鸿蒙NEXT开发：ArkData数据管理-@ohos.data.preferences (用户首选项) ...

万有斥力  论坛元老 | 2025-3-22 20:36:10 | 显示全部楼层 | 阅读模式
打印 上一主题 下一主题
楼主

主题 1660|帖子 1660|积分 4980

 往期鸿蒙5.0全套实战文章必看：（文中附带全栈鸿蒙5.0学习资料）



  • 鸿蒙开发核心知识点，看这篇文章就够了
  • 最新版！鸿蒙HarmonyOS Next应用开发实战学习路线
  • 鸿蒙HarmonyOS NEXT开发技术最全学习路线指南
  • 鸿蒙应用开发实战项目，看这一篇文章就够了（部分项目附源码）
@ohos.data.preferences (用户首选项)

用户首选项为应用提供Key-Value键值型的数据处理能力，支持应用长期化轻量级数据，并对其修改和查询。
数据存储形式为键值对，键的类型为字符串型，值的存储数据类型包罗数字型、字符型、布尔型以及这3种类型的数组类型。
用户首选项的长期化文件存储在preferencesDir路径下，创建preferences对象前，需要保证preferencesDir路径可读写。
   阐明
  本模块首批接口从API version 9开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。
  首选项无法保证进程并发安全，会有文件损坏和数据丢失的风险，不支持在多进程场景下使用。
  导入模块

  1. import { preferences } from '@kit.ArkData';
复制代码
常量

元服务API： 从API version 11开始，该接口支持在元服务中使用。
体系能力： SystemCapability.DistributedDataManager.Preferences.Core
名称参数类型可读可写阐明MAX_KEY_LENGTHnumber是否Key的最大长度限制为1024个字节。MAX_VALUE_LENGTHnumber是否Value的最大长度限制为16MB。 preferences.getPreferences

getPreferences(context: Context, name: string, callback: AsyncCallback<references>): void
获取Preferences实例，使用callback异步回调。
元服务API： 从API version 11开始，该接口支持在元服务中使用。
体系能力： SystemCapability.DistributedDataManager.Preferences.Core
参数：
参数名类型必填阐明contextContext是 应用上下文。
FA模子的应用Context界说见Context。
Stage模子的应用Context界说见Context。
namestring是Preferences实例的名称。callbackAsyncCallback<references>是回调函数。当获取Preferences实例乐成，err为undefined，返回Preferences实例；否则err为错误对象。 错误码：
以下错误码的具体先容。
错误码ID错误信息401 Parameter error. Possible causes:
1. Mandatory parameters are left unspecified;
2. Incorrect parameter types;
3. Parameter verification failed.
15500000Inner error. 示例：
FA模子示例：
  1. import { featureAbility } from '@kit.AbilityKit';
  2. import { BusinessError } from '@kit.BasicServicesKit';
  4. let context = featureAbility.getContext();
  5. let dataPreferences: preferences.Preferences | null = null;
  7. preferences.getPreferences(context, 'myStore', (err: BusinessError, val: preferences.Preferences) => {
  8.   if (err) {
  9.     console.error("Failed to get preferences. code =" + err.code + ", message =" + err.message);
  10.     return;
  11.   }
  12.   dataPreferences = val;
  13.   console.info("Succeeded in getting preferences.");
  14. })
复制代码
Stage模子示例：
  1. import { UIAbility } from '@kit.AbilityKit';
  2. import { BusinessError } from '@kit.BasicServicesKit';
  3. import { window } from '@kit.ArkUI';
  5. let dataPreferences: preferences.Preferences | null = null;
  7. class EntryAbility extends UIAbility {
  8.   onWindowStageCreate(windowStage: window.WindowStage) {
  9.     preferences.getPreferences(this.context, 'myStore', (err: BusinessError, val: preferences.Preferences) => {
  10.       if (err) {
  11.         console.error("Failed to get preferences. code =" + err.code + ", message =" + err.message);
  12.         return;
  13.       }
  14.       dataPreferences = val;
  15.       console.info("Succeeded in getting preferences.");
  16.     })
  17.   }
  18. }
复制代码
preferences.getPreferences

getPreferences(context: Context, name: string): Promise<references>
获取Preferences实例，使用Promise异步回调。
元服务API： 从API version 11开始，该接口支持在元服务中使用。
体系能力： SystemCapability.DistributedDataManager.Preferences.Core
参数：
参数名类型必填阐明contextContext是 应用上下文。
FA模子的应用Context界说见Context。
Stage模子的应用Context界说见Context。
namestring是Preferences实例的名称。 返回值：
类型阐明Promise<references>Promise对象，返回Preferences实例。 错误码：
以下错误码的具体先容。
错误码ID错误信息401 Parameter error. Possible causes:
1. Mandatory parameters are left unspecified;
2. Incorrect parameter types;
3. Parameter verification failed.
15500000Inner error. 示例：
FA模子示例：
  1. // 获取context
  2. import { featureAbility } from '@kit.AbilityKit';
  3. import { BusinessError } from '@kit.BasicServicesKit';
  5. let context = featureAbility.getContext();
  7. let dataPreferences: preferences.Preferences | null = null;
  8. let promise = preferences.getPreferences(context, 'myStore');
  9. promise.then((object: preferences.Preferences) => {
  10.   dataPreferences = object;
  11.   console.info("Succeeded in getting preferences.");
  12. }).catch((err: BusinessError) => {
  13.   console.error("Failed to get preferences. code =" + err.code + ", message =" + err.message);
  14. })
复制代码
Stage模子示例：
  1. import { UIAbility } from '@kit.AbilityKit';
  2. import { BusinessError } from '@kit.BasicServicesKit';
  3. import { window } from '@kit.ArkUI';
  5. let dataPreferences: preferences.Preferences | null = null;
  7. class EntryAbility extends UIAbility {
  8.   onWindowStageCreate(windowStage: window.WindowStage) {
  9.     let promise = preferences.getPreferences(this.context, 'myStore');
  10.     promise.then((object: preferences.Preferences) => {
  11.       dataPreferences = object;
  12.       console.info("Succeeded in getting preferences.");
  13.     }).catch((err: BusinessError) => {
  14.       console.error("Failed to get preferences. code =" + err.code + ", message =" + err.message);
  15.     })
  16.   }
  17. }
复制代码
preferences.getPreferences10+

getPreferences(context: Context, options: Options, callback: AsyncCallback<references>): void
获取Preferences实例，使用callback异步回调。
元服务API： 从API version 11开始，该接口支持在元服务中使用。
体系能力： SystemCapability.DistributedDataManager.Preferences.Core
参数：
参数名类型必填阐明contextContext是 应用上下文。
FA模子的应用Context界说见Context。
Stage模子的应用Context界说见Context。
optionsOptions是与Preferences实例相关的配置选项。callbackAsyncCallback<references>是回调函数。当获取Preferences实例乐成，err为undefined，返回Preferences实例；否则err为错误对象。 错误码：
以下错误码的具体先容。
错误码ID错误信息401 Parameter error. Possible causes:
1. Mandatory parameters are left unspecified;
2. Incorrect parameter types;
3. Parameter verification failed.
801Capability not supported.15500000Inner error.15501001The operations is supported in stage mode only.15501002Invalid dataGroupId. 示例：
FA模子示例：
  1. // 获取context
  2. import { featureAbility } from '@kit.AbilityKit';
  3. import { BusinessError } from '@kit.BasicServicesKit';
  5. let context = featureAbility.getContext();
  6. let dataPreferences: preferences.Preferences | null = null;
  8. let options: preferences.Options = { name: 'myStore' };
  9. preferences.getPreferences(context, options, (err: BusinessError, val: preferences.Preferences) => {
  10.   if (err) {
  11.     console.error("Failed to get preferences. code =" + err.code + ", message =" + err.message);
  12.     return;
  13.   }
  14.   dataPreferences = val;
  15.   console.info("Succeeded in getting preferences.");
  16. })
复制代码
Stage模子示例：
  1. import { UIAbility } from '@kit.AbilityKit';
  2. import { BusinessError } from '@kit.BasicServicesKit';
  3. import { window } from '@kit.ArkUI';
  5. let dataPreferences: preferences.Preferences | null = null;
  7. class EntryAbility extends UIAbility {
  8.   onWindowStageCreate(windowStage: window.WindowStage) {
  9.     let options: preferences.Options = { name: 'myStore' };
  10.     preferences.getPreferences(this.context, options, (err: BusinessError, val: preferences.Preferences) => {
  11.       if (err) {
  12.         console.error("Failed to get preferences. code =" + err.code + ", message =" + err.message);
  13.         return;
  14.       }
  15.       dataPreferences = val;
  16.       console.info("Succeeded in getting preferences.");
  17.     })
  18.   }
  19. }
复制代码
preferences.getPreferences10+

