@blocklet/payment-react/docs/components-ui-form-elements-address-form.zh-TW.md

Reusable react components for payment kit v2

# AddressForm

`AddressForm` 元件提供了一個預先建置的使用者介面，用於收集帳單地址資訊。它與 `react-hook-form` 無縫整合，並包含針對郵遞區號等欄位的內建、特定國家/地區的驗證。

此元件設計靈活，支援完整地址收集和用於 Stripe 郵遞區號驗證的簡化版本。

## Props

| Prop              | Type                               | Description                                                                                                                              | Default         |
| ----------------- | ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | --------------- |
| `mode`            | `string`                           | 決定要顯示的欄位。設定為 `'required'` 以顯示完整的地址表單（地址第一行、城市、州/省、郵遞區號、國家/地區）。       | `undefined`     |
| `stripe`          | `boolean`                          | 若為 `true`，則顯示一個僅包含郵遞區號和國家/地區的簡化表單，通常用於 Stripe 的卡片驗證。             | `false`         |
| `sx`              | `SxProps`                          | MUI 的 `sx` prop，用於對根 `Stack` 元件進行自訂樣式設定。                                                                        | `{}`            |
| `fieldValidation` | `Record<string, any>`              | 一個用於為特定欄位提供自訂驗證規則的物件，例如正規表示式模式。詳情請參閱驗證部分。 | `{}`            |
| `errorPosition`   | `'right'` \| `'bottom'`             | 指定相對於輸入欄位的驗證錯誤訊息顯示位置。                                                      | `'right'`       |

## Usage

`AddressForm` 必須在 `react-hook-form` 的 `FormProvider` 內使用，因為它依賴其上下文來註冊欄位和管理狀態。

### 標準帳單地址

若要收集完整的帳單地址，請將 `mode` prop 設定為 `'required'`。這將呈現所有標準地址欄位，每個欄位都帶有「必填」驗證規則。

```tsx 包含完整地址的 AddressForm icon=material-symbols:location-on-outline
import { FormProvider, useForm } from 'react-hook-form';
import { Button, Stack } from '@mui/material';
import AddressForm from './AddressForm'; // 調整匯入路徑

export default function FullAddressExample() {
  const methods = useForm({
    defaultValues: {
      billing_address: {
        line1: '',
        city: '',
        state: '',
        postal_code: '',
        country: 'US', // 預設國家/地區
      },
    },
  });

  const onSubmit = (data) => {
    console.log('Form data:', data);
  };

  return (
    <FormProvider {...methods}>
      <form onSubmit={methods.handleSubmit(onSubmit)}>
        <Stack spacing={2}>
          <AddressForm mode="required" />
          <Button type="submit" variant="contained">
            提交
          </Button>
        </Stack>
      </form>
    </FormProvider>
  );
}
```

此設定會呈現地址、城市、州/省和郵遞區號的輸入欄位。國家/地區是透過整合的 [CountrySelect](./components-ui-form-elements-country-select.md) 元件來選擇。

### Stripe 郵遞區號驗證

當使用像 Stripe 這樣的支付方式時，通常只需要郵遞區號和國家/地區進行卡片驗證。將 `stripe` prop 設定為 `true`，以呈現僅包含這兩個欄位的簡化表單。

```tsx 用於 Stripe 的 AddressForm icon=logos:stripe
import { FormProvider, useForm } from 'react-hook-form';
import { Button, Stack } from '@mui/material';
import AddressForm from './AddressForm'; // 調整匯入路徑

export default function StripeAddressExample() {
  const methods = useForm({
    defaultValues: {
      billing_address: {
        postal_code: '',
        country: 'US', // 預設國家/地區
      },
    },
  });

  const onSubmit = (data) => {
    console.log('Form data:', data);
  };

  return (
    <FormProvider {...methods}>
      <form onSubmit={methods.handleSubmit(onSubmit)}>
        <Stack spacing={2}>
          <AddressForm stripe={true} />
          <Button type="submit" variant="contained">
            提交
          </Button>
        </Stack>
      </form>
    </FormProvider>
  );
}
```

## 驗證

該元件包含對必填欄位的自動驗證。最顯著的特點是動態郵遞區號驗證，它會根據所選國家/地區調整其規則。

- **必填欄位**：所有可見欄位都會自動標記為必填。
- **郵遞區號**：驗證邏輯使用 `validator/lib/isPostalCode` 函式庫。它會根據所選國家/地區的標準格式（例如，美國為 5 位數字，加拿大為字母數字）來檢查郵遞區號格式。如果某個國家/地區的格式未被明確支援，則會套用通用驗證。
- **自訂驗證**：您可以透過 `fieldValidation` prop 傳遞額外的驗證規則。例如，若要對 `state` 欄位強制執行特定模式：

```tsx
const customValidation = {
  'billing_address.state': {
    pattern: '^[A-Z]{2}$',
    pattern_message: {
      en: '州/省必須是 2 個字母的代碼。',
    },
  },
};

<AddressForm mode="required" fieldValidation={customValidation} />;
```