# @economist/web-apple-pay 中文文档

规范地址：https://npmcn.com/package/%40economist/web-apple-pay/

版本：1\.16\.0
npm 元数据更新时间：2026-11-11T14:49:34.550Z
中文译文更新时间：2026-11-13T06:04:05.807Z
软件包许可：未声明

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

原始 npm 页面：https://www.npmjs.com/package/%40economist/web-apple-pay
原文对照：https://npmcn.com/package/%40economist/web-apple-pay/?lang=original
项目主页：https://github.com/EconomistDigitalSolutions/shared-packages#readme
源码仓库：https://github.com/EconomistDigitalSolutions/shared-packages

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

- 包体积（解压后）：641 kB，71 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=20\.x
- 运行依赖：0 个
- 首次发布：2026-04-17T05:36:49.722Z
- 最新版本发布：2026-11-11T14:49:33.788Z
- 近 30 天下载量：2886（2026-10-13 至 2026-11-11，npm 官方下载统计）
- 已发布版本数：106（近 12 个月 106 个）

## 中文简介

苹果付费UI 的 Web 组件包

## 安装

```sh
npm install @economist/web-apple-pay
```

也可以使用：`pnpm add @economist/web-apple-pay`、`yarn add @economist/web-apple-pay`、`bun add @economist/web-apple-pay`

## README

# @economist/web-apple-pay (英语)

框架不可知Apple Pay UI组件作为Web组件被执行.

本套件提供:

-   `teg-apple-pay-button`
-   `teg-apple-pay-modal`

它有意以UI为重点。 消费者应用程序拥有后端支付管弦乐,商号验证,以及秘密操作.

## 所需资源

-   节点.js `20.x` 或稍后时间
-   无 `10.x` 或稍后时间

## 安装

```sh
npm install --save @economist/web-apple-pay
```

## 快开始

### (1) 配置运行时间值

打电话 `configureApplePay(...)` 在应用程序启动期间, 在渲染 Apple Pay UI 之前 :

```ts
import {
  configureApplePay,
  defineApplePayElements,
} from '@economist/web-apple-pay';

configureApplePay({
  merchantId: 'merchant.com.economist.your-app',
  debugBypassEnabled: false,
  // required: wallet API base URL for session and checkout calls
  walletApiBaseUrl: 'https://bff-test.economist.com',
});

defineApplePayElements();
```

### 2) 创建并挂载按钮

```ts
import type { Offer, ApplePayButton } from '@economist/web-apple-pay';

const button = document.createElement('teg-apple-pay-button') as ApplePayButton;
button.offer = offer as Offer;
button.country = 'US';
button.dataset.loggedIn = 'true';

container.appendChild(button);
```

单击时,按钮创建并打开 `teg-apple-pay-modal` 自动.

## 运行时间配置

### `configureApplePay(config)`

设置 Apple Pay 可用性检查所用的软件包级运行时间配置 . 在应用程序启动时调用一次 .

`config` 形状 :

-   `merchantId` (单位:千美元)`string`,需要):用于活性卡检查的Apple Pay商标识.
-   `debugBypassEnabled` (单位:千美元)`boolean`:允许 `?BYPASS_APPLE_PAY_CHECKS=1` 查询参数以绕过非生产风格调试流中的能力检查.
-   `walletApiBaseUrl` (单位:千美元)`string`,需要):钱包 API 请求的基础 URL.

若为 `merchantId` 未配置, Apple Pay 可用性检查返回 `false` 按钮会隐藏自己.

## 组件行为

### `ApplePayButton`

-   要求数 `offer` 财务报告和审定财务报表 `country` 在单击流程之前是有意义的.
-   在连接时检查 Apple Pay 可用性; 如果无法使用, 它会隐藏 .
-   为被排除在外的变体跳过渲染( S)`bundle`, (中文(简体) ), `insider_print`) (中文(简体) ). 每一个 `ProductVariant` (包括 `play`)符合条件;计费国仅限于出价区.
-   前进 `data-logged-in` 从按钮到模式( e)`modal.dataset.loggedIn`) (中文(简体) ).

#### 等待完成的工作—— `whenReady()`

使用 `whenReady()` 等待组件的成型寿命周期 给DOM。 这是支持的,稳定的方式 来了解苹果支付是否 可用而不触摸寿命周期内部.

