Recurly.js Elements完全指南打造完全自定义UI的新一代支付表单API【免费下载链接】recurly-jsSimple subscription billing in the browser项目地址: https://gitcode.com/gh_mirrors/re/recurly-jsRecurly.js 是 Recurly 推出的浏览器端订阅计费 JavaScript 库Simple subscription billing in the browser而Elements API是它构建支付表单的核心能力通过几个独立的支付元素嵌入你的页面你可以自由设计卡号、有效期、CVV 输入框的外观与布局同时敏感数据始终在安全的 iframe 中处理让你的站点轻松满足 PCI 合规要求。本指南面向新手带你快速掌握 Elements 的 5 种元素、样式定制、事件监听与令牌Token生成的完整流程。为什么选择 Elements完全自定义的支付表单相比传统的 Hosted Fields 整组托管输入框新一代 Elements API 在自由度上实现了质的飞跃对比项Hosted FieldsElements APIUI 自由度有限完全自定义布局字段拆分整组卡号/月份/年份/CVV 可独立拆分数据合规iframe 隔离同样基于 iframe 隔离事件回调有限change / focus / blur / submit每个 Element 本质上是一个透明 iframe实现见 element.js用户的输入永远不会进入你的页面 DOM而是通过 postMessage 总线bus.js与 Recurly 服务器通信从源头保证卡号安全。上图是官方 E2E 视觉基线截图CardElement 将卡号、有效期、CVV 合并在一个输入框中左侧自动识别并显示银行卡品牌图标整体外观完全由你的 CSS 决定。认识 5 种支付元素CardElement 与独立字段Elements 实例elements.js提供 5 个工厂方法按需选择组合元素用途源码文件CardElement卡号 有效期 CVV 三合一card.jsCardNumberElement仅卡号输入框card-number.jsCardMonthElement有效期月份card-month.jsCardYearElement有效期年份card-year.jsCardCvvElement安全码输入框card-cvv.js⚠️组合规则CardElement必须单独使用4 个独立字段则须一起使用。这套白名单规则由源码中的VALID_SETS强制执行elements.js#L33-L37混用会直接抛出错误。当你希望卡号占满一行、月份/年份/安全码各占一格这种完全自由的布局时就使用 4 个独立元素——它们与 CardElement 完全兼容同一套样式与事件 API。快速上手3 步创建 Elements 支付表单1️⃣创建实例与元素入口在 lib/recurly.js 暴露的recurly.Elements()工厂方法上2️⃣挂载到容器attach()支持选择器字符串或 DOM 节点3️⃣提交时生成 Tokenrecurly.token()自动识别 Elements 实例token.js。// 创建并挂载一个 CardElement recurly.Elements() .CardElement({ displayIcon: true }) .attach(#card-container);// 表单提交时生成安全令牌 recurly.token(elements, { first_name: Ada }, (err, res) { // res.token 可安全提交到你的后端创建订阅 });元素还提供remove()从页面移除、focus()主动聚焦、configure()动态改样式等方法完整类型签名见 types/lib/elements.d.ts。深度定制外观style 选项与 CSS 状态类configure(options)支持的选项由源码白名单约束element.js#L26-L31displayIcon是否显示卡品牌图标inputTypetext/mobileSelect/select移动端自动弹出原生下拉选择有效期tabIndex控制 Tab 键焦点顺序style字体颜色、字号、字重、行高、placeholder 文案与颜色、无效值invalid样式等同时元素容器会自动携带状态类名你可以用一行 CSS 实现视觉反馈recurly-element-focus→ 聚焦中recurly-element-valid→ 输入合法recurly-element-invalid→ 输入有误 例如.recurly-element-invalid { border-color: red; }就能让校验状态清晰可见配合内置的style.invalid甚至可以在不写 CSS 的情况下完成错误提示美化。监听关键事件change、focus、blur 与 submit每个元素都是事件发射器可监听 6 类事件change/focus/blur/submit/attach/remove定义见 elements.d.ts#L207change值变化时触发实时拿到empty、focus、valid三个状态适合做实时校验提示focus/blur配合你的 UI 做高亮动画submit用户在框内按回车时触发Elements 实例会统一向父页面转发elements.js#L159-L162上图来自项目的 E2E 视觉测试基线对应 behavior.tabbing.test.js展示了 Tab 键在卡号、月份、年份、CVV 输入框间切换时焦点高亮与移动端tabProxy代理机制的工作效果——移动端焦点代理同样由 element.js#L113-L118 实现。安全机制卡号如何变成 Tokenrecurly.token(elements, customerData, callback)是 Elements 的令牌生成入口token.js#L97-L137流程如下卡号等敏感数据始终留在 iframe 内经加密通道直达 Recurly 服务器你只需要传姓名、地址等非敏感客户数据first_name、address1等白名单字段见 token.js#L11-L22回调中的res.token可安全 POST 给你的后端用于创建订阅订单⚠️注意Elements 实例中必须包含可生成令牌的元素CardElement或完整的 4 字段组合否则会得到elements-tokenization-not-possible错误elements.js#L170-L177。新手常见问题 FAQQ1Elements 和 Hosted Fields 有什么区别Hosted Fields 是较早期的整组托管输入框Elements 是新一代 API字段可拆分、样式选项与事件回调更丰富。Q2卡号会暴露在我的页面上吗不会。输入发生在 Recurly 的独立 iframe 中你的服务器只会收到 Token天然降低 PCI-DSS 合规范围。Q3如何优化移动端体验将inputType设为mobileSelectiPhone/Android 上输入有效期时会弹出原生下拉框告别手动输入月份年份。Q4哪里能找到完整的类型定义查看 types/lib/elements.d.ts包含全部样式选项、事件签名与attach/configure方法定义IDE 自动补全开箱即用。小结Recurly.js Elements 用元素化的方式重塑了浏览器支付表单5 种元素自由组合、style 选项与 CSS 状态类双重美化、iframe 隔离保障 PCI 合规、Token 机制让后端收发无忧。无论你是新建订阅结账页还是重构旧的支付表单Elements API 都是简单、安全又灵活的选择。✅【免费下载链接】recurly-jsSimple subscription billing in the browser项目地址: https://gitcode.com/gh_mirrors/re/recurly-js创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Recurly.js Elements完全指南：打造完全自定义UI的新一代支付表单API
Recurly.js Elements完全指南打造完全自定义UI的新一代支付表单API【免费下载链接】recurly-jsSimple subscription billing in the browser项目地址: https://gitcode.com/gh_mirrors/re/recurly-jsRecurly.js 是 Recurly 推出的浏览器端订阅计费 JavaScript 库Simple subscription billing in the browser而Elements API是它构建支付表单的核心能力通过几个独立的支付元素嵌入你的页面你可以自由设计卡号、有效期、CVV 输入框的外观与布局同时敏感数据始终在安全的 iframe 中处理让你的站点轻松满足 PCI 合规要求。本指南面向新手带你快速掌握 Elements 的 5 种元素、样式定制、事件监听与令牌Token生成的完整流程。为什么选择 Elements完全自定义的支付表单相比传统的 Hosted Fields 整组托管输入框新一代 Elements API 在自由度上实现了质的飞跃对比项Hosted FieldsElements APIUI 自由度有限完全自定义布局字段拆分整组卡号/月份/年份/CVV 可独立拆分数据合规iframe 隔离同样基于 iframe 隔离事件回调有限change / focus / blur / submit每个 Element 本质上是一个透明 iframe实现见 element.js用户的输入永远不会进入你的页面 DOM而是通过 postMessage 总线bus.js与 Recurly 服务器通信从源头保证卡号安全。上图是官方 E2E 视觉基线截图CardElement 将卡号、有效期、CVV 合并在一个输入框中左侧自动识别并显示银行卡品牌图标整体外观完全由你的 CSS 决定。认识 5 种支付元素CardElement 与独立字段Elements 实例elements.js提供 5 个工厂方法按需选择组合元素用途源码文件CardElement卡号 有效期 CVV 三合一card.jsCardNumberElement仅卡号输入框card-number.jsCardMonthElement有效期月份card-month.jsCardYearElement有效期年份card-year.jsCardCvvElement安全码输入框card-cvv.js⚠️组合规则CardElement必须单独使用4 个独立字段则须一起使用。这套白名单规则由源码中的VALID_SETS强制执行elements.js#L33-L37混用会直接抛出错误。当你希望卡号占满一行、月份/年份/安全码各占一格这种完全自由的布局时就使用 4 个独立元素——它们与 CardElement 完全兼容同一套样式与事件 API。快速上手3 步创建 Elements 支付表单1️⃣创建实例与元素入口在 lib/recurly.js 暴露的recurly.Elements()工厂方法上2️⃣挂载到容器attach()支持选择器字符串或 DOM 节点3️⃣提交时生成 Tokenrecurly.token()自动识别 Elements 实例token.js。// 创建并挂载一个 CardElement recurly.Elements() .CardElement({ displayIcon: true }) .attach(#card-container);// 表单提交时生成安全令牌 recurly.token(elements, { first_name: Ada }, (err, res) { // res.token 可安全提交到你的后端创建订阅 });元素还提供remove()从页面移除、focus()主动聚焦、configure()动态改样式等方法完整类型签名见 types/lib/elements.d.ts。深度定制外观style 选项与 CSS 状态类configure(options)支持的选项由源码白名单约束element.js#L26-L31displayIcon是否显示卡品牌图标inputTypetext/mobileSelect/select移动端自动弹出原生下拉选择有效期tabIndex控制 Tab 键焦点顺序style字体颜色、字号、字重、行高、placeholder 文案与颜色、无效值invalid样式等同时元素容器会自动携带状态类名你可以用一行 CSS 实现视觉反馈recurly-element-focus→ 聚焦中recurly-element-valid→ 输入合法recurly-element-invalid→ 输入有误 例如.recurly-element-invalid { border-color: red; }就能让校验状态清晰可见配合内置的style.invalid甚至可以在不写 CSS 的情况下完成错误提示美化。监听关键事件change、focus、blur 与 submit每个元素都是事件发射器可监听 6 类事件change/focus/blur/submit/attach/remove定义见 elements.d.ts#L207change值变化时触发实时拿到empty、focus、valid三个状态适合做实时校验提示focus/blur配合你的 UI 做高亮动画submit用户在框内按回车时触发Elements 实例会统一向父页面转发elements.js#L159-L162上图来自项目的 E2E 视觉测试基线对应 behavior.tabbing.test.js展示了 Tab 键在卡号、月份、年份、CVV 输入框间切换时焦点高亮与移动端tabProxy代理机制的工作效果——移动端焦点代理同样由 element.js#L113-L118 实现。安全机制卡号如何变成 Tokenrecurly.token(elements, customerData, callback)是 Elements 的令牌生成入口token.js#L97-L137流程如下卡号等敏感数据始终留在 iframe 内经加密通道直达 Recurly 服务器你只需要传姓名、地址等非敏感客户数据first_name、address1等白名单字段见 token.js#L11-L22回调中的res.token可安全 POST 给你的后端用于创建订阅订单⚠️注意Elements 实例中必须包含可生成令牌的元素CardElement或完整的 4 字段组合否则会得到elements-tokenization-not-possible错误elements.js#L170-L177。新手常见问题 FAQQ1Elements 和 Hosted Fields 有什么区别Hosted Fields 是较早期的整组托管输入框Elements 是新一代 API字段可拆分、样式选项与事件回调更丰富。Q2卡号会暴露在我的页面上吗不会。输入发生在 Recurly 的独立 iframe 中你的服务器只会收到 Token天然降低 PCI-DSS 合规范围。Q3如何优化移动端体验将inputType设为mobileSelectiPhone/Android 上输入有效期时会弹出原生下拉框告别手动输入月份年份。Q4哪里能找到完整的类型定义查看 types/lib/elements.d.ts包含全部样式选项、事件签名与attach/configure方法定义IDE 自动补全开箱即用。小结Recurly.js Elements 用元素化的方式重塑了浏览器支付表单5 种元素自由组合、style 选项与 CSS 状态类双重美化、iframe 隔离保障 PCI 合规、Token 机制让后端收发无忧。无论你是新建订阅结账页还是重构旧的支付表单Elements API 都是简单、安全又灵活的选择。✅【免费下载链接】recurly-jsSimple subscription billing in the browser项目地址: https://gitcode.com/gh_mirrors/re/recurly-js创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考