入门检查

# Web 组件入门 ## 概述该技能为使用 Primer 的 Web 组件库 (`@primer-io/primer-js`) 构建结账和支付体验提供了全面的指导。入门组件是与框架无关的自定义元素，可与 React、Next.js、Vue、Svelte 或 vanilla JavaScript 配合使用。在以下情况下使用此技能： * 实施结账页面或支付流程 * 集成Primer支付方式（银行卡、PayPal、BLIK、Apple Pay、Google Pay等） * 构建带有验证的自定义卡片表单 * 使用 React 并需要正确处理 Web 组件集成 * 使用主题和 CSS 自定义属性自定义支付 UI * 为保存的付款方式实施保险库 * 处理支付生命周期事件和回调 ## 🚨 v0.7.0 中的重大变化 **关键 API 更改：** 从 v0.7.0 开始，回调和事件 API 已更新，以便更清晰地分离成功和失败处理： * **回调** ：`onPaymentComplete` 替换为 `onPaymentSuccess` 和 `onPaymentFailure` * **状态字段** : `error` → `primerJsError`, `failure` → ` paymentFailure` * **事件名称** : `primer: payment-methods-updated` → 使用 `primer:methods-update` **v0.7.0 中的新功能：** * 支付生命周期事件：`primer: payment-start`, `primer: payment-success`, `primer: payment-failure` * Vault 事件：`primer:vault:methods-update` * 保险库回调：`onVaultedMethodsUpdate` * 成功负载中经过 PII 过滤的支付数据本技能中的所有示例均使用 v0.7.0+ API。如果使用较旧的 SDK 版本，请参阅旧文档。 ## 快速入门指南 ### 安装 npm 安装@primer-io/primer-js ### 基本 HTML 设置 <头> <元字符集=“UTF-8”/> 入门检查 <正文> <脚本类型=“模块”src=“/src/main.ts”> ### Vanilla JavaScript 初始化从'@primer-io/primer-js'导入{loadPrimer}；从 './fetchClientToken' 导入 { fetchClientToken }；（异步函数（）{ 等待 loadPrimer(); const checkout = document.querySelector('primer-checkout')!; const response =等待 fetchClientToken('order-id'); 如果（响应.成功）{ checkout.setAttribute('client-token', response.clientToken); } // 处理支付成功和失败 checkout.addEventListener('底漆:就绪', (事件) => { const 底漆 = event.detail; primer.onPaymentSuccess = ({ paymentSummary, paymentMethodType }) => { console.log('✅支付成功！', paymentSummary.id); window.location.href = `/confirmation?orderId=${ paymentSummary.orderId}`; }; primer.onPaymentFailure = ({ 错误 }) => { console.error('❌支付失败:', error.message); // 向用户显示错误 }; }); })(); ### React 19 设置（推荐） **打字稿配置：** 从 '@primer-io/primer-js' 导入类型 { CheckoutElement }；声明全局{ 名称空间 JSX { 接口 IntrinsicElements { '底漆结帐'：CheckoutElement； } } } **组件：** 从'react'导入{useEffect}；从'@primer-io/primer-js'导入{loadPrimer}； // ✅ 在组件外部定义选项以供稳定参考常量 SDK_OPTIONS = { 区域设置：'en-GB'，启用支付方法：[PaymentMethodType.PAYMENT_CARD]， }; 函数 CheckoutPage({ clientToken }: { clientToken: string }) { 使用效果（（）=> { 加载底漆（）； }, []); 返回（）； } ## 组件架构 ### 核心组件层次结构底漆检查（根） ├── prime-main（布局容器） │ ├── slot=" payments" (付款方式选择) │ ├── slot="checkout-complete" (成功状态) │ └── slot="checkout-failure" (错误状态) ├── Prime-Payment-Method（个人支付型） ├── prime- payment-method-container（声明式过滤） ├── prime-billing-address（账单信息，仅限SDK Core） ├── prime-error-message-container（支付失败显示） └── prime-card-form（卡支付输入） ├── 引物输入卡号 ├── 引物输入卡到期 ├── 底漆-输入-cvv ├── 底漆输入持卡人姓名 ├── 底漆卡表格提交 └── 使用基础组件的自定义字段： ├── 引物输入包装器 ├── 引物输入标签 └── 引物输入 ## SDK 模式：核心模式与传统模式 ### SDK 核心（自 v0.4.0 起默认）具有增强功能的新支付引擎。 **这是默认设置，建议用于新集成。** // SDK Core默认开启结帐选项= { sdkCore: true, // 默认，无需指定 }; **当前支持的付款方式：** * `PAYMENT_CARD` \- 完整的银行卡付款表格 * `PAYPAL` \- PayPal 按钮集成 * `ADYEN_BLIK` \- 波兰支付方式（OTP 验证）定期添加新的付款方式。检查发行说明以获取更新。 **好处：** * 现代支付处理引擎 * 增强的性能和可靠性 * 新的支付方式支持 * 更好的错误处理和诊断 ### 旧版 SDK 使用 `sdkCore: false` 启用。通过 Web Headless API 提供对 50 多种支付方式的访问。结帐选项= { sdkCore: false, // 选择旧版 SDK }; **何时使用：** * 需要 SDK Core 中尚未包含的支付方式 * 使用遗留模式的现有集成 * 需要特定处理器特定的方法 **重要提示：** 付款方式的可用性取决于： 1. 入门仪表板配置 2. 支付处理器 Web Headless 支持 3. 区域可用性并非所有支付方式都支持 Web Headless。检查 [Primer 付款方式目录]() 中的“Web Headless”列。 ## SDK 选项参考 ### 核心选项通过“options”属性配置 SDK 行为：结帐选项= { // 核心配置 sdkCore: true, // 默认值：true（SDK Core 已启用） locale: 'en-US', // 强制 UI 区域设置 merchantDomain: 'merchant.example.com', // 用于 Apple Pay 验证 disabledPayments: false, // 禁用所有付款方式启用付款方式：[ PaymentMethodType.PAYMENT_CARD, 付款方式类型.PAYPAL, ], }; **核心选项：** 选项 |类型 |默认 |描述 ---|---|---|--- `sdkCore` | `布尔值` | `真实` |启用SDK核心引擎 `语言环境` | `字符串` |浏览器的区域设置 |强制 UI 区域设置（例如“en-GB”） `merchantDomain` | `字符串` | `window.location.hostname` | Apple Pay 验证域名 `禁用付款` | `布尔值` | `假` |禁用全球所有支付方式 `启用付款方式` | `PaymentMethodType[]` | `[PaymentMethodType.PAYMENT_CARD]` |显示哪些付款方式 ### 卡选项配置卡付款表单行为：结帐选项= { 卡：{ 持卡人姓名：{ required: true, // 是否需要持卡人姓名 visible: true, // 持卡人姓名字段是否可见 }, }, }; **卡选项：** 选项 |类型 |默认 |描述 ---|---|---|--- `card.cardholderName.required` | `布尔值` | `假` |需要持卡人姓名 `card.cardholderName.visible` | `布尔值` | `真实` |显示持卡人姓名字段 ### Apple Pay 选项配置 Apple Pay 按钮外观和数据收集：结帐选项= { 苹果支付：{ ButtonType: '购买', // '普通' | '购买' | '设置' | '捐赠' | '退房' | '书' | ‘订阅’ ButtonStyle: '黑色', // '白色' | '白色轮廓' | ‘黑色’ 计费选项：{ requiredBillingContactFields: ['邮政地址', '电子邮件地址'], }, 运输选项：{ requiredShippingContactFields: ['邮政地址', '姓名'], 要求运输方法：假， }, }, }; ### Google Pay 选项配置 Google Pay 按钮外观和数据收集：结帐选项= { 谷歌支付：{ 按钮类型： 'long', // 'long' | '短' | '书' | '购买' | '结帐' | '捐赠' | '订单' | '支付' | '简单' | ‘订阅’ ButtonColor: '黑色', // '默认' | '黑色' | '白色' ButtonSizeMode: '填充', // '填充' | “静态” 捕获账单地址：true，电子邮件必填： false, 要求运输方法：假， }, }; ### 克拉纳选项配置 Klarna 付款行为：结帐选项= { 克拉纳：{ paymentFlow: '默认', // '默认' | “PREFER_VAULT” allowedPaymentCategories: ['pay_now', 'pay_later', 'pay_over_time'], 按钮选项：{ text: '用 Klarna 付款', }, }, }; ### 保险库选项配置付款方式保管（保存以供将来使用）：结帐选项= { 保险库：{ enabled: true, // 启用存储 showEmptyState: true, // 当不存在保管方法时显示消息 }, }; ### 条纹选项配置 Stripe 特定的支付选项：结帐选项= { 条纹：{ 授权数据：{ fullMandateText: '通过提供您的付款信息...', 商户名称：'您的公司名称'， }, publishableKey: 'pk_test_...', }, }; ### 提交按钮选项配置提交按钮行为：结帐选项= { 提交按钮：{ amountVisible: true, // 在按钮上显示金额（例如，“支付 12.34 美元”） useBuiltInButton: true, // 默认：true，对于外部按钮设置 false }, }; **使用外部提交按钮：** // 隐藏内置按钮结帐选项= { 提交按钮：{ useBuiltInButton：假， }, }; // 调度事件以从外部按钮提交 document.getElementById('my-button').addEventListener('click', () => { 文档.dispatchEvent( new CustomEvent('底漆:卡片提交', { 气泡：真实，组成：真实，详细信息：{来源：'外部按钮'}， }), ）； }); ## 贝宝集成 PayPal 集成需要 SDK Core（`sdkCore: true`，这是默认值）。 ### 基本配置从 '@primer-io/primer-js' 导入 { PaymentMethodType }；结帐选项= { sdkCore: true, // 默认，PayPal 必需启用付款方式：[ PaymentMethodType.PAYMENT_CARD, 付款方式类型.PAYPAL, ], 贝宝：{ 风格：{ 布局：'垂直'，颜色：‘金色’，形状：'矩形'，身高：45，标签：“结账”， }, }, }; ### 按钮样式选项自定义 PayPal 按钮外观：选项 |类型 |默认 |描述 ---|---|---|--- `布局` | `'垂直'` | `'水平'` | `'垂直'` |按钮布局方向 `颜色` | ''黄金'` | ''蓝色'` | ``银'` | ''白色'` | ''黑色'` | ''黄金'` |按钮颜色主题 `形状` | `'直'` | `'药丸'` | `'直'` |按钮边框形状 `高度` | `数字` (25-55) | `40` |按钮高度（以像素为单位） `标签` | `'贝宝'` | `'结帐'` | `'立即购买'` | `'支付'` | `'分期付款'` | `'贝宝'` |按钮标签文本 `标语` | `布尔值` | `假` |显示标语（仅限水平布局） `borderRadius` | `数字` (0-55) | `4` |按钮圆角半径（以像素为单位） `禁用最大宽度` | `布尔值` | `假` |禁用最大宽度约束 **造型示例：** // 水平蓝色药丸按钮贝宝：{ 风格：{ 布局：'水平'，颜色：'蓝色'，形状：'药丸'，身高：45，标签：“结账”，标语：假的， } } // 具有自定义边框半径的垂直银色按钮贝宝：{ 风格：{ 布局：'垂直'，颜色：'银色'，形状：'矩形'，身高：50，边框半径：8，禁用最大宽度：true， } } ### 资金来源控制控制可用的 PayPal 资金来源：贝宝：{ disableFunding: ['credit', 'paylater', 'card'], // 隐藏这些选项 enableFunding: ['venmo'], // 显式启用 Venmo } **可用资金来源：** * `card` \- 宾客卡付款（无需 PayPal 账户的信用卡/借记卡） * `credit` \- PayPal 信用（美国、英国） * `paylat` \- PayPal 稍后付款 * `venmo` \- Venmo（美国） **资金控制示例：** // 只有 PayPal 余额和银行账户贝宝：{ 禁用资金：['卡'，'信用卡'，'稍后付款'，'venmo']， } // 仅限 PayPal 和 Venmo 贝宝：{ 禁用资金：['卡'，'信用卡'，'稍后付款']，启用资金：['venmo']， } **重要提示：** `disableFunding` 优先于 `enableFunding`。如果一个源同时出现在两个数组中，它将被禁用。 ### PayPal 保管库启用保管库以允许客户保存他们的 PayPal 帐户：贝宝：{ Vault: true, // 在 SDK 中启用存储 } **要求：** 保管库需要**同时** SDK 配置和服务器端设置： 1. **SDK配置** : 在PayPal选项中设置`vault: true` 2. **客户端会话**：在客户端会话创建请求中配置 `vaultOnSuccess: true` **旧版 SDK** ：对于 `sdkCore: false`，请使用：贝宝：{ 付款流程：'PREFER_VAULT', } ### 完整的 PayPal 示例结帐选项= { sdkCore：正确，启用付款方式：[ PaymentMethodType.PAYMENT_CARD, 付款方式类型.PAYPAL, ], 贝宝：{ // 按钮样式风格：{ 布局：'垂直'，颜色：‘金色’，形状：'药丸'，身高：45，标签：“结账”，边框半径：6， }, // 资金控制禁用资金：['信用卡'，'卡']，启用资金：['venmo']， // 跳跃保险库：真实， }, }; ## 事件和回调 Primer Checkout 使用带有自定义 DOM 事件和回调的事件驱动架构。事件通过 DOM 冒泡，回调提供支付生命周期的直接处理。 ### 核心活动 #### `底漆：准备好` 当 Primer SDK 完全初始化并可供使用时调度。 **事件详细信息：** 包含带有方法和回调的 PrimerJS 实例。 **用途：** const checkout = document.querySelector('primer-checkout'); checkout.addEventListener('底漆:就绪', (事件) => { const 底漆 = event.detail; console.log('✅ Primer SDK 就绪'); // 配置支付成功处理程序 primer.onPaymentSuccess = ({ paymentSummary, paymentMethodType }) => { console.log('✅支付成功', paymentSummary.id); console.log('💳 方法：', paymentMethodType); // 访问可用的支付数据（经过 PII 过滤） if ( paymentSummary. paymentMethodData?.last4Digits ) { console.log('最后 4:', paymentSummary. paymentMethodData.last4Digits); } // 重定向到确认页面 window.location.href = `/order/confirmation?id=${ paymentSummary.orderId}`; }; // 配置支付失败处理程序 primer.onPaymentFailure = ({ 错误, paymentMethodType }) => { console.error('❌支付失败', error.message); console.error('错误代码：', error.code); // 记录诊断 ID 以获取支持 if (error.diagnosticsId) { console.error('诊断 ID:', error.diagnosticsId); } // 显示错误消息并允许重试 showErrorMessage(错误消息); }; // 配置保管方法更新处理程序 Primer.onVaultedMethodsUpdate = ({VaultedPayments }) => { console.log('金库已更新：',VaultedPayments.size(),'方法'); updateVaultUI(vaultedPayments.toArray()); }; }); #### `底漆：状态改变` 每当结账状态发生变化（处理、成功、错误等）时调度。 **事件详细信息：** 包含`isProcessing`、`isSuccessful`、`isLoading`、`primerJsError`、` paymentFailure`。 **用途：** checkout.addEventListener('primer:state-change', (event) => { const { isProcessing, isSuccessful, primeJsError, paymentFailure } = 事件.详细信息；如果（正在处理）{ console.log('⏳ 正在处理付款...'); 显示加载旋转器（）； } 否则如果（成功）{ console.log('✅支付成功！'); 隐藏LoadingSpinner(); } else if (primerJsError || paymentFailure) { const 错误消息 = primeJsError？.message ||付款失败？.message || '发生错误'； console.error('❌支付失败:', errorMessage); // 记录错误代码以供调试 if (付款失败?.code) { console.error('错误代码：', paymentFailure.code); } 隐藏LoadingSpinner(); 显示错误消息（错误消息）； } }); **v0.7.0 中的状态字段更改：** * `error` → `primerJsError` （SDK 级别的错误） * `failure` → ` paymentFailure`（支付级别失败） #### `底漆：方法更新` 当可用的付款方式加载并准备就绪时调度。 **事件详细信息：** 包含带有“toArray()”和“size()”方法的“InitializedPayments”实例。 **用途：** checkout.addEventListener('primer:methods-update', (event) => { const paymentMethods = event.detail.toArray(); console.log('可用的支付方式：', paymentMethods); console.log('总方法：', paymentMethods.length); // 访问各个方法的详细信息 paymentMethods.forEach((方法) => { console.log('方法类型：', method.type); }); }); **提示：** 对于大多数布局和过滤用例，“primer- payment-method-container”组件提供了更简单的声明性方法，无需事件侦听器。 ### 支付生命周期事件（v0.7.0 中的新增功能）支付生命周期事件通过详细的数据负载提供对支付处理阶段的精细跟踪。 #### `底漆：付款开始` 在用户发起付款后立即付款处理开始时调度。 **事件详细信息：** `未定义`（仅用作触发信号） **用途：** document.addEventListener('底漆:付款开始', () => { console.log('💳 付款处理开始'); // 显示加载指示器 showPaymentLoadingSpinner(); // 禁用表单输入以防止重复提交禁用表单输入（）； // 跟踪付款启动 Analytics.track('付款已开始'); }); #### `入门：支付成功` 付款成功完成后发送。 **活动详情：** { paymentSummary：付款摘要； // PII 过滤的支付数据支付方式类型：字符串； // 例如，“PAYMENT_CARD”、“PAYPAL” 时间戳：数字； // 成功的 Unix 时间戳 } **付款摘要结构：** 可用字段（经过 PII 过滤）： * `id`: 支付ID * `orderId`: 商户订单ID * ` paymentMethodType`：使用的付款方式类型 * ` paymentMethodData`：包含非敏感卡数据的对象 * `last4Digits`：卡号的最后 4 位数字（如果适用） * `network`: 卡网络（Visa、Mastercard 等） * ` paymentMethodType`：支付方式类型过滤字段（不可用）： * `cardholderName`：针对 PII 保护进行过滤 **用途：** document.addEventListener('primer:支付成功', (event) => { const { paymentSummary, paymentMethodType, 时间戳 } = event.detail; console.log('✅支付成功！'); console.log('付款ID：', paymentSummary.id); console.log('订单ID：', paymentSummary.orderId); console.log('方法：', paymentMethodType); console.log('时间戳：', new Date(时间戳)); // 访问可用的支付方式数据 if ( paymentSummary. paymentMethodData?.last4Digits ) { console.log('最后 4 位数字：', paymentSummary. paymentMethodData.last4Digits); console.log('网络：', paymentSummary. paymentMethodData.network); } // 在分析中跟踪成功付款 Analytics.track('支付成功', { paymentId: paymentSummary.id, orderId: paymentSummary.orderId, 方法：付款方法类型， last4: paymentSummary. paymentMethodData?.last4Digits, }); // 重定向到确认页面 window.location.href = `/order/confirmation?id=${ paymentSummary.orderId}`; }); **重要提示：** `PaymentSummary` 对象会过滤持卡人姓名等敏感信息。仅使用提供的非敏感字段进行显示和分析。 #### `入门：支付失败` 当付款失败或遇到错误时调度。 **活动详情：** { 错误：{ 代码：字符串； // 错误代码（例如“CARD_DECLINED”）消息：字符串； // 用户友好的错误消息诊断ID？：字符串； // 用于支持的可选诊断 ID 数据？：任何； // 可选的附加错误数据 }; paymentSummary?: PaymentSummary; // 可选，可能未定义支付方式类型：字符串；时间戳：数字； } **用途：** document.addEventListener('primer:支付失败', (event) => { const { 错误、 paymentSummary、 paymentMethodType、时间戳 } = event.detail; console.error('❌支付失败'); console.error('错误代码：', error.code); console.error('错误信息：', error.message); if (error.diagnosticsId) { console.error('诊断 ID:', error.diagnosticsId); } //向用户显示错误信息 showErrorMessage(错误消息); // 在分析中跟踪支付失败 Analytics.track('支付失败', { 错误代码：错误代码，错误消息：错误消息，诊断Id：错误.诊断Id，方法：付款方法类型，时间戳：新日期（时间戳）， }); // 发送到错误跟踪服务 if (error.diagnosticsId) { errorTracker.capturePaymentFailure({ 诊断Id：错误.诊断Id，代码：错误代码，付款方式类型, }); } }); ### Vault 活动（v0.7.0 中的新增功能） #### `底漆：vault：方法更新` 当加载、更新保管库的付款方式或保管库状态更改时调度。 **活动详情：** { VaultedPayments：InitializedVaultedPayments； // Vault API 实例时间戳：数字； // Unix时间戳 } **初始化VaultedPayments API：** * `toArray()`：返回 `VaultedPaymentMethodSummary` 对象的数组 * `get(id: string)`: 通过ID获取特定的保管支付方式 * `size()`: 返回保存的支付方式数量 **VaultedPaymentMethod摘要结构：** * `id`：保管支付方式的唯一标识符 * `analyticsId`：分析跟踪标识符 * ` paymentMethodType`：付款方式类型（例如，'PAYMENT_CARD'、'ADYEN_STRIPE_ACH'） * ` paymentInstrumentType`：工具类型 * ` paymentInstrumentData`：具有经过 PII 过滤的支付工具详细信息的对象 * `last4Digits`: 卡的最后 4 位数字（仅限卡） * `network`: 卡网络，如 VISA、MASTERCARD（仅限卡） * `accountNumberLastFourDigits`：帐号的最后 4 位（仅限 ACH） * `bankName`：银行名称（仅限 ACH） * `accountType`：支票或储蓄（仅限 ACH） * `email`: 电子邮件地址（PayPal 等钱包方式） * `userDescription`：可选的用户提供的描述 **重要提示：** 为了安全起见，持卡人姓名、到期日期和完整帐号等敏感字段将被过滤掉。 **用途：** document.addEventListener('primer:vault:methods-update', (event) => { const { archedPayments, 时间戳 } = event.detail; console.log('💳 Vault 方法已更新'); console.log('保存的方法总数：',VaultedPayments.size()); // 获取所有保存的支付方式 const 方法 =VaultedPayments.toArray(); 方法.forEach((方法) => { console.log('方法ID:', method.id); console.log('类型：', method. paymentMethodType); if (method. paymentInstrumentData) { console.log('最后 4:', method. paymentInstrumentData.last4Digits); console.log('网络：', method. paymentInstrumentData.network); } }); // 使用保存的方法更新 UI 更新VaultDisplay（方法）； // 跟踪分析中的库更新 Analytics.track('Vault 方法已更新', { 计数：方法.长度，时间戳， }); }); ### 卡牌活动卡事件特定于卡支付表单交互和验证。 #### `入门：卡片成功` 当卡表单成功验证并提交时调度。 **事件详细信息：** 包含带有付款提交数据的“结果”对象。 **用途：** checkout.addEventListener('底漆:打卡成功', (event) => { const 结果 = event.detail.result; console.log('✅ 卡片表单提交成功', result); // 禁用表单以防止重复提交禁用CardForm(); // 显示中间成功消息 showMessage('正在处理您的付款...'); }); #### `底漆：卡片错误` 当卡验证失败或提交遇到错误时调度。 **事件详细信息：** 包含带有验证错误对象的“errors”数组。 **用途：** checkout.addEventListener('primer:card-error', (event) => { const 错误 = event.detail.errors; console.error('❌卡验证错误:', error); // 记录每个错误错误.forEach((错误) => { console.error(`${error.field}: ${error.error}`); }); // 显示自定义错误UI 显示验证错误（错误）； }); #### `底漆：卡网络更改` 当检测到卡网络（Visa、Mastercard 等）或根据输入的卡号发生更改时调度。 **事件详细信息：** 包含“DetectedCardNetwork”、“selectableCardNetworks”和“isLoading”。 **用途：** checkout.addEventListener('primer:card-network-change', (event) => { const { detectorCardNetwork, selectableCardNetworks, isLoading } = 事件.详细信息；如果（正在加载）{ console.log('🔍 检测卡网络...'); 返回； } 如果（检测到卡网络）{ const 网络 = detectorCardNetwork.network; console.log('💳 检测到卡网络：', network); // 显示卡片品牌标志 updateCardBrandLogo(网络); // 轨迹卡网络检测 Analytics.track('检测到卡网络', { network }); } }); ### 可触发事件可触发事件是您调度以控制 SDK 行为的事件。 #### `入门：卡片提交` 从应用程序中的任何位置以编程方式触发卡表单提交。 **事件详细信息：** 可选的“source”属性，用于标识触发源。 **用途：** 结帐组件在文档级别侦听此事件，因此您可以从任何地方分派它，而无需直接引用卡片表单元素。 // 从任何地方触发卡片表单提交文档.dispatchEvent( new CustomEvent('底漆:卡片提交', { 气泡：真实，组成：真实，详细信息：{来源：'自定义按钮'}， }), ）； **完整示例：外部提交按钮** <底漆主槽=“主”>

