# @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<Preferences>): 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.");
});

1
2
3
4
5
6
7
8
9
10
11
12
13

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.");
});

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

# data_preferences.getPreferences

getPreferences(context: Context, name: string): Promise<Preferences>

获取 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);
  });

1
2
3
4
5
6
7
8
9
10
11
12
13
14

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);
  });

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

# data_preferences.deletePreferences

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

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

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

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

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

参数：

参数名	类型	必填	说明
context	Context	是	应用上下文。 FA 模型的应用 Context 定义见Context。 Stage 模型的应用 Context 定义见Context。
name	string	是	Preferences 实例的名称。
callback	AsyncCallback<void>	是	回调函数。当移除成功，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.");
});

1
2
3
4
5
6
7
8
9
10
11

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.");
});

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

# data_preferences.deletePreferences

deletePreferences(context: Context, name: string): Promise<void>

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

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

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

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

参数：

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

返回值：

类型	说明
Promise<void>	无返回结果的 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);
  });

1
2
3
4
5
6
7
8
9
10
11
12

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);
  });

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

# data_preferences.removePreferencesFromCache

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

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

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

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

参数：

参数名	类型	必填	说明
context	Context	是	应用上下文。 FA 模型的应用 Context 定义见Context。 Stage 模型的应用 Context 定义见Context。
name	string	是	Preferences 实例的名称。
callback	AsyncCallback<void>	是	回调函数。当移除成功，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.");
});

1
2
3
4
5
6
7
8
9
10
11

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.");
});

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

# data_preferences.removePreferencesFromCache

removePreferencesFromCache(context: Context, name: string): Promise<void>

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

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

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

参数：

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

返回值：

类型	说明
Promise<void>	无返回结果的 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);
  });

1
2
3
4
5
6
7
8
9
10
11
12

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);
  });

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

# Preferences

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

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

# get

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

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

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

参数：

参数名	类型	必填	说明
key	string	是	要获取的存储 Key 名称，不能为空。
defValue	ValueType	是	默认返回值。支持 number、string、boolean、Array<number>、Array<string>、Array<boolean>类型。
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);
});

1
2
3
4
5
6
7

# get

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

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

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

参数：

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

返回值：

类型	说明
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);
  });

1
2
3
4
5
6
7
8

# getAll

getAll(callback: AsyncCallback<Object>): void;

获取含有所有键值的 Object 对象。

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

参数：

参数名	类型	必填	说明
callback	AsyncCallback<Object>	是	回调函数。当获取成功，err 为 undefined，value 为含有所有键值的 Object 对象；否则 err 为错误码。

示例：

preferences.getAll(function (err, value) {
  if (err) {
    console.info("Failed to get all key-values. Cause: " + err);
    return;
  }
  let allKeys = Object.keys(value);
  console.info("getAll keys = " + allKeys);
  console.info("getAll object = " + JSON.stringify(value));
});

1
2
3
4
5
6
7
8
9

# getAll

getAll(): Promise<Object>

获取含有所有键值的 Object 对象。

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

返回值：

类型	说明
Promise<Object>	Promise 对象，返回含有所有键值的 Object 对象。

示例：

let promise = preferences.getAll();
promise
  .then((value) => {
    let allKeys = Object.keys(value);
    console.info("getAll keys = " + allKeys);
    console.info("getAll object = " + JSON.stringify(value));
  })
  .catch((err) => {
    console.info("Failed to get all key-values. Cause: " + err);
  });

1
2
3
4
5
6
7
8
9
10

# put

put(key: string, value: ValueType, callback: AsyncCallback<void>): void

将数据写入 Preferences 实例，可通过flush将 Preferences 实例持久化，使用 callback 异步回调。

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

参数：

参数名	类型	必填	说明
key	string	是	要修改的存储的 Key，不能为空。
value	ValueType	是	存储的新值。支持 number、string、boolean、Array<number>、Array<string>、Array<boolean>类型。
callback	AsyncCallback<void>	是	回调函数。当数据写入成功，err 为 undefined；否则为错误码。

示例：

