1# 应用级变量的状态管理 2 3状态管理模块提供了应用程序的数据存储能力、持久化数据管理能力、Ability数据存储能力和应用程序需要的环境状态，其中Ability数据存储从API version9开始支持。 4 5> **说明：** 6> 7> 本模块首批接口从API version 7开始支持，后续版本的新增接口，采用上角标单独标记接口的起始版本。 8 9## AppStorage 10 11### Link 12 13Link(propName: string): any 14 15与localStorage双向数据绑定。 16 17**参数：** 18 19| 参数名 | 类型 | 必填 | 参数描述 | 20| -------- | ------ | ---- | ----------- | 21| propName | string | 是 | 要双向绑定的属性名称。 | 22 23**返回值：** 24 25| 类型 | 描述 | 26| ----- | ---------------------------------------- | 27| @Link | 在具有给定键的数据，则返回到此属性的双向数据绑定，该双向绑定意味着变量或者组件对数据的更改将同步到AppStorage，通过AppStorage对数据的修改将同步到变量或者组件。 | 28 29```ts 30let simple = AppStorage.Link('simpleProp') 31``` 32 33### SetAndLink 34 35SetAndLink\<T>(propName: string, defaultValue: T): SubscribedAbstractProperty\<T> 36 37与Link接口类似，如果当前的key保存于AppStorage，则返回该key对应的value。如果该key未被创建，则创建一个对应default值的Link返回。 38 39**参数：** 40 41| 参数名 | 类型 | 必填 | 参数描述 | 42| ------------ | ------ | ---- | ----------- | 43| propName | string | 是 | 要进行创建的key值。 | 44| defaultValue | T | 是 | 要进行设置的默认值。 | 45 46**返回值：** 47 48| 类型 | 描述 | 49| ----- | ---------------------------------------- | 50| @Link | 与Link接口类似，如果当前的key保存于AppStorage，返回该key值对应的value值。如果该key值未被创建，则创建一个对应的defaultValue的Link返回。 | 51 52```ts 53let simple = AppStorage.SetAndLink('simpleProp', 121) 54``` 55 56### Prop 57 58Prop(propName: string): any 59 60单向属性绑定的一种。更新组件的状态。。 61 62**参数：** 63 64| 参数名 | 类型 | 必填 | 参数描述 | 65| -------- | ------ | ---- | ----------- | 66| propName | string | 是 | 要进行创建的key值。 | 67 68**返回值：** 69 70| 类型 | 描述 | 71| ----- | ---------------------------------------- | 72| @Prop | 如果存在具有给定键的属性，则返回此属性的单向数据绑定。该单向绑定意味着只能通过AppStorage将属性的更改同步到变量或者组件。该方法返回的变量为不可变变量，适用于可变和不可变的状态属性，如果具有此键的属性不存在则返回undefined。 | 73 74```ts 75let simple = AppStorage.Prop('simpleProp') 76``` 77 78### SetAndProp 79 80SetAndProp\<S>(propName: string, defaultValue: S): SubscribedAbstractProperty\<S> 81 82与Prop接口类似，如果当前的key保存于AppStorage，则返回该key对应的value。如果该key未被创建，则创建一个对应default值的Prop返回。 83 84**参数：** 85 86| 参数名 | 类型 | 必填 | 参数描述 | 87| ------------ | ------ | ---- | --------------- | 88| propName | string | 是 | 要保存的的键值对中的key值。 | 89| defaultValue | S | 是 | 创建的默认值。 | 90 91**返回值：** 92 93| 类型 | 描述 | 94| ----- | ---------------------------------------- | 95| @Prop | 如果当前的key保存与AppStorage，返回该key值对应的value值。如果该key值未被创建，则创建一个对应的defaultValue的Prop返回。 | 96 97```ts 98let simple = AppStorage.SetAndProp('simpleProp', 121) 99``` 100 101### Has 102 103Has(propName: string): boolean 104 105判断对应键值的属性是否存在。 106 107**参数：** 108 109| 参数名 | 类型 | 必填 | 参数描述 | 110| -------- | ------ | ---- | ------- | 111| propName | string | 是 | 属性的属性值。 | 112 113**返回值：** 114 115| 类型 | 描述 | 116| ------- | ------------- | 117| boolean | 返回属性的属性值是否存在。 | 118 119```ts 120let simple = AppStorage.Has('simpleProp') 121``` 122 123### Get 124 125Get\<T>(propName: string): T | undefined 126 127通过此接口获取对应key值的value。 128 129**参数：** 130 131| 参数名 | 类型 | 必填 | 参数描述 | 132| -------- | ------ | ---- | ----------- | 133| propName | string | 是 | 要获取对应的key值。 | 134 135**返回值：** 136 137| 类型 | 描述 | 138| ----------------- | ------------- | 139| T或undefined | 属性存在返回属性值，属性不存在返回undefined。 | 140 141```ts 142let simple = AppStorage.Get('simpleProp') 143``` 144 145### Set 146 147Set\<T>(propName: string, newValue: T): boolean 148 149对已保存的key值，替换其value值。 150 151**参数：** 152 153| 参数名 | 类型 | 必填 | 参数描述 | 154| -------- | ------ | ---- | ----------- | 155| propName | string | 是 | 要设置的key值。 | 156| newValue | T | 是 | 要设置的value值。 | 157 158**返回值：** 159 160| 类型 | 描述 | 161| ------- | ----------------------------------- | 162| boolean | 如果存在key值，设置value值并返回true，否则返回false。 | 163 164```ts 165let simple = AppStorage.Set('simpleProp', 121) 166``` 167 168### SetOrCreate 169 170SetOrCreate\<T>(propName: string, newValue: T): void 171 172创建或更新setOrCreate内部的值。 173 174**参数：** 175 176| 参数名 | 类型 | 必填 | 参数描述 | 177| -------- | ------ | ---- | --------------- | 178| propName | string | 是 | 要更新或者创建的key值。 | 179| newValue | T | 是 | 要更新或者创建的value值。 | 180 181**返回值：** 182 183| 类型 | 描述 | 184| ------- | ---------------------------------------- | 185| boolean | 如果已存在与给定键名字相同的属性，更新其值且返回true。如果不存在具有给定名称的属性，在AppStorage中创建具有给定默认值的新属性，默认值必须是T类型。不允许undefined 或 null 返回true。 | 186 187```ts 188let simple = AppStorage.SetOrCreate('simpleProp', 121) 189``` 190 191### Delete 192 193Delete(propName: string): boolean 194 195删除key指定的键值对。 196 197**参数：** 198 199| 参数名 | 类型 | 必填 | 参数描述 | 200| -------- | ------ | ---- | ------------ | 201| propName | string | 是 | 要删除的属性的key值。 | 202 203**返回值：** 204 205| 类型 | 描述 | 206| ------- | ---------------------------------------- | 207| boolean | 删除key指定的键值对，如果存在且删除成功返回true，不存在或删除失败返回false。 | 208 209```ts 210let simple = AppStorage.Delete('simpleProp') 211``` 212 213### keys 214 215keys(): IterableIterator\<string> 216 217查找所有键。 218 219**返回值：** 220 221| 类型 | 描述 | 222| -------------- | -------------- | 223| array\<string> | 返回包含所有键的字符串数组。 | 224 225```ts 226let simple = AppStorage.Keys() 227``` 228 229### staticClear 230 231staticClear(): boolean 232 233删除所有的属性。 234 235从API version 9开始废弃，推荐使用[Clear](#clear)。 236 237**返回值：** 238 239| 类型 | 描述 | 240| ------- | --------------------------------- | 241| boolean | 删除所有的属性，如果当前有状态变量依旧引用此属性，返回false。 | 242 243```ts 244let simple = AppStorage.staticClear() 245``` 246 247### Clear<sup>9+</sup> 248 249Clear(): boolean 250 251删除所有的属性。 252 253**返回值：** 254 255| 类型 | 描述 | 256| ------- | --------------------------------- | 257| boolean | 删除所有的属性，如果当前有状态变量依旧引用此属性，返回false。 | 258 259```typescript 260let simple = AppStorage.Clear() 261``` 262 263### IsMutable 264 265IsMutable(propName: string): boolean 266 267查询属性及状态。 268 269**参数：** 270 271| 参数名 | 类型 | 必填 | 参数描述 | 272| -------- | ------ | :--- | ------------ | 273| propName | string | 是 | 要查询的属性的key值。 | 274 275**返回值：** 276 277| 类型 | 描述 | 278| ------- | ------------------ | 279| boolean | 返回此属性是否存在并且是否可以改变。 | 280 281```ts 282let simple = AppStorage.IsMutable('simpleProp') 283``` 284 285### Size 286 287Size(): number 288 289存在的键值对的个数。 290 291**返回值：** 292 293| 类型 | 描述 | 294| ------ | --------- | 295| number | 返回键值对的数量。 | 296 297```ts 298let simple = AppStorage.Size() 299``` 300 301## LocalStorage<sup>9+</sup> 302 303### constructor<sup>9+</sup> 304 305constructor(initializingProperties?: Object) 306 307创建一个新的LocalStorage对象，并进行初始化。 308 309**参数：** 310 311| 参数名 | 类型 | 必填 | 参数描述 | 312| ---------------------- | ------ | ---- | ---------------------------------------- | 313| initializingProperties | Object | 否 | object.keys(obj)返回的所有对象属性及其值都将添加到LocalStorage。 | 314 315```ts 316let storage = new LocalStorage() 317``` 318 319### GetShared<sup>9+</sup> 320 321static GetShared(): LocalStorage 322 323获取当前的共享的LocalStorage对象。 324 325此接口仅可在Stage模型下使用。 326 327**返回值：** 328 329| 类型 | 描述 | 330| ----------------------------- | ----------------- | 331| [LocalStorage](#localstorage) | 返回LocalStorage对象。 | 332 333```ts 334let storage = LocalStorage.GetShared() 335``` 336 337### has<sup>9+</sup> 338 339has(propName: string): boolean 340 341判断属性值是否存在。 342 343**参数：** 344 345| 参数名 | 类型 | 必填 | 参数描述 | 346| -------- | ------ | ---- | ------- | 347| propName | string | 是 | 属性的属性值。 | 348 349**返回值：** 350 351| 类型 | 描述 | 352| ------- | ------------- | 353| boolean | 返回属性的属性值是否存在。 | 354 355```ts 356let storage = new LocalStorage() 357storage.has('storageSimpleProp') 358``` 359 360### get<sup>9+</sup> 361 362get\<T>(propName: string): T 363 364获取对应key值的value。 365 366**参数：** 367 368| 参数名 | 类型 | 必填 | 参数描述 | 369| -------- | ------ | ---- | ----------- | 370| propName | string | 是 | 要获取对应的key值。 | 371 372**返回值：** 373 374| 类型 | 描述 | 375| -------------- | ---------------------------------------- | 376| T \| undefined | 当keyvalue存在时，返回keyvalue值。不存在返回undefined。 | 377 378```ts 379let storage = new LocalStorage() 380let simpleValue = storage.get('storageSimpleProp') 381``` 382 383### set<sup>9+</sup> 384 385set\<T>(propName: string, newValue: T): boolean 386 387存储对象值。 388 389**参数：** 390 391| 参数名 | 类型 | 必填 | 参数描述 | 392| -------- | ------ | ---- | ----------- | 393| propName | string | 是 | 要设置的key值。 | 394| newValue | T | 是 | 要设置的value值。 | 395 396**返回值：** 397 398| 类型 | 描述 | 399| ------- | ----------------------------------- | 400| boolean | 如果存在key值，设置value值并返回true，否则返回false。 | 401 402```ts 403let storage = new LocalStorage() 404storage.set('storageSimpleProp', 121) 405``` 406 407### setOrCreate<sup>9+</sup> 408 409setOrCreate\<T>(propName: string, newValue: T): boolean 410 411创建或更新setOrCreate内部的值。 412 413**参数：** 414 415| 参数名 | 类型 | 必填 | 参数描述 | 416| -------- | ------ | :--- | -------------- | 417| propName | string | 是 | 要更新或创建的key值。 | 418| newValue | T | 是 | 要更新或创建的value值。 | 419 420**返回值：** 421 422| 类型 | 描述 | 423| ------- | ---------------------------------------- | 424| boolean | 如果已存在与给定键名字相同的属性，更新其值且返回true。如果不存在具有给定名称的属性，在LocalStorage中创建具有给定默认值的新属性，默认值必须是T类型，不允许undefined 或 null 。 | 425 426```ts 427let storage = new LocalStorage() 428storage.setOrCreate('storageSimpleProp', 121) 429``` 430 431### link<sup>9+</sup> 432 433link\<T>(propName: string): T 434 435与localStorage双向数据绑定。 436 437**参数：** 438 439| 参数名 | 类型 | 必填 | 参数描述 | 440| -------- | ------ | ---- | ----------- | 441| propName | string | 是 | 要双向绑定的属性名称。 | 442 443**返回值：** 444 445| 类型 | 描述 | 446| ---- | ---------------------------------------- | 447| T | 如果存在具有给定键的属性，返回到此属性的双向绑定，该双向绑定意味着变量或者组件对数据的更改将同步到LocalStorage，然后通过LocalStorage实例同步到任何变量或组件。如果不存在给定键的属性，返回undefined。 | 448 449```ts 450let storage = new LocalStorage() 451let localStorage = storage.link('storageSimpleProp') 452``` 453 454### setAndLink<sup>9+</sup> 455 456setAndLink\<T>(propName: string, defaultValue: T): T 457 458与link接口类似，双向数据绑定localStorage。 459 460**参数：** 461 462| 参数名 | 类型 | 必填 | 参数描述 | 463| ------------ | ------ | ---- | ----------- | 464| propName | string | 是 | 要进行创建的key值。 | 465| defaultValue | T | 是 | 要进行设置的默认值。 | 466 467**返回值：** 468 469| 类型 | 描述 | 470| ----- | ---------------------------------------- | 471| @Link | 与Link接口类似，如果当前的key保存于LocalStorage，返回该key值对应的value值。如果该key值未被创建，则创建一个对应的defaultValue的Link返回。 | 472 473```ts 474let storage = new LocalStorage() 475let localStorage = storage.setAndLink('storageSimpleProp', 121) 476``` 477 478### prop<sup>9+</sup> 479 480prop\<T>(propName: string): T 481 482单向属性绑定的一种。更新组件的状态。 483 484**参数：** 485 486| 参数名 | 类型 | 必填 | 参数描述 | 487| -------- | ------ | ---- | ------------- | 488| propName | string | 是 | 要单向数据绑定的key值。 | 489 490**返回值：** 491 492| 类型 | 描述 | 493| ----- | ---------------------------------------- | 494| @Prop | 如果存在具有给定键的属性，返回此属性的单向数据绑定。该单向绑定意味着只能通过LocalStorage将属性的更改同步到变量或组件。该方法返回的变量为不可变变量，适用于可变和不可变的状态变量。如果此键的属性不存在则返回undefined。 | 495 496```ts 497let storage = new LocalStorage() 498let localStorage = storage.prop('storageSimpleProp') 499``` 500 501### setAndProp<sup>9+</sup> 502 503setAndProp\<T>(propName: string, defaultValue: T): T 504 505与Prop接口类似，存在localStorage的单向数据绑定prop值。 506 507**参数：** 508 509| 参数名 | 类型 | 必填 | 参数描述 | 510| ------------ | ------ | ---- | -------------- | 511| propName | string | 是 | 要保存的键值对中的key值。 | 512| defaultValue | T | 是 | 创建的默认值。 | 513 514**返回值：** 515 516| 类型 | 描述 | 517| ----- | ---------------------------------------- | 518| @Prop | 如果当前的key保存与LocalStorage，返回该key值对应的value值。如果该key值未被创建，则创建一个对应的defaultValue的Prop返回。 | 519 520```ts 521let storage = new LocalStorage() 522let localStorage = storage.setAndProp('storageSimpleProp', 121) 523``` 524 525### delete<sup>9+</sup> 526 527delete(propName: string): boolean 528 529删除key指定的键值对。 530 531**参数：** 532 533| 参数名 | 类型 | 必填 | 参数描述 | 534| -------- | ------ | :--- | ------------ | 535| propName | string | 是 | 要删除的属性的key值。 | 536 537**返回值：** 538 539| 类型 | 描述 | 540| ------- | ---------------------------------------- | 541| boolean | 删除key指定的键值对。存在且删除成功，返回true。不存在、删除失败或有状态变量依旧引用propName，返回false。 | 542 543```ts 544let storage = new LocalStorage() 545storage.delete('storageSimpleProp') 546``` 547 548### keys<sup>9+</sup> 549 550keys(): IterableIterator\<string> 551 552查找所有键。 553 554**返回值：** 555 556| 类型 | 描述 | 557| -------------- | ------------------- | 558| array\<string> | 返回包含所有键不可序列化的字符串数组。 | 559 560```ts 561let storage = new LocalStorage() 562let simple = storage.keys() 563``` 564 565### size<sup>9+</sup> 566 567size(): number 568 569存在的键值对的个数。 570 571**返回值：** 572 573| 类型 | 描述 | 574| ------ | --------- | 575| number | 返回键值对的数量。 | 576 577```ts 578let storage = new LocalStorage() 579let simple = storage.size() 580``` 581 582### Clear<sup>9+</sup> 583 584clear(): boolean 585 586删除所有的属性。 587 588**返回值：** 589 590| 类型 | 描述 | 591| ------- | --------------------------------- | 592| boolean | 删除所有的属性，如果当前有状态变量依旧引用此属性，返回false。 | 593 594```ts 595let storage = new LocalStorage() 596let simple = storage.clear() 597``` 598 599## PersistentStorage 600 601### constructor 602 603constructor(appStorage: AppStorage, storage: Storage) 604 605创建一个新的persistentstorage对象。 606 607**参数：** 608 609| 参数名 | 类型 | 必填 | 参数描述 | 610| ---------- | ---------- | ---- | ---------------- | 611| appStorage | AppStorage | 是 | 保存所有属性及属性值的单例对象。 | 612| storage | Storage | 是 | Storage实例对象。 | 613 614```ts 615let persistentstorage = new PersistentStorage(AppStorage,Storage) 616``` 617 618### PersistProp 619 620PersistProp(key:string,defaultValue:T): void 621 622关联命名的属性再AppStorage变为持久化数据。 623 624**参数：** 625 626| 参数名 | 类型 | 必填 | 参数描述 | 627| ------------ | ------ | ---- | -------------- | 628| key | string | 是 | 要关联的属性的key值。 | 629| defaultValue | T | 是 | 要关联的属性的value值。 | 630 631```ts 632PersistentStorage.PersistProp('highScore', '0') 633``` 634 635### DeleteProp 636 637DeleteProp(key: string): void 638 639取消双向数据绑定，该属性值将从持久存储中删除。 640 641**参数：** 642 643| 参数名 | 类型 | 必填 | 参数描述 | 644| ---- | ------ | ---- | ------------ | 645| key | string | 是 | 要取消的属性的key值。 | 646 647```ts 648PersistentStorage.DeleteProp('highScore') 649``` 650 651### PersistProps 652 653PersistProps(properties: {key: string, defaultValue: any}[]): void 654 655关联多个命名的属性绑定。 656 657**参数：** 658 659| 参数名 | 类型 | 必填 | 参数描述 | 660| ---- | ---------------------------------- | ---- | --------- | 661| key | {key: string, defaultValue: any}[] | 是 | 要关联的属性数组。 | 662 663```ts 664PersistentStorage.PersistProps([{key: 'highScore', defaultValue: '0'},{key: 'wightScore',defaultValue: '1'}]) 665``` 666 667### Keys 668 669Keys(): Array\<string> 670 671返回所有持久化属性的标记。 672 673**返回值：** 674 675| 类型 | 描述 | 676| -------------- | ------------- | 677| Array\<string> | 返回所有持久化属性的标记。 | 678 679```ts 680let simple = PersistentStorage.Keys() 681``` 682 683> **说明：** 684> 685> - PersistProp接口使用时，需要保证输入对应的key应当在AppStorage存在。 686> 687> - DeleteProp接口使用时，只能对本次启动已经link过的数据生效。 688 689## Environment 690 691### constructor 692 693创建一个environment对象。 694 695```ts 696let simple = new Environment() 697``` 698 699### EnvProp 700 701EnvProp\<S>(key: string, value: S): boolean 702 703关联此系统项到AppStorage中，建议在app启动时使用此接口。如果该属性在AppStorage已存在，返回false。请勿使用AppStorage中的变量，在调用此方法关联环境变量。 704 705**参数：** 706 707| 参数名 | 类型 | 必填 | 参数描述 | 参数描述 | 708| ----- | ------ | ---- | ---------- | ------------------------- | 709| key | string | 是 | 要关联的key值 | 要关联的key值，支持的范围详见内置环境变量说明。 | 710| value | S | 是 | 要关联的value值 | 要关联的value值。 | 711 712**返回值：** 713 714| 类型 | 描述 | 715| ------- | ---------------------- | 716| boolean | 返回该属性在AppStorage中是否存在。 | 717 718**内置环境变量说明：** 719 720| key | 类型 | 说明 | 721| -------------------- | --------------- | ---------------------------------------- | 722| accessibilityEnabled | string | 无障碍屏幕朗读是否启用。 | 723| colorMode | ColorMode | 深浅色模式，可选值为：<br>- ColorMode.LIGHT：浅色模式；<br>- ColorMode.DARK：深色模式。 | 724| fontScale | number | 字体大小比例。 | 725| fontWeightScale | number | 字重比例。 | 726| layoutDirection | LayoutDirection | 布局方向类型，可选值为：<br>- LayoutDirection.LTR：从左到右；<br>- LayoutDirection.RTL：从右到左。 | 727| languageCode | string | 当前系统语言，小写字母，例如zh。 | 728 729```ts 730Environment.EnvProp('accessibilityEnabled', 'default') 731``` 732 733### EnvProps 734 735EnvProps(props: {key: string, defaultValue: any}[]): void 736 737关联此系统项数组到AppStorage中 738 739**参数：** 740 741| 参数名 | 类型 | 必填 | 参数描述 | 参数描述 | 742| ---- | ---------------------------------- | ---- | --------- | --------- | 743| key | {key: string, defaultValue: any}[] | 是 | 要关联的属性数组。 | 要关联的属性数组。 | 744 745```ts 746Environment.EnvProps([{key: 'accessibilityEnabled', defaultValue: 'default'},{key: 'accessibilityUnEnabled', defaultValue: 'undefault'}]) 747``` 748 749### Keys 750 751Keys(): Array\<string> 752 753返回关联的系统项。 754 755**返回值：** 756 757| 类型 | 描述 | 758| -------------- | ----------- | 759| Array\<string> | 返回关联的系统项数组。 | 760 761```ts 762let simple = Environment.Keys() 763``` 764 765