條碼

Barcode 模組（BarcodeGenerator、BarcodeRenderer）能直接在 PDF 中以向量方式繪製一維與二維條碼，不需要外部圖片。條碼類型由 BarcodeType 與 Barcode2DType 列舉定義。所有方法皆回傳 static，支援方法鏈。

基本範例

use Yeeefang\TcpdfNext\Core\Document;

$pdf = Document::create()
    ->addPage()
    ->setFont('Helvetica', '', 12)
    ->cell(0, 10, 'Product Barcodes', newLine: true)

    // 1D：EAN-13
    ->write1DBarcode('4006381333931', 'EAN13', 10, 30, 80, 30, 0.4, [
        'border' => false,
        'text'   => true,
        'fgcolor' => [0, 0, 0],
    ])

    // 1D：Code 128
    ->write1DBarcode('TCPDF-NEXT', 'C128', 10, 70, 80, 20, 0.4)

    // 2D：QR Code
    ->write2DBarcode('https://tcpdf-next.dev', 'QRCODE,H', 10, 100, 50, 50, [
        'fgcolor' => [0, 0, 0],
        'bgcolor' => [255, 255, 255],
    ])

    // 2D：DataMatrix
    ->write2DBarcode('Hello DataMatrix', 'DATAMATRIX', 70, 100, 40, 40);

1D 條碼

write1DBarcode()

$pdf->write1DBarcode(
    string $code,           // 要編碼的資料
    string $type,           // 條碼類型字串
    float  $x,              // X 座標
    float  $y,              // Y 座標
    float  $w,              // 寬度
    float  $h,              // 高度
    float  $xres = 0.4,    // 最細條的寬度（使用者單位）
    array  $style = [],     // 樣式選項
);

支援的 1D 條碼類型（BarcodeType）

類型字串	列舉值	說明
C39	CODE_39	Code 39
C93	CODE_93	Code 93
C128	CODE_128	Code 128（自動模式）
C128A	CODE_128A	Code 128 子集 A
C128B	CODE_128B	Code 128 子集 B
C128C	CODE_128C	Code 128 子集 C
EAN8	EAN_8	EAN-8
EAN13	EAN_13	EAN-13
UPCA	UPC_A	UPC-A
UPCE	UPC_E	UPC-E
I25	I25	Interleaved 2 of 5（交錯式二五碼）
S25	S25	Standard 2 of 5（標準二五碼）
CODABAR	CODABAR	Codabar
CODE11	CODE_11	Code 11
MSI	MSI	MSI Plessey
POSTNET	POSTNET	POSTNET（美國郵政）
PLANET	PLANET	PLANET（美國郵政）
IMB	IMB	Intelligent Mail Barcode
PHARMA	PHARMACODE	Pharmacode（製藥業）

常用 1D 條碼範例

// EAN-13：零售商品條碼
$pdf->write1DBarcode('4710088432001', 'EAN13', 10, 30, 60, 25, 0.4, [
    'text' => true,
    'fgcolor' => [0, 0, 0],
]);

// Code 128：物流與庫存管理
$pdf->write1DBarcode('SHIP-2026-00042', 'C128', 10, 65, 80, 20, 0.4, [
    'text' => true,
]);

// UPC-A：北美零售商品碼
$pdf->write1DBarcode('012345678905', 'UPCA', 10, 95, 60, 25, 0.4, [
    'text' => true,
]);

2D 條碼

write2DBarcode()

$pdf->write2DBarcode(
    string $code,           // 要編碼的資料
    string $type,           // 條碼類型字串
    float  $x,              // X 座標
    float  $y,              // Y 座標
    float  $w,              // 寬度
    float  $h,              // 高度
    array  $style = [],     // 樣式選項
);

支援的 2D 條碼類型（Barcode2DType）

類型字串	列舉值	說明
QRCODE,L	QR_CODE	QR Code — 低容錯（約 7%）
QRCODE,M	QR_CODE	QR Code — 中容錯（約 15%）
QRCODE,Q	QR_CODE	QR Code — 中高容錯（約 25%）
QRCODE,H	QR_CODE	QR Code — 高容錯（約 30%）
DATAMATRIX	DATAMATRIX	DataMatrix
PDF417	PDF417	PDF417

QR Code 容錯等級選擇

等級	容錯率	適用場景
L	約 7%	資料量最小，適合受控環境
M	約 15%	一般用途，平衡資料量與容錯
Q	約 25%	可能會有部分遮擋的場景
H	約 30%	需要疊加 Logo 或惡劣掃描條件

常用 2D 條碼範例

// QR Code：網址連結
$pdf->write2DBarcode('https://tcpdf-next.dev', 'QRCODE,H', 10, 30, 50, 50, [
    'fgcolor' => [0, 0, 0],
    'bgcolor' => [255, 255, 255],
]);

// DataMatrix：工業產品序號
$pdf->write2DBarcode('01034531200000111719112510ABCD1234', 'DATAMATRIX', 70, 30, 40, 40);

// PDF417：身分證件或運輸標籤
$pdf->write2DBarcode('PASSPORT|WANG|DA-MING|M|1990-01-15|A123456789', 'PDF417', 10, 90, 80, 30);

樣式選項

$style 陣列控制 1D 與 2D 條碼的外觀：

鍵	類型	說明
border	bool	是否在條碼周圍繪製邊框
padding	float|array	邊框內的間距
fgcolor	array	前景色（條碼線條）[r, g, b]
bgcolor	array	背景色 [r, g, b]
text	bool	是否在 1D 條碼下方顯示可讀文字
stretch	bool	是否延伸條碼以填滿指定寬度

自訂樣式範例

// 深藍色前景搭配淺色背景
$pdf->write1DBarcode('CUSTOM-001', 'C128', 10, 30, 80, 25, 0.4, [
    'border'  => true,
    'padding' => 4,
    'text'    => true,
    'fgcolor' => [0, 51, 102],
    'bgcolor' => [240, 248, 255],
]);

完整範例：產品標籤

use Yeeefang\TcpdfNext\Core\Document;

$pdf = Document::create()
    ->addPage()
    ->setFont('Helvetica', 'B', 14)
    ->cell(0, 10, 'Widget Pro X1', newLine: true)
    ->setFont('Helvetica', '', 10)
    ->cell(0, 8, 'SKU: WPX1-2026', newLine: true)

    // EAN-13 商品條碼
    ->write1DBarcode('4006381333931', 'EAN13', 10, 35, 60, 25, 0.4, [
        'text'    => true,
        'fgcolor' => [0, 0, 0],
    ])

    // QR Code 連結到產品頁面
    ->write2DBarcode('https://example.com/product/123', 'QRCODE,H', 80, 30, 30, 30, [
        'fgcolor' => [33, 37, 41],
        'bgcolor' => [255, 255, 255],
    ]);

提示

• 當 QR Code 上方需要疊加 Logo 時，請使用容錯等級 H（高），以確保即使部分被遮擋仍然能掃描。
• 1D 條碼的 $xres 參數控制最細條的寬度，數值越小條碼越緊密，但過小可能導致掃描困難。
• 所有條碼皆以向量方式繪製，放大後不會失真，非常適合用於高品質列印。
• DataMatrix 特別適合在小空間內編碼大量資料，例如電子零件標籤。