圖形 (HasDrawing)

HasDrawing trait 提供向量繪圖基元，涵蓋直線、矩形、圓形、多邊形、曲線、箭頭及扇形。所有方法都回傳 static，因此每個呼叫都可以鏈式串接。

速查表

方法	圖形
line()	兩點之間的直線
rect()	矩形
roundedRect()	圓角矩形
circle()	圓形
ellipse()	橢圓
polygon()	任意多邊形（頂點陣列）
regularPolygon()	正多邊形（n 邊）
starPolygon()	星形
arrow()	帶箭頭的線段
pieSector()	扇形（用於圖表）
curve()	三次貝茲曲線
polyCurve()	多段貝茲曲線

基本範例

use Yeeefang\TcpdfNext\Core\Document;

$pdf = Document::create()
    ->addPage()
    ->setDrawColor(255, 0, 0)
    ->setFillColor(200, 220, 255)
    ->line(10, 10, 100, 10)
    ->rect(10, 20, 80, 40, 'DF')
    ->roundedRect(10, 70, 80, 40, 5, 'DF')
    ->circle(150, 40, 30, 'DF')
    ->ellipse(150, 100, 40, 20, 'DF')
    ->arrow(10, 140, 100, 140)
    ->regularPolygon(150, 160, 25, 6, 'DF')
    ->starPolygon(50, 200, 25, 5, 3, 'DF');

樣式參數

大多數繪圖方法都接受一個 $style 字串，用於控制渲染方式：

值	意義
S	僅描邊（輪廓） — 預設值
F	僅填充
DF 或 B	描邊加填充（兩者皆有）

直線與矩形

$pdf->line(float $x1, float $y1, float $x2, float $y2);
$pdf->rect(float $x, float $y, float $w, float $h, string $style = '');
$pdf->roundedRect(float $x, float $y, float $w, float $h, float $r, string $style = '');

line() 從 (x1, y1) 畫到 (x2, y2)。rect() 繪製標準矩形。roundedRect() 增加半徑為 $r 的圓角。

圓形與橢圓

$pdf->circle(float $x0, float $y0, float $r, string $style = '');
$pdf->ellipse(float $x0, float $y0, float $rx, float $ry, string $style = '');

circle() 接受圓心與半徑。ellipse() 則使用水平與垂直兩個獨立的半徑。

多邊形

$pdf->polygon(array $points, string $style = '');
$pdf->regularPolygon(float $x0, float $y0, float $r, int $ns, string $style = '');
$pdf->starPolygon(float $x0, float $y0, float $r, int $nv, int $ng, string $style = '');

polygon() 接受一個扁平的座標陣列 [x1, y1, x2, y2, ...]。regularPolygon() 繪製內接於半徑 $r 圓形的 n 邊正多邊形。starPolygon() 繪製具有 $nv 個頂點及間距因子 $ng 的星形。

// 三角形
$pdf->polygon(
    points: [50, 10, 10, 60, 90, 60],
    style: 'DF'
);

// 正六邊形
$pdf->regularPolygon(
    x0: 60, y0: 80, r: 25,
    ns: 6, style: 'DF'
);

// 五角星
$pdf->starPolygon(
    x0: 150, y0: 80, r: 25,
    nv: 5, ng: 3, style: 'DF'
);

箭頭與扇形

$pdf->arrow(float $x0, float $y0, float $x1, float $y1);
$pdf->pieSector(float $xc, float $yc, float $r, float $a, float $b, string $style = '');

arrow() 繪製一條在終點帶有箭頭的線段。pieSector() 從角度 $a 到 $b（度數）繪製扇形，非常適合用於圓餅圖：

$pdf->setFillColor(255, 100, 100)->pieSector(100, 100, 40, 0, 120, 'F')
    ->setFillColor(100, 255, 100)->pieSector(100, 100, 40, 120, 250, 'F')
    ->setFillColor(100, 100, 255)->pieSector(100, 100, 40, 250, 360, 'F');

貝茲曲線

$pdf->curve(float $x0, float $y0, float $x1, float $y1, float $x2, float $y2, float $x3, float $y3);
$pdf->polyCurve(array $points);

curve() 從 (x0, y0) 到 (x3, y3) 繪製三次貝茲曲線，(x1, y1) 和 (x2, y2) 為控制點。polyCurve() 從座標陣列串接多段貝茲曲線。

// 三次貝茲曲線
$pdf->curve(
    20, 200,   // 起點
    80, 150,   // 控制點 1
    120, 250,  // 控制點 2
    180, 200   // 終點
);

線條樣式

$pdf->setLineStyle(array $style);

$style 陣列支援以下鍵值：width（浮點數）、cap（butt、round、square）、join（miter、round、bevel）、dash（字串或陣列模式）以及 color（RGB 陣列）。

$pdf->setLineStyle([
    'width' => 0.5,
    'cap'   => 'round',
    'join'  => 'round',
    'dash'  => '3,2',
    'color' => [0, 0, 200],
])->line(10, 10, 190, 10);

線帽樣式

值	說明
butt	平切 — 線條在端點處截斷（預設）
round	圓形 — 在端點加上半圓形突出
square	方形 — 在端點加上半方形突出

線接樣式

值	說明
miter	尖角 — 線段延伸至交匯點（預設）
round	圓角 — 在接合處加上圓弧
bevel	斜角 — 在接合處截平

裁切標記與對位標記

在專業印刷輸出中加入對位標記與裁切標記：

$pdf->cropMark(20, 20, 10, 10)
    ->registrationMark(105, 10)
    ->colorRegistrationBar(20, 280, 170, 5);

• cropMark() — 裁切標記，標示紙張的裁切位置。
• registrationMark() — 對位標記（十字標記），用於多色套印對位。
• colorRegistrationBar() — 色彩條，用於檢查印刷色彩的準確性。