getPreferences(context: Context, options: Options): Promise<references>
获取Preferences实例，使用Promise异步回调。
元服务API： 从API version 11开始，该接口支持在元服务中使用。
体系能力： SystemCapability.DistributedDataManager.Preferences.Core
参数：
参数名类型必填阐明contextContext是 应用上下文。
FA模子的应用Context界说见Context。
Stage模子的应用Context界说见Context。
optionsOptions是与Preferences实例相关的配置选项。 返回值：
类型阐明Promise<references>Promise对象，返回Preferences实例。 错误码：
以下错误码的具体先容。
错误码ID错误信息401 Parameter error. Possible causes:
1. Mandatory parameters are left unspecified;
2. Incorrect parameter types;
3. Parameter verification failed.
801Capability not supported.15500000Inner error.15501001The operations is supported in stage mode only.15501002Invalid dataGroupId. 示例：
FA模子示例：
  1. // 获取context
  2. import { featureAbility } from '@kit.AbilityKit';
  3. import { BusinessError } from '@kit.BasicServicesKit';
  5. let context = featureAbility.getContext();
  7. let dataPreferences: preferences.Preferences | null = null;
  8. let options: preferences.Options = { name: 'myStore' };
  9. let promise = preferences.getPreferences(context, options);
  10. promise.then((object: preferences.Preferences) => {
  11.   dataPreferences = object;
  12.   console.info("Succeeded in getting preferences.");
  13. }).catch((err: BusinessError) => {
  14.   console.error("Failed to get preferences. code =" + err.code + ", message =" + err.message);
  15. })
复制代码
Stage模子示例：
  1. import { UIAbility } from '@kit.AbilityKit';
  2. import { BusinessError } from '@kit.BasicServicesKit';
  3. import { window } from '@kit.ArkUI';
  5. let dataPreferences: preferences.Preferences | null = null;
  7. class EntryAbility extends UIAbility {
  8.   onWindowStageCreate(windowStage: window.WindowStage) {
  9.     let options: preferences.Options = { name: 'myStore' };
  10.     let promise = preferences.getPreferences(this.context, options);
  11.     promise.then((object: preferences.Preferences) => {
  12.       dataPreferences = object;
  13.       console.info("Succeeded in getting preferences.");
  14.     }).catch((err: BusinessError) => {
  15.       console.error("Failed to get preferences. code =" + err.code + ", message =" + err.message);
  16.     })
  17.   }
  18. }
复制代码
preferences.getPreferencesSync10+

getPreferencesSync(context: Context, options: Options): Preferences
获取Preferences实例，此为同步接口。
元服务API： 从API version 11开始，该接口支持在元服务中使用。
体系能力： SystemCapability.DistributedDataManager.Preferences.Core
参数：
参数名类型必填阐明contextContext是 应用上下文。
FA模子的应用Context界说见Context。
Stage模子的应用Context界说见Context。
optionsOptions是与Preferences实例相关的配置选项。 返回值：
类型阐明Preferences返回Preferences实例。 错误码：
以下错误码的具体先容。
错误码ID错误信息401 Parameter error. Possible causes:
1. Mandatory parameters are left unspecified;
2. Incorrect parameter types;
3. Parameter verification failed.
801Capability not supported.15500000Inner error.15501001The operations is supported in stage mode only.15501002Invalid dataGroupId. 示例：
FA模子示例：
  1. // 获取context
  2. import { featureAbility } from '@kit.AbilityKit';
  4. let context = featureAbility.getContext();
  5. let dataPreferences: preferences.Preferences | null = null;
  7. let options: preferences.Options = { name: 'myStore' };
  8. dataPreferences = preferences.getPreferencesSync(context, options);
复制代码
Stage模子示例：
  1. import { UIAbility } from '@kit.AbilityKit';
  2. import { window } from '@kit.ArkUI';
  4. let dataPreferences: preferences.Preferences | null = null;
  6. class EntryAbility extends UIAbility {
  7.   onWindowStageCreate(windowStage: window.WindowStage) {
  8.     let options: preferences.Options = { name: 'myStore' };
  9.     dataPreferences = preferences.getPreferencesSync(this.context, options);
  10.   }
  11. }
复制代码
preferences.deletePreferences

deletePreferences(context: Context, name: string, callback: AsyncCallback<void>): void
从缓存中移出指定的Preferences实例，若Preferences实例有对应的长期化文件，则同时删除其长期化文件。使用callback异步回调。
调用该接口后，不发起再使用旧的Preferences实例举行数据利用，否则会出现数据同等性题目，应将Preferences实例置为null，体系将会同一回收。
不支持该接口与preference其他接口并发调用。
元服务API： 从API version 11开始，该接口支持在元服务中使用。
体系能力： SystemCapability.DistributedDataManager.Preferences.Core
参数：
参数名类型必填阐明contextContext是 应用上下文。
FA模子的应用Context界说见Context。
Stage模子的应用Context界说见Context。
namestring是Preferences实例的名称。callbackAsyncCallback<void>是回调函数。当移除乐成，err为undefined，否则为错误对象。 错误码：
以下错误码的具体先容。
错误码ID错误信息401 Parameter error. Possible causes:
1. Mandatory parameters are left unspecified;
2. Incorrect parameter types;
3. Parameter verification failed.
15500000Inner error.15500010Failed to delete the user preferences persistence file. 示例：
FA模子示例：
  1. // 获取context
  2. import { featureAbility } from '@kit.AbilityKit';
  3. import { BusinessError } from '@kit.BasicServicesKit';
  5. let context = featureAbility.getContext();
  7. preferences.deletePreferences(context, 'myStore', (err: BusinessError) => {
  8.   if (err) {
  9.     console.error("Failed to delete preferences. code =" + err.code + ", message =" + err.message);
  10.     return;
  11.   }
  12.   console.info("Succeeded in deleting preferences.");
  13. })
复制代码
Stage模子示例：
  1. import { UIAbility } from '@kit.AbilityKit';
  2. import { BusinessError } from '@kit.BasicServicesKit';
  3. import { window } from '@kit.ArkUI';
  5. class EntryAbility extends UIAbility {
  6.   onWindowStageCreate(windowStage: window.WindowStage) {
  7.     preferences.deletePreferences(this.context, 'myStore', (err: BusinessError) => {
  8.       if (err) {
  9.         console.error("Failed to delete preferences. code =" + err.code + ", message =" + err.message);
  10.         return;
  11.       }
  12.       console.info("Succeeded in deleting preferences.");
  13.     })
  14.   }
  15. }
复制代码
preferences.deletePreferences

deletePreferences(context: Context, name: string): Promise<void>
从缓存中移出指定的Preferences实例，若Preferences实例有对应的长期化文件，则同时删除其长期化文件。使用Promise异步回调。
调用该接口后，不发起再使用旧的Preferences实例举行数据利用，否则会出现数据同等性题目，应将Preferences实例置为null，体系将会同一回收。
不支持该接口与preference其他接口并发调用。
元服务API： 从API version 11开始，该接口支持在元服务中使用。
体系能力： SystemCapability.DistributedDataManager.Preferences.Core
参数：
参数名类型必填阐明contextContext是 应用上下文。
FA模子的应用Context界说见Context。
Stage模子的应用Context界说见Context。
namestring是Preferences实例的名称。 返回值：
类型阐明Promise<void>无返回结果的Promise对象。 错误码：
以下错误码的具体先容。
错误码ID错误信息401 Parameter error. Possible causes:
1. Mandatory parameters are left unspecified;
2. Incorrect parameter types;
3. Parameter verification failed.
15500000Inner error.15500010Failed to delete the user preferences persistence file. 示例：
FA模子示例：
  1. // 获取context
  2. import { featureAbility } from '@kit.AbilityKit';
  3. import { BusinessError } from '@kit.BasicServicesKit';
  5. let context = featureAbility.getContext();
  7. let promise = preferences.deletePreferences(context, 'myStore');
  8. promise.then(() => {
  9.   console.info("Succeeded in deleting preferences.");
  10. }).catch((err: BusinessError) => {
  11.   console.error("Failed to delete preferences. code =" + err.code + ", message =" + err.message);
  12. })
复制代码
Stage模子示例：
  1. import { UIAbility } from '@kit.AbilityKit';
  2. import { BusinessError } from '@kit.BasicServicesKit';
  3. import { window } from '@kit.ArkUI';
  5. class EntryAbility extends UIAbility {
  6.   onWindowStageCreate(windowStage: window.WindowStage) {
  7.     let promise = preferences.deletePreferences(this.context, 'myStore');
  8.     promise.then(() => {
  9.       console.info("Succeeded in deleting preferences.");
  10.     }).catch((err: BusinessError) => {
  11.       console.error("Failed to delete preferences. code =" + err.code + ", message =" + err.message);
  12.     })
  13.   }
  14. }
复制代码
preferences.deletePreferences10+

