Baza wiedzyCentrum egzaminacyjne
PLPolski
Wybierz język13

CKTIS / JavaScript

Symbol.toPrimitive — własna konwersja obiektu do wartości prymitywnej

Symbol.toPrimitive jest standardowym symbolem wskazującym metodę konwersji obiektu do wartości prymitywnej. Metoda otrzymuje wskazówkę "string", "number" albo "default" i ma pierwszeństwo przed zwykłym użyciem valueOf() oraz toString().

Wersja: ECMAScript and Web APIs; exact feature edition and browser support reviewed per entry; Node 24 in repository does not prove browser API support

Składnia

const value = { [Symbol.toPrimitive](hint) { return hint === "string" ? "label" : 10; } };

Symbol.toPrimitive to symbol będący kluczem metody, a nie funkcja konwertująca. Zdefiniuj [Symbol.toPrimitive](hint) { ... }, aby sterować konwersją obiektu do wartości prymitywnej. Metoda jest wywoływana z konwertowanym obiektem jako this.

Argument hint ma wartość "string" przy String(obj), "number" przy Number(obj) oraz "default" przy dodawaniu obj + 3. Wskazówka nie wymusza typu wyniku: metoda musi zwrócić wartość prymitywną, a otaczająca operacja może ją dalej konwertować. Zwrócenie obiektu powoduje TypeError, bez próby użycia valueOf() lub toString().

Jeśli właściwość ma wartość undefined albo null, stosowana jest zwykła konwersja: dla wskazówki tekstowej najpierw toString(), potem valueOf(); dla liczbowej odwrotnie. Bez wskazówki zwykła konwersja przyjmuje wariant liczbowy. Każda inna wartość właściwości, której nie można wywołać, powoduje TypeError.

W przykładzie String(amount) daje Amount(7), Number(amount) daje 7, a amount + 3 daje 10. Obsłuż świadomie wszystkie trzy wskazówki, aby uniknąć zaskakujących wyników operatora +.

Przykłady

const amount = {
  value: 7,
  [Symbol.toPrimitive](hint) {
    if (hint === "string") return `Amount(${this.value})`;
    return this.value;
  }
};

console.log(String(amount));
console.log(Number(amount));
console.log(amount + 3);

Wynik

Amount(7)
7
10

Wyświetlony kod i zadeklarowany wynik zweryfikowano w odizolowanym środowisku metodą zapisaną w dowodzie weryfikacji tej dokładnej wersji.

Źródła