1# 应用级变量的状态管理 2 3 4状态管理模块提供了应用程序的数据存储能力、持久化数据管理能力、UIAbility数据存储能力和应用程序需要的环境状态。 5 6 7>**说明：** 8> 9>本模块首批接口从API version 7开始支持，后续版本的新增接口，采用上角标单独标记接口的起始版本。 10 11 12本文中T和S的含义如下： 13 14 15| 类型 | 描述 | 16| ---- | -------------------------------------- | 17| T | Class，number，boolean，string和这些类型的数组形式。 | 18| S | number，boolean，string。 | 19 20 21## AppStorage 22 23 24### Link 25 26static Link(propName: string): any 27 28与AppStorage中对应的propName建立双向数据绑定。如果给定的propName在AppStorage中存在，返回与AppStorage中propName对应属性的双向绑定数据。 29 30双向绑定数据的修改会同步回AppStorage中，AppStorage会将变化同步到所有绑定该propName的数据和自定义组件中。 31 32如果AppStorage中不存在propName，则返回undefined。 33 34**参数：** 35 36| 参数名 | 类型 | 必填 | 参数描述 | 37| -------- | ------ | ---- | ---------------- | 38| propName | string | 是 | AppStorage中的属性名。 | 39 40**返回值：** 41 42| 类型 | 描述 | 43| ---- | ---------------------------------------- | 44| any | 返回双向绑定的数据，如果AppStorage不存在对应的propName，在返回undefined。 | 45 46 47```ts 48AppStorage.SetOrCreate('PropA', 47); 49let linkToPropA1 = AppStorage.Link('PropA'); 50let linkToPropA2 = AppStorage.Link('PropA'); // linkToPropA2.get() == 47 51linkToPropA1.set(48); // 双向同步: linkToPropA1.get() == linkToPropA2.get() == 48 52``` 53 54 55### SetAndLink 56 57static SetAndLink<T>(propName: string, defaultValue: T): SubscribedAbstractProperty<T> 58 59与Link接口类似，如果给定的propName在AppStorage中存在，则返回该propName对应的属性的双向绑定数据。如果不存在，则使用defaultValue在AppStorage创建和初始化propName，返回其双向绑定数据。 60 61**参数：** 62 63| 参数名 | 类型 | 必填 | 参数描述 | 64| ------------ | ------ | ---- | ---------------------------------------- | 65| propName | string | 是 | AppStorage中的属性名。 | 66| defaultValue | T | 是 | 当propName在AppStorage中不存在，使用defaultValue在AppStorage中初始化对应的propName。 | 67 68**返回值：** 69 70| 类型 | 描述 | 71| ----------------------------------- | ---------------------------------------- | 72| SubscribedAbstractProperty<T> | SubscribedAbstractProperty<T>的实例，和AppStorage中propName对应属性的双向绑定的数据。 | 73 74 75```ts 76AppStorage.SetOrCreate('PropA', 47); 77let link1: SubscribedAbstractProperty<number> = AppStorage.SetAndLink('PropB', 49); // Create PropB 49 78let link2: SubscribedAbstractProperty<number> = AppStorage.SetAndLink('PropA', 50); // PropA exists, remains 47 79``` 80 81 82### Prop 83 84static Prop(propName: string): any 85 86与AppStorage中对应的propName建立单向属性绑定。如果给定的propName在AppStorage中存在，则返回与AppStorage中propName对应属性的单向绑定数据。如果AppStorage中不存在propName，则返回undefined。单向绑定数据的修改不会被同步回AppStorage中。 87 88>**说明：** 89> Prop仅支持简单类型。 90 91**参数：** 92 93| 参数名 | 类型 | 必填 | 参数描述 | 94| -------- | ------ | ---- | ---------------- | 95| propName | string | 是 | AppStorage中的属性名。 | 96 97**返回值：** 98 99| 类型 | 描述 | 100| ---- | ---------------------------------------- | 101| any | 返回单向绑定的数据，如果AppStorage不存在对应的propName，在返回undefined。 | 102 103 104```ts 105AppStorage.SetOrCreate('PropA', 47); 106let prop1 = AppStorage.Prop('PropA'); 107let prop2 = AppStorage.Prop('PropA'); 108prop1.set(1); // one-way sync: prop1.get()=1; but prop2.get() == 47 109``` 110 111 112### SetAndProp 113 114static SetAndProp<S>(propName: string, defaultValue: S): SubscribedAbstractProperty<S> 115 116与Prop接口类似。如果给定的propName在AppStorage存在，则返回该propName对应的属性的单向绑定数据。如果不存在，则使用defaultValue在AppStorage创建和初始化propName对应的属性，返回其单向绑定数据。 117 118**参数：** 119 120| 参数名 | 类型 | 必填 | 参数描述 | 121| ------------ | ------ | ---- | ---------------------------------------- | 122| propName | string | 是 | AppStorage中的属性名。 | 123| defaultValue | S | 是 | 当propName在AppStorage中不存在时，使用default在AppStorage中初始化对应的propName。 | 124 125**返回值：** 126 127| 类型 | 描述 | 128| ----------------------------------- | --------------------------------------- | 129| SubscribedAbstractProperty<S> | SubscribedAbstractProperty<S>的实例。 | 130 131 132```ts 133AppStorage.SetOrCreate('PropA', 47); 134let prop: SubscribedAbstractProperty<number> = AppStorage.SetAndProp('PropB', 49); // PropA -> 47, PropB -> 49 135``` 136 137 138### Has 139 140static Has(propName: string): boolean 141 142判断propName对应的属性是否在AppStorage中存在。 143 144**参数：** 145 146| 参数名 | 类型 | 必填 | 参数描述 | 147| -------- | ------ | ---- | ---------------- | 148| propName | string | 是 | AppStorage中的属性名。 | 149 150**返回值：** 151 152| 类型 | 描述 | 153| ------- | ---------------------------------------- | 154| boolean | 如果propName对应的属性在AppStorage中存在，则返回true。不存在则返回false。 | 155 156 157```ts 158AppStorage.Has('simpleProp'); 159``` 160 161 162### Get 163 164static Get<T>(propName: string): T | undefined 165 166获取propName在AppStorage中对应的属性。如果不存在返回undefined。 167 168**参数：** 169 170| 参数名 | 类型 | 必填 | 参数描述 | 171| -------- | ------ | ---- | ---------------- | 172| propName | string | 是 | AppStorage中的属性名。 | 173 174**返回值：** 175 176| 类型 | 描述 | 177| ------------------------ | ---------------------------------------- | 178| T \| undefined | AppStorage中propName对应的属性，如果不存在返回undefined。 | 179 180 181```ts 182AppStorage.SetOrCreate('PropA', 47); 183let value: number = AppStorage.Get('PropA'); // 47 184``` 185 186 187### Set 188 189static Set<T>(propName: string, newValue: T): boolean 190 191在AppStorage中设置propName对应属性的值。如果newValue的值和propName对应属性的值相同，即不需要做赋值操作，状态变量不会通知UI刷新propName对应属性的值。 192 193**参数：** 194 195| 参数名 | 类型 | 必填 | 参数描述 | 196| -------- | ------ | ---- | ---------------------- | 197| propName | string | 是 | AppStorage中的属性名。 | 198| newValue | T | 是 | 属性值，不能为undefined或null。 | 199 200**返回值：** 201 202| 类型 | 描述 | 203| ------- | ---------------------------------------- | 204| boolean | 如果AppStorage不存在propName对应的属性，或者设置的newValue是undefined或者null，返回false。设置成功则返回true。 | 205 206 207```ts 208AppStorage.SetOrCreate('PropA', 48); 209let res: boolean = AppStorage.Set('PropA', 47) // true 210let res1: boolean = AppStorage.Set('PropB', 47) // false 211``` 212 213 214### SetOrCreate 215 216static SetOrCreate<T>(propName: string, newValue: T): void 217 218如果propName已经在AppStorage中存在，并且newValue和propName对应属性的值不同，则设置propName对应属性的值为newValue，否则状态变量不会通知UI刷新propName对应属性的值。 219如果propName不存在，则创建propName属性，值为newValue。 220 221**参数：** 222 223| 参数名 | 类型 | 必填 | 参数描述 | 224| -------- | ------ | ---- | ---------------------- | 225| propName | string | 是 | AppStorage中的属性名。 | 226| newValue | T | 是 | 属性值，不能为undefined或null。 | 227 228 229```ts 230AppStorage.SetOrCreate('simpleProp', 121); 231``` 232 233 234### Delete 235 236static Delete(propName: string): boolean 237 238在AppStorage中删除propName对应的属性。 239 240在AppStorage中删除该属性的前提是必须保证该属性没有订阅者。如果有订阅者，则返回false。删除成功返回true。 241 242属性的订阅者为Link、Prop等接口绑定的propName，以及\@StorageLink('propName')和\@StorageProp('propName')。这就意味着如果自定义组件中使用\@StorageLink('propName')和\@StorageProp('propName')或者SubscribedAbstractProperty实例依旧对propName有同步关系，则该属性不能从AppStorage中删除。 243 244**参数：** 245 246| 参数名 | 类型 | 必填 | 参数描述 | 247| -------- | ------ | ---- | ---------------- | 248| propName | string | 是 | AppStorage中的属性名。 | 249 250**返回值：** 251 252| 类型 | 描述 | 253| ------- | ---------------------------------------- | 254| boolean | 如果AppStorage中有对应的属性，且该属性已经没有订阅者，则删除成功，返回true。如果属性不存在，或者该属性还存在订阅者，则返回false。 | 255 256 257```ts 258AppStorage.SetOrCreate('PropA', 47); 259AppStorage.Link('PropA'); 260let res: boolean = AppStorage.Delete('PropA'); // false, PropA still has a subscriber 261 262AppStorage.SetOrCreate('PropB', 48); 263let res1: boolean = AppStorage.Delete('PropB'); // true, PropB is deleted from AppStorage successfully 264``` 265 266 267### Keys 268 269static Keys(): IterableIterator<string> 270 271返回AppStorage中所有的属性名。 272 273**返回值：** 274 275| 类型 | 描述 | 276| ------------------------------ | ------------------ | 277| IterableIterator<string> | AppStorage中所有的属性名。 | 278 279 280```ts 281AppStorage.SetOrCreate('PropB', 48); 282let keys: IterableIterator<string> = AppStorage.Keys(); 283``` 284 285 286### staticClear 287 288static staticClear(): boolean 289 290删除所有的属性。 291 292从API version 9开始废弃，推荐使用[Clear9+](#clear9)。 293 294**返回值：** 295 296| 类型 | 描述 | 297| ------- | --------------------------------- | 298| boolean | 删除所有的属性，如果当前有状态变量依旧引用此属性，返回false。 | 299 300 301```ts 302let simple = AppStorage.staticClear(); 303``` 304 305 306### Clear<sup>9+</sup> 307 308static Clear(): boolean 309 310清除AppStorage的所有的属性。在AppStorage中清除所有属性的前提是，已经没有任何订阅者。如果有，则什么都不做返回false；删除成功返回true。 311 312订阅者的含义和参考[Delete](#delete)。 313 314**返回值：** 315 316| 类型 | 描述 | 317| ------- | ---------------------------------------- | 318| boolean | 如果AppStorage中的属性已经没有订阅者，则清除成功，返回true。否则返回false。 | 319 320 321```typescript 322AppStorage.SetOrCreate('PropA', 47); 323let res: boolean = AppStorage.Clear(); // true, there are no subscribers 324``` 325 326 327### IsMutable 328 329static IsMutable(propName: string): boolean 330 331返回AppStorage中propName对应的属性是否是可变的。 332 333**参数：** 334 335| 参数名 | 类型 | 必填 | 参数描述 | 336| -------- | ------ | ---- | ---------------- | 337| propName | string | 是 | AppStorage中的属性名。 | 338 339**返回值：** 340 341| 类型 | 描述 | 342| ------- | -------------------------------- | 343| boolean | 返回AppStorage中propNam对应的属性是否是可变的。 | 344 345 346```ts 347AppStorage.SetOrCreate('PropA', 47); 348let res: boolean = AppStorage.IsMutable('simpleProp'); 349``` 350 351 352### Size 353 354static Size(): number 355 356返回AppStorage中的属性数量。 357 358**返回值：** 359 360| 类型 | 描述 | 361| ------ | ------------------- | 362| number | 返回AppStorage中属性的数量。 | 363 364 365```ts 366AppStorage.SetOrCreate('PropB', 48); 367let res: number = AppStorage.Size(); // 1 368``` 369 370 371## LocalStorage<sup>9+</sup> 372 373 374### constructor<sup>9+</sup> 375 376constructor(initializingProperties?: Object) 377 378创建一个新的LocalStorage实例。使用Object.keys(initializingProperties)返回的属性和其数值，初始化LocalStorage实例。 379 380从API version 9开始，该接口支持在ArkTS卡片中使用。 381 382**参数：** 383 384| 参数名 | 类型 | 必填 | 参数描述 | 385| ---------------------- | ------ | ---- | ---------------------------------------- | 386| initializingProperties | Object | 否 | 用initializingProperties包含的属性和数值初始化LocalStorage。initializingProperties不能为undefined。 | 387 388 389```ts 390let storage: LocalStorage = new LocalStorage({ 'PropA': 47 }); 391``` 392 393 394### GetShared<sup>9+</sup> 395 396static GetShared(): LocalStorage 397 398获取当前stage共享的LocalStorage实例。 399 400从API version 9开始，该接口支持在ArkTS卡片中使用。 401 402**模型约束：**此接口仅可在Stage模型下使用。 403 404**返回值：** 405 406| 类型 | 描述 | 407| ------------------------------ | ----------------- | 408| [LocalStorage](#localstorage9) | 返回LocalStorage实例。 | 409 410 411```ts 412let storage: LocalStorage = LocalStorage.GetShared(); 413``` 414 415 416### has<sup>9+</sup> 417 418has(propName: string): boolean 419 420判断propName对应的属性是否在LocalStorage中存在。 421 422从API version 9开始，该接口支持在ArkTS卡片中使用。 423 424**参数：** 425 426| 参数名 | 类型 | 必填 | 参数描述 | 427| -------- | ------ | ---- | ------------------ | 428| propName | string | 是 | LocalStorage中的属性名。 | 429 430**返回值：** 431 432| 类型 | 描述 | 433| ------- | ---------------------------------------- | 434| boolean | 如果propName对应的属性在AppStorage中存在，则返回true。不存在则返回false。 | 435 436 437``` 438let storage: LocalStorage = new LocalStorage({ 'PropA': 47 }); 439storage.has('PropA'); // true 440``` 441 442 443### get<sup>9+</sup> 444 445get<T>(propName: string): T | undefined 446 447获取propName在LocalStorage中对应的属性。 448 449从API version 9开始，该接口支持在ArkTS卡片中使用。 450 451**参数：** 452 453| 参数名 | 类型 | 必填 | 参数描述 | 454| -------- | ------ | ---- | ------------------ | 455| propName | string | 是 | LocalStorage中的属性名。 | 456 457**返回值：** 458 459| 类型 | 描述 | 460| ------------------------ | ---------------------------------------- | 461| T \| undefined | LocalStorage中propName对应的属性，如果不存在返回undefined。 | 462 463 464```ts 465let storage: LocalStorage = new LocalStorage({ 'PropA': 47 }); 466let value: number = storage.get('PropA'); // 47 467``` 468 469 470### set<sup>9+</sup> 471 472set<T>(propName: string, newValue: T): boolean 473 474在LocalStorage中设置propName对应属性的值。如果newValue的值和propName对应属性的值相同，即不需要做赋值操作，状态变量不会通知UI刷新propName对应属性的值。 475 476从API version 9开始，该接口支持在ArkTS卡片中使用。 477 478**参数：** 479 480| 参数名 | 类型 | 必填 | 参数描述 | 481| -------- | ------ | ---- | ----------------------- | 482| propName | string | 是 | LocalStorage中的属性名。 | 483| newValue | T | 是 | 属性值，不能为undefined或者null。 | 484 485**返回值：** 486 487| 类型 | 描述 | 488| ------- | ---------------------------------------- | 489| boolean | 如果LocalStorage不存在propName对应的属性，或者设置的newValue是undefined或者null，返回false。设置成功返回true。 | 490 491 492```ts 493let storage: LocalStorage = new LocalStorage({ 'PropA': 47 }); 494let res: boolean = storage.set('PropA', 47); // true 495let res1: boolean = storage.set('PropB', 47); // false 496``` 497 498 499### setOrCreate<sup>9+</sup> 500 501setOrCreate<T>(propName: string, newValue: T): boolean 502 503如果propName已经在AppStorage中存在，并且newValue和propName对应属性的值不同，则设置propName对应属性的值为newValue，否则状态变量不会通知UI刷新propName对应属性的值。 504如果propName不存在，则创建propName属性，值为newValue。 505 506从API version 9开始，该接口支持在ArkTS卡片中使用。 507 508**参数：** 509 510| 参数名 | 类型 | 必填 | 参数描述 | 511| -------- | ------ | ---- | ----------------------- | 512| propName | string | 是 | LocalStorage中的属性名。 | 513| newValue | T | 是 | 属性值，不能为undefined或者null。 | 514 515**返回值：** 516 517| 类型 | 描述 | 518| ------- | ---------------------------------------- | 519| boolean | 如果设置的newValue是undefined或者null，返回false。<br/>如果LocalStorage存在propName，则更新其值为newValue，返回true。<br/>如果LocalStorage不存在propName，则创建propName，并初始化其值为newValue，返回true。 | 520 521 522```ts 523let storage: LocalStorage = new LocalStorage({ 'PropA': 47 }); 524let res: boolean =storage.setOrCreate('PropA', 121); // true 525let res1: boolean =storage.setOrCreate('PropB', 111); // true 526let res2: boolean =storage.setOrCreate('PropB', undefined); // false 527``` 528 529 530### link<sup>9+</sup> 531 532link<T>(propName: string): SubscribedAbstractProperty<T> 533 534如果给定的propName在LocalStorage实例中存在，则返回与LocalStorage中propName对应属性的双向绑定数据。 535 536双向绑定数据的修改会被同步回LocalStorage中，LocalStorage会将变化同步到所有绑定该propName的数据和Component中。 537 538如果LocalStorage中不存在propName，则返回undefined。 539 540从API version 9开始，该接口支持在ArkTS卡片中使用。 541 542**参数：** 543 544| 参数名 | 类型 | 必填 | 参数描述 | 545| -------- | ------ | ---- | ------------------ | 546| propName | string | 是 | LocalStorage中的属性名。 | 547 548**返回值：** 549 550| 类型 | 描述 | 551| ----------------------------------- | ---------------------------------------- | 552| SubscribedAbstractProperty<T> | SubscribedAbstractProperty<T>的实例，如果AppStorage不存在对应的propName，再返回undefined。 | 553 554 555```ts 556let storage: LocalStorage = new LocalStorage({ 'PropA': 47 }); 557let linkToPropA1: SubscribedAbstractProperty<number> = storage.link('PropA'); 558let linkToPropA2: SubscribedAbstractProperty<number> = storage.link('PropA'); // linkToPropA2.get() == 47 559linkToPropA1.set(48); // 双向同步: linkToPropA1.get() == linkToPropA2.get() == 48 560``` 561 562 563### setAndLink<sup>9+</sup> 564 565setAndLink<T>(propName: string, defaultValue: T): SubscribedAbstractProperty<T> 566 567与Link接口类似，如果给定的propName在LocalStorage存在，则返回该propName对应的属性的双向绑定数据。如果不存在，则使用defaultValue在LocalStorage创建和初始化propName，返回其双向绑定数据。 568 569从API version 9开始，该接口支持在ArkTS卡片中使用。 570 571**参数：** 572 573| 参数名 | 类型 | 必填 | 参数描述 | 574| ------------ | ------ | ---- | ---------------------------------------- | 575| propName | string | 是 | LocalStorage中的属性名。 | 576| defaultValue | T | 是 | 当propName在LocalStorage中不存在，使用default在LocalStorage中初始化对应的propName。 | 577 578**返回值：** 579 580| 类型 | 描述 | 581| ----------------------------------- | ---------------------------------------- | 582| SubscribedAbstractProperty<T> | SubscribedAbstractProperty<T>的实例，如果AppStorage不存在对应的propName，再返回undefined。 | 583 584 585```ts 586let storage: LocalStorage = new LocalStorage({ 'PropA': 47 }); 587let link1: SubscribedAbstractProperty<number> = storage.setAndLink('PropB', 49); // Create PropB 49 588var link2: SubscribedAbstractProperty<number> = storage.setAndLink('PropA', 50); // PropA exists, remains 47 589``` 590 591 592### prop<sup>9+</sup> 593 594prop<S>(propName: string): SubscribedAbstractProperty<S> 595 596如果给定的propName在LocalStorage存在，则返回与LocalStorage中propName对应属性的单向绑定数据。如果LocalStorage中不存在propName，则返回undefined。单向绑定数据的修改不会被同步回LocalStorage中。 597 598从API version 9开始，该接口支持在ArkTS卡片中使用。 599 600**参数：** 601 602| 参数名 | 类型 | 必填 | 参数描述 | 603| -------- | ------ | ---- | ------------------ | 604| propName | string | 是 | LocalStorage中的属性名。 | 605 606**返回值：** 607 608| 类型 | 描述 | 609| ----------------------------------- | ---------------------------------------- | 610| SubscribedAbstractProperty<S> | SubscribedAbstractProperty<S>的实例，如果AppStorage不存在对应的propName，在返回undefined。 | 611 612 613```ts 614let storage: LocalStorage = new LocalStorage({ 'PropA': 47 }); 615let prop1: SubscribedAbstractProperty<number> = storage.prop('PropA'); 616let prop2: SubscribedAbstractProperty<number> = storage.prop('PropA'); 617prop1.set(1); // one-way sync: prop1.get()=1; but prop2.get() == 47 618``` 619 620 621### setAndProp<sup>9+</sup> 622 623setAndProp<S>(propName: string, defaultValue: S): SubscribedAbstractProperty<S> 624 625propName在LocalStorage存在，则返回该propName对应的属性的单向绑定数据。如果不存在，则使用defaultValue在LocalStorage创建和初始化propName对应的属性，返回其单向绑定数据。 626 627从API version 9开始，该接口支持在ArkTS卡片中使用。 628 629**参数：** 630 631| 参数名 | 类型 | 必填 | 参数描述 | 632| ------------ | ------ | ---- | ---------------------------------------- | 633| propName | string | 是 | LocalStorage中的属性名。 | 634| defaultValue | S | 是 | 当propName在AppStorage中不存在，使用default在AppStorage中初始化对应的propName。 | 635 636**返回值：** 637 638| 类型 | 描述 | 639| ----------------------------------- | ---------------------------------------- | 640| SubscribedAbstractProperty<S> | SubscribedAbstractProperty<S>的实例，和AppStorage中propName对应属性的单向绑定的数据。 | 641 642 643```ts 644let storage: LocalStorage = new LocalStorage({ 'PropA': 47 }); 645let prop: SubscribedAbstractProperty<number> = storage.setAndProp('PropB', 49); // PropA -> 47, PropB -> 49 646``` 647 648 649### delete<sup>9+</sup> 650 651delete(propName: string): boolean 652 653在LocalStorage中删除propName对应的属性。删除属性的前提是该属性已经没有订阅者，如果有则返回false。删除成功则返回true。 654 655属性的订阅者是link，prop接口绑定的propName，以及\@LocalStorageLink('propName')和\@LocalStorageProp('propName')。如果自定义组件Component中使用或者SubscribedAbstractProperty（link和prop接口的返回类型）依旧有同步关系，则该属性不能从LocalStorage中删除。 656 657从API version 9开始，该接口支持在ArkTS卡片中使用。 658 659**参数：** 660 661| 参数名 | 类型 | 必填 | 参数描述 | 662| -------- | ------ | ---- | ------------------ | 663| propName | string | 是 | LocalStorage中的属性名。 | 664 665**返回值：** 666 667| 类型 | 描述 | 668| ------- | ---------------------------------------- | 669| boolean | 如果LocalStorage中有对应的属性，且该属性已经没有订阅者，则删除成功返回true。如果属性不存在，或者该属性还存在订阅者，则返回false。 | 670 671 672```ts 673let storage: LocalStorage = new LocalStorage({ 'PropA': 47 }); 674storage.link('PropA'); 675let res: boolean = storage.delete('PropA'); // false, PropA still has a subscriber 676let res1: boolean = storage.delete('PropB'); // false, PropB is not in storage 677storage.setOrCreate('PropB', 48); 678let res2: boolean = storage.delete('PropB'); // true, PropB is deleted from storage successfully 679``` 680 681 682### keys<sup>9+</sup> 683 684keys(): IterableIterator<string> 685 686返回AppStorage中所有的属性名。 687 688从API version 9开始，该接口支持在ArkTS卡片中使用。 689 690**返回值：** 691 692| 类型 | 描述 | 693| ------------------------------ | -------------------- | 694| IterableIterator<string> | LocalStorage中所有的属性名。 | 695 696 697```ts 698let storage: LocalStorage = new LocalStorage({ 'PropA': 47 }); 699let keys: IterableIterator<string> = storage.keys(); 700``` 701 702 703### size<sup>9+</sup> 704 705size(): number 706 707返回LocalStorage中的属性数量。 708 709从API version 9开始，该接口支持在ArkTS卡片中使用。 710 711**返回值：** 712 713| 类型 | 描述 | 714| ------ | --------- | 715| number | 返回键值对的数量。 | 716 717 718```ts 719let storage: LocalStorage = new LocalStorage({ 'PropA': 47 }); 720let res: number = storage.size(); // 1 721``` 722 723 724### clear<sup>9+</sup> 725 726clear(): boolean 727 728 729清除LocalStorage的所有的属性。在LocalStorage中清除所有属性的前提是已经没有任何订阅者。如果有则返回false；清除成功返回true。 730 731从API version 9开始，该接口支持在ArkTS卡片中使用。 732 733**返回值：** 734 735 736| 类型 | 描述 | 737| ------- | ---------------------------------------- | 738| boolean | 如果LocalStorage中的属性已经没有任何订阅者，则清除成功，返回true。否则返回false。 | 739 740 741 742```ts 743let storage: LocalStorage = new LocalStorage({ 'PropA': 47 }); 744let res: boolean = storage.clear(); // true, there are no subscribers 745``` 746 747 748## SubscribedAbstractProperty 749 750 751### get<sup>9+</sup> 752 753abstract get(): T 754 755读取从AppStorage/LocalStorage同步属性的数据。 756 757从API version 9开始，该接口支持在ArkTS卡片中使用。 758 759**返回值：** 760 761| 类型 | 描述 | 762| ---- | ------------------------------- | 763| T | AppStorage/LocalStorage同步属性的数据。 | 764 765 766```ts 767AppStorage.SetOrCreate('PropA', 47); 768let prop1 = AppStorage.Prop('PropA'); 769prop1.get(); // prop1.get()=47 770``` 771 772 773### set<sup>9+</sup> 774 775abstract set(newValue: T): void 776 777设置AppStorage/LocalStorage同步属性的数据。 778 779从API version 9开始，该接口支持在ArkTS卡片中使用。 780 781 782**参数：** 783 784 785| 参数名 | 类型 | 必填 | 参数描述 | 786| -------- | ---- | ---- | ------- | 787| newValue | T | 是 | 要设置的数据。 | 788 789 790 791``` 792AppStorage.SetOrCreate('PropA', 47); 793let prop1 = AppStorage.Prop('PropA'); 794prop1.set(1); // prop1.get()=1 795``` 796 797 798## PersistentStorage 799 800 801### PersistProp 802 803static PersistProp<T>(key: string, defaultValue: T): void 804 805将AppStorage中key对应的属性持久化到文件中。该接口的调用通常在访问AppStorage之前。 806 807确定属性的类型和值的顺序如下： 808 8091. 如果PersistentStorage文件中存在key对应的属性，在AppStorage中创建对应的propName，并用在PersistentStorage中找到的key的属性初始化。 810 8112. 如果PersistentStorage文件中没有查询到key对应的属性，则在AppStorage中查找key对应的属性。如果找到key对应的属性，则将该属性持久化。 812 8133. 如果AppStorage也没查找到key对应的属性，则在AppStorage中创建key对应的属性。用defaultValue初始化其值，并将该属性持久化。 814 815根据上述的初始化流程，如果AppStorage中有该属性，则会使用其值，覆盖掉PersistentStorage文件中的值。由于AppStorage是内存内数据，该行为会导致数据丧失持久化能力。 816 817**参数：** 818 819| 参数名 | 类型 | 必填 | 参数描述 | 820| ------------ | ------ | ---- | ---------------------------------------- | 821| key | string | 是 | 属性名。 | 822| defaultValue | T | 是 | 在PersistentStorage和AppStorage未查询到时，则使用默认值初始化初始化它。不允许为undefined和null。 | 823 824 825**示例：** 826 827 828 829```ts 830PersistentStorage.PersistProp('highScore', '0'); 831``` 832 833 834### DeleteProp 835 836static DeleteProp(key: string): void 837 838PersistProp的逆向操作。将key对应的属性从PersistentStorage删除，后续AppStorage的操作，对PersistentStorage不会再有影响。 839 840**参数：** 841 842| 参数名 | 类型 | 必填 | 参数描述 | 843| ---- | ------ | ---- | ----------------------- | 844| key | string | 是 | PersistentStorage中的属性名。 | 845 846 847```ts 848PersistentStorage.DeleteProp('highScore'); 849``` 850 851 852### PersistProps 853 854static PersistProps(properties: {key: string, defaultValue: any;}[]): void 855 856行为和PersistProp类似，不同在于可以一次性持久化多个数据，适合在应用启动的时候初始化。 857 858**参数：** 859 860| 参数名 | 类型 | 必填 | 参数描述 | 861| ---------- | ---------------------------------------- | ---- | ---------------------------------------- | 862| properties | {key: string, defaultValue: any}[] | 是 | 持久化数组，启动key为属性名，defaultValue为默认值。规则同PersistProp。 | 863 864 865```ts 866PersistentStorage.PersistProps([{ key: 'highScore', defaultValue: '0' }, { key: 'wightScore', defaultValue: '1' }]); 867``` 868 869 870### Keys 871 872static Keys(): Array<string> 873 874返回所有持久化属性的key的数组。 875 876**返回值：** 877 878| 类型 | 描述 | 879| ------------------- | ----------------- | 880| Array<string> | 返回所有持久化属性的key的数组。 | 881 882 883```ts 884let keys: Array<string> = PersistentStorage.Keys(); 885``` 886 887 888## Environment 889 890 891### EnvProp 892 893static EnvProp<S>(key: string, value: S): boolean 894 895将Environment的内置环境变量key存入AppStorage中。如果系统中未查询到Environment环境变量key的值，则使用默认值value，存入成功，返回true。如果AppStorage已经有对应的key，则返回false。 896 897所以建议在程序启动的时候调用该接口。 898 899在没有调用EnvProp，就使用AppStorage读取环境变量是错误的。 900 901**参数：** 902 903| 参数名 | 类型 | 必填 | 参数描述 | 904| ----- | ------ | ---- | --------------------------------------- | 905| key | string | 是 | 环境变量名称，支持的范围详见[内置环境变量说明](#内置环境变量说明)。 | 906| value | S | 是 | 查询不到环境变量key，则使用value作为默认值存入AppStorage中。 | 907 908**返回值：** 909 910| 类型 | 描述 | 911| ------- | ---------------------------------------- | 912| boolean | 如果key对应的属性在AppStorage中存在，则返回false。不存在则在AppStorage中创建key对应的属性，返回true。 | 913 914**示例：** 915 916 917```ts 918Environment.EnvProp('accessibilityEnabled', 'default'); 919``` 920 921 922### 内置环境变量说明 923 924| key | 类型 | 说明 | 925| -------------------- | --------------- | ---------------------------------------- | 926| accessibilityEnabled | string | 无障碍屏幕朗读是否启用。 | 927| colorMode | ColorMode | 深浅色模式，可选值为：<br/>- ColorMode.LIGHT：浅色模式；<br/>- ColorMode.DARK：深色模式。 | 928| fontScale | number | 字体大小比例。 | 929| fontWeightScale | number | 字重比例。 | 930| layoutDirection | LayoutDirection | 布局方向类型，可选值为：<br/>- LayoutDirection.LTR：从左到右；<br/>- LayoutDirection.RTL：从右到左。 | 931| languageCode | string | 当前系统语言，小写字母，例如zh。 | 932 933 934### EnvProps 935 936static EnvProps(props: {key: string; defaultValue: any;}[]): void 937 938和EnvProp类似，不同点在于参数为数组，可以一次性初始化多个数据。建议在应用启动时调用，将系统环境变量批量存入AppStorage中。 939 940**参数：** 941 942| 参数名 | 类型 | 必填 | 参数描述 | 943| ----- | ---------------------------------------- | ---- | ------------------ | 944| props | {key: string, defaultValue: any}[] | 是 | 系统环境变量和默认值的键值对的数组。 | 945 946 947```ts 948Environment.EnvProps([{ key: 'accessibilityEnabled', defaultValue: 'default' }, { 949 key: 'languageCode', 950 defaultValue: 'en' 951}, { key: 'prop', defaultValue: 'hhhh' }]); 952``` 953 954 955### Keys 956 957static Keys(): Array<string> 958 959返回环境变量的属性key的数组。 960 961**返回值：** 962 963| 类型 | 描述 | 964| ------------------- | ----------- | 965| Array<string> | 返回关联的系统项数组。 | 966 967 968```ts 969Environment.EnvProps([{ key: 'accessibilityEnabled', defaultValue: 'default' }, { 970 key: 'languageCode', 971 defaultValue: 'en' 972}, { key: 'prop', defaultValue: 'hhhh' }]); 973 974let keys: Array<string> = Environment.Keys(); // accessibilityEnabled, languageCode, prop 975```