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 23AppStorage具体UI使用说明,详见[AppStorage(应用全局的UI状态存储)](../../../quick-start/arkts-appstorage.md) 24 25**原子化服务API:** 从API version 11开始,该接口支持在原子化服务中使用。 26 27**系统能力:** SystemCapability.ArkUI.ArkUI.Full 28 29### ref<sup>12+</sup> 30 31static ref\<T\>(propName: string): AbstractProperty\<T\> | undefined 32 33如果给定的propName在[AppStorage](../../../quick-start/arkts-appstorage.md)中存在,则获得AppStorage中propName对应数据的引用。否则,返回undefined。 34 35与[link](#link10)的功能基本一致,但不需要手动释放返回的[AbstractProperty](#abstractproperty)类型的变量。 36 37**原子化服务API:** 从API version 12开始,该接口支持在原子化服务中使用。 38 39**系统能力:** SystemCapability.ArkUI.ArkUI.Full 40 41**参数:** 42 43| 参数名 | 类型 | 必填 | 说明 | 44| -------- | ------ | ---- | ---------------------- | 45| propName | string | 是 | AppStorage中的属性名。 | 46 47**返回值:** 48 49| 类型 | 说明 | 50| -------------------------------------- | ------------------------------------------------------------ | 51| [AbstractProperty<T>](#abstractproperty) \| undefined | AppStorage中propName对应属性的引用,如果AppStorage中不存在对应的propName,则返回undefined。 | 52 53**示例:** 54 55```ts 56AppStorage.setOrCreate('PropA', 47); 57let refToPropA1: AbstractProperty<number> | undefined = AppStorage.ref('PropA'); 58let refToPropA2: AbstractProperty<number> | undefined = AppStorage.ref('PropA'); // refToPropA2.get() == 47 59refToPropA1?.set(48); // 同步修改AppStorage: refToPropA1.get() == refToPropA2.get() == 48 60``` 61 62### setAndRef<sup>12+</sup> 63 64static setAndRef<T>(propName: string, defaultValue: T): AbstractProperty<T> 65 66与[ref](#ref12)接口类似,如果给定的propName在[AppStorage](../../../quick-start/arkts-appstorage.md)中存在,则获得AppStorage中propName对应数据的引用。如果不存在,则使用defaultValue在AppStorage中创建和初始化propName对应的属性,并返回其引用。defaultValue须为T类型,可以为null或undefined。 67 68与[setAndLink](#setandlink10)的功能基本一致,但不需要手动释放返回的[AbstractProperty](#abstractproperty)类型的变量。 69 70> **说明:**<br/> 71> 从API version 12开始,AppStorage支持[Map](../../../quick-start/arkts-appstorage.md#装饰map类型变量)、[Set](../../../quick-start/arkts-appstorage.md#装饰set类型变量)、[Date类型](../../../quick-start/arkts-appstorage.md#装饰date类型变量),支持null、undefined以及[联合类型](../../../quick-start/arkts-appstorage.md#appstorage支持联合类型)。 72 73**原子化服务API:** 从API version 12开始,该接口支持在原子化服务中使用。 74 75**系统能力:** SystemCapability.ArkUI.ArkUI.Full 76 77**参数:** 78 79| 参数名 | 类型 | 必填 | 说明 | 80| ------------ | ------ | ---- | ------------------------------------------------------------ | 81| propName | string | 是 | AppStorage中的属性名。 | 82| defaultValue | T | 是 | 当propName在AppStorage中不存在时,使用defaultValue在AppStorage中初始化对应的propName,defaultValue可以为null或undefined。 | 83 84**返回值:** 85 86| 类型 | 说明 | 87| ------------------------- | ------------------------------------------------------------ | 88| [AbstractProperty<T>](#abstractproperty) | AbstractProperty<T>的实例,为AppStorage中propName对应属性的引用。 | 89 90**示例:** 91 92```ts 93AppStorage.setOrCreate('PropA', 47); 94let ref1: AbstractProperty<number> = AppStorage.setAndRef('PropB', 49); // Create PropB 49 95let ref2: AbstractProperty<number> = AppStorage.setAndRef('PropA', 50); // PropA exists, remains 47 96``` 97 98 99### link<sup>10+</sup> 100 101static link<T>(propName: string): SubscribedAbstractProperty<T> 102 103与[AppStorage](../../../quick-start/arkts-appstorage.md)中对应的propName建立双向数据绑定。如果给定的propName在AppStorage中存在,返回AppStorage中propName对应属性的双向绑定数据。 104 105双向绑定数据的修改会同步回AppStorage中,AppStorage会将变化同步到所有绑定该propName的数据和自定义组件中。 106 107如果AppStorage中不存在propName,则返回undefined。 108 109**原子化服务API:** 从API version 11开始,该接口支持在原子化服务中使用。 110 111**系统能力:** SystemCapability.ArkUI.ArkUI.Full 112 113**参数:** 114 115| 参数名 | 类型 | 必填 | 说明 | 116| -------- | ------ | ---- | ---------------- | 117| propName | string | 是 | AppStorage中的属性名。 | 118 119**返回值:** 120 121| 类型 | 说明 | 122| ----------------------------------- | ------------------------------------------------------------ | 123| [SubscribedAbstractProperty<T>](#subscribedabstractproperty) | 返回双向绑定的数据,如果AppStorage中不存在对应的propName,则返回undefined。 | 124 125**示例:** 126```ts 127AppStorage.setOrCreate('PropA', 47); 128let linkToPropA1: SubscribedAbstractProperty<number> = AppStorage.link('PropA'); 129let linkToPropA2: SubscribedAbstractProperty<number> = AppStorage.link('PropA'); // linkToPropA2.get() == 47 130linkToPropA1.set(48); // 双向同步: linkToPropA1.get() == linkToPropA2.get() == 48 131``` 132 133 134### setAndLink<sup>10+</sup> 135 136static setAndLink<T>(propName: string, defaultValue: T): SubscribedAbstractProperty<T> 137 138与[link](#link10)接口类似,如果给定的propName在[AppStorage](../../../quick-start/arkts-appstorage.md)中存在,则返回该propName对应的属性的双向绑定数据。如果不存在,则使用defaultValue在AppStorage中创建和初始化propName对应的属性,返回其双向绑定数据。defaultValue必须为T类型,从API version 12开始defaultValue可以为null或undefined。 139 140> **说明:**<br/> 141> 从API version 12开始,AppStorage支持[Map](../../../quick-start/arkts-appstorage.md#装饰map类型变量)、[Set](../../../quick-start/arkts-appstorage.md#装饰set类型变量)、[Date类型](../../../quick-start/arkts-appstorage.md#装饰date类型变量),支持null、undefined以及[联合类型](../../../quick-start/arkts-appstorage.md#appstorage支持联合类型)。 142 143**原子化服务API:** 从API version 11开始,该接口支持在原子化服务中使用。 144 145**系统能力:** SystemCapability.ArkUI.ArkUI.Full 146 147**参数:** 148 149| 参数名 | 类型 | 必填 | 说明 | 150| ------------ | ------ | ---- | ------------------------------------------------------------ | 151| propName | string | 是 | AppStorage中的属性名。 | 152| defaultValue | T | 是 | 当propName在AppStorage中不存在时,使用defaultValue在AppStorage中初始化对应的propName,从API version 12开始,defaultValue可以为null或undefined。 | 153 154**返回值:** 155 156| 类型 | 说明 | 157| ----------------------------------- | ---------------------------------------- | 158| [SubscribedAbstractProperty<T>](#subscribedabstractproperty) | SubscribedAbstractProperty<T>的实例,和AppStorage中propName对应属性的双向绑定的数据。 | 159 160**示例:** 161```ts 162AppStorage.setOrCreate('PropA', 47); 163let link1: SubscribedAbstractProperty<number> = AppStorage.setAndLink('PropB', 49); // Create PropB 49 164let link2: SubscribedAbstractProperty<number> = AppStorage.setAndLink('PropA', 50); // PropA exists, remains 47 165``` 166 167 168### prop<sup>10+</sup> 169 170static prop<T>(propName: string): SubscribedAbstractProperty<T> 171 172与[AppStorage](../../../quick-start/arkts-appstorage.md)中对应的propName建立单向属性绑定。如果给定的propName在AppStorage中存在,则返回与AppStorage中propName对应属性的单向绑定数据。如果AppStorage中不存在propName,则返回undefined。单向绑定数据的修改不会被同步回AppStorage中。 173 174**原子化服务API:** 从API version 11开始,该接口支持在原子化服务中使用。 175 176**系统能力:** SystemCapability.ArkUI.ArkUI.Full 177 178**参数:** 179 180| 参数名 | 类型 | 必填 | 说明 | 181| -------- | ------ | ---- | ---------------- | 182| propName | string | 是 | AppStorage中的属性名。 | 183 184**返回值:** 185 186| 类型 | 说明 | 187| ----------------------------------- | ------------------------------------------------------------ | 188| [SubscribedAbstractProperty<T>](#subscribedabstractproperty) | 返回单向绑定的数据,如果AppStorage中不存在对应的propName,则返回undefined。 | 189 190**示例:** 191 192```ts 193AppStorage.setOrCreate('PropA', 47); 194let prop1: SubscribedAbstractProperty<number> = AppStorage.prop('PropA'); 195let prop2: SubscribedAbstractProperty<number> = AppStorage.prop('PropA'); 196prop1.set(1); // one-way sync: prop1.get()=1; but prop2.get() == 47 197``` 198 199 200### setAndProp<sup>10+</sup> 201 202static setAndProp<T>(propName: string, defaultValue: T): SubscribedAbstractProperty<T> 203 204与[prop](#prop10)接口类似。如果给定的propName在[AppStorage](../../../quick-start/arkts-appstorage.md)中存在,则返回该propName对应的属性的单向绑定数据。如果不存在,则使用defaultValue在AppStorage中创建和初始化propName对应的属性,返回其单向绑定数据。defaultValue必须为T类型,从API version 12开始defaultValue可以为null或undefined。 205 206> **说明:**<br/> 207> 从API version 12开始,AppStorage支持[Map](../../../quick-start/arkts-appstorage.md#装饰map类型变量)、[Set](../../../quick-start/arkts-appstorage.md#装饰set类型变量)、[Date类型](../../../quick-start/arkts-appstorage.md#装饰date类型变量),支持null、undefined以及[联合类型](../../../quick-start/arkts-appstorage.md#appstorage支持联合类型)。 208 209**原子化服务API:** 从API version 11开始,该接口支持在原子化服务中使用。 210 211**系统能力:** SystemCapability.ArkUI.ArkUI.Full 212 213**参数:** 214 215| 参数名 | 类型 | 必填 | 说明 | 216| ------------ | ------ | ---- | ------------------------------------------------------------ | 217| propName | string | 是 | AppStorage中的属性名。 | 218| defaultValue | T | 是 | 当propName在AppStorage中不存在时,使用defaultValue在AppStorage中初始化对应的propName,从API version 12开始,defaultValue可以为null或undefined。 | 219 220**返回值:** 221 222| 类型 | 说明 | 223| ----------------------------------- | --------------------------------------- | 224| [SubscribedAbstractProperty<T>](#subscribedabstractproperty) | SubscribedAbstractProperty<T>的实例。 | 225 226**示例:** 227```ts 228AppStorage.setOrCreate('PropA', 47); 229let prop: SubscribedAbstractProperty<number> = AppStorage.setAndProp('PropB', 49); // PropA -> 47, PropB -> 49 230``` 231 232 233### has<sup>10+</sup> 234 235static has(propName: string): boolean 236 237判断propName对应的属性是否在[AppStorage](../../../quick-start/arkts-appstorage.md)中存在。 238 239**原子化服务API:** 从API version 11开始,该接口支持在原子化服务中使用。 240 241**系统能力:** SystemCapability.ArkUI.ArkUI.Full 242 243**参数:** 244 245| 参数名 | 类型 | 必填 | 说明 | 246| -------- | ------ | ---- | ---------------- | 247| propName | string | 是 | AppStorage中的属性名。 | 248 249**返回值:** 250 251| 类型 | 说明 | 252| ------- | ---------------------------------------- | 253| boolean | 如果propName对应的属性在AppStorage中存在,则返回true。不存在则返回false。 | 254 255**示例:** 256```ts 257AppStorage.has('simpleProp'); 258``` 259 260 261### get<sup>10+</sup> 262 263static get<T>(propName: string): T | undefined 264 265获取propName在[AppStorage](../../../quick-start/arkts-appstorage.md)中对应的属性值。如果不存在则返回undefined。 266 267**原子化服务API:** 从API version 11开始,该接口支持在原子化服务中使用。 268 269**系统能力:** SystemCapability.ArkUI.ArkUI.Full 270 271**参数:** 272 273| 参数名 | 类型 | 必填 | 说明 | 274| -------- | ------ | ---- | ---------------- | 275| propName | string | 是 | AppStorage中的属性名。 | 276 277**返回值:** 278 279| 类型 | 说明 | 280| ------------------------ | ----------------------------------------------------------- | 281| T \| undefined | AppStorage中propName对应的属性,如果不存在则返回undefined。 | 282 283**示例:** 284```ts 285AppStorage.setOrCreate('PropA', 47); 286let value: number = AppStorage.get('PropA') as number; // 47 287``` 288 289 290### set<sup>10+</sup> 291 292static set<T>(propName: string, newValue: T): boolean 293 294在[AppStorage](../../../quick-start/arkts-appstorage.md)中设置propName对应属性的值。如果newValue的值和propName对应属性的值相同,即不需要做赋值操作,状态变量不会通知UI刷新propName对应属性的值,从API version 12开始,newValue可以为null或undefined。 295 296> **说明:**<br/> 297> 从API version 12开始,AppStorage支持[Map](../../../quick-start/arkts-appstorage.md#装饰map类型变量)、[Set](../../../quick-start/arkts-appstorage.md#装饰set类型变量)、[Date类型](../../../quick-start/arkts-appstorage.md#装饰date类型变量),支持null、undefined以及[联合类型](../../../quick-start/arkts-appstorage.md#appstorage支持联合类型)。 298 299**原子化服务API:** 从API version 11开始,该接口支持在原子化服务中使用。 300 301**系统能力:** SystemCapability.ArkUI.ArkUI.Full 302 303**参数:** 304 305| 参数名 | 类型 | 必填 | 说明 | 306| -------- | ------ | ---- | ---------------------- | 307| propName | string | 是 | AppStorage中的属性名。 | 308| newValue | T | 是 | 属性值,从API version 12开始可以为null或undefined。 | 309 310**返回值:** 311 312| 类型 | 说明 | 313| ------- | ------------------------------------------------------------ | 314| boolean | 如果AppStorage中不存在propName对应的属性,或设值失败,则返回false。设置成功则返回true。 | 315 316**示例:** 317```ts 318AppStorage.setOrCreate('PropA', 48); 319let res: boolean = AppStorage.set('PropA', 47) // true 320let res1: boolean = AppStorage.set('PropB', 47) // false 321``` 322 323 324### setOrCreate<sup>10+</sup> 325 326static setOrCreate<T>(propName: string, newValue: T): void 327 328如果propName已经在[AppStorage](../../../quick-start/arkts-appstorage.md)中存在,并且newValue和propName对应属性的值不同,则设置propName对应属性的值为newValue,否则状态变量不会通知UI刷新propName对应属性的值。 329如果propName不存在,则创建propName属性,值为newValue。setOrCreate只可以创建单个AppStorage的键值对,如果想创建多个AppStorage键值对,可以多次调用此方法。从API version 12开始,newValue可以为null或undefined。 330 331> **说明:**<br/> 332> 从API version 12开始,AppStorage支持[Map](../../../quick-start/arkts-appstorage.md#装饰map类型变量)、[Set](../../../quick-start/arkts-appstorage.md#装饰set类型变量)、[Date类型](../../../quick-start/arkts-appstorage.md#装饰date类型变量),支持null、undefined以及[联合类型](../../../quick-start/arkts-appstorage.md#appstorage支持联合类型)。 333 334**原子化服务API:** 从API version 11开始,该接口支持在原子化服务中使用。 335 336**系统能力:** SystemCapability.ArkUI.ArkUI.Full 337 338**参数:** 339 340| 参数名 | 类型 | 必填 | 说明 | 341| -------- | ------ | ---- | ---------------------- | 342| propName | string | 是 | AppStorage中的属性名。 | 343| newValue | T | 是 | 属性值,从API version 12开始可以为null或undefined。 | 344 345**示例:** 346```ts 347AppStorage.setOrCreate('simpleProp', 121); 348``` 349 350 351### delete<sup>10+</sup> 352 353static delete(propName: string): boolean 354 355在[AppStorage](../../../quick-start/arkts-appstorage.md)中删除propName对应的属性。 356 357在AppStorage中删除该属性的前提是必须保证该属性没有订阅者。如果有订阅者,则返回false。如果没有订阅者则删除成功并返回true。 358 359属性的订阅者为: 360 3611. [\@StorageLink](../../../quick-start/arkts-appstorage.md#storagelink)、[\@StorageProp](../../../quick-start/arkts-appstorage.md#storageprop)装饰的变量。 362 3632. 通过[link](#link10)、[prop](#prop10)、[setAndLink](#setandlink10)、[setAndProp](#setandprop10)接口返回的[SubscribedAbstractProperty](#subscribedabstractproperty)的实例。 364 365如果想要删除这些订阅者,可以通过以下方式: 366 3671. 删除\@StorageLink、\@StorageProp所在的自定义组件。删除自定义组件请参考[自定义组件的删除](../../../quick-start/arkts-page-custom-components-lifecycle.md#自定义组件的删除)。 368 3692. 对link、prop、setAndLink、setAndProp接口返回的SubscribedAbstractProperty的实例调用[aboutToBeDeleted](#abouttobedeleted10)接口。 370 371**原子化服务API:** 从API version 11开始,该接口支持在原子化服务中使用。 372 373**系统能力:** SystemCapability.ArkUI.ArkUI.Full 374 375**参数:** 376 377| 参数名 | 类型 | 必填 | 说明 | 378| -------- | ------ | ---- | ---------------- | 379| propName | string | 是 | AppStorage中的属性名。 | 380 381**返回值:** 382 383| 类型 | 说明 | 384| ------- | ---------------------------------------- | 385| boolean | 如果AppStorage中有对应的属性,且该属性已经没有订阅者,则删除成功,返回true。如果属性不存在,或者该属性还存在订阅者,则返回false。 | 386 387**示例:** 388```ts 389AppStorage.setOrCreate('PropA', 47); 390AppStorage.link<number>('PropA'); 391let res: boolean = AppStorage.delete('PropA'); // false, PropA still has a subscriber 392 393AppStorage.setOrCreate('PropB', 48); 394let res1: boolean = AppStorage.delete('PropB'); // true, PropB is deleted from AppStorage successfully 395``` 396 397 398### keys<sup>10+</sup> 399 400static keys(): IterableIterator<string> 401 402返回[AppStorage](../../../quick-start/arkts-appstorage.md)中所有的属性名。 403 404**原子化服务API:** 从API version 11开始,该接口支持在原子化服务中使用。 405 406**系统能力:** SystemCapability.ArkUI.ArkUI.Full 407 408**返回值:** 409 410| 类型 | 说明 | 411| ------------------------------ | ------------------ | 412| IterableIterator<string> | AppStorage中所有的属性名。 | 413 414**示例:** 415```ts 416AppStorage.setOrCreate('PropB', 48); 417let keys: IterableIterator<string> = AppStorage.keys(); 418``` 419 420 421### clear<sup>10+</sup> 422 423static clear(): boolean 424 425删除[AppStorage](../../../quick-start/arkts-appstorage.md)中所有属性。删除所有属性的前提是,AppStorage已经没有任何订阅者。如果有订阅者,clear将不会生效并返回false。如果没有订阅者,则删除成功,并返回true。 426 427订阅者的含义参考[delete](#delete10)。 428 429**原子化服务API:** 从API version 11开始,该接口支持在原子化服务中使用。 430 431**系统能力:** SystemCapability.ArkUI.ArkUI.Full 432 433**返回值:** 434 435| 类型 | 说明 | 436| ------- | ------------------------------------------------------------ | 437| boolean | 如果AppStorage中的属性已经没有订阅者则删除成功,返回true。否则返回false。 | 438 439**示例:** 440```ts 441AppStorage.setOrCreate('PropA', 47); 442let res: boolean = AppStorage.clear(); // true, there are no subscribers 443``` 444 445 446### size<sup>10+</sup> 447 448static size(): number 449 450返回[AppStorage](../../../quick-start/arkts-appstorage.md)中的属性数量。 451 452**原子化服务API:** 从API version 11开始,该接口支持在原子化服务中使用。 453 454**系统能力:** SystemCapability.ArkUI.ArkUI.Full 455 456**返回值:** 457 458| 类型 | 说明 | 459| ------ | ------------------- | 460| number | 返回AppStorage中属性的数量。 | 461 462**示例:** 463```ts 464AppStorage.setOrCreate('PropB', 48); 465let res: number = AppStorage.size(); // 1 466``` 467 468 469### Link<sup>(deprecated)</sup> 470 471static Link(propName: string): any 472 473与[AppStorage](../../../quick-start/arkts-appstorage.md)中对应的propName建立双向数据绑定。如果给定的propName在AppStorage中存在,返回与AppStorage中propName对应属性的双向绑定数据。 474 475双向绑定数据的修改会同步回AppStorage中,AppStorage会将变化同步到所有绑定该propName的数据和自定义组件中。 476 477如果AppStorage中不存在propName,则返回undefined。 478 479> **说明:**<br/> 480> 从API version 7 开始支持,从API version 10 开始废弃,推荐使用[link10+](#link10)替代。 481 482**系统能力:** SystemCapability.ArkUI.ArkUI.Full 483 484**参数:** 485 486| 参数名 | 类型 | 必填 | 说明 | 487| -------- | ------ | ---- | ---------------- | 488| propName | string | 是 | AppStorage中的属性名。 | 489 490**返回值:** 491 492| 类型 | 说明 | 493| -------------------------------- | ------------------------------------------------------------ | 494| any | 返回双向绑定的数据,如果AppStorage中不存在对应的propName,则返回undefined。 | 495 496**示例:** 497```ts 498AppStorage.SetOrCreate('PropA', 47); 499let linkToPropA1: SubscribedAbstractProperty<number> = AppStorage.Link('PropA'); 500let linkToPropA2: SubscribedAbstractProperty<number> = AppStorage.Link('PropA'); // linkToPropA2.get() == 47 501linkToPropA1.set(48); // 双向同步: linkToPropA1.get() == linkToPropA2.get() == 48 502``` 503 504### SetAndLink<sup>(deprecated)</sup> 505 506static SetAndLink<T>(propName: string, defaultValue: T): SubscribedAbstractProperty<T> 507 508与[Link](#linkdeprecated)接口类似,如果给定的propName在[AppStorage](../../../quick-start/arkts-appstorage.md)中存在,则返回该propName对应的属性的双向绑定数据。如果不存在,则使用defaultValue在AppStorage中创建和初始化propName对应的属性,并返回其双向绑定数据。defaultValue必须为T类型,且不能为null或undefined。 509 510> **说明:**<br/> 511> 从API version 7 开始支持,从API version 10 开始废弃,推荐使用[setAndLink10+](#setandlink10)替代。 512 513**系统能力:** SystemCapability.ArkUI.ArkUI.Full 514 515**参数:** 516 517| 参数名 | 类型 | 必填 | 说明 | 518| ------------ | ------ | ---- | ------------------------------------------------------------ | 519| propName | string | 是 | AppStorage中的属性名。 | 520| defaultValue | T | 是 | 当propName在AppStorage中不存在,使用defaultValue在AppStorage中初始化对应的propName,defaultValue不能为null或undefined。 | 521 522**返回值:** 523 524| 类型 | 说明 | 525| ----------------------------------- | ---------------------------------------- | 526| [SubscribedAbstractProperty<T>](#subscribedabstractproperty) | SubscribedAbstractProperty<T>的实例,和AppStorage中propName对应属性的双向绑定的数据。 | 527 528**示例:** 529```ts 530AppStorage.SetOrCreate('PropA', 47); 531let link1: SubscribedAbstractProperty<number> = AppStorage.SetAndLink('PropB', 49); // Create PropB 49 532let link2: SubscribedAbstractProperty<number> = AppStorage.SetAndLink('PropA', 50); // PropA exists, remains 47 533``` 534 535 536### Prop<sup>(deprecated)</sup> 537 538static Prop(propName: string): any 539 540与[AppStorage](../../../quick-start/arkts-appstorage.md)中对应的propName建立单向属性绑定。如果给定的propName在AppStorage中存在,则返回与AppStorage中propName对应属性的单向绑定数据。如果AppStorage中不存在propName,则返回undefined。单向绑定数据的修改不会被同步回AppStorage中。 541 542> **说明:**<br/> 543> Prop仅支持简单类型。 544> 从API version 7 开始支持,从API version 10 开始废弃,推荐使用[prop10+](#prop10)替代。 545 546**系统能力:** SystemCapability.ArkUI.ArkUI.Full 547 548**参数:** 549 550| 参数名 | 类型 | 必填 | 说明 | 551| -------- | ------ | ---- | ---------------- | 552| propName | string | 是 | AppStorage中的属性名。 | 553 554**返回值:** 555 556| 类型 | 说明 | 557| -------------------------------- | ------------------------------------------------------------ | 558| any | 返回单向绑定的数据,如果AppStorage中不存在对应的propName,则返回undefined。 | 559 560**示例:** 561```ts 562AppStorage.SetOrCreate('PropA', 47); 563let prop1: SubscribedAbstractProperty<number> = AppStorage.Prop('PropA'); 564let prop2: SubscribedAbstractProperty<number> = AppStorage.Prop('PropA'); 565prop1.set(1); // one-way sync: prop1.get()=1; but prop2.get() == 47 566``` 567 568### SetAndProp<sup>(deprecated)</sup> 569 570static SetAndProp<S>(propName: string, defaultValue: S): SubscribedAbstractProperty<S> 571 572与[Prop](#propdeprecated)接口类似。如果给定的propName在[AppStorage](../../../quick-start/arkts-appstorage.md)中存在,则返回该propName对应的属性的单向绑定数据。如果不存在,则使用defaultValue在AppStorage中创建和初始化propName对应的属性,返回其单向绑定数据。defaultValue必须为S类型,且不能为null或undefined。 573 574> **说明:**<br/> 575> 从API version 7 开始支持,从API version 10 开始废弃,推荐使用[setAndProp10+](#setandprop10)替代。 576 577**系统能力:** SystemCapability.ArkUI.ArkUI.Full 578 579**参数:** 580 581| 参数名 | 类型 | 必填 | 说明 | 582| ------------ | ------ | ---- | ------------------------------------------------------------ | 583| propName | string | 是 | AppStorage中的属性名。 | 584| defaultValue | S | 是 | 当propName在AppStorage中不存在时,使用defaultValue在AppStorage中初始化对应的propName,defaultValue不能为null或undefined。 | 585 586**返回值:** 587 588| 类型 | 说明 | 589| ----------------------------------- | --------------------------------------- | 590| [SubscribedAbstractProperty<S>](#subscribedabstractproperty) | SubscribedAbstractProperty<S>的实例。 | 591 592**示例:** 593```ts 594AppStorage.SetOrCreate('PropA', 47); 595let prop: SubscribedAbstractProperty<number> = AppStorage.SetAndProp('PropB', 49); // PropA -> 47, PropB -> 49 596``` 597 598### Has<sup>(deprecated)</sup> 599 600static Has(propName: string): boolean 601 602判断propName对应的属性是否在[AppStorage](../../../quick-start/arkts-appstorage.md)中存在。 603 604> **说明:**<br/> 605> 从API version 7 开始支持,从API version 10 开始废弃,推荐使用[has10+](#has10)替代。 606 607**系统能力:** SystemCapability.ArkUI.ArkUI.Full 608 609**参数:** 610 611| 参数名 | 类型 | 必填 | 说明 | 612| -------- | ------ | ---- | ---------------- | 613| propName | string | 是 | AppStorage中的属性名。 | 614 615**返回值:** 616 617| 类型 | 说明 | 618| ------- | ---------------------------------------- | 619| boolean | 如果propName对应的属性在AppStorage中存在,则返回true。不存在则返回false。 | 620 621**示例:** 622```ts 623AppStorage.Has('simpleProp'); 624``` 625 626### Get<sup>(deprecated)</sup> 627 628static Get<T>(propName: string): T | undefined 629 630获取propName在[AppStorage](../../../quick-start/arkts-appstorage.md)中对应的属性值。如果不存在则返回undefined。 631 632> **说明:**<br/> 633> 从API version 7 开始支持,从API version 10 开始废弃,推荐使用[get10+](#get10)替代。 634 635**系统能力:** SystemCapability.ArkUI.ArkUI.Full 636 637**参数:** 638 639| 参数名 | 类型 | 必填 | 说明 | 640| -------- | ------ | ---- | ---------------- | 641| propName | string | 是 | AppStorage中的属性名。 | 642 643**返回值:** 644 645| 类型 | 说明 | 646| ------------------------ | ------------------------------------------------------------ | 647| T \| undefined | AppStorage中propName对应的属性值,如果不存在则返回undefined。 | 648 649**示例:** 650```ts 651AppStorage.SetOrCreate('PropA', 47); 652let value: number = AppStorage.Get('PropA') as number; // 47 653``` 654 655### Set<sup>(deprecated)</sup> 656 657static Set<T>(propName: string, newValue: T): boolean 658 659在[AppStorage](../../../quick-start/arkts-appstorage.md)中设置propName对应属性的值。 660 661> **说明:**<br/> 662> 从API version 7 开始支持,从API version 10 开始废弃,推荐使用[set10+](#set10)替代。 663 664**系统能力:** SystemCapability.ArkUI.ArkUI.Full 665 666**参数:** 667 668| 参数名 | 类型 | 必填 | 说明 | 669| -------- | ------ | ---- | ------------------------------- | 670| propName | string | 是 | AppStorage中的属性名。 | 671| newValue | T | 是 | 属性值,不能为null或undefined。 | 672 673**返回值:** 674 675| 类型 | 说明 | 676| ------- | ------------------------------------------------------------ | 677| boolean | 如果AppStorage中不存在propName对应的属性,或者设置的newValue是undefined或者null,返回false。设置成功则返回true。 | 678 679**示例:** 680```ts 681AppStorage.SetOrCreate('PropA', 48); 682let res: boolean = AppStorage.Set('PropA', 47) // true 683let res1: boolean = AppStorage.Set('PropB', 47) // false 684``` 685 686### SetOrCreate<sup>(deprecated)</sup> 687 688static SetOrCreate<T>(propName: string, newValue: T): void 689 690如果propName已经在[AppStorage](../../../quick-start/arkts-appstorage.md)中存在,则设置propName对应是属性的值为newValue。如果不存在,则创建propName属性,值为newValue。 691 692newValue不能为null或undefined。 693 694> **说明:**<br/> 695> 从API version 7 开始支持,从API version 10 开始废弃,推荐使用[setOrCreate10+](#setorcreate10)替代。 696 697**系统能力:** SystemCapability.ArkUI.ArkUI.Full 698 699**参数:** 700 701| 参数名 | 类型 | 必填 | 说明 | 702| -------- | ------ | ---- | ------------------------------- | 703| propName | string | 是 | AppStorage中的属性名。 | 704| newValue | T | 是 | 属性值,不能为null或undefined。 | 705 706**示例:** 707```ts 708AppStorage.SetOrCreate('simpleProp', 121); 709``` 710 711### Delete<sup>(deprecated)</sup> 712 713static Delete(propName: string): boolean 714 715在[AppStorage](../../../quick-start/arkts-appstorage.md)中删除propName对应的属性。 716 717在AppStorage中删除该属性的前提是必须保证该属性没有订阅者。如果有订阅者,则返回false。如果没有订阅者则删除成功并返回true。 718 719属性的订阅者为[Link](#linkdeprecated)、[Prop](#propdeprecated)等接口绑定的propName,以及[\@StorageLink('propName')](../../../quick-start/arkts-appstorage.md#storagelink)和[\@StorageProp('propName')](../../../quick-start/arkts-appstorage.md#storageprop)。如果自定义组件中使用\@StorageLink('propName')和\@StorageProp('propName')或者SubscribedAbstractProperty实例依旧对propName有同步关系,则该属性不能从AppStorage中删除。 720 721> **说明:**<br/> 722> 从API version 7 开始支持,从API version 10 开始废弃,推荐使用[delete10+](#delete10)替代。 723 724**系统能力:** SystemCapability.ArkUI.ArkUI.Full 725 726**参数:** 727 728| 参数名 | 类型 | 必填 | 说明 | 729| -------- | ------ | ---- | ---------------- | 730| propName | string | 是 | AppStorage中的属性名。 | 731 732**返回值:** 733 734| 类型 | 说明 | 735| ------- | ---------------------------------------- | 736| boolean | 如果AppStorage中有对应的属性,且该属性已经没有订阅者,则删除成功,返回true。如果属性不存在,或者该属性还存在订阅者,则返回false。 | 737 738**示例:** 739```ts 740AppStorage.SetOrCreate('PropA', 47); 741AppStorage.Link('PropA'); 742let res: boolean = AppStorage.Delete('PropA'); // false, PropA still has a subscriber 743 744AppStorage.SetOrCreate('PropB', 48); 745let res1: boolean = AppStorage.Delete('PropB'); // true, PropB is deleted from AppStorage successfully 746``` 747 748### Keys<sup>(deprecated)</sup> 749 750static Keys(): IterableIterator<string> 751 752返回[AppStorage](../../../quick-start/arkts-appstorage.md)中所有的属性名。 753 754> **说明:**<br/> 755> 从API version 7 开始支持,从API version 10 开始废弃,推荐使用[keys10+](#keys10)替代。 756 757**系统能力:** SystemCapability.ArkUI.ArkUI.Full 758 759**返回值:** 760 761| 类型 | 说明 | 762| ------------------------------ | ------------------ | 763| IterableIterator<string> | AppStorage中所有的属性名。 | 764 765**示例:** 766```ts 767AppStorage.SetOrCreate('PropB', 48); 768let keys: IterableIterator<string> = AppStorage.Keys(); 769``` 770 771 772### staticClear<sup>(deprecated)</sup> 773 774static staticClear(): boolean 775 776删除所有的属性。 777 778> **说明:**<br/> 779> 从API version 7 开始支持,从API version 9 开始废弃,推荐使用[clear10+](#clear10)替代。 780 781**系统能力:** SystemCapability.ArkUI.ArkUI.Full 782 783**返回值:** 784 785| 类型 | 说明 | 786| ------- | --------------------------------- | 787| boolean | 删除所有的属性,如果当前有状态变量依旧引用此属性,返回false。 | 788 789**示例:** 790```ts 791let simple = AppStorage.staticClear(); 792``` 793 794 795### Clear<sup>(deprecated)</sup> 796 797static Clear(): boolean 798 799删除[AppStorage](../../../quick-start/arkts-appstorage.md)中所有属性。删除所有属性的前提是,AppStorage已经没有任何订阅者。如果有订阅者,Clear将不会生效并返回false。如果没有订阅者且删除成功则返回true。 800 801订阅者的含义参考[delete](#delete10)。 802 803> **说明:**<br/> 804> 从API version 9 开始支持,从API version 10 开始废弃,推荐使用[clear10+](#clear10)替代。 805 806**系统能力:** SystemCapability.ArkUI.ArkUI.Full 807 808**返回值:** 809 810| 类型 | 说明 | 811| ------- | ------------------------------------------------------------ | 812| boolean | 如果AppStorage中的属性已经没有订阅者则删除成功,返回true。否则返回false。 | 813 814**示例:** 815```typescript 816AppStorage.SetOrCreate('PropA', 47); 817let res: boolean = AppStorage.Clear(); // true, there are no subscribers 818``` 819 820 821### IsMutable<sup>(deprecated)</sup> 822 823static IsMutable(propName: string): boolean 824 825返回[AppStorage](../../../quick-start/arkts-appstorage.md)中propName对应的属性是否是可变的。 826 827> **说明:**<br/> 828> 从API version 7 开始支持,从API version 10 开始废弃。 829 830**系统能力:** SystemCapability.ArkUI.ArkUI.Full 831 832**参数:** 833 834| 参数名 | 类型 | 必填 | 说明 | 835| -------- | ------ | ---- | ---------------- | 836| propName | string | 是 | AppStorage中的属性名。 | 837 838**返回值:** 839 840| 类型 | 说明 | 841| ------- | -------------------------------- | 842| boolean | 返回AppStorage中propNam对应的属性是否是可变的。 | 843 844**示例:** 845```ts 846AppStorage.SetOrCreate('PropA', 47); 847let res: boolean = AppStorage.IsMutable('simpleProp'); 848``` 849 850 851### Size<sup>(deprecated)</sup> 852 853static Size(): number 854 855返回[AppStorage](../../../quick-start/arkts-appstorage.md)中的属性数量。 856 857> **说明:**<br/> 858> 从API version 7 开始支持,从API version 10 开始废弃,推荐使用[size10+](#size10)替代。 859 860**系统能力:** SystemCapability.ArkUI.ArkUI.Full 861 862**返回值:** 863 864| 类型 | 说明 | 865| ------ | ------------------- | 866| number | 返回AppStorage中属性的数量。 | 867 868**示例:** 869```ts 870AppStorage.SetOrCreate('PropB', 48); 871let res: number = AppStorage.Size(); // 1 872``` 873 874 875## LocalStorage<sup>9+</sup> 876 877 878LocalStorage具体UI使用说明,详见[LocalStorage(页面级UI状态存储)](../../../quick-start/arkts-localstorage.md) 879 880**卡片能力:** 从API version 9开始,支持在ArkTS卡片中使用。 881 882**原子化服务API:** 从API version 11开始,该接口支持在原子化服务中使用。 883 884**系统能力:** SystemCapability.ArkUI.ArkUI.Full 885 886### constructor<sup>9+</sup> 887 888constructor(initializingProperties?: Object) 889 890创建一个新的[LocalStorage](../../../quick-start/arkts-localstorage.md)实例。使用Object.keys(initializingProperties)返回的属性和其数值,初始化LocalStorage实例。 891 892**卡片能力:** 从API version 9开始,该接口支持在ArkTS卡片中使用。 893 894**原子化服务API:** 从API version 11开始,该接口支持在原子化服务中使用。 895 896**系统能力:** SystemCapability.ArkUI.ArkUI.Full 897 898**参数:** 899 900| 参数名 | 类型 | 必填 | 说明 | 901| ---------------------- | ------ | ---- | ---------------------------------------- | 902| initializingProperties | Object | 否 | 用initializingProperties包含的属性和数值初始化LocalStorage。initializingProperties不能为undefined。 | 903 904**示例:** 905```ts 906let para: Record<string, number> = { 'PropA': 47 }; 907let storage: LocalStorage = new LocalStorage(para); 908``` 909 910 911### getShared<sup>10+</sup> 912 913static getShared(): LocalStorage 914 915获取当前stage共享的[LocalStorage](../../../quick-start/arkts-localstorage.md)实例。 916 917**卡片能力:** 从API version 10开始,该接口支持在ArkTS卡片中使用。 918 919**原子化服务API:** 从API version 11开始,该接口支持在原子化服务中使用。 920 921**系统能力:** SystemCapability.ArkUI.ArkUI.Full 922 923**模型约束:** 此接口仅可在Stage模型下使用。 924 925**返回值:** 926 927| 类型 | 说明 | 928| ------------------------------ | ----------------- | 929| [LocalStorage](#localstorage9) | 返回LocalStorage实例。 | 930 931**示例:** 932getShared具体使用,见[在UI页面通过getShared接口获取在通过loadContent共享的LocalStorage实例](../../../quick-start/arkts-localstorage.md#将localstorage实例从uiability共享到一个或多个视图) 933 934 935### has<sup>9+</sup> 936 937has(propName: string): boolean 938 939判断propName对应的属性是否在[LocalStorage](../../../quick-start/arkts-localstorage.md)中存在。 940 941**卡片能力:** 从API version 9开始,该接口支持在ArkTS卡片中使用。 942 943**原子化服务API:** 从API version 11开始,该接口支持在原子化服务中使用。 944 945**系统能力:** SystemCapability.ArkUI.ArkUI.Full 946 947**参数:** 948 949| 参数名 | 类型 | 必填 | 说明 | 950| -------- | ------ | ---- | ------------------ | 951| propName | string | 是 | LocalStorage中的属性名。 | 952 953**返回值:** 954 955| 类型 | 说明 | 956| ------- | ------------------------------------------------------------ | 957| boolean | 如果propName对应的属性在LocalStorage中存在,则返回true。不存在则返回false。 | 958 959**示例:** 960```ts 961let para: Record<string, number> = { 'PropA': 47 }; 962let storage: LocalStorage = new LocalStorage(para); 963storage.has('PropA'); // true 964``` 965 966 967### get<sup>9+</sup> 968 969get<T>(propName: string): T | undefined 970 971获取propName在[LocalStorage](../../../quick-start/arkts-localstorage.md)中对应的属性值。 972 973**卡片能力:** 从API version 9开始,该接口支持在ArkTS卡片中使用。 974 975**原子化服务API:** 从API version 11开始,该接口支持在原子化服务中使用。 976 977**系统能力:** SystemCapability.ArkUI.ArkUI.Full 978 979**参数:** 980 981| 参数名 | 类型 | 必填 | 说明 | 982| -------- | ------ | ---- | ------------------ | 983| propName | string | 是 | LocalStorage中的属性名。 | 984 985**返回值:** 986 987| 类型 | 说明 | 988| ------------------------ | ------------------------------------------------------------ | 989| T \| undefined | LocalStorage中propName对应的属性值,如果不存在则返回undefined。 | 990 991**示例:** 992```ts 993let para: Record<string, number> = { 'PropA': 47 }; 994let storage: LocalStorage = new LocalStorage(para); 995let value: number = storage.get('PropA') as number; // 47 996``` 997 998 999### set<sup>9+</sup> 1000 1001set<T>(propName: string, newValue: T): boolean 1002 1003在[LocalStorage](../../../quick-start/arkts-localstorage.md)中设置propName对应属性的值。如果newValue的值和propName对应属性的值相同,即不需要做赋值操作,状态变量不会通知UI刷新propName对应属性的值。从API version 12开始,newValue可以为null或undefined。 1004 1005> **说明:** 1006> 1007> 从API version 12开始,LocalStorage支持[Map](../../../quick-start/arkts-localstorage.md#装饰map类型变量)、[Set](../../../quick-start/arkts-localstorage.md#装饰set类型变量)、[Date类型](../../../quick-start/arkts-localstorage.md#装饰date类型变量),支持null、undefined以及[联合类型](../../../quick-start/arkts-localstorage.md#localstorage支持联合类型)。 1008 1009**卡片能力:** 从API version 9开始,该接口支持在ArkTS卡片中使用。 1010 1011**原子化服务API:** 从API version 11开始,该接口支持在原子化服务中使用。 1012 1013**系统能力:** SystemCapability.ArkUI.ArkUI.Full 1014 1015**参数:** 1016 1017| 参数名 | 类型 | 必填 | 说明 | 1018| -------- | ------ | ---- | ----------------------- | 1019| propName | string | 是 | LocalStorage中的属性名。 | 1020| newValue | T | 是 | 属性值,从API version 12开始可以为undefined或者null。 | 1021 1022**返回值:** 1023 1024| 类型 | 说明 | 1025| ------- | ------------------------------------------------------------ | 1026| boolean | 如果LocalStorage中不存在propName对应的属性,返回false。设置成功返回true。 | 1027 1028**示例:** 1029 1030```ts 1031let para: Record<string, number> = { 'PropA': 47 }; 1032let storage: LocalStorage = new LocalStorage(para); 1033let res: boolean = storage.set('PropA', 47); // true 1034let res1: boolean = storage.set('PropB', 47); // false 1035``` 1036 1037 1038### setOrCreate<sup>9+</sup> 1039 1040setOrCreate<T>(propName: string, newValue: T): boolean 1041 1042如果propName已经在[LocalStorage](../../../quick-start/arkts-localstorage.md)中存在,并且newValue和propName对应属性的值不同,则设置propName对应属性的值为newValue,否则状态变量不会通知UI刷新propName对应属性的值。 1043如果propName不存在,则创建propName属性,值为newValue。setOrCreate只可以创建单个LocalStorage的键值对,如果想创建多个LocalStorage键值对,可以多次调用此方法。从API version 12开始,newValue可以为null或undefined。 1044 1045> **说明:** 1046> 1047> 从API version 12开始,LocalStorage支持[Map](../../../quick-start/arkts-localstorage.md#装饰map类型变量)、[Set](../../../quick-start/arkts-localstorage.md#装饰set类型变量)、[Date类型](../../../quick-start/arkts-localstorage.md#装饰date类型变量),支持null、undefined以及[联合类型](../../../quick-start/arkts-localstorage.md#localstorage支持联合类型)。 1048 1049**卡片能力:** 从API version 9开始,该接口支持在ArkTS卡片中使用。 1050 1051**原子化服务API:** 从API version 11开始,该接口支持在原子化服务中使用。 1052 1053**系统能力:** SystemCapability.ArkUI.ArkUI.Full 1054 1055**参数:** 1056 1057| 参数名 | 类型 | 必填 | 说明 | 1058| -------- | ------ | ---- | ----------------------- | 1059| propName | string | 是 | LocalStorage中的属性名。 | 1060| newValue | T | 是 | 属性值,从API version 12开始可以为undefined或者null。 | 1061 1062**返回值:** 1063 1064| 类型 | 说明 | 1065| ------- | ------------------------------------------------------------ | 1066| boolean | 如果LocalStorage中存在propName,则更新其值为newValue,返回true。<br/>如果LocalStorage中不存在propName,则创建propName,并初始化其值为newValue,返回true。 | 1067 1068**示例:** 1069 1070```ts 1071let para: Record<string, number> = { 'PropA': 47 }; 1072let storage: LocalStorage = new LocalStorage(para); 1073let res: boolean = storage.setOrCreate('PropA', 121); // true 1074let res1: boolean = storage.setOrCreate('PropB', 111); // true 1075let res2: boolean = storage.setOrCreate('PropB', null); // true (API12及之后返回true,API11及之前返回false) 1076``` 1077 1078### ref<sup>12+</sup> 1079 1080public ref\<T\>(propName: string): AbstractProperty\<T\> | undefined 1081 1082如果给定的propName在[LocalStorage](../../../quick-start/arkts-localstorage.md)中存在,则获得LocalStorage中propName对应数据的引用。否则,返回undefined。 1083 1084与[link](#link9)的功能基本一致,但不需要手动释放返回的[AbstractProperty](#abstractproperty)类型的变量。 1085 1086**原子化服务API:** 从API version 12开始,该接口支持在原子化服务中使用。 1087 1088**系统能力:** SystemCapability.ArkUI.ArkUI.Full 1089 1090**参数:** 1091 1092| 参数名 | 类型 | 必填 | 说明 | 1093| -------- | ------ | ---- | ------------------------ | 1094| propName | string | 是 | LocalStorage中的属性名。 | 1095 1096**返回值:** 1097 1098| 类型 | 说明 | 1099| -------------------------------------- | ------------------------------------------------------------ | 1100| [AbstractProperty<T>](#abstractproperty) \| undefined | LocalStorage中propName对应属性的引用,如果LocalStorage中不存在对应的propName,则返回undefined。 | 1101 1102**示例:** 1103 1104```ts 1105let para: Record<string, number> = { 'PropA': 47 }; 1106let storage: LocalStorage = new LocalStorage(para); 1107let refToPropA1: AbstractProperty<number> | undefined = storage.ref('PropA'); 1108let refToPropA2: AbstractProperty<number> | undefined = storage.ref('PropA'); // refToPropA2.get() == 47 1109refToPropA1?.set(48); // refToPropA1.get() == refToPropA2.get() == 48 1110``` 1111 1112### setAndRef<sup>12+</sup> 1113 1114public setAndRef<T>(propName: string, defaultValue: T): AbstractProperty<T> 1115 1116与[ref](#ref12-1)接口类似,如果给定的propName在[LocalStorage](../../../quick-start/arkts-localstorage.md)中存在,则获得LocalStorage中propName对应数据的引用。如果不存在,则使用defaultValue在LocalStorage中创建和初始化propName对应的属性,并返回其引用。defaultValue须为T类型,可以为null或undefined。 1117 1118与[setAndLink](#setandlink9)的功能基本一致,但不需要手动释放返回的[AbstractProperty](#abstractproperty)类型的变量。 1119 1120> **说明:**<br/> 1121> 从API version 12开始,LocalStorage支持[Map](../../../quick-start/arkts-localstorage.md#装饰map类型变量)、[Set](../../../quick-start/arkts-localstorage.md#装饰set类型变量)、[Date类型](../../../quick-start/arkts-localstorage.md#装饰date类型变量),支持null、undefined以及[联合类型](../../../quick-start/arkts-localstorage.md#localstorage支持联合类型)。 1122 1123**原子化服务API:** 从API version 12开始,该接口支持在原子化服务中使用。 1124 1125**系统能力:** SystemCapability.ArkUI.ArkUI.Full 1126 1127**参数:** 1128 1129| 参数名 | 类型 | 必填 | 说明 | 1130| ------------ | ------ | ---- | ------------------------------------------------------------ | 1131| propName | string | 是 | LocalStorage中的属性名。 | 1132| defaultValue | T | 是 | 当propName在LocalStorage中不存在时,使用defaultValue在LocalStorage中初始化对应的propName,defaultValue可以为null或undefined。 | 1133 1134**返回值:** 1135 1136| 类型 | 说明 | 1137| ------------------------- | ------------------------------------------------------------ | 1138| [AbstractProperty<T>](#abstractproperty) | AbstractProperty<T>的实例,为LocalStorage中propName对应属性的引用。 | 1139 1140**示例:** 1141 1142```ts 1143let para: Record<string, number> = { 'PropA': 47 }; 1144let storage: LocalStorage = new LocalStorage(para); 1145let ref1: AbstractProperty<number> = storage.setAndRef('PropB', 49); // Create PropB 49 1146let ref2: AbstractProperty<number> = storage.setAndRef('PropA', 50); // PropA exists, remains 47 1147``` 1148 1149### link<sup>9+</sup> 1150 1151link<T>(propName: string): SubscribedAbstractProperty<T> 1152 1153如果给定的propName在[LocalStorage](../../../quick-start/arkts-localstorage.md)实例中存在,则返回与LocalStorage中propName对应属性的双向绑定数据。 1154 1155双向绑定数据的修改会被同步回LocalStorage中,LocalStorage会将变化同步到所有绑定该propName的数据和Component中。 1156 1157如果LocalStorage中不存在propName,则返回undefined。 1158 1159**卡片能力:** 从API version 9开始,该接口支持在ArkTS卡片中使用。 1160 1161**原子化服务API:** 从API version 11开始,该接口支持在原子化服务中使用。 1162 1163**系统能力:** SystemCapability.ArkUI.ArkUI.Full 1164 1165**参数:** 1166 1167| 参数名 | 类型 | 必填 | 说明 | 1168| -------- | ------ | ---- | ------------------ | 1169| propName | string | 是 | LocalStorage中的属性名。 | 1170 1171**返回值:** 1172 1173| 类型 | 说明 | 1174| ----------------------------------- | ------------------------------------------------------------ | 1175| [SubscribedAbstractProperty<T>](#subscribedabstractproperty) | SubscribedAbstractProperty<T>的实例,与LocalStorage中propName对应属性的双向绑定的数据,如果LocalStorage中不存在对应的propName,则返回undefined。 | 1176 1177**示例:** 1178```ts 1179let para: Record<string, number> = { 'PropA': 47 }; 1180let storage: LocalStorage = new LocalStorage(para); 1181let linkToPropA1: SubscribedAbstractProperty<number> = storage.link('PropA'); 1182let linkToPropA2: SubscribedAbstractProperty<number> = storage.link('PropA'); // linkToPropA2.get() == 47 1183linkToPropA1.set(48); // 双向同步: linkToPropA1.get() == linkToPropA2.get() == 48 1184``` 1185 1186 1187### setAndLink<sup>9+</sup> 1188 1189setAndLink<T>(propName: string, defaultValue: T): SubscribedAbstractProperty<T> 1190 1191与[link](#link9)接口类似,如果给定的propName在[LocalStorage](../../../quick-start/arkts-localstorage.md)中存在,则返回该propName对应的属性的双向绑定数据。如果不存在,则使用defaultValue在LocalStorage中创建和初始化propName对应的属性,返回其双向绑定数据。defaultValue必须为T类型,从API开始defaultValue可以为null或undefined。 1192 1193> **说明:** 1194> 1195> 从API version 12开始,LocalStorage支持[Map](../../../quick-start/arkts-localstorage.md#装饰map类型变量)、[Set](../../../quick-start/arkts-localstorage.md#装饰set类型变量)、[Date类型](../../../quick-start/arkts-localstorage.md#装饰date类型变量),支持null、undefined以及[联合类型](../../../quick-start/arkts-localstorage.md#localstorage支持联合类型)。 1196 1197**卡片能力:** 从API version 9开始,该接口支持在ArkTS卡片中使用。 1198 1199**原子化服务API:** 从API version 11开始,该接口支持在原子化服务中使用。 1200 1201**系统能力:** SystemCapability.ArkUI.ArkUI.Full 1202 1203**参数:** 1204 1205| 参数名 | 类型 | 必填 | 说明 | 1206| ------------ | ------ | ---- | ------------------------------------------------------------ | 1207| propName | string | 是 | LocalStorage中的属性名。 | 1208| defaultValue | T | 是 | 当propName在LocalStorage中不存在时,使用defaultValue在LocalStorage中初始化对应的propName,从API version 12开始defaultValue可以为null或undefined。 | 1209 1210**返回值:** 1211 1212| 类型 | 说明 | 1213| ----------------------------------- | ------------------------------------------------------------ | 1214| [SubscribedAbstractProperty<T>](#subscribedabstractproperty) | SubscribedAbstractProperty<T>的实例,与LocalStorage中propName对应属性的双向绑定的数据。 | 1215 1216**示例:** 1217```ts 1218let para: Record<string, number> = { 'PropA': 47 }; 1219let storage: LocalStorage = new LocalStorage(para); 1220let link1: SubscribedAbstractProperty<number> = storage.setAndLink('PropB', 49); // Create PropB 49 1221let link2: SubscribedAbstractProperty<number> = storage.setAndLink('PropA', 50); // PropA exists, remains 47 1222``` 1223 1224 1225### prop<sup>9+</sup> 1226 1227prop<S>(propName: string): SubscribedAbstractProperty<S> 1228 1229如果给定的propName在[LocalStorage](../../../quick-start/arkts-localstorage.md)中存在,则返回与LocalStorage中propName对应属性的单向绑定数据。如果LocalStorage中不存在propName,则返回undefined。单向绑定数据的修改不会被同步回LocalStorage中。 1230 1231**卡片能力:** 从API version 9开始,该接口支持在ArkTS卡片中使用。 1232 1233**原子化服务API:** 从API version 11开始,该接口支持在原子化服务中使用。 1234 1235**系统能力:** SystemCapability.ArkUI.ArkUI.Full 1236 1237**参数:** 1238 1239| 参数名 | 类型 | 必填 | 说明 | 1240| -------- | ------ | ---- | ------------------ | 1241| propName | string | 是 | LocalStorage中的属性名。 | 1242 1243**返回值:** 1244 1245| 类型 | 说明 | 1246| ----------------------------------- | ------------------------------------------------------------ | 1247| [SubscribedAbstractProperty<S>](#subscribedabstractproperty) | SubscribedAbstractProperty<S>的实例,和LocalStorage中propName对应属性的单向绑定的数据。如果LocalStorage中不存在对应的propName,则返回undefined。 | 1248 1249**示例:** 1250```ts 1251let para: Record<string, number> = { 'PropA': 47 }; 1252let storage: LocalStorage = new LocalStorage(para); 1253let prop1: SubscribedAbstractProperty<number> = storage.prop('PropA'); 1254let prop2: SubscribedAbstractProperty<number> = storage.prop('PropA'); 1255prop1.set(1); // one-way sync: prop1.get()=1; but prop2.get() == 47 1256``` 1257 1258 1259### setAndProp<sup>9+</sup> 1260 1261setAndProp<S>(propName: string, defaultValue: S): SubscribedAbstractProperty<S> 1262 1263与[prop](#prop9)接口类似。如果propName在[LocalStorage](../../../quick-start/arkts-localstorage.md)中存在,则返回该propName对应的属性的单向绑定数据。如果不存在,则使用defaultValue在LocalStorage中创建和初始化propName对应的属性,返回其单向绑定数据。defaultValue必须为S类型,从API version 12开始defaultValue可以为null或undefined。 1264 1265> **说明:** 1266> 1267> 从API version 12开始,LocalStorage支持[Map](../../../quick-start/arkts-localstorage.md#装饰map类型变量)、[Set](../../../quick-start/arkts-localstorage.md#装饰set类型变量)、[Date类型](../../../quick-start/arkts-localstorage.md#装饰date类型变量),支持null、undefined以及[联合类型](../../../quick-start/arkts-localstorage.md#localstorage支持联合类型)。 1268 1269**卡片能力:** 从API version 9开始,该接口支持在ArkTS卡片中使用。 1270 1271**原子化服务API:** 从API version 11开始,该接口支持在原子化服务中使用。 1272 1273**系统能力:** SystemCapability.ArkUI.ArkUI.Full 1274 1275**参数:** 1276 1277| 参数名 | 类型 | 必填 | 说明 | 1278| ------------ | ------ | ---- | ------------------------------------------------------------ | 1279| propName | string | 是 | LocalStorage中的属性名。 | 1280| defaultValue | S | 是 | 当propName在LocalStorage中不存在,使用defaultValue在LocalStorage中初始化对应的propName,从API version 12开始defaultValue可以为null或undefined。 | 1281 1282**返回值:** 1283 1284| 类型 | 说明 | 1285| ----------------------------------- | ------------------------------------------------------------ | 1286| [SubscribedAbstractProperty<S>](#subscribedabstractproperty) | SubscribedAbstractProperty<S>的实例,和LocalStorage中propName对应属性的单向绑定的数据。 | 1287 1288**示例:** 1289 1290```ts 1291let para: Record<string, number> = { 'PropA': 47 }; 1292let storage: LocalStorage = new LocalStorage(para); 1293let prop: SubscribedAbstractProperty<number> = storage.setAndProp('PropB', 49); // PropA -> 47, PropB -> 49 1294``` 1295 1296 1297### delete<sup>9+</sup> 1298 1299delete(propName: string): boolean 1300 1301在[LocalStorage](../../../quick-start/arkts-localstorage.md)中删除propName对应的属性。在LocalStorage中删除属性的前提是该属性已经没有订阅者,如果有订阅者,则返回false。如果没有订阅者则删除成功并返回true。 1302 1303属性的订阅者为: 1304 13051. [\@LocalStorageLink](../../../quick-start/arkts-localstorage.md#localstoragelink)、[\@LocalStorageProp](../../../quick-start/arkts-localstorage.md#localstorageprop)装饰的变量。 1306 13072. 通过[link](#link9)、[prop](#prop9)、[setAndLink](#setandlink9)、[setAndProp](#setandprop9)接口返回的[SubscribedAbstractProperty](#subscribedabstractproperty)的实例。 1308 1309如果想要删除这些订阅者,可以通过以下方式: 1310 13111. 删除\@LocalStorageLink、\@LocalStorageProp所在的自定义组件。删除自定义组件请参考[自定义组件的删除](../../../quick-start/arkts-page-custom-components-lifecycle.md#自定义组件的删除)。 1312 13132. 对link、prop、setAndLink、setAndProp接口返回的SubscribedAbstractProperty的实例调用[aboutToBeDeleted](#abouttobedeleted10)接口。 1314 1315**卡片能力:** 从API version 9开始,该接口支持在ArkTS卡片中使用。 1316 1317**原子化服务API:** 从API version 11开始,该接口支持在原子化服务中使用。 1318 1319**系统能力:** SystemCapability.ArkUI.ArkUI.Full 1320 1321**参数:** 1322 1323| 参数名 | 类型 | 必填 | 说明 | 1324| -------- | ------ | ---- | ------------------ | 1325| propName | string | 是 | LocalStorage中的属性名。 | 1326 1327**返回值:** 1328 1329| 类型 | 说明 | 1330| ------- | ------------------------------------------------------------ | 1331| boolean | 如果LocalStorage中有对应的属性,且该属性已经没有订阅者,则删除成功,返回true。如果属性不存在,或者该属性还存在订阅者,则返回false。 | 1332 1333**示例:** 1334```ts 1335let para: Record<string, number> = { 'PropA': 47 }; 1336let storage: LocalStorage = new LocalStorage(para); 1337storage.link<number>('PropA'); 1338let res: boolean = storage.delete('PropA'); // false, PropA still has a subscriber 1339let res1: boolean = storage.delete('PropB'); // false, PropB is not in storage 1340storage.setOrCreate('PropB', 48); 1341let res2: boolean = storage.delete('PropB'); // true, PropB is deleted from storage successfully 1342``` 1343 1344 1345### keys<sup>9+</sup> 1346 1347keys(): IterableIterator<string> 1348 1349返回[LocalStorage](../../../quick-start/arkts-localstorage.md)中所有的属性名。 1350 1351**卡片能力:** 从API version 9开始,该接口支持在ArkTS卡片中使用。 1352 1353**原子化服务API:** 从API version 11开始,该接口支持在原子化服务中使用。 1354 1355**系统能力:** SystemCapability.ArkUI.ArkUI.Full 1356 1357**返回值:** 1358 1359| 类型 | 说明 | 1360| ------------------------------ | -------------------- | 1361| IterableIterator<string> | LocalStorage中所有的属性名。 | 1362 1363**示例:** 1364```ts 1365let para: Record<string, number> = { 'PropA': 47 }; 1366let storage: LocalStorage = new LocalStorage(para); 1367let keys: IterableIterator<string> = storage.keys(); 1368``` 1369 1370 1371### size<sup>9+</sup> 1372 1373size(): number 1374 1375返回[LocalStorage](../../../quick-start/arkts-localstorage.md)中的属性数量。 1376 1377**卡片能力:** 从API version 9开始,该接口支持在ArkTS卡片中使用。 1378 1379**原子化服务API:** 从API version 11开始,该接口支持在原子化服务中使用。 1380 1381**系统能力:** SystemCapability.ArkUI.ArkUI.Full 1382 1383**返回值:** 1384 1385| 类型 | 说明 | 1386| ------ | ---------------------------- | 1387| number | LocalStorage中属性的数量。 | 1388 1389**示例:** 1390```ts 1391let para: Record<string, number> = { 'PropA': 47 }; 1392let storage: LocalStorage = new LocalStorage(para); 1393let res: number = storage.size(); // 1 1394``` 1395 1396 1397### clear<sup>9+</sup> 1398 1399clear(): boolean 1400 1401删除[LocalStorage](../../../quick-start/arkts-localstorage.md)中所有的属性。删除所有属性的前提是已经没有任何订阅者。如果有订阅者,clear不会生效并返回false。如果没有订阅者则删除成功并返回true。 1402 1403订阅者的含义参考[delete](#delete9)。 1404 1405**卡片能力:** 从API version 9开始,该接口支持在ArkTS卡片中使用。 1406 1407**原子化服务API:** 从API version 11开始,该接口支持在原子化服务中使用。 1408 1409**系统能力:** SystemCapability.ArkUI.ArkUI.Full 1410 1411**返回值:** 1412 1413 1414| 类型 | 说明 | 1415| ------- | ------------------------------------------------------------ | 1416| boolean | 如果LocalStorage中的属性已经没有任何订阅者,则删除成功,并返回true。否则返回false。 | 1417 1418 1419**示例:** 1420```ts 1421let para: Record<string, number> = { 'PropA': 47 }; 1422let storage: LocalStorage = new LocalStorage(para); 1423let res: boolean = storage.clear(); // true, there are no subscribers 1424``` 1425 1426 1427### GetShared<sup>(deprecated)</sup> 1428 1429static GetShared(): LocalStorage 1430 1431获取当前stage共享的[LocalStorage](../../../quick-start/arkts-localstorage.md)实例。 1432 1433> **说明:** 1434> 1435> 从API version 10开始废弃,推荐使用[getShared10+](#getshared10)。 1436 1437**卡片能力:** 从API version 9开始,该接口支持在ArkTS卡片中使用。 1438 1439**系统能力:** SystemCapability.ArkUI.ArkUI.Full 1440 1441**模型约束:**此接口仅可在Stage模型下使用。 1442 1443**返回值:** 1444 1445| 类型 | 说明 | 1446| ------------------------------ | ----------------- | 1447| [LocalStorage](#localstorage9) | 返回LocalStorage实例。 | 1448 1449**示例:** 1450```ts 1451let storage: LocalStorage = LocalStorage.GetShared(); 1452``` 1453 1454## AbstractProperty 1455 1456**原子化服务API:** 从API version 12开始,该接口支持在原子化服务中使用。 1457 1458**系统能力:** SystemCapability.ArkUI.ArkUI.Full 1459 1460### get<sup>12+</sup> 1461 1462get(): T 1463 1464读取[AppStorage](../../../quick-start/arkts-appstorage.md)/[LocalStorage](../../../quick-start/arkts-localstorage.md)中所引用属性的数据。 1465 1466**原子化服务API:** 从API version 12开始,该接口支持在原子化服务中使用。 1467 1468**系统能力:** SystemCapability.ArkUI.ArkUI.Full 1469 1470**返回值:** 1471 1472| 类型 | 说明 | 1473| ---- | ------------------------------------------- | 1474| T | AppStorage/LocalStorage中所引用属性的数据。 | 1475 1476**示例:** 1477 1478```ts 1479AppStorage.setOrCreate('PropA', 47); 1480let ref1: AbstractProperty<number> | undefined = AppStorage.ref('PropA'); 1481ref1?.get(); // ref1.get()=47 1482``` 1483 1484 1485### set<sup>12+</sup> 1486 1487set(newValue: T): void 1488 1489更新[AppStorage](../../../quick-start/arkts-appstorage.md)/[LocalStorage](../../../quick-start/arkts-localstorage.md)中所引用属性的数据,newValue必须是T类型,可以为null或undefined。 1490 1491> **说明:**<br/> 1492> 1493> 从API version 12开始,AppStorage/LocalStorage支持Map、Set、Date类型,支持null、undefined以及联合类型。 1494 1495**原子化服务API:** 从API version 12开始,该接口支持在原子化服务中使用。 1496 1497**系统能力:** SystemCapability.ArkUI.ArkUI.Full 1498 1499 1500**参数:** 1501 1502 1503| 参数名 | 类型 | 必填 | 说明 | 1504| -------- | ---- | ---- | ------------------------------------- | 1505| newValue | T | 是 | 要更新的数据,可以为null或undefined。 | 1506 1507 1508**示例:** 1509 1510```ts 1511AppStorage.setOrCreate('PropA', 47); 1512let ref1: AbstractProperty<number> | undefined = AppStorage.ref('PropA'); 1513ref1?.set(1); // ref1.get()=1 1514let a: Map<string, number> = new Map([['1', 0]]); 1515let ref2 = AppStorage.setAndRef('MapA', a); 1516ref2.set(a); 1517let b: Set<string> = new Set('1'); 1518let ref3 = AppStorage.setAndRef('SetB', b); 1519ref3.set(b); 1520let c: Date = new Date('2024'); 1521let ref4 = AppStorage.setAndRef('DateC', c); 1522ref4.set(c); 1523ref2.set(null); 1524ref3.set(undefined); 1525``` 1526 1527### info<sup>12+</sup> 1528 1529info(): string 1530 1531读取[AppStorage](../../../quick-start/arkts-appstorage.md)/[LocalStorage](../../../quick-start/arkts-localstorage.md)中所引用属性的属性名。 1532 1533**原子化服务API:** 从API version 12开始,该接口支持在原子化服务中使用。 1534 1535**系统能力:** SystemCapability.ArkUI.ArkUI.Full 1536 1537**返回值:** 1538 1539| 类型 | 说明 | 1540| ------ | --------------------------------------------- | 1541| string | AppStorage/LocalStorage中所引用属性的属性名。 | 1542 1543**示例:** 1544 1545```ts 1546AppStorage.setOrCreate('PropA', 47); 1547let ref1: AbstractProperty<number> | undefined = AppStorage.ref('PropA'); 1548ref1?.info(); // ref1.info()='PropA' 1549``` 1550 1551## SubscribedAbstractProperty 1552 1553**卡片能力:** 从API version 9开始,该接口支持在ArkTS卡片中使用。 1554 1555**原子化服务API:** 从API version 11开始,该接口支持在原子化服务中使用。 1556 1557**系统能力:** SystemCapability.ArkUI.ArkUI.Full 1558 1559### get<sup>9+</sup> 1560 1561abstract get(): T 1562 1563读取从[AppStorage](../../../quick-start/arkts-appstorage.md)/[LocalStorage](../../../quick-start/arkts-localstorage.md)同步属性的数据。 1564 1565**卡片能力:** 从API version 9开始,该接口支持在ArkTS卡片中使用。 1566 1567**原子化服务API:** 从API version 11开始,该接口支持在原子化服务中使用。 1568 1569**系统能力:** SystemCapability.ArkUI.ArkUI.Full 1570 1571**返回值:** 1572 1573| 类型 | 说明 | 1574| ---- | ------------------------------- | 1575| T | AppStorage/LocalStorage同步属性的数据。 | 1576 1577**示例:** 1578```ts 1579AppStorage.setOrCreate('PropA', 47); 1580let prop1: SubscribedAbstractProperty<number> = AppStorage.prop('PropA'); 1581prop1.get(); // prop1.get()=47 1582``` 1583 1584 1585### set<sup>9+</sup> 1586 1587abstract set(newValue: T): void 1588 1589设置[AppStorage](../../../quick-start/arkts-appstorage.md)/[LocalStorage](../../../quick-start/arkts-localstorage.md)同步属性的数据,newValue必须是T类型,从API version 12开始可以为null或undefined。 1590 1591> **说明:** 1592> 1593>从API version 12开始,AppStorage/LocalStorage支持Map、Set、Date类型,支持null、undefined以及联合类型。 1594 1595**卡片能力:** 从API version 9开始,该接口支持在ArkTS卡片中使用。 1596 1597**原子化服务API:** 从API version 11开始,该接口支持在原子化服务中使用。 1598 1599**系统能力:** SystemCapability.ArkUI.ArkUI.Full 1600 1601 1602**参数:** 1603 1604 1605| 参数名 | 类型 | 必填 | 说明 | 1606| -------- | ---- | ---- | --------------------------------------------------------- | 1607| newValue | T | 是 | 要设置的数据,从API version 12开始可以为null或undefined。 | 1608 1609 1610**示例:** 1611```ts 1612AppStorage.setOrCreate('PropA', 47); 1613let prop1: SubscribedAbstractProperty<number> = AppStorage.prop('PropA'); 1614prop1.set(1); // prop1.get()=1 1615// 从API12开始支持Map、Set、Date类型,支持null、undefined以及联合类型。 1616let a: Map<string, number> = new Map([['1', 0]]); 1617let prop2 = AppStorage.setAndProp('MapA', a); 1618prop2.set(a); 1619let b: Set<string> = new Set('1'); 1620let prop3 = AppStorage.setAndProp('SetB', b); 1621prop3.set(b); 1622let c: Date = new Date('2024'); 1623let prop4 = AppStorage.setAndProp('DateC', c); 1624prop4.set(c); 1625prop2.set(null); 1626prop3.set(undefined); 1627``` 1628 1629### aboutToBeDeleted<sup>10+</sup> 1630 1631abstract aboutToBeDeleted(): void 1632 1633取消[SubscribedAbstractProperty](#subscribedabstractproperty)实例对[AppStorage](../../../quick-start/arkts-appstorage.md)/[LocalStorage](../../../quick-start/arkts-localstorage.md)的单/双向同步关系,并无效化SubscribedAbstractProperty实例,即当调用aboutToBeDelted方法之后不能再使用SubscribedAbstractProperty实例调用[set](#set9-1)或[get](#get9-1)方法。 1634 1635**原子化服务API:** 从API version 11开始,该接口支持在原子化服务中使用。 1636 1637**系统能力:** SystemCapability.ArkUI.ArkUI.Full 1638 1639**示例:** 1640```ts 1641AppStorage.setOrCreate('PropA', 47); 1642let link = AppStorage.setAndLink('PropB', 49); // PropA -> 47, PropB -> 49 1643link.aboutToBeDeleted(); 1644``` 1645 1646### info 1647 1648info(): string; 1649 1650返回属性名称。 1651 1652**原子化服务API:** 从API version 11开始,该接口支持在原子化服务中使用。 1653 1654**系统能力:** SystemCapability.ArkUI.ArkUI.Full 1655 1656**返回值:** 1657 1658|类型 |说明 | 1659|---------|-------------| 1660|string |属性名称。 | 1661 1662 1663## PersistentStorage 1664 1665**原子化服务API:** 从API version 11开始,该接口支持在原子化服务中使用。 1666 1667**系统能力:** SystemCapability.ArkUI.ArkUI.Full 1668 1669PersistentStorage具体UI使用说明,详见[PersistentStorage(持久化存储UI状态)](../../../quick-start/arkts-persiststorage.md) 1670 1671> **说明:**<br/> 1672> 从API version 12开始,PersistentStorage支持null、undefined。 1673 1674### PersistPropsOptions 1675 1676**原子化服务API:** 从API version 11开始,该接口支持在原子化服务中使用。 1677 1678**系统能力:** SystemCapability.ArkUI.ArkUI.Full 1679 1680**参数:** 1681 1682| 参数名 | 类型 | 必填 | 说明 | 1683| ------------ | ------------------------------------- | ---- | ------------------------------------------------------------ | 1684| key | string | 是 | 属性名。 | 1685| defaultValue | number \| string \| boolean \| Object | 是 | 在PersistentStorage和AppStorage未查询到时,则使用默认值初始化它。从API version 12开始,defaultValue允许为null或undefined。 | 1686 1687 1688### persistProp<sup>10+</sup> 1689 1690static persistProp<T>(key: string, defaultValue: T): void 1691 1692将[AppStorage](../../../quick-start/arkts-appstorage.md)中key对应的属性持久化到文件中。该接口的调用通常在访问AppStorage之前。 1693 1694确定属性的类型和值的顺序如下: 1695 16961. 如果[PersistentStorage](../../../quick-start/arkts-persiststorage.md)文件中存在key对应的属性,在AppStorage中创建对应的propName,并用在PersistentStorage中找到的key的属性初始化。 1697 16982. 如果PersistentStorage文件中没有查询到key对应的属性,则在AppStorage中查找key对应的属性。如果找到key对应的属性,则将该属性持久化。 1699 17003. 如果AppStorage中也没查找到key对应的属性,则在AppStorage中创建key对应的属性。用defaultValue初始化其值,并将该属性持久化。 1701 1702根据上述的初始化流程,如果AppStorage中有该属性,则会使用其值,覆盖掉PersistentStorage文件中的值。由于AppStorage是内存内数据,该行为会导致数据丧失持久化能力。 1703 1704**原子化服务API:** 从API version 11开始,该接口支持在原子化服务中使用。 1705 1706**系统能力:** SystemCapability.ArkUI.ArkUI.Full 1707 1708**参数:** 1709 1710| 参数名 | 类型 | 必填 | 说明 | 1711| ------------ | ------ | ---- | ------------------------------------------------------------ | 1712| key | string | 是 | 属性名。 | 1713| defaultValue | T | 是 | 在PersistentStorage和AppStorage中未查询到时,则使用默认值进行初始化。从API version 12开始允许为null或undefined。 | 1714 1715 1716**示例:** 1717 1718 1719persistProp具体使用,见[从AppStorage中访问PersistentStorage初始化的属性](../../../quick-start/arkts-persiststorage.md#从appstorage中访问persistentstorage初始化的属性) 1720 1721 1722### deleteProp<sup>10+</sup> 1723 1724static deleteProp(key: string): void 1725 1726[persistProp](#persistprop10)的逆向操作。将key对应的属性从PersistentStorage中删除,后续[AppStorage](../../../quick-start/arkts-appstorage.md)的操作,对[PersistentStorage](../../../quick-start/arkts-persiststorage.md)不会再有影响。该操作会将对应的key从持久化文件中删除,如果希望再次持久化,可以再次调用[persistProp](#persistprop10)接口。 1727 1728**原子化服务API:** 从API version 11开始,该接口支持在原子化服务中使用。 1729 1730**系统能力:** SystemCapability.ArkUI.ArkUI.Full 1731 1732**参数:** 1733 1734| 参数名 | 类型 | 必填 | 说明 | 1735| ---- | ------ | ---- | ----------------------- | 1736| key | string | 是 | PersistentStorage中的属性名。 | 1737 1738**示例:** 1739```ts 1740PersistentStorage.deleteProp('highScore'); 1741``` 1742 1743 1744### persistProps<sup>10+</sup> 1745 1746static persistProps(props: PersistPropsOptions[]): void 1747 1748行为和[persistProp](#persistprop10)类似,不同在于可以一次性持久化多个数据,适合在应用启动的时候初始化。 1749 1750**原子化服务API:** 从API version 11开始,该接口支持在原子化服务中使用。 1751 1752**系统能力:** SystemCapability.ArkUI.ArkUI.Full 1753 1754**参数:** 1755 1756| 参数名 | 类型 | 必填 | 说明 | 1757| ---------- | ---------------------------------------- | ---- | ---------------------------------------- | 1758| props | [PersistPropsOptions](#persistpropsoptions)[] | 是 | 持久化数组。 | 1759 1760**示例:** 1761```ts 1762PersistentStorage.persistProps([{ key: 'highScore', defaultValue: '0' }, { key: 'wightScore', defaultValue: '1' }]); 1763``` 1764 1765 1766### keys<sup>10+</sup> 1767 1768static keys(): Array<string> 1769 1770返回所有持久化属性的属性名的数组。 1771 1772**原子化服务API:** 从API version 11开始,该接口支持在原子化服务中使用。 1773 1774**系统能力:** SystemCapability.ArkUI.ArkUI.Full 1775 1776**返回值:** 1777 1778| 类型 | 说明 | 1779| ------------------- | ---------------------------------- | 1780| Array<string> | 返回所有持久化属性的属性名的数组。 | 1781 1782**示例:** 1783```ts 1784let keys: Array<string> = PersistentStorage.keys(); 1785``` 1786 1787 1788### PersistProp<sup>(deprecated)</sup> 1789 1790static PersistProp<T>(key: string, defaultValue: T): void 1791 1792将[AppStorage](../../../quick-start/arkts-appstorage.md)中key对应的属性持久化到文件中。该接口的调用通常在访问AppStorage之前。 1793 1794确定属性的类型和值的顺序如下: 1795 17961. 如果[PersistentStorage](../../../quick-start/arkts-persiststorage.md)文件中存在key对应的属性,在AppStorage中创建对应的propName,并用在PersistentStorage中找到的key的属性初始化。 1797 17982. 如果PersistentStorage文件中没有查询到key对应的属性,则在AppStorage中查找key对应的属性。如果找到key对应的属性,则将该属性持久化。 1799 18003. 如果AppStorage也没查找到key对应的属性,则在AppStorage中创建key对应的属性。用defaultValue初始化其值,并将该属性持久化。 1801 1802根据上述的初始化流程,如果AppStorage中有该属性,则会使用其值,覆盖掉PersistentStorage文件中的值。由于AppStorage是内存内数据,该行为会导致数据丧失持久化能力。 1803 1804 1805> **说明:**<br/> 1806> 从API version 10开始废弃,推荐使用[persistProp10+](#persistprop10)替代。 1807 1808**系统能力:** SystemCapability.ArkUI.ArkUI.Full 1809 1810**参数:** 1811 1812| 参数名 | 类型 | 必填 | 说明 | 1813| ------------ | ------ | ---- | ------------------------------------------------------------ | 1814| key | string | 是 | 属性名。 | 1815| defaultValue | T | 是 | 在PersistentStorage和AppStorage中未查询到时,则使用默认值进行初始化。不允许为null或undefined。 | 1816 1817 1818**示例:** 1819 1820 1821```ts 1822PersistentStorage.PersistProp('highScore', '0'); 1823``` 1824 1825 1826### DeleteProp<sup>(deprecated)</sup> 1827 1828static DeleteProp(key: string): void 1829 1830[PersistProp](#persistpropdeprecated)的逆向操作。将key对应的属性从[PersistentStorage](../../../quick-start/arkts-persiststorage.md)中删除,后续[AppStorage](../../../quick-start/arkts-appstorage.md)的操作,对PersistentStorage不会再有影响。 1831 1832 1833> **说明:**<br/> 1834> 从API version 10开始废弃,推荐使用[deleteProp10+](#deleteprop10)替代。 1835 1836**系统能力:** SystemCapability.ArkUI.ArkUI.Full 1837 1838**参数:** 1839 1840| 参数名 | 类型 | 必填 | 说明 | 1841| ---- | ------ | ---- | ----------------------- | 1842| key | string | 是 | PersistentStorage中的属性名。 | 1843 1844**示例:** 1845```ts 1846PersistentStorage.DeleteProp('highScore'); 1847``` 1848 1849 1850### PersistProps<sup>(deprecated)</sup> 1851 1852static PersistProps(properties: {key: string, defaultValue: any;}[]): void 1853 1854行为和[PersistProp](#persistpropdeprecated)类似,不同在于可以一次性持久化多个数据,适合在应用启动的时候初始化。 1855 1856> **说明:**<br/> 1857> 从API version 10开始废弃,推荐使用[persistProps10+](#persistprops10)替代。 1858 1859**系统能力:** SystemCapability.ArkUI.ArkUI.Full 1860 1861**参数:** 1862 1863| 参数名 | 类型 | 必填 | 说明 | 1864| ---------- | ---------------------------------- | ---- | ------------------------------------------------------------ | 1865| properties | {key: string, defaultValue: any}[] | 是 | 持久化数组,启动key为属性名,defaultValue为默认值。规则同PersistProp。 | 1866 1867**示例:** 1868 1869```ts 1870PersistentStorage.PersistProps([{ key: 'highScore', defaultValue: '0' }, { key: 'wightScore', defaultValue: '1' }]); 1871``` 1872 1873 1874### Keys<sup>(deprecated)</sup> 1875 1876static Keys(): Array<string> 1877 1878返回所有持久化属性的属性名的数组。 1879 1880> **说明:**<br/> 1881> 从API version 10开始废弃,推荐使用[keys10+](#keys10-1)替代。 1882 1883**系统能力:** SystemCapability.ArkUI.ArkUI.Full 1884 1885**返回值:** 1886 1887| 类型 | 说明 | 1888| ------------------- | ---------------------------------- | 1889| Array<string> | 返回所有持久化属性的属性名的数组。 | 1890 1891**示例:** 1892```ts 1893let keys: Array<string> = PersistentStorage.Keys(); 1894``` 1895 1896 1897## Environment 1898 1899**原子化服务API:** 从API version 11开始,该接口支持在原子化服务中使用。 1900 1901**系统能力:** SystemCapability.ArkUI.ArkUI.Full 1902 1903Environment具体使用说明,详见[Environment(设备环境查询)](../../../quick-start/arkts-environment.md) 1904 1905### EnvPropsOptions 1906 1907**原子化服务API:** 从API version 11开始,该接口支持在原子化服务中使用。 1908 1909**系统能力:** SystemCapability.ArkUI.ArkUI.Full 1910 1911**参数:** 1912 1913| 参数名 | 类型 | 必填 | 说明 | 1914| ------------ | --------------------------- | ---- | ------------------------------------------------------------ | 1915| key | string | 是 | 环境变量名称,支持的范围详见[内置环境变量说明](#内置环境变量说明)。 | 1916| defaultValue | number \| string \| boolean | 是 | 查询不到环境变量key,则使用defaultValue作为默认值存入AppStorage中。 | 1917 1918 1919### envProp<sup>10+</sup> 1920 1921static envProp<S>(key: string, value: S): boolean 1922 1923将[Environment](../../../quick-start/arkts-environment.md)的内置环境变量key存入[AppStorage](../../../quick-start/arkts-appstorage.md)中。如果系统中未查询到Environment环境变量key的值,则使用默认值value,存入成功,返回true。如果AppStorage中已经有对应的key,则返回false。 1924 1925所以建议在程序启动的时候调用该接口。 1926 1927在没有调用envProp的情况下,就使用AppStorage读取环境变量是错误的。 1928 1929**原子化服务API:** 从API version 11开始,该接口支持在原子化服务中使用。 1930 1931**系统能力:** SystemCapability.ArkUI.ArkUI.Full 1932 1933**参数:** 1934 1935| 参数名 | 类型 | 必填 | 说明 | 1936| ------ | ------ | ---- | ------------------------------------------------------------ | 1937| key | string | 是 | 环境变量名称,支持的范围详见[内置环境变量说明](#内置环境变量说明)。 | 1938| value | S | 是 | 查询不到环境变量key时,则使用value作为默认值存入AppStorage中。 | 1939 1940**返回值:** 1941 1942| 类型 | 说明 | 1943| ------- | ------------------------------------------------------------ | 1944| boolean | 如果key对应的属性在AppStorage中存在,则返回false。不存在则在AppStorage中用value作为默认值创建key对应的属性,返回true。 | 1945 1946**示例:** 1947 1948 1949envProp具体使用,见[从UI中访问Environment参数](../../../quick-start/arkts-environment.md#从ui中访问environment参数) 1950 1951 1952### envProps<sup>10+</sup> 1953 1954static envProps(props: EnvPropsOptions[]): void 1955 1956和[envProp](#envprop10)类似,不同点在于参数为数组,可以一次性初始化多个数据。建议在应用启动时调用,将系统环境变量批量存入[AppStorage](../../../quick-start/arkts-appstorage.md)中。 1957 1958**原子化服务API:** 从API version 11开始,该接口支持在原子化服务中使用。 1959 1960**系统能力:** SystemCapability.ArkUI.ArkUI.Full 1961 1962**参数:** 1963 1964| 参数名 | 类型 | 必填 | 说明 | 1965| ------ | --------------------------------------------- | ---- | ------------------------------------ | 1966| props | [EnvPropsOptions](#envpropsoptions)[] | 是 | 系统环境变量和默认值的键值对的数组。 | 1967 1968**示例:** 1969```ts 1970Environment.envProps([{ key: 'accessibilityEnabled', defaultValue: 'default' }, { 1971 key: 'languageCode', 1972 defaultValue: 'en' 1973}, { key: 'prop', defaultValue: 'hhhh' }]); 1974``` 1975 1976 1977### keys<sup>10+</sup> 1978 1979static keys(): Array<string> 1980 1981返回环境变量的属性key的数组。 1982 1983**原子化服务API:** 从API version 11开始,该接口支持在原子化服务中使用。 1984 1985**系统能力:** SystemCapability.ArkUI.ArkUI.Full 1986 1987**返回值:** 1988 1989| 类型 | 说明 | 1990| ------------------- | ----------- | 1991| Array<string> | 返回关联的系统项数组。 | 1992 1993**示例:** 1994```ts 1995Environment.envProps([{ key: 'accessibilityEnabled', defaultValue: 'default' }, { 1996 key: 'languageCode', 1997 defaultValue: 'en' 1998}, { key: 'prop', defaultValue: 'hhhh' }]); 1999 2000let keys: Array<string> = Environment.keys(); // accessibilityEnabled, languageCode, prop 2001``` 2002 2003 2004### EnvProp<sup>(deprecated)</sup> 2005 2006static EnvProp<S>(key: string, value: S): boolean 2007 2008将[Environment](../../../quick-start/arkts-environment.md)的内置环境变量key存入[AppStorage](../../../quick-start/arkts-appstorage.md)中。如果系统中未查询到Environment环境变量key的值,则使用默认值value,存入成功,返回true。如果AppStorage中已经有对应的key,则返回false。 2009 2010所以建议在程序启动的时候调用该接口。 2011 2012在没有调用EnvProp的情况下,就使用AppStorage读取环境变量是错误的。 2013 2014> **说明:**<br/> 2015> 从API version 10开始废弃,推荐使用[envProp10+](#envprop10)替代。 2016 2017**系统能力:** SystemCapability.ArkUI.ArkUI.Full 2018 2019**参数:** 2020 2021| 参数名 | 类型 | 必填 | 说明 | 2022| ------ | ------ | ---- | ------------------------------------------------------------ | 2023| key | string | 是 | 环境变量名称,支持的范围详见[内置环境变量说明](#内置环境变量说明)。 | 2024| value | S | 是 | 查询不到环境变量key,则使用value作为默认值存入AppStorage中。 | 2025 2026**返回值:** 2027 2028| 类型 | 说明 | 2029| ------- | ------------------------------------------------------------ | 2030| boolean | 如果key对应的属性在AppStorage中存在,则返回false。不存在则在AppStorage中用value作为默认值创建key对应的属性,返回true。 | 2031 2032**示例:** 2033 2034 2035```ts 2036Environment.EnvProp('accessibilityEnabled', 'default'); 2037``` 2038 2039 2040### EnvProps<sup>(deprecated)</sup> 2041 2042static EnvProps(props: {key: string; defaultValue: any;}[]): void 2043 2044和[EnvProp](#envpropdeprecated)类似,不同点在于参数为数组,可以一次性初始化多个数据。建议在应用启动时调用,将系统环境变量批量存入[AppStorage](../../../quick-start/arkts-appstorage.md)中。 2045 2046> **说明:**<br/> 2047> 从API version 10开始废弃,推荐使用[envProps10+](#envprops10)替代。 2048 2049**系统能力:** SystemCapability.ArkUI.ArkUI.Full 2050 2051**参数:** 2052 2053| 参数名 | 类型 | 必填 | 说明 | 2054| ------ | ------------------------------------------------- | ---- | ------------------------------------ | 2055| props | {key: string, defaultValue: any}[] | 是 | 系统环境变量和默认值的键值对的数组。 | 2056 2057**示例:** 2058```ts 2059Environment.EnvProps([{ key: 'accessibilityEnabled', defaultValue: 'default' }, { 2060 key: 'languageCode', 2061 defaultValue: 'en' 2062}, { key: 'prop', defaultValue: 'hhhh' }]); 2063``` 2064 2065 2066### Keys<sup>(deprecated)</sup> 2067 2068static Keys(): Array<string> 2069 2070返回环境变量的属性key的数组。 2071 2072> **说明:**<br/> 2073> 从API version 10开始废弃,推荐使用[keys10+](#keys10-2)替代。 2074 2075**系统能力:** SystemCapability.ArkUI.ArkUI.Full 2076 2077**返回值:** 2078 2079| 类型 | 说明 | 2080| ------------------- | ----------- | 2081| Array<string> | 返回关联的系统项数组。 | 2082 2083**示例:** 2084 2085```ts 2086Environment.EnvProps([{ key: 'accessibilityEnabled', defaultValue: 'default' }, { 2087 key: 'languageCode', 2088 defaultValue: 'en' 2089}, { key: 'prop', defaultValue: 'hhhh' }]); 2090 2091let keys: Array<string> = Environment.Keys(); // accessibilityEnabled, languageCode, prop 2092``` 2093 2094 2095## 内置环境变量说明 2096 2097| key | 类型 | 说明 | 2098| -------------------- | --------------- | ------------------------------------------------------------ | 2099| accessibilityEnabled | string | 无障碍屏幕朗读是否启用。当无法获取环境变量中的accessibilityEnabled的值时,将通过envProp、envProps等接口传入的开发者指定的默认值添加到AppStorage中。 | 2100| colorMode | ColorMode | 深浅色模式,可选值为:<br/>- ColorMode.LIGHT:浅色模式;<br/>- ColorMode.DARK:深色模式。 | 2101| fontScale | number | 字体大小比例。 | 2102| fontWeightScale | number | 字重比例。 | 2103| layoutDirection | LayoutDirection | 布局方向类型,可选值为:<br/>- LayoutDirection.LTR:从左到右;<br/>- LayoutDirection.RTL:从右到左。<br/>- Auto:跟随系统。 | 2104| languageCode | string | 当前系统语言,小写字母,例如zh。 | 2105