deletePreferences(context: Context, options: Options, callback: AsyncCallback<void>): void
从缓存中移出指定的Preferences实例，若Preferences实例有对应的长期化文件，则同时删除其长期化文件。使用callback异步回调。
调用该接口后，不发起再使用旧的Preferences实例举行数据利用，否则会出现数据同等性题目，应将Preferences实例置为null，体系将会同一回收。
不支持该接口与preference其他接口并发调用。
元服务API： 从API version 11开始，该接口支持在元服务中使用。
体系能力： SystemCapability.DistributedDataManager.Preferences.Core
参数：
参数名类型必填阐明contextContext是 应用上下文。
FA模子的应用Context界说见Context。
Stage模子的应用Context界说见Context。
optionsOptions是与Preferences实例相关的配置选项。callbackAsyncCallback<void>是回调函数。当移除乐成，err为undefined，否则为错误对象。 错误码：
以下错误码的具体先容。
错误码ID错误信息401 Parameter error. Possible causes:
1. Mandatory parameters are left unspecified;
2. Incorrect parameter types;
3. Parameter verification failed.
801Capability not supported.15500000Inner error.15500010Failed to delete the user preferences persistence file.15501001The operations is supported in stage mode only.15501002Invalid dataGroupId. 示例：
FA模子示例：
  1. // 获取context
  2. import { featureAbility } from '@kit.AbilityKit';
  3. import { BusinessError } from '@kit.BasicServicesKit';
  5. let context = featureAbility.getContext();
  7. let options: preferences.Options = { name: 'myStore' };
  8. preferences.deletePreferences(context, options, (err: BusinessError) => {
  9.   if (err) {
  10.     console.error("Failed to delete preferences. code =" + err.code + ", message =" + err.message);
  11.     return;
  12.   }
  13.   console.info("Succeeded in deleting preferences.");
  14. })
复制代码
Stage模子示例：
  1. import { UIAbility } from '@kit.AbilityKit';
  2. import { BusinessError } from '@kit.BasicServicesKit';
  3. import { window } from '@kit.ArkUI';
  5. class EntryAbility extends UIAbility {
  6.   onWindowStageCreate(windowStage: window.WindowStage) {
  7.     let options: preferences.Options = { name: 'myStore' };
  8.     preferences.deletePreferences(this.context, options, (err: BusinessError) => {
  9.       if (err) {
  10.         console.error("Failed to delete preferences. code =" + err.code + ", message =" + err.message);
  11.         return;
  12.       }
  13.       console.info("Succeeded in deleting preferences.");
  14.     })
  15.   }
  16. }
复制代码
preferences.deletePreferences10+

deletePreferences(context: Context, options: Options): Promise<void>
从缓存中移出指定的Preferences实例，若Preferences实例有对应的长期化文件，则同时删除其长期化文件。使用Promise异步回调。
调用该接口后，不发起再使用旧的Preferences实例举行数据利用，否则会出现数据同等性题目，应将Preferences实例置为null，体系将会同一回收。
不支持该接口与preference其他接口并发调用。
元服务API： 从API version 11开始，该接口支持在元服务中使用。
体系能力： SystemCapability.DistributedDataManager.Preferences.Core
参数：
参数名类型必填阐明contextContext是 应用上下文。
FA模子的应用Context界说见Context。
Stage模子的应用Context界说见Context。
optionsOptions是与Preferences实例相关的配置选项。 返回值：
类型阐明Promise<void>无返回结果的Promise对象。 错误码：
以下错误码的具体先容。
错误码ID错误信息401 Parameter error. Possible causes:
1. Mandatory parameters are left unspecified;
2. Incorrect parameter types;
3. Parameter verification failed.
801Capability not supported.15500000Inner error.15500010Failed to delete the user preferences persistence file.15501001The operations is supported in stage mode only.15501002Invalid dataGroupId. 示例：
FA模子示例：
  1. // 获取context
  2. import { featureAbility } from '@kit.AbilityKit';
  3. import { BusinessError } from '@kit.BasicServicesKit';
  5. let context = featureAbility.getContext();
  7. let options: preferences.Options = { name: 'myStore' };
  8. let promise = preferences.deletePreferences(context, options);
  9. promise.then(() => {
  10.   console.info("Succeeded in deleting preferences.");
  11. }).catch((err: BusinessError) => {
  12.   console.error("Failed to delete preferences. code =" + err.code + ", message =" + err.message);
  13. })
复制代码
Stage模子示例：
  1. import { UIAbility } from '@kit.AbilityKit';
  2. import { BusinessError } from '@kit.BasicServicesKit';
  3. import { window } from '@kit.ArkUI';
  5. class EntryAbility extends UIAbility {
  6.   onWindowStageCreate(windowStage: window.WindowStage) {
  7.     let options: preferences.Options = { name: 'myStore' };
  8.     let promise = preferences.deletePreferences(this.context, options);
  9.     promise.then(() => {
  10.       console.info("Succeeded in deleting preferences.");
  11.     }).catch((err: BusinessError) => {
  12.       console.error("Failed to delete preferences. code =" + err.code + ", message =" + err.message);
  13.     })
  14.   }
  15. }
复制代码
preferences.removePreferencesFromCache

removePreferencesFromCache(context: Context, name: string, callback: AsyncCallback<void>): void
从缓存中移出指定的Preferences实例，使用callback异步回调。
应用初次调用getPreferences接口获取某个Preferences实例后，该实例会被会被缓存起来，后续再次getPreferences时不会再次从长期化文件中读取，直接从缓存中获取Preferences实例。调用此接口移出缓存中的实例之后，再次getPreferences将会重新读取长期化文件，天生新的Preferences实例。
调用该接口后，不发起再使用旧的Preferences实例举行数据利用，否则会出现数据同等性题目，应将Preferences实例置为null，体系将会同一回收。
元服务API： 从API version 11开始，该接口支持在元服务中使用。
体系能力： SystemCapability.DistributedDataManager.Preferences.Core
参数：
参数名类型必填阐明contextContext是 应用上下文。
FA模子的应用Context界说见Context。
Stage模子的应用Context界说见Context。
namestring是Preferences实例的名称。callbackAsyncCallback<void>是回调函数。当移除乐成，err为undefined，否则为错误对象。 错误码：
以下错误码的具体先容。
错误码ID错误信息401 Parameter error. Possible causes:
1. Mandatory parameters are left unspecified;
2. Incorrect parameter types;
3. Parameter verification failed.
15500000Inner error. 示例：
FA模子示例：
  1. // 获取context
  2. import { featureAbility } from '@kit.AbilityKit';
  3. import { BusinessError } from '@kit.BasicServicesKit';
  5. let context = featureAbility.getContext();
  6. preferences.removePreferencesFromCache(context, 'myStore', (err: BusinessError) => {
  7.   if (err) {
  8.     console.error("Failed to remove preferences. code =" + err.code + ", message =" + err.message);
  9.     return;
  10.   }
  11.   console.info("Succeeded in removing preferences.");
  12. })
复制代码
Stage模子示例：
  1. import { UIAbility } from '@kit.AbilityKit';
  2. import { BusinessError } from '@kit.BasicServicesKit';
  3. import { window } from '@kit.ArkUI';
  5. class EntryAbility extends UIAbility {
  6.   onWindowStageCreate(windowStage: window.WindowStage) {
  7.     preferences.removePreferencesFromCache(this.context, 'myStore', (err: BusinessError) => {
  8.       if (err) {
  9.         console.error("Failed to remove preferences. code =" + err.code + ", message =" + err.message);
  10.         return;
  11.       }
  12.       console.info("Succeeded in removing preferences.");
  13.     })
  14.   }
  15. }
复制代码
preferences.removePreferencesFromCache

removePreferencesFromCache(context: Context, name: string): Promise<void>
从缓存中移出指定的Preferences实例，使用Promise异步回调。
应用初次调用getPreferences接口获取某个Preferences实例后，该实例会被会被缓存起来，后续再次getPreferences时不会再次从长期化文件中读取，直接从缓存中获取Preferences实例。调用此接口移出缓存中的实例之后，再次getPreferences将会重新读取长期化文件，天生新的Preferences实例。
调用该接口后，不发起再使用旧的Preferences实例举行数据利用，否则会出现数据同等性题目，应将Preferences实例置为null，体系将会同一回收。
元服务API： 从API version 11开始，该接口支持在元服务中使用。
体系能力： SystemCapability.DistributedDataManager.Preferences.Core
参数：
参数名类型必填阐明contextContext是 应用上下文。
FA模子的应用Context界说见Context。
Stage模子的应用Context界说见Context。
namestring是Preferences实例的名称。 返回值：
类型阐明Promise<void>无返回结果的Promise对象。 错误码：
以下错误码的具体先容。
错误码ID错误信息401 Parameter error. Possible causes:
1. Mandatory parameters are left unspecified;
2. Incorrect parameter types;
3. Parameter verification failed.
15500000Inner error. 示例：
FA模子示例：
  1. // 获取context
  2. import { featureAbility } from '@kit.AbilityKit';
  3. import { BusinessError } from '@kit.BasicServicesKit';
  5. let context = featureAbility.getContext();
  6. let promise = preferences.removePreferencesFromCache(context, 'myStore');
  7. promise.then(() => {
  8.   console.info("Succeeded in removing preferences.");
  9. }).catch((err: BusinessError) => {
  10.   console.error("Failed to remove preferences. code =" + err.code + ", message =" + err.message);
  11. })