<底漆卡形式>

<底漆输入卡编号> <底漆输入卡到期> <底漆-输入-cvv>

<脚本> // 设置外部按钮 document.getElementById('external-submit').addEventListener('click', () => { // 将事件分派到文档 - checkout 在文档级别侦听文档.dispatchEvent( new CustomEvent('底漆:卡片提交', { 气泡：真实，组成：真实，详细信息：{来源：'外部按钮'}， }), ）； }); // 监听提交结果 const checkout = document.querySelector('primer-checkout'); checkout.addEventListener('底漆:打卡成功', (event) => { console.log('✅ 卡片表单提交成功'); }); checkout.addEventListener('primer:card-error', (event) => { console.log('❌验证错误:', event.detail.errors); }); **重要：** * `bubbles: true` 和 `composed: true` 属性是必需的 * 始终包含一个有意义的“source”参数以进行调试 * checkout组件在文档级别处理事件并在内部转发 ## 保险库集成 Vault 允许客户保存付款方式以供将来使用。 ### 配置结帐选项= { 保险库：{ enabled: true, // 启用存储 showEmptyState: true, // 当没有保存的方法时显示空状态消息 }, }; ### 避难所活动使用“primer:vault:methods-update”事件响应保管库更改： document.addEventListener('primer:vault:methods-update', (event) => { const { archedPayments, 时间戳 } = event.detail; console.log('保存的方法总数：',VaultedPayments.size()); // 获取所有方法 const 方法 =VaultedPayments.toArray(); 方法.forEach((方法) => { console.log(`${method.network} 以 ${method.last4Digits} 结尾`); }); // 获取具体方法 const method =VaultedPayments.get('付款方法-id'); 如果（方法）{ console.log('找到方法：', method); } }); ### 保险库回调在“primer:ready”事件中使用回调进行直接保管库处理： checkout.addEventListener('底漆:就绪', (事件) => { const 底漆 = event.detail; Primer.onVaultedMethodsUpdate = ({VaultedPayments }) => { console.log('金库已更新：',VaultedPayments.size(),'方法'); updateVaultUI(vaultedPayments.toArray()); }; }); ### 完整的 Vault 示例 <底漆主槽=“主”>

