Barcode — 深度参考

概览

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'（需要失败即关闭 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	枚举（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 规则、profile	Gs1ValidationResult	—	实例路径；构造函数接受一个注入的解析器
Gs1SupplyChainProfile	—	NONE 跳过 profile 规则	枚举（5 个 case）	—	RETAIL、FOOD、PHARMA、LOGISTICS、NONE；requiredAIs()、recommendedAIs()、primaryIdentifiers()
Gs1ValidationResult	—	构造时按严重度对发现项分区	readonly 类	—	isValid、findings、errors、warnings、infos、parsedData；passes()、fails()、totalFindings()
Gs1ValidationFinding / Gs1FindingSeverity	—	severity、ruleId、message，可选的 ai 与 suggestion	readonly 类 / 枚举	—	严重度：Error、Warning、Info
CompositeComponentA::codewordsFor()	string $data	§5 通用二进制串编码法、base-928 转换、往返自检	list<int>（每个 0–927）	InvalidArgumentException	馈入 linkFor() 或一个外部 CC-A 载体渲染器
CompositeComponentA::encode()	忽略	拒绝 CC-A 全符号渲染	—	UnsupportedBarcodeFeature（始终）	失败即关闭；见边界情形
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	枚举	—	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 规则，以及行业 profile 强制要求的 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 数据码字，并带一个失败即关闭的编解码往返自检，但拒绝全符号渲染。CC-B 完全拒绝 2D 编码。linkFor() 将组件码字与一个 1D 载体配对为一个 CompositeLinkage 值，强制载体可接受性与容量。

边界情形与失败模式

• 每个编码器都以 InvalidArgumentException 拒绝一个空载荷。
• Micro QR：请求不支持的 H 纠错级别会静默强制转为 L 而非失败（如果你需要失败即关闭的 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（失败即关闭）。CC-C 在空数据或 PDF417 容量溢出（超过 925 个码字）时抛出 BarcodeException，并在载体不可接受时抛出 CompositeLinkageException。
• GS1 校验在编码之前标记格式不正确的 AI 结构与错误的校验位；一个无效的供应链字符串绝不会产出一个可扫描的符合规范的符号。
• IMB 仅接受 20、25、29 或 31 位的输入。
• 条码编码不执行任何密码学。没有 FIPS 模式专属行为；无论 FIPS profile 如何，编码器都以相同方式运行。

符合性

NextPDF 依据下方引用的已发布标准实现这些符号系统，并在其测试套件中固定参考轨迹。本页上的陈述是能力声明：支持不等于符合，符合不等于认证。NextPDF 不持有任何符号系统认证。条款锚点是从产品源码及其符合性 fixture 转述而来；符合性引擎语料库不覆盖条码符号系统标准，因此下方的锚点以产品为依据，没有引用标识符。

接口面	标准	条款锚点（已转述）
GS1 DataBar 元素宽度代数	ISO/IEC 24724:2011	§5.2 符号字符结构；Annex F.1 范例（Omnidirectional）；Annex F.2（Limited）；Annex F.3（Expanded）
GS1 DataBar stacked 布局	ISO/IEC 24724:2011	§5.4 Stacked；§5.5 Stacked Omnidirectional；§7.2.8 Expanded Stacked 行分区与分隔
GS1 DataBar Expanded 编码法	ISO/IEC 24724:2011	§7.2.5.5 三模式压缩状态机；§7.2.6 mod-211 校验字符
GS1 Composite 链接与 CC-C	ISO/IEC 24723:2010	§5.4 CCSI 码字语义；§5.1 载体可接受性
GS1 Composite CC-A 码字	ISO/IEC 24723:2010	§5 带 base-928 转换的通用二进制串编码法
rMQR 符号结构	ISO/IEC 23941:2022	§6.3.2 Table 1 版本尺寸；§7.8.2 固定掩码；Annex C / Annex I 格式信息参考
Micro QR	ISO/IEC 18004	Micro QR M1–M4 容量与格式信息
Han Xin Code	ISO/IEC 20830:2021	符号结构；finder 与 alignment 图案；GB 2312 Region 1/2 模式；Reed–Solomon ECC；掩码
JabCode	ISO/IEC 23634	符号、色彩与 ECC 结构
Postal 符号系统	USPS-B-3200	Intelligent Mail Barcode 字段结构

逐符号系统支持状态