preferences.put("startup", "auto", function (err) {
  if (err) {
    console.info("Failed to put value of 'startup'. Cause: " + err);
    return;
  }
  console.info("Succeeded in putting value of 'startup'.");
});

1
2
3
4
5
6
7

# put

put(key: string, value: ValueType): Promise<void>

将数据写入 Preferences 实例，可通过flush将 Preferences 实例持久化，使用 Promise 异步回调。

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

参数：

参数名	类型	必填	说明
key	string	是	要修改的存储的 Key，不能为空。
value	ValueType	是	存储的新值。支持 number、string、boolean、Array<number>、Array<string>、Array<boolean>类型。

返回值：

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

示例：

let promise = preferences.put("startup", "auto");
promise
  .then(() => {
    console.info("Succeeded in putting value of 'startup'.");
  })
  .catch((err) => {
    console.info("Failed to put value of 'startup'. Cause: " + err);
  });

1
2
3
4
5
6
7
8

# has

has(key: string, callback: AsyncCallback<boolean>): void

检查 Preferences 实例是否包含名为给定 Key 的存储键值对，使用 callback 异步回调。

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

参数：

参数名	类型	必填	说明
key	string	是	要检查的存储 key 名称，不能为空。
callback	AsyncCallback<boolean>	是	回调函数。返回 Preferences 实例是否包含给定 key 的存储键值对，true 表示存在，false 表示不存在。

示例：

preferences.has("startup", function (err, isExist) {
  if (err) {
    console.info("Failed to check the key 'startup'. Cause: " + err);
    return;
  }
  if (isExist) {
    console.info("The key 'startup' is contained.");
  } else {
    console.info("The key 'startup' dose not contain.");
  }
});

1
2
3
4
5
6
7
8
9
10
11

# has

has(key: string): Promise<boolean>

检查 Preferences 实例是否包含名为给定 Key 的存储键值对，使用 Promise 异步回调。

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

参数：

参数名	类型	必填	说明
key	string	是	要检查的存储 key 名称，不能为空。

返回值：

类型	说明
Promise<boolean>	Promise 对象。返回 Preferences 实例是否包含给定 key 的存储键值对，true 表示存在，false 表示不存在。

示例：

let promise = preferences.has("startup");
promise
  .then((isExist) => {
    if (isExist) {
      console.info("The key 'startup' is contained.");
    } else {
      console.info("The key 'startup' dose not contain.");
    }
  })
  .catch((err) => {
    console.info("Failed to check the key 'startup'. Cause: " + err);
  });

1
2
3
4
5
6
7
8
9
10
11
12

# delete

delete(key: string, callback: AsyncCallback<void>): void

从 Preferences 实例中删除名为给定 Key 的存储键值对，使用 callback 异步回调。

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

参数：

参数名	类型	必填	说明
key	string	是	要删除的存储 Key 名称，不能为空。
callback	AsyncCallback<void>	是	回调函数。当删除成功，err 为 undefined；否则为错误码。

示例：

preferences.delete("startup", function (err) {
  if (err) {
    console.info("Failed to delete the key 'startup'. Cause: " + err);
    return;
  }
  console.info("Succeeded in deleting the key 'startup'.");
});

1
2
3
4
5
6
7

# delete

delete(key: string): Promise<void>

从 Preferences 实例中删除名为给定 Key 的存储键值对，使用 Promise 异步回调。

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

参数：

参数名	类型	必填	说明
key	string	是	要删除的存储 key 名称，不能为空。

返回值：

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

示例：

let promise = preferences.delete("startup");
promise
  .then(() => {
    console.info("Succeeded in deleting the key 'startup'.");
  })
  .catch((err) => {
    console.info("Failed to delete the key 'startup'. Cause: " + err);
  });

1
2
3
4
5
6
7
8

# flush

flush(callback: AsyncCallback<void>): void

将当前 Preferences 实例的数据异步存储到首选项持久化文件中，使用 callback 异步回调。

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

参数：

参数名	类型	必填	说明
callback	AsyncCallback<void>	是	回调函数。当保存成功，err 为 undefined；否则为错误码。

