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

title: useRegionSelector
description: 使用 General Translation gt-react 构建自定义区域切换器。useRegionSelector API 参考。

---

`useRegionSelector` 钩子会返回构建自定义区域选择器所需的数据和处理函数：当前活动区域、可用区域、区域元数据，以及更新区域或区域设置的函数。

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

*注意：`gt-next` 和 `gt-tanstack-start` 不导出此项。*

## 概览 [#overview]

调用 `useRegionSelector`，并将其返回值接入你自己的 UI。

```tsx
'use client';
import { useRegionSelector } from 'gt-react';

export default function CustomRegionSelector() {
  const { region, setRegion, regions, regionData } = useRegionSelector({ // [!code highlight]
    customMapping: { US: { name: 'United States', emoji: '🇺🇸' } }, // [!code highlight]
  });

  return (
    <select value={region} onChange={(e) => setRegion(e.target.value)}>
      {regions.map((r) => (
        <option key={r} value={r}>
          {regionData.get(r)?.emoji} {regionData.get(r)?.name}
        </option>
      ))}
    </select>
  );
}
```

*注意：`useRegionSelector` 仅可在客户端使用，且必须在 [`<GTProvider>`](/docs/react/reference/components/gt-provider) 下使用。如果你不需要自定义 UI，请改用 [`<RegionSelector>`](/docs/react/reference/components/region-selector) 组件。*

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

该钩子会返回当前选定区域、区域的有序列表、包含显示元数据的 `regionData` 映射，以及用于设置区域和区域设置的函数。当未提供 `regions` 时，可用区域会根据支持的区域设置推断出来。

## 参数 [#parameters]

`useRegionSelector` 接受一个可选的配置对象。

| 参数                                             | 描述                       | 类型         | 可选 | 默认值    |
| ---------------------------------------------- | ------------------------ | ---------- | -- | ------ |
| [`regions`](#regions)                          | 要显示的 ISO 3166 区域代码子集。    | `string[]` | 是  | 自动推断   |
| [`customMapping`](#custom-mapping)             | 为各区域自定义显示名称、emoji 或区域设置。 | `object`   | 是  | —      |
| [`prioritizeCurrentLocaleRegion`](#prioritize) | 将当前区域设置对应的区域排在最前面。       | `boolean`  | 是  | `true` |
| [`sortRegionsAlphabetically`](#sort)           | 按显示名称的字母顺序对区域进行排序。       | `boolean`  | 是  | `true` |

### `regions` [#regions]

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

要显示的 ISO 3166 区域代码。省略时，会根据支持的区域设置自动推断。

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

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

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

### `prioritizeCurrentLocaleRegion` [#prioritize]

**Type** `boolean` · **可选** · **默认值** `true`

当为 `true` 时，列表中会优先显示与当前区域设置匹配的区域。

### `sortRegionsAlphabetically` [#sort]

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

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

## 返回值 [#returns]

**类型** `object`

| 字段             | 描述                                              | 类型                                      |
| -------------- | ----------------------------------------------- | --------------------------------------- |
| `region`       | 当前选中的区域代码。                                      | `string \| undefined`                   |
| `setRegion`    | 更新选中的区域。                                        | `(region: string \| undefined) => void` |
| `regions`      | 可用的区域代码。                                        | `string[]`                              |
| `regionData`   | 区域代码到显示数据 (`code`、`name`、`emoji`、`locale`) 的映射。 | `Map<string, RegionData>`               |
| `locale`       | 当前的区域设置。                                        | `string`                                |
| `setLocale`    | 更新区域设置。                                         | `(locale: string) => void`              |
| `localeRegion` | 当前区域设置对应的 ISO 3166 区域代码。                        | `string`                                |

## 注意事项 [#notes]

* `useRegionSelector` 仅限客户端使用。
* 如需现成的下拉菜单，请使用 [`<RegionSelector>`](/docs/react/reference/components/region-selector)。
* 如需对应的区域设置版本，请参阅 [`useLocaleSelector`](/docs/react/reference/hooks/use-locale-selector)。