跳到主要內容

AddressForm

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

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

Props

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

Usage

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

標準帳單地址

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

包含完整地址的 AddressForm

tsx
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 元件來選擇。

Stripe 郵遞區號驗證

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

用於 Stripe 的 AddressForm

tsx
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} />;