# generaltranslation: General Translation Core SDK: formatNum
URL: https://generaltranslation.com/ja/docs/core/class/methods/formatting/format-num.mdx
---
title: formatNum
description: ロケールの慣習に従って数値をフォーマットする `formatNum` メソッドの API リファレンス
---

## 概要

`formatNum` メソッドは、Internationalization API を使用して、ロケールの慣習に従って数値をフォーマットします。
対象のロケールに応じて、小数点区切り文字、桁区切り文字、数値体系を自動的に処理します。

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

const formatted = gt.formatNum(1234.56, {
  style: 'decimal',
  minimumFractionDigits: 2
});
// 戻り値: "1.234,56" (ドイツ語の数値フォーマット)
```


## リファレンス

### パラメータ

| 名前         | 型                     | 説明             |
| ---------- | --------------------- | -------------- |
| `number`   | `number`              | 書式設定する数値       |
| `options?` | `NumberFormatOptions` | 省略可能な書式設定オプション |

### NumberFormatOptions

追加のロケール指定をサポートするように `Intl.NumberFormatOptions` を拡張したものです。

| 名前                          | 型                                                                                                                    | 説明                                            |
| --------------------------- | -------------------------------------------------------------------------------------------------------------------- | --------------------------------------------- |
| `locales?`                  | `string \| string[]`                                                                                                 | 書式設定に使用するロケールを上書きします (デフォルトではインスタンスのロケールを使用)  |
| `style?`                    | `'decimal' \| 'currency' \| 'percent' \| 'unit'`                                                                     | 数値の書式スタイル                                     |
| `currency?`                 | `string`                                                                                                             | 通貨コード (style が 'currency' の場合は必須)     |
| `currencyDisplay?`          | `'symbol' \| 'narrowSymbol' \| 'code' \| 'name'`                                                                     | 通貨の表示方法                                       |
| `currencySign?`             | `'standard' \| 'accounting'`                                                                                         | 使用する通貨符号                                      |
| `unit?`                     | `string`                                                                                                             | 単位識別子 (style が 'unit' の場合は必須)         |
| `unitDisplay?`              | `'short' \| 'narrow' \| 'long'`                                                                                      | 単位の表示方法                                       |
| `minimumIntegerDigits?`     | `number`                                                                                                             | 整数部の最小桁数 (1〜21)                               |
| `minimumFractionDigits?`    | `number`                                                                                                             | 小数部の最小桁数 (0〜20)                               |
| `maximumFractionDigits?`    | `number`                                                                                                             | 小数部の最大桁数 (0〜20)                               |
| `minimumSignificantDigits?` | `number`                                                                                                             | 有効桁数の最小値 (1〜21)                               |
| `maximumSignificantDigits?` | `number`                                                                                                             | 有効桁数の最大値 (1〜21)                               |
| `useGrouping?`              | `boolean \| 'always' \| 'auto' \| 'min2'`                                                                            | 桁区切り記号を使用するかどうか                               |
| `notation?`                 | `'standard' \| 'scientific' \| 'engineering' \| 'compact'`                                                           | 数値表記の形式                                       |
| `compactDisplay?`           | `'short' \| 'long'`                                                                                                  | コンパクト表記の表示スタイル                                |
| `signDisplay?`              | `'auto' \| 'never' \| 'always' \| 'exceptZero'`                                                                      | 符号を表示するタイミング                                  |
| `roundingMode?`             | `'ceil' \| 'floor' \| 'expand' \| 'trunc' \| 'halfCeil' \| 'halfFloor' \| 'halfExpand' \| 'halfTrunc' \| 'halfEven'` | 丸めモード                                         |
| `roundingIncrement?`        | `1 \| 2 \| 5 \| 10 \| 20 \| 25 \| 50 \| 100`                                                                         | 丸めの刻み幅                                        |
| `trailingZeroDisplay?`      | `'auto' \| 'stripIfInteger'`                                                                                         | 末尾のゼロを表示するかどうか                                |

### 戻り値

`string` - ロケールの慣習に従って書式化された数値を表す文字列。

***

## 例

### 基本的な数値のフォーマット

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

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

// 基本的な小数のフォーマット
console.log(gt.formatNum(1234.567));
// 出力: "1,234.567"

// ドイツ語ロケールのフォーマット
console.log(gt.formatNum(1234.567, { locales: 'de-DE' }));
// 出力: "1.234,567"

// フランス語ロケールのフォーマット  
console.log(gt.formatNum(1234.567, { locales: 'fr-FR' }));
// 出力: "1 234,567"
```


### 通貨のフォーマット

```typescript copy
// 米ドルのフォーマット
console.log(gt.formatNum(1234.56, {
  style: 'currency',
  currency: 'USD'
}));
// Output: "$1,234.56"

// ドイツ語ロケールでのユーロのフォーマット
console.log(gt.formatNum(1234.56, {
  style: 'currency',
  currency: 'EUR',
  locales: 'de-DE'
}));
// Output: "1.234,56 €"

// 通貨表示オプション
console.log(gt.formatNum(1234.56, {
  style: 'currency',
  currency: 'USD',
  currencyDisplay: 'code'
}));
// Output: "USD 1,234.56"

// 会計フォーマット（負の値を括弧で表示）
console.log(gt.formatNum(-1234.56, {
  style: 'currency',
  currency: 'USD',
  currencySign: 'accounting'
}));
// Output: "($1,234.56)"
```


### パーセンテージと科学表記

```typescript copy
// 基本的なパーセント表示
console.log(gt.formatNum(0.1234, { style: 'percent' }));
// 出力: "12%"

// 小数点以下を含むパーセント表示
console.log(gt.formatNum(0.1234, {
  style: 'percent',
  minimumFractionDigits: 1,
  maximumFractionDigits: 2
}));
// 出力: "12.34%"

// コンパクト表記
console.log(gt.formatNum(1234567, { notation: 'compact' }));
// 出力: "1.2M"

// 指数表記
console.log(gt.formatNum(1234567, { notation: 'scientific' }));
// 出力: "1.235E6"
```

***


## 注意事項

* 数値の書式は、特定のロケールの規則に自動的に従います
* このメソッドは、最適なパフォーマンスと精度のために、ブラウザネイティブの `Intl.NumberFormat` を使用します
* 通貨の書式設定には、`style: 'currency'` と有効な `currency` コードの両方が必要です
* 単位の書式設定には、`style: 'unit'` と有効な `unit` 識別子の両方が必要です

## 次のステップ

* さらに多くのオプションについては、[`Intl.NumberFormat` のドキュメント](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat)を参照してください
* 数値補間を含むメッセージの書式設定については、[`format-message`](/docs/core/class/methods/formatting/format-message)を参照してください
* GT インスタンスを作成せずに使用する場合は、スタンドアロンの [`format-num`](/docs/core/functions/formatting/format-num)を参照してください
* ロケール固有の書式設定情報については、[`get-locale-properties`](/docs/core/class/methods/locales/get-locale-properties)を参照してください