# General Translation Platform: getRegionProperties
URL: https://generaltranslation.com/zh/docs/platform/core/reference/gt-class-methods/locales/get-region-properties.mdx
---

title: getRegionProperties
description: 返回区域设置或区域代码的区域元数据。getRegionProperties 的 API 参考。

---

获取 [GT](/docs/platform/core/reference/gt-class/constructor) 实例中某个区域代码的详细信息，包括其本地化名称及对应的旗帜表情符号。General Translation 提供了一种便捷方式来获取区域特定的显示信息，以便构建国际化用户界面。

## 概览 [#overview]

在 [`GT`](/docs/platform/core/reference/gt-class/constructor) 实例上调用 `getRegionProperties`，可选择传入区域代码。省略时，会使用该实例目标区域设置中的区域。

```typescript
const gt = new GT({ sourceLocale: 'en-US', targetLocale: 'fr-FR' });

// 获取区域属性
const usProps = gt.getRegionProperties('US');
console.log(usProps);
// { code: 'US', name: 'États-Unis', emoji: '🇺🇸' }

const frProps = gt.getRegionProperties('FR');
console.log(frProps);
// { code: 'FR', name: 'France', emoji: '🇫🇷' }

// 从当前区域设置自动检测
const currentRegion = gt.getRegionProperties(); // 使用 targetLocale 的区域
console.log(currentRegion);
// { code: 'FR', name: 'France', emoji: '🇫🇷' }
```

签名：

```typescript
getRegionProperties(
  region?: string,
  customMapping?: CustomRegionMapping
): { code: string; name: string; emoji: string }
```

*注意：`getRegionProperties` 会通过 `Intl.DisplayNames` 在本地运行，不需要 API Key。省略 `region` 时，它会使用该实例 `targetLocale` 中的地区，并根据该实例的 `targetLocale` 对地区名称进行本地化。若要在没有 `GT` 实例的情况下进行查找，请参阅独立的 [`getRegionProperties`](/docs/platform/core/reference/utility-functions/locales/get-region-properties)。*

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

* **地区代码。** 接受 ISO 3166-1 alpha-2 或 UN M.49 区域代码 (例如 `"US"`、`"FR"`、`"419"`) 。
* **本地化名称。** 使用 `Intl.DisplayNames` 按实例的 `targetLocale` 对地区名称进行本地化，必要时回退到 library 的默认区域设置。
* **自定义映射优先级。** 如果 `customMapping` 为该地区提供了 `name` 或 `emoji`，则会覆盖默认值。
* **后备机制。** 如果显示名称解析失败，则使用区域代码作为 `name`；如果找不到 emoji 映射，则使用默认 emoji。
* **地区后备。** 省略 `region` 时，将使用实例目标区域设置中的地区。
* **缺少区域设置。** 如果没有可用于确定地区属性的目标区域设置，则会抛出 `Error`。

## 参数 [#parameters]

| 参数                                 | 描述                                 | 类型                    | 可选 | 默认值                                     |
| ---------------------------------- | ---------------------------------- | --------------------- | -- | --------------------------------------- |
| [`region`](#region)                | ISO 3166-1 alpha-2 或 UN M.49 区域代码。 | `string`              | 是  | `this.getLocaleProperties().regionCode` |
| [`customMapping`](#custom-mapping) | 用于覆盖默认名称和表情符号的自定义区域映射。             | `CustomRegionMapping` | 是  | `this.customRegionMapping`              |

### `region` [#region]

**类型** `string` · **可选** · **默认值** `this.getLocaleProperties().regionCode`

ISO 3166-1 alpha-2 或 UN M.49 区域代码。如果未提供，则使用该实例目标区域设置中的区域。

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

**类型** `CustomRegionMapping` · **可选** · **默认值** `this.customRegionMapping`

可选的自定义区域映射，用于覆盖默认的区域名称和表情。

## 返回值 [#returns]

**类型** `{ code: string; name: string; emoji: string }`

一个对象，包含：

* `code`：输入的区域代码。
* `name`：目标区域设置语言中的本地化 (或自定义) 地区名称。
* `emoji`：对应的旗帜表情符号或其他符号。

## 示例 [#examples]

```typescript
// 基本区域信息
const gt = new GT({ sourceLocale: 'en-US', targetLocale: 'en-US' });

// 常见区域代码
console.log(gt.getRegionProperties('US')); // { code: 'US', name: 'United States', emoji: '🇺🇸' }
console.log(gt.getRegionProperties('GB')); // { code: 'GB', name: 'United Kingdom', emoji: '🇬🇧' }
console.log(gt.getRegionProperties('DE')); // { code: 'DE', name: 'Germany', emoji: '🇩🇪' }
console.log(gt.getRegionProperties('JP')); // { code: 'JP', name: 'Japan', emoji: '🇯🇵' }
```

```typescript
// 自定义区域映射会覆盖默认值
const gt = new GT({ targetLocale: 'en-US' });

console.log(gt.getRegionProperties('US', { US: { name: 'USA', emoji: '🗽' } }));
// { code: 'US', name: 'USA', emoji: '🗽' }
```

## 注意事项 [#notes]

* 使用 `Intl.DisplayNames` API 获取本地化的地区名称。
* 同时支持 ISO 3166-1 alpha-2 和 UN M.49 区域代码。
* 自定义映射会覆盖默认名称和表情符号。
* 如果未提供参数，则会根据目标区域设置自动检测地区。
* 如果显示名称解析失败，则会回退为使用区域代码作为名称。