当一个 pro/tests/** 下的 fixture 演练某个变体时，该变体获评 已验证 —— 最好是一个固定到某个已发布范例的参考轨迹。一个已发行但没有专门 fixture 的变体保持 声明。一个无编码器的变体是 不支持。

符号系统 / 变体	状态	佐证（测试路径）	备注
Micro QR (M1–M4)	已验证	pro/tests/Unit/Barcode/MicroQrEncoderTest.php	单元级；一个范例参考轨迹 fixture 是已跟踪的补齐项
DotCode	已验证	pro/tests/Unit/Barcode/DotCodeEncoderTest.php; DotCodeGfArithmeticTest.php	伽罗瓦域算术已覆盖；无厂商解码器往返
Han Xin Code	已验证	pro/tests/Unit/Barcode/HanXinEncoderTest.php; HanXinRsEncodingTest.php	Reed–Solomon 编码路径被显式演练
JabCode (1–61 symbols, 4–256 colors, ECC 0–10)	已验证	pro/tests/Unit/Barcode/JabCode/JabCodeEncoderTest.php（+ 同目录中的 11 个组件套件）	多符号级联与 ECC 范围被演练；无厂商解码器往返
USPS Intelligent Mail Barcode	已验证	pro/tests/Unit/Barcode/ImbEncoderTest.php; ImbRoutingCodeTest.php	路由码与 20/25/29/31 位长度校验被演练
rMQR — all 32 ISO/IEC 23941 versions	已验证	pro/tests/Conformance/Barcode/Rmqr/AnnexValidatedSizesTest.php; RmqrAnnexCFormatInfoTest.php; pro/tests/Unit/Barcode/Rmqr/RmqrEncoderTest.php	version 与 EC 对照 ISO/IEC 23941 Table 1 检查；Annex C / Annex I 格式信息参考值
GS1 DataBar — Omnidirectional / Truncated	已验证	pro/tests/Conformance/Barcode/Gs1DataBar/Gs1DataBarReferenceTest.php	与 Annex F.1 范例逐字节相等；Truncated 以缩减高度共用同一编码
GS1 DataBar — Stacked / Stacked Omnidirectional	已验证	pro/tests/Conformance/Barcode/Gs1DataBar/Gs1DataBarStackedReferenceTest.php	行拆分由 Annex F.1 轨迹派生；分隔构造依 §5.4 与 §5.5
GS1 DataBar — Limited	已验证	pro/tests/Conformance/Barcode/Gs1DataBar/Gs1DataBarLimitedReferenceTest.php; pro/tests/Unit/Barcode/Gs1DataBar/Gs1DataBarLimitedEncoderTest.php	与 Annex F.2 范例逐字节相等（item 00098765432105）
GS1 DataBar — Expanded	已验证	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	已验证	pro/tests/Unit/Barcode/Gs1DataBar/Gs1DataBarExpandedEncoderTest.php（stacked 用例）；上述集成往返	与单行 Expanded 相同的数据流水线；§7.2.8 行分区与分隔被断言
GS1 Composite — CC-C (PDF417 carrier)	已验证	pro/tests/Conformance/Barcode/Gs1Composite/CompositeComponentCTest.php; CompositeRoundtripTest.php; CompositeLinkageTest.php	CCSI 码字 920 与链接标志相互作用已覆盖
GS1 Composite — CC-A	部分	pro/tests/Unit/Barcode/Gs1Composite/CompositeComponentACodewordTest.php; pro/tests/Conformance/Barcode/Gs1Composite/CompositeComponentATest.php	码字生成已验证（base-928、往返自检）；全符号渲染不受支持 —— encode() 失败即关闭
GS1 Composite — CC-B	不支持	pro/tests/Conformance/Barcode/Gs1Composite/CompositeComponentBTest.php（断言失败即关闭的拒绝）	无 2D 编码；链接辅助方法（CCSI 901）仍然可用
GS1 AI parser	已验证	pro/tests/Unit/Barcode/Gs1DataParserTest.php; Gs1DataParserFnc1Test.php	两种输入格式与全部三种载体字节序列输出均被演练
GS1 supply-chain validator	已验证	pro/tests/Unit/Barcode/Gs1ValidatorTest.php; Gs1ValidatorCrossAiTest.php; pro/tests/Unit/Barcode/Gs1/Gs1ValidatorDateValidationEdgeCaseTest.php	校验位、跨 AI 强制组合与日期逻辑被演练

开发说明

• 本页上的佐证锚点是 pro/tests/** 下的测试路径；本模块的仓库不发行任何 examples/ 目录。
• 可用性与授权下列出的七个能力名称是服务提供方绑定的键。IMB 编码器直接构造，不携带任何注册表键。
• CC-A 仅发出通用编码法；应用专属的压缩方法是一个有记录的密度残留，而非一个正确性缺口。

发布边界

本页仅记录外部可观察的行为与受支持的公共 API 接口面。内部命名空间路径、辅助类、机制表、运行手册文件名以及工单前缀不在范围内。

另请参阅

• 条码能力概览（NextPDF Pro）
• Chart 深度参考
• Core 条码模块