To tłumaczenie jest niekompletne. Pomóż przetłumaczyć ten artykuł z języka angielskiego.

Funkcja Symbol() zwraca wartość typu symbol, posiada statyczne własności wystawiające kilka wartości używanych we wbudowanych obiektach, posiada statyczne metody wystawiające globalny rejestr symboli i przypomina wbudowaną klasę obiektu, jest jednak niekompletna jako konstruktor ponieważ nie wspiera składni "new Symbol()".  

Każdy symbol zwrócony przez Symbol() jest unikalny. Symbol powinien być użyty jako identyfikator własności obiektu, został zaprojektowany jedynie w tym celu. Pełniejsze wyjaśnienie dotyczące jego przeznaczenia i użycia można znaleźć w poświęconym mu wpisie w glosariuszu.

Typ symbol jest typem prostym.

Składnia

Symbol([opis])

Parametry

opis Optional
Ciąg znaków, parametr opcjonalny. Opis symbolu, może być użyty do debugowania, ale nie do dostania się do samego symbolu.

Opis

Aby stworzyć nowy symbol należy użyć funkcji Symbol(), opcjonalnie przekazując jej opisowy ciąg znaków:

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

Powyższy kod tworzy trzy nowe symbole. Należy zwrócić uwagę, że Symbol("foo") nie konwertuje ciągu znaków "foo" na symbol, tylko tworzy za każdym razem nowy symbol:

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

Następująca składnia z operatorem new spowoduje wyjątek TypeError:

var sym = new Symbol(); // TypeError

Dzieje się tak dlatego żeby powstrzymać programistów przed opakowywaniem wartości symboli w obiekty i może być zaskakujące, gdyż tworzenie opakowanych wartości dla typów prostych jest zazwyczaj możliwe (na przykład new Boolean, new String i new Number).

Jeśli stworzenie opakowanego symbolu jest dokładnie tym czego chce programista, może do tego użyć funkcji Object():

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

Symbole współdzielone w globalnym rejestrze symboli

Powyższa składnia używająca funkcji Symbol() nie stworzy globalnego symbolu, który będzie dostępny w całym kodzie. Aby stworzyć symbol dostępny między plikami, a nawet między sferami (z których każda ma swoją globalną przestrzeń) należy użyć metody Symbol.for(). Z kolei metody Symbol.keyFor() można użyć aby uzyskać nazwę globalnego klucza dla posiadanego symbolu.

Znajdowanie własności indeksowanych symbolami na obiekcie

Metoda Object.getOwnPropertySymbols() zwraca tablicę symboli i pozwala znaleźć własności indeksowane symbolami na danym obiekcie. Każdy obiekt jest inicjowany bez takich własności, więc metoda ta zwróci pustą tablicę do czasu ustawienia na obiekcie własności pod kluczem typu symbol.

Własności

Symbol.length
Własność length której wartością jest 0.
Symbol.prototype
Reprezentuje prototyp konstruktora Symbol.

Znane symbole

Oprócz symboli zdefiniowanych przez programistę, JavaScript posiada wbudowane symbole reprezentujące wewnętrzne mechanizmy języka, które nie były widoczne dla programisty w wersji ECMAScript 5 i wcześniejszych. Dostęp do tych symboli jest możliwy za pomocą następujących własności statycznych:

Symbole iteracji

Symbol.iterator
Metoda zwracająca domyślny iterator dla obiektu. Używana przez for...of.
Symbol.asyncIterator
Metoda zwracająca domyślny asynchroniczny iterator dla obiektu. Używana przez for await of.

Symbole wyrażeń regularnych

Symbol.match
Metoda dopasowująca dla ciągu znaków, używana również dla określenia czy obiekt może zostać użyty jako wyrażenie regularne. Używana przez String.prototype.match().
Symbol.replace
Metoda zastępująca dopasowany ciąg w ciągu znaków. Używana przez String.prototype.replace().
Symbol.search
Metoda zwracająca indeks początku ciągu znaków który został dopasowany do wyrażenia regularnego. Używana przez String.prototype.search().
Symbol.split
Metoda dzieląca łańcuch znaków w miejscu w którym został dopasowany do wyrażenia regularnego. Używana przez String.prototype.split().

