# General Translation Platform: formatListToParts
URL: https://generaltranslation.com/zh/docs/platform/core/reference/utility-functions/formatting/format-list-to-parts.mdx
---

title: formatListToParts
description: 在没有 GT 实例的情况下，将列表格式化为符合区域设置的 parts。formatListToParts 的 API 参考。

---

[`formatListToParts`](/docs/platform/core/reference/gt-class-methods/formatting/format-list-to-parts) 是 General Translation 核心库提供的独立工具函数，用于将数组格式化为特定区域设置的 parts。它会在各项之间插入字符串分隔符，同时保留每个元素的原始类型，并返回 `Array<T | string>`。

## 概述 [#overview]

直接从 `generaltranslation` 导入 `formatListToParts`，并传入一个 array 和一个 options object 来调用它。它不需要 API Key，也不需要 [GT](/docs/platform/core/reference/gt-class/constructor) 实例。若要使用基于实例且继承实例区域设置的格式化方式，请改用 [`GT`](/docs/platform/core/reference/gt-class/constructor) 实例上的 [`formatListToParts`](/docs/platform/core/reference/gt-class-methods/formatting/format-list-to-parts) 方法。

与返回扁平 `string` 的 [`formatList`](/docs/platform/core/reference/utility-functions/formatting/format-list) 不同，此函数会保留原始项不变，只在它们之间插入字符串分隔符——这对于在 React 等 UI 框架中渲染混合类型的 array 非常有用。

```typescript
import { formatListToParts } from 'generaltranslation';

const parts = formatListToParts(['red', 'green', 'blue'], {
  locales: ['es'],
  type: 'disjunction',
});
// 返回: ['red', ', ', 'green', ' o ', 'blue']
```

签名：

```typescript
formatListToParts<T>(
  array: Array<T>,
  options?: { locales?: string | string[] } & Intl.ListFormatOptions
): Array<T | string>
```

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

* **底层 API。** 使用与 GT 类方法相同的 [`Intl.ListFormat`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/ListFormat)。
* **类型保留。** 仅在元素之间插入字符串分隔符；每个原始项都保留原有类型，因此数字和对象会原样传递。
* **区域设置解析。** 如果省略 `locales`，则回退到 library 的默认区域设置 `en`。

## 参数 [#parameters]

| 参数                    | 描述              | 类型                                                          | 可选 | 默认值  |
| --------------------- | --------------- | ----------------------------------------------------------- | -- | ---- |
| [`array`](#array)     | 要格式化的项目数组。      | `Array<T>`                                                  | 否  | —    |
| [`options`](#options) | 格式化配置，包括目标区域设置。 | `{ locales?: string \| string[] } & Intl.ListFormatOptions` | 是  | `{}` |

### `array` [#array]

**Type** `Array<T>` · **必填**

要格式化的数组项。支持任意类型的项；非字符串项将原样返回。

### `options` [#options]

**类型** `{ locales?: string | string[] } & Intl.ListFormatOptions` · **可选** · **默认值** `{}`

格式化配置。该表列出了已发布的 Core 类型公开的常用选项及其实际采用的 Core 默认值。有关补充的标准详情和运行时特定详情，请参阅 [`Intl.ListFormat` 构造函数选项](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/ListFormat/ListFormat#options)。

| 属性              | 描述          | 类型                                         | 可选 | 默认值             |
| --------------- | ----------- | ------------------------------------------ | -- | --------------- |
| `locales`       | 用于格式化的区域设置。 | `string \| string[]`                       | 是  | `en`            |
| `localeMatcher` | 区域设置匹配算法。   | `'lookup' \| 'best fit'`                   | 是  | `'best fit'`    |
| `type`          | 列表格式类型。     | `'conjunction' \| 'disjunction' \| 'unit'` | 是  | `'conjunction'` |
| `style`         | 列表格式样式。     | `'long' \| 'short' \| 'narrow'`            | 是  | `'long'`        |

## 返回 [#returns]

**类型** `Array<T | string>`

一个数组，原始条目与区域设置特定的字符串分隔符交错排列。

## 示例 [#examples]

```typescript
import { formatListToParts } from 'generaltranslation';

// 连接列表（默认）
console.log(formatListToParts(['A', 'B', 'C'], { locales: 'en' }));
// 输出：['A', ', ', 'B', ', and ', 'C']

// 析取列表
console.log(formatListToParts(['A', 'B', 'C'], { locales: 'en', type: 'disjunction' }));
// 输出：['A', ', ', 'B', ', or ', 'C']
```

```typescript
// 混合类型数组：数字和对象会被保留
console.log(formatListToParts(['apple', 42, { type: 'fruit' }], { locales: 'en' }));
// 输出：['apple', ', ', 42, ', and ', { type: 'fruit' }]
```

```typescript
// 西班牙语析取
console.log(formatListToParts(['red', 'green', 'blue'], {
  locales: 'es',
  type: 'disjunction',
}));
// 输出：['red', ', ', 'green', ' o ', 'blue']

// 简短样式
console.log(formatListToParts(['first', 'second'], {
  locales: 'en',
  style: 'short',
}));
// 输出：['first', ' & ', 'second']
```

## 注意事项 [#notes]

* 会保留原始项的类型——只会在各元素之间插入字符串分隔符。
* 这也是它与 [`formatList`](/docs/platform/core/reference/utility-functions/formatting/format-list) 的关键区别：后者会返回一个扁平的 `string`。
* 特别适合在 React 等 UI 框架中渲染混合类型的数组。
* 它使用与 GT 类方法相同的底层 `Intl.ListFormat`。