Pro 版本

條碼 — 深入參考

概覽

NextPDF Pro 條碼介面在 Core 條碼模組之上加入特殊 2D 與供應鏈符號系統。它隨附六個註冊表解析的 2D 編碼器（Micro QR、DotCode、Han Xin Code、JabCode、rMQR、GS1 DataBar）、一個 GS1 Composite 2D 元件編碼器（CC-C）、USPS Intelligent Mail 1D 編碼器，以及一個 GS1 Application Identifier 剖析器加上供應鏈驗證器。編碼具確定性：相同的承載與選項一律產生完全相同的模組矩陣。本頁陳述公開 API、行為合約、失敗模式，以及各符號系統的一致性證據。

供應與授權

此能力隨 NextPDF Pro（nextpdf/pro）出貨，並以 Pro 級授權信封啟用。未持有該授權的部署不會載入此能力的類別。比較版本並取得授權。

composer require nextpdf/pro:^3

每個符號系統在授權信封中綁定自己的能力名稱：barcode.microqr、barcode.dotcode、barcode.hanxin、barcode.jabcode、barcode.rmqr、barcode.gs1databar 與 barcode.gs1-composite-cc-c。當某項能力未授權時，註冊表不會解析該編碼器。GS1 Composite CC-A 與 CC-B 的完整符號編碼不受支援（請參閱支援狀態表），因此不會註冊任何 barcode.gs1-composite-cc-a 或 barcode.gs1-composite-cc-b 鍵。

公開 API 介面

註冊表鍵來自 Core 的 NextPDF\Barcode\Barcode2DType case 值，外加字面鍵 gs1-composite-cc-c。對於註冊表解析的編碼器而言，穩定合約是註冊表鍵，而非編碼器的 FQCN。