<底漆付款方法容器>

<脚本> const checkout = document.querySelector('primer-checkout'); // 配置保险库结帐选项= { 保险库：{ 启用：真，显示空状态：真， }, }; // 处理库更新 checkout.addEventListener('底漆:就绪', (事件) => { const 底漆 = event.detail; Primer.onVaultedMethodsUpdate = ({VaultedPayments }) => { const 方法 =VaultedPayments.toArray(); console.log(`已加载 ${methods.length} 个托管付款方式`); // 显示保存的方法方法.forEach((方法) => { if (method. paymentInstrumentData) { 控制台.日志（ `${method. paymentInstrumentData.network} 以 ${method. paymentInstrumentData.last4Digits} 结尾`, ）； } }); }; }); ## React 集成模式 ### 关键：稳定的对象引用 React 中 Primer 最常见的错误是在每次渲染时创建新的对象引用，导致组件重新初始化和用户输入丢失。这适用于 **React 18 和 React 19**。 ### React 18 与 React 19 比较 React 19 改进了对 Web 组件的支持，但对稳定引用的需求仍然至关重要。方面|反应 18 |反应19 ---|---|--- **物体如何通过** |参考+使用效果| JSX 道具 **属性转换** |将对象转换为 `[object Object]` |指定为属性 **代码模式** |当务之急|声明式 **代码行** | ~15 行 | 〜5行 **需要稳定的参考文献吗？** | ✅ 是（总是）| ✅ 是（总是） **可以内联对象吗？** | ❌ 不（不起作用）| ❌ 否（导致问题） ### 所有三种稳定的参考模式 #### 模式 1：恒定外部组件（对于静态选项） // ✅ 在模块加载时创建一次，永远相同的引用常量 SDK_OPTIONS = { 区域设置：'en-GB'，卡：{ 持卡人姓名：{ 要求：真实，可见：真实， }, }, }; 函数 CheckoutPage({ clientToken }: { clientToken: string }) { // 反应 19 示例返回 ; } **何时使用：** 选项是静态的，不依赖于 props、state 或用户输入 **好处：** * ✅ 零重新渲染开销 * ✅ 最简单的图案 * ✅ 不需要 React hooks #### 模式 2：动态选项的 useMemo 从 'react' 导入 { useMemo } ；函数 CheckoutPage({ clientToken, userLocale,merchantName }: Props) { // ✅ 仅当依赖关系发生变化时创建新对象 const sdkOptions = useMemo( () => ({ 区域设置：用户区域设置，苹果支付：{ 商户名称：商户名称，商家国家代码：'GB'， }, }), [userLocale,merchantName] // 仅当这些更改时重新创建）； // 反应 19 示例返回 ; } **何时使用：** 选项取决于可以更改的道具、状态或上下文 **好处：** * ✅ 稳定的引用，直到依赖关系发生变化 * ✅ 仅在必要时重新初始化 * ✅ 防止不必要的重新渲染 #### 模式 3：要避免的常见错误 // ❌ 错误：JSX 中的内联对象函数结账页面（）{ // 每次渲染时都会有新对象返回 ; } // ❌ 错误：对象位于组件主体中函数结账页面（）{ // 每次渲染时都会有新对象 const options = { locale: 'en-GB' }; 返回 ; } // ✅ 正确：使用常量或 useMemo const SDK_OPTIONS = { locale: 'en-GB' }; 函数结账页面（）{ // 每次渲染都引用相同的对象返回 ; } // ✅ 正确：对空 deps 使用 useMemo 函数结账页面（）{ const options = useMemo(() => ({ locale: 'en-GB' }), []); 返回 ; } ### TypeScript 设置显示两种模式： **模式1：CheckoutElement** 从 '@primer-io/primer-js' 导入类型 { CheckoutElement }；声明全局{ 名称空间 JSX { 接口 IntrinsicElements { '底漆结帐'：CheckoutElement； } } } **模式 2：SDK 选项类型** 从 '@primer-io/primer-js' 导入类型 { PrimerCheckoutOptions }；常量选项：PrimerCheckoutOptions = { 区域设置：'en-GB'，启用支付方法：[PaymentMethodType.PAYMENT_CARD]， }; ### React 18 模式（对于旧版应用程序）对于 React 18，您必须使用 refs 和 useEffect：从 'react' 导入 { useRef, useEffect }; // ✅ 在组件外部定义选项或使用 useMemo const SDK_OPTIONS = { locale: 'en-GB' }; 函数 CheckoutPage({ clientToken }: { clientToken: string }) { const checkoutRef = useRef(null); 使用效果（（）=> { const checkout = checkoutRef.current； if (!checkout) 返回； // 命令式属性赋值 checkout.options = SDK_OPTIONS; // 设置事件监听器 const handleReady = () => console.log('✅ SDK 就绪'); checkout.addEventListener('primer:ready',handleReady); 返回（）=> { checkout.removeEventListener('primer:ready',handleReady); }; }, []); // 空 deps - 运行一次返回 ; } ### React 19 模式（推荐） React 19 允许直接 JSX 属性分配： // ✅ 在组件外部定义选项或使用 useMemo const SDK_OPTIONS = { locale: 'en-GB' }; 函数 CheckoutPage({ clientToken }: { clientToken: string }) { 返回 ; } **关键：** 保持不变！ React 19 并没有消除对稳定引用的需求。 ## 服务器端渲染（SSR） Primer Checkout 需要浏览器 API（Web 组件、DOM）并且必须仅加载客户端。 ### 为什么 SSR 需要特殊处理 SDK依赖于： * Web 组件 API (`customElements.define()`) * 用于组件渲染的 DOM API * iframe 和支付处理的浏览器上下文 * `窗口` 对象这些在 Node.js（服务器）环境中不存在。 ### Next.js #### 应用程序路由器（Next.js 13+） '使用客户端'；从'react'导入{useEffect}；从'@primer-io/primer-js'导入{loadPrimer}；导出默认函数 CheckoutPage() { 使用效果（（）=> { if (窗口类型!== '未定义') { loadPrimer().catch(console.error); } }, []); 返回 ; } “use client”指令将该组件标记为仅客户端。 #### 页面路由器（旧版）从'react'导入{useEffect}；从'@primer-io/primer-js'导入{loadPrimer}；函数结账页面（）{ 使用效果（（）=> { if (窗口类型!== '未定义') { constinitializePrimer = async () => { 尝试{ 等待 loadPrimer(); console.log('✅ 底漆已加载'); } 捕获（错误）{ console.error('❌ 无法加载入门:', error); } }; 初始化底漆（）； } }, []); 返回 ; } 导出默认结账页面； ### Nuxt.js 3 <模板> <脚本设置> 从 'vue' 导入 { onMounted } ； onMounted（异步（）=> { if (import.meta.client) { 尝试{ const { loadPrimer } =等待导入（'@primer-io/primer-js'）; 加载底漆（）； console.log('✅ 底漆已加载'); } 捕获（错误）{ console.error('❌ 无法加载入门:', error); } } }); **注意：** 使用 `import.meta.client` （现代 Nuxt 3）而不是 `process.client` （旧版 Nuxt 2）。 ### SvelteKit <脚本> 从 'svelte' 导入 { onMount }；从 '$app/environment' 导入 { browser } ； onMount（异步（）=> { 如果（浏览器）{ 尝试{ const { loadPrimer } =等待导入（'@primer-io/primer-js'）; 加载底漆（）； console.log('✅ 底漆已加载'); } 捕获（错误）{ console.error('❌ 无法加载入门:', error); } } });