Pozostałe symbole

Symbol.hasInstance
Metoda określająca czy konstruktor rozpoznaje obiekt jako swoją instancję. Używana przez instanceof.
Symbol.isConcatSpreadable
Wartość logiczna określająca czy obiekt powinien zostać spłaszczony do jego elementów tablicy. Używana przez Array.prototype.concat().
Symbol.unscopables
Wartość obiektu którego własne i dziediczone nazwy własności są wykluczone ze środowiska with powiązanego obiektu.
Symbol.species
Funkcja konstruktora używana do tworzenia obiektów wywodzących się z danego.
Symbol.toPrimitive
Metoda konwertująca obiekt na typ prosty.
Symbol.toStringTag
Ciąg znaków używany dla domyślnego opisu obiektu. Używany przez Object.prototype.toString().

Metody

Symbol.for(key)
Szuka istniejącego symbolu o podanym kluczu i zwraca go, jeśli został znaleziony. W przeciwnym razie w globalnym rejestrze tworzony jest nowy symbol o podanym kluczu i również zwracany.
Symbol.keyFor(sym)
Zwraca klucz w globalnym rejestrze zapisany dla danego symbolu.

Symbol prototype

Wszystkie symbole dziecidzą po Symbol.prototype.

Własności

Symbol.prototype.constructor
Returns the function that created an instance's prototype. This is the Symbol function by default.
Symbol.prototype.description
A read-only string containing the description of the symbol.

Metody

Symbol.prototype.toSource()
Returns a string containing the source of the Symbol object. Overrides the Object.prototype.toSource() method.
Symbol.prototype.toString()
Returns a string containing the description of the Symbol. Overrides the Object.prototype.toString() method.
Symbol.prototype.valueOf()
Returns the primitive value of the Symbol object. Overrides the Object.prototype.valueOf() method.
Symbol.prototype[@@toPrimitive]
Returns the primitive value of the Symbol object.

Przykłady

Używanie operatora typeof z symbolami

Operator typeof może pomóc w identyfikacji symboli.

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

Konwersje typu symbol

  • Podczas próby konwersji symbolu na liczbę zostanie rzucony wyjątek TypeError.
    (np. +sym lub sym | 0).
  • Przy porównaniu z pominięciem typu Object(sym) == sym zwraca true.
  • Symbol("foo") + "bar" wyrzuci TypeError (nie można skonwertować symbolu na ciąg znaków). Służy to powstrzymaniu programisty na przykład przed stworzeniem nowej nazwy własności z użyciem symbolu.
  • "Bezpieczniejsza" konwersja String(sym) działa jak wywołanie Symbol.prototype.toString() ale należy mieć na uwadze, że new String(sym) rzuci wyjątkiem.

Symbole i iteracja for...in

Symbole nie są iterowalne w pętlach for...in. Dodatkowo, Object.getOwnPropertyNames() nie zwróci własności obiektu zapisanych pod kluczem którym jest symbol, do tego celu można użyć 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); // loguje "c" i "d"
}

Symbole i JSON.stringify()

Własności obiektu znajdujące się pod kluczem w postaci symbolu są ignorowane przez JSON.stringify():

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

Żeby dowiedzieć się więcej zobacz JSON.stringify().

Symbole opakowane w obiekty jako klucze własności

Gdy symbol opakowany w obiekt jest użyty jako klucz własności, obiekt opakowujący zostanie skonwertowany do symbolu który opakowuje:

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

Specyfikacje

Specyfikacja Status Komentarz
ECMAScript 2015 (6th Edition, ECMA-262)
The definition of 'Symbol' in that specification.
Standard Wstępna definicja
ECMAScript Latest Draft (ECMA-262)
The definition of 'Symbol' in that specification.
Draft  

Kompatybilność przeglądarek

