@additionapps/polaris-form-builder 中文文档教程

Question

Polaris Form Builder

使用简单的配置对象在 Shopify Polaris 应用程序中构建表单。

此包使您能够在 Shopify 应用程序中构建复杂的表单，而无需加载混乱的模板样板。 只需将您想要在表单上的字段配置为纯 javascript 数组，表单生成器将负责显示字段和更新值。

它支持大多数开箱即用的基本 Polaris 表单字段组件，还可以处理自定义字段、分组字段、可重复字段和一些其他附加功能。 让我们开始吧！

Contents

• Installation
• Example usage
• Configuring a Form Builder
• Defining Fields
• Error handling
• Dynamic fields
• Custom fields
• Examples

Installation

您可以通过 NPM 安装此包：

npm install @additionapps/polaris-form-builder

请注意，此包要求您的应用程序使用 Shopify Polaris 版本 4.* 或更高版本。

Example usage

使用表单生成器是一个三步过程。

首先，配置您希望显示的表单。 这是一个包含字段对象的简单 javascript 数组：

// In MyForm.js
export const fields = [
    {
        key: "title",
        input: "text",
        config: {
            name: "title",
            label: "Product title",
            placeholder: "Product title",
        },
    },
    {
        key: "description",
        input: "text",
        config: {
            name: "description",
            label: "Product description",
            placeholder: "Product description",
        },
    },
];

接下来我们将定义我们的模型 - 我们希望表单与之交互的数据 - 以及设置此数据的方法。 我们将使用 React 功能组件作为示例：

// In MyComponent.jsx
export const MyComponent = () {
    const [model, setModel] = useState({
        title: null,
        description: null,
    });

    return (
        //...
    );
}

现在，剩下要做的就是配置我们的 Form Builder：

import { fields } from './MyForm';
import { PolarisFormBuilder} from '@additionapps/polaris-form-builder;

export const MyComponent = () {
    const [model, setModel] = useState({
        title: null,
        description: null,
    });

    return (
        <PolarisFormBuilder
            model={model}
            fields={fields}
            onModelUpdate={setModel}
        ></PolarisFormBuilder>
    );
}

就是这样！ 表单生成器将负责显示您的表单字段，并在字段中的值发生变化时更新您的模型。 你可以在这里看到这个简单的例子：

href="https://codesandbox.io/s/simple-demo-fx8nq?file=/SimpleDemoForm.jsx">Polaris Form Builder - simple demo

Polaris Form Builder - 厨房水槽演示

---

Configuring a Form Builder

配置表单生成器时可用的选项比上面简单示例中显示的要多。 以下是可用的道具：

fields

必需。 包含要在表单上显示的每个字段的配置对象的数组。 请参阅定义字段。

model

必需。 封装表单将与之交互的数据的对象。 此对象上的每个键都应对应于表单字段配置数组中某个字段的 key 属性。

onModelUpdate

必需。 当任何表单字段中的输入发生变化时，接受更新模型作为其唯一参数的函数。

units

可选。 包含与应在某些表单字段中使用的单位相关的配置的对象。 此对象中的键都是可选的，包括：

• locale: The string representing the desired language as defined in BCP 47 . If not supplied, the locale will be automatically derived via navigator.language.
• currency: The three-letter currency code as defined by ISO 4217]. If not supplied the currency will be derived automatically based on the locale.
• weight: One of g (grams), kg (kilograms), oz (ounces) or lb (pounds).

errors

可选。 验证错误消息的对象。 该对象的键应该是错误所指字段的点符号路径，值是错误消息本身。 示例：

const errors = {
  'title' : 'The title field is required',
  'things.0.summary' => 'A thing must have a summary'
}

onErrorUpdate

可选。 接受更新的错误对象作为其唯一参数的函数。 当有错误的字段接收到新输入时，错误将从提供的 errors 对象中删除。 此回调函数允许消费组件对此更改做出反应。 有关详细信息，请参阅错误处理。

focus

可选。 一个字符串，描述指向应关注的字段的点符号路径。 这在处理错误 或动态表单字段时很有用。