### 最佳实践 1. **始终使用框架生命周期方法**（useEffect、onMounted、onMount） 2. **包括环境检查**（`typeof window`、`import.meta.client`、`browser`） 3. **使用动态导入**来防止服务器捆绑 4. **包裹在try-catch**中进行错误处理 5. **对选项对象使用稳定引用**（适用于所有框架） ## 错误处理 ### 付款失败与验证错误 **验证错误：** * 由输入组件本身处理 * 阻止表单提交直至修复 * 通过卡输入内联显示 * 无需您采取任何行动 **付款失败：** * 表单提交后发生 * 通过 `` 或自定义处理显示 * 需要用户操作（重试、更改付款方式） ### 使用错误消息容器 <底漆主槽=“主”>

<底漆错误消息容器>

**安置指南：** 1. 尝试付款后明显可见 2. 用户自然寻求反馈的地方 3. 与支付方式处于相同的视觉环境中 ### 自定义错误处理 **使用回调：** checkout.addEventListener('底漆:就绪', (事件) => { const 底漆 = event.detail; primer.onPaymentFailure = ({ 错误, paymentMethodType }) => { // 显示自定义错误UI 显示错误通知({ title: '支付失败', 消息：错误消息，允许重试：真， }); // 调试日志 console.error('支付失败：', { 代码：错误代码，消息：错误消息， DiagnosticsId: error.diagnosticsId, // 用于支持方法：付款方法类型， }); // 发送到错误跟踪 errorTracker.capture({ 错误代码：错误代码，诊断Id：错误.诊断Id， }); }; }); **使用状态更改事件：** checkout.addEventListener('primer:state-change', (event) => { const { primeJsError, paymentFailure } = event.detail; if (primerJsError || paymentFailure) { const message = primeJsError?.message ||付款失败？.消息；显示错误消息（消息）； // 记录诊断 ID 以获取支持如果（付款失败？.diagnosticsId）{ console.error('诊断 ID:', paymentFailure.diagnosticsId); } } }); **使用支付失败事件：** document.addEventListener('primer:支付失败', (event) => { const { 错误, paymentMethodType } = event.detail; // 显示用户友好的错误 showErrorMessage(错误消息); // 跟踪分析 Analytics.track('支付失败', { 错误代码：错误代码，方法：付款方法类型， }); // 调试日志 if (error.diagnosticsId) { console.error('支持诊断 ID:', error.diagnosticsId); } }); ## 组件属性与 SDK 选项 ### 为什么存在这种区别组件属性使用 Lit 的属性系统来监视 DOM 属性的变化。直接属性分配会绕过该系统，导致值被忽略。 `options` 属性是唯一的例外 - 它被设计为接受直接属性分配。 ### 组件属性（使用 `setAttribute()`）这些是通过 `setAttribute()` 设置的 HTML 属性： * `client-token` \- 来自后端的 JWT（必需） * `custom-styles` \- CSS 变量的 JSON 字符串 * `loader-disabled` \- 禁用加载程序的布尔值 checkout.setAttribute('client-token', 'your-token'); checkout.setAttribute('加载器禁用', 'true'); 结帐.setAttribute( '自定义样式', JSON.stringify({primerColorBrand: '#4a6cf7' }), ）； ### SDK 选项（使用属性分配）其他所有内容都在“选项”对象中： * 区域设置、付款方式、保险库配置等。结帐选项= { 区域设置：'en-GB'，启用支付方法：[PaymentMethodType.PAYMENT_CARD]，保险库：{启用：true}， }; ### 调试技巧 // 检查是否使用正确 checkout.getAttribute('客户端令牌'); // 应该返回令牌结帐选项； // 应该返回选项对象 // 常见错误 checkout.getAttribute('语言环境'); // 返回 null（区域设置在选项中！） **记住：**切勿混淆这些。组件属性使用 setAttribute()，SDK 选项使用直接属性赋值。 ## 防止未定义组件的闪存 (FOUC) Web 组件通过 JavaScript 注册。注册之前，自定义元素可能会闪烁为未定义。 ### CSS 解决方案（简单）底漆检查：有（：不（：定义））{ 可见性：隐藏； } 使用“visibility:hidden”（而不是“display:none”）来保留布局空间。 ### JavaScript 解决方案（更多控制） Promise.allSettled([ customElements.whenDefined('primer-checkout'), customElements.whenDefined('底漆付款方法'), ]).then(() => { document.querySelector('.checkout-container').classList.add('ready'); }); .checkout-container { 可见性：隐藏； } .checkout-container.ready { 可见性：可见； } ## CSS 主题 ### 自定义属性通过 CSS 申请：：根{ --底漆颜色品牌：#2f98ff； --底漆半径基数：8px； --primer-typography-brand: '国际米兰，无衬线'; --底漆空间基数：4px； } /* 或特定结帐的范围 */ 底漆检查 { --底漆颜色品牌：#4a6cf7； } 或者通过“custom-styles”属性： <底漆检查自定义样式='{“primerColorBrand”：“#2f98ff”，“primerRadiusBase”：“8px”}' > ### 黑暗主题底漆-checkout.底漆-黑暗主题 { --primer-color-text-primary: var(--primer-color-gray-100); --primer-color-background-outlined-default：var(--primer-color-gray-800); } // 应用主题 const checkout = document.querySelector('primer-checkout'); checkout.classList.add('primer-dark-theme'); ## 常见用例 ### 1\.默认结账（最简单）这提供了所有可用支付方式的完整结账体验。 ### 2\.自定义付款方式布局 <底漆主槽=“主”>

