数据管理 - @ohos.data.preferences (首选项)

@ohos.data.preferences (首选项)

首选项为应用提供 Key-Value 键值型的数据处理能力，支持应用持久化轻量级数据，并对其修改和查询。

数据存储形式为键值对，键的类型为字符串型，值的存储数据类型包括数字型、字符型、布尔型以及这 3 种类型的数组类型。

说明：

本模块首批接口从 API version 9 开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。

#导入模块

import data_preferences from "@ohos.data.preferences";

#常量

系统能力： SystemCapability.DistributedDataManager.Preferences.Core

名称	参数类型	可读	可写	说明
MAX_KEY_LENGTH	number	是	否	Key 的最大长度限制，需小于 80 个字节。
MAX_VALUE_LENGTH	number	是	否	Value 的最大长度限制，需小于 8192 个字节。

#data_preferences.getPreferences

getPreferences(context: Context, name: string, callback: AsyncCallback): void

获取 Preferences 实例，使用 callback 异步回调。

系统能力： SystemCapability.DistributedDataManager.Preferences.Core

参数：

参数名	类型	必填	说明
context	Context	是	应用上下文。 FA 模型的应用 Context 定义见Context。 Stage 模型的应用 Context 定义见Context。
name	string	是	Preferences 实例的名称。
callback	AsyncCallback<Preferences>	是	回调函数。当获取 Preferences 实例成功，err 为 undefined，返回 Preferences 实例；否则 err 为错误码。

示例：

FA 模型示例：

// 获取context
import featureAbility from "@ohos.ability.featureAbility";
let context = featureAbility.getContext();

let preferences = null;
data_preferences.getPreferences(context, "mystore", function (err, object) {
  if (err) {
    console.info("Failed to get preferences. Cause: " + err);
    return;
  }
  preferences = object;
  console.info("Succeeded in getting preferences.");
});

Stage 模型示例：

// 获取context
import Ability from "@ohos.application.Ability";
let context = null;
class MainAbility extends Ability {
  onWindowStageCreate(windowStage) {
    context = this.context;
  }
}

let preferences = null;
data_preferences.getPreferences(context, "mystore", function (err, object) {
  if (err) {
    console.info("Failed to get preferences. Cause: " + err);
    return;
  }
  preferences = object;
  console.info("Succeeded in getting preferences.");
});

#data_preferences.getPreferences

getPreferences(context: Context, name: string): Promise

获取 Preferences 实例，使用 Promise 异步回调。

系统能力： SystemCapability.DistributedDataManager.Preferences.Core

参数：

参数名	类型	必填	说明
context	Context	是	应用上下文。 FA 模型的应用 Context 定义见Context。 Stage 模型的应用 Context 定义见Context。
name	string	是	Preferences 实例的名称。

返回值：

类型	说明
Promise<Preferences>	Promise 对象，返回 Preferences 实例。

示例：

FA 模型示例：

// 获取context
import featureAbility from "@ohos.ability.featureAbility";
let context = featureAbility.getContext();

let preferences = null;
let promise = data_preferences.getPreferences(context, "mystore");
promise
  .then((object) => {
    preferences = object;
    console.info("Succeeded in getting preferences.");
  })
  .catch((err) => {
    console.info("Failed to get preferences. Cause: " + err);
  });

Stage 模型示例：

// 获取context
import Ability from "@ohos.application.Ability";
let context = null;
class MainAbility extends Ability {
  onWindowStageCreate(windowStage) {
    context = this.context;
  }
}

let preferences = null;
let promise = data_preferences.getPreferences(context, "mystore");
promise
  .then((object) => {
    preferences = object;
    console.info("Succeeded in getting preferences.");
  })
  .catch((err) => {
    console.info("Failed to get preferences. Cause: " + err);
  });

#data_preferences.deletePreferences

deletePreferences(context: Context, name: string, callback: AsyncCallback): void

从内存中移除指定的 Preferences 实例，使用 callback 异步回调。