onFocusUpdate

可选。 一个函数，它接受一个字符串作为其唯一参数，该字符串描述最近关注的字段的点符号路径。 这在处理错误 或动态表单字段 时很有用。

---

Defining fields

传递给 Form Builder 的 fields 属性是一个对象数组，每个对象都配置表单中的一个字段。

所有字段对象至少应具有以下三个必需属性：

key - 与您传​​递给 Form Builder 的模型上的属性相匹配的字符串

input - 对应的字符串为内置字段类型之一或自定义字段类型（请参阅自定义字段）。 内置字段类型是：

• checkbox
• choice
• group
• money
• percentage
• range
• repeater
• select
• text
• weight

config - 允许您根据 Polaris 文档配置底层 Polaris 字段组件的对象。

所有字段也有一些可选键：

• warning - accepts a string as a value. If this is present a yellow warning banner will display below the input with the string specified.
• defaultValue - For use with subfields only. Accepts a string or number as a value.

某些字段需要指定其他选项。 各字段要求如下：

checkbox

该字段对应Shopify Polaris Checkbox字段。

最低配置：

{
  key: "my_checkbox_field",
  input: "checkbox",
  config: {
    // required by Polaris component
    label: "Do you agree?"
  }
}

config 对象可以包含 Shopify Polaris Checkbox 文档，除了 checked、error 和 onChange，因为它们由 Form Builder 处理。

choice

此字段对应于 Shopify Polaris Choice List 字段。

最低配置：

{
  key: "my_checkbox_or_radio_list_field",
  input: "choice",
  config: {
    // required by Polaris component
    title: "Select some things",
    choices: [
      // { label: "Thing One", value: "one" },
      // { label: "Thing Two", value: "two" },
    ]
  }
}

config 对象可以包含 Shopify Polaris Choice List 文档，但 selected、error 和 onChange 除外，因为它们由 Form Builder 处理。

group

group 字段是一个容器，可以并排显示两个或多个子字段。

最低配置：

{
    // The key for a group field does not correspond
  // to a property in your data model.  Prefixed here
  // with an underscore to make this more apparent
  key: "_my_group_field",
  input: "group",
  layout: 'condensed',
  subFields: [
    // Child field configuration objects
  ]
}

layout 键确定 group 应该使用压缩还是常规 Shopify Polaris 表单布局。 如果省略此键，将使用常规表单布局组。 如果该值设置为 condensed，将使用压缩形式布局组。

subFields 数组可以包含任何内置或自定义字段类型的配置对象。

money

该字段允许以货币的最低面额（例如美分、便士等）保留货币值。 通过将 units 对象传递给表单生成器来指定货币 - 请参阅配置表单生成器。

该值将显示为浮点数或整数 - 适用于货币 - 当字段获得焦点时，将显示基于区域设置的值的格式化表示（再次通过 units 指定）表单生成器上的道具）。

为了进行说明，我们假设一个 Form Builder 实例使用 GBP 作为货币，使用 en-GB 作为语言环境。 如果用户在货币字段中输入 10.45，则数据模型中保存的值将为 1045，并且在模糊时，该字段将显示 £10.45。

最低配置：

{
  key: "my_money_field",
  input: "money",
  config: {
    // required by Polaris component
    label: "Price",
  }
}

config 对象可以包含 Shopify Polaris 文本字段中定义的任何道具 文档，除了 value、error、focused、onChange、onFocus和 onBlur，因为它们由 Form Builder 处理。

simple_money

该字段是 money 字段的更基本版本。 它本质上是一个带有前缀的 text 字段，显示 units 属性中指定的货币。 不对输入执行额外的检查或格式化 - 假设您的应用程序后端负责验证和处理输入，并且传递给该字段的值采用正确的格式。

最低配置：

{
  key: "my_simple_money_field",
  input: "simple_money",
  config: {
    // required by Polaris component
    label: "How much is it worth?",
  }
}

config 对象可以包含 Shopify Polaris 文本字段中定义的任何道具 文档，除了 value、error、focused、onFocus 和 onChange因为这些是由 Form Builder 处理的。