选择付款方式

<底漆错误消息容器>

感谢您的订单！

### 3\.声明式付款过滤

### 4\.定制卡表格 <底漆卡形式>

<底漆输入卡编号>

<底漆输入卡到期> <底漆-输入-cvv>

<底漆输入卡持有人名称> <底漆输入包装器> 帐单邮政编码

<底漆卡表单提交>

## 最佳实践 1. **在 React 中始终使用稳定的对象引用**（模块级常量或 `useMemo`） 2. **通过`setAttribute()`**设置组件属性，SDK选项通过属性赋值 3. React `useEffect` 清理函数中的**清理事件监听器** 4. **使用声明性容器**（`primer- payment-method-container`）而不是手动过滤 5. **通过 `primer-error-message-container` 或自定义回调包含错误处理** 6. **在 SSR 框架的`useEffect`**（或同等内容）中加载 Primer 7. **使用 TypeScript 声明**以获得正确的 JSX 支持 8. **保持 SDK 选项简单** \- 仅配置您需要的内容 9. **使用 v0.7.0+ 回调**（`onPaymentSuccess`、`onPaymentFailure`）进行更清晰的错误处理 10. **跟踪支持查询付款失败中的diagnosticsId** ## 常见故障排除 ### 组件在每次渲染时重新初始化？ → 检查对象参考稳定性。使用模块级常量或“useMemo”。 → 在 React 19 中，确保选项对象具有稳定的引用。 → 适用于 React 18 和 React 19。 ### JSX 出现 TypeScript 错误？ → 添加 TypeScript 声明：`import type { CheckoutElement } from '@primer-io/primer-js'` → 在全局 JSX 命名空间中声明或使用 `CustomElements` 类型 ### SSR 错误（“customElements 未定义”、“window 未定义”）？ → 在客户端生命周期中加载 Primer：`useEffect`、`onMounted`、`onMount` → 在 Next.js App Router 中使用 `'use client'` 指令 → 添加环境检查：`typeof window !== 'undefined'` → 使用动态导入：`await import('@primer-io/primer-js')` ### 事件未触发？ → 添加监听器之前确保组件已经挂载 → 在 React 中使用 `useEffect`，等待 `primer:ready` → 检查事件名称（v0.7.0 重命名了一些事件） ### 付款方式未显示？ → 检查客户端令牌是否有效 → 检查 `enabledPaymentMethods` 配置 → 在访问 SDK 之前等待 `primer:ready` 事件 → 验证方法是否在 Primer Dashboard 中配置 → 检查 SDK Core 与 Legacy 模式的兼容性 ### 选项不适用？ → 检查您使用的是 `checkout.options = {...}`，而不是 `setAttribute` → 验证对象在 React 中具有稳定的引用 → 检查 SDK Core 与 Legacy 模式的兼容性 → 切勿在选项中设置 `client-token` （它是组件属性） ### 样式不适用？ → CSS 自定义属性刺穿 Shadow DOM → 使用 `--primer-*` 变量 → 检查特异性和范围 → 应用于 `primer-checkout` 元素或 `:root` ### React 中的无限重新渲染？ → JSX 中的内联对象：`options={{ locale: 'en-GB' }}` \- 使用常量或 useMemo → 组件主体中的对象没有 useMemo → useMemo 数组中缺少依赖项 → 这种情况在 React 18 和 React 19 中都会发生 ### “无法设置 HTMLElement 的属性选项”？ → 组件尚未注册，等待 `primer:ready` → 或确保 `loadPrimer()` 被调用 → 使用 `customElements.whenDefined('primer-checkout')` 等待 ### 付款失败未显示？ → 在布局中包含 `` → 或通过 `onPaymentFailure` 回调实现自定义错误处理 → 或监听 `primer: payment-failure` 事件 → 在状态更改事件中检查 `primerJsError` 和 ` paymentFailure` ### Vault 方法没有出现？ → 在选项中检查 `vault.enabled: true` → 验证客户端会话是否有 `vaultOnSuccess: true` → 监听 `primer:vault:methods-update` 事件 → 使用 `onVaultedMethodsUpdate` 回调进行更新 ### PayPal 按钮未显示？ → 检查 `sdkCore: true` （PayPal 必需） → 在 `enabledPaymentMethods` 中包含 `PaymentMethodType.PAYPAL` → 验证 PayPal 是否已在 Primer Dashboard 中配置 → 检查浏览器控制台是否有 PayPal SDK 错误 ## 资源为了始终保持最新的文档，此技能引用了 Primer Checkout 文档，其中包括： * 组件API和属性 * SDK选项和配置 * 事件负载和回调 * 支付生命周期处理 * Vault 集成模式 * React 集成模式（React 18 和 19） * SSR 框架模式（Next.js、Nuxt、SvelteKit） * CSS 主题和定制 * TypeScript 类型定义有关最新的组件 API、模式和示例，请使用 Context7 MCP 服务器： // 解析库 constlibrary=awaitresolveLibraryId('底漆签出组件'); // 返回：/primer-io/examples // 获取文档 const docs =等待 getLibraryDocs('/primer-io/examples', { 主题：“支付生命周期事件”，代币：10000， }); 这可确保访问最新的组件 API、v0.7.0+ 功能和集成模式。

Web 组件入门

包含技能