# @destinationstransfers/passkit 中文文档

规范地址：https://npmcn.com/package/%40destinationstransfers/passkit/

版本：6\.6\.1
npm 元数据更新时间：2022-04-05T04:01:15.158Z
中文译文更新时间：2026-11-12T04:08:55.524Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40destinationstransfers/passkit
原文对照：https://npmcn.com/package/%40destinationstransfers/passkit/?lang=original
项目主页：https://github.com/destinationstransfers/passkit
源码仓库：https://github.com/destinationstransfers/passkit

弃用说明：WARNING: This project has been renamed to @walletpass/pass-js\. Install using @walletpass/pass-js instead\.

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：129 kB，42 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=10\.1
- 运行依赖：8 个
- 首次发布：2017-08-07T04:21:53.331Z
- 最新版本发布：2019-10-06T10:51:29.946Z
- 近 30 天下载量：3000（2026-10-12 至 2026-11-10，npm 官方下载统计）
- 已发布版本数：56（近 12 个月 0 个）

## 中文简介

苹果钱包传出并从 Node.js 推动更新

## 安装

```sh
npm install @destinationstransfers/passkit
```

也可以使用：`pnpm add @destinationstransfers/passkit`、`yarn add @destinationstransfers/passkit`、`bun add @destinationstransfers/passkit`

## README

