Symbol

Symbol() 関数は、symbol 型の値を返します。これはビルトインオブジェクトを公開するための静的プロパティを持ち、グローバル symbol レジストリーを公開するための静的メソッドを持つので、ビルトインオブジェクトクラスのようにも見えますが、コンストラクタとしての機能を持たず、"new Symbol()" はサポートされていません。

Symbol() 関数は常に一意の値を返します。symbol 値はオブジェクトのプロパティ識別子として使われます。symbol 型はこの目的のためだけに使われます。目的や使用方法の詳細を知りたい場合、 MDN用語集：Symbol を見てください。

symbol データ型は、プリミティブデータ型です。

The source for this interactive example is stored in a GitHub repository. If you'd like to contribute to the interactive examples project, please clone https://github.com/mdn/interactive-examples and send us a pull request.

構文

Symbol([description])

引数

description Optional

任意で文字列を渡すことができます。デバック用に使われますが、シンボル自体にはアクセスしないシンボルの説明です。

説明

新しいプリミティブ symbol を生成するために、説明のためのオプション文字列とともに Symbol() を記述します。

var sym1 = Symbol();
var sym2 = Symbol("foo");
var sym3 = Symbol("foo");

上述のコードは、新しい symbol を 3 つ生成しています。Symbol("foo") は、同一の symbol に文字列 "foo" を強制していません。毎回新しい symbol を生成しています。

Symbol("foo") === Symbol("foo"); // false

次の new 演算子を用いた構文は、TypeError を生成するでしょう。

var sym = new Symbol(); // TypeError

これは、記述者が新しい symbol の値を生成する代わりに明示的な Symbol ラッパーオブジェクトを生成することを防ぎます。プリミティブデータ型の周りに明示的なラッパーオブジェクトを生成することは、もはや ECMAScript6 ではサポートされていません。しかし、new Boolean や new String、new Number のような既存のプリミティブラッパーオブジェクトは、歴史的な理由からまだ生成できます。

そして、もし本当に Symbol ラッパーオブジェクトを生成したいなら、Object() 関数を使用できます。

var sym = Symbol("foo");
typeof sym;     // "symbol" 
var symObj = Object(sym);
typeof symObj;  // "object"

グローバル symbol レジストリの共有 symbol

上述の Symbol() 関数を使用した構文は、あなたのコード全体で使用できるグローバル symbol は生成しません。ファイルを跨いでグローバルスコープのような環境で使用できる symbol を生成するには、グローバル symbol レジストリから symbol を扱うための Symbol.for() と Symbol.keyFor() メソッドを使用します。

オブジェクトの symbol プロパティを探す

Object.getOwnPropertySymbols() メソッドは、symbol の配列を返し、与えられたオブジェクトの symbol プロパティを見つけられるようにしてくれます。すべてのオブジェクトは、symbol なしで初期化されます。そのため、オブジェクトに symbol プロパティを設定しないかぎり、この配列は空だということに注意してください。

プロパティ

Symbol.length

値が 0 の Length プロパティ

Symbol.prototype

Symbol コンストラクターのためのプロトタイプを表します。

予約された symbol

ユーザーの symbol に加えて、JavaScript は ECMAScript5 以前では開発者に公開されていなかった言語内部のふるまいを表すビルトイン symbol を持っています。これらは下記のプロパティを使用することでアクセスできます。

反復用途の symbol

Symbol.iterator

オブジェクトのための既定のイテレーターを返すメソッドです。for...of で使用されます。

Symbol.asyncIterator

A method that returns the default AsyncIterator for an object. for await of で使用されます。

正規表現用途の symbol

Symbol.match

文字列にマッチするメソッドや、オブジェクトが正規表現として使用できるか決定するために使用されます。String.prototype.match() で使われます。

Symbol.replace

マッチした文字列の部分を置き換えるメソッドです。String.prototype.replace() で使われます。

Symbol.search

正規表現にマッチする文字列内のインデックスを返すメソッドです。String.prototype.search() で使われます。

Symbol.split

正規表現にマッチするインデックスで文字列を分割するメソッドです。String.prototype.split() で使われます。

そのほかの symbol

Symbol.hasInstance

コンストラクターオブジェクトがオブジェクトをそのインスタンスか確認するために使用するメソッドです。instanceof で使用されます。

Symbol.isConcatSpreadable

オブジェクトが配列要素にフラット化できるかを示す真偽値です。Array.prototype.concat() で使用されます。

Symbol.unscopables

プロパティの値を示す文字列の配列です。これらは関連するオブジェクトをバインドする with 環境から除外されます。

Symbol.species

派生オブジェクトを生成するために使われるコンストラクター関数です。

Symbol.toPrimitive

オブジェクトをプリミティブ値に変換する関数です。

Symbol.toStringTag

オブジェクトの既定の説明のために使われる文字列値です。Object.prototype.toString() で使用されます。

メソッド

Symbol.for(key)

与えられた key で存在するシンボルを検索し、見つかればそれを返します。もしくは、グローバル symbol レジストリーにこの key で新しい symbol を生成します。

Symbol.keyFor(sym)

グローバル symbol レジストリーから、与えられた symbol のための共有 symbol Key を取得します。

Symbol プロトタイプ

すべての Symbol は、Symbol.prototype を継承しています。

プロパティ

メソッド

例

symbol と一緒に typeof 演算子を使用する

typeof 演算子は、symbol を識別するために役立ちます。

typeof Symbol() === 'symbol'
typeof Symbol('foo') === 'symbol'
typeof Symbol.iterator === 'symbol'

Symbol 型変換

symbol の型変換作業を行うとき、いくつかの点に注意してください。

• symbol を number に変換しようとするとき, TypeError がスローされます（例： +sym 、 sym | 0 ）。
• 緩い等価演算子を使うとき、Object(sym) == sym は true を返します。
• Symbol("foo") + "bar" は TypeError （ symbol を string に変換できません）をスローします。例えば、これは新しい string プロパティ名を暗黙的に生成することを防ぎます。
• "安全な" String(sym) 変換は symbol とともにSymbol.prototype.toString() を呼び出したかのように動作しますが、new String(sym) は TypeError をスローすることに注意してください。

Symbols と for...in による反復

Symbol は for...in よる反復からは取得できません。加えて、Object.getOwnPropertyNames() は symbol オブジェクトプロパティを返しません、それらを取得するために Object.getOwnPropertySymbols() を使うことができます。

var obj = {};

obj[Symbol("a")] = "a";
obj[Symbol.for("b")] = "b";
obj["c"] = "c";
obj.d = "d";

for (var i in obj) {
   console.log(i); // logs "c" and "d"
}

Symbol と JSON.stringify()

JSON.stringify() を使用するとき、Symbol をキーとしたプロパティは完全に無視されます。

JSON.stringify({[Symbol("foo")]: "foo"});                 
// '{}'

詳しくは JSON.stringify() を見てください。

プロパティキーとしての Symbol ラッパーオブジェクト

プロパティキーとして symbol ラッパーオブジェクトを使うとき、このオブジェクトはラッパーされた symbol を強制されます。

var sym = Symbol("foo");
var obj = {[sym]: 1};
obj[sym];            // 1
obj[Object(sym)];    // still 1

仕様

ブラウザー実装状況

関連項目

• 用語集: Symbol
• typeof
• データ型とデータ構造
• "ES6 In Depth: Symbols" on hacks.mozilla.org