复制代码
Stage模子示例：
  1. import { UIAbility } from '@kit.AbilityKit';
  2. import { BusinessError } from '@kit.BasicServicesKit';
  3. import { window } from '@kit.ArkUI';
  5. class EntryAbility extends UIAbility {
  6.   onWindowStageCreate(windowStage: window.WindowStage) {
  7.     let promise = preferences.removePreferencesFromCache(this.context, 'myStore');
  8.     promise.then(() => {
  9.       console.info("Succeeded in removing preferences.");
  10.     }).catch((err: BusinessError) => {
  11.       console.error("Failed to remove preferences. code =" + err.code + ", message =" + err.message);
  12.     })
  13.   }
  14. }
复制代码
preferences.removePreferencesFromCacheSync10+

removePreferencesFromCacheSync(context: Context, name: string): void
从缓存中移出指定的Preferences实例，此为同步接口。
应用初次调用getPreferences接口获取某个Preferences实例后，该实例会被会被缓存起来，后续再次getPreferences时不会再次从长期化文件中读取，直接从缓存中获取Preferences实例。调用此接口移出缓存中的实例之后，再次getPreferences将会重新读取长期化文件，天生新的Preferences实例。
调用该接口后，不发起再使用旧的Preferences实例举行数据利用，否则会出现数据同等性题目，应将Preferences实例置为null，体系将会同一回收。
元服务API： 从API version 11开始，该接口支持在元服务中使用。
体系能力： SystemCapability.DistributedDataManager.Preferences.Core
参数：
参数名类型必填阐明contextContext是 应用上下文。
FA模子的应用Context界说见Context。
Stage模子的应用Context界说见Context。
namestring是Preferences实例的名称。 错误码：
以下错误码的具体先容。
错误码ID错误信息401 Parameter error. Possible causes:
1. Mandatory parameters are left unspecified;
2. Incorrect parameter types;
3. Parameter verification failed.
15500000Inner error. 示例：
FA模子示例：
  1. // 获取context
  2. import { featureAbility } from '@kit.AbilityKit';
  3. let context = featureAbility.getContext();
  4. preferences.removePreferencesFromCacheSync(context, 'myStore');
复制代码
Stage模子示例：
  1. import { UIAbility } from '@kit.AbilityKit';
  2. import { window } from '@kit.ArkUI';
  4. class EntryAbility extends UIAbility {
  5.   onWindowStageCreate(windowStage: window.WindowStage) {
  6.     preferences.removePreferencesFromCacheSync(this.context, 'myStore');
  7.   }
  8. }
复制代码
preferences.removePreferencesFromCache10+

removePreferencesFromCache(context: Context, options: Options, callback: AsyncCallback<void>): void
从缓存中移出指定的Preferences实例，使用callback异步回调。
应用初次调用getPreferences接口获取某个Preferences实例后，该实例会被会被缓存起来，后续再次getPreferences时不会再次从长期化文件中读取，直接从缓存中获取Preferences实例。调用此接口移出缓存中的实例之后，再次getPreferences将会重新读取长期化文件，天生新的Preferences实例。
调用该接口后，不发起再使用旧的Preferences实例举行数据利用，否则会出现数据同等性题目，应将Preferences实例置为null，体系将会同一回收。
元服务API： 从API version 11开始，该接口支持在元服务中使用。
体系能力： SystemCapability.DistributedDataManager.Preferences.Core
参数：
参数名类型必填阐明contextContext是 应用上下文。
FA模子的应用Context界说见Context。
Stage模子的应用Context界说见Context。
optionsOptions是与Preferences实例相关的配置选项。callbackAsyncCallback<void>是回调函数。当移除乐成，err为undefined，否则为错误对象。 错误码：
以下错误码的具体先容。
错误码ID错误信息401 Parameter error. Possible causes:
1. Mandatory parameters are left unspecified;
2. Incorrect parameter types;
3. Parameter verification failed.
801Capability not supported.15500000Inner error.15501001The operations is supported in stage mode only.15501002Invalid dataGroupId. 示例：
FA模子示例：
  1. // 获取context
  2. import { featureAbility } from '@kit.AbilityKit';
  3. import { BusinessError } from '@kit.BasicServicesKit';
  5. let context = featureAbility.getContext();
  6. let options: preferences.Options = { name: 'myStore' };
  7. preferences.removePreferencesFromCache(context, options, (err: BusinessError) => {
  8.   if (err) {
  9.     console.error("Failed to remove preferences. code =" + err.code + ", message =" + err.message);
  10.     return;
  11.   }
  12.   console.info("Succeeded in removing preferences.");
  13. })
复制代码
Stage模子示例：
  1. import { UIAbility } from '@kit.AbilityKit';
  2. import { BusinessError } from '@kit.BasicServicesKit';
  3. import { window } from '@kit.ArkUI';
  5. class EntryAbility extends UIAbility {
  6.   onWindowStageCreate(windowStage: window.WindowStage) {
  7.     let options: preferences.Options = { name: 'myStore' };
  8.     preferences.removePreferencesFromCache(this.context, options, (err: BusinessError) => {
  9.       if (err) {
  10.         console.error("Failed to remove preferences. code =" + err.code + ", message =" + err.message);
  11.         return;
  12.       }
  13.       console.info("Succeeded in removing preferences.");
  14.     })
  15.   }
  16. }
复制代码
preferences.removePreferencesFromCache10+

removePreferencesFromCache(context: Context, options: Options): Promise<void>
从缓存中移出指定的Preferences实例，使用Promise异步回调。
应用初次调用getPreferences接口获取某个Preferences实例后，该实例会被会被缓存起来，后续再次getPreferences时不会再次从长期化文件中读取，直接从缓存中获取Preferences实例。调用此接口移出缓存中的实例之后，再次getPreferences将会重新读取长期化文件，天生新的Preferences实例。
调用该接口后，不发起再使用旧的Preferences实例举行数据利用，否则会出现数据同等性题目，应将Preferences实例置为null，体系将会同一回收。
元服务API： 从API version 11开始，该接口支持在元服务中使用。
体系能力： SystemCapability.DistributedDataManager.Preferences.Core
参数：
参数名类型必填阐明contextContext是 应用上下文。
FA模子的应用Context界说见Context。
Stage模子的应用Context界说见Context。
optionsOptions是与Preferences实例相关的配置选项。 返回值：
类型阐明Promise<void>无返回结果的Promise对象。 错误码：
以下错误码的具体先容。
错误码ID错误信息401 Parameter error. Possible causes:
1. Mandatory parameters are left unspecified;
2. Incorrect parameter types;
3. Parameter verification failed.
801Capability not supported.15500000Inner error.15501001The operations is supported in stage mode only.15501002Invalid dataGroupId. 示例：
FA模子示例：
  1. // 获取context
  2. import { featureAbility } from '@kit.AbilityKit';
  3. import { BusinessError } from '@kit.BasicServicesKit';
  5. let context = featureAbility.getContext();
  6. let options: preferences.Options = { name: 'myStore' };
  7. let promise = preferences.removePreferencesFromCache(context, options);
  8. promise.then(() => {
  9. console.info("Succeeded in removing preferences.");
  10. }).catch((err: BusinessError) => {
  11. console.error("Failed to remove preferences. code =" + err.code + ", message =" + err.message);
  12. })
复制代码
Stage模子示例：
  1. import { UIAbility } from '@kit.AbilityKit';
  2. import { BusinessError } from '@kit.BasicServicesKit';
  3. import { window } from '@kit.ArkUI';
  5. class EntryAbility extends UIAbility {
  6.   onWindowStageCreate(windowStage: window.WindowStage) {
  7.     let options: preferences.Options = { name: 'myStore' };
  8.     let promise = preferences.removePreferencesFromCache(this.context, options);
  9.     promise.then(() => {
  10.       console.info("Succeeded in removing preferences.");
  11.     }).catch((err: BusinessError) => {
  12.       console.error("Failed to remove preferences. code =" + err.code + ", message =" + err.message);
  13.     })
  14.   }
  15. }
复制代码
preferences.removePreferencesFromCacheSync10+

