表单元素 | ArcBlock

@blocklet/payment-react 库提供了一系列精细的输入组件，旨在简化自定义支付和联系信息表单的创建。这些元素在构建时充分考虑了验证和用户体验，能够与 react-hook-form 顺畅集成，为数据收集提供了一个强大而灵活的解决方案。

每个组件都被设计为一个独立的单元，让你可以将它们组合成满足你特定需求的复杂表单。以下是可用的表单元素概览。

AddressForm

一个预构建的表单，用于收集账单地址详情，并带有特定国家/地区的验证功能。

PhoneInput

一个国际电话号码输入框，集成了国家/地区代码选择器和验证功能。

CountrySelect

一个可搜索的下拉菜单，用于选择国家/地区，配有国旗和移动端友好的用户界面。

CurrencySelector

一个允许用户从可用选项中选择其偏好支付货币的组件。

通用使用模式

这些表单元素旨在与 react-hook-form 的 FormProvider 一起使用。你可以组合它们来构建全面的表单，以捕获交易所需的所有必要信息。虽然每个组件都有其自己的一套属性，但它们共享一个通用的集成模式。

下面是一个基本示例，展示了如何组合多个表单元素来创建一个用户信息表单：

MyCustomForm.tsx

import { FormProvider, useForm } from 'react-hook-form';
import { AddressForm, PhoneInput, CurrencySelector } from '@blocklet/payment-react';
import { Button, Stack } from '@mui/material';

// 假设 `availableCurrencies` 是从你的后端获取的
const availableCurrencies = [
  {
    id: 'usd_xxx',
    name: 'USD',
    symbol: 'USD',
    logo: 'url/to/usd_logo.png',
    method: { id: 'stripe', name: 'Stripe' },
  },
  // ... 其他货币
];

function MyCustomForm() {
  const methods = useForm({
    defaultValues: {
      currency: 'usd_xxx',
      phone_number: '',
      billing_address: {
        line1: '',
        city: '',
        state: '',
        postal_code: '',
        country: 'US', // 使用 ISO2 代码
      },
    },
  });

  const onSubmit = (data) => {
    console.log('表单数据已提交：', data);
  };

  return (
    <FormProvider {...methods}>
      <form onSubmit={methods.handleSubmit(onSubmit)}>
        <Stack spacing={2}>
          <CurrencySelector
            value={methods.watch('currency')}
            currencies={availableCurrencies}
            onChange={(currencyId) => methods.setValue('currency', currencyId)}
          />
          <PhoneInput name="phone_number" label="Phone Number" required />
          <AddressForm mode="required" stripe={false} />
          <Button type="submit" variant="contained">
            Submit
          </Button>
        </Stack>
      </form>
    </FormProvider>
  );
}

在此示例中，CurrencySelector、PhoneInput 和 AddressForm 组合在同一个表单中。CurrencySelector 用作与表单状态绑定的受控组件，而 PhoneInput 和 AddressForm 是非受控组件，它们会自动将其字段和验证规则注册到 react-hook-form 的上下文中。

后续步骤

要了解每个组件的具体属性和实现细节，请浏览它们各自的文档页面。

从 AddressForm 开始，了解如何收集账单信息。