Barcode API¶

namespace NextPDF\Core\Barcode;

final class BarcodeRenderer

/**
 * 在頁面上渲染條碼。
 *
 * @param BarcodeEncoderInterface $encoder   條碼編碼器
 * @param Position                $position  左上角位置（mm）
 * @param Dimension               $dimension 條碼尺寸（mm）
 * @param BarcodeOptions          $options   樣式選項（可選）
 */
public function render(
    BarcodeEncoderInterface $encoder,
    Position                $position,
    Dimension               $dimension,
    BarcodeOptions          $options = new BarcodeOptions(),
): RenderedBarcode

final class BarcodeOptions
{
    public static function create(): self

    public function withForeground(string $hexColor): self      // 預設 #000000
    public function withBackground(string $hexColor): self      // 預設 #FFFFFF
    public function withHumanReadable(bool $show): self         // 顯示人眼可讀文字
    public function withFontName(string $name): self
    public function withFontSize(float $pt): self               // 預設 8.0
    public function withTextAlignment(string $align): self      // 'center'|'left'|'right'
    public function withQuietZone(
        float $top, float $right, float $bottom, float $left
    ): self
    public function withColor(string $hexColor): self           // 快捷方法（設定前景色）
}

namespace NextPDF\Core\Barcode\Encoders;

final class QrCodeEncoder implements BarcodeEncoderInterface

/**
 * @param non-empty-string           $data       QR Code 資料（URL、文字等）
 * @param 'L'|'M'|'Q'|'H'           $errorLevel 錯誤更正等級（L=7%, M=15%, Q=25%, H=30%）
 * @param positive-int               $quietZone  靜區模組數（預設 4）
 * @param positive-int|null          $version    QR Code 版本（1-40，null = 自動）
 */
public static function create(
    string  $data,
    string  $errorLevel = 'M',
    int     $quietZone  = 4,
    ?int    $version    = null,
): self

public static function create(
    string $data,
    int    $quietZone = 2,
): self

public static function create(
    string $data,
    int    $rows            = 0,       // 0 = 自動計算
    int    $columns         = 0,       // 0 = 自動計算
    int    $errorCorrection = 2,       // 0-8（越大越安全）
): self

public static function create(
    string $data,
    int    $errorPercent = 23,  // 12–100
): self

public static function create(
    string $data,
    int    $mode = 4,  // 2-6，4 = Secondary Message
): self

public static function create(
    string $data,
    string $errorLevel = 'M',
): self

/**
 * @param 'A'|'B'|'C'|'auto' $codeSet 字符集（auto = 自動選擇最短編碼）
 */
public static function create(string $data, string $codeSet = 'auto'): self

/** @param bool $extendedMode 是否啟用 Code 39 Extended（支援完整 ASCII）*/
public static function create(string $data, bool $extendedMode = false): self

/**
 * @param non-empty-string $data 12 位數字（不含校驗碼），校驗碼自動計算
 * @throws InvalidBarcodeDataException 若非 12 位數字
 */
public static function create(string $data): self

/** @param non-empty-string $data 7 位數字 */
public static function create(string $data): self

/** @param non-empty-string $data 11 位數字 */
public static function create(string $data): self

/** @param non-empty-string $data 6 位數字（壓縮碼）*/
public static function create(string $data): self

/** @param non-empty-string $data 13 位數字 */
public static function create(string $data): self

/**
 * @param 'A'|'B'|'C'|'D' $startChar 起始字元
 * @param 'A'|'B'|'C'|'D' $stopChar  終止字元
 */
public static function create(
    string $data,
    string $startChar = 'A',
    string $stopChar  = 'B',
): self

public static function create(string $data): self

namespace NextPDF\Core\Contracts;

interface BarcodeEncoderInterface
{
    /** 回傳驗證後的資料（若資料無效則拋出例外）*/
    public function validate(): void;

    /** 回傳條碼符號的矩陣表示（用於向量渲染）*/
    public function encode(): BarcodeMatrix;

    /** 回傳條碼類型名稱 */
    public function type(): string;

    /** 最小顯示尺寸建議（mm），低於此尺寸掃描儀可能無法識別 */
    public function minimumSize(): Dimension;
}