自定义字段类型参考

阅读时间：10分钟 | 难度：初学者

概述

表单构建器中的表单字段选项卡是您构建客户在付款表单上看到和填写的表单内容的地方。点击选择字段…，您将看到19种字段类型，涵盖客户信息、展示元素、付款选择和提交按钮本身。

本文档是每种字段类型的完整参考。有关自定义字段工作原理的通用指南——添加、排序、删除、标记为必填——请从如何配置付款表单字段并收集自定义数据开始。

先决条件

• WP Simple Pay Pro（除基本功能外的自定义字段需要 Pro 版）
• 在表单编辑器中打开的付款表单

字段类别

这19种字段类型分为四个功能组：

组	字段
客户信息	姓名、电子邮件地址、电话、地址、税号、日期
付款选择	价格选择器、自定义金额输入、优惠券、定期金额切换、费用恢复切换、金额明细、付款方式
表单结构/显示	标题、文本、下拉菜单、单选按钮
提交触发器	结账按钮、付款按钮

---

客户信息字段

姓名

收集客户的全名并将其存储在 Stripe 客户记录中。在后台拆分为名/姓，以兼容 Stripe。

• 必需项：信用卡支付、大多数法规遵从性要求，以及在电子邮件中进行诸如 {customer-name} 之类的智能标签替换。
• 选项：标签、占位符、必填切换。

电子邮件地址

收集用作客户联系地址和 Stripe 客户电子邮件的电子邮件。当表单发送付款收据时，此项始终是必需的。

• 必需项：收据、管理订阅链接、废弃购物车恢复、ACH/SEPA/Bacs（Stripe 对这些付款方式需要电子邮件）。
• 选项：标签、占位符、必填切换。

电话

收集客户的电话号码，支持国际格式。

• 必需项：短信确认、欺诈筛查、B2B 表单。
• 选项：标签、占位符、必填切换。

地址

收集账单或送货地址。渲染 Stripe 的智能地址元素，包含国家/地区相关的字段和自动完成功能。

• 必需项：税务计算（自动税务需要账单地址）、送货处理、欺诈检查。
• 选项：地址类型（账单或送货）、标签、必填切换。

税务 ID

收集业务税务标识符（增值税、商品及服务税、ABN、EIN 等），并将其附加到 Stripe 客户信息中用于开票。

• 适用于：B2B 欧盟开票、反向征税增值税、需要在收据上打印税号的企业。
• 选项：标签、占位符、必填切换。

日期

使用日期选择器收集日期值。

• 适用于：活动注册、预约预订、特定日期的捐赠、“首选送达”日期。
• 选项：标签、占位符、必填切换、最小/最大日期限制。
• 注意：选定的值将作为表单元数据存储——它不会影响收费金额或 Stripe 账单周期。

---

付款选择字段

价格选择器

多价格表单中最重要的付款字段。允许客户在您在付款选项卡中定义的价位选项之间进行选择。

• 显示样式：选择价格的显示方式：
  • 基本 — 普通单选列表（默认用于包含 1-3 个价位选项的表单）。
  • 下拉菜单 — 精简的 <select> 元素。当您有许多价位并且希望节省垂直空间时最佳。
  • 列表 — 带标题、描述和价格的堆叠卡片。最适合分级定价。
  • 按钮 — 并排的按钮组。最适合简短的标签式选项（10 美元、25 美元、50 美元）。
• 选项：标签、默认价格、必填切换。

自定义金额输入

允许客户输入自己的金额——这是“随心付”和捐赠表单的基础。

• 选项：标签、占位符、最低金额、最高金额、默认金额。
• 提示：与价格选择器结合使用，以提供建议金额以及“自定义”选项。

优惠券

允许客户在结账时应用优惠券代码。优惠券本身在WP Simple Pay > 优惠券下进行管理——请参阅如何添加和配置优惠券。

• 选项：标签、占位符。
• 注意：与全局优惠券管理页面不同。该字段是面向客户的输入；管理页面是创建优惠券代码的地方。

定期金额切换

一个复选框，当客户启用它时，会将一次性付款转换为同一表单上的定期订阅。无需两个单独的表单即可实现“改为每月捐赠？”模式。

• 选项：标签、账单间隔（每日/每周/每月/每年）、发票限额。
• 需要：表单上已启用订阅。

费用回收切换

一个复选框，允许客户自愿承担 Stripe 交易费用，将收费金额增加一个计算出的数额，以便您收到完整的预期总额。

• 选项：标签、费用百分比、固定费用金额、默认状态（选中/未选中）。
• 适用于：非营利组织、捐赠表单、B2B 发票。

