# General Translation React SDKs (gt-react, gt-next, gt-react-native): `<LocaleSelector>`
URL: https://generaltranslation.com/zh/docs/react/reference/components/locale-selector.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: 渲染一个用于切换当前生效的区域设置的下拉菜单。`<LocaleSelector>` 组件的 API 参考。

`<LocaleSelector>` 组件是一个预构建的客户端下拉菜单，提供应用中已配置的 locales 选项，因此你无需自行构建，也能添加一个可用的语言切换器。

*可在 `gt-react`、`gt-next` 和 `gt-tanstack-start` 中使用。*

*注意：`gt-react-native` 不导出此组件。若要使用自定义选择器，请使用 [`useLocaleSelector`](/docs/react/reference/hooks/use-locale-selector)。*

## 概览 [#overview]

可以在任意客户端组件中渲染 `<LocaleSelector>`。不传入任何属性时，它会列出已配置的 locales。

*示例从 `gt-react` 导入；请改为从你的框架的软件包导入。*

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

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

*注意：`<LocaleSelector>` 仅支持客户端。若需完全自定义的切换器，请使用 [`useLocaleSelector`](/docs/react/reference/hooks/use-locale-selector) 钩子。*

## 工作方式 [#how-it-works]

* **读取上下文。** 默认情况下，这些选项来自 [`<GTProvider>`](/docs/react/reference/components/gt-provider) 上下文中的受支持 locales。传入 `locales` 可只显示其中一部分。
* **切换 locales。** 选择某个选项会保存当前生效的区域设置，并触发框架的刷新、重新加载或导航行为。请参阅[管理 locales](/docs/react/guides/managing-locales#persistence)。
* **为空时不渲染任何内容。** 当没有可用的 locales 时，该组件会返回 `null`。

## 属性 [#props]

| 属性                                 | 描述                      | 类型                                                    | 可选 | 默认             |
| ---------------------------------- | ----------------------- | ----------------------------------------------------- | -- | -------------- |
| [`locales`](#locales)              | 要显示的 locales 子集。        | `string[]`                                            | 是  | 所有受支持的 locales |
| [`customMapping`](#custom-mapping) | locales 的自定义选项标签。       | `Record<string, string \| Partial<LocaleProperties>>` | 是  | —              |
| [`customNames`](#custom-names)     | 已弃用的代码到标签映射。            | `Record<string, string>`                              | 是  | —              |
| [Select 属性](#select-attributes)    | 转发到底层 `<select>` 的标准属性。 | `React.SelectHTMLAttributes<HTMLSelectElement>`       | 是  | —              |

### `locales` [#locales]

**类型** `string[]` · **可选** · **默认值** 所有受支持的区域设置

用于填充下拉菜单的区域设置代码子集，例如 `['en', 'es-MX', 'fr']`。如果省略，则使用 [`<GTProvider>`](/docs/react/reference/components/gt-provider) 上下文中的 locales。

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

**类型** `Record<string, string | Partial<LocaleProperties>>` · **可选**

将区域设置代码映射为自定义选项标签。字符串值会直接用作标签；对象值则使用其 [`LocaleProperties`](/docs/platform/core/reference/types/locale-properties) 中的 `name` 属性。其他区域设置属性不会影响渲染的标签。

### `customNames` [#custom-names]

**类型** `Record<string, string>` · **可选** · **已弃用**

为保持兼容性而保留的旧版代码到标签映射。请改用 `customMapping`。同时提供这两个属性时，`customMapping` 优先。

### Select 属性 [#select-attributes]

标准的 `<select>` 属性 (如 `className`、`disabled` 和 `aria-describedby`) 会传递给渲染后的元素。该组件负责控制 `value` 和 `onChange`，因此选择选项时会更新当前生效的区域设置。

## 示例 [#examples]

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

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

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

export default function MyComponent() {
  const customMapping = {
    en: 'English',
    es: 'Español',
    'fr-CA': 'Français (Canada)',
  };
  return <LocaleSelector customMapping={customMapping} />;
}
```

## 说明 [#notes]

* `<LocaleSelector>` 仅可在客户端使用。
* 要读取当前生效的区域设置，请使用 [`useLocale`](/docs/react/reference/hooks/use-locale)；要构建自定义选择器，请使用 [`useLocaleSelector`](/docs/react/reference/hooks/use-locale-selector)。

## Sitemap

See the full [sitemap](https://generaltranslation.com/sitemap.md) for all pages.