Number.prototype.toLocaleString()

toLocaleString() メソッドは、この数値を表す言語依存の文字列を返します。

新しい locales と options 引数で アプリケーションは フォーマット変換で使われる言語を指定でき、関数の振る舞いをカスタマイズできます。古い実装では、locales と options 引数は無視され、使われるロケールや返される文字列の形式は完全に実装依存です。

構文

numObj.toLocaleString([locales [, options]])

引数

どのブラウザーが locales 引数と options 引数をサポートしているか確かめるためにブラウザー実装状況セクションを調べてください。特徴検出のために例: locales 引数と options 引数をサポートしているか調べるを調べてください。

注意: Firefox 29 で実装されている ECMAScript 国際化 API では、locales 引数が Number.toLocaleString() メソッドに追加されました。引数が undefined なら、このメソッドは OS によって指定されたローカライズされた数値を返します。Firefox の以前のバージョンでは、英語の数字が返されます。この変更はすぐに修正される可能性がある下位互換性に影響を与える回帰として報告されています。（バグ 999003）

戻り値

渡された数値を表す、言語依存の文字列です。

例

toLocaleString を使う

ロケールを指定しない基本的な使用で、デフォルトロケールとデフォルトオプションのフォーマットされた文字列が返されます。

var number = 3500;

console.log(number.toLocaleString()); // Displays "3,500" if in U.S. English locale

locales 引数と options 引数をサポートしているか調べる

locales 引数と options 引数はまだすべてのブラウザーでサポートされておりません。不正な言語タグが RangeError 例外で拒否される要件を使うことで、実装がすでにサポートしているかどうかを調べられます。

function toLocaleStringSupportsLocales() {
  var number = 0;
  try {
    number.toLocaleString('i');
  } catch (e) {
    return e​.name === 'RangeError';
  }
  return false;
}

ES5.1 以前の実装では、引数を使って toLocaleString を呼んだ場合に RangeError 例外を throw する必要はありませんでした。

5.1 以前の ECMAScript をサポートしているものも含めたすべてのホストで動くチェックは、直接 Number.prototype.toLocaleString の地域オプションのサポートに必要な ECMA-402 で指定された機能をテストすることで行えます。

function toLocaleStringSupportsOptions() {
  return !!(typeof Intl == 'object' && Intl && typeof Intl.NumberFormat == 'function');
}

上記のコードは、グローバル Intl オブジェクトが null でないことと、Intl オブジェクトが NumberFormat プロパティを持ち、それが関数であることをテストします。

locales を使う

この例ではローカライズされた数値変換のバリエーションのいくつかを示します。アプリケーションのユーザーインターフェイスで使われる言語の形式を得るために、locales 引数を用いている言語（そしておそらくいくつかのフォールバック言語）を明示することを確かめてください。

var number = 123456.789;

// German uses comma as decimal separator and period for thousands
console.log(number.toLocaleString('de-DE'));
// → 123.456,789

// Arabic in most Arabic speaking countries uses real Arabic digits
console.log(number.toLocaleString('ar-EG'));
// → ١٢٣٤٥٦٫٧٨٩

// India uses thousands/lakh/crore separators
console.log(number.toLocaleString('en-IN'));
// → 1,23,456.789

// the nu extension key requests a numbering system, e.g. Chinese decimal
console.log(number.toLocaleString('zh-Hans-CN-u-nu-hanidec'));
// → 一二三,四五六.七八九

// when requesting a language that may not be supported, such as
// Balinese, include a fallback language, in this case Indonesian
console.log(number.toLocaleString(['ban', 'id']));
// → 123.456,789

options を使う

toLocaleString によって得られる結果は options 引数を使用してカスタマイズできます。

var number = 123456.789;

// request a currency format
console.log(number.toLocaleString('de-DE', { style: 'currency', currency: 'EUR' }));
// → 123.456,79 €

// the Japanese yen doesn't use a minor unit
console.log(number.toLocaleString('ja-JP', { style: 'currency', currency: 'JPY' }))
// → ￥123,457

// limit to three significant digits
console.log(number.toLocaleString('en-IN', { maximumSignificantDigits: 3 }));
// → 1,23,000

// Use the host default language with options for number formatting
var num = 30000.65;
console.log(num.toLocaleString(undefined, {minimumFractionDigits: 2, maximumFractionDigits: 2}));
// → "30,000.65" where English is the default language, or
// → "30.000,65" where German is the default language, or
// → "30 000,65" where French is the default language

性能

多数の数値をフォーマットするとき、NumberFormat オブジェクトを生成して NumberFormat.format プロパティによって得られる関数を使用するほうが良いです。

仕様

ブラウザー実装状況

BCD tables only load in the browser

関連情報