```ts
container.appendChild(btn); // spec-compliant — browser fires connectedCallback naturally
await btn.whenReady(); // resolves when rendering is complete
if (btn.style.display !== 'none') {
  // Apple Pay rendered successfully
} else {
  btn.remove(); // unavailable or suppressed
}
```

> **重要内容:** 电话 `whenReady()` _在此之前_ `appendChild` 决定 立即联系 `undefined` 它不会等待未来的连接. 总是在附加元素后调用 .

### `ApplePayModal`

-   打开 `ApplePayButton` 点击.
-   输出 `apple-pay-confirmed` 当CTA被接受.
-   `Escape` 关闭模式并阻止向其他全球处理者传播.

## 活动

### `apple-pay-confirmed`

调自 `ApplePayModal` 作为 `CustomEvent` 改为:

-   `detail.skuId` (单位:千美元)`string`(中文(简体) )
-   `detail.country` (单位:千美元)`string`(中文(简体) )

消费者应该倾听这个活动,继续支付管弦乐.

## 公共 API

-   `defineApplePayElements()`:登记两个自定义要素.
-   `configureApplePay(config)`:设置所需的运行时间配置(merchant ID和钱包 API Base URL,带有可选调试绕行).
-   `ApplePayButton`:按钮组件类.
    -   `whenReady(): Promise<void>` ——当当前使生命周期完成(可用或隐藏)时解决. 如果在元素连接之前被调用, 立即决定 .
    -   `createIfEnabled(offer, country, entryPoint?)`: 返回已配置的按钮或 `null`。 。 。 .
        -   `DUAL_OFFER_BANNER` (或省略):总是在提供排除条件之后进行——没有主页/Safari门 `createIfEnabled` (设备通过) `isApplePayAvailable` 上载.
        -   `FREE_TRIAL_BANNER`: 总是与 Dual 相同的隔离门; 钱包印象 `entry_point` 实值 `free_trial_banner`。 。 。 .
        -   `FREE_TRIAL_POPUP`: 总是在排出后门. 钱包印象 `entry_point` 实值 `free_trial_popup`关于一个登录读者的付款成功, `/checkout/complete` 以 `status=nspc`。匿名弹出会留下 `nex`其他入境点停留 `lex` 或者说 `nex`。原始 URL 仍然写入到 `checkout-redirect` 来检查一下.
        -   `SUBSCRIBE`: 相同的 " 后排 " 门 `/subscribe` (sma-checkout);无振幅. 钱包印象 `entry_point` 实值 `subscribe`。 。 。 .
        -   `SALES_PAGE`: 用于Sma-checkout销售页面(黑色星期五和其他升级)的同一门;无展出。 主机管理的返回 URL 如 `SUBSCRIBE`;不包括打印报价。 钱包印象 `entry_point` 实值 `sales_page`。 。 。 .
        -   `PAYWALL`: 总是在提供排除后+Safari/Apple安置资格。 无振幅实验 / `$exposure`。 。 。 .
        -   `REGWALL`: 惰性——总是返回 `null`。 。 。 .
    -   **分析.** 切入点为 `entry_point` 每次TEDL漏斗事件: `express_wallet_impression`, (中文(简体) ), `express_wallet_click`, (中文(简体) ), `wallet_payment_sheet_open`, (中文(简体) ), `wallet_payment_authorised`, (中文(简体) ), `wallet_payment_success`, (中文(简体) ), `wallet_payment_failure` 财务报告和审定财务报表 `fallback_checkout`。当主机未设置一个时,它被忽略。 每场 `validation_*` 事件不会携带它.
    -   **印刷报价(`bundle`, (中文(简体) ), `insider_print`)——在一面旗帜后,默认关闭.** `PRINT_OFFERS_ENABLED` (编入放行,出船 `false`: `false` 不包括每个入口处的打印; `true` 启用特性。 即便如此,也只有入境点 `allowsPrintOffers: true` 内 `ENTRY_POINT_CONFIG` (单位:千美元)`src/apple-pay-button.ts`)取出印刷品——目前仅取出 `SUBSCRIBE`旗帜,弹出,付费墙和regwall从来不做。 更新的主机 `button.offer` 应使用 `getExcludedVariants(entryPoint)` 而不是堕落的 `APPLE_PAY_EXCLUDED_VARIANTS`。对于允许的打印报价,表格另外收集交货地址、名称和电话,以及:
        -   限制要约价格区的交货量减去无法向(`src/data/no-delivery-countries.json`);没有可交付国家的提议会隐藏按钮;
        -   以 sma-checkout 交付格式规则(按区、商务服务长度限制、US zip/加拿大邮政编码格式、IN和CN 所需的电话)验证地址,并保持工作表的开通时有字段错误(`delivery-contact-details.ts`规则 `utils/address-rules.ts`(三);
        -   发送 `supportedDeliveryCountries` 和货运联系人 `/v1/wallet/purchase` (电话由验证器正常使用,例如. `098765 43210` 因为 In 变成 `+919876543210`;不能正常化的则被排除在外),它重新验证并转发送货地址给商务服务公司. **释放命令 :** 使用钱包支付- api 更改后, 随旗帜释放 `true`· ;
        -   一起报告计费和发送字段错误,所以工作表显示每个差的字段.
        -   名称和地址必须是拉丁字母外加每次购买(SMA-3066)的已核准的二甲状腺素,与sma-checkout相同;非拉丁输入显示"请只使用拉丁字母".
    -   **买后还.** Banners, 弹出, paywall和regwall 将用户返回到按钮打开的页面. `SUBSCRIBE` 财务报告和审定财务报表 `SALES_PAGE` 将返回目标留给主机(sma-checkout 保存用户从那里来的文章).
-   `ApplePayModal`: 模式组件类.
-   `Offer`: 提供组件道具所使用的合同类型.

## 解决问题

### 未显示按钮

检查 :

-   `configureApplePay(...)` 在渲染前被调用(带有有效 `merchantId` 财务报告和审定财务报表 `walletApiBaseUrl`(中文(简体) )
-   设备/浏览器支持 Apple Pay( 需要苹果设备上的 Safari) —— 由 `isApplePayAvailable` 挂载)
-   工资墙: Safari/Apple安置资格(或 `?BYPASS_APPLE_PAY_CHECKS=1` 质量保证)
-   标语 / `FREE_TRIAL_POPUP`: 消费者杀机关机(无主页/Safari门) `createIfEnabled`(中文(简体) )
-   不排除要约的变式(`bundle`, (中文(简体) ), `insider_print`页:1 `PRINT_OFFERS_ENABLED` 实值 `false`(中文(简体) )

### 登录的复选框副本显示错误

设定 `button.dataset.loggedIn = 'true'` 在附加按钮之前。 按钮自动向模式转发此旗帜 .

## 安全和责任

商贸设置必须通过消费申请处理:

-   运行时注入商家配置
-   在信任的后端服务中进行商家验证
-   在此软件包外保留证书/ 机密

## 地方发展

从 `shared-packages`数字 :

```sh
cd packages/web-apple-pay
npm run build
yalc publish --sig
```

然后在消费的应用中:

```sh
yalc add @economist/web-apple-pay
```

## 故事书

本地运行故事书 :

```sh
npm run storybook --workspace @economist/web-apple-pay
```

构建静态故事本输出 :

```sh
npm run build-storybook --workspace @economist/web-apple-pay
```

故事报道矩阵:

-   `ApplePayButton` docs页面显示稳定的默认示例.
-   `ApplePayButton` 行为和状态变体作为个别画布故事在"故事本"中提供.
-   `ApplePayModal` docs页面显示稳定的默认示例.
-   `ApplePayModal` 行为和状态变体作为个别画布故事在"故事本"中提供.

已停用`PRINT_OFFERS_ENABLED` 实值 `false`;见上文公共API部分.

## 常见问题

### @economist/web-apple-pay 是什么？

苹果付费UI 的 Web 组件包

### 如何安装 @economist/web-apple-pay？

在项目目录运行 npm install @economist/web-apple-pay，或使用 pnpm add / yarn add / bun add。

### @economist/web-apple-pay 支持 TypeScript 吗？

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

### @economist/web-apple-pay 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @economist/web-apple-pay 需要什么版本的 Node\.js？

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

### @economist/web-apple-pay 可以商用吗？

@economist/web-apple-pay 使用 未声明 许可。package\.json 没有声明许可证。没有许可证的代码默认保留全部权利，商用前请联系作者或查看仓库中的 LICENSE 文件。以上为概括，不构成法律意见，请以许可原文为准。

### @economist/web-apple-pay 的下载量有多少？

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

### @economist/web-apple-pay 还在维护吗？

最新版本 1\.16\.0 发布于 2026/11/11（2 天前）；至今共发布 106 个版本，其中过去 12 个月发布了 106 个；首次发布于 2026/04/17。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。