Symbol.toPrimitive

Статическое свойство данных Symbol.toPrimitive представляет собой общеизвестный символ Symbol.toPrimitive. Все алгоритмы приведения типов ищут этот символ в объектах для метода, который принимает предпочтительный тип и возвращает примитивное представление объекта, прежде чем использовать методы valueOf() и toString() объекта.

Попробуйте

const object = {
  [Symbol.toPrimitive](hint) {
    if (hint === "number") {
      return 42;
    }
    return null;
  },
};

console.log(+object);
// Expected output: 42

Значение

Общеизвестный символ Symbol.toPrimitive.

Описание

С помощью свойства Symbol.toPrimitive (используемого как значение функции) объект может быть преобразован в примитивное значение. Функция вызывается со строковым аргументом hint, который указывает предпочтительный тип результирующего примитивного значения. Аргумент hint может быть одним из "number", "string" и "default".

Подсказка "number" используется алгоритмами числового приведения. Подсказка "string" используется алгоритмом строкового приведения. Подсказка "default" используется алгоритмом примитивного приведения. hint действует только как слабый сигнал предпочтения, и реализация вольна игнорировать его (как это делает Symbol.prototype[Symbol.toPrimitive]()). Язык не обеспечивает согласованность между hint и типом результата, хотя [Symbol.toPrimitive]() должен возвращать примитив, иначе будет выдана ошибка TypeError.

Объекты без свойства [Symbol.toPrimitive] преобразуются в примитивы путём вызова методов valueOf() и toString() в разном порядке, что более подробно объясняется в разделе приведение типов. [Symbol.toPrimitive]() позволяет полностью контролировать процесс преобразования примитивов. Например, Date.prototype[Symbol.toPrimitive]() обрабатывает "default" так, как если бы это был "string", и вызывает toString() вместо valueOf(). Symbol.prototype[Symbol.toPrimitive]() игнорирует подсказку и всегда возвращает символ, что означает, что даже в строковых контекстах Symbol.prototype.toString() не будет вызван, и объекты Symbol всегда должны быть явно преобразованы в строки через String().

Примеры

Изменение примитивных значений, преобразованных из объекта

Следующий пример описывает, как свойство Symbol.toPrimitive может изменить примитивное значение, преобразованное из объекта.

// An object without Symbol.toPrimitive property.
const obj1 = {};
console.log(+obj1); // NaN
console.log(`${obj1}`); // "[object Object]"
console.log(obj1 + ""); // "[object Object]"

// An object with Symbol.toPrimitive property.
const obj2 = {
  [Symbol.toPrimitive](hint) {
    if (hint === "number") {
      return 10;
    }
    if (hint === "string") {
      return "hello";
    }
    return true;
  },
};
console.log(+obj2); // 10        — hint is "number"
console.log(`${obj2}`); // "hello"   — hint is "string"
console.log(obj2 + ""); // "true"    — hint is "default"

Спецификации

Совместимость с браузерами

Смотрите также

• Полифил Symbol.toPrimitive в core-js
• Date.prototype[Symbol.toPrimitive]()
• Symbol.prototype[Symbol.toPrimitive]()
• Object.prototype.toString()
• Object.prototype.valueOf()