removePreferencesFromCacheSync(context: Context, options: Options):void
从缓存中移出指定的Preferences实例，此为同步接口。
应用初次调用getPreferences接口获取某个Preferences实例后，该实例会被会被缓存起来，后续再次getPreferences时不会再次从长期化文件中读取，直接从缓存中获取Preferences实例。调用此接口移出缓存中的实例之后，再次getPreferences将会重新读取长期化文件，天生新的Preferences实例。
调用该接口后，不发起再使用旧的Preferences实例举行数据利用，否则会出现数据同等性题目，应将Preferences实例置为null，体系将会同一回收。
元服务API： 从API version 11开始，该接口支持在元服务中使用。
体系能力： SystemCapability.DistributedDataManager.Preferences.Core
参数：
参数名类型必填阐明contextContext是 应用上下文。
FA模子的应用Context界说见Context。
Stage模子的应用Context界说见Context。
optionsOptions是与Preferences实例相关的配置选项。 错误码：
以下错误码的具体先容。
错误码ID错误信息401 Parameter error. Possible causes:
1. Mandatory parameters are left unspecified;
2. Incorrect parameter types;
3. Parameter verification failed.
801Capability not supported.15500000Inner error.15501001The operations is supported in stage mode only.15501002Invalid dataGroupId. 示例：
FA模子示例：
  1. // 获取context
  2. import { featureAbility } from '@kit.AbilityKit';
  3. let context = featureAbility.getContext();
  4. let options: preferences.Options = { name: 'myStore' };
  5. preferences.removePreferencesFromCacheSync(context, options);
复制代码
Stage模子示例：
  1. import { UIAbility } from '@kit.AbilityKit';
  2. import { window } from '@kit.ArkUI';
  4. class EntryAbility extends UIAbility {
  5.   onWindowStageCreate(windowStage: window.WindowStage) {
  6.     let options: preferences.Options = { name: 'myStore' };
  7.     preferences.removePreferencesFromCacheSync(this.context, options);
  8.   }
  9. }
复制代码
Options10+

Preferences实例配置选项。
元服务API： 从API version 11开始，该接口支持在元服务中使用。
体系能力： SystemCapability.DistributedDataManager.Preferences.Core
名称类型必填阐明namestring是 Preferences实例的名称。名称长度需大于零且小于等于255字节，名称中不能包含'/'且不能以'/'结尾。
元服务API： 从API version 11开始，该参数支持在元服务中使用。
dataGroupIdstring|null|undefined否 应用组ID，需要向应用市场获取。基于dataGroupId的数据共享支持两种场景：1.同一应用的不同进程间共享，只支持三方应用中输入法和输入法的扩展场景使用；2.不同应用间的数据共享，只支持体系应用使用。
为可选参数。指定在此dataGroupId对应的沙箱路径下创建Preferences实例。当此参数不填时，默认在本应用沙箱目录下创建Preferences实例。
模子束缚： 此属性仅在Stage模子下可用。
元服务API： 从API version 11开始，该参数支持在元服务中使用。
  Preferences

首选项实例，提供获取和修改存储数据的接口。
下列接口都需先使用preferences.getPreferences获取到Preferences实例，再通过此实例调用对应接口。
get

get(key: string, defValue: ValueType, callback: AsyncCallback<ValueType>): void
从缓存的Preferences实例中获取键对应的值，假如值为null或者非默认值类型，返回默认数据defValue，使用callback异步回调。
元服务API： 从API version 11开始，该接口支持在元服务中使用。
体系能力： SystemCapability.DistributedDataManager.Preferences.Core
参数：
参数名类型必填阐明keystring是要获取的存储Key名称，不能为空。defValueValueType是默认返回值。callbackAsyncCallback<ValueType>是回调函数。当获取乐成时，err为undefined，data为键对应的值；否则err为错误对象。 错误码：
以下错误码的具体先容。
错误码ID错误信息401 Parameter error. Possible causes:
1. Mandatory parameters are left unspecified;
2. Incorrect parameter types;
3. Parameter verification failed.
15500000Inner error. 示例：
  1. import { BusinessError } from '@kit.BasicServicesKit';
  3. dataPreferences.get('startup', 'default', (err: BusinessError, val: preferences.ValueType) => {
  4.   if (err) {
  5.     console.error("Failed to get value of 'startup'. code =" + err.code + ", message =" + err.message);
  6.     return;
  7.   }
  8.   console.info("Succeeded in getting value of 'startup'. val： " + val);
  9. })
复制代码
get

get(key: string, defValue: ValueType): Promise<ValueType>
从缓存的Preferences实例中获取键对应的值，假如值为null或者非默认值类型，返回默认数据defValue，使用Promise异步回调。
元服务API： 从API version 11开始，该接口支持在元服务中使用。
体系能力： SystemCapability.DistributedDataManager.Preferences.Core
参数：
参数名类型必填阐明keystring是要获取的存储Key名称，不能为空。defValueValueType是默认返回值。 返回值：
类型阐明Promise<ValueType>Promise对象，返回键对应的值。 错误码：
以下错误码的具体先容。
错误码ID错误信息401 Parameter error. Possible causes:
1. Mandatory parameters are left unspecified;
2. Incorrect parameter types;
3. Parameter verification failed.
15500000Inner error. 示例：
  1. import { BusinessError } from '@kit.BasicServicesKit';
  3. let promise = dataPreferences.get('startup', 'default');
  4. promise.then((data: preferences.ValueType) => {
  5.   console.info("Succeeded in getting value of 'startup'. Data: " + data);
  6. }).catch((err: BusinessError) => {
  7.   console.error("Failed to get value of 'startup'. code =" + err.code + ", message =" + err.message);
  8. })
复制代码
getSync10+

getSync(key: string, defValue: ValueType): ValueType
从缓存的Preferences实例中获取键对应的值，假如值为null或者非默认值类型，返回默认数据defValue，此为同步接口。
元服务API： 从API version 11开始，该接口支持在元服务中使用。
体系能力： SystemCapability.DistributedDataManager.Preferences.Core
参数：
参数名类型必填阐明keystring是要获取的存储Key名称，不能为空。defValueValueType是默认返回值。 返回值：
类型阐明ValueType返回键对应的值。 错误码：
以下错误码的具体先容。
错误码ID错误信息401 Parameter error. Possible causes:
1. Mandatory parameters are left unspecified;
2. Incorrect parameter types;
3. Parameter verification failed.
15500000Inner error. 示例：
  1. let value: preferences.ValueType = dataPreferences.getSync('startup', 'default');
复制代码
getAll

getAll(callback: AsyncCallback<Object>): void;
从缓存的Preferences实例中获取所有键值数据。
元服务API： 从API version 11开始，该接口支持在元服务中使用。
体系能力： SystemCapability.DistributedDataManager.Preferences.Core
参数：
参数名类型必填阐明callbackAsyncCallback<Object>是回调函数。当获取乐成，err为undefined，value为所有键值数据；否则err为错误对象。 错误码：
以下错误码的具体先容。
错误码ID错误信息401Parameter error. Mandatory parameters are left unspecified.15500000Inner error. 示例：
  1. import { BusinessError } from '@kit.BasicServicesKit';
  3. // 由于ArkTS中无Object.keys，且无法使用for..in...
  4. // 若报ArkTS问题，请将此方法单独抽离至一个ts文件中并暴露，在需要用到的ets文件中引入使用
  5. function getObjKeys(obj: Object): string[] {
  6.   let keys = Object.keys(obj);
  7.   return keys;
  8. }
  10. dataPreferences.getAll((err: BusinessError, value: Object) => {
  11.   if (err) {
  12.     console.error("Failed to get all key-values. code =" + err.code + ", message =" + err.message);
  13.     return;
  14.   }
  15.   let allKeys = getObjKeys(value);
  16.   console.info("getAll keys = " + allKeys);
  17.   console.info("getAll object = " + JSON.stringify(value));
  18. })
复制代码
getAll

getAll(): Promise<Object>
从缓存的Preferences实例中获取所有键值数据。
元服务API： 从API version 11开始，该接口支持在元服务中使用。
体系能力： SystemCapability.DistributedDataManager.Preferences.Core
返回值：
类型阐明Promise<Object>Promise对象，返回含有所有键值数据。 错误码：
以下错误码的具体先容。
错误码ID错误信息15500000Inner error. 示例：
  1. import { BusinessError } from '@kit.BasicServicesKit';
  3. // 由于ArkTS中无Object.keys，且无法使用for..in...
  4. // 若报ArkTS问题，请将此方法单独抽离至一个ts文件中并暴露，在需要用到的ets文件中引入使用
  5. function getObjKeys(obj: Object): string[] {
  6.   let keys = Object.keys(obj);
  7.   return keys;
  8. }
  10. let promise = dataPreferences.getAll();
  11. promise.then((value: Object) => {
  12.   let allKeys = getObjKeys(value);
  13.   console.info('getAll keys = ' + allKeys);
  14.   console.info("getAll object = " + JSON.stringify(value));
  15. }).catch((err: BusinessError) => {
  16.   console.error("Failed to get all key-values. code =" + err.code + ", message =" + err.message);
  17. })
复制代码
getAllSync10+