符號	參數	預設行為	回傳	拋出或失敗於	註記
`BarcodeProServiceProvider::register()`	`BarcodeEncoderRegistry $registry`	綁定全部七個 Pro 註冊表鍵	`void`	—	靜態；具冪等性——第二次呼叫會取代第一次的綁定
`MicroQrEncoder::encode()`	`$data`；選項 `ecLevel`（`'L'`、`'M'`、`'Q'`；預設 `'L'`）、`version`（1–4 或 null）、`mask`（0–3 或 null）	自動選擇最小可容納的版本 M1–M4	`Barcode2DData`	`InvalidArgumentException`	不支援的 `'H'` 會靜默地強制轉為 `'L'`（需要 fail-closed EC 選擇的呼叫端必須預先驗證）；M1 忽略 `ecLevel`
`DotCodeEncoder::encode()`	`$data`；選項 `gs1`（bool，預設 false）、`columns`（int）、`rows`（int）、`ratio`（float，預設 1.5）	以 1.5 的寬高比自動調整格點尺寸	`Barcode2DData`	`InvalidArgumentException`	可依各軸強制指定格點維度
`HanXinEncoder::encode()`	`$data`；選項 `ecLevel`（0–3，預設 1）、`version`（1–84，預設自動）	最小可容納的版本	`Barcode2DData`	`InvalidArgumentException`	依 ISO/IEC 20830 的 GB 2312 Region 1/2 文字模式
`JabCodeEncoder::encode()`	`$data`；選項 `colors`（4、8、16、32、64、128、256；預設 8）、`eccLevel`（0–10，預設 3）、`symbolNumber`（1–61，預設 1）、`symbolVersions`、`symbolPositions`、`symbolEccLevels`	單一 8 色符號	`BarcodeColorData`	`InvalidArgumentException`、`JabCodeEncodingException`	帶調色盤的多色模組矩陣
`RmqrEncoder::encode()`	`$data`；選項 `ecLevel`（預設 `RmqrConstants::EC_M`，或 `EC_H`）、`version`（例如 `'R7x43'`，預設自動）	32 個 ISO/IEC 23941 版本中最小可容納者	`Barcode2DData`	`InvalidArgumentException`	拒絕超出容量的承載；絕不截斷
`Gs1DataBarEncoder::encode()`	`$data`；選項 `variant`（`Gs1DataBarVariant`，預設 `OMNIDIRECTIONAL`）、`linkage`（bool，預設 false）、`height`（int，預設為變體最小值；Expanded Stacked 為每列）、`segmentsPerRow`（int，預設 4；僅限 Expanded Stacked）	編碼 GTIN 輸入（§5/§6 家族）或 GS1 AI 元素字串（§7 家族）	`Barcode2DData`	`InvalidArgumentException`；`InvalidSymbolStructureException`	全部七個 ISO/IEC 24724 Annex J 變體皆可編碼
`Gs1DataBarVariant`	—	`isImplemented()` 對全部七個 case 回傳 true	enum（7 個 case）	—	依 Annex J 的 `minimumHeightX()` 與 `defaultHeightX()`
`ImbEncoder::encode()`	`string $code`（20、25、29 或 31 位數字）	65 條四狀態條	`BarcodeData`	`InvalidArgumentException`	1D 編碼器介面；非 2D 註冊表鍵
`ImbEncoder::encodeToString()`	`string $code`	將條狀態表示為 T/A/D/F 字串	`string`	`InvalidArgumentException`	用於對照 USPS 參考向量進行檢查
`Gs1DataParser::parse()`	`string $data`	自動偵測 Digital Link URI，否則為 `(AI)value` 格式	`Gs1ParsedData`	`InvalidArgumentException`	實作 Core 的 `Gs1DataParserInterface` 合約
`Gs1DataParser::parseDigitalLink()`	`string $uri`	剖析一個 GS1 Digital Link URI	`Gs1ParsedData`	`InvalidArgumentException`	—
`Gs1DataParser::encodeForCode128()` / `::encodeForQrCode()` / `::encodeForDataMatrix()`	`object $parsed`	帶有該載體 FNC1 慣例的載體位元組序列	`string`	—	預期一個 `Gs1ParsedData` 實例
`Gs1DataParser::validateAI()`	`string $ai`、`string $value`	對單一 AI 值進行結構檢查	`bool`	—	—
`Gs1Validator::validate()`	`string $barcodeData`、`Gs1SupplyChainProfile $profile`（預設 `NONE`）	`run()` 之上的靜態捷徑	`Gs1ValidationResult`	—	剖析失敗會成為發現項，而非例外
`Gs1Validator::run()`	同 `validate()`	剖析、檢查碼、日期、跨 AI 規則、設定檔	`Gs1ValidationResult`	—	實例路徑；建構子接受注入的剖析器
`Gs1SupplyChainProfile`	—	`NONE` 略過設定檔規則	enum（5 個 case）	—	`RETAIL`、`FOOD`、`PHARMA`、`LOGISTICS`、`NONE`；`requiredAIs()`、`recommendedAIs()`、`primaryIdentifiers()`
`Gs1ValidationResult`	—	建構時依嚴重度分割發現項	readonly class	—	`isValid`、`findings`、`errors`、`warnings`、`infos`、`parsedData`；`passes()`、`fails()`、`totalFindings()`
`Gs1ValidationFinding` / `Gs1FindingSeverity`	—	`severity`、`ruleId`、`message`，以及選用的 `ai` 與 `suggestion`	readonly class / enum	—	嚴重度：`Error`、`Warning`、`Info`
`CompositeComponentA::codewordsFor()`	`string $data`	§5 通用二進位字串 encodation、base-928 轉換、往返自我檢查	`list<int>`（各為 0–927）	`InvalidArgumentException`	供 `linkFor()` 或外部 CC-A 載體彩現器使用
`CompositeComponentA::encode()`	忽略	拒絕 CC-A 完整符號彩現	—	`UnsupportedBarcodeFeature`（一律）	Fail-closed；請參閱邊界案例
`CompositeComponentB::encode()`	忽略	拒絕 CC-B 2D 編碼	—	`UnsupportedBarcodeFeature`（一律）	`linkFor()` 仍可使用（CCSI 901）
`CompositeComponentC::encode()`	`$data`；選項轉遞給 PDF417 載體；`carrierType`（預設 `GS1_128`）	以 CCSI 碼字 920 領頭的完整 PDF417 載體	`Barcode2DData`	`BarcodeException`；`CompositeLinkageException`	僅接受 `GS1_128` 載體
`CompositeComponent{A,B,C}::linkFor()`	`string $carrierId`、`array $codewords`、`CompositeCarrierType $carrierType`	將元件碼字與 1D 載體配對	`CompositeLinkage`	`CompositeLinkageException`	強制執行載體可用性與容量
`CompositeVariant` / `CompositeCarrierType`	—	`CC_A`、`CC_B`、`CC_C`；`GS1_DATABAR`、`GS1_128`	enums	—	`maxCodewords()`、`ccsi()`、`allowedCarriers()`、`usesFullPdf417()`

