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.