金额明细

一个只读显示字段，用于列出付款总额——明细项目、税费、手续费、优惠券和最终金额。随着客户与其它字段的交互而实时更新。

• 必需项： 使用税务功能收取税款的表单 — 请参阅 如何收取付款税款。没有此字段，客户在提交前将看不到税款明细项。
• 选项： 标签、项目显示偏好设置。

付款方式

渲染 Stripe 付款元素，客户在此输入卡详细信息、选择替代付款方式（ACH、SEPA、Klarna 等）或选择已保存的付款方式。

• 显示类型： 标签页（水平）或手风琴（堆叠）— 请参阅 如何选择付款方式显示类型。
• 可见项目： 使用手风琴时，控制显示多少种付款方式后出现“更多”按钮。默认值：5。
• 必需项： 每个现场付款表单。站外（Stripe Checkout）表单不使用此字段。

---

表单结构 / 显示字段

标题

在其他字段之间插入样式化的标题。用于对相关字段进行分组（“账单信息”、“活动详情”、“可选附加项”）。

• 选项： 标题文本、标题级别（H2–H6）。
• 注意：纯粹视觉效果 — 不收集或发送任何值到 Stripe。

文本

用于自由格式 HTML/文本的多行块。用于说明、服务条款文本、营销文案或感谢内容。

• 选项：正文内容（允许 HTML）。
• 注意：与标题一样，这仅用于展示。

下拉列表

一个 <select> 元素，您可以在其中定义可用选项。将所选值存储为表单元数据，可在客户记录和 Stripe 元数据中查看。

• 选项：标签、选项列表（标签/值对）、默认选择、必填切换。
• 适用于：“您从哪里得知我们？”，T 恤尺码，活动场次选择。

单选按钮

与下拉菜单具有相同的数据结构，但显示为单选按钮而不是 <select>。当您有 2-5 个选项并希望一次性全部显示时，此选项更佳。

• 选项：标签、选项列表、默认选择、必填切换。

---

提交触发器

每个表单必须包含以下两种按钮字段中的一种。它们是互斥的：表单类型（在常规选项卡中设置）决定了在选择器中显示哪一个。

付款按钮

现场付款表单（嵌入式或叠加式）的提交按钮。使用同一页面上的 Stripe 付款元素向客户收费。

• 选项：按钮文本、处理中文本（在请求进行时显示）。

结账按钮

站外 Stripe Checkout 表单的提交按钮。将客户重定向到 Stripe 的托管结账页面。

• 选项：按钮文本、处理中文本。

常见问题解答

为什么我在某些表单上看到付款按钮，而在其他表单上看到结账按钮？

按钮类型与常规选项卡中的表单类型相关联。现场表单使用付款按钮；站外（Stripe Checkout）表单使用结账按钮。在常规选项卡中切换类型会自动为您更换按钮字段。

我可以添加两次相同的字段类型吗？

某些字段可以添加多次（标题、文本、下拉菜单、单选按钮、日期）。其他字段在每个表单中只能使用一次，因为它们具有固定角色 — 您只能有一个电子邮件、一个价格选择器、一个付款方式字段、一个优惠券字段和一个提交按钮。选择器会使已在使用中的字段变灰。

自定义字段的数据去向何处？

自定义字段值将作为元数据保存在 Stripe PaymentIntent 或 Subscription 上。您可以在 Stripe Dashboard 的付款记录的元数据部分以及 WP Simple Pay 内的客户记录中查看它们。数据也可供网络钩子和 Uncanny Automator 等集成使用（请参阅如何使用自动化选项卡）。

字段值是否包含在收据电子邮件中？

是的 — 使用智能标签将任何自定义字段值插入电子邮件主题或正文中。请参阅使用智能标签。

为什么金额明细字段为空？

金额明细仅显示当前表单上的项目。如果您的表单没有税费、没有附加费用、未输入优惠券，并且只有一个价格选项，则明细将仅显示总计。当有需要列出的项目时，它会“活跃”起来。

我可以自定义字段验证规则吗？

内置字段强制执行合理的默认值（电子邮件验证为电子邮件格式，税务 ID 接受 Stripe 接受的格式等）。对于自定义验证逻辑，请使用 simpay_form_validation 过滤器 — 但大多数情况都已通过内置的必填切换和特定于字段的选项涵盖。

下一步是什么？

• 如何配置付款表单的字段和收集自定义数据 – 添加和排序字段的通用演练
• 如何收取付款税费 – 一起使用地址和金额明细字段
• 如何选择付款方式显示类型 – 配置付款方式字段