Update compatibility data on GitHub
DesktopMobileServer
ChromeEdgeFirefoxInternet ExplorerOperaSafariAndroid webviewChrome for AndroidEdge MobileFirefox for AndroidOpera for AndroidiOS SafariSamsung InternetNode.js
Basic supportChrome Full support 38Edge Full support 12
Notes
Full support 12
Notes
Notes Edge 12 included Symbol properties in JSON.stringify() output.
Firefox Full support 36IE No support NoOpera Full support 25Safari Full support 9WebView Android Full support YesChrome Android Full support 38Edge Mobile Full support YesFirefox Android Full support 36Opera Android Full support 25Safari iOS Full support 9Samsung Internet Android Full support Yesnodejs Full support Yes
asyncIterator
Experimental
Chrome No support NoEdge No support NoFirefox No support No
Notes
No support No
Notes
Notes Available in Firefox Nightly.
IE No support NoOpera No support NoSafari No support NoWebView Android No support NoChrome Android No support NoEdge Mobile No support NoFirefox Android No support NoOpera Android No support NoSafari iOS No support NoSamsung Internet Android No support Nonodejs No support No
descriptionChrome Full support 70Edge No support NoFirefox Full support 63IE No support NoOpera Full support 57Safari No support NoWebView Android Full support 70Chrome Android Full support 70Edge Mobile No support NoFirefox Android Full support 63Opera Android Full support 57Safari iOS No support NoSamsung Internet Android No support Nonodejs No support No
forChrome Full support 40Edge Full support YesFirefox Full support 36IE No support NoOpera Full support YesSafari Full support 9WebView Android Full support YesChrome Android Full support YesEdge Mobile Full support YesFirefox Android Full support 36Opera Android Full support YesSafari iOS Full support 9Samsung Internet Android Full support Yesnodejs Full support Yes
hasInstanceChrome Full support 51Edge Full support 15Firefox Full support 50IE No support NoOpera Full support YesSafari Full support YesWebView Android Full support YesChrome Android Full support YesEdge Mobile Full support YesFirefox Android Full support 50Opera Android Full support YesSafari iOS Full support YesSamsung Internet Android Full support Yesnodejs Full support 6.5.0
Full support 6.5.0
Full support 6.0.0
Disabled
Disabled From version 6.0.0: this feature is behind the --harmony runtime flag.
isConcatSpreadableChrome Full support 48Edge Full support 15Firefox Full support 48IE No support NoOpera Full support YesSafari Full support YesWebView Android Full support YesChrome Android Full support YesEdge Mobile Full support YesFirefox Android Full support 48Opera Android Full support YesSafari iOS Full support YesSamsung Internet Android Full support Yesnodejs Full support 6.0.0
iteratorChrome Full support 43Edge Full support YesFirefox Full support 36IE No support NoOpera Full support 30Safari Full support 10WebView Android Full support YesChrome Android Full support YesEdge Mobile Full support YesFirefox Android Full support 36Opera Android Full support YesSafari iOS Full support 10Samsung Internet Android Full support Yesnodejs Full support 0.12
keyForChrome Full support 40Edge Full support YesFirefox Full support 36IE No support NoOpera Full support YesSafari Full support 9WebView Android Full support YesChrome Android Full support YesEdge Mobile Full support YesFirefox Android Full support 36Opera Android Full support YesSafari iOS Full support 9Samsung Internet Android Full support Yesnodejs Full support Yes
matchChrome Full support 50Edge Full support YesFirefox Full support 40IE No support NoOpera Full support YesSafari Full support YesWebView Android Full support YesChrome Android Full support YesEdge Mobile Full support YesFirefox Android Full support 40Opera Android Full support YesSafari iOS Full support YesSamsung Internet Android Full support Yesnodejs Full support 6.0.0
prototypeChrome Full support 38Edge Full support 12Firefox Full support 36IE No support NoOpera Full support 25Safari Full support 9WebView Android Full support YesChrome Android Full support 38Edge Mobile Full support YesFirefox Android Full support 36Opera Android Full support 25Safari iOS Full support 9Samsung Internet Android Full support Yesnodejs Full support Yes
replaceChrome Full support 50Edge Full support YesFirefox Full support 49IE No support NoOpera Full support YesSafari Full support YesWebView Android Full support YesChrome Android Full support YesEdge Mobile Full support YesFirefox Android Full support 49Opera Android Full support YesSafari iOS Full support YesSamsung Internet Android Full support Yesnodejs Full support 6.0.0
searchChrome Full support 50Edge Full support YesFirefox Full support 49IE No support NoOpera Full support YesSafari Full support YesWebView Android Full support YesChrome Android Full support YesEdge Mobile Full support YesFirefox Android Full support 49Opera Android Full support YesSafari iOS Full support YesSamsung Internet Android Full support Yesnodejs Full support 6.0.0
speciesChrome Full support 51Edge Full support 14Firefox Full support 41IE No support NoOpera Full support 38Safari Full support 10WebView Android Full support YesChrome Android Full support YesEdge Mobile Full support 14Firefox Android Full support 41Opera Android Full support 38Safari iOS Full support 10Samsung Internet Android Full support Yesnodejs Full support 6.5.0
Full support 6.5.0
Full support 6.0.0
Disabled
Disabled From version 6.0.0: this feature is behind the --harmony runtime flag.
splitChrome Full support 50Edge Full support YesFirefox Full support 49IE No support NoOpera Full support YesSafari Full support YesWebView Android Full support YesChrome Android Full support YesEdge Mobile Full support YesFirefox Android Full support 49Opera Android Full support YesSafari iOS Full support YesSamsung Internet Android Full support Yesnodejs Full support 6.0.0
toPrimitiveChrome Full support 48Edge Full support 15Firefox Full support 44IE No support NoOpera Full support YesSafari Full support YesWebView Android Full support YesChrome Android Full support YesEdge Mobile Full support YesFirefox Android Full support 44Opera Android Full support YesSafari iOS Full support YesSamsung Internet Android Full support Yesnodejs Full support 6.0.0
toSource
Non-standard
Chrome No support NoEdge No support NoFirefox Full support 36IE No support NoOpera No support NoSafari No support NoWebView Android No support NoChrome Android No support NoEdge Mobile No support NoFirefox Android Full support 36Opera Android No support NoSafari iOS No support NoSamsung Internet Android No support Nonodejs No support No
toStringChrome Full support 38Edge Full support 12Firefox Full support 36IE No support NoOpera Full support 25Safari Full support 9WebView Android Full support YesChrome Android Full support 38Edge Mobile Full support YesFirefox Android Full support 36Opera Android Full support 25Safari iOS Full support 9Samsung Internet Android Full support Yesnodejs Full support Yes
toStringTagChrome Full support 49Edge Full support 15Firefox Full support 51IE No support NoOpera Full support YesSafari Full support YesWebView Android Full support YesChrome Android Full support YesEdge Mobile Full support YesFirefox Android Full support 51Opera Android Full support YesSafari iOS Full support YesSamsung Internet Android Full support Yesnodejs Full support 6.0.0
Full support 6.0.0
Full support 4.0.0
Disabled
Disabled From version 4.0.0: this feature is behind the --harmony runtime flag.
unscopablesChrome Full support 38Edge Full support YesFirefox Full support 48IE No support NoOpera Full support YesSafari Full support 9WebView Android Full support YesChrome Android Full support YesEdge Mobile Full support YesFirefox Android Full support 48Opera Android Full support YesSafari iOS Full support 9Samsung Internet Android Full support Yesnodejs Full support 0.12
valueOfChrome Full support 38Edge Full support 12Firefox Full support 36IE No support NoOpera Full support 25Safari Full support 9WebView Android Full support YesChrome Android Full support 38Edge Mobile Full support YesFirefox Android Full support 36Opera Android Full support 25Safari iOS Full support 9Samsung Internet Android Full support Yesnodejs Full support Yes
@@toPrimitiveChrome ? Edge ? Firefox Full support 44IE No support NoOpera ? Safari ? WebView Android ? Chrome Android ? Edge Mobile ? Firefox Android Full support 44Opera Android ? Safari iOS ? Samsung Internet Android ? nodejs ?

Legend

Full support  
Full support
No support  
No support
Compatibility unknown  
Compatibility unknown
Experimental. Expect behavior to change in the future.
Experimental. Expect behavior to change in the future.
Non-standard. Expect poor cross-browser support.
Non-standard. Expect poor cross-browser support.
See implementation notes.
See implementation notes.
User must explicitly enable this feature.
User must explicitly enable this feature.

Zobacz również

Autorzy i etykiety dokumentu

Autorzy tej strony: kjarmicki
Ostatnia aktualizacja: kjarmicki,