[![npm (scoped)](https://img.shields.io/npm/v/@destinationstransfers/passkit.svg)](https://www.npmjs.com/package/@destinationstransfers/passkit) [![codecov](https://codecov.io/gh/destinationstransfers/passkit/branch/master/graph/badge.svg)](https://codecov.io/gh/destinationstransfers/passkit) [![Build Status](https://dev.azure.com/destinationstransfers/passkit/_apis/build/status/destinationstransfers.passkit?branchName=master)](https://dev.azure.com/destinationstransfers/passkit/_build/latest?definitionId=2&branchName=master) [![Known Vulnerabilities](https://snyk.io/test/github/destinationstransfers/passkit/badge.svg?targetFile=package.json)](https://snyk.io/test/github/destinationstransfers/passkit?targetFile=package.json) [![DeepScan grade](https://deepscan.io/api/teams/2667/projects/4302/branches/35050/badge/grade.svg)](https://deepscan.io/dashboard#view=project&tid=2667&pid=4302&bid=35050) [![Reliability Rating](https://sonarcloud.io/api/project_badges/measure?project=destinationstransfers_passkit&metric=reliability_rating)](https://sonarcloud.io/dashboard?id=destinationstransfers_passkit) [![Lines of Code](https://sonarcloud.io/api/project_badges/measure?project=destinationstransfers_passkit&metric=ncloc)](https://sonarcloud.io/dashboard?id=destinationstransfers_passkit) [![Maintainability Rating](https://sonarcloud.io/api/project_badges/measure?project=destinationstransfers_passkit&metric=sqale_rating)](https://sonarcloud.io/dashboard?id=destinationstransfers_passkit) [![tested with jest](https://img.shields.io/badge/tested_with-jest-99424f.svg)](https://github.com/facebook/jest) [![install size](https://packagephobia.now.sh/badge?p=@destinationstransfers/passkit)](https://packagephobia.now.sh/result?p=@destinationstransfers/passkit) [![Language grade: JavaScript](https://img.shields.io/lgtm/grade/javascript/g/destinationstransfers/passkit.svg?logo=lgtm&logoWidth=18)](https://lgtm.com/projects/g/destinationstransfers/passkit/context:javascript)

![Apple Wallet logo](https://docs-assets.developer.apple.com/published/c104c9bff0/841b02dd-b78c-4cad-8da4-700761d34e14.png)

# @ 日期转让/ passkit

一个用于生成 Apple Walet 通行证的Node.js 库,其中包含本地化,NFC 和网络服务推取更新支持. 以 Typescript 写成 .

  
  
  

# 安装

安装方式 `NPM` 或者说 `yarn`数字 :

```sh
npm install @destinationstransfers/passkit --save

yarn add @destinationstransfers/passkit
```

# 获取您的证书

首先,你需要一份证书 [iOS 提供 门户](https://developer.apple.com/ios/manage/passtypeids/index.action)。 。 每张通行证类型ID需要一张证书.

在将此证书添加到您的密钥链后, 您需要将其导出为 `.p12` 文件,然后将该文件转换为 `.pem` 使用 `passkit-keys` 命令 :

```sh
./bin/passkit-keys ./pathToKeysFolder
```

并复制到密钥目录中.

这个 [苹果世界开发者关系认证 权力](https://www.apple.com/certificateauthority/) 证书不再需要,因为它已经包含在这个软件包中.

# 从模板开始

从模板开始。 模板将包含所有共同数据字段 分享你的通行证.

```js
const { Template } = require("@destinationstransfers/passkit");

// Create a Template from local folder, see __test__/resources/passes for examples
// .load will load all fields from pass.json,
// as well as all images and com.example.passbook.pem file as key
// and localization string too
const template = await Template.load(
  "./path/to/templateFolder",
  "secretKeyPasswod"
);

// or
// create a Template from a Buffer with ZIP content
const s3 = new AWS.S3({ apiVersion: "2006-03-01", region: "us-west-2" });
const s3file = await s3
  .getObject({
    Bucket: "bucket",
    Key: "pass-template.zip"
  })
  .promise();
const template = await Template.fromBuffer(s3file.Body);

// or create it manually
const template = new Template("coupon", {
  passTypeIdentifier: "pass.com.example.passbook",
  teamIdentifier: "MXL",
  backgroundColor: "red",
  sharingProhibited: true
});
await template.images.add("icon", iconPngFileBuffer)
                     .add("logo", pathToLogoPNGfile)
```

第一个论点是传球风格(`coupon`, (中文(简体) ), `eventTicket`),并 第二个可选参数有要设置在模板上的任何字段.

您可以直接访问模板字段,或者从链式访问器方法访问,例如:

```js
template.passTypeIdentifier = "pass.com.example.passbook";
template.teamIdentifier = "MXL";
```

需要以下模板字段:

-   `passTypeIdentifier` - 具有前缀的Apple Pass 类型 ID `pass.`
-   `teamIdentifier` - 可能包含一个I

您可以将任何可用的字段设置在一个模板或通过实例上,例如: `backgroundColor`, (中文(简体) ), `foregroundColor`, (中文(简体) ), `labelColor`, (中文(简体) ), `logoText`, (中文(简体) ), `organizationName`, (中文(简体) ), `suppressStripShine` 财务报告和审定财务报表 `webServiceURL`。 。 。 .

此外,您需要告诉模板在哪里找到密钥文件 :

```js
await template.loadCertificate(
  "/etc/passbook/certificate_and_key.pem",
  "secret"
);
// or set them as strings
template.setCertificate(pemEncodedPassCertificate);
template.setPrivateKey(pemEncodedPrivateKey, optionalKeyPassword);
```

如果您拥有所有通道通用的图像, 您可能想要在模板中指定一次 :

```js
// specify a single image with specific density and localization
await pass.images.add("icon", iconFilename, "2x", "ru");
// load all appropriate images in all densities and localizations
await template.images.load("./images");
```

您可以添加图像本身或图像 `Buffer`。图像格式将执行 **巴布亚新几内亚**。 。 。 .

或者, 如果您有一个包含模板文件的目录 `pass.json`键 `com.example.passbook.pem` 和所有需要的图像,你可以只使用这个单一命令:

```js
const template = await Template.load(
  "./path/to/templateFolder",
  "secretKeyPasswod"
);
```

# 创建您的通行证

要从模板创建新密码:

```js
const pass = template.createPass({
  serialNumber: "123456",
  description: "20% off"
});
```

就像模板一样,你可以直接访问通过字段,例如:

```js
pass.serialNumber = "12345";
pass.description = "20% off";
```

在JSON的规格中,结构字段(主字段,副字段, 等)作为数组表示,但项目必须具有不同的密钥属性。 乐 叹一口气.

为方便起见,可以使用标准映射对象的方法或 `add` 那个 会做符合逻辑的事。 例如,增加一个主字段:

```js
pass.primaryFields.add({ key: "time", label: "Time", value: "10:00AM" });
```

要得到一个或所有字段:

```js
const dateField = pass.primaryFields.get("date");
for (const [key, { value }] of pass.primaryFields.entries()) {
  // ...
}
```

删除一个或全部字段 :

```js
pass.primaryFields.delete("date");
pass.primaryFields.clear();
```

将图像添加到通道上与将图像添加到模板上(见上文)相同.

# 处理日期

如果你有的话 [在您的作业区域中的日期](https://developer.apple.com/library/archive/documentation/UserExperience/Reference/PassKit_Bundle/Chapters/FieldDictionary.html#//apple_ref/doc/uid/TP40012026-CH4-SW6) 确保它们采用ISO 8601格式,带有时区或一个 `Date` 举个例子. 例如:

```js
const { constants } = require('@destinationstransfers/passkit');

pass.primaryFields.add({ key: "updated", label: "Updated at", value: new Date(), dateStyle: constants.dateTimeFormat.SHORT, timeStyle: constants.dateTimeFormat.SHORT });

// there is also a helper setDateTime method
pass.auxiliaryFields.setDateTime(
  'serviceDate',
  'DATE',
  serviceMoment.toDate(),
  {
    dateStyle: constants.dateTimeFormat.MEDIUM,
    timeStyle: constants.dateTimeFormat.NONE,
    changeMessage: 'Service date changed to %@.',
  },
);
// main fields also accept Date objects
pass.relevantDate = new Date(2020, 1, 1, 10, 0);
template.expirationDate = new Date(2020, 10, 10, 10, 10);
```

# 本地化

此库完全支持两者 [字符串本地化](https://developer.apple.com/library/archive/documentation/UserExperience/Conceptual/PassKit_PG/Creating.html#//apple_ref/doc/uid/TP40012195-CH4-SW54) 和(或) [图像本地化](https://developer.apple.com/library/archive/documentation/UserExperience/Conceptual/PassKit_PG/Creating.html#//apple_ref/doc/uid/TP40012195-CH4-SW1)数字 :

```js
// everything from template
// will load all localized images and strings from folders like ru.lproj/ or fr-CA.lproj/
await template.load(folderPath);

// Strings

pass.localizations
  .add("en-GB", {
    GATE: "GATE",
    DEPART: "DEPART",
    ARRIVE: "ARRIVE",
    SEAT: "SEAT",
    PASSENGER: "PASSENGER",
    FLIGHT: "FLIGHT"
  })
  .add("ru", {
    GATE: "ВЫХОД",
    DEPART: "ВЫЛЕТ",
    ARRIVE: "ПРИЛЁТ",
    SEAT: "МЕСТО",
    PASSENGER: "ПАССАЖИР",
    FLIGHT: "РЕЙС"
  });

// Images

await template.images.add(
  "logo" | "icon" | etc,
  imageFilePathOrBufferWithPNGdata,
  "1x" | "2x" | "3x" | undefined,
  "ru"
);
```

本地化适用于所有字段' `label` 财务报告和审定财务报表 `value`。有关于这一点的说明 [文档](https://developer.apple.com/library/ios/documentation/UserExperience/Conceptual/PassKit_PG/Creating.html)。 。 。 .

# 生成文件

要生成文件 :

```js
const buf = await pass.asBuffer();
await fs.writeFile("pathToPass.pass", buf);
```

您可以直接将缓冲发送到 HTTP 服务器响应 :

```js
app.use(async (ctx, next) => {
  ctx.status = 200;
  ctx.type = passkit.constants.PASS_MIME_TYPE;
  ctx.body = await pass.asBuffer();
});
```

# 解决控制台应用程序的问题

如果通过文件生成时没有出错,但无法打开iPhone的传出,将iPhone用macOS 10.14+插入Mac并打开"Console"应用程序. 左边可以选择你的iPhone. 然后,您可以在添加通行证时检查任何出错.

# 贷项

这个项目始于 [assaf/节点密码簿](http://github.com/assaf/node-passbook)。 。 。 . 5.0版本 我们的模块不兼容API,请参见 [释放](https://github.com/destinationstransfers/passkit/releases) 更多信息.

-   瞄准节点QQ 10并重写为Typescript,去除被贬损的呼叫(`new Buffer`页:1
-   替换 `openssl` 与本地 Javascript RSA 执行(通过) `node-forge`(中文(简体) )
-   包括 `Template.pushUpdates(pushToken)` 向 pushToken 发送 APN 更新给定密码类型的请求( 获得) `pushToken` 在您的 PassKit 网络服务执行中)
-   添加字典字段字符串值的常数
-   调整测试到 Jest
-   扩大测试覆盖面
-   添加严格的字典字段值验证( 如有可能) 以防止更早出错
-   添加对地理定位字段和灯塔字段的支持
-   从 JSON 文件添加简单模板和本地化负载
-   我们用它生产 [转帐. do](https://transfers.do/)

## 常见问题

### @destinationstransfers/passkit 是什么？

苹果钱包传出并从 Node\.js 推动更新注意：该包已被作者标记为弃用——WARNING: This project has been renamed to @walletpass/pass-js\. Install using @walletpass/pass-js instead\.

### 如何安装 @destinationstransfers/passkit？

在项目目录运行 npm install @destinationstransfers/passkit，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 passkit-keys，可以用 npx passkit-keys 直接运行。

### @destinationstransfers/passkit 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @destinationstransfers/passkit 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @destinationstransfers/passkit 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=10\.1。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @destinationstransfers/passkit 可以商用吗？

@destinationstransfers/passkit 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @destinationstransfers/passkit 的下载量有多少？

根据 npm 官方下载统计，@destinationstransfers/passkit 在 2026/10/12 – 2026/11/10 这 30 天内被下载 3,000 次，日均约 100 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @destinationstransfers/passkit 还在维护吗？

最新版本 6\.6\.1 发布于 2019/10/06（7 年前）；至今共发布 56 个版本，其中过去 12 个月发布了 0 个；首次发布于 2017/08/07。作者已将其标记为弃用，新项目建议寻找替代方案。