getAllSync(): Object
从缓存的Preferences实例中获取所有键值数据，此为同步接口。
元服务API： 从API version 11开始，该接口支持在元服务中使用。
体系能力： SystemCapability.DistributedDataManager.Preferences.Core
返回值：
类型阐明Object返回含有所有键值数据。 错误码：
以下错误码的具体先容。
错误码ID错误信息15500000Inner error. 示例：
  1. // 由于ArkTS中无Object.keys，且无法使用for..in...
  2. // 若报ArkTS问题，请将此方法单独抽离至一个ts文件中并暴露，在需要用到的ets文件中引入使用
  3. function getObjKeys(obj: Object): string[] {
  4.   let keys = Object.keys(obj);
  5.   return keys;
  6. }
  8. let value = dataPreferences.getAllSync();
  9. let allKeys = getObjKeys(value);
  10. console.info('getAll keys = ' + allKeys);
  11. console.info("getAll object = " + JSON.stringify(value));
复制代码
put

put(key: string, value: ValueType, callback: AsyncCallback<void>): void
将数据写入缓存的Preferences实例中，可通过flush将Preferences实例长期化，使用callback异步回调。
   阐明
  当value中包含非UTF-8格式的字符串时，请使用Uint8Array类型存储，否则会造发展期化文件出现格式错误造成文件损坏。
  当对应的键已经存在时，put()方法会覆盖其值。可以使用hasSync()方法检查是否存在对应键值对。
  元服务API： 从API version 11开始，该接口支持在元服务中使用。
体系能力： SystemCapability.DistributedDataManager.Preferences.Core
参数：
参数名类型必填阐明keystring是要修改的存储的Key，不能为空。valueValueType是存储的新值。callbackAsyncCallback<void>是回调函数。当数据写入乐成，err为undefined；否则为错误对象。 错误码：
以下错误码的具体先容。
错误码ID错误信息401 Parameter error. Possible causes:
1. Mandatory parameters are left unspecified;
2. Incorrect parameter types;
3. Parameter verification failed.
15500000Inner error. 示例：
  1. import { BusinessError } from '@kit.BasicServicesKit';
  3. dataPreferences.put('startup', 'auto', (err: BusinessError) => {
  4.   if (err) {
  5.     console.error("Failed to put value of 'startup'. code =" + err.code + ", message =" + err.message);
  6.     return;
  7.   }
  8.   console.info("Succeeded in putting value of 'startup'.");
  9. })
复制代码
put

put(key: string, value: ValueType): Promise<void>
将数据写入缓存的Preferences实例中，可通过flush将Preferences实例长期化，使用Promise异步回调。
   阐明
  当value中包含非UTF-8格式的字符串时，请使用Uint8Array类型存储，否则会造发展期化文件出现格式错误造成文件损坏。
  当对应的键已经存在时，put()方法会覆盖其值。可以使用hasSync()方法检查是否存在对应键值对。
  元服务API： 从API version 11开始，该接口支持在元服务中使用。
体系能力： SystemCapability.DistributedDataManager.Preferences.Core
参数：
参数名类型必填阐明keystring是要修改的存储的Key，不能为空。valueValueType是存储的新值。 返回值：
类型阐明Promise<void>无返回结果的Promise对象。 错误码：
以下错误码的具体先容。
错误码ID错误信息401 Parameter error. Possible causes:
1. Mandatory parameters are left unspecified;
2. Incorrect parameter types;
3. Parameter verification failed.
15500000Inner error. 示例：
  1. import { BusinessError } from '@kit.BasicServicesKit';
  3. let promise = dataPreferences.put('startup', 'auto');
  4. promise.then(() => {
  5.   console.info("Succeeded in putting value of 'startup'.");
  6. }).catch((err: BusinessError) => {
  7.   console.error("Failed to put value of 'startup'. code =" + err.code + ", message =" + err.message);
  8. })
复制代码
putSync10+

putSync(key: string, value: ValueType): void
将数据写入缓存的Preferences实例中，可通过flush将Preferences实例长期化，此为同步接口。
   阐明
  当value中包含非UTF-8格式的字符串时，请使用Uint8Array类型存储，否则会造发展期化文件出现格式错误造成文件损坏。
  当对应的键已经存在时，putSync()方法会覆盖其值。可以使用hasSync()方法检查是否存在对应键值对。
  元服务API： 从API version 11开始，该接口支持在元服务中使用。
体系能力： SystemCapability.DistributedDataManager.Preferences.Core
参数：
参数名类型必填阐明keystring是要修改的存储的Key，不能为空。valueValueType是存储的新值。 错误码：
以下错误码的具体先容。
错误码ID错误信息401 Parameter error. Possible causes:
1. Mandatory parameters are left unspecified;
2. Incorrect parameter types;
3. Parameter verification failed.
15500000Inner error. 示例：
  1. dataPreferences.putSync('startup', 'auto');
复制代码
has

has(key: string, callback: AsyncCallback<boolean>): void
检查缓存的Preferences实例中是否包含名为给定Key的存储键值对，使用callback异步回调。
元服务API： 从API version 11开始，该接口支持在元服务中使用。
体系能力： SystemCapability.DistributedDataManager.Preferences.Core
参数：
参数名类型必填阐明keystring是要检查的存储key名称，不能为空。callbackAsyncCallback<boolean>是回调函数。返回Preferences实例是否包含给定key的存储键值对，true表现存在，false表现不存在。 错误码：
以下错误码的具体先容。
错误码ID错误信息401 Parameter error. Possible causes:
1. Mandatory parameters are left unspecified;
2. Incorrect parameter types;
3. Parameter verification failed.
15500000Inner error. 示例：
  1. import { BusinessError } from '@kit.BasicServicesKit';
  3. dataPreferences.has('startup', (err: BusinessError, val: boolean) => {
  4.   if (err) {
  5.     console.error("Failed to check the key 'startup'. code =" + err.code + ", message =" + err.message);
  6.     return;
  7.   }
  8.   if (val) {
  9.     console.info("The key 'startup' is contained.");
  10.   } else {
  11.     console.info("The key 'startup' dose not contain.");
  12.   }
  13. })
复制代码
has

has(key: string): Promise<boolean>
检查缓存的Preferences实例中是否包含名为给定Key的存储键值对，使用Promise异步回调。
元服务API： 从API version 11开始，该接口支持在元服务中使用。
体系能力： SystemCapability.DistributedDataManager.Preferences.Core
参数：
参数名类型必填阐明keystring是要检查的存储key名称，不能为空。 返回值：
类型阐明Promise<boolean>Promise对象。返回Preferences实例是否包含给定key的存储键值对，true表现存在，false表现不存在。 错误码：
以下错误码的具体先容。
错误码ID错误信息401 Parameter error. Possible causes:
1. Mandatory parameters are left unspecified;
2. Incorrect parameter types;
3. Parameter verification failed.
15500000Inner error. 示例：
  1. import { BusinessError } from '@kit.BasicServicesKit';
  3. let promise = dataPreferences.has('startup');
  4. promise.then((val: boolean) => {
  5.   if (val) {
  6.     console.info("The key 'startup' is contained.");
  7.   } else {
  8.     console.info("The key 'startup' dose not contain.");
  9.   }
  10. }).catch((err: BusinessError) => {
  11.   console.error("Failed to check the key 'startup'. code =" + err.code + ", message =" + err.message);
  12. })
复制代码
hasSync10+

hasSync(key: string): boolean
检查缓存的Preferences实例中是否包含名为给定Key的存储键值对，此为同步接口。
元服务API： 从API version 11开始，该接口支持在元服务中使用。
体系能力： SystemCapability.DistributedDataManager.Preferences.Core
参数：
参数名类型必填阐明keystring是要检查的存储key名称，不能为空。 返回值：
类型阐明boolean返回Preferences实例是否包含给定key的存储键值对，true表现存在，false表现不存在。 错误码：
以下错误码的具体先容。
错误码ID错误信息401 Parameter error. Possible causes:
1. Mandatory parameters are left unspecified;
2. Incorrect parameter types;
3. Parameter verification failed.
15500000Inner error. 示例：
  1. let isExist: boolean = dataPreferences.hasSync('startup');
  2. if (isExist) {
  3.   console.info("The key 'startup' is contained.");
  4. } else {
  5.   console.info("The key 'startup' dose not contain.");
  6. }
复制代码
delete

delete(key: string, callback: AsyncCallback<void>): void
从缓存的Preferences实例中删除名为给定Key的存储键值对，可通过flush将Preferences实例长期化，使用callback异步回调。
元服务API： 从API version 11开始，该接口支持在元服务中使用。
体系能力： SystemCapability.DistributedDataManager.Preferences.Core
参数：
参数名类型必填阐明keystring是要删除的存储Key名称，不能为空。callbackAsyncCallback<void>是回调函数。当删除乐成，err为undefined；否则为错误对象。 错误码：
以下错误码的具体先容。
错误码ID错误信息401 Parameter error. Possible causes:
1. Mandatory parameters are left unspecified;
2. Incorrect parameter types;
3. Parameter verification failed.
15500000Inner error. 示例：
  1. import { BusinessError } from '@kit.BasicServicesKit';
  3. dataPreferences.delete('startup', (err: BusinessError) => {
  4.   if (err) {
  5.     console.error("Failed to delete the key 'startup'. code =" + err.code + ", message =" + err.message);
  6.     return;
  7.   }
  8.   console.info("Succeeded in deleting the key 'startup'.");
  9. })
