# General Translation React SDKs (gt-react, gt-next): RegionSelector
URL: https://generaltranslation.com/zh/docs/react/reference/components/region-selector.mdx
---

title: RegionSelector
description: 使用 General Translation gt-react 渲染用于切换当前活动 地区 的 dropdown。RegionSelector 的 API 参考。

---

`<RegionSelector>` 组件会渲染一个 dropdown，让用户可以切换当前活动的 地区。它是一个 客户端 组件，会从 [`<GTProvider>`](/docs/react/reference/components/gt-provider) 上下文中读取 地区 数据。

*可在 `gt-react` 和 `gt-next` 中使用。示例从 `gt-react` 导入；请改为从你所使用框架对应的包中导入。*

*注意：`gt-tanstack-start` 和 `gt-react-native` 不导出此组件。*

## 概览 [#overview]

在 provider 中渲染 `<RegionSelector>`。如果不传入任何属性，它会根据支持的区域设置推断地区。

```tsx
import { RegionSelector } from 'gt-react';

export default function MyComponent() {
  return <RegionSelector />;
}
```

*注意：`<RegionSelector>` 仅可在客户端使用，会渲染一个 `<select>` 元素 (如果没有可用地区，则返回 `null`) 。如果需要完全自定义的切换器，请使用 [`useRegionSelector`](/docs/react/reference/hooks/use-region-selector) 钩子。*

## 工作原理 [#how-it-works]

* **读取上下文。** 默认情况下，regions 会根据 `<GTProvider>` 上下文中支持的区域设置推断。传入 `regions` 可显示一组指定区域。
* **切换区域。** 选择某个选项会设置当前区域。使用 `asLocaleSelector` 时，还会将区域设置同步更新为该区域关联的区域设置。
* **透传属性。** 任何额外属性都会转发给底层的 `<select>` 元素。

## 属性 [#props]

| 属性                                             | 描述                     | 类型          | 可选 | 默认值     |
| ---------------------------------------------- | ---------------------- | ----------- | -- | ------- |
| [`regions`](#regions)                          | 要显示的 ISO 3166 地区代码子集。  | `string[]`  | 是  | 自动推断    |
| [`placeholder`](#placeholder)                  | 第一个选项的占位内容。            | `ReactNode` | 是  | —       |
| [`customMapping`](#custom-mapping)             | 为各地区自定义显示名称、表情符号或区域设置。 | `object`    | 是  | —       |
| [`prioritizeCurrentLocaleRegion`](#prioritize) | 将当前区域设置对应的地区置于首位。      | `boolean`   | 是  | `true`  |
| [`sortRegionsAlphabetically`](#sort)           | 按显示名称的字母顺序对地区排序。       | `boolean`   | 是  | `true`  |
| [`asLocaleSelector`](#as-locale-selector)      | 选择地区时也会更新区域设置。         | `boolean`   | 是  | `false` |

### `regions` [#regions]

**类型** `string[]` · **可选** · **默认值** 自动推断

要显示的 ISO 3166 地区代码数组，例如 `['US', 'CA', 'GB']`。省略时，会根据支持的区域设置自动推断这些地区代码。

### `placeholder` [#placeholder]

**类型** `ReactNode` · **可选**

未选择地区时显示为第一个选项的占位内容。

### `customMapping` [#custom-mapping]

**类型** `object` · **可选**

用于将地区代码映射到自定义显示数据。每个值都可以是字符串 (显示名称) ，也可以是包含 `name`、`emoji` 和/或 `locale` 属性的对象。

### `prioritizeCurrentLocaleRegion` [#prioritize]

**类型** `boolean` · **可选** · **默认值** `true`

当为 `true` 时，与当前区域设置对应的地区会优先显示在列表顶部。

### `sortRegionsAlphabetically` [#sort]

**类型** `boolean` · **可选** · **默认值** `true`

当为 `true` 时，地区将按显示名称的字母顺序排序。

### `asLocaleSelector` [#as-locale-selector]

**类型** `boolean` · **可选** · **默认值** `false`

当为 `true` 时，选择某个地区也会将区域设置更新为与该地区关联的区域设置。

## 示例 [#examples]

```tsx title="MyComponent.tsx"
import { RegionSelector } from 'gt-react';

export default function MyComponent() {
  return <RegionSelector />;
}
```

```tsx title="CustomRegion.tsx"
import { RegionSelector } from 'gt-react';

export default function CustomRegion() {
  return (
    <RegionSelector
      regions={['US', 'CA', 'GB']}
      placeholder="Select a region"
      customMapping={{
        US: { name: 'United States', emoji: '🇺🇸' },
        CA: { name: 'Canada', emoji: '🇨🇦' },
        GB: { name: 'United Kingdom', emoji: '🇬🇧' },
      }}
    />
  );
}
```

## 注意事项 [#notes]

* `<RegionSelector>` 仅可在客户端使用。
* 要读取当前生效的 地区，请使用 [`useRegion`](/docs/react/reference/hooks/use-region)；要构建自定义选择器，请使用 [`useRegionSelector`](/docs/react/reference/hooks/use-region-selector)。
* 对应的区域设置版本，请参见 [`<LocaleSelector>`](/docs/react/reference/components/locale-selector)。