Map

Объект Map хранит пары ключ-значение и запоминает исходный порядок вставки ключей. Любое значение (как объекты, так и примитивные значения) может быть использовано в качестве ключа или значения.

Попробуйте

const map = new Map();

map.set("a", 1);
map.set("b", 2);
map.set("c", 3);

console.log(map.get("a"));
// Expected output: 1

map.set("a", 97);

console.log(map.get("a"));
// Expected output: 97

console.log(map.size);
// Expected output: 3

map.delete("b");

console.log(map.size);
// Expected output: 2

Описание

Объекты Map представляют собой коллекции пар ключ-значение. Ключ в Map может встречаться только один раз; он уникален в коллекции Map. Объект Map итерируется по парам ключ-значение — цикл for...of возвращает массив из 2 элементов [key, value] для каждой итерации. Итерация происходит в порядке вставки, который соответствует порядку, в котором каждая пара ключ-значение была впервые вставлена в Map с помощью метода set() (то есть, когда вызывался set(), ключа с таким же значением еще не было в Map).

Спецификация требует, чтобы реализация Map «в среднем обеспечивала время доступа, которое является сублинейным относительно числа элементов в коллекции». Следовательно, она может быть представлена внутри как хеш-таблица (с поиском O(1)), дерево поиска (с поиском O(log(N))) или любая другая структура данных, при условии, что сложность лучше, чем O(N).

Равенство ключей

Равенство значений основано на алгоритме SameValueZero. (Раньше использовался SameValue, который рассматривал 0 и -0 как разные. Проверьте совместимость с браузерами.) Это означает, что NaN считается тем же, что и NaN (хотя NaN !== NaN), а все остальные значения считаются равными в соответствии с семантикой оператора ===. Кроме того, для ключей-объектов равенство основано на идентичности объекта. Они сравниваются по ссылке, а не по значению. Примеры см. в разделе Использование объекта Map.

Объекты (Objects) против Map

Object похож на Map—оба позволяют устанавливать ключи для значений, извлекать эти значения, удалять ключи и определять, хранится ли что-либо по ключу. По этой причине (и из-за отсутствия встроенных альтернатив) Object исторически использовался как Map.

Однако есть важные различия, которые делают Map предпочтительным в некоторых случаях:

Установка свойств объекта

Установка свойств объекта также работает для объектов Map и может вызвать значительное замешательство.

Таким образом, кажется, что это работает:

const wrongMap = new Map();
wrongMap["bla"] = "blaa";
wrongMap["bla2"] = "blaaa2";

console.log(wrongMap); // Map { bla: 'blaa', bla2: 'blaaa2' }

Но такой способ установки свойства не взаимодействует со структурой данных Map. Он использует возможности обычного объекта. Значение 'bla' не сохраняется в Map для запросов. Другие операции с данными завершаются неудачей:

wrongMap.has("bla"); // false
wrongMap.delete("bla"); // false
console.log(wrongMap); // Map { bla: 'blaa', bla2: 'blaaa2' }

Правильное использование для хранения данных в Map — это метод set(key, value).

const contacts = new Map();
contacts.set("Jessie", { phone: "213-555-1234", address: "123 N 1st Ave" });
contacts.has("Jessie"); // true
contacts.get("Hilary"); // undefined
contacts.set("Hilary", { phone: "617-555-4321", address: "321 S 2nd St" });
contacts.get("Jessie"); // {phone: "213-555-1234", address: "123 N 1st Ave"}
contacts.delete("Raymond"); // false
contacts.delete("Jessie"); // true
console.log(contacts.size); // 1

Браузерные API, похожие на Map

Браузерные объекты, похожие на Map (или «maplike-объекты»), — это интерфейсы Web API, которые во многом ведут себя как Map.

Как и в Map, записи могут итерироваться в том же порядке, в котором они были добавлены в объект. Объекты, похожие на Map, и Map также имеют свойства и методы с одинаковыми именами и поведением. Однако, в отличие от Map, они допускают только определённые предопределённые типы для ключей и значений каждой записи.