percentage

该字段允许将百分比值保留为小数。 该值将在聚焦时显示为更人性化的百分比，并将显示基于语言环境的百分比的格式化版本（这是通过表单生成器上的 units 属性指定的 - 请参阅配置表单生成器）。

为了进行说明，我们假设一个 Form Builder 实例使用 en-GB 作为语言环境。 如果用户在百分比字段中输入 25，则数据模型中保存的值将为 0.25，并且在模糊时，该字段将显示 25 %。

最低配置：

{
  key: "my_percentage_field",
  input: "percentage",
  config: {
    // required by Polaris component
    label: "What percentage?",
  }
}

config 对象可以包含 Shopify Polaris 文本字段中定义的任何道具 文档，除了 value、error、focused、onChange、onFocus和 onBlur，因为它们由 Form Builder 处理。

range_slider

此字段对应于 Shopify Polaris Range Slider 字段。

最低配置：

{
  key: "my_slider_field",
  input: "range_slider",
  config: {
    // required by Polaris component
    label: "What value?"
  }
}

config 对象可以包含 Shopify Polaris Range Slider 中定义的任何道具 文档，但 value、error 和 onChange 除外，因为它们由 Form Builder 处理。

repeater

repeater 字段使处理模型数据中的对象数组成为可能。 例如：

const data: {
  my_repeater_field: [
    { title: 'Foo', description: 'Bar' },
    { title: 'Baz', description: 'Qux' },
  ]
}

转发器字段将为用户提供添加和删除数据行的控件。

最低配置：

{
  key: "my_repeater_field",
  input: "repeater",
  emptyMessage: "No people added",
  addButtonText: "Add person",
  layout: 'stacked',
  title: 'My repeater field', //optional
  minRows: 1, //optional
  maxRows: 5, //optional
  subFields: [
    // Child field configuration objects
  ]
}

emptyMessage 属性是必需的，当转发器字段没有行时将显示。

addButtonText 属性确定显示在用于添加新行的按钮上的文本。 此属性是可选的 - 如果缺少该按钮将显示“添加行”。

title 属性将在转发器字段上方添加一个副标题。 此属性是可选的 - 如果缺少，则不会显示任何标题。

minRows 和 maxRows 属性将确保转发器不能少于或多于指定的项目数。 一旦达到这些限制，将不会显示添加/删除按钮。 这些属性是可选的，可以独立设置。

layout 属性决定子字段的显示方式。 这可以是以下三个值之一：stacked、grouped 或 condensed。 这些选项对应于三个不同的 Shopify Polaris 表单布局 选项。 此属性是可选的 - 如果缺少布局将被堆叠。

subFields 数组可以包含任何内置或自定义字段类型（包括其他转发器字段）的配置对象。

select

此字段对应于 Shopify Polaris 选择字段 字段。

最低配置：

{
  key: "my_select_field",
  input: "select",
  config: {
    // required by Polaris component
    label: "Choose a thing",
    options: [
      // { label: "Thing One", value: "one" },
      // { label: "Thing Two", value: "two" },
    ]
  }
}

config 对象可以包含 Shopify Polaris Select Field 文档，但 value、error 和 onChange 除外，因为它们由 Form Builder 处理。

simple_money

该字段是 money 字段的更基本版本。 它本质上是一个带有前缀的 text 字段，显示 units 属性中指定的货币。 不对输入执行额外的检查或格式化 - 假设您的应用程序后端负责验证和处理输入，并且传递给该字段的值采用正确的格式。

最低配置：

{
  key: "my_simple_money_field",
  input: "simple_money",
  config: {
    // required by Polaris component
    label: "How much is it worth?",
  }
}

config 对象可以包含 Shopify Polaris 文本字段中定义的任何道具 文档，除了 value、error、focused、onFocus 和 onChange因为这些是由 Form Builder 处理的。

simple_weight

此字段是 weight 字段的更基本版本。 它本质上是一个 text 字段，带有一个后缀，显示 units 属性中指定的重量单位。 不对输入执行额外的检查或格式化 - 假设您的应用程序后端负责验证和处理输入，并且传递给该字段的值采用正确的格式。