進入點簽章

public static function register(BarcodeEncoderRegistry $registry): void

public function encode(string $data, array $options = []): Barcode2DData

public static function validate(
    string $barcodeData,
    Gs1SupplyChainProfile $profile = Gs1SupplyChainProfile::NONE,
): Gs1ValidationResult

public function run(
    string $barcodeData,
    Gs1SupplyChainProfile $profile = Gs1SupplyChainProfile::NONE,
): Gs1ValidationResult

public function parse(string $data): Gs1ParsedData
public function parseDigitalLink(string $uri): Gs1ParsedData
public function encodeForCode128(object $parsed): string
public function encodeForQrCode(object $parsed): string
public function encodeForDataMatrix(object $parsed): string
public function validateAI(string $ai, string $value): bool

public function codewordsFor(string $data): array

行為合約

註冊表解析

Core 預設註冊表工廠會將 Pro 編碼器預先綁定為惰性、受能力授權的項目。對於組合一個無預設值之註冊表的應用程式（例如具有自有容器的框架整合），BarcodeProServiceProvider::register() 是受支援的回退。每個編碼器會將一個字串承載與各符號系統的選項轉換為一個條碼資料物件，再由頁面彩現器轉成 PDF 內容運算子。

GS1 剖析與驗證

Gs1DataParser 接受人類可讀的 AI 字串（(01)09521234543213(17)260131）與 GS1 Digital Link URI。它為 GS1-128、QR Code 與 Data Matrix 載體產生編碼後的位元組序列，並套用各載體的 FNC1 與群組分隔符慣例。Gs1Validator 執行一條五步管線：剖析、檢查碼（GTIN、SSCC）、日期邏輯、跨 AI 規則，以及產業設定檔的必填 AI。剖析失敗會產生一個帶有發現項的無效結果；它不會拋出例外。發現項依嚴重度分割為 errors、warnings 與 infos。

GS1 DataBar 變體分派

Gs1DataBarEncoder::encode() 透過單一選項合約分派全部七個 ISO/IEC 24724:2011 Annex J 變體。Omnidirectional、Truncated、Stacked 與 Stacked Omnidirectional 共用 §5 的元素寬度代數，搭配 mod-79 檢查字元。Limited 使用自有的 §6 符號字元代數，搭配 mod-89 檢查字元。Expanded 與 Expanded Stacked 使用 §7 (17,4) 代數：§7.2.5.5 的三模式數字、英數與 ISO/IEC 646 壓縮狀態機，外加 mod-211 檢查字元（§7.2.6）。§5/§6 家族接受帶 mod-10 檢查碼的 14 位 GTIN-14 或 13 位項目識別碼。§7 家族接受原始的 GS1 AI 元素字串（數字、字母、ISO/IEC 646 標點子集，以及作為位元組 0x1D 的 FNC1）。linkage 選項會設定 2D 元件連結旗標，以供作為 GS1 Composite 符號的線性元件。

GS1 Composite 元件

CC-C 在完整 PDF417 載體上產生一個完整的 2D 擴充元件，並注入強制的 CCSI 碼字 920 作為領頭資料碼字（ISO/IEC 24723:2010 §5.4）。CC-A 透過 codewordsFor() 產生符規的 base-928 資料碼字，並帶有 fail-closed 的編碼—解碼往返自我檢查，但拒絕完整符號彩現。CC-B 完全拒絕 2D 編碼。linkFor() 會將元件碼字與 1D 載體配對為一個 CompositeLinkage 值，並強制執行載體可用性與容量。

邊界案例與失敗模式

