当前位置：首页 > news >正文

pass-js API参考：模板、通行证与字段操作的10个实用方法

news 2026/7/16 22:25:55

pass-js API参考：模板、通行证与字段操作的10个实用方法

【免费下载链接】pass-jsApple Wallet Passes generating library for Node.JS项目地址: https://gitcode.com/gh_mirrors/pa/pass-js

pass-js是一个强大的Node.js库，专门用于生成Apple Wallet通行证（Passes）。无论您是为活动票务、会员卡、优惠券还是登机牌创建数字通行证，pass-js都提供了完整的解决方案。这个库支持本地化、NFC功能和Web服务推送更新，让您的Apple Wallet集成变得简单高效。🎫

📋 为什么选择pass-js？

在开始详细介绍API之前，让我们先了解pass-js的核心优势：

零运行时依赖- 完全自包含，安装时无需额外依赖
TypeScript原生支持- 提供完整的类型定义和智能提示
完整的Apple Pass规范支持- 支持所有通行证样式和功能
本地化支持- 多语言字符串和图像本地化
NFC集成- 支持近场通信功能
Web服务更新- 支持远程通行证更新

🏗️ 模板系统：通行证的基础架构

1. 模板创建与加载方法

模板是pass-js的核心概念，它承载了所有通行证共享的字段、图像和本地化配置。您可以通过多种方式创建模板：

从文件夹加载模板

const template = await Template.load( './path/to/templateFolder', 'secretKeyPassword' );

从ZIP缓冲区创建模板

const template = await Template.fromBuffer(zipBuffer);

手动构建模板

const template = new Template('coupon', { passTypeIdentifier: 'pass.com.example.passbook', teamIdentifier: 'MXL', backgroundColor: 'red', sharingProhibited: true });

2. 证书和密钥管理

每个通行证都需要Apple开发者证书进行签名。pass-js提供了灵活的证书管理方法：

// 从PEM文件加载证书 await template.loadCertificate( '/etc/passbook/certificate_and_key.pem', 'secret' ); // 或直接设置证书字符串 template.setCertificate(pemEncodedPassCertificate); template.setPrivateKey(pemEncodedPrivateKey, optionalKeyPassword);

🎫 通行证创建与配置

3. 从模板创建通行证

一旦模板准备就绪，创建单个通行证变得非常简单：

const pass = template.createPass({ serialNumber: '123456', description: '20%折扣优惠券', logoText: '特别优惠' });

4. 通行证字段操作

pass-js使用类似Map的API来管理通行证字段，这使得字段操作既直观又类型安全：

// 添加主要字段 pass.primaryFields.add({ key: 'time', label: '时间', value: '10:00AM' }); // 读取字段 const dateField = pass.primaryFields.get('date'); // 删除字段 pass.primaryFields.delete('date'); // 清空所有字段 pass.primaryFields.clear();

🎨 图像和本地化管理

5. 图像添加与密度支持

pass-js支持多种图像密度（1x、2x、3x）和本地化图像：

// 添加单张图像 await template.images.add('icon', iconPngBuffer); // 添加特定密度和语言的图像 await template.images.add('logo', logoPath, '2x', 'zh-CN'); // 批量加载所有图像 await template.images.load('./images');

6. 多语言本地化支持

完整的本地化支持让您的通行证适应全球用户：

// 添加英文本地化 pass.localization.add('en', { GATE: 'GATE', DEPART: 'DEPART', ARRIVE: 'ARRIVE' }); // 添加中文本地化 pass.localization.add('zh-CN', { GATE: '登机口', DEPART: '出发', ARRIVE: '到达' });

📅 日期和时间处理

7. 日期字段格式化

pass-js提供了强大的日期处理功能，支持ISO 8601字符串和JavaScript Date对象：

import { constants } from '@walletpass/pass-js'; // 使用Date对象 pass.primaryFields.add({ key: 'updated', label: '更新时间', value: new Date(), dateStyle: constants.dateTimeFormat.SHORT, timeStyle: constants.dateTimeFormat.SHORT }); // 使用setDateTime辅助方法 pass.auxiliaryFields.setDateTime( 'serviceDate', 'DATE', serviceDate, { dateStyle: constants.dateTimeFormat.MEDIUM, timeStyle: constants.dateTimeFormat.NONE, changeMessage: '服务日期已更新为%@。' } );

📱 NFC和个人化功能

8. NFC功能集成

对于会员卡等需要NFC功能的通行证，pass-js提供了完整的支持：

const template = new Template('storeCard', { passTypeIdentifier: 'pass.com.example.passbook', teamIdentifier: 'MXL' }); template.nfc.message = 'member-id';

9. 个人化配置

pass-js支持通行证个人化流程，用于奖励卡注册等场景：

template.personalization = { description: '加入Acme奖励计划', requiredPersonalizationFields: [ 'PKPassPersonalizationFieldName', 'PKPassPersonalizationFieldEmailAddress' ], termsAndConditions: '<a href="https://example.com/terms">条款与条件</a>' }; await template.images.add('personalizationLogo', personalizationLogoPng);

📦 生成和输出

10. 通行证文件生成

生成最终的.pkpass文件非常简单：

// 生成Buffer const buffer = await pass.asBuffer(); // 保存到文件 import { writeFile } from 'node:fs/promises'; await writeFile('myPass.pkpass', buffer); // 或直接作为HTTP响应 app.use(async (ctx, next) => { ctx.status = 200; ctx.type = constants.PASS_MIME_TYPE; ctx.body = await pass.asBuffer(); });

🔧 实用工具和常量

pass-js提供了丰富的常量来简化开发：

import { constants } from '@walletpass/pass-js'; // 通行证样式 const PASS_STYLES = ['boardingPass', 'coupon', 'eventTicket', 'storeCard', 'generic']; // 条码格式 constants.barcodeFormat.QR // 'PKBarcodeFormatQR' constants.barcodeFormat.PDF417 // 'PKBarcodeFormatPDF417' constants.barcodeFormat.Aztec // 'PKBarcodeFormatAztec' // 日期格式 constants.dateTimeFormat.SHORT // 'PKDateStyleShort' constants.dateTimeFormat.MEDIUM // 'PKDateStyleMedium' constants.dateTimeFormat.LONG // 'PKDateStyleLong' // 文本对齐方式 constants.textDirection.LEFT // 'PKTextAlignmentLeft' constants.textDirection.CENTER // 'PKTextAlignmentCenter' constants.textDirection.RIGHT // 'PKTextAlignmentRight'