最低配置：

{
  key: "my_simple_weight_field",
  input: "simple_weight",
  config: {
    // required by Polaris component
    label: "How much does it weigh?",
  }
}

config 对象可以包含 Shopify Polaris 文本字段中定义的任何道具 文档，除了 value、error、focused、onFocus 和 onChange因为这些是由 Form Builder 处理的。

text

此字段对应于 Shopify Polaris 文本字段 字段。

最低配置：

{
  key: "my_text_field",
  input: "text",
  config: {
    // required by Polaris component
    label: "Choose a thing",
  }
}

config 对象可以包含 Shopify Polaris 文本字段中定义的任何道具 文档，除了 value、error、focused、onFocus 和 onChange因为这些是由 Form Builder 处理的。

weight

该字段允许以克为单位保留重量值，同时让用户根据提供的重量单位输入值（这是通过表单生成器上的 units 属性指定的 - 请参阅配置表单生成器）。

为了说明，我们假设一个 Form Builder 实例使用 kg 作为重量单位。 如果用户在权重字段中输入 5，则数据模型中保存的值将为 5000。

最低配置：

{
  key: "my_weight_field",
  input: "weight",
  config: {
    // required by Polaris component
    label: "What weight?",
  }
}

config 对象可以包含 Shopify Polaris Text Field 文档，除了 value、error、focused< /code>、onChange、onFocus 和 onBlur，因为它们由 Form Builder 处理。

Note for TypeScript users

内置字段从 Polaris 字段接口扩展而来。 因此，您应该确保为 config 对象中的底层 Polaris 字段提供所有 必需的道具。

在实践中，这通常意味着为您的字段提供一个 value（或者在类似选择的字段的情况下，您需要指定一个 selected 属性）。 通常您可以将其设置为 null - Form Builder 将在生成字段时覆盖它。 示例：

import Field from '@additionapps/polaris-form-builder;

const fields: Field[] = [
  {
    key: "my_text_field",
    input: "text",
    config: {
      // Both label and value are required
        // by Polaris component
      label: "Choose a thing",
      value: null
    }
  }
]

---

Error handling

Form Builder 可以负责显示通过 errors 属性传递给 PolarisFormBuilder 组件的表单验证错误。

通常有两种表单验证方法：

• Validation on form submission - the server sends back a set of validation errors for the form which are then displayed to the user
• Validation on input - the data model is checked as it is updated to ensure that it matches a set of validation requirements that are defined in JavaScript.

让我们看看表单构建器如何处理这些方法：

Validation on form submission

在提交表单时，您的应用程序通常会生成一个 XMLHttpRequest 并接收来自服务器的响应。 如果存在验证错误，这些错误将作为对象发回，然后可以将其传递到 Form Builder 实例中。

Form Builder 期望错误对象具有与您的数据模型中具有无效值的键相对应的键。 这些键应该使用点表示法来定位模型键，它们嵌套在数组中，例如：

const errors = {
  'title' : 'The title field is required',
  'things.0.summary' => 'A thing must have a summary'
}

当显示错误的字段接收到新输入时，Form Builder 实例将从错误对象中删除该项目。 为了保持父组件的状态与 Form Builder 同步，可以向 Form Builder 提供一个 onErrorUpdate 回调函数。 此方法将从 Form Builder 接收更新的错误对象，然后可以将其应用于父组件状态。

表单生成器还接受一个 focus 属性和一个 onFocusUpdate 回调方法。 此回调方法有助于确保在错误更新和表单构建器重新呈现时字段焦点不会丢失在文本（或类似文本）字段中。 这是一个示例：

Polaris Form Builder - 验证提交演示

注意 - 对于仅在表单提交时使用验证且不接受动态字段或动态单元的简单表单，无需使用这些事件回调来管理错误和焦点 - 表单生成器将在内部跟踪错误的更改。

Validation on input

