# General Translation Platform: formatList
URL: https://generaltranslation.com/ja/docs/platform/core/reference/gt-class-methods/formatting/format-list.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: GT インスタンスで配列をロケール対応のリスト文字列に整形します。formatList の API リファレンス。

General Translation は組み込みの `Intl.ListFormat` API を使用し、各ロケールに適した区切り文字と、conjunction (「and」) または disjunction (「or」) に対応する表現で項目を連結します。

## 概要 [#overview]

[`GT`](/docs/platform/core/reference/gt-class/constructor) インスタンスで `formatList` を呼び出し、配列と省略可能なオプションオブジェクトを渡します。戻り値は、解決されたロケールに応じて項目を連結したフラットな文字列です。

```typescript
const gt = new GT({ targetLocale: 'en' });

const list = gt.formatList(['apple', 'banana', 'orange']);
// "apple, banana, and orange"
```

シグネチャ:

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

*注: `formatList` は単一の `string` を返します。元の項目の型 (型が混在した配列や JSX 配列など) を保持したい場合は、代わりに [`formatListToParts`](/docs/platform/core/reference/gt-class-methods/formatting/format-list-to-parts) を使用してください。`GT` インスタンスを使わずにフォーマットする場合は、スタンドアロンの [`formatList`](/docs/platform/core/reference/utility-functions/formatting/format-list) を参照してください。*

## 仕組み [#how-it-works]

* **Intl 対応。** フォーマット処理は [`Intl.ListFormat`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/ListFormat) に委ねられます。
* **ロケールの解決。** デフォルトでは、このメソッドはインスタンスのターゲットロケール向けにフォーマットし、ソースロケール、さらにライブラリのデフォルト (`en`) の順にフォールバックします。`locales` の設定配列は使われません。上書きするには、options で `locales` を渡します。
* **リストタイプ。** `type: 'conjunction'` は &quot;and&quot; 形式のリスト、`'disjunction'` は &quot;or&quot; 形式のリスト、`'unit'` は単位形式のリストを生成します。

## パラメータ [#parameters]

| パラメータ                 | 説明                                                               | 型                         | 任意  | デフォルト |
| --------------------- | ---------------------------------------------------------------- | ------------------------- | --- | ----- |
| [`array`](#array)     | 書式設定する項目の一覧。                                                     | `Array<string \| number>` | いいえ | —     |
| [`options`](#options) | `locales` のオーバーライドを追加して `Intl.ListFormatOptions` を拡張した書式設定オプション。 | `object`                  | はい  | —     |

### `array` [#array]

**型** `Array<string | number>` · **必須**

項目を1つの文字列に連結するためのリストです。

### `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[]`                       | はい | `targetLocale` → `sourceLocale` → `en` |
| `localeMatcher` | ロケール照合アルゴリズム。         | `'lookup' \| 'best fit'`                   | はい | `'best fit'`                           |
| `type`          | リストのフォーマットの型。           | `'conjunction' \| 'disjunction' \| 'unit'` | はい | `'conjunction'`                        |
| `style`         | リストのフォーマットスタイル。         | `'long' \| 'short' \| 'narrow'`            | はい | `'long'`                               |

## 戻り値 [#returns]

**型** `string`

項目を結合して1つのロケール対応リスト文字列にしたもの。

## 例 [#examples]

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

const gt = new GT({ targetLocale: 'en' });

// Conjunction（デフォルト）— "and" リスト
console.log(gt.formatList(['A', 'B', 'C']));
// 出力: "A, B, and C"

// Disjunction — "or" リスト
console.log(gt.formatList(['A', 'B', 'C'], { type: 'disjunction' }));
// 出力: "A, B, or C"

// スペイン語の disjunction
console.log(gt.formatList(['red', 'green', 'blue'], {
  locales: ['es'],
  type: 'disjunction',
}));
// 出力: "red, green o blue"
```

## メモ [#notes]

* 戻り値はフラットな `string` です。`string` 以外の項目型を保持する必要がある場合は、[`formatListToParts`](/docs/platform/core/reference/gt-class-methods/formatting/format-list-to-parts) を使用してください。
* このメソッドは内部でブラウザネイティブの `Intl.ListFormat` を使用しています。

## Sitemap

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