若 Preferences 实例有对应的持久化文件，则同时删除其持久化文件。

调用该接口后，应用不允许再使用该 Preferences 实例进行数据操作，否则会出现数据一致性问题。

系统能力： SystemCapability.DistributedDataManager.Preferences.Core

参数：

参数名	类型	必填	说明
context	Context	是	应用上下文。 FA 模型的应用 Context 定义见Context。 Stage 模型的应用 Context 定义见Context。
name	string	是	Preferences 实例的名称。
callback	AsyncCallback	是	回调函数。当移除成功，err 为 undefined，否则为错误码。

示例：

FA 模型示例：

// 获取context
import featureAbility from "@ohos.ability.featureAbility";
let context = featureAbility.getContext();

data_preferences.deletePreferences(context, "mystore", function (err) {
  if (err) {
    console.info("Failed to delete preferences. Cause: " + err);
    return;
  }
  console.info("Succeeded in deleting preferences.");
});

Stage 模型示例：

// 获取context
import Ability from "@ohos.application.Ability";
let context = null;
class MainAbility extends Ability {
  onWindowStageCreate(windowStage) {
    context = this.context;
  }
}

data_preferences.deletePreferences(context, "mystore", function (err) {
  if (err) {
    console.info("Failed to delete preferences. Cause: " + err);
    return;
  }
  console.info("Succeeded in deleting preferences.");
});

#data_preferences.deletePreferences

deletePreferences(context: Context, name: string): Promise

从内存中移除指定的 Preferences 实例，使用 Promise 异步回调。

若 Preferences 实例有对应的持久化文件，则同时删除其持久化文件。

调用该接口后，应用不允许再使用该 Preferences 实例进行数据操作，否则会出现数据一致性问题。

系统能力： SystemCapability.DistributedDataManager.Preferences.Core

参数：

参数名	类型	必填	说明
context	Context	是	应用上下文。 FA 模型的应用 Context 定义见Context。 Stage 模型的应用 Context 定义见Context。
name	string	是	Preferences 实例的名称。

返回值：

类型	说明
Promise	无返回结果的 Promise 对象。

示例：

FA 模型示例：

// 获取context
import featureAbility from "@ohos.ability.featureAbility";
let context = featureAbility.getContext();

let promise = data_preferences.deletePreferences(context, "mystore");
promise
  .then(() => {
    console.info("Succeeded in deleting preferences.");
  })
  .catch((err) => {
    console.info("Failed to delete preferences. Cause: " + err);
  });

Stage 模型示例：

// 获取context
import Ability from "@ohos.application.Ability";
let context = null;
class MainAbility extends Ability {
  onWindowStageCreate(windowStage) {
    context = this.context;
  }
}

let promise = data_preferences.deletePreferences(context, "mystore");
promise
  .then(() => {
    console.info("Succeeded in deleting preferences.");
  })
  .catch((err) => {
    console.info("Failed to delete preferences. Cause: " + err);
  });

#data_preferences.removePreferencesFromCache

removePreferencesFromCache(context: Context, name: string, callback: AsyncCallback): void

从内存中移除指定的 Preferences 实例，使用 callback 异步回调。

调用该接口后，应用不允许再使用该 Preferences 实例进行数据操作，否则会出现数据一致性问题。

系统能力： SystemCapability.DistributedDataManager.Preferences.Core

参数：

参数名	类型	必填	说明
context	Context	是	应用上下文。 FA 模型的应用 Context 定义见Context。 Stage 模型的应用 Context 定义见Context。
name	string	是	Preferences 实例的名称。
callback	AsyncCallback	是	回调函数。当移除成功，err 为 undefined，否则为错误码。

示例：

FA 模型示例：

// 获取context
import featureAbility from "@ohos.ability.featureAbility";
let context = featureAbility.getContext();

data_preferences.removePreferencesFromCache(context, "mystore", function (err) {
  if (err) {
    console.info("Failed to remove preferences. Cause: " + err);
    return;
  }
  console.info("Succeeded in removing preferences.");
});