Разрешённые типы устанавливаются в определении IDL спецификации. Например, RTCStatsReport — это объект, похожий на Map, который должен использовать строки для ключей и объекты для значений. Это определено в IDL спецификации ниже:

interface RTCStatsReport {
  readonly maplike<DOMString, object>;
};

Объекты, похожие на Map, бывают либо доступными только для чтения (read-only), либо доступными для чтения и записи (read-writable) (см. ключевое слово readonly в IDL выше).

• Объекты, похожие на Map, доступные только для чтения, имеют свойство size и методы: entries(), forEach(), get(), has(), keys(), values(), и [Symbol.iterator]().
• Объекты, похожие на Map, доступные для записи, дополнительно имеют методы: clear(), delete(), и set().

Методы и свойства имеют то же поведение, что и эквивалентные сущности в Map, за исключением ограничения на типы ключей и значений.

Ниже приведены примеры браузерных объектов, похожих на Map, доступных только для чтения:

• AudioParamMap
• CSSFontFeatureValuesMap
• EventCounts
• KeyboardLayoutMap
• MIDIInputMap
• MIDIOutputMap
• RTCStatsReport

Конструктор

Map()

Создает новый объект Map.

Статические свойства

Map[Symbol.species]

Функция-конструктор, используемая для создания производных объектов.

Статические методы

Map.groupBy()

Группирует элементы заданного итерируемого объекта, используя значения, возвращаемые предоставленной функцией обратного вызова. Конечный возвращаемый Map использует уникальные значения из тестовой функции в качестве ключей, которые могут быть использованы для получения массива элементов в каждой группе.

Свойства экземпляра

Эти свойства определены в Map.prototype и используются всеми экземплярами Map.

Map.prototype.constructor

Функция-конструктор, которая создала объект экземпляра. Для экземпляров Map начальным значением является конструктор Map.

Map.prototype.size

Возвращает количество пар ключ/значение в объекте Map.

Map.prototype[Symbol.toStringTag]

Начальным значением свойства [Symbol.toStringTag] является строка "Map". Это свойство используется в Object.prototype.toString().

Методы экземпляра

Map.prototype.clear()

Удаляет все пары ключ-значение из объекта Map.

Map.prototype.delete()

Удаляет запись, указанную ключом, из этого Map.

Map.prototype.entries()

Возвращает новый объект Iterator, который содержит массив из двух элементов [key, value] для каждого элемента в объекте Map в порядке вставки.

Map.prototype.forEach()

Вызывает callbackFn один раз для каждой пары ключ-значение, присутствующей в объекте Map, в порядке вставки. Если параметр thisArg предоставлен forEach, он будет использоваться в качестве значения this для каждого обратного вызова.

Map.prototype.get()

Возвращает значение, соответствующее ключу в этом Map, или undefined, если такого ключа нет.

Map.prototype.getOrInsert()

Возвращает значение, соответствующее указанному ключу в этом Map. Если ключ отсутствует, он вставляет новую запись с ключом и заданным значением по умолчанию и возвращает вставленное значение.

Map.prototype.getOrInsertComputed()

Возвращает значение, соответствующее указанному ключу в этом Map. Если ключ отсутствует, он вставляет новую запись с ключом и значением по умолчанию, вычисленным из заданного обратного вызова, и возвращает вставленное значение.

Map.prototype.has()

Возвращает логическое значение, указывающее, существует ли запись с указанным ключом в этом Map или нет.

Map.prototype.keys()

Возвращает новый объект Iterator, который содержит ключи для каждого элемента в объекте Map в порядке вставки.

Map.prototype.set()

Добавляет новую запись с указанным ключом и значением в этот Map или обновляет существующую запись, если ключ уже существует.

Map.prototype.values()

Возвращает новый объект Iterator, который содержит значения для каждого элемента в объекте Map в порядке вставки.

Map.prototype[Symbol.iterator]()

Возвращает новый объект Iterator, который содержит массив из двух элементов [key, value] для каждого элемента в объекте Map в порядке вставки.

