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

Reusable react components for payment kit v2

# AddressForm

`AddressForm`コンポーネントは、請求先住所情報を収集するための構築済みUIを提供します。`react-hook-form`とシームレスに統合されており、郵便番号などのフィールドに対して国別の組み込みバリデーションが含まれています。

このコンポーネントは柔軟に設計されており、完全な住所の収集と、Stripeの郵便番号検証用の簡易バージョンの両方をサポートしています。

## Props

| Prop              | Type                               | Description                                                                                                                              | Default         |
| ----------------- | ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | --------------- |
| `mode`            | `string`                           | 表示するフィールドを決定します。`'required'`に設定すると、完全な住所フォーム（住所1、市区町村、都道府県、郵便番号、国）が表示されます。       | `undefined`     |
| `stripe`          | `boolean`                          | `true`の場合、郵便番号と国のみを含む簡易フォームを表示します。これは通常、Stripeでのカード検証に使用されます。             | `false`         |
| `sx`              | `SxProps`                          | ルートの`Stack`コンポーネントをカスタムスタイリングするためのMUIの`sx`プロパティです。                                                                        | `{}`            |
| `fieldValidation` | `Record<string, any>`              | 特定のフィールドに正規表現パターンなどのカスタムバリデーションルールを提供するためのオブジェクトです。詳細はバリデーションのセクションを参照してください。 | `{}`            |
| `errorPosition`   | `'right'` \| `'bottom'`             | 入力フィールドに対してバリデーションエラーメッセージをどこに表示するかを指定します。                                                      | `'right'`       |

## Usage

`AddressForm`は、フィールドの登録と状態管理のために`react-hook-form`のコンテキストに依存しているため、`FormProvider`内で使用する必要があります。

### 標準的な請求先住所

完全な請求先住所を収集するには、`mode`プロパティを`'required'`に設定します。これにより、すべての標準的な住所フィールドが、それぞれ`'required'`のバリデーションルールと共にレンダリングされます。

```tsx AddressForm with Full Address 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">
            Submit
          </Button>
        </Stack>
      </form>
    </FormProvider>
  );
}
```

この設定では、住所、市区町村、都道府県、郵便番号の入力フィールドがレンダリングされます。国は、統合された[CountrySelect](./components-ui-form-elements-country-select.md)コンポーネントを介して選択されます。

### Stripeの郵便番号検証

Stripeのような決済方法を使用する場合、カード検証に必要なのは郵便番号と国のみであることがよくあります。`stripe`プロパティを`true`に設定すると、これら2つのフィールドのみを含む簡易フォームがレンダリングされます。

```tsx AddressForm for Stripe 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">
            Submit
          </Button>
        </Stack>
      </form>
    </FormProvider>
  );
}
```

## バリデーション

このコンポーネントには、必須フィールドに対する自動バリデーションが含まれています。最も注目すべき機能は、動的な郵便番号バリデーションであり、選択された国に基づいてルールを調整します。

- **必須フィールド**: 表示されるすべてのフィールドは自動的に必須としてマークされます。
- **郵便番号**: バリデーションロジックは`validator/lib/isPostalCode`ライブラリを使用します。選択された国の標準形式（例：米国の場合は5桁、カナダの場合は英数字）に対して郵便番号の形式をチェックします。国の形式が明示的にサポートされていない場合は、一般的なバリデーションが適用されます。
- **カスタムバリデーション**: `fieldValidation`プロパティを介して追加のバリデーションルールを渡すことができます。例えば、`state`フィールドに特定のパターンを適用するには：

```tsx
const customValidation = {
  'billing_address.state': {
    pattern: '^[A-Z]{2}$',
    pattern_message: {
      en: '州は2文字のコードでなければなりません。',
    },
  },
};

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