打印精灵GS1 JavaScript 库使用手册

简介

GS1 库是一个用于构建和管理符合 GS1 标准数据结构（如条形码或 RFID 标签中使用的应用标识符 AIs）的 JavaScript 工具。它帮助您将产品、物流和贸易信息编码成标准的 GS1 格式。

核心概念

• 应用标识符 (AI - Application Identifier): 由 GS1 定义的两位到四位数字前缀，用于标识其后面数据的含义和格式。例如，01 代表全球贸易项目代码 (GTIN)，10 代表批号。
• 元素 (Element): 结合了 AI 及其对应的值，构成一个完整的 GS1 数据段。例如 (01)12345678901231。
• FNC1 分隔符: 在某些 GS1 元素的末尾需要一个特殊的分隔符（通常在条形码中表示为 FNC1 字符，ASCII 29），以指示下一个 AI 的开始，尤其是在变长字段之后。此库的 fullcode 方法目前简化了分隔符的处理。

GS1.AI (应用标识符常量)

这是一个静态对象，包含了常用的 GS1 应用标识符及其对应的代码。建议在 add 方法中使用这些常量以提高代码可读性和减少错误。

分类	AI 常量	GS1 AI 代码	描述	备注
产品标识	GTIN	01	全球贸易项目代码	14位数字，包含校验位
	CTN_GTIN	02	内含贸易项目的GTIN
	VAR	20	产品变体
日期/时间	PROD	11	生产日期 (YYMMDD)
	EXP	17	有效期 (YYMMDD)
	PACK	13	包装日期 (YYMMDD)
	BEST	15	保质期 (YYMMDD)
	SELL	16	销售截止日期 (YYMMDD)
批号/序列号	BATCH	10	批号
	SERIAL	21	序列号
	CPV	22	消费者产品变体
	ADD_ID	240	附加产品标识
	SERIAL_2	250	二级序列号
物流单元	SSCC	00	系列货运包装箱代码	18位数字，包含校验位
数量	QTY_VAR	30	可变数量
	QTY_FIXED	37	数量
重量/尺寸	NET_WT	310n	净重(kg), n代表小数位数	例如 3102 代表小数点后两位
	LEN	311n	长度(m), n代表小数位数
	WIDTH	312n	宽度(m), n代表小数位数
	HEIGHT	313n	高度(m), n代表小数位数
	AREA	314n	面积(m²), n代表小数位数
	VOL	315n	净容积(L), n代表小数位数
位置	DEST	410	交货地全球位置码
	BILL_TO	415	受票方全球位置码
	SHIP_TO_LOC	420	交货地邮政编码
	ORIGIN	422	原产国
金额	AMOUNT	390n	应付款金额, n代表小数位数
内部使用	INTERNAL	90	公司内部信息
	INT_91_99	91-99	公司内部使用范围	请注意，91-99 是一个范围描述，不是单个 AI

GS1.check_digit(s) (静态方法)

计算 GS1 校验位。

• 参数:
  • s (String): 需要计算校验位的数字字符串。
• 返回:
  • (Number): 计算出的校验位。
• 用途: 在生成 GTIN 或 SSCC 等带校验位的代码时使用。

1const checkDigit = GS1.check_digit('1234567890123'); // 计算GTIN的校验位
2console.log(checkDigit); // 输出校验位

new GS1() (构造函数)

创建一个新的 GS1 实例。每个实例可以包含一组 GS1 元素。

1const myGs1Data = new GS1();

gs1.add(ai, value) (实例方法)

向 GS1 实例添加一个 GS1 元素。

• 参数:
  • ai (String): 应用标识符 (AI)，可以是 GS1.AI 中定义的常量，也可以是自定义的 2-4 位数字字符串。
  • value (String): 与 AI 关联的数据值。
• 返回:
  • this (GS1 实例): 允许链式调用。
• 抛出错误:
  • 如果 ai 格式不正确。
  • 如果尝试添加重复的 ai。
  • 对于 GTIN 和 SSCC，如果 value 的长度或校验位不符合规范。
• 特殊处理:
  • GTIN (AI '01') / CTN_GTIN (AI '02'): 如果提供的 value 少于 14 位，它会自动在前面填充零并计算校验位。如果提供了 14 位，它会验证第 14 位是否为正确的校验位。
  • SSCC (AI '00'): 如果提供的 value 是 17 位，它会自动计算并添加校验位使其成为 18 位。如果提供了 18 位，它会验证第 18 位是否为正确的校验位。

 1const gs1 = new GS1();
 2
 3gs1.add(GS1.AI.GTIN, '0123456789012') // 自动补齐14位并计算校验位
 4   .add(GS1.AI.BATCH, 'A123B')
 5   .add(GS1.AI.EXP, '251231'); // 生产日期，例如 2025年12月31日
 6
 7// 尝试添加重复AI会报错
 8try {
 9    gs1.add(GS1.AI.BATCH, 'C456D');
10} catch (e) {
11    console.error(e.message); // AI duplicate: (10)
12}
13
14// SSCC 示例
15const gs1Sscc = new GS1();
16gs1Sscc.add(GS1.AI.SSCC, '01234567890123456'); // 自动补齐18位并计算校验位

gs1.fullcode() (实例方法)

生成包含所有已添加 GS1 元素的完整编码字符串。

• 返回:
  • (String): 格式为 (AI)VALUE(AI)VALUE... 的字符串。
• 注意: 当前实现中，每个 AI 及其值都用括号包裹，但没有添加 FNC1 (ASCII 29) 分隔符。在实际的 GS1 条形码或 RFID 应用中，变长字段后通常需要 FNC1。如果需要生成包含 FNC1 的字符串，您可能需要修改 _requiresSeparator 和 fullcode 方法。

1const gs1 = new GS1();
2gs1.add(GS1.AI.GTIN, '0123456789012')
3   .add(GS1.AI.BATCH, 'BATCHABC');
4
5console.log(gs1.fullcode()); // 输出: (01)01234567890123(10)BATCHABC

gs1._requiresSeparator(ai) (内部方法)

此方法为内部使用，通常不建议直接调用。 判断给定的 AI 是否需要在其值后面添加 FNC1 分隔符。当前实现中，它会检查 separatorsNeeded 数组。

gs1.get(ai) (实例方法)

获取指定 AI 对应的值。

• 参数:
  • ai (String): 要查询的应用标识符。
• 返回:
  • (String|null): 如果找到，返回对应的值；否则返回 null。

1const gs1 = new GS1();
2gs1.add(GS1.AI.GTIN, '0123456789012');
3
4console.log(gs1.get(GS1.AI.GTIN)); // 输出: 01234567890123
5console.log(gs1.get(GS1.AI.BATCH)); // 输出: null

gs1.clear() (实例方法)

清空 GS1 实例中所有已添加的元素。

• 返回:
  • this (GS1 实例): 允许链式调用。

1const gs1 = new GS1();
2gs1.add(GS1.AI.GTIN, '123').add(GS1.AI.BATCH, 'XYZ');
3console.log(gs1.getAIs()); // ['01', '10']
4
5gs1.clear();
6console.log(gs1.getAIs