# gt-next: General Translation Next.js SDK: RegionSelector
URL: https://generaltranslation.com/zh/docs/next/api/components/region-selector.mdx
---
title: RegionSelector
description: RegionSelector 组件的 API 参考文档
---

{/* 自动生成：请勿直接编辑。请改为编辑 content/docs-templates/ 中的模板。 */}


## 概述

`<RegionSelector>` 组件是一个下拉列表，用于让用户选择所在区域。
它是一个客户端组件，会从 [`<GTProvider>` 上下文](/docs/next/api/components/gtprovider) 中读取区域数据。

## 参考

### 返回值

一个允许用户选择其区域的 `<select>` 元素；如果没有可用区域，则返回 `null`。

### 属性

| Prop                            | 类型          | 默认值     | 说明                                                                                             |
| ------------------------------- | ----------- | ------- | ---------------------------------------------------------------------------------------------- |
| `regions`                       | `string[]`  | —       | 可选的 ISO 3166 地区代码数组 (例如 `['US', 'CA', 'GB']`) ，用于指定要显示的区域。若未提供，则会根据受支持的区域设置推断出区域。              |
| `placeholder`                   | `ReactNode` | —       | 可选的占位内容，在未选择任何区域时作为第一个选项显示。                                                                    |
| `customMapping`                 | `object`    | —       | 可选的映射，用于将地区代码映射到自定义显示名称、表情符号或关联的区域设置。值可以是字符串 (显示名称) ，也可以是包含 `name`、`emoji` 和/或 `locale` 属性的对象。 |
| `prioritizeCurrentLocaleRegion` | `boolean`   | `true`  | 如果为 true，则列表中会优先显示与当前区域设置对应的区域。                                                                |
| `sortRegionsAlphabetically`     | `boolean`   | `true`  | 如果为 true，则会按显示名称的字母顺序对区域进行排序。                                                                  |
| `asLocaleSelector`              | `boolean`   | `false` | 如果为 true，选择某个区域时，也会将区域设置更新为该区域关联的区域设置。                                                         |

其他属性会透传给底层的 `<select>` 元素。

## 示例

### 基本用法

```jsx title="MyComponent.jsx" copy
import { RegionSelector } from 'gt-next';

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


### 结合自定义映射和占位符

```jsx title="CustomRegion.jsx" copy
import { RegionSelector } from 'gt-next';

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: "🇬🇧" },
      }}
    />
  );
}
```

***


## 注意

* `<RegionSelector>` 组件仅可在客户端使用。
* 如需完全自定义区域选择器 UI，请使用 [`useRegionSelector`](/docs/next/api/helpers/use-region-selector) Hook。

## 下一步

* 请参阅 [`useRegionSelector`](/docs/next/api/helpers/use-region-selector)，了解如何构建自定义区域选择器。
* 请参阅 [`useRegion`](/docs/next/api/helpers/use-region)，了解如何读取当前区域。
* 请参阅 [`<LocaleSelector>`](/docs/next/api/components/locale-selector)，了解对应的区域设置选择器。