Примеры

Использование объекта Map

const myMap = new Map();

const keyString = "a string";
const keyObj = {};
const keyFunc = () => {};

// setting the values
myMap.set(keyString, "value associated with 'a string'");
myMap.set(keyObj, "value associated with keyObj");
myMap.set(keyFunc, "value associated with keyFunc");

console.log(myMap.size); // 3

// getting the values
console.log(myMap.get(keyString)); // "value associated with 'a string'"
console.log(myMap.get(keyObj)); // "value associated with keyObj"
console.log(myMap.get(keyFunc)); // "value associated with keyFunc"

console.log(myMap.get("a string")); // "value associated with 'a string'", because keyString === 'a string'
console.log(myMap.get({})); // undefined, because keyObj !== {}
console.log(myMap.get(() => {})); // undefined, because keyFunc !== () => {}

Использование NaN в качестве ключей Map

NaN также может использоваться в качестве ключа. Несмотря на то, что каждый NaN не равен самому себе (NaN !== NaN истинно), следующий пример работает, потому что NaN неотличимы друг от друга:

const myMap = new Map();
myMap.set(NaN, "not a number");

myMap.get(NaN);
// "not a number"

const otherNaN = Number("foo");
myMap.get(otherNaN);
// "not a number"

Итерация Map с помощью for...of

Map можно итерировать с помощью цикла for...of:

const myMap = new Map();
myMap.set(0, "zero");
myMap.set(1, "one");

for (const [key, value] of myMap) {
  console.log(`${key} = ${value}`);
}
// 0 = zero
// 1 = one

for (const key of myMap.keys()) {
  console.log(key);
}
// 0
// 1

for (const value of myMap.values()) {
  console.log(value);
}
// zero
// one

for (const [key, value] of myMap.entries()) {
  console.log(`${key} = ${value}`);
}
// 0 = zero
// 1 = one

Итерация Map с помощью forEach()

Map можно итерировать с помощью метода forEach():

myMap.forEach((value, key) => {
  console.log(`${key} = ${value}`);
});
// 0 = zero
// 1 = one

Связь с объектами Array

const kvArray = [
  ["key1", "value1"],
  ["key2", "value2"],
];

// Use the regular Map constructor to transform a 2D key-value Array into a map
const myMap = new Map(kvArray);

console.log(myMap.get("key1")); // "value1"

// Use Array.from() to transform a map into a 2D key-value Array
console.log(Array.from(myMap)); // Will show you exactly the same Array as kvArray

// A succinct way to do the same, using the spread syntax
console.log([...myMap]);

// Or use the keys() or values() iterators, and convert them to an array
console.log(Array.from(myMap.keys())); // ["key1", "key2"]

Клонирование и слияние Map

Подобно Array, Map могут быть клонированы:

const original = new Map([[1, "one"]]);

const clone = new Map(original);

console.log(clone.get(1)); // one
console.log(original === clone); // false (useful for shallow comparison)

Map могут быть объединены, сохраняя уникальность ключей:

const first = new Map([
  [1, "one"],
  [2, "two"],
  [3, "three"],
]);

const second = new Map([
  [1, "uno"],
  [2, "dos"],
]);

// Merge two maps. The last repeated key wins.
// Spread syntax essentially converts a Map to an Array
const merged = new Map([...first, ...second]);

console.log(merged.get(1)); // uno
console.log(merged.get(2)); // dos
console.log(merged.get(3)); // three

Map также могут быть объединены с массивами:

const first = new Map([
  [1, "one"],
  [2, "two"],
  [3, "three"],
]);

const second = new Map([
  [1, "uno"],
  [2, "dos"],
]);

// Merge maps with an array. The last repeated key wins.
const merged = new Map([...first, ...second, [1, "un"]]);

console.log(merged.get(1)); // un
console.log(merged.get(2)); // dos
console.log(merged.get(3)); // three

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

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

См. также

• Полифил для Map в core-js
• Полифил es-shims для Map
• Set
• WeakMap
• WeakSet