示例：

preferences.flush(function (err) {
  if (err) {
    console.info("Failed to flush. Cause: " + err);
    return;
  }
  console.info("Succeeded in flushing.");
});

1
2
3
4
5
6
7

# flush

flush(): Promise<void>

将当前 Preferences 实例的数据异步存储到首选项持久化文件中，使用 Promise 异步回调。

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

返回值：

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

示例：

let promise = preferences.flush();
promise
  .then(() => {
    console.info("Succeeded in flushing.");
  })
  .catch((err) => {
    console.info("Failed to flush. Cause: " + err);
  });

1
2
3
4
5
6
7
8

# clear

clear(callback: AsyncCallback<void>): void

清除此 Preferences 实例中的所有存储，使用 callback 异步回调。

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

参数：

参数名	类型	必填	说明
callback	AsyncCallback<void>	是	回调函数。当清除成功，err 为 undefined；否则为错误码。

示例：

preferences.clear(function (err) {
  if (err) {
    console.info("Failed to clear. Cause: " + err);
    return;
  }
  console.info("Succeeded in clearing.");
});

1
2
3
4
5
6
7

# clear

clear(): Promise<void>

清除此 Preferences 实例中的所有存储，使用 Promise 异步回调。

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

返回值：

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

示例：

let promise = preferences.clear();
promise
  .then(() => {
    console.info("Succeeded in clearing.");
  })
  .catch((err) => {
    console.info("Failed to clear. Cause: " + err);
  });

1
2
3
4
5
6
7
8

# on('change')

on(type: 'change', callback: Callback<{ key : string }>): void

订阅数据变更，订阅的 Key 的值发生变更后，在执行flush方法后，触发 callback 回调。

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

参数：

参数名	类型	必填	说明
type	string	是	事件类型，固定值'change'，表示数据变更。
callback	Callback<{ key : string }>	是	回调对象实例。

示例：

data_preferences.getPreferences(
  this.context,
  "mystore",
  function (err, preferences) {
    if (err) {
      console.info("Failed to get preferences.");
      return;
    }
    let observer = function (key) {
      console.info("The key " + key + " changed.");
    };
    preferences.on("change", observer);
    preferences.put("startup", "manual", function (err) {
      if (err) {
        console.info("Failed to put the value of 'startup'. Cause: " + err);
        return;
      }
      console.info("Succeeded in putting the value of 'startup'.");

      preferences.flush(function (err) {
        if (err) {
          console.info("Failed to flush. Cause: " + err);
          return;
        }
        console.info("Succeeded in flushing."); // observer will be called.
      });
    });
  }
);

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29

# off('change')

off(type: 'change', callback?: Callback<{ key : string }>): void

取消订阅数据变更。

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

参数：

参数名	类型	必填	说明
type	string	是	事件类型，固定值'change'，表示数据变更。
callback	Callback<{ key : string }>	否	需要取消的回调对象实例，不填写则全部取消。

示例：

data_preferences.getPreferences(
  this.context,
  "mystore",
  function (err, preferences) {
    if (err) {
      console.info("Failed to get preferences.");
      return;
    }
    let observer = function (key) {
      console.info("The key " + key + " changed.");
    };
    preferences.on("change", observer);
    preferences.put("startup", "auto", function (err) {
      if (err) {
        console.info("Failed to put the value of 'startup'. Cause: " + err);
        return;
      }
      console.info("Succeeded in putting the value of 'startup'.");

      preferences.flush(function (err) {
        if (err) {
          console.info("Failed to flush. Cause: " + err);
          return;
        }
        console.info("Succeeded in flushing."); // observer will be called.
      });
      preferences.off("change", observer);
    });
  }
);

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30

# ValueType

用于表示允许的数据字段类型。

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

类型	说明
number	表示值类型为数字。
string	表示值类型为字符串。
boolean	表示值类型为布尔值。
Array<number>	表示值类型为数字类型的数组。
Array<boolean>	表示值类型为布尔类型的数组。
Array<string>	表示值类型为字符串类型的数组。