1# @ohos.data.preferences (用户首选项) 2 3用户首选项为应用提供Key-Value键值型的数据处理能力，支持应用持久化轻量级数据，并对其修改和查询。 4 5数据存储形式为键值对，键的类型为字符串型，值的存储数据类型包括数字型、字符型、布尔型以及这3种类型的数组类型。 6 7用户首选项的持久化文件存储在[preferencesDir](../../../application-dev/application-models/application-context-stage.md#获取应用文件路径)路径下，创建preferences对象前，需要保证preferencesDir路径可读写。持久化文件存储路径中的[加密等级](../../../application-dev/reference/apis-ability-kit/js-apis-app-ability-contextConstant.md#areamode)会影响文件的可读写状态，路径访问限制详见[应用文件目录与应用文件路径](../../../application-dev/file-management/app-sandbox-directory.md#应用文件目录与应用文件路径)。 8 9> **说明：** 10> 11> 本模块首批接口从API version 9开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 12> 13> 首选项无法保证进程并发安全，会有文件损坏和数据丢失的风险，不支持在多进程场景下使用。 14 15## 导入模块 16 17```ts 18import { preferences } from '@kit.ArkData'; 19``` 20 21## 常量 22 23**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 24 25**系统能力：** SystemCapability.DistributedDataManager.Preferences.Core 26 27| 名称 | 参数类型 | 可读 | 可写 | 说明 | 28| ---------------- | -------- | ---- | ---- | --------------------------------------- | 29| MAX_KEY_LENGTH | number | 是 | 否 | Key的最大长度限制为1024个字节。 | 30| MAX_VALUE_LENGTH | number | 是 | 否 | Value的最大长度限制为16MB。 | 31 32 33## preferences.getPreferences 34 35getPreferences(context: Context, name: string, callback: AsyncCallback<Preferences>): void 36 37获取Preferences实例，使用callback异步回调。 38 39**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 40 41**系统能力：** SystemCapability.DistributedDataManager.Preferences.Core 42 43**参数：** 44 45| 参数名 | 类型 | 必填 | 说明 | 46| -------- | ------------------------------------------------ | ---- | ------------------------------------------------------------ | 47| context | Context | 是 | 应用上下文。<br>FA模型的应用Context定义见[Context](../apis-ability-kit/js-apis-inner-app-context.md)。<br>Stage模型的应用Context定义见[Context](../apis-ability-kit/js-apis-inner-application-uiAbilityContext.md)。 | 48| name | string | 是 | Preferences实例的名称。 | 49| callback | AsyncCallback<[Preferences](#preferences)> | 是 | 回调函数。当获取Preferences实例成功，err为undefined，返回Preferences实例；否则err为错误对象。 | 50 51**错误码：** 52 53以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[用户首选项错误码](errorcode-preferences.md)。 54 55| 错误码ID | 错误信息 | 56| -------- | ------------------------------ | 57| 401 | Parameter error. Possible causes:<br>1. Mandatory parameters are left unspecified;<br>2. Incorrect parameter types;<br>3. Parameter verification failed. | 58| 15500000 | Inner error. | 59 60**示例：** 61 62FA模型示例： 63 64<!--code_no_check_fa--> 65```ts 66import { featureAbility } from '@kit.AbilityKit'; 67import { BusinessError } from '@kit.BasicServicesKit'; 68 69let context = featureAbility.getContext(); 70let dataPreferences: preferences.Preferences | null = null; 71 72preferences.getPreferences(context, 'myStore', (err: BusinessError, val: preferences.Preferences) => { 73 if (err) { 74 console.error("Failed to get preferences. code =" + err.code + ", message =" + err.message); 75 return; 76 } 77 dataPreferences = val; 78 console.info("Succeeded in getting preferences."); 79}) 80``` 81 82Stage模型示例： 83 84```ts 85import { UIAbility } from '@kit.AbilityKit'; 86import { BusinessError } from '@kit.BasicServicesKit'; 87import { window } from '@kit.ArkUI'; 88 89let dataPreferences: preferences.Preferences | null = null; 90 91class EntryAbility extends UIAbility { 92 onWindowStageCreate(windowStage: window.WindowStage) { 93 preferences.getPreferences(this.context, 'myStore', (err: BusinessError, val: preferences.Preferences) => { 94 if (err) { 95 console.error("Failed to get preferences. code =" + err.code + ", message =" + err.message); 96 return; 97 } 98 dataPreferences = val; 99 console.info("Succeeded in getting preferences."); 100 }) 101 } 102} 103``` 104 105## preferences.getPreferences 106 107getPreferences(context: Context, name: string): Promise<Preferences> 108 109获取Preferences实例，使用Promise异步回调。 110 111**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 112 113**系统能力：** SystemCapability.DistributedDataManager.Preferences.Core 114 115**参数：** 116 117| 参数名 | 类型 | 必填 | 说明 | 118| ------- | ------------------------------------- | ---- | ----------------------- | 119| context | Context | 是 | 应用上下文。<br>FA模型的应用Context定义见[Context](../apis-ability-kit/js-apis-inner-app-context.md)。<br>Stage模型的应用Context定义见[Context](../apis-ability-kit/js-apis-inner-application-uiAbilityContext.md)。 | 120| name | string | 是 | Preferences实例的名称。 | 121 122**返回值：** 123 124| 类型 | 说明 | 125| ------------------------------------------ | ---------------------------------- | 126| Promise<[Preferences](#preferences)> | Promise对象，返回Preferences实例。 | 127 128**错误码：** 129 130以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[用户首选项错误码](errorcode-preferences.md)。 131 132| 错误码ID | 错误信息 | 133| -------- | ------------------------------ | 134| 401 | Parameter error. Possible causes:<br>1. Mandatory parameters are left unspecified;<br>2. Incorrect parameter types;<br>3. Parameter verification failed. | 135| 15500000 | Inner error. | 136 137**示例：** 138 139FA模型示例： 140 141<!--code_no_check_fa--> 142```ts 143// 获取context 144import { featureAbility } from '@kit.AbilityKit'; 145import { BusinessError } from '@kit.BasicServicesKit'; 146 147let context = featureAbility.getContext(); 148 149let dataPreferences: preferences.Preferences | null = null; 150let promise = preferences.getPreferences(context, 'myStore'); 151promise.then((object: preferences.Preferences) => { 152 dataPreferences = object; 153 console.info("Succeeded in getting preferences."); 154}).catch((err: BusinessError) => { 155 console.error("Failed to get preferences. code =" + err.code + ", message =" + err.message); 156}) 157``` 158 159Stage模型示例： 160 161```ts 162import { UIAbility } from '@kit.AbilityKit'; 163import { BusinessError } from '@kit.BasicServicesKit'; 164import { window } from '@kit.ArkUI'; 165 166let dataPreferences: preferences.Preferences | null = null; 167 168class EntryAbility extends UIAbility { 169 onWindowStageCreate(windowStage: window.WindowStage) { 170 let promise = preferences.getPreferences(this.context, 'myStore'); 171 promise.then((object: preferences.Preferences) => { 172 dataPreferences = object; 173 console.info("Succeeded in getting preferences."); 174 }).catch((err: BusinessError) => { 175 console.error("Failed to get preferences. code =" + err.code + ", message =" + err.message); 176 }) 177 } 178} 179``` 180 181## preferences.getPreferences<sup>10+</sup> 182 183getPreferences(context: Context, options: Options, callback: AsyncCallback<Preferences>): void 184 185获取Preferences实例，使用callback异步回调。 186 187**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 188 189**系统能力：** SystemCapability.DistributedDataManager.Preferences.Core 190 191**参数：** 192 193| 参数名 | 类型 | 必填 | 说明 | 194| -------- | --------------------------------------------- | ---- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | 195| context | Context | 是 | 应用上下文。<br>FA模型的应用Context定义见[Context](../apis-ability-kit/js-apis-inner-app-context.md)。<br>Stage模型的应用Context定义见[Context](../apis-ability-kit/js-apis-inner-application-uiAbilityContext.md)。 | 196| options | [Options](#options10) | 是 | 与Preferences实例相关的配置选项。 | 197| callback | AsyncCallback<[Preferences](#preferences)> | 是 | 回调函数。当获取Preferences实例成功，err为undefined，返回Preferences实例；否则err为错误对象。 | 198 199**错误码：** 200 201以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[用户首选项错误码](errorcode-preferences.md)。 202 203| 错误码ID | 错误信息 | 204| -------- | ------------------------------ | 205| 401 | Parameter error. Possible causes:<br>1. Mandatory parameters are left unspecified;<br>2. Incorrect parameter types;<br>3. Parameter verification failed. | 206| 801 | Capability not supported. | 207| 15500000 | Inner error. | 208| 15501001 | The operations is supported in stage mode only. | 209| 15501002 | Invalid dataGroupId. | 210 211**示例：** 212 213FA模型示例： 214 215<!--code_no_check_fa--> 216```ts 217// 获取context 218import { featureAbility } from '@kit.AbilityKit'; 219import { BusinessError } from '@kit.BasicServicesKit'; 220 221let context = featureAbility.getContext(); 222let dataPreferences: preferences.Preferences | null = null; 223 224let options: preferences.Options = { name: 'myStore' }; 225preferences.getPreferences(context, options, (err: BusinessError, val: preferences.Preferences) => { 226 if (err) { 227 console.error("Failed to get preferences. code =" + err.code + ", message =" + err.message); 228 return; 229 } 230 dataPreferences = val; 231 console.info("Succeeded in getting preferences."); 232}) 233``` 234 235 236Stage模型示例： 237 238```ts 239import { UIAbility } from '@kit.AbilityKit'; 240import { BusinessError } from '@kit.BasicServicesKit'; 241import { window } from '@kit.ArkUI'; 242 243let dataPreferences: preferences.Preferences | null = null; 244 245class EntryAbility extends UIAbility { 246 onWindowStageCreate(windowStage: window.WindowStage) { 247 let options: preferences.Options = { name: 'myStore' }; 248 preferences.getPreferences(this.context, options, (err: BusinessError, val: preferences.Preferences) => { 249 if (err) { 250 console.error("Failed to get preferences. code =" + err.code + ", message =" + err.message); 251 return; 252 } 253 dataPreferences = val; 254 console.info("Succeeded in getting preferences."); 255 }) 256 } 257} 258``` 259 260## preferences.getPreferences<sup>10+</sup> 261 262getPreferences(context: Context, options: Options): Promise<Preferences> 263 264获取Preferences实例，使用Promise异步回调。 265 266**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 267 268**系统能力：** SystemCapability.DistributedDataManager.Preferences.Core 269 270**参数：** 271 272| 参数名 | 类型 | 必填 | 说明 | 273| ------- | ---------------- | ---- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | 274| context | Context | 是 | 应用上下文。<br>FA模型的应用Context定义见[Context](../apis-ability-kit/js-apis-inner-app-context.md)。<br>Stage模型的应用Context定义见[Context](../apis-ability-kit/js-apis-inner-application-uiAbilityContext.md)。 | 275| options | [Options](#options10) | 是 | 与Preferences实例相关的配置选项。 | 276 277**返回值：** 278 279| 类型 | 说明 | 280| --------------------------------------- | ---------------------------------- | 281| Promise<[Preferences](#preferences)> | Promise对象，返回Preferences实例。 | 282 283**错误码：** 284 285以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[用户首选项错误码](errorcode-preferences.md)。 286 287| 错误码ID | 错误信息 | 288| -------- | ------------------------------ | 289| 401 | Parameter error. Possible causes:<br>1. Mandatory parameters are left unspecified;<br>2. Incorrect parameter types;<br>3. Parameter verification failed. | 290| 801 | Capability not supported. | 291| 15500000 | Inner error. | 292| 15501001 | The operations is supported in stage mode only. | 293| 15501002 | Invalid dataGroupId. | 294 295**示例：** 296 297FA模型示例： 298 299<!--code_no_check_fa--> 300```ts 301// 获取context 302import { featureAbility } from '@kit.AbilityKit'; 303import { BusinessError } from '@kit.BasicServicesKit'; 304 305let context = featureAbility.getContext(); 306 307let dataPreferences: preferences.Preferences | null = null; 308let options: preferences.Options = { name: 'myStore' }; 309let promise = preferences.getPreferences(context, options); 310promise.then((object: preferences.Preferences) => { 311 dataPreferences = object; 312 console.info("Succeeded in getting preferences."); 313}).catch((err: BusinessError) => { 314 console.error("Failed to get preferences. code =" + err.code + ", message =" + err.message); 315}) 316``` 317 318Stage模型示例： 319 320```ts 321import { UIAbility } from '@kit.AbilityKit'; 322import { BusinessError } from '@kit.BasicServicesKit'; 323import { window } from '@kit.ArkUI'; 324 325let dataPreferences: preferences.Preferences | null = null; 326 327class EntryAbility extends UIAbility { 328 onWindowStageCreate(windowStage: window.WindowStage) { 329 let options: preferences.Options = { name: 'myStore' }; 330 let promise = preferences.getPreferences(this.context, options); 331 promise.then((object: preferences.Preferences) => { 332 dataPreferences = object; 333 console.info("Succeeded in getting preferences."); 334 }).catch((err: BusinessError) => { 335 console.error("Failed to get preferences. code =" + err.code + ", message =" + err.message); 336 }) 337 } 338} 339``` 340 341## preferences.getPreferencesSync<sup>10+</sup> 342 343getPreferencesSync(context: Context, options: Options): Preferences 344 345获取Preferences实例，此为同步接口。 346 347**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 348 349**系统能力：** SystemCapability.DistributedDataManager.Preferences.Core 350 351**参数：** 352 353| 参数名 | 类型 | 必填 | 说明 | 354| ------- | --------------------- | ---- | ------------------------------------------------------------ | 355| context | Context | 是 | 应用上下文。<br>FA模型的应用Context定义见[Context](../apis-ability-kit/js-apis-inner-app-context.md)。<br>Stage模型的应用Context定义见[Context](../apis-ability-kit/js-apis-inner-application-uiAbilityContext.md)。 | 356| options | [Options](#options10) | 是 | 与Preferences实例相关的配置选项。 | 357 358**返回值：** 359 360| 类型 | 说明 | 361| --------------------------- | --------------------- | 362| [Preferences](#preferences) | 返回Preferences实例。 | 363 364**错误码：** 365 366以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[用户首选项错误码](errorcode-preferences.md)。 367 368| 错误码ID | 错误信息 | 369| -------- | ------------------------------ | 370| 401 | Parameter error. Possible causes:<br>1. Mandatory parameters are left unspecified;<br>2. Incorrect parameter types;<br>3. Parameter verification failed. | 371| 801 | Capability not supported. | 372| 15500000 | Inner error. | 373| 15501001 | The operations is supported in stage mode only. | 374| 15501002 | Invalid dataGroupId. | 375 376**示例：** 377 378FA模型示例： 379 380<!--code_no_check_fa--> 381```ts 382// 获取context 383import { featureAbility } from '@kit.AbilityKit'; 384 385let context = featureAbility.getContext(); 386let dataPreferences: preferences.Preferences | null = null; 387 388let options: preferences.Options = { name: 'myStore' }; 389dataPreferences = preferences.getPreferencesSync(context, options); 390``` 391 392Stage模型示例： 393 394```ts 395import { UIAbility } from '@kit.AbilityKit'; 396import { window } from '@kit.ArkUI'; 397 398let dataPreferences: preferences.Preferences | null = null; 399 400class EntryAbility extends UIAbility { 401 onWindowStageCreate(windowStage: window.WindowStage) { 402 let options: preferences.Options = { name: 'myStore' }; 403 dataPreferences = preferences.getPreferencesSync(this.context, options); 404 } 405} 406``` 407 408## preferences.deletePreferences 409 410deletePreferences(context: Context, name: string, callback: AsyncCallback<void>): void 411 412从缓存中移出指定的Preferences实例，若Preferences实例有对应的持久化文件，则同时删除其持久化文件。使用callback异步回调。 413 414调用该接口后，不建议再使用旧的Preferences实例进行数据操作，否则会出现数据一致性问题，应将Preferences实例置为null，系统将会统一回收。 415 416不支持该接口与preference其他接口并发调用。 417 418**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 419 420**系统能力：** SystemCapability.DistributedDataManager.Preferences.Core 421 422**参数：** 423 424| 参数名 | 类型 | 必填 | 说明 | 425| -------- | ------------------------------------- | ---- | ---------------------------------------------------- | 426| context | Context | 是 | 应用上下文。<br>FA模型的应用Context定义见[Context](../apis-ability-kit/js-apis-inner-app-context.md)。<br>Stage模型的应用Context定义见[Context](../apis-ability-kit/js-apis-inner-application-uiAbilityContext.md)。 | 427| name | string | 是 | Preferences实例的名称。 | 428| callback | AsyncCallback<void> | 是 | 回调函数。当移除成功，err为undefined，否则为错误对象。 | 429 430**错误码：** 431 432以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[用户首选项错误码](errorcode-preferences.md)。 433 434| 错误码ID | 错误信息 | 435| -------- | ------------------------------ | 436| 401 | Parameter error. Possible causes:<br>1. Mandatory parameters are left unspecified;<br>2. Incorrect parameter types;<br>3. Parameter verification failed. | 437| 15500000 | Inner error. | 438| 15500010 | Failed to delete the user preferences persistence file. | 439 440**示例：** 441 442FA模型示例： 443 444<!--code_no_check_fa--> 445```ts 446// 获取context 447import { featureAbility } from '@kit.AbilityKit'; 448import { BusinessError } from '@kit.BasicServicesKit'; 449 450let context = featureAbility.getContext(); 451 452preferences.deletePreferences(context, 'myStore', (err: BusinessError) => { 453 if (err) { 454 console.error("Failed to delete preferences. code =" + err.code + ", message =" + err.message); 455 return; 456 } 457 console.info("Succeeded in deleting preferences."); 458}) 459``` 460 461Stage模型示例： 462 463```ts 464import { UIAbility } from '@kit.AbilityKit'; 465import { BusinessError } from '@kit.BasicServicesKit'; 466import { window } from '@kit.ArkUI'; 467 468class EntryAbility extends UIAbility { 469 onWindowStageCreate(windowStage: window.WindowStage) { 470 preferences.deletePreferences(this.context, 'myStore', (err: BusinessError) => { 471 if (err) { 472 console.error("Failed to delete preferences. code =" + err.code + ", message =" + err.message); 473 return; 474 } 475 console.info("Succeeded in deleting preferences."); 476 }) 477 } 478} 479``` 480 481## preferences.deletePreferences 482 483deletePreferences(context: Context, name: string): Promise<void> 484 485从缓存中移出指定的Preferences实例，若Preferences实例有对应的持久化文件，则同时删除其持久化文件。使用Promise异步回调。 486 487调用该接口后，不建议再使用旧的Preferences实例进行数据操作，否则会出现数据一致性问题，应将Preferences实例置为null，系统将会统一回收。 488 489不支持该接口与preference其他接口并发调用。 490 491**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 492 493**系统能力：** SystemCapability.DistributedDataManager.Preferences.Core 494 495**参数：** 496 497| 参数名 | 类型 | 必填 | 说明 | 498| ------- | ------------------------------------- | ---- | ----------------------- | 499| context | Context | 是 | 应用上下文。<br>FA模型的应用Context定义见[Context](../apis-ability-kit/js-apis-inner-app-context.md)。<br>Stage模型的应用Context定义见[Context](../apis-ability-kit/js-apis-inner-application-uiAbilityContext.md)。 | 500| name | string | 是 | Preferences实例的名称。 | 501 502**返回值：** 503 504| 类型 | 说明 | 505| ------------------- | ------------------------- | 506| Promise<void> | 无返回结果的Promise对象。 | 507 508**错误码：** 509 510以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[用户首选项错误码](errorcode-preferences.md)。 511 512| 错误码ID | 错误信息 | 513| -------- | ------------------------------ | 514| 401 | Parameter error. Possible causes:<br>1. Mandatory parameters are left unspecified;<br>2. Incorrect parameter types;<br>3. Parameter verification failed. | 515| 15500000 | Inner error. | 516| 15500010 | Failed to delete the user preferences persistence file. | 517 518**示例：** 519 520FA模型示例： 521 522<!--code_no_check_fa--> 523```ts 524// 获取context 525import { featureAbility } from '@kit.AbilityKit'; 526import { BusinessError } from '@kit.BasicServicesKit'; 527 528let context = featureAbility.getContext(); 529 530let promise = preferences.deletePreferences(context, 'myStore'); 531promise.then(() => { 532 console.info("Succeeded in deleting preferences."); 533}).catch((err: BusinessError) => { 534 console.error("Failed to delete preferences. code =" + err.code + ", message =" + err.message); 535}) 536``` 537 538Stage模型示例： 539 540```ts 541import { UIAbility } from '@kit.AbilityKit'; 542import { BusinessError } from '@kit.BasicServicesKit'; 543import { window } from '@kit.ArkUI'; 544 545class EntryAbility extends UIAbility { 546 onWindowStageCreate(windowStage: window.WindowStage) { 547 let promise = preferences.deletePreferences(this.context, 'myStore'); 548 promise.then(() => { 549 console.info("Succeeded in deleting preferences."); 550 }).catch((err: BusinessError) => { 551 console.error("Failed to delete preferences. code =" + err.code + ", message =" + err.message); 552 }) 553 } 554} 555``` 556 557## preferences.deletePreferences<sup>10+</sup> 558 559deletePreferences(context: Context, options: Options, callback: AsyncCallback<void>): void 560 561从缓存中移出指定的Preferences实例，若Preferences实例有对应的持久化文件，则同时删除其持久化文件。使用callback异步回调。 562 563调用该接口后，不建议再使用旧的Preferences实例进行数据操作，否则会出现数据一致性问题，应将Preferences实例置为null，系统将会统一回收。 564 565不支持该接口与preference其他接口并发调用。 566 567**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 568 569**系统能力：** SystemCapability.DistributedDataManager.Preferences.Core 570 571**参数：** 572 573| 参数名 | 类型 | 必填 | 说明 | 574| -------- | ------------------------- | ---- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | 575| context | Context | 是 | 应用上下文。<br>FA模型的应用Context定义见[Context](../apis-ability-kit/js-apis-inner-app-context.md)。<br>Stage模型的应用Context定义见[Context](../apis-ability-kit/js-apis-inner-application-uiAbilityContext.md)。 | 576| options | [Options](#options10) | 是 | 与Preferences实例相关的配置选项。 | 577| callback | AsyncCallback<void> | 是 | 回调函数。当移除成功，err为undefined，否则为错误对象。 | 578 579**错误码：** 580 581以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[用户首选项错误码](errorcode-preferences.md)。 582 583| 错误码ID | 错误信息 | 584| -------- | ------------------------------ | 585| 401 | Parameter error. Possible causes:<br>1. Mandatory parameters are left unspecified;<br>2. Incorrect parameter types;<br>3. Parameter verification failed. | 586| 801 | Capability not supported. | 587| 15500000 | Inner error. | 588| 15500010 | Failed to delete the user preferences persistence file. | 589| 15501001 | The operations is supported in stage mode only. | 590| 15501002 | Invalid dataGroupId. | 591 592**示例：** 593 594FA模型示例： 595 596<!--code_no_check_fa--> 597```ts 598// 获取context 599import { featureAbility } from '@kit.AbilityKit'; 600import { BusinessError } from '@kit.BasicServicesKit'; 601 602let context = featureAbility.getContext(); 603 604let options: preferences.Options = { name: 'myStore' }; 605preferences.deletePreferences(context, options, (err: BusinessError) => { 606 if (err) { 607 console.error("Failed to delete preferences. code =" + err.code + ", message =" + err.message); 608 return; 609 } 610 console.info("Succeeded in deleting preferences."); 611}) 612``` 613 614Stage模型示例： 615 616```ts 617import { UIAbility } from '@kit.AbilityKit'; 618import { BusinessError } from '@kit.BasicServicesKit'; 619import { window } from '@kit.ArkUI'; 620 621class EntryAbility extends UIAbility { 622 onWindowStageCreate(windowStage: window.WindowStage) { 623 let options: preferences.Options = { name: 'myStore' }; 624 preferences.deletePreferences(this.context, options, (err: BusinessError) => { 625 if (err) { 626 console.error("Failed to delete preferences. code =" + err.code + ", message =" + err.message); 627 return; 628 } 629 console.info("Succeeded in deleting preferences."); 630 }) 631 } 632} 633``` 634 635 636## preferences.deletePreferences<sup>10+</sup> 637 638deletePreferences(context: Context, options: Options): Promise<void> 639 640从缓存中移出指定的Preferences实例，若Preferences实例有对应的持久化文件，则同时删除其持久化文件。使用Promise异步回调。 641 642调用该接口后，不建议再使用旧的Preferences实例进行数据操作，否则会出现数据一致性问题，应将Preferences实例置为null，系统将会统一回收。 643 644不支持该接口与preference其他接口并发调用。 645 646**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 647 648**系统能力：** SystemCapability.DistributedDataManager.Preferences.Core 649 650**参数：** 651 652| 参数名 | 类型 | 必填 | 说明 | 653| ------- | ---------------- | ---- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | 654| context | Context | 是 | 应用上下文。<br>FA模型的应用Context定义见[Context](../apis-ability-kit/js-apis-inner-app-context.md)。<br>Stage模型的应用Context定义见[Context](../apis-ability-kit/js-apis-inner-application-uiAbilityContext.md)。 | 655| options | [Options](#options10) | 是 | 与Preferences实例相关的配置选项。 | 656 657**返回值：** 658 659| 类型 | 说明 | 660| ------------------- | ------------------------- | 661| Promise<void> | 无返回结果的Promise对象。 | 662 663**错误码：** 664 665以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[用户首选项错误码](errorcode-preferences.md)。 666 667| 错误码ID | 错误信息 | 668| -------- | ------------------------------ | 669| 401 | Parameter error. Possible causes:<br>1. Mandatory parameters are left unspecified;<br>2. Incorrect parameter types;<br>3. Parameter verification failed. | 670| 801 | Capability not supported. | 671| 15500000 | Inner error. | 672| 15500010 | Failed to delete the user preferences persistence file. | 673| 15501001 | The operations is supported in stage mode only. | 674| 15501002 | Invalid dataGroupId. | 675 676**示例：** 677 678FA模型示例： 679 680<!--code_no_check_fa--> 681```ts 682// 获取context 683import { featureAbility } from '@kit.AbilityKit'; 684import { BusinessError } from '@kit.BasicServicesKit'; 685 686let context = featureAbility.getContext(); 687 688let options: preferences.Options = { name: 'myStore' }; 689let promise = preferences.deletePreferences(context, options); 690promise.then(() => { 691 console.info("Succeeded in deleting preferences."); 692}).catch((err: BusinessError) => { 693 console.error("Failed to delete preferences. code =" + err.code + ", message =" + err.message); 694}) 695``` 696 697Stage模型示例： 698 699```ts 700import { UIAbility } from '@kit.AbilityKit'; 701import { BusinessError } from '@kit.BasicServicesKit'; 702import { window } from '@kit.ArkUI'; 703 704class EntryAbility extends UIAbility { 705 onWindowStageCreate(windowStage: window.WindowStage) { 706 let options: preferences.Options = { name: 'myStore' }; 707 let promise = preferences.deletePreferences(this.context, options); 708 promise.then(() => { 709 console.info("Succeeded in deleting preferences."); 710 }).catch((err: BusinessError) => { 711 console.error("Failed to delete preferences. code =" + err.code + ", message =" + err.message); 712 }) 713 } 714} 715``` 716 717 718## preferences.removePreferencesFromCache 719 720removePreferencesFromCache(context: Context, name: string, callback: AsyncCallback<void>): void 721 722从缓存中移出指定的Preferences实例，使用callback异步回调。 723 724应用首次调用[getPreferences](#preferencesgetpreferences)接口获取某个Preferences实例后，该实例会被会被缓存起来，后续再次[getPreferences](#preferencesgetpreferences)时不会再次从持久化文件中读取，直接从缓存中获取Preferences实例。调用此接口移出缓存中的实例之后，再次getPreferences将会重新读取持久化文件，生成新的Preferences实例。 725 726调用该接口后，不建议再使用旧的Preferences实例进行数据操作，否则会出现数据一致性问题，应将Preferences实例置为null，系统将会统一回收。 727 728**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 729 730**系统能力：** SystemCapability.DistributedDataManager.Preferences.Core 731 732**参数：** 733 734| 参数名 | 类型 | 必填 | 说明 | 735| -------- | ------------------------------------- | ---- | ---------------------------------------------------- | 736| context | Context | 是 | 应用上下文。<br>FA模型的应用Context定义见[Context](../apis-ability-kit/js-apis-inner-app-context.md)。<br>Stage模型的应用Context定义见[Context](../apis-ability-kit/js-apis-inner-application-uiAbilityContext.md)。 | 737| name | string | 是 | Preferences实例的名称。 | 738| callback | AsyncCallback<void> | 是 | 回调函数。当移除成功，err为undefined，否则为错误对象。 | 739 740**错误码：** 741 742以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[用户首选项错误码](errorcode-preferences.md)。 743 744| 错误码ID | 错误信息 | 745| -------- | ------------------------------ | 746| 401 | Parameter error. Possible causes:<br>1. Mandatory parameters are left unspecified;<br>2. Incorrect parameter types;<br>3. Parameter verification failed. | 747| 15500000 | Inner error. | 748 749**示例：** 750 751FA模型示例： 752 753<!--code_no_check_fa--> 754```ts 755// 获取context 756import { featureAbility } from '@kit.AbilityKit'; 757import { BusinessError } from '@kit.BasicServicesKit'; 758 759let context = featureAbility.getContext(); 760preferences.removePreferencesFromCache(context, 'myStore', (err: BusinessError) => { 761 if (err) { 762 console.error("Failed to remove preferences. code =" + err.code + ", message =" + err.message); 763 return; 764 } 765 console.info("Succeeded in removing preferences."); 766}) 767``` 768 769Stage模型示例： 770 771```ts 772import { UIAbility } from '@kit.AbilityKit'; 773import { BusinessError } from '@kit.BasicServicesKit'; 774import { window } from '@kit.ArkUI'; 775 776class EntryAbility extends UIAbility { 777 onWindowStageCreate(windowStage: window.WindowStage) { 778 preferences.removePreferencesFromCache(this.context, 'myStore', (err: BusinessError) => { 779 if (err) { 780 console.error("Failed to remove preferences. code =" + err.code + ", message =" + err.message); 781 return; 782 } 783 console.info("Succeeded in removing preferences."); 784 }) 785 } 786} 787``` 788 789## preferences.removePreferencesFromCache 790 791removePreferencesFromCache(context: Context, name: string): Promise<void> 792 793从缓存中移出指定的Preferences实例，使用Promise异步回调。 794 795应用首次调用[getPreferences](#preferencesgetpreferences)接口获取某个Preferences实例后，该实例会被会被缓存起来，后续再次[getPreferences](#preferencesgetpreferences)时不会再次从持久化文件中读取，直接从缓存中获取Preferences实例。调用此接口移出缓存中的实例之后，再次getPreferences将会重新读取持久化文件，生成新的Preferences实例。 796 797调用该接口后，不建议再使用旧的Preferences实例进行数据操作，否则会出现数据一致性问题，应将Preferences实例置为null，系统将会统一回收。 798 799**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 800 801**系统能力：** SystemCapability.DistributedDataManager.Preferences.Core 802 803**参数：** 804 805| 参数名 | 类型 | 必填 | 说明 | 806| ------- | ------------------------------------- | ---- | ----------------------- | 807| context | Context | 是 | 应用上下文。<br>FA模型的应用Context定义见[Context](../apis-ability-kit/js-apis-inner-app-context.md)。<br>Stage模型的应用Context定义见[Context](../apis-ability-kit/js-apis-inner-application-uiAbilityContext.md)。 | 808| name | string | 是 | Preferences实例的名称。 | 809 810**返回值：** 811 812| 类型 | 说明 | 813| ------------------- | ------------------------- | 814| Promise<void> | 无返回结果的Promise对象。 | 815 816**错误码：** 817 818以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[用户首选项错误码](errorcode-preferences.md)。 819 820| 错误码ID | 错误信息 | 821| -------- | ------------------------------ | 822| 401 | Parameter error. Possible causes:<br>1. Mandatory parameters are left unspecified;<br>2. Incorrect parameter types;<br>3. Parameter verification failed. | 823| 15500000 | Inner error. | 824 825**示例：** 826 827FA模型示例： 828 829<!--code_no_check_fa--> 830```ts 831// 获取context 832import { featureAbility } from '@kit.AbilityKit'; 833import { BusinessError } from '@kit.BasicServicesKit'; 834 835let context = featureAbility.getContext(); 836let promise = preferences.removePreferencesFromCache(context, 'myStore'); 837promise.then(() => { 838 console.info("Succeeded in removing preferences."); 839}).catch((err: BusinessError) => { 840 console.error("Failed to remove preferences. code =" + err.code + ", message =" + err.message); 841}) 842``` 843 844Stage模型示例： 845 846```ts 847import { UIAbility } from '@kit.AbilityKit'; 848import { BusinessError } from '@kit.BasicServicesKit'; 849import { window } from '@kit.ArkUI'; 850 851class EntryAbility extends UIAbility { 852 onWindowStageCreate(windowStage: window.WindowStage) { 853 let promise = preferences.removePreferencesFromCache(this.context, 'myStore'); 854 promise.then(() => { 855 console.info("Succeeded in removing preferences."); 856 }).catch((err: BusinessError) => { 857 console.error("Failed to remove preferences. code =" + err.code + ", message =" + err.message); 858 }) 859 } 860} 861``` 862 863## preferences.removePreferencesFromCacheSync<sup>10+</sup> 864 865removePreferencesFromCacheSync(context: Context, name: string): void 866 867从缓存中移出指定的Preferences实例，此为同步接口。 868 869应用首次调用[getPreferences](#preferencesgetpreferences)接口获取某个Preferences实例后，该实例会被会被缓存起来，后续再次[getPreferences](#preferencesgetpreferences)时不会再次从持久化文件中读取，直接从缓存中获取Preferences实例。调用此接口移出缓存中的实例之后，再次getPreferences将会重新读取持久化文件，生成新的Preferences实例。 870 871调用该接口后，不建议再使用旧的Preferences实例进行数据操作，否则会出现数据一致性问题，应将Preferences实例置为null，系统将会统一回收。 872 873**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 874 875**系统能力：** SystemCapability.DistributedDataManager.Preferences.Core 876 877**参数：** 878 879| 参数名 | 类型 | 必填 | 说明 | 880| ------- | ------------------------------------- | ---- | ----------------------- | 881| context | Context | 是 | 应用上下文。<br>FA模型的应用Context定义见[Context](../apis-ability-kit/js-apis-inner-app-context.md)。<br>Stage模型的应用Context定义见[Context](../apis-ability-kit/js-apis-inner-application-uiAbilityContext.md)。 | 882| name | string | 是 | Preferences实例的名称。 | 883 884**错误码：** 885 886以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[用户首选项错误码](errorcode-preferences.md)。 887 888| 错误码ID | 错误信息 | 889| -------- | ------------------------------ | 890| 401 | Parameter error. Possible causes:<br>1. Mandatory parameters are left unspecified;<br>2. Incorrect parameter types;<br>3. Parameter verification failed. | 891| 15500000 | Inner error. | 892 893**示例：** 894 895FA模型示例： 896 897<!--code_no_check_fa--> 898```ts 899// 获取context 900import { featureAbility } from '@kit.AbilityKit'; 901let context = featureAbility.getContext(); 902preferences.removePreferencesFromCacheSync(context, 'myStore'); 903``` 904 905Stage模型示例： 906 907```ts 908import { UIAbility } from '@kit.AbilityKit'; 909import { window } from '@kit.ArkUI'; 910 911class EntryAbility extends UIAbility { 912 onWindowStageCreate(windowStage: window.WindowStage) { 913 preferences.removePreferencesFromCacheSync(this.context, 'myStore'); 914 } 915} 916``` 917 918## preferences.removePreferencesFromCache<sup>10+</sup> 919 920removePreferencesFromCache(context: Context, options: Options, callback: AsyncCallback<void>): void 921 922从缓存中移出指定的Preferences实例，使用callback异步回调。 923 924应用首次调用[getPreferences](#preferencesgetpreferences)接口获取某个Preferences实例后，该实例会被会被缓存起来，后续再次[getPreferences](#preferencesgetpreferences)时不会再次从持久化文件中读取，直接从缓存中获取Preferences实例。调用此接口移出缓存中的实例之后，再次getPreferences将会重新读取持久化文件，生成新的Preferences实例。 925 926调用该接口后，不建议再使用旧的Preferences实例进行数据操作，否则会出现数据一致性问题，应将Preferences实例置为null，系统将会统一回收。 927 928**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 929 930**系统能力：** SystemCapability.DistributedDataManager.Preferences.Core 931 932**参数：** 933 934| 参数名 | 类型 | 必填 | 说明 | 935| -------- | ------------------------- | ---- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | 936| context | Context | 是 | 应用上下文。<br>FA模型的应用Context定义见[Context](../apis-ability-kit/js-apis-inner-app-context.md)。<br>Stage模型的应用Context定义见[Context](../apis-ability-kit/js-apis-inner-application-uiAbilityContext.md)。 | 937| options | [Options](#options10) | 是 | 与Preferences实例相关的配置选项。 | 938| callback | AsyncCallback<void> | 是 | 回调函数。当移除成功，err为undefined，否则为错误对象。 | 939 940**错误码：** 941 942以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[用户首选项错误码](errorcode-preferences.md)。 943 944| 错误码ID | 错误信息 | 945| -------- | ------------------------------ | 946| 401 | Parameter error. Possible causes:<br>1. Mandatory parameters are left unspecified;<br>2. Incorrect parameter types;<br>3. Parameter verification failed. | 947| 801 | Capability not supported. | 948| 15500000 | Inner error. | 949| 15501001 | The operations is supported in stage mode only. | 950| 15501002 | Invalid dataGroupId. | 951 952**示例：** 953 954FA模型示例： 955 956<!--code_no_check_fa--> 957```ts 958// 获取context 959import { featureAbility } from '@kit.AbilityKit'; 960import { BusinessError } from '@kit.BasicServicesKit'; 961 962let context = featureAbility.getContext(); 963let options: preferences.Options = { name: 'myStore' }; 964preferences.removePreferencesFromCache(context, options, (err: BusinessError) => { 965 if (err) { 966 console.error("Failed to remove preferences. code =" + err.code + ", message =" + err.message); 967 return; 968 } 969 console.info("Succeeded in removing preferences."); 970}) 971``` 972 973Stage模型示例： 974 975```ts 976import { UIAbility } from '@kit.AbilityKit'; 977import { BusinessError } from '@kit.BasicServicesKit'; 978import { window } from '@kit.ArkUI'; 979 980class EntryAbility extends UIAbility { 981 onWindowStageCreate(windowStage: window.WindowStage) { 982 let options: preferences.Options = { name: 'myStore' }; 983 preferences.removePreferencesFromCache(this.context, options, (err: BusinessError) => { 984 if (err) { 985 console.error("Failed to remove preferences. code =" + err.code + ", message =" + err.message); 986 return; 987 } 988 console.info("Succeeded in removing preferences."); 989 }) 990 } 991} 992``` 993 994## preferences.removePreferencesFromCache<sup>10+</sup> 995 996removePreferencesFromCache(context: Context, options: Options): Promise<void> 997 998从缓存中移出指定的Preferences实例，使用Promise异步回调。 999 1000应用首次调用[getPreferences](#preferencesgetpreferences)接口获取某个Preferences实例后，该实例会被会被缓存起来，后续再次[getPreferences](#preferencesgetpreferences)时不会再次从持久化文件中读取，直接从缓存中获取Preferences实例。调用此接口移出缓存中的实例之后，再次getPreferences将会重新读取持久化文件，生成新的Preferences实例。 1001 1002调用该接口后，不建议再使用旧的Preferences实例进行数据操作，否则会出现数据一致性问题，应将Preferences实例置为null，系统将会统一回收。 1003 1004**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1005 1006**系统能力：** SystemCapability.DistributedDataManager.Preferences.Core 1007 1008**参数：** 1009 1010| 参数名 | 类型 | 必填 | 说明 | 1011| ------- | ---------------- | ---- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | 1012| context | Context | 是 | 应用上下文。<br>FA模型的应用Context定义见[Context](../apis-ability-kit/js-apis-inner-app-context.md)。<br>Stage模型的应用Context定义见[Context](../apis-ability-kit/js-apis-inner-application-uiAbilityContext.md)。 | 1013| options | [Options](#options10) | 是 | 与Preferences实例相关的配置选项。 | 1014 1015**返回值：** 1016 1017| 类型 | 说明 | 1018| ------------------- | ------------------------- | 1019| Promise<void> | 无返回结果的Promise对象。 | 1020 1021**错误码：** 1022 1023以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[用户首选项错误码](errorcode-preferences.md)。 1024 1025| 错误码ID | 错误信息 | 1026| -------- | ------------------------------ | 1027| 401 | Parameter error. Possible causes:<br>1. Mandatory parameters are left unspecified;<br>2. Incorrect parameter types;<br>3. Parameter verification failed. | 1028| 801 | Capability not supported. | 1029| 15500000 | Inner error. | 1030| 15501001 | The operations is supported in stage mode only. | 1031| 15501002 | Invalid dataGroupId. | 1032 1033**示例：** 1034 1035FA模型示例： 1036 1037<!--code_no_check_fa--> 1038```ts 1039// 获取context 1040import { featureAbility } from '@kit.AbilityKit'; 1041import { BusinessError } from '@kit.BasicServicesKit'; 1042 1043let context = featureAbility.getContext(); 1044let options: preferences.Options = { name: 'myStore' }; 1045let promise = preferences.removePreferencesFromCache(context, options); 1046promise.then(() => { 1047 console.info("Succeeded in removing preferences."); 1048}).catch((err: BusinessError) => { 1049 console.error("Failed to remove preferences. code =" + err.code + ", message =" + err.message); 1050}) 1051``` 1052 1053Stage模型示例： 1054 1055```ts 1056import { UIAbility } from '@kit.AbilityKit'; 1057import { BusinessError } from '@kit.BasicServicesKit'; 1058import { window } from '@kit.ArkUI'; 1059 1060class EntryAbility extends UIAbility { 1061 onWindowStageCreate(windowStage: window.WindowStage) { 1062 let options: preferences.Options = { name: 'myStore' }; 1063 let promise = preferences.removePreferencesFromCache(this.context, options); 1064 promise.then(() => { 1065 console.info("Succeeded in removing preferences."); 1066 }).catch((err: BusinessError) => { 1067 console.error("Failed to remove preferences. code =" + err.code + ", message =" + err.message); 1068 }) 1069 } 1070} 1071``` 1072 1073## preferences.removePreferencesFromCacheSync<sup>10+</sup> 1074 1075removePreferencesFromCacheSync(context: Context, options: Options):void 1076 1077从缓存中移出指定的Preferences实例，此为同步接口。 1078 1079应用首次调用[getPreferences](#preferencesgetpreferences)接口获取某个Preferences实例后，该实例会被会被缓存起来，后续再次[getPreferences](#preferencesgetpreferences)时不会再次从持久化文件中读取，直接从缓存中获取Preferences实例。调用此接口移出缓存中的实例之后，再次getPreferences将会重新读取持久化文件，生成新的Preferences实例。 1080 1081调用该接口后，不建议再使用旧的Preferences实例进行数据操作，否则会出现数据一致性问题，应将Preferences实例置为null，系统将会统一回收。 1082 1083**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1084 1085**系统能力：** SystemCapability.DistributedDataManager.Preferences.Core 1086 1087**参数：** 1088 1089| 参数名 | 类型 | 必填 | 说明 | 1090| ------- | --------------------- | ---- | ------------------------------------------------------------ | 1091| context | Context | 是 | 应用上下文。<br>FA模型的应用Context定义见[Context](../apis-ability-kit/js-apis-inner-app-context.md)。<br>Stage模型的应用Context定义见[Context](../apis-ability-kit/js-apis-inner-application-uiAbilityContext.md)。 | 1092| options | [Options](#options10) | 是 | 与Preferences实例相关的配置选项。 | 1093 1094**错误码：** 1095 1096以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[用户首选项错误码](errorcode-preferences.md)。 1097 1098| 错误码ID | 错误信息 | 1099| -------- | ------------------------------ | 1100| 401 | Parameter error. Possible causes:<br>1. Mandatory parameters are left unspecified;<br>2. Incorrect parameter types;<br>3. Parameter verification failed. | 1101| 801 | Capability not supported. | 1102| 15500000 | Inner error. | 1103| 15501001 | The operations is supported in stage mode only. | 1104| 15501002 | Invalid dataGroupId. | 1105 1106**示例：** 1107 1108FA模型示例： 1109 1110<!--code_no_check_fa--> 1111```ts 1112// 获取context 1113import { featureAbility } from '@kit.AbilityKit'; 1114let context = featureAbility.getContext(); 1115let options: preferences.Options = { name: 'myStore' }; 1116preferences.removePreferencesFromCacheSync(context, options); 1117``` 1118 1119Stage模型示例： 1120 1121```ts 1122import { UIAbility } from '@kit.AbilityKit'; 1123import { window } from '@kit.ArkUI'; 1124 1125class EntryAbility extends UIAbility { 1126 onWindowStageCreate(windowStage: window.WindowStage) { 1127 let options: preferences.Options = { name: 'myStore' }; 1128 preferences.removePreferencesFromCacheSync(this.context, options); 1129 } 1130} 1131``` 1132 1133## Options<sup>10+</sup> 1134 1135Preferences实例配置选项。 1136 1137**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1138 1139**系统能力：** SystemCapability.DistributedDataManager.Preferences.Core 1140 1141| 名称 | 类型 | 必填 | 说明 | 1142| ----------- | ------ | ---- | ------------------------------------------------------------ | 1143| name | string | 是 | Preferences实例的名称。 | 1144| dataGroupId | string\|null\|undefined | 否 | 应用组ID，<!--RP1-->暂不支持指定dataGroupId在对应共享沙箱路径下创建Preferences实例。<!--RP1End--><br/>为可选参数。指定在此dataGroupId对应的沙箱路径下创建Preferences实例。当此参数不填时，默认在本应用沙箱目录下创建Preferences实例。<br/> **模型约束：** 此属性仅在Stage模型下可用。<br/>**原子化服务API：** 从API version 11开始，该参数支持在原子化服务中使用。 <br/> | 1145 1146 1147## Preferences 1148 1149首选项实例，提供获取和修改存储数据的接口。 1150 1151下列接口都需先使用[preferences.getPreferences](#preferencesgetpreferences)获取到Preferences实例，再通过此实例调用对应接口。 1152 1153 1154### get 1155 1156get(key: string, defValue: ValueType, callback: AsyncCallback<ValueType>): void 1157 1158从缓存的Preferences实例中获取键对应的值，如果值为null或者非默认值类型，返回默认数据defValue，使用callback异步回调。 1159 1160**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1161 1162**系统能力：** SystemCapability.DistributedDataManager.Preferences.Core 1163 1164**参数：** 1165 1166| 参数名 | 类型 | 必填 | 说明 | 1167| -------- | -------------------------------------------- | ---- |---------------------------| 1168| key | string | 是 | 要获取的存储Key名称，不能为空。 | 1169| defValue | [ValueType](#valuetype) | 是 | 默认返回值。 | 1170| callback | AsyncCallback<[ValueType](#valuetype)> | 是 | 回调函数。当获取成功时，err为undefined，data为键对应的值；否则err为错误对象。 | 1171 1172**错误码：** 1173 1174以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[用户首选项错误码](errorcode-preferences.md)。 1175 1176| 错误码ID | 错误信息 | 1177| -------- | ------------------------------ | 1178| 401 | Parameter error. Possible causes:<br>1. Mandatory parameters are left unspecified;<br>2. Incorrect parameter types;<br>3. Parameter verification failed. | 1179| 15500000 | Inner error. | 1180 1181**示例：** 1182 1183```ts 1184import { BusinessError } from '@kit.BasicServicesKit'; 1185 1186dataPreferences.get('startup', 'default', (err: BusinessError, val: preferences.ValueType) => { 1187 if (err) { 1188 console.error("Failed to get value of 'startup'. code =" + err.code + ", message =" + err.message); 1189 return; 1190 } 1191 console.info("Succeeded in getting value of 'startup'. val： " + val); 1192}) 1193``` 1194 1195### get 1196 1197get(key: string, defValue: ValueType): Promise<ValueType> 1198 1199从缓存的Preferences实例中获取键对应的值，如果值为null或者非默认值类型，返回默认数据defValue，使用Promise异步回调。 1200 1201**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1202 1203**系统能力：** SystemCapability.DistributedDataManager.Preferences.Core 1204 1205 **参数：** 1206 1207| 参数名 | 类型 | 必填 | 说明 | 1208| -------- | ----------------------- | ---- |--------| 1209| key | string | 是 | 要获取的存储Key名称，不能为空。 | 1210| defValue | [ValueType](#valuetype) | 是 | 默认返回值。 | 1211 1212**返回值：** 1213 1214| 类型 | 说明 | 1215| ----------------------------------- | ----------------------------- | 1216| Promise<[ValueType](#valuetype)> | Promise对象，返回键对应的值。 | 1217 1218**错误码：** 1219 1220以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[用户首选项错误码](errorcode-preferences.md)。 1221 1222| 错误码ID | 错误信息 | 1223| -------- | ------------------------------ | 1224| 401 | Parameter error. Possible causes:<br>1. Mandatory parameters are left unspecified;<br>2. Incorrect parameter types;<br>3. Parameter verification failed. | 1225| 15500000 | Inner error. | 1226 1227**示例：** 1228 1229```ts 1230import { BusinessError } from '@kit.BasicServicesKit'; 1231 1232let promise = dataPreferences.get('startup', 'default'); 1233promise.then((data: preferences.ValueType) => { 1234 console.info("Succeeded in getting value of 'startup'. Data: " + data); 1235}).catch((err: BusinessError) => { 1236 console.error("Failed to get value of 'startup'. code =" + err.code + ", message =" + err.message); 1237}) 1238``` 1239 1240### getSync<sup>10+</sup> 1241 1242getSync(key: string, defValue: ValueType): ValueType 1243 1244从缓存的Preferences实例中获取键对应的值，如果值为null或者非默认值类型，返回默认数据defValue，此为同步接口。 1245 1246**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1247 1248**系统能力：** SystemCapability.DistributedDataManager.Preferences.Core 1249 1250**参数：** 1251 1252| 参数名 | 类型 | 必填 | 说明 | 1253| -------- | ----------------------- | ---- |---------------------| 1254| key | string | 是 | 要获取的存储Key名称，不能为空。 | 1255| defValue | [ValueType](#valuetype) | 是 | 默认返回值。 | 1256 1257**返回值：** 1258 1259| 类型 | 说明 | 1260| ----------------------------------- | ----------------------------- | 1261| [ValueType](#valuetype) | 返回键对应的值。 | 1262 1263**错误码：** 1264 1265以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[用户首选项错误码](errorcode-preferences.md)。 1266 1267| 错误码ID | 错误信息 | 1268| -------- | ------------------------------ | 1269| 401 | Parameter error. Possible causes:<br>1. Mandatory parameters are left unspecified;<br>2. Incorrect parameter types;<br>3. Parameter verification failed. | 1270| 15500000 | Inner error. | 1271 1272**示例：** 1273 1274```ts 1275let value: preferences.ValueType = dataPreferences.getSync('startup', 'default'); 1276``` 1277 1278### getAll 1279 1280getAll(callback: AsyncCallback<Object>): void; 1281 1282从缓存的Preferences实例中获取所有键值数据。 1283 1284**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1285 1286**系统能力：** SystemCapability.DistributedDataManager.Preferences.Core 1287 1288**参数：** 1289 1290| 参数名 | 类型 | 必填 | 说明 | 1291| -------- | --------------------------- | ---- | ------------------------------------------------------------ | 1292| callback | AsyncCallback<Object> | 是 | 回调函数。当获取成功，err为undefined，value为所有键值数据；否则err为错误对象。 | 1293 1294**错误码：** 1295 1296以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[用户首选项错误码](errorcode-preferences.md)。 1297 1298| 错误码ID | 错误信息 | 1299| -------- | ------------------------------ | 1300| 401 | Parameter error. Mandatory parameters are left unspecified.| 1301| 15500000 | Inner error. | 1302 1303**示例：** 1304 1305```ts 1306import { BusinessError } from '@kit.BasicServicesKit'; 1307 1308// 由于ArkTS中无Object.keys，且无法使用for..in... 1309// 若报ArkTS问题，请将此方法单独抽离至一个ts文件中并暴露，在需要用到的ets文件中引入使用 1310function getObjKeys(obj: Object): string[] { 1311 let keys = Object.keys(obj); 1312 return keys; 1313} 1314 1315dataPreferences.getAll((err: BusinessError, value: Object) => { 1316 if (err) { 1317 console.error("Failed to get all key-values. code =" + err.code + ", message =" + err.message); 1318 return; 1319 } 1320 let allKeys = getObjKeys(value); 1321 console.info("getAll keys = " + allKeys); 1322 console.info("getAll object = " + JSON.stringify(value)); 1323}) 1324``` 1325 1326 1327### getAll 1328 1329getAll(): Promise<Object> 1330 1331从缓存的Preferences实例中获取所有键值数据。 1332 1333**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1334 1335**系统能力：** SystemCapability.DistributedDataManager.Preferences.Core 1336 1337**返回值：** 1338 1339| 类型 | 说明 | 1340| --------------------- | ------------------------------------------- | 1341| Promise<Object> | Promise对象，返回含有所有键值数据。 | 1342 1343**错误码：** 1344 1345以下错误码的详细介绍请参见[用户首选项错误码](errorcode-preferences.md)。 1346 1347| 错误码ID | 错误信息 | 1348| -------- | ------------------------------ | 1349| 15500000 | Inner error. | 1350 1351**示例：** 1352 1353```ts 1354import { BusinessError } from '@kit.BasicServicesKit'; 1355 1356// 由于ArkTS中无Object.keys，且无法使用for..in... 1357// 若报ArkTS问题，请将此方法单独抽离至一个ts文件中并暴露，在需要用到的ets文件中引入使用 1358function getObjKeys(obj: Object): string[] { 1359 let keys = Object.keys(obj); 1360 return keys; 1361} 1362 1363let promise = dataPreferences.getAll(); 1364promise.then((value: Object) => { 1365 let allKeys = getObjKeys(value); 1366 console.info('getAll keys = ' + allKeys); 1367 console.info("getAll object = " + JSON.stringify(value)); 1368}).catch((err: BusinessError) => { 1369 console.error("Failed to get all key-values. code =" + err.code + ", message =" + err.message); 1370}) 1371``` 1372 1373### getAllSync<sup>10+</sup> 1374 1375getAllSync(): Object 1376 1377从缓存的Preferences实例中获取所有键值数据，此为同步接口。 1378 1379**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1380 1381**系统能力：** SystemCapability.DistributedDataManager.Preferences.Core 1382 1383**返回值：** 1384 1385| 类型 | 说明 | 1386| --------------------- | ------------------------------------------- | 1387| Object | 返回含有所有键值数据。 | 1388 1389**错误码：** 1390 1391以下错误码的详细介绍请参见[用户首选项错误码](errorcode-preferences.md)。 1392 1393| 错误码ID | 错误信息 | 1394| -------- | ------------------------------ | 1395| 15500000 | Inner error. | 1396 1397**示例：** 1398 1399```ts 1400// 由于ArkTS中无Object.keys，且无法使用for..in... 1401// 若报ArkTS问题，请将此方法单独抽离至一个ts文件中并暴露，在需要用到的ets文件中引入使用 1402function getObjKeys(obj: Object): string[] { 1403 let keys = Object.keys(obj); 1404 return keys; 1405} 1406 1407let value = dataPreferences.getAllSync(); 1408let allKeys = getObjKeys(value); 1409console.info('getAll keys = ' + allKeys); 1410console.info("getAll object = " + JSON.stringify(value)); 1411``` 1412 1413### put 1414 1415put(key: string, value: ValueType, callback: AsyncCallback<void>): void 1416 1417将数据写入缓存的Preferences实例中，可通过[flush](#flush)将Preferences实例持久化，使用callback异步回调。 1418 1419 > **说明：** 1420 > 1421 > 当value中包含非UTF-8格式的字符串时，请使用Uint8Array类型存储，否则会造成持久化文件出现格式错误造成文件损坏。 1422 > 1423 > 当对应的键已经存在时，put()方法会覆盖其值。可以使用hasSync()方法检查是否存在对应键值对。 1424 1425**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1426 1427**系统能力：** SystemCapability.DistributedDataManager.Preferences.Core 1428 1429**参数：** 1430 1431| 参数名 | 类型 | 必填 | 说明 | 1432| -------- | ------------------------- | ---- |-------------------------| 1433| key | string | 是 | 要修改的存储的Key，不能为空。 | 1434| value | [ValueType](#valuetype) | 是 | 存储的新值。 | 1435| callback | AsyncCallback<void> | 是 | 回调函数。当数据写入成功，err为undefined；否则为错误对象。 | 1436 1437**错误码：** 1438 1439以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[用户首选项错误码](errorcode-preferences.md)。 1440 1441| 错误码ID | 错误信息 | 1442| -------- | ------------------------------ | 1443| 401 | Parameter error. Possible causes:<br>1. Mandatory parameters are left unspecified;<br>2. Incorrect parameter types;<br>3. Parameter verification failed. | 1444| 15500000 | Inner error. | 1445 1446**示例：** 1447 1448```ts 1449import { BusinessError } from '@kit.BasicServicesKit'; 1450 1451dataPreferences.put('startup', 'auto', (err: BusinessError) => { 1452 if (err) { 1453 console.error("Failed to put value of 'startup'. code =" + err.code + ", message =" + err.message); 1454 return; 1455 } 1456 console.info("Succeeded in putting value of 'startup'."); 1457}) 1458``` 1459 1460 1461### put 1462 1463put(key: string, value: ValueType): Promise<void> 1464 1465将数据写入缓存的Preferences实例中，可通过[flush](#flush)将Preferences实例持久化，使用Promise异步回调。 1466 1467 > **说明：** 1468 > 1469 > 当value中包含非UTF-8格式的字符串时，请使用Uint8Array类型存储，否则会造成持久化文件出现格式错误造成文件损坏。 1470 > 1471 > 当对应的键已经存在时，put()方法会覆盖其值。可以使用hasSync()方法检查是否存在对应键值对。 1472 1473**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1474 1475**系统能力：** SystemCapability.DistributedDataManager.Preferences.Core 1476 1477**参数：** 1478 1479| 参数名 | 类型 | 必填 | 说明 | 1480| ------ | ----------------------- | ---- |--------------------------| 1481| key | string | 是 | 要修改的存储的Key，不能为空。 | 1482| value | [ValueType](#valuetype) | 是 | 存储的新值。 | 1483 1484**返回值：** 1485 1486| 类型 | 说明 | 1487| ------------------- | ------------------------- | 1488| Promise<void> | 无返回结果的Promise对象。 | 1489 1490**错误码：** 1491 1492以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[用户首选项错误码](errorcode-preferences.md)。 1493 1494| 错误码ID | 错误信息 | 1495| -------- | ------------------------------ | 1496| 401 | Parameter error. Possible causes:<br>1. Mandatory parameters are left unspecified;<br>2. Incorrect parameter types;<br>3. Parameter verification failed. | 1497| 15500000 | Inner error. | 1498 1499**示例：** 1500 1501```ts 1502import { BusinessError } from '@kit.BasicServicesKit'; 1503 1504let promise = dataPreferences.put('startup', 'auto'); 1505promise.then(() => { 1506 console.info("Succeeded in putting value of 'startup'."); 1507}).catch((err: BusinessError) => { 1508 console.error("Failed to put value of 'startup'. code =" + err.code + ", message =" + err.message); 1509}) 1510``` 1511 1512 1513### putSync<sup>10+</sup> 1514 1515putSync(key: string, value: ValueType): void 1516 1517将数据写入缓存的Preferences实例中，可通过[flush](#flush)将Preferences实例持久化，此为同步接口。 1518 1519 > **说明：** 1520 > 1521 > 当value中包含非UTF-8格式的字符串时，请使用Uint8Array类型存储，否则会造成持久化文件出现格式错误造成文件损坏。 1522 > 1523 > 当对应的键已经存在时，putSync()方法会覆盖其值。可以使用hasSync()方法检查是否存在对应键值对。 1524 1525**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1526 1527**系统能力：** SystemCapability.DistributedDataManager.Preferences.Core 1528 1529**参数：** 1530 1531| 参数名 | 类型 | 必填 | 说明 | 1532| ------ | ----------------------- | ---- | ------------------------ | 1533| key | string | 是 | 要修改的存储的Key，不能为空。 | 1534| value | [ValueType](#valuetype) | 是 | 存储的新值。 | 1535 1536**错误码：** 1537 1538以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[用户首选项错误码](errorcode-preferences.md)。 1539 1540| 错误码ID | 错误信息 | 1541| -------- | ------------------------------ | 1542| 401 | Parameter error. Possible causes:<br>1. Mandatory parameters are left unspecified;<br>2. Incorrect parameter types;<br>3. Parameter verification failed. | 1543| 15500000 | Inner error. | 1544 1545**示例：** 1546 1547```ts 1548dataPreferences.putSync('startup', 'auto'); 1549``` 1550 1551 1552### has 1553 1554has(key: string, callback: AsyncCallback<boolean>): void 1555 1556检查缓存的Preferences实例中是否包含名为给定Key的存储键值对，使用callback异步回调。 1557 1558**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1559 1560**系统能力：** SystemCapability.DistributedDataManager.Preferences.Core 1561 1562**参数：** 1563 1564| 参数名 | 类型 | 必填 | 说明 | 1565| -------- | ---------------------------- | ---- | ------------------------------------------------------------ | 1566| key | string | 是 | 要检查的存储key名称，不能为空。 | 1567| callback | AsyncCallback<boolean> | 是 | 回调函数。返回Preferences实例是否包含给定key的存储键值对，true表示存在，false表示不存在。 | 1568 1569**错误码：** 1570 1571以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[用户首选项错误码](errorcode-preferences.md)。 1572 1573| 错误码ID | 错误信息 | 1574| -------- | ------------------------------ | 1575| 401 | Parameter error. Possible causes:<br>1. Mandatory parameters are left unspecified;<br>2. Incorrect parameter types;<br>3. Parameter verification failed. | 1576| 15500000 | Inner error. | 1577 1578**示例：** 1579 1580```ts 1581import { BusinessError } from '@kit.BasicServicesKit'; 1582 1583dataPreferences.has('startup', (err: BusinessError, val: boolean) => { 1584 if (err) { 1585 console.error("Failed to check the key 'startup'. code =" + err.code + ", message =" + err.message); 1586 return; 1587 } 1588 if (val) { 1589 console.info("The key 'startup' is contained."); 1590 } else { 1591 console.info("The key 'startup' dose not contain."); 1592 } 1593}) 1594``` 1595 1596 1597### has 1598 1599has(key: string): Promise<boolean> 1600 1601检查缓存的Preferences实例中是否包含名为给定Key的存储键值对，使用Promise异步回调。 1602 1603**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1604 1605**系统能力：** SystemCapability.DistributedDataManager.Preferences.Core 1606 1607**参数：** 1608 1609| 参数名 | 类型 | 必填 | 说明 | 1610| ------ | ------ | ---- | ------------------------------- | 1611| key | string | 是 | 要检查的存储key名称，不能为空。 | 1612 1613**返回值：** 1614 1615| 类型 | 说明 | 1616| ---------------------- | ------------------------------------------------------------ | 1617| Promise<boolean> | Promise对象。返回Preferences实例是否包含给定key的存储键值对，true表示存在，false表示不存在。 | 1618 1619**错误码：** 1620 1621以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[用户首选项错误码](errorcode-preferences.md)。 1622 1623| 错误码ID | 错误信息 | 1624| -------- | ------------------------------ | 1625| 401 | Parameter error. Possible causes:<br>1. Mandatory parameters are left unspecified;<br>2. Incorrect parameter types;<br>3. Parameter verification failed. | 1626| 15500000 | Inner error. | 1627 1628**示例：** 1629 1630```ts 1631import { BusinessError } from '@kit.BasicServicesKit'; 1632 1633let promise = dataPreferences.has('startup'); 1634promise.then((val: boolean) => { 1635 if (val) { 1636 console.info("The key 'startup' is contained."); 1637 } else { 1638 console.info("The key 'startup' dose not contain."); 1639 } 1640}).catch((err: BusinessError) => { 1641 console.error("Failed to check the key 'startup'. code =" + err.code + ", message =" + err.message); 1642}) 1643``` 1644 1645 1646### hasSync<sup>10+</sup> 1647 1648hasSync(key: string): boolean 1649 1650检查缓存的Preferences实例中是否包含名为给定Key的存储键值对，此为同步接口。 1651 1652**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1653 1654**系统能力：** SystemCapability.DistributedDataManager.Preferences.Core 1655 1656**参数：** 1657 1658| 参数名 | 类型 | 必填 | 说明 | 1659| ------ | ------ | ---- | ------------------------------- | 1660| key | string | 是 | 要检查的存储key名称，不能为空。 | 1661 1662**返回值：** 1663 1664| 类型 | 说明 | 1665| ---------------------- | ------------------------------------------------------------ | 1666| boolean | 返回Preferences实例是否包含给定key的存储键值对，true表示存在，false表示不存在。 | 1667 1668**错误码：** 1669 1670以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[用户首选项错误码](errorcode-preferences.md)。 1671 1672| 错误码ID | 错误信息 | 1673| -------- | ------------------------------ | 1674| 401 | Parameter error. Possible causes:<br>1. Mandatory parameters are left unspecified;<br>2. Incorrect parameter types;<br>3. Parameter verification failed. | 1675| 15500000 | Inner error. | 1676 1677**示例：** 1678 1679```ts 1680let isExist: boolean = dataPreferences.hasSync('startup'); 1681if (isExist) { 1682 console.info("The key 'startup' is contained."); 1683} else { 1684 console.info("The key 'startup' dose not contain."); 1685} 1686``` 1687 1688 1689### delete 1690 1691delete(key: string, callback: AsyncCallback<void>): void 1692 1693从缓存的Preferences实例中删除名为给定Key的存储键值对，可通过[flush](#flush)将Preferences实例持久化，使用callback异步回调。 1694 1695**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1696 1697**系统能力：** SystemCapability.DistributedDataManager.Preferences.Core 1698 1699**参数：** 1700 1701| 参数名 | 类型 | 必填 | 说明 | 1702| -------- | ------------------------- | ---- | ---------------------------------------------------- | 1703| key | string | 是 | 要删除的存储Key名称，不能为空。 | 1704| callback | AsyncCallback<void> | 是 | 回调函数。当删除成功，err为undefined；否则为错误对象。 | 1705 1706**错误码：** 1707 1708以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[用户首选项错误码](errorcode-preferences.md)。 1709 1710| 错误码ID | 错误信息 | 1711| -------- | ------------------------------ | 1712| 401 | Parameter error. Possible causes:<br>1. Mandatory parameters are left unspecified;<br>2. Incorrect parameter types;<br>3. Parameter verification failed. | 1713| 15500000 | Inner error. | 1714 1715**示例：** 1716 1717```ts 1718import { BusinessError } from '@kit.BasicServicesKit'; 1719 1720dataPreferences.delete('startup', (err: BusinessError) => { 1721 if (err) { 1722 console.error("Failed to delete the key 'startup'. code =" + err.code + ", message =" + err.message); 1723 return; 1724 } 1725 console.info("Succeeded in deleting the key 'startup'."); 1726}) 1727``` 1728 1729 1730### delete 1731 1732delete(key: string): Promise<void> 1733 1734从缓存的Preferences实例中删除名为给定Key的存储键值对，可通过[flush](#flush)将Preferences实例持久化，使用Promise异步回调。 1735 1736**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1737 1738**系统能力：** SystemCapability.DistributedDataManager.Preferences.Core 1739 1740**参数：** 1741 1742| 参数名 | 类型 | 必填 | 说明 | 1743| ------ | ------ | ---- | ------------------------------- | 1744| key | string | 是 | 要删除的存储key名称，不能为空。 | 1745 1746**返回值：** 1747 1748| 类型 | 说明 | 1749| ------------------- | ------------------------- | 1750| Promise<void> | 无返回结果的Promise对象。 | 1751 1752**错误码：** 1753 1754以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[用户首选项错误码](errorcode-preferences.md)。 1755 1756| 错误码ID | 错误信息 | 1757| -------- | ------------------------------ | 1758| 401 | Parameter error. Possible causes:<br>1. Mandatory parameters are left unspecified;<br>2. Incorrect parameter types;<br>3. Parameter verification failed. | 1759| 15500000 | Inner error. | 1760 1761**示例：** 1762 1763```ts 1764import { BusinessError } from '@kit.BasicServicesKit'; 1765 1766let promise = dataPreferences.delete('startup'); 1767promise.then(() => { 1768 console.info("Succeeded in deleting the key 'startup'."); 1769}).catch((err: BusinessError) => { 1770 console.error("Failed to delete the key 'startup'. code =" + err.code +", message =" + err.message); 1771}) 1772``` 1773 1774 1775### deleteSync<sup>10+</sup> 1776 1777deleteSync(key: string): void 1778 1779从缓存的Preferences实例中删除名为给定Key的存储键值对，可通过[flush](#flush)将Preferences实例持久化，此为同步接口。 1780 1781**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1782 1783**系统能力：** SystemCapability.DistributedDataManager.Preferences.Core 1784 1785**参数：** 1786 1787| 参数名 | 类型 | 必填 | 说明 | 1788| ------ | ------ | ---- | ------------------------------- | 1789| key | string | 是 | 要删除的存储key名称，不能为空。 | 1790 1791**错误码：** 1792 1793以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[用户首选项错误码](errorcode-preferences.md)。 1794 1795| 错误码ID | 错误信息 | 1796| -------- | ------------------------------ | 1797| 401 | Parameter error. Possible causes:<br>1. Mandatory parameters are left unspecified;<br>2. Incorrect parameter types;<br>3. Parameter verification failed. | 1798| 15500000 | Inner error. | 1799 1800**示例：** 1801 1802```ts 1803dataPreferences.deleteSync('startup'); 1804``` 1805 1806 1807### flush 1808 1809flush(callback: AsyncCallback<void>): void 1810 1811 > **说明：** 1812 > 1813 > 当数据未修改或修改后的数据与缓存数据一致时，不会刷新持久化文件。 1814 1815将缓存的Preferences实例中的数据异步存储到用户首选项的持久化文件中，使用callback异步回调。 1816 1817**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1818 1819**系统能力：** SystemCapability.DistributedDataManager.Preferences.Core 1820 1821**参数：** 1822 1823| 参数名 | 类型 | 必填 | 说明 | 1824| -------- | ------------------------- | ---- | ---------------------------------------------------- | 1825| callback | AsyncCallback<void> | 是 | 回调函数。当保存成功，err为undefined；否则为错误对象。 | 1826 1827**错误码：** 1828 1829以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[用户首选项错误码](errorcode-preferences.md)。 1830 1831| 错误码ID | 错误信息 | 1832| -------- | ------------------------------ | 1833| 401 | Parameter error. Mandatory parameters are left unspecified. | 1834| 15500000 | Inner error. | 1835 1836**示例：** 1837 1838```ts 1839import { BusinessError } from '@kit.BasicServicesKit'; 1840 1841dataPreferences.flush((err: BusinessError) => { 1842 if (err) { 1843 console.error("Failed to flush. code =" + err.code + ", message =" + err.message); 1844 return; 1845 } 1846 console.info("Succeeded in flushing."); 1847}) 1848``` 1849 1850 1851### flush 1852 1853flush(): Promise<void> 1854 1855将缓存的Preferences实例中的数据异步存储到用户首选项的持久化文件中，使用Promise异步回调。 1856 1857 > **说明：** 1858 > 1859 > 当数据未修改或修改后的数据与缓存数据一致时，不会刷新持久化文件。 1860 1861**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1862 1863**系统能力：** SystemCapability.DistributedDataManager.Preferences.Core 1864 1865**返回值：** 1866 1867| 类型 | 说明 | 1868| ------------------- | ------------------------- | 1869| Promise<void> | 无返回结果的Promise对象。 | 1870 1871**错误码：** 1872 1873以下错误码的详细介绍请参见[用户首选项错误码](errorcode-preferences.md)。 1874 1875| 错误码ID | 错误信息 | 1876| -------- | ------------------------------ | 1877| 15500000 | Inner error. | 1878 1879**示例：** 1880 1881```ts 1882import { BusinessError } from '@kit.BasicServicesKit'; 1883 1884let promise = dataPreferences.flush(); 1885promise.then(() => { 1886 console.info("Succeeded in flushing."); 1887}).catch((err: BusinessError) => { 1888 console.error("Failed to flush. code =" + err.code + ", message =" + err.message); 1889}) 1890``` 1891 1892### flushSync<sup>14+</sup> 1893 1894flushSync(): void 1895 1896将缓存的Preferences实例中的数据存储到用户首选项的持久化文件中。 1897 1898 > **说明：** 1899 > 1900 > 当数据未修改或修改后的数据与缓存数据一致时，不会刷新持久化文件。 1901 1902**原子化服务API：** 从API version 14开始，该接口支持在原子化服务中使用。 1903 1904**系统能力：** SystemCapability.DistributedDataManager.Preferences.Core 1905 1906**错误码：** 1907 1908以下错误码的详细介绍请参见[用户首选项错误码](errorcode-preferences.md)。 1909 1910| 错误码ID | 错误信息 | 1911| -------- | ------------------------------ | 1912| 15500000 | Inner error. | 1913 1914**示例：** 1915 1916```ts 1917dataPreferences.flushSync(); 1918``` 1919 1920### clear 1921 1922clear(callback: AsyncCallback<void>): void 1923 1924清除缓存的Preferences实例中的所有数据，可通过[flush](#flush)将Preferences实例持久化，使用callback异步回调。 1925 1926**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1927 1928**系统能力：** SystemCapability.DistributedDataManager.Preferences.Core 1929 1930**参数：** 1931 1932| 参数名 | 类型 | 必填 | 说明 | 1933| -------- | ------------------------- | ---- | ---------------------------------------------------- | 1934| callback | AsyncCallback<void> | 是 | 回调函数。当清除成功，err为undefined；否则为错误对象。 | 1935 1936**错误码：** 1937 1938以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[用户首选项错误码](errorcode-preferences.md)。 1939 1940| 错误码ID | 错误信息 | 1941| -------- | ------------------------------ | 1942| 401 | Parameter error. Mandatory parameters are left unspecified. | 1943| 15500000 | Inner error. | 1944 1945**示例：** 1946 1947```ts 1948import { BusinessError } from '@kit.BasicServicesKit'; 1949 1950dataPreferences.clear((err: BusinessError) =>{ 1951 if (err) { 1952 console.error("Failed to clear. code =" + err.code + ", message =" + err.message); 1953 return; 1954 } 1955 console.info("Succeeded in clearing."); 1956}) 1957``` 1958 1959 1960### clear 1961 1962clear(): Promise<void> 1963 1964清除缓存的Preferences实例中的所有数据，可通过[flush](#flush)将Preferences实例持久化，使用Promise异步回调。 1965 1966**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1967 1968**系统能力：** SystemCapability.DistributedDataManager.Preferences.Core 1969 1970**返回值：** 1971 1972| 类型 | 说明 | 1973| ------------------- | ------------------------- | 1974| Promise<void> | 无返回结果的Promise对象。 | 1975 1976**错误码：** 1977 1978以下错误码的详细介绍请参见[用户首选项错误码](errorcode-preferences.md)。 1979 1980| 错误码ID | 错误信息 | 1981| -------- | ------------------------------ | 1982| 15500000 | Inner error. | 1983 1984**示例：** 1985 1986```ts 1987import { BusinessError } from '@kit.BasicServicesKit'; 1988 1989let promise = dataPreferences.clear(); 1990promise.then(() => { 1991 console.info("Succeeded in clearing."); 1992}).catch((err: BusinessError) => { 1993 console.error("Failed to clear. code =" + err.code + ", message =" + err.message); 1994}) 1995``` 1996 1997 1998### clearSync<sup>10+</sup> 1999 2000clearSync(): void 2001 2002清除缓存的Preferences实例中的所有数据，可通过[flush](#flush)将Preferences实例持久化，此为同步接口。 2003 2004**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 2005 2006**系统能力：** SystemCapability.DistributedDataManager.Preferences.Core 2007 2008**示例：** 2009 2010```ts 2011dataPreferences.clearSync(); 2012``` 2013 2014 2015### on('change') 2016 2017on(type: 'change', callback: Callback<string>): void 2018 2019订阅数据变更，订阅的Key的值发生变更后，在执行[flush](#flush)方法后，触发callback回调。 2020 2021 > **说明：** 2022 > 2023 > 当调用[removePreferencesFromCache](#preferencesremovepreferencesfromcache)或者[deletePreferences](#preferencesdeletepreferences)后，订阅的数据变更会主动取消订阅，在重新[getPreferences](#preferencesgetpreferences)后需要重新订阅数据变更。 2024 2025**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 2026 2027**系统能力：** SystemCapability.DistributedDataManager.Preferences.Core 2028 2029**参数：** 2030 2031| 参数名 | 类型 | 必填 | 说明 | 2032| -------- | -------- | ---- | ---------------------------------------- | 2033| type | string | 是 | 事件类型，固定值'change'，表示数据变更。 | 2034| callback | Callback<string> | 是 | 回调函数。 | 2035 2036**错误码：** 2037 2038以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[用户首选项错误码](errorcode-preferences.md)。 2039 2040| 错误码ID | 错误信息 | 2041| -------- | ------------------------------ | 2042| 401 | Parameter error. Possible causes:<br>1. Mandatory parameters are left unspecified;<br>2. Incorrect parameter types;<br>3. Parameter verification failed. | 2043| 15500000 | Inner error. | 2044 2045**示例：** 2046 2047```ts 2048import { BusinessError } from '@kit.BasicServicesKit'; 2049 2050let observer = (key: string) => { 2051 console.info("The key " + key + " changed."); 2052} 2053dataPreferences.on('change', observer); 2054dataPreferences.putSync('startup', 'manual'); 2055dataPreferences.flush((err: BusinessError) => { 2056 if (err) { 2057 console.error("Failed to flush. Cause: " + err); 2058 return; 2059 } 2060 console.info("Succeeded in flushing."); 2061}) 2062``` 2063 2064### on('multiProcessChange')<sup>10+</sup> 2065 2066on(type: 'multiProcessChange', callback: Callback<string>): void 2067 2068订阅进程间数据变更，多个进程持有同一个首选项文件时，在任意一个进程（包括本进程）执行[flush](#flush)方法，持久化文件发生变更后，触发callback回调。 2069 2070本接口提供给申请了[dataGroupId](#options10)的应用进行使用，未申请的应用不推荐使用，多进程操作可能会损坏持久化文件，导致数据丢失。 2071 2072 > **说明：** 2073 > 2074 > 同一持久化文件在当前进程订阅进程间数据变更的最大数量为50次，超过最大限制后会订阅失败。建议在触发callback回调后及时取消订阅。 2075 > 2076 > 当调用[removePreferencesFromCache](#preferencesremovepreferencesfromcache)或者[deletePreferences](#preferencesdeletepreferences)后，订阅的数据变更会主动取消订阅，在重新[getPreferences](#preferencesgetpreferences)后需要重新订阅数据变更。 2077 2078**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 2079 2080**系统能力：** SystemCapability.DistributedDataManager.Preferences.Core 2081 2082**参数：** 2083 2084| 参数名 | 类型 | 必填 | 说明 | 2085| -------- | -------- | ---- | ------------------------------------------------------------ | 2086| type | string | 是 | 事件类型，固定值'multiProcessChange'，表示多进程间的数据变更。 | 2087| callback | Callback<string> | 是 | 回调函数。 | 2088 2089**错误码：** 2090 2091以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[用户首选项错误码](errorcode-preferences.md)。 2092 2093| 错误码ID | 错误信息 | 2094| -------- | -------------------------------------- | 2095| 401 | Parameter error. Possible causes:<br>1. Mandatory parameters are left unspecified;<br>2. Incorrect parameter types;<br>3. Parameter verification failed. | 2096| 15500000 | Inner error. | 2097| 15500019 | Failed to obtain the subscription service. | 2098 2099**示例：** 2100 2101```ts 2102import { BusinessError } from '@kit.BasicServicesKit'; 2103 2104let observer = (key: string) => { 2105 console.info("The key " + key + " changed."); 2106} 2107dataPreferences.on('multiProcessChange', observer); 2108dataPreferences.putSync('startup', 'manual'); 2109dataPreferences.flush((err: BusinessError) => { 2110 if (err) { 2111 console.error("Failed to flush. Cause: " + err); 2112 return; 2113 } 2114 console.info("Succeeded in flushing."); 2115}) 2116``` 2117 2118### on('dataChange')<sup>12+</sup> 2119 2120on(type: 'dataChange', keys: Array<string>, callback: Callback<Record<string, ValueType>>): void 2121 2122精确订阅数据变更，只有被订阅的key值发生变更后，在执行[flush](#flush)方法后，触发callback回调。 2123 2124 > **说明：** 2125 > 2126 > 当调用[removePreferencesFromCache](#preferencesremovepreferencesfromcache)或者[deletePreferences](#preferencesdeletepreferences)后，订阅的数据变更会主动取消订阅，在重新[getPreferences](#preferencesgetpreferences)后需要重新订阅数据变更。 2127 2128**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 2129 2130**系统能力：** SystemCapability.DistributedDataManager.Preferences.Core 2131 2132**参数：** 2133 2134| 参数名 | 类型 | 必填 | 说明 | 2135| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 2136| type | string | 是 | 事件类型，固定值'dataChange'，表示精确的数据变更。 | 2137| keys | Array<string> | 是 | 需要订阅的key集合。 | 2138| callback | Callback<Record<string, [ValueType](#valuetype)>> | 是 | 回调函数。回调支持返回多个键值对，其中键为发生变更的订阅key，值为变更后的数据：支持number、string、boolean、Array\<number>、Array\<string>、Array\<boolean>、Uint8Array、object类型。 | 2139 2140**错误码：** 2141 2142以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[用户首选项错误码](errorcode-preferences.md)。 2143 2144| 错误码ID | 错误信息 | 2145| -------- | ------------------------------ | 2146| 401 | Parameter error. Possible causes:<br>1. Mandatory parameters are left unspecified;<br>2. Incorrect parameter types;<br>3. Parameter verification failed. | 2147| 15500000 | Inner error. | 2148 2149**示例：** 2150 2151```ts 2152import { BusinessError } from '@kit.BasicServicesKit'; 2153 2154let observer = (data: Record<string, preferences.ValueType>) => { 2155 for (const keyValue of Object.entries(data)) { 2156 console.info(`observer : ${keyValue}`) 2157 } 2158 console.info("The observer called.") 2159} 2160let keys = ['name', 'age'] 2161dataPreferences.on('dataChange', keys, observer); 2162dataPreferences.putSync('name', 'xiaohong'); 2163dataPreferences.putSync('weight', 125); 2164dataPreferences.flush((err: BusinessError) => { 2165 if (err) { 2166 console.error("Failed to flush. Cause: " + err); 2167 return; 2168 } 2169 console.info("Succeeded in flushing."); 2170}) 2171``` 2172 2173### off('change') 2174 2175off(type: 'change', callback?: Callback<string>): void 2176 2177取消订阅数据变更。 2178 2179**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 2180 2181**系统能力：** SystemCapability.DistributedDataManager.Preferences.Core 2182 2183**参数：** 2184 2185| 参数名 | 类型 | 必填 | 说明 | 2186| -------- | -------- | ---- | ------------------------------------------------------------ | 2187| type | string | 是 | 事件类型，固定值'change'，表示数据变更。 | 2188| callback | Callback<string> | 否 | 需要取消的回调函数，不填写则全部取消。 | 2189 2190**错误码：** 2191 2192以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[用户首选项错误码](errorcode-preferences.md)。 2193 2194| 错误码ID | 错误信息 | 2195| -------- | ------------------------------ | 2196| 401 | Parameter error. Possible causes:<br>1. Mandatory parameters are left unspecified;<br>2. Incorrect parameter types;<br>3. Parameter verification failed. | 2197| 15500000 | Inner error. | 2198 2199**示例：** 2200 2201```ts 2202import { BusinessError } from '@kit.BasicServicesKit'; 2203 2204let observer = (key: string) => { 2205 console.info("The key " + key + " changed."); 2206} 2207dataPreferences.on('change', observer); 2208dataPreferences.putSync('startup', 'auto'); 2209dataPreferences.flush((err: BusinessError) => { 2210 if (err) { 2211 console.error("Failed to flush. Cause: " + err); 2212 return; 2213 } 2214 console.info("Succeeded in flushing."); 2215}) 2216dataPreferences.off('change', observer); 2217``` 2218 2219### off('multiProcessChange')<sup>10+</sup> 2220 2221off(type: 'multiProcessChange', callback?: Callback<string>): void 2222 2223取消订阅进程间数据变更。 2224 2225本接口提供给申请了[dataGroupId](#options10)的应用进行使用，未申请的应用不推荐使用，多进程操作可能会损坏持久化文件，导致数据丢失。 2226 2227**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 2228 2229**系统能力：** SystemCapability.DistributedDataManager.Preferences.Core 2230 2231**参数：** 2232 2233| 参数名 | 类型 | 必填 | 说明 | 2234| -------- | -------- | ---- | ------------------------------------------------------------ | 2235| type | string | 是 | 事件类型，固定值'multiProcessChange'，表示多进程间的数据变更。 | 2236| callback | Callback<string> | 否 | 需要取消的回调函数，不填写则全部取消。 | 2237 2238**错误码：** 2239 2240以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[用户首选项错误码](errorcode-preferences.md)。 2241 2242| 错误码ID | 错误信息 | 2243| -------- | ------------------------------ | 2244| 401 | Parameter error. Possible causes:<br>1. Mandatory parameters are left unspecified;<br>2. Incorrect parameter types;<br>3. Parameter verification failed. | 2245| 15500000 | Inner error. | 2246 2247**示例：** 2248 2249```ts 2250import { BusinessError } from '@kit.BasicServicesKit'; 2251 2252let observer = (key: string) => { 2253 console.info("The key " + key + " changed."); 2254} 2255dataPreferences.on('multiProcessChange', observer); 2256dataPreferences.putSync('startup', 'auto'); 2257dataPreferences.flush((err: BusinessError) => { 2258 if (err) { 2259 console.error("Failed to flush. Cause: " + err); 2260 return; 2261 } 2262 console.info("Succeeded in flushing."); 2263}) 2264dataPreferences.off('multiProcessChange', observer); 2265``` 2266### off('dataChange')<sup>12+</sup> 2267 2268off(type: 'dataChange', keys: Array<string>, callback?: Callback<Record<string, ValueType>>): void 2269 2270取消精确订阅数据变更。 2271 2272**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 2273 2274**系统能力：** SystemCapability.DistributedDataManager.Preferences.Core 2275 2276**参数：** 2277 2278| 参数名 | 类型 | 必填 | 说明 | 2279| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 2280| type | string | 是 | 事件类型，固定值'dataChange'，表示精确的数据变更。 | 2281| keys | Array<string> | 是 | 需要取消订阅的key集合，当keys为空数组时，表示取消订阅全部key；当keys为非空数组时，表示只取消订阅key集合中的key。 | 2282| callback | Callback<Record<string, [ValueType](#valuetype)>> | 否 | 需要取消的回调函数，若callback不填写，表示所有的callback都需要处理；若callback填写，表示只处理该callback。 | 2283 2284**错误码：** 2285 2286以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[用户首选项错误码](errorcode-preferences.md)。 2287 2288| 错误码ID | 错误信息 | 2289| -------- | ------------------------------ | 2290| 401 | Parameter error. Possible causes:<br>1. Mandatory parameters are left unspecified;<br>2. Incorrect parameter types;<br>3. Parameter verification failed. | 2291| 15500000 | Inner error. | 2292 2293**示例：** 2294 2295```ts 2296import { BusinessError } from '@kit.BasicServicesKit'; 2297 2298let observer = (data: Record<string, preferences.ValueType>) => { 2299 for (const keyValue of Object.entries(data)) { 2300 console.info(`observer : ${keyValue}`) 2301 } 2302 console.info("The observer called.") 2303} 2304let keys = ['name', 'age'] 2305dataPreferences.on('dataChange', keys, observer); 2306dataPreferences.putSync('name', 'xiaohong'); 2307dataPreferences.putSync('weight', 125); 2308dataPreferences.flush((err: BusinessError) => { 2309 if (err) { 2310 console.error("Failed to flush. Cause: " + err); 2311 return; 2312 } 2313 console.info("Succeeded in flushing."); 2314}) 2315dataPreferences.off('dataChange', keys, observer); 2316``` 2317 2318## ValueType 2319 2320type ValueType = number | string | boolean | Array\<number> | Array\<string> | Array\<boolean> | Uint8Array | object | bigint 2321 2322用于表示允许的数据字段类型。 2323 2324**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 2325 2326**系统能力：** SystemCapability.DistributedDataManager.Preferences.Core 2327 2328| 类型 | 说明 | 2329|--------------------------|-------------------| 2330| number | 表示值类型为数字。 | 2331| string | 表示值类型为字符串。 | 2332| boolean | 表示值类型为布尔值。 | 2333| Array\<number> | 表示值类型为数字类型的数组。 | 2334| Array\<boolean> | 表示值类型为布尔类型的数组。 | 2335| Array\<string> | 表示值类型为字符串类型的数组。 | 2336| Uint8Array<sup>11+</sup> | 表示值类型为8位无符号整型的数组。 | 2337| object<sup>12+</sup> | 表示值类型为对象。 | 2338| bigint<sup>12+</sup> | 表示值类型为任意精度格式的整数。 | 2339