复制代码
delete

delete(key: string): Promise<void>
从缓存的Preferences实例中删除名为给定Key的存储键值对，可通过flush将Preferences实例长期化，使用Promise异步回调。
元服务API： 从API version 11开始，该接口支持在元服务中使用。
体系能力： SystemCapability.DistributedDataManager.Preferences.Core
参数：
参数名类型必填阐明keystring是要删除的存储key名称，不能为空。 返回值：
类型阐明Promise<void>无返回结果的Promise对象。 错误码：
以下错误码的具体先容。
错误码ID错误信息401 Parameter error. Possible causes:
1. Mandatory parameters are left unspecified;
2. Incorrect parameter types;
3. Parameter verification failed.
15500000Inner error. 示例：
  1. import { BusinessError } from '@kit.BasicServicesKit';
  3. let promise = dataPreferences.delete('startup');
  4. promise.then(() => {
  5.   console.info("Succeeded in deleting the key 'startup'.");
  6. }).catch((err: BusinessError) => {
  7.   console.error("Failed to delete the key 'startup'. code =" + err.code +", message =" + err.message);
  8. })
复制代码
deleteSync10+

deleteSync(key: string): void
从缓存的Preferences实例中删除名为给定Key的存储键值对，可通过flush将Preferences实例长期化，此为同步接口。
元服务API： 从API version 11开始，该接口支持在元服务中使用。
体系能力： SystemCapability.DistributedDataManager.Preferences.Core
参数：
参数名类型必填阐明keystring是要删除的存储key名称，不能为空。 错误码：
以下错误码的具体先容。
错误码ID错误信息401 Parameter error. Possible causes:
1. Mandatory parameters are left unspecified;
2. Incorrect parameter types;
3. Parameter verification failed.
15500000Inner error. 示例：
  1. dataPreferences.deleteSync('startup');
复制代码
flush

flush(callback: AsyncCallback<void>): void
   阐明
  当数据未修改或修改后的数据与缓存数据同等时，不会刷新长期化文件。
  将缓存的Preferences实例中的数据异步存储到用户首选项的长期化文件中，使用callback异步回调。
  元服务API： 从API version 11开始，该接口支持在元服务中使用。
体系能力： SystemCapability.DistributedDataManager.Preferences.Core
参数：
参数名类型必填阐明callbackAsyncCallback<void>是回调函数。当保存乐成，err为undefined；否则为错误对象。 错误码：
以下错误码的具体先容。
错误码ID错误信息401Parameter error. Mandatory parameters are left unspecified.15500000Inner error. 示例：
  1. import { BusinessError } from '@kit.BasicServicesKit';
  3. dataPreferences.flush((err: BusinessError) => {
  4.   if (err) {
  5.     console.error("Failed to flush. code =" + err.code + ", message =" + err.message);
  6.     return;
  7.   }
  8.   console.info("Succeeded in flushing.");
  9. })
复制代码
flush

flush(): Promise<void>
将缓存的Preferences实例中的数据异步存储到用户首选项的长期化文件中，使用Promise异步回调。
   阐明
  当数据未修改或修改后的数据与缓存数据同等时，不会刷新长期化文件。
  元服务API： 从API version 11开始，该接口支持在元服务中使用。
体系能力： SystemCapability.DistributedDataManager.Preferences.Core
返回值：
类型阐明Promise<void>无返回结果的Promise对象。 错误码：
以下错误码的具体先容。
错误码ID错误信息15500000Inner error. 示例：
  1. import { BusinessError } from '@kit.BasicServicesKit';
  3. let promise = dataPreferences.flush();
  4. promise.then(() => {
  5.   console.info("Succeeded in flushing.");
  6. }).catch((err: BusinessError) => {
  7.   console.error("Failed to flush. code =" + err.code + ", message =" + err.message);
  8. })
复制代码
flushSync14+

flushSync(): void
将缓存的Preferences实例中的数据存储到用户首选项的长期化文件中。
   阐明
  当数据未修改或修改后的数据与缓存数据同等时，不会刷新长期化文件。
  元服务API： 从API version 14开始，该接口支持在元服务中使用。
体系能力： SystemCapability.DistributedDataManager.Preferences.Core
错误码：
以下错误码的具体先容。
错误码ID错误信息15500000Inner error. 示例：
  1. dataPreferences.flushSync();
复制代码
clear

clear(callback: AsyncCallback<void>): void
扫除缓存的Preferences实例中的所有数据，可通过flush将Preferences实例长期化，使用callback异步回调。
元服务API： 从API version 11开始，该接口支持在元服务中使用。
体系能力： SystemCapability.DistributedDataManager.Preferences.Core
参数：
参数名类型必填阐明callbackAsyncCallback<void>是回调函数。当扫除乐成，err为undefined；否则为错误对象。 错误码：
以下错误码的具体先容。
错误码ID错误信息401Parameter error. Mandatory parameters are left unspecified.15500000Inner error. 示例：
  1. import { BusinessError } from '@kit.BasicServicesKit';
  3. dataPreferences.clear((err: BusinessError) =>{
  4.   if (err) {
  5.     console.error("Failed to clear. code =" + err.code + ", message =" + err.message);
  6.     return;
  7.   }
  8.   console.info("Succeeded in clearing.");
  9. })
复制代码
clear

clear(): Promise<void>
扫除缓存的Preferences实例中的所有数据，可通过flush将Preferences实例长期化，使用Promise异步回调。
元服务API： 从API version 11开始，该接口支持在元服务中使用。
体系能力： SystemCapability.DistributedDataManager.Preferences.Core
返回值：
类型阐明Promise<void>无返回结果的Promise对象。 错误码：
以下错误码的具体先容。
错误码ID错误信息15500000Inner error. 示例：
  1. import { BusinessError } from '@kit.BasicServicesKit';
  3. let promise = dataPreferences.clear();
  4. promise.then(() => {
  5.   console.info("Succeeded in clearing.");
  6. }).catch((err: BusinessError) => {
  7.   console.error("Failed to clear. code =" + err.code + ", message =" + err.message);
  8. })
复制代码
clearSync10+

clearSync(): void
扫除缓存的Preferences实例中的所有数据，可通过flush将Preferences实例长期化，此为同步接口。
元服务API： 从API version 11开始，该接口支持在元服务中使用。
体系能力： SystemCapability.DistributedDataManager.Preferences.Core
示例：
  1. dataPreferences.clearSync();
复制代码
on('change')

on(type: 'change', callback: Callback<string>): void
订阅数据变更，订阅的Key的值发生变更后，在实行flush方法后，触发callback回调。
   阐明
  当调用removePreferencesFromCache或者deletePreferences后，订阅的数据变更会自动取消订阅，在重新getPreferences后需要重新订阅数据变更。
  元服务API： 从API version 11开始，该接口支持在元服务中使用。
体系能力： SystemCapability.DistributedDataManager.Preferences.Core
参数：
参数名类型必填阐明typestring是事件类型，固定值'change'，表现数据变更。callbackCallback<string>是回调函数。 错误码：
以下错误码的具体先容。
错误码ID错误信息401 Parameter error. Possible causes:
1. Mandatory parameters are left unspecified;
2. Incorrect parameter types;
3. Parameter verification failed.
15500000Inner error. 示例：
  1. import { BusinessError } from '@kit.BasicServicesKit';
  3. let observer = (key: string) => {
  4.   console.info("The key " + key + " changed.");
  5. }
  6. dataPreferences.on('change', observer);
  7. dataPreferences.putSync('startup', 'manual');
  8. dataPreferences.flush((err: BusinessError) => {
  9.   if (err) {
  10.     console.error("Failed to flush. Cause: " + err);
  11.     return;
  12.   }
  13.   console.info("Succeeded in flushing.");
  14. })
复制代码
on('multiProcessChange')10+

on(type: 'multiProcessChange', callback: Callback<string>): void
订阅进程间数据变更，多个进程持有同一个首选项文件时，在恣意一个进程（包罗本进程）实行flush方法，长期化文件发生变更后，触发callback回调。
本接口提供给申请了dataGroupId的应用举利用用，未申请的应用不推荐使用，多进程利用可能会损坏长期化文件，导致数据丢失。
   阐明
  同一长期化文件在当前进程订阅进程间数据变更的最大数目为50次，凌驾最大限制后会订阅失败。发起在触发callback回调后及时取消订阅。
  当调用removePreferencesFromCache或者deletePreferences后，订阅的数据变更会自动取消订阅，在重新getPreferences后需要重新订阅数据变更。
  元服务API： 从API version 11开始，该接口支持在元服务中使用。
