# gt-next: General Translation Next.js SDK: useRegionSelector
URL: https://generaltranslation.com/zh/docs/next/api/helpers/use-region-selector.mdx
---
title: useRegionSelector
description: useRegionSelector Hook 的 API 参考
---

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


## 概述

`useRegionSelector` hook 提供了实现自定义区域选择器 UI 组件所需的数据和处理函数。它会返回当前区域、可用区域列表、区域元数据，以及用于更新区域或区域设置的函数。

<Callout>
  `useRegionSelector` 是一个客户端 hook，*只能在客户端组件中使用*。
  请确保你的应用已由 [`<GTProvider>`](/docs/next/api/components/gtprovider) 包裹。
</Callout>

## 参考文档

### 参数

一个可选的配置对象：

| 参数                              | 类型         | 默认值    | 描述                                                                                         |
| ------------------------------- | ---------- | ------ | ------------------------------------------------------------------------------------------ |
| `regions`                       | `string[]` | —      | 可选的 ISO 3166 区域代码数组，用于指定要显示的区域。如果未提供，则会根据支持的 locales 推断区域。                                 |
| `customMapping`                 | `object`   | —      | 可选映射，用于覆盖区域显示名称、表情符号或关联的 locales。值可以是字符串 (显示名称) ，也可以是包含 `name`、`emoji` 和/或 `locale` 属性的对象。 |
| `prioritizeCurrentLocaleRegion` | `boolean`  | `true` | 如果为 true，则会在列表中优先显示与当前区域设置对应的区域。                                                           |
| `sortRegionsAlphabetically`     | `boolean`  | `true` | 如果为 true，则区域会按显示名称的字母顺序排列。                                                                 |

### 返回值

一个对象，包含：

| 字段           | 类型                                      | 说明                                                    |
| ------------ | --------------------------------------- | ----------------------------------------------------- |
| `region`     | `string \| undefined`                   | 当前选中的区域代码。                                            |
| `setRegion`  | `(region: string \| undefined) => void` | 用于更新所选区域的函数。                                          |
| `regions`    | `string[]`                              | 可用区域代码数组。                                             |
| `regionData` | `Map<string, RegionData>`               | 将区域代码映射到其显示数据 (`code`、`name`、`emoji`、`locale`) 的 Map。 |
| `locale`     | `string`                                | 当前区域设置。                                               |
| `setLocale`  | `(locale: string) => void`              | 用于更新区域设置的函数。                                          |

***

## 示例

### 创建自定义区域选择器

```jsx title="CustomRegionSelector.jsx" copy
'use client';
import { useRegionSelector } from 'gt-next';

export default function CustomRegionSelector() {
  const { region, setRegion, regions, regionData } = useRegionSelector({ // [!code highlight]
    customMapping: { US: { name: "United States", emoji: "🇺🇸" } }, // [!code highlight]
  }); // [!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>
  );
}
```

***


## 说明

* 如果未提供 `regions`，则会根据你在 [`gt.config.json`](/docs/next/api/config/gt-config-json) 中配置的受支持区域设置推断可用区域。
* 如需使用现成的区域选择器，请使用 [`<RegionSelector>`](/docs/next/api/components/region-selector) 组件。

## 后续步骤

* 如需可直接使用的下拉组件，请参阅 [`<RegionSelector>`](/docs/next/api/components/region-selector)。
* 如需读取当前区域，请参阅 [`useRegion`](/docs/next/api/helpers/use-region)。
* 如需使用对应的区域设置版本，请参阅 [`useLocaleSelector`](/docs/next/api/helpers/use-locale-selector)。