openharmony 鸿蒙 arkts-apis-arkts-collections-Map

2026-08-25 浏览 (1)

Class (Map)

A non-linear data structure.

NOTE

  • The initial APIs of this module are supported since API version 12. Newly added APIs will be marked with a superscript to indicate their earliest API version.

  • This module can be imported only to ArkTS files (with the file name extension .ets).

This section uses the following to identify the use of generics:

  • K: key.
  • V: value.

The K and V types must be any of the sendable data types.

Decorator: @Sendable

Modules to Import

import { collections } from '@kit.ArkTS';

Properties

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.Utils.Lang

NameTypeRead OnlyOptionalDescription
sizenumberYesNoNumber of elements in a map.

constructor

constructor(entries?: readonly (readonly [K, V])[]|null)

A constructor used to create an ArkTS map.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.Utils.Lang

Parameters

NameTypeMandatoryDescription
entriesreadonly (readonly [K, V])[] |nullNoArray containing key-value pairs, or iterator object. The default value is null, indicating that an empty map is created.

Error codes

For details about the error codes, see Universal Error Codes and Utils Error Codes.

IDError Message
401Parameter error.
10200012The ArkTS Map's constructor cannot be directly invoked.

Example

// Positive example 1:
const myMap = new collections.Map<number, number>();

// Positive example 2:
const myMap = new collections.Map<number, string>([
  [1, "one"],
  [2, "two"],
  [3, "three"],
]);

// Negative example:
@Sendable
class SharedClass {
  constructor() {
  }
}
let sObj = new SharedClass();
const myMap1: collections.Map<number, SharedClass> = new collections.Map<number, SharedClass>([[1, sObj]]);
// Type arguments of generic "Sendable" type must be a "Sendable" data type (arkts-sendable-generic-types)
let obj = new Object();
const myMap2: collections.Map<number, Object> = new collections.Map<number, Object>([[1, obj]]);

constructor

constructor(iterable: Iterable<readonly [K, V]>)

A constructor used to create an ArkTS map.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.Utils.Lang

Parameters

NameTypeMandatoryDescription
iterableIterable<readonly [K, V]>YesObject used to construct the ArkTS map.

Error codes

For details about the error codes, see Universal Error Codes and Utils Error Codes.

IDError Message
401Parameter error.
10200012The ArkTS Map's constructor cannot be directly invoked.

Example

const mapper = new Map([
  ['1', 'a'],
  ['2', 'b'],
]);
let newMap = new collections.Map<string, string>(mapper.entries());
console.info(newMap.get('1')); // Expected output: a
console.info(newMap.get('2')); // Expected output: b

entries

entries(): IterableIterator<[K, V]>

Returns a map iterator object that contains the key-value pair of each element in this ArkTS map.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.Utils.Lang

Return value

TypeDescription
IterableIterator<[K, V]>Map iterator object.

Error codes

For details about the error codes, see Utils Error Codes.

IDError Message
10200011The entries method cannot be bound with non-sendable.
10200201Concurrent modification error.

Example

// Example 1:
const myMap = new collections.Map<number, string>([
  [0, "foo"],
  [1, "bar"]
]);

const iterator = myMap.entries();
// Expected output: 0, foo
console.info(iterator.next().value);
// Expected output: 1, bar
console.info(iterator.next().value);

// Example 2:
const myMap: collections.Map<number, string> = new collections.Map<number, string>([
  [0, "one"],
  [1, "two"],
  [2, "three"],
  [3, "four"]
]);
const entriesIter: IterableIterator<[number, string]> = myMap.entries();
for (const entry of entriesIter) {
  if (entry[1].startsWith('t')) {
    myMap.delete(entry[0]);
  }
}
// Expected output: 2
console.info("size:" + myMap.size);

keys

keys(): IterableIterator<K>

Returns a map iterator object that contains the key of each element in this ArkTS map.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.Utils.Lang

Return value

TypeDescription
IterableIterator<K>Map iterator object.

Error codes

For details about the error codes, see Utils Error Codes.

IDError Message
10200011The keys method cannot be bound with non-sendable.
10200201Concurrent modification error.

Example

const myMap = new collections.Map<number, string>([
  [0, "foo"],
  [1, "bar"]
]);

const iterator = myMap.keys();
// Expected output: 0
console.info(iterator.next().value);
// Expected output: 1
console.info(iterator.next().value);

values

values(): IterableIterator<V>

Returns a map iterator object that contains the value of each element in this ArkTS map.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.Utils.Lang

Return value

TypeDescription
IterableIterator<V>Map iterator object.

Error codes

For details about the error codes, see Utils Error Codes.

IDError Message
10200011The values method cannot be bound with non-sendable.
10200201Concurrent modification error.

Example

const myMap = new collections.Map<number, string>([
  [0, "foo"],
  [1, "bar"]
]);

const iterator = myMap.values();
// Expected output: "foo"
console.info(iterator.next().value);
// Expected output: "bar"
console.info(iterator.next().value);

clear

clear(): void

Removes all elements from this ArkTS map.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.Utils.Lang

Error codes

For details about the error codes, see Utils Error Codes.

IDError Message
10200011The clear method cannot be bound with non-sendable.
10200201Concurrent modification error.

Example

const myMap = new collections.Map<number, string>([
  [0, "foo"],
  [1, "bar"]
]);
// Expected output: 2
console.info("size:" + myMap.size);
myMap.clear();
// Expected output: 0
console.info("size:" + myMap.size);

delete

delete(key: K): boolean

Deletes a specified key from this ArkTS map.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.Utils.Lang

Parameters

NameTypeMandatoryDescription
keyKYesKey to delete.

Return value