体系能力： SystemCapability.DistributedDataManager.Preferences.Core
参数：
参数名类型必填阐明typestring是事件类型，固定值'multiProcessChange'，表现多进程间的数据变更。callbackCallback<string>是回调函数。 错误码：
以下错误码的具体先容。
错误码ID错误信息401 Parameter error. Possible causes:
1. Mandatory parameters are left unspecified;
2. Incorrect parameter types;
3. Parameter verification failed.
15500000Inner error.15500019Failed to obtain the subscription service. 示例：
  1. import { BusinessError } from '@kit.BasicServicesKit';
  3. let observer = (key: string) => {
  4.   console.info("The key " + key + " changed.");
  5. }
  6. dataPreferences.on('multiProcessChange', observer);
  7. dataPreferences.putSync('startup', 'manual');
  8. dataPreferences.flush((err: BusinessError) => {
  9.   if (err) {
  10.     console.error("Failed to flush. Cause: " + err);
  11.     return;
  12.   }
  13.   console.info("Succeeded in flushing.");
  14. })
复制代码
on('dataChange')12+

on(type: 'dataChange', keys: Array<string>, callback: Callback<Record<string, ValueType>>): void
精确订阅数据变更，只有被订阅的key值发生变更后，在实行flush方法后，触发callback回调。
   阐明
  当调用removePreferencesFromCache或者deletePreferences后，订阅的数据变更会自动取消订阅，在重新getPreferences后需要重新订阅数据变更。
  元服务API： 从API version 12开始，该接口支持在元服务中使用。
体系能力： SystemCapability.DistributedDataManager.Preferences.Core
参数：
参数名类型必填阐明typestring是事件类型，固定值'dataChange'，表现精确的数据变更。keysArray<string>是需要订阅的key集合。callbackCallback<Record<string, ValueType>>是回调函数。回调支持返回多个键值对，其中键为发生变更的订阅key，值为变更后的数据：支持number、string、boolean、Array<number>、Array<string>、Array<boolean>、Uint8Array、object类型。 错误码：
以下错误码的具体先容。
错误码ID错误信息401 Parameter error. Possible causes:
1. Mandatory parameters are left unspecified;
2. Incorrect parameter types;
3. Parameter verification failed.
15500000Inner error. 示例：
  1. import { BusinessError } from '@kit.BasicServicesKit';
  3. let observer = (data: Record<string, preferences.ValueType>) => {
  4.   for (const keyValue of Object.entries(data)) {
  5.     console.info(`observer : ${keyValue}`)
  6.   }
  7.   console.info("The observer called.")
  8. }
  9. let keys = ['name', 'age']
  10. dataPreferences.on('dataChange', keys, observer);
  11. dataPreferences.putSync('name', 'xiaohong');
  12. dataPreferences.putSync('weight', 125);
  13. dataPreferences.flush((err: BusinessError) => {
  14.   if (err) {
  15.     console.error("Failed to flush. Cause: " + err);
  16.     return;
  17.   }
  18.   console.info("Succeeded in flushing.");
  19. })
复制代码
off('change')

off(type: 'change', callback?: Callback<string>): void
取消订阅数据变更。
元服务API： 从API version 11开始，该接口支持在元服务中使用。
体系能力： SystemCapability.DistributedDataManager.Preferences.Core
参数：
参数名类型必填阐明typestring是事件类型，固定值'change'，表现数据变更。callbackCallback<string>否需要取消的回调函数，不填写则全部取消。 错误码：
以下错误码的具体先容。
错误码ID错误信息401 Parameter error. Possible causes:
1. Mandatory parameters are left unspecified;
2. Incorrect parameter types;
3. Parameter verification failed.
15500000Inner error. 示例：
  1. import { BusinessError } from '@kit.BasicServicesKit';
  3. let observer = (key: string) => {
  4.   console.info("The key " + key + " changed.");
  5. }
  6. dataPreferences.on('change', observer);
  7. dataPreferences.putSync('startup', 'auto');
  8. dataPreferences.flush((err: BusinessError) => {
  9.   if (err) {
  10.     console.error("Failed to flush. Cause: " + err);
  11.     return;
  12.   }
  13.   console.info("Succeeded in flushing.");
  14. })
  15. dataPreferences.off('change', observer);
复制代码
off('multiProcessChange')10+

off(type: 'multiProcessChange', callback?: Callback<string>): void
取消订阅进程间数据变更。
本接口提供给申请了dataGroupId的应用举利用用，未申请的应用不推荐使用，多进程利用可能会损坏长期化文件，导致数据丢失。
元服务API： 从API version 11开始，该接口支持在元服务中使用。
体系能力： SystemCapability.DistributedDataManager.Preferences.Core
参数：
参数名类型必填阐明typestring是事件类型，固定值'multiProcessChange'，表现多进程间的数据变更。callbackCallback<string>否需要取消的回调函数，不填写则全部取消。 错误码：
以下错误码的具体先容。
错误码ID错误信息401 Parameter error. Possible causes:
1. Mandatory parameters are left unspecified;
2. Incorrect parameter types;
3. Parameter verification failed.
15500000Inner error. 示例：
  1. import { BusinessError } from '@kit.BasicServicesKit';
  3. let observer = (key: string) => {
  4.   console.info("The key " + key + " changed.");
  5. }
  6. dataPreferences.on('multiProcessChange', observer);
  7. dataPreferences.putSync('startup', 'auto');
  8. dataPreferences.flush((err: BusinessError) => {
  9.   if (err) {
  10.     console.error("Failed to flush. Cause: " + err);
  11.     return;
  12.   }
  13.   console.info("Succeeded in flushing.");
  14. })
  15. dataPreferences.off('multiProcessChange', observer);
复制代码
off('dataChange')12+

off(type: 'dataChange', keys: Array<string>, callback?: Callback<Record<string, ValueType>>): void
取消精确订阅数据变更。
元服务API： 从API version 12开始，该接口支持在元服务中使用。
体系能力： SystemCapability.DistributedDataManager.Preferences.Core
参数：
参数名类型必填阐明typestring是事件类型，固定值'dataChange'，表现精确的数据变更。keysArray<string>是需要取消订阅的key集合，当keys为空数组时，表现取消订阅全部key；当keys为非空数组时，表现只取消订阅key集合中的key。callbackCallback<Record<string, ValueType>>否需要取消的回调函数，若callback不填写，表现所有的callback都需要处理；若callback填写，表现只处理该callback。 错误码：
以下错误码的具体先容。
错误码ID错误信息401 Parameter error. Possible causes:
1. Mandatory parameters are left unspecified;
2. Incorrect parameter types;
3. Parameter verification failed.
15500000Inner error. 示例：
  1. import { BusinessError } from '@kit.BasicServicesKit';
  3. let observer = (data: Record<string, preferences.ValueType>) => {
  4.   for (const keyValue of Object.entries(data)) {
  5.     console.info(`observer : ${keyValue}`)
  6.   }
  7.   console.info("The observer called.")
  8. }
  9. let keys = ['name', 'age']
  10. dataPreferences.on('dataChange', keys, observer);
  11. dataPreferences.putSync('name', 'xiaohong');
  12. dataPreferences.putSync('weight', 125);
  13. dataPreferences.flush((err: BusinessError) => {
  14.   if (err) {
  15.     console.error("Failed to flush. Cause: " + err);
  16.     return;
  17.   }
  18.   console.info("Succeeded in flushing.");
  19. })dataPreferences.off('dataChange', keys, observer);
复制代码
ValueType

type ValueType = number | string | boolean | Array<number> | Array<string> | Array<boolean> | Uint8Array | object | bigint
用于表现答应的数据字段类型。
元服务API： 从API version 11开始，该接口支持在元服务中使用。
体系能力： SystemCapability.DistributedDataManager.Preferences.Core
类型阐明number表现值类型为数字。string表现值类型为字符串。boolean表现值类型为布尔值。Array<number>表现值类型为数字类型的数组。Array<boolean>表现值类型为布尔类型的数组。Array<string>表现值类型为字符串类型的数组。Uint8Array11+表现值类型为8位无符号整型的数组。object12+表现值类型为对象。bigint12+表现值类型为恣意精度格式的整数。


免责声明：如果侵犯了您的权益，请联系站长，我们会及时删除侵权内容，谢谢合作！更多信息从访问主页：qidao123.com:ToB企服之家，中国第一个企服评测及商务社交产业平台。

本帖子中包含更多资源

您需要 登录 才可以下载或查看，没有账号？立即注册

x
回复

使用道具 举报

0 个回复

倒序浏览
返回列表

快速回复

高级模式
B Color Image Link Quote Code Smilies
您需要登录后才可以回帖 登录 or 立即注册

本版积分规则

万有斥力

论坛元老
这个人很懒什么都没写!

楼主热帖

标签云

AI 运维 CIO 存储 服务器
微信订阅号
微信服务号
微信客服
小程序
H5
关于我们 商务合作 网站地图
©Copyright 2022-2024 杭州祥升科技有限公司 版权所有 浙ICP备20004199号
快速回复 返回顶部 返回列表