Stage 模型示例：

// 获取context
import Ability from "@ohos.application.Ability";
let context = null;
class MainAbility extends Ability {
  onWindowStageCreate(windowStage) {
    context = this.context;
  }
}

data_preferences.removePreferencesFromCache(context, "mystore", function (err) {
  if (err) {
    console.info("Failed to remove preferences. Cause: " + err);
    return;
  }
  console.info("Succeeded in removing preferences.");
});

#data_preferences.removePreferencesFromCache

removePreferencesFromCache(context: Context, name: string): Promise

从内存中移除指定的 Preferences 实例，使用 Promise 异步回调。

调用该接口后，应用不允许再使用该 Preferences 实例进行数据操作，否则会出现数据一致性问题。

系统能力： SystemCapability.DistributedDataManager.Preferences.Core

参数：

参数名	类型	必填	说明
context	Context	是	应用上下文。 FA 模型的应用 Context 定义见Context。 Stage 模型的应用 Context 定义见Context。
name	string	是	Preferences 实例的名称。

返回值：

类型	说明
Promise	无返回结果的 Promise 对象。

示例：

FA 模型示例：

// 获取context
import featureAbility from "@ohos.ability.featureAbility";
let context = featureAbility.getContext();

let promise = data_preferences.removePreferencesFromCache(context, "mystore");
promise
  .then(() => {
    console.info("Succeeded in removing preferences.");
  })
  .catch((err) => {
    console.info("Failed to remove preferences. Cause: " + err);
  });

Stage 模型示例：

// 获取context
import Ability from "@ohos.application.Ability";
let context = null;
class MainAbility extends Ability {
  onWindowStageCreate(windowStage) {
    context = this.context;
  }
}

let promise = data_preferences.removePreferencesFromCache(context, "mystore");
promise
  .then(() => {
    console.info("Succeeded in removing preferences.");
  })
  .catch((err) => {
    console.info("Failed to remove preferences. Cause: " + err);
  });

#Preferences

存储实例，提供获取和修改存储数据的接口。

下列接口都需先使用data_preferences.getPreferences获取到 Preferences 实例，再通过此实例调用对应接口。

#get

get(key: string, defValue: ValueType, callback: AsyncCallback): void

获取键对应的值，如果值为 null 或者非默认值类型，返回默认数据，使用 callback 异步回调。

系统能力： SystemCapability.DistributedDataManager.Preferences.Core

参数：

参数名	类型	必填	说明
key	string	是	要获取的存储 Key 名称，不能为空。
defValue	ValueType	是	默认返回值。支持 number、string、boolean、Array、Array、Array类型。
callback	AsyncCallback<ValueType>	是	回调函数。当获取成功时，err 为 undefined，data 为键对应的值；否则 err 为错误码。

示例：

preferences.get("startup", "default", function (err, data) {
  if (err) {
    console.info("Failed to get value of 'startup'. Cause: " + err);
    return;
  }
  console.info("Succeeded in getting value of 'startup'. Data： " + data);
});

#get

get(key: string, defValue: ValueType): Promise

获取键对应的值，如果值为 null 或者非默认值类型，返回默认数据，使用 Promise 异步回调。

系统能力： SystemCapability.DistributedDataManager.Preferences.Core

参数：

参数名	类型	必填	说明
key	string	是	要获取的存储 Key 名称，不能为空。
defValue	ValueType	是	默认返回值。支持 number、string、boolean、Array、Array、Array类型。

返回值：

类型	说明
Promise<ValueType>	Promise 对象，返回键对应的值。

示例：

let promise = preferences.get("startup", "default");
promise
  .then((data) => {
    console.info("Succeeded in getting value of 'startup'. Data: " + data);
  })
  .catch((err) => {
    console.info("Failed to get value of 'startup'. Cause: " + err);
  });

#getAll

getAll(callback: AsyncCallback