为了方便您的用户，您可能希望在他们与您的表单交互时提供验证反馈。 表单生成器可以与对象验证器集成，例如流行的 Yup 库。

这是一个使用此库的简单示例，用于演示输入验证：

Polaris Form Builder - 输入演示验证

Dynamic fields

表单中的一个常见要求是字段根据用户的输入向用户呈现不同的选项或字段。 例如，如果用户在 country 字段中选择“United States”，他们应该会在 states 字段中看到美国各州的列表。 如果他们随后选择另一个 country，他们应该看到一组不同的 states。

因为字段被定义为 JavaScript 数组，所以您可以在将其传递到 Form Builder 之前根据需要对其进行操作。 通常，这将涉及从您的模型中获取一个或多个值，并映射到您的表单配置中的字段，以根据这些值根据需要操作它们。

为了使这个过程更容易一些，您可以使用 transformFields 实用程序方法，该方法接受字段配置选项数组作为第一个参数，以及一个定义数组中每个字段应如何操作的回调。

如果 Form Builder 检测到传递给它的字段发生变化，它将重新呈现。

这是一个示例：

Polaris Form Builder - 动态字段演示< /a>

Custom fields

虽然内置字段类型将涵盖大多数用例，但在某些情况下可能需要自定义字段类型。

表单生成器接受可选的 customFields 道具。 这个 prop 应该传递一组功能性的 React 组件，每个组件都是一个自定义字段类型。

您可以在此处查看使用自定义字段类型的表单生成器示例：

Polaris Form Builder - 自定义字段演示

关于创建自定义字段的一些注意事项：

Naming

React 功能组件的名称应为 Pascal 大小写，并以单词 Field 为后缀。 在您的表单配置中定义字段时，将使用此名称的蛇形大小写形式（不带字段后缀）。 例如，如果您的自定义字段组件是 CustomColourField，您应该在表单配置中将此字段类型称为 input: 'custom_colour'。

Props

您的字段应该接受四个属性 - field、state、actions 和 ancestors：

• field - the configuration object for the field, as defined in your form config.
• state - an object representing the current internal state of the Form Builder instance. There are several properties on this object:
  • model - the current state of the model, passed into the Form Builder.
  • fields - the full form config object.
  • errors - the current state of any errors passed into the Form Builder.
  • focus - a dot notation path for the most recently focused field.
  • inputs - an array of input types currently registered on the current Form Builder instance. This will include all the built-in field types and any custom fields passed into the form builder.
  • units - an object with information about the units that should be used to display certain field values.
• actions - an object holding a number of methods used to manage the state of the form builder. Relevant methods:
  • updateField(value, field, ancestors) - used to update the model with the new value. This method is typically invoked when the field receives input.
  • setFocus(field, ancestors) - used to keep track of the most recently focused form field. This is typically used for text-like fields and in usually invoked on field focus.
• ancestors - an array of ‘field parent’ objects that helps to determine the position of a field within the model. This value typically won’t be interacted with directly but will be passed to actions like updateField and setFocus

Examples

本自述文件包含许多实时为方便起见再次在下面列出的示例：

• Simple demo
• Kitchen sink demo
• Validation on form submit
• Validation on input
• Dynamic form fields
• Custom fields

---

Changelog

请参阅 CHANGELOG 了解更多信息最近发生了什么变化。

Contributing

有关详细信息，请参阅CONTRIBUTING。

Security

如果您发现任何与安全相关的问题，请发送电子邮件至 john@addition.com.au 而不是使用问题跟踪器。

Treeware

您可以自由使用此包，但如果它适用于您的生产环境，我们将非常感谢您为世界购买或种植一棵树。

现在众所周知，应对气候危机和防止气温上升超过 1.5 摄氏度的最佳工具之一是植树。 如果您为我的森林做出贡献，您将为当地家庭创造就业机会并恢复野生动物栖息地。

您可以在 Offset Earth 购买树木 在 Treeware

阅读更多关于 Treeware 的信息a>

Credits

约翰·威尔斯 所有贡献者

License

MIT 许可证 (MIT)。 请参阅许可证文件文件以获取更多信息。