每個編碼器都會以 InvalidArgumentException 拒絕空承載。
Micro QR：請求不支援的 H 錯誤更正等級會靜默地強制轉為 L 而非失敗（若需要 fail-closed EC 選擇，請預先驗證選項），因為 ISO/IEC 18004 對 Micro QR 符號僅定義 L、M 與 Q。
rMQR：錯誤更正等級必須是 M 或 H；超出 32 個版本容量的承載會被拒絕，絕不截斷。
JabCode：超出支援的 2 的次方集合的顏色數、超出 0–10 的 ECC 等級，或超出 1–61 的符號數皆會被拒絕；下游的編碼失敗會引發 JabCodeEncodingException。
GS1 DataBar：§5/§6 家族會驗證 GTIN 的 mod-10 檢查碼，而 Limited 將指示位限制為 0 或 1。§7 家族會拒絕無法編碼的字元以及尾隨或重複的 FNC1 分隔符。Expanded Stacked 會拒絕每列奇數的符號字元數，以及低於 34X 最小值的每列高度。內部結構自我檢查會以 InvalidSymbolStructureException 失敗，而非發出格式錯誤的符號。
GS1 Composite：CC-A 與 CC-B 的 encode() 一律拋出 UnsupportedBarcodeFeature（fail closed）。CC-C 在資料為空或 PDF417 容量溢位（超過 925 個碼字）時拋出 BarcodeException，並在載體不可接受時拋出 CompositeLinkageException。
GS1 驗證會在編碼前標記格式錯誤的 AI 結構與不正確的檢查碼；一個無效的供應鏈字串絕不會產生可掃描的符規符號。
IMB 僅接受 20、25、29 或 31 位數字的輸入。
條碼編碼不執行任何密碼學。沒有 FIPS 模式專屬行為；編碼器無論 FIPS 設定檔為何都以相同方式執行。

一致性

NextPDF 依下列引用的已發布標準實作這些符號系統，並在其測試套件中釘選參考軌跡。本頁的陳述為能力宣稱：支援不等於一致性，一致性也不等於認證。NextPDF 未持有任何符號系統認證。條款錨點係自產品原始碼及其一致性 fixture 改寫而來；合規引擎語料庫並未涵蓋條碼符號系統標準，因此下列錨點以產品為依據，且不附參考識別碼。

介面	標準	條款錨點（改寫）
GS1 DataBar 元素寬度代數	ISO/IEC 24724:2011	§5.2 symbol-character structure; Annex F.1 worked example (Omnidirectional); Annex F.2 (Limited); Annex F.3 (Expanded)
GS1 DataBar 堆疊版面	ISO/IEC 24724:2011	§5.4 Stacked; §5.5 Stacked Omnidirectional; §7.2.8 Expanded Stacked row partition and separators
GS1 DataBar Expanded 編碼	ISO/IEC 24724:2011	§7.2.5.5 three-mode compaction state machine; §7.2.6 mod-211 check character
GS1 Composite 連結與 CC-C	ISO/IEC 24723:2010	§5.4 CCSI codeword semantics; §5.1 carrier admissibility
GS1 Composite CC-A 碼字	ISO/IEC 24723:2010	§5 general-purpose binary-string encodation with base-928 conversion
rMQR 符號結構	ISO/IEC 23941:2022	§6.3.2 Table 1 version dimensions; §7.8.2 fixed mask; Annex C / Annex I format-information reference
Micro QR	ISO/IEC 18004	Micro QR M1–M4 capacity and format information
Han Xin Code	ISO/IEC 20830:2021	Symbol structure; finder and alignment patterns; GB 2312 Region 1/2 modes; Reed–Solomon ECC; masking
JabCode	ISO/IEC 23634	Symbol, colour, and ECC structure
郵政符號系統	USPS-B-3200	Intelligent Mail Barcode field structure

各符號系統支援狀態

