1# Class (Map) 2<!--Kit: ArkTS--> 3<!--Subsystem: CommonLibrary--> 4<!--Owner: @lijiamin2025--> 5<!--Designer: @weng-changcheng--> 6<!--Tester: @kirl75; @zsw_zhushiwei--> 7<!--Adviser: @ge-yafang--> 8> **说明：** 9> 10> 本模块首批接口从API version 12开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 11> 12> 此模块仅支持在ArkTS文件（文件后缀为.ets）中导入使用。 13 14一种非线性数据结构。 15 16文档中存在泛型的使用，涉及以下泛型标记符： 17 18- K：Key，键 19- V：Value，值 20 21K和V类型都需为[Sendable支持的数据类型](../../arkts-utils/arkts-sendable.md#sendable支持的数据类型)。 22 23**装饰器类型：**\@Sendable 24 25## 导入模块 26 27```ts 28import { collections } from '@kit.ArkTS'; 29``` 30 31## 属性 32 33**原子化服务API**：从API version 12 开始，该接口支持在原子化服务中使用。 34 35**系统能力：** SystemCapability.Utils.Lang 36 37| 名称 | 类型 | 只读 | 可选 | 说明 | 38| ---- | ------ | ---- | ---- | --------------- | 39| size | number | 是 | 否 | Map的元素个数。 | 40 41 42## constructor 43constructor(entries?: readonly (readonly [K, V])[] | null) 44 45构造函数，用于创建ArkTS Map对象。 46 47**原子化服务API**：从API version 12 开始，该接口支持在原子化服务中使用。 48 49**系统能力：** SystemCapability.Utils.Lang 50 51**参数：** 52 53| 参数名 | 类型 | 必填 | 说明 | 54| ------- | ------ | ---- | ------------------------------------------------------------ | 55| entries | readonly (readonly [K, V])[] \| null | 否 | 键值对数组或其它可迭代对象。默认值为null，创建一个空Map对象。 | 56 57**错误码：** 58 59以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)和[语言基础类库错误码](errorcode-utils.md)。 60 61| 错误码ID | 错误信息 | 62| -------- | ------------------------------------------------------- | 63| 401 | Parameter error. | 64| 10200012 | The ArkTS Map's constructor cannot be directly invoked. | 65 66**示例：** 67 68```ts 69// 正例1： 70const myMap = new collections.Map<number, number>(); 71``` 72 73```ts 74// 正例2： 75const myMap = new collections.Map<number, string>([ 76 [1, "one"], 77 [2, "two"], 78 [3, "three"], 79]); 80``` 81 82<!--code_no_check--> 83```ts 84// 反例： 85@Sendable 86class SharedClass { 87 constructor() { 88 } 89} 90let sObj = new SharedClass(); 91const myMap1: collections.Map<number, SharedClass> = new collections.Map<number, SharedClass>([[1, sObj]]); 92// Type arguments of generic "Sendable" type must be a "Sendable" data type (arkts-sendable-generic-types) 93let obj = new Object(); 94const myMap2: collections.Map<number, Object> = new collections.Map<number, Object>([[1, obj]]); 95``` 96 97## entries 98entries(): IterableIterator<[K, V]> 99 100返回一个Map迭代器对象，该对象包含了此Map中的每个元素的[key, value]对。 101 102**原子化服务API**：从API version 12 开始，该接口支持在原子化服务中使用。 103 104**系统能力：** SystemCapability.Utils.Lang 105 106**返回值：** 107 108| 类型 | 说明 | 109| ------------------------------ | ----------------------- | 110| IterableIterator<[K, V]> | 返回一个Map迭代器对象。 | 111 112**错误码：** 113 114以下错误码的详细介绍请参见[语言基础类库错误码](errorcode-utils.md)。 115 116| 错误码ID | 错误信息 | 117| -------- | ----------------------------------------------------- | 118| 10200011 | The entries method cannot be bound with non-sendable. | 119| 10200201 | Concurrent modification error. | 120 121**示例：** 122 123```ts 124// 例1： 125const myMap = new collections.Map<number, string>([ 126 [0, "foo"], 127 [1, "bar"] 128]); 129 130const iterator = myMap.entries(); 131// Expected output: 0, foo 132console.info(iterator.next().value); 133// Expected output: 1, bar 134console.info(iterator.next().value); 135``` 136 137```ts 138// 例2： 139const myMap: collections.Map<number, string> = new collections.Map<number, string>([ 140 [0, "one"], 141 [1, "two"], 142 [2, "three"], 143 [3, "four"] 144]); 145const entriesIter: IterableIterator<[number, string]> = myMap.entries(); 146for (const entry of entriesIter) { 147 if (entry[1].startsWith('t')) { 148 myMap.delete(entry[0]); 149 } 150} 151// Expected output: 2 152console.info("size:" + myMap.size); 153``` 154 155## keys 156keys(): IterableIterator\<K> 157 158返回一个Map迭代器对象，该对象包含了此Map中每个元素的键。 159 160**原子化服务API**：从API version 12 开始，该接口支持在原子化服务中使用。 161 162**系统能力：** SystemCapability.Utils.Lang 163 164**返回值：** 165 166| 类型 | 说明 | 167| ------------------------- | ----------------------- | 168| IterableIterator<K> | 返回一个Map迭代器对象。 | 169 170**错误码：** 171 172以下错误码的详细介绍请参见[语言基础类库错误码](errorcode-utils.md)。 173 174| 错误码ID | 错误信息 | 175| -------- | -------------------------------------------------- | 176| 10200011 | The keys method cannot be bound with non-sendable. | 177| 10200201 | Concurrent modification error. | 178 179**示例：** 180 181```ts 182const myMap = new collections.Map<number, string>([ 183 [0, "foo"], 184 [1, "bar"] 185]); 186 187const iterator = myMap.keys(); 188// Expected output: 0 189console.info(iterator.next().value); 190// Expected output: 1 191console.info(iterator.next().value); 192``` 193 194## values 195values(): IterableIterator\<V> 196 197返回一个Map迭代器对象，该对象包含此Map中每个元素的值。 198 199**原子化服务API**：从API version 12 开始，该接口支持在原子化服务中使用。 200 201**系统能力：** SystemCapability.Utils.Lang 202 203**返回值：** 204 205| 类型 | 说明 | 206| ------------------------- | ----------------------- | 207| IterableIterator<V> | 返回一个Map迭代器对象。 | 208 209**错误码：** 210 211以下错误码的详细介绍请参见[语言基础类库错误码](errorcode-utils.md)。 212 213| 错误码ID | 错误信息 | 214| -------- | ---------------------------------------------------- | 215| 10200011 | The values method cannot be bound with non-sendable. | 216| 10200201 | Concurrent modification error. | 217 218**示例：** 219 220```ts 221const myMap = new collections.Map<number, string>([ 222 [0, "foo"], 223 [1, "bar"] 224]); 225 226const iterator = myMap.values(); 227// Expected output: "foo" 228console.info(iterator.next().value); 229// Expected output: "bar" 230console.info(iterator.next().value); 231``` 232 233## clear 234clear(): void 235 236删除该Map中的所有元素。 237 238**原子化服务API**：从API version 12 开始，该接口支持在原子化服务中使用。 239 240**系统能力：** SystemCapability.Utils.Lang 241 242**错误码：** 243 244以下错误码的详细介绍请参见[语言基础类库错误码](errorcode-utils.md)。 245 246| 错误码ID | 错误信息 | 247| -------- | --------------------------------------------------- | 248| 10200011 | The clear method cannot be bound with non-sendable. | 249| 10200201 | Concurrent modification error. | 250 251**示例：** 252 253```ts 254const myMap = new collections.Map<number, string>([ 255 [0, "foo"], 256 [1, "bar"] 257]); 258// Expected output: 2 259console.info("size:" + myMap.size); 260myMap.clear(); 261// Expected output: 0 262console.info("size:" + myMap.size); 263``` 264 265## delete 266delete(key: K): boolean 267 268删除该Map中指定元素。 269 270**原子化服务API**：从API version 12 开始，该接口支持在原子化服务中使用。 271 272**系统能力：** SystemCapability.Utils.Lang 273 274**参数：** 275 276| 参数名 | 类型 | 必填 | 说明 | 277| ------ | ---- | ---- | ---------------- | 278| key | K | 是 | 待删除元素的键。 | 279 280**返回值：** 281 282| 类型 | 说明 | 283| ------- | ------------------------------------------------------------ | 284| boolean | 如果元素存在并已被删除，则为true；否则该元素不存在，返回false。 | 285 286**错误码：** 287 288以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)和[语言基础类库错误码](errorcode-utils.md)。 289 290| 错误码ID | 错误信息 | 291| -------- | ---------------------------------------------------- | 292| 401 | Parameter error. | 293| 10200011 | The delete method cannot be bound with non-sendable. | 294| 10200201 | Concurrent modification error. | 295 296 297**示例：** 298 299```ts 300const myMap = new collections.Map<string, string>([ 301 ["hello", "world"], 302]); 303// Expected result: true 304console.info("result:" + myMap.delete("hello")); 305// Expected result: false 306console.info("result:" + myMap.has("hello")); 307// Expected result: false 308console.info("result:" + myMap.delete("hello")); 309``` 310 311## forEach 312forEach(callbackFn: (value: V, key: K, map: Map<K, V>) => void): void 313 314按插入顺序对该Map中的每个键/值对执行一次回调函数。 315 316**原子化服务API**：从API version 12 开始，该接口支持在原子化服务中使用。 317 318**系统能力：** SystemCapability.Utils.Lang 319 320**参数：** 321 322| 参数名 | 类型 | 必填 | 说明 | 323| ---------- | ------------------------------------------ | ---- | ---------- | 324| callbackFn | (value: V, key: K, map: Map<K, V>) => void | 是 | 回调函数。 | 325 326callbackFn的参数说明： 327| 参数名 | 类型 | 必填 | 说明 | 328| ------ | --------------- | ---- | ---------------------------- | 329| value | V | 否 | 当前遍历到的元素键值对的值。 | 330| key | K | 否 | 当前遍历到的元素键值对的键。 | 331| map | Map<K, V> | 否 | 当前map实例对象。 | 332 333**错误码：** 334 335以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)和[语言基础类库错误码](errorcode-utils.md)。 336 337| 错误码ID | 错误信息 | 338| -------- | ----------------------------------------------------- | 339| 401 | Parameter error. | 340| 10200011 | The forEach method cannot be bound with non-sendable. | 341| 10200201 | Concurrent modification error. | 342 343**示例：** 344 345```ts 346// 正例： 347new collections.Map<string, number>([ 348 ['foo', 0], 349 ['bar', 1], 350 ['baz', 2], 351]).forEach((value, key, map) => { 352 console.info(`m[${key}] = ${value}`); 353}); 354``` 355 356<!--code_no_check--> 357```ts 358// 反例： 359new collections.Map<string, number>([ 360 ['foo', 0], 361 ['bar', 1], 362 ['baz', 2], 363]).forEach((value, key, map) => { 364 // Throw exception `Concurrent modification error.` 365 map.delete(key); 366}); 367``` 368 369## get 370get(key: K): V | undefined 371 372返回该Map中的指定元素。 373 374**原子化服务API**：从API version 12 开始，该接口支持在原子化服务中使用。 375 376**系统能力：** SystemCapability.Utils.Lang 377 378**参数：** 379 380| 参数名 | 类型 | 必填 | 说明 | 381| ------ | ---- | ---- | --------- | 382| key | K | 是 | 指定key。 | 383 384**返回值：** 385 386| 类型 | 说明 | 387| ---- | ------------------------------------------------------------ | 388| V \| undefined | 与指定键相关联的元素，如果键在Map对象中找不到，则返回undefined。 | 389 390**错误码：** 391 392以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)和[语言基础类库错误码](errorcode-utils.md)。 393 394| 错误码ID | 错误信息 | 395| -------- | ------------------------------------------------- | 396| 401 | Parameter error. | 397| 10200011 | The get method cannot be bound with non-sendable. | 398| 10200201 | Concurrent modification error. | 399 400**示例：** 401 402```ts 403const myMap = new collections.Map<string, string>([ 404 ["hello", "world"], 405]); 406// Expected output: "world" 407console.info(myMap.get("hello")); 408// Expected output: undefined 409console.info(myMap.get("hel")); 410``` 411 412## has 413has(key: K): boolean 414 415判断该Map中是否存在指定元素。 416 417**原子化服务API**：从API version 12 开始，该接口支持在原子化服务中使用。 418 419**系统能力：** SystemCapability.Utils.Lang 420 421**参数：** 422 423| 参数名 | 类型 | 必填 | 说明 | 424| ------ | ---- | ---- | --------- | 425| key | K | 是 | 待查找元素的值。 | 426 427**返回值：** 428 429| 类型 | 说明 | 430| ------- | --------------------------------------------- | 431| boolean | 如果存在指定元素，则返回true，否则返回false。 | 432 433**错误码：** 434 435以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)和[语言基础类库错误码](errorcode-utils.md)。 436 437| 错误码ID | 错误信息 | 438| -------- | ------------------------------------------------- | 439| 401 | Parameter error. | 440| 10200011 | The has method cannot be bound with non-sendable. | 441| 10200201 | Concurrent modification error. | 442 443**示例：** 444 445```ts 446const myMap = new collections.Map<string, string>([ 447 ["hello", "world"], 448]); 449// Expected output: true 450console.info("result:" + myMap.has("hello")); 451// Expected output: false 452console.info("result:" + myMap.has("world")); 453``` 454 455## set 456set(key: K, value: V): Map<K, V> 457 458向该Map添加或更新一个指定的键值对。 459 460**原子化服务API**：从API version 12 开始，该接口支持在原子化服务中使用。 461 462**系统能力：** SystemCapability.Utils.Lang 463 464**参数：** 465 466| 参数名 | 类型 | 必填 | 说明 | 467| ------ | ---- | ---- | --------- | 468| key | K | 是 | 添加或更新指定元素的键。 | 469| value | V | 是 | 添加或更新指定元素的值。 | 470 471**返回值：** 472 473| 类型 | 说明 | 474| --------------- | ------- | 475| Map<K, V> | Map对象 | 476 477**错误码：** 478 479以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)和[语言基础类库错误码](errorcode-utils.md)。 480 481| 错误码ID | 错误信息 | 482| -------- | ------------------------------------------------- | 483| 401 | Parameter error. | 484| 10200011 | The set method cannot be bound with non-sendable. | 485| 10200201 | Concurrent modification error. | 486 487**示例：** 488 489```ts 490// 正例： 491const myMap = new collections.Map<string, string>(); 492myMap.set("foo", "bar"); 493``` 494 495<!--code_no_check--> 496```ts 497// 反例： 498let obj = new Object(); 499const myMap: collections.Map<string, Object> = new collections.Map<string, Object>(); 500// Type arguments of generic "Sendable" type must be a "Sendable" data type (arkts-sendable-generic-types) 501myMap.set("foo", obj); 502``` 503 504## [Symbol.iterator] 505 506[Symbol.iterator]\(): IterableIterator<[K, V]> 507 508返回一个迭代器，迭代器的每一项都是一个JavaScript对象，并返回该对象。 509 510> **说明：** 511> 512> 本接口不支持在.ets文件中使用。 513 514**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 515 516**系统能力：** SystemCapability.Utils.Lang 517 518**返回值：** 519| 类型 | 说明 | 520| -------- | -------- | 521| IterableIterator<[K, V]> | 返回一个迭代器。 | 522 523**错误码：** 524 525以下错误码的详细介绍请参见[语言基础类库错误码](errorcode-utils.md)。 526 527| 错误码ID | 错误信息 | 528| -------- | -------- | 529| 10200011 | The Symbol.iterator method cannot be bound. | 530 531**示例：** 532 533```ts 534let map = new collections.Map<number, string>([ 535 [0, "one"], 536 [1, "two"], 537 [2, "three"], 538 [3, "four"] 539]); 540 541let keys = Array.from(map.keys()); 542for (let key of keys) { 543 console.info("key:" + key); 544 console.info("value:" + map.get(key)); 545} 546``` 547