TypeDescription
booleanOperation result. The value true is returned if the key exists and has been deleted; otherwise, false is returned.

Error codes

For details about the error codes, see Universal Error Codes and Utils Error Codes.

IDError Message
401Parameter error.
10200011The delete method cannot be bound with non-sendable.
10200201Concurrent modification error.

Example

const myMap = new collections.Map<string, string>([
  ["hello", "world"],
]);
// Expected result: true
console.info("result:" + myMap.delete("hello"));
// Expected result: false
console.info("result:" + myMap.has("hello"));
// Expected result: false
console.info("result:" + myMap.delete("hello"));

forEach

forEach(callbackFn: (value: V, key: K, map: Map<K, V>) => void): void

Calls a callback function for each key-value pair in this ArkTS map.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.Utils.Lang

Parameters

NameTypeMandatoryDescription
callbackFn(value: V, key: K, map: Map<K, V>) => voidYesCallback function to run for each key-value pair.

callbackFn parameters

NameTypeMandatoryDescription
valueVNoValue of the element that is currently traversed.
keyKNoKey of the element that is currently traversed.
mapMap<K, V>NoCurrent map object.

Error codes

For details about the error codes, see Universal Error Codes and Utils Error Codes.

IDError Message
401Parameter error.
10200011The forEach method cannot be bound with non-sendable.
10200201Concurrent modification error.

Example

// Positive example:
new collections.Map<string, number>([
  ['foo', 0],
  ['bar', 1],
  ['baz', 2],
]).forEach((value, key, map) => {
  console.info(`m[${key}] = ${value}`);
});

// Negative example:
new collections.Map<string, number>([
  ['foo', 0],
  ['bar', 1],
  ['baz', 2],
]).forEach((value, key, map) => {
  // Throw exception `Concurrent modification error.`
  map.delete(key);
});

get

get(key: K): V|undefined

Obtains the value of the specified key in this ArkTS map.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.Utils.Lang

Parameters

NameTypeMandatoryDescription
keyKYesTarget key.

Return value

TypeDescription
V |undefinedValue obtained. If the key is not found, undefined is returned.

Error codes

For details about the error codes, see Universal Error Codes and Utils Error Codes.

IDError Message
401Parameter error.
10200011The get method cannot be bound with non-sendable.
10200201Concurrent modification error.

Example

const myMap = new collections.Map<string, string>([
  ["hello", "world"],
]);
// Expected output: "world"
console.info(myMap.get("hello"));
// Expected output: undefined
console.info(myMap.get("hel"));

has

has(key: K): boolean

Checks whether a key exists in this ArkTS map.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.Utils.Lang

Parameters

NameTypeMandatoryDescription
keyKYesTarget key.

Return value

TypeDescription
booleanCheck result. The value true is returned if the key exists; otherwise, false is returned.

Error codes

For details about the error codes, see Universal Error Codes and Utils Error Codes.

IDError Message
401Parameter error.
10200011The has method cannot be bound with non-sendable.
10200201Concurrent modification error.

Example

const myMap = new collections.Map<string, string>([
  ["hello", "world"],
]);
// Expected output: true
console.info("result:" + myMap.has("hello"));
// Expected output: false
console.info("result:" + myMap.has("world"));

set

set(key: K, value: V): Map<K, V>

Adds or updates a key-value pair to this ArkTS map.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.Utils.Lang

Parameters

NameTypeMandatoryDescription
keyKYesTarget key.
valueVYesTarget value.

Return value

TypeDescription
Map<K, V>New map obtained.

Error codes

For details about the error codes, see Universal Error Codes and Utils Error Codes.

IDError Message
401Parameter error.
10200011The set method cannot be bound with non-sendable.
10200201Concurrent modification error.

Example

// Positive example:
const myMap = new collections.Map<string, string>();
myMap.set("foo", "bar");

// Negative example:
let obj = new Object();
const myMap: collections.Map<string, Object> = new collections.Map<string, Object>();
// Type arguments of generic "Sendable" type must be a "Sendable" data type (arkts-sendable-generic-types)
myMap.set("foo", obj);

[Symbol.iterator]

[Symbol.iterator](): IterableIterator<[K, V]>

Returns an iterator, each item of which is a JavaScript object.

NOTE

This API cannot be used in .ets files.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.Utils.Lang

Return value

TypeDescription
IterableIterator<[K, V]>Iterator obtained.

Error codes

For details about the error codes, see Utils Error Codes.

IDError Message
10200011The Symbol.iterator method cannot be bound.

Example

let map = new collections.Map<number, string>([
    [0, "one"],
    [1, "two"],
    [2, "three"],
    [3, "four"]
]);

let keys = Array.from(map.keys());
for (let key of keys) {
  console.info("key:" + key);
  console.info("value:" + map.get(key));
}

你可能感兴趣的鸿蒙文章

openharmony 鸿蒙 arkts-apis-arkts-collections-Float32Array

openharmony 鸿蒙 arkts-apis-arkts-collections-ArrayBuffer

openharmony 鸿蒙 js-apis-lightweightset

openharmony 鸿蒙 errorcode-source-obfuscation

openharmony 鸿蒙 arkts-apis-arkts-utils-ASON

openharmony 鸿蒙 arkts-apis-arkts-collections-Uint8ClampedArray

openharmony 鸿蒙 errorcode-tsc

openharmony 鸿蒙 js-apis-deque

openharmony 鸿蒙 arkts-apis-arkts-collections-BitVector

openharmony 鸿蒙 js-apis-worker

  • 所属分类： 后端技术
  • 本文标签： 软件 鸿蒙
  • 版权声明： 本文链接 https://seaxiang.com/blog/CfHuV9VF