當 pro/tests/** 下有一個 fixture 確實演練某個變體時，該變體即為 Verified——最好是一個釘選到已發布實作範例的參考軌跡。一個有隨附但無專屬 fixture 的變體維持在 Claimed。一個沒有編碼器的變體為 Not supported。

符號系統/變體	狀態	證據（測試路徑）	註記
Micro QR (M1–M4)	Verified	`pro/tests/Unit/Barcode/MicroQrEncoderTest.php`	單元層級；實作範例參考軌跡 fixture 為已追蹤的補齊項目
DotCode	Verified	`pro/tests/Unit/Barcode/DotCodeEncoderTest.php`; `DotCodeGfArithmeticTest.php`	涵蓋 Galois-field 算術；無廠商解碼器往返
Han Xin Code	Verified	`pro/tests/Unit/Barcode/HanXinEncoderTest.php`; `HanXinRsEncodingTest.php`	明確演練 Reed–Solomon 編碼路徑
JabCode（1–61 符號、4–256 色、ECC 0–10）	Verified	`pro/tests/Unit/Barcode/JabCode/JabCodeEncoderTest.php`（同目錄下另有 11 個元件套件）	演練多符號串接與 ECC 範圍；無廠商解碼器往返
USPS Intelligent Mail Barcode	Verified	`pro/tests/Unit/Barcode/ImbEncoderTest.php`; `ImbRoutingCodeTest.php`	演練路由碼與 20/25/29/31 位長度驗證
rMQR — 全部 32 個 ISO/IEC 23941 版本	Verified	`pro/tests/Conformance/Barcode/Rmqr/AnnexValidatedSizesTest.php`; `RmqrAnnexCFormatInfoTest.php`; `pro/tests/Unit/Barcode/Rmqr/RmqrEncoderTest.php`	版本與 EC 配對對照 ISO/IEC 23941 Table 1 檢查；Annex C / Annex I 格式資訊參考值
GS1 DataBar — Omnidirectional / Truncated	Verified	`pro/tests/Conformance/Barcode/Gs1DataBar/Gs1DataBarReferenceTest.php`	與 Annex F.1 實作範例位元組相等；Truncated 以縮減高度共用相同編碼
GS1 DataBar — Stacked / Stacked Omnidirectional	Verified	`pro/tests/Conformance/Barcode/Gs1DataBar/Gs1DataBarStackedReferenceTest.php`	列分割自 Annex F.1 軌跡衍生；分隔符建構依 §5.4 與 §5.5
GS1 DataBar — Limited	Verified	`pro/tests/Conformance/Barcode/Gs1DataBar/Gs1DataBarLimitedReferenceTest.php`; `pro/tests/Unit/Barcode/Gs1DataBar/Gs1DataBarLimitedEncoderTest.php`	與 Annex F.2 實作範例位元組相等（項目 00098765432105）
GS1 DataBar — Expanded	Verified	`pro/tests/Conformance/Barcode/Gs1DataBar/Gs1DataBarExpandedReferenceTest.php`; `pro/tests/Integration/Barcode/Gs1DataBarExpandedTwoDecoderTest.php`	與 Annex F.3 實作範例位元組相等（`(10)12A`）；對照 zxing-cpp 與 ZBar 的獨立解碼器往返
GS1 DataBar — Expanded Stacked	Verified	`pro/tests/Unit/Barcode/Gs1DataBar/Gs1DataBarExpandedEncoderTest.php`（堆疊案例）；上述整合往返	與單列 Expanded 相同的資料管線；斷言 §7.2.8 列分割與分隔符
GS1 Composite — CC-C（PDF417 載體）	Verified	`pro/tests/Conformance/Barcode/Gs1Composite/CompositeComponentCTest.php`; `CompositeRoundtripTest.php`; `CompositeLinkageTest.php`	涵蓋 CCSI 碼字 920 與連結旗標互動
GS1 Composite — CC-A	Partial	`pro/tests/Unit/Barcode/Gs1Composite/CompositeComponentACodewordTest.php`; `pro/tests/Conformance/Barcode/Gs1Composite/CompositeComponentATest.php`	碼字產生為 Verified（base-928、往返自我檢查）；完整符號彩現不受支援——`encode()` fail closed
GS1 Composite — CC-B	Not supported	`pro/tests/Conformance/Barcode/Gs1Composite/CompositeComponentBTest.php`（斷言 fail-closed 拒絕）	無 2D 編碼；連結輔助（CCSI 901）仍可使用
GS1 AI 剖析器	Verified	`pro/tests/Unit/Barcode/Gs1DataParserTest.php`; `Gs1DataParserFnc1Test.php`	演練兩種輸入格式與全部三種載體位元組序列輸出
GS1 供應鏈驗證器	Verified	`pro/tests/Unit/Barcode/Gs1ValidatorTest.php`; `Gs1ValidatorCrossAiTest.php`; `pro/tests/Unit/Barcode/Gs1/Gs1ValidatorDateValidationEdgeCaseTest.php`	演練檢查碼、跨 AI 必填組合與日期邏輯

開發註記

本頁的證據錨點是 pro/tests/** 下的測試路徑；此模組的儲存庫並未隨附 examples/ 目錄。
供應與授權下列出的七個能力名稱，就是服務供應者所綁定的鍵。IMB 編碼器是直接建構的，不帶任何註冊表鍵。
CC-A 僅輸出通用 encodation 方法；應用專屬的壓縮方法是一項已記錄的密度殘留，而非正確性缺口。

發布邊界

本頁僅記錄外部可觀察的行為與受支援的公開 API 介面。內部命名空間路徑、輔助類別、機制表、runbook 檔名與工單前綴均不在範圍內。