@blocklet/payment-react/docs/components-ui-form-elements-country-select.zh.md

Reusable react components for payment kit v2

# CountrySelect

`CountrySelect` 组件提供了一个用户友好的国家选择下拉菜单。它具有可搜索列表、显示国旗，并提供响应式设计，可适应桌面和移动设备。该组件设计用于在 `react-hook-form` 管理的表单中使用。

## Props

| Prop | Type | Description | Required | Default |
|---|---|---|---|---|
| `value` | `CountryIso2` | 所选国家的 ISO2 代码（例如，'us'）。 | 是 | |
| `onChange` | `(value: CountryIso2) => void` | 选择国家时调用的回调函数。 | 是 | |
| `name` | `string` | 输入的 name 属性，用于与 `react-hook-form` 集成。 | 是 | |
| `sx` | `SxProps` | 应用于根元素的自定义样式。 | 否 | `{}` |
| `showDialCode` | `boolean` | 如果为 `true`，国家的电话区号将与其名称一起显示在列表中。 | 否 | `false` |

## 基本用法

要使用 `CountrySelect` 组件，您必须将其包装在 `react-hook-form` 的 `FormProvider` 中。组件的状态应通过表单上下文进行管理。

```tsx Basic CountrySelect Example icon=logos:react
import { FormProvider, useForm } from 'react-hook-form';
import { Box, Button, Typography } from '@mui/material';
import CountrySelect from '@blocklet/payment-react/src/components/country-select'; // Adjust path as needed
import type { CountryIso2 } from 'react-international-phone';

export default function BasicCountrySelect() {
  const methods = useForm<{ country: CountryIso2 }>({
    defaultValues: {
      country: 'us',
    },
  });

  const { handleSubmit, watch, setValue } = methods;
  const countryValue = watch('country'); // Watch for changes to update the controlled component

  const onSubmit = (data: { country: CountryIso2 }) => {
    alert(`Form submitted with country: ${data.country}`);
  };

  return (
    <FormProvider {...methods}>
      <form onSubmit={handleSubmit(onSubmit)}>
        <Box sx={{ display: 'flex', flexDirection: 'column', gap: 2, maxWidth: 400 }}>
          <Typography variant="h6">Select Your Country</Typography>
          <CountrySelect
            name="country"
            value={countryValue}
            onChange={(newCountry) => {
              setValue('country', newCountry, { shouldValidate: true });
            }}
          />
          <Button type="submit" variant="contained">
            Submit
          </Button>
          <Typography>
            Current form value: {countryValue}
          </Typography>
        </Box>
      </form>
    </FormProvider>
  );
}
```

## 功能

### 搜索和筛选
组件在下拉列表顶部包含一个搜索栏，允许用户通过国家名称、ISO2 代码或电话区号快速查找国家。例如，搜索“+1”将显示美国和加拿大。

### 响应式 UI
在桌面设备上，`CountrySelect` 渲染为标准下拉菜单。在移动设备上，它会转变为一个从屏幕底部滑出的全宽对话框，为小型设备提供优化的用户体验。

### 键盘可访问性
`CountrySelect` 支持完整的键盘导航。用户可以使用 `ArrowUp` 和 `ArrowDown` 键在列表中导航，使用 `Enter` 键选择国家，使用 `Escape` 键关闭下拉列表。`Tab` 和 `Shift+Tab` 也可以在列表项之间循环切换。

### 表单集成
设计用于与 `react-hook-form` 无缝协作。当做出选择时，它会自动更新表单状态，因此需要将其包装在 `FormProvider` 中。

## 高级用法

### 显示电话区号

您可以通过将 `showDialCode` 属性设置为 `true` 来在列表中显示每个国家的电话区号。

```tsx CountrySelect with Dial Code icon=logos:react
import { FormProvider, useForm } from 'react-hook-form';
import { Box, Button } from '@mui/material';
import CountrySelect from '@blocklet/payment-react/src/components/country-select'; // Adjust path as needed
import type { CountryIso2 } from 'react-international-phone';

export default function CountrySelectWithDialCode() {
  const methods = useForm<{ country: CountryIso2 }>({
    defaultValues: {
      country: 'gb',
    },
  });

  const { handleSubmit, watch, setValue } = methods;
  const countryValue = watch('country');

  const onSubmit = (data: { country: CountryIso2 }) => {
    alert(`Form submitted with country: ${data.country}`);
  };

  return (
    <FormProvider {...methods}>
      <form onSubmit={handleSubmit(onSubmit)}>
        <Box sx={{ display: 'flex', flexDirection: 'column', gap: 2, maxWidth: 400 }}>
          <CountrySelect
            name="country"
            value={countryValue}
            onChange={(newCountry) => setValue('country', newCountry)}
            showDialCode={true}
          />
          <Button type="submit" variant="contained">
            Submit
          </Button>
        </Box>
      </form>
    </FormProvider>
  );
}
```

## 后续步骤

该组件是构建更复杂表单元素的基础。请参阅它如何集成到 [PhoneInput](./components-ui-form-elements-phone-input.md) 组件中，以创建一个完整的国际电话号码字段。