Skip to content

D
Docs

OpenHarmony / Docs
1 年多 前同步成功

通知 159
Star 292
Fork 28
D
Docs
未验证 提交 3b81471f 编写于 作者: O openharmony_ci 提交者： Gitee
浏览文件
操作

!7901 3.2Beta2分支：首选项Preferences指南和API整改优化：需同步翻译 

Merge pull request !7901 from 葛亚芳/OpenHarmony-3.2-Beta2
上级 480110ad 60355647
展开全部 隐藏空白更改
内联 并排
Showing with 336 addition and 311 deletion
zh-cn/application-dev/database/database-preference-guidelines.md
浏览文件 @ 3b81471f
......@@ -6,11 +6,17 @@
## 场景介绍
首选项功能通常用于保存应用的一些常用配置信息，并不适合需要存储大量数据和频繁改变数据的场景。应用的数据保存在文件中，这些文件可以持久化地存储在设备上。需要注意的是，应用访问的实例包含文件所有数据，这些数据会一直加载在设备的内存中，直到应用主动从内存中将其移除前，应用都可以通过Preferences API进行相关数据操作。
首选项功能通常用于保存应用的一些常用配置信息，并不适合需要存储大量数据和频繁改变数据的场景。应用的数据保存在文件中，这些文件可以持久化地存储在设备上。
需要注意的是，应用访问的实例包含文件所有数据，这些数据会一直加载在设备的内存中，直到应用主动从内存中将其移除前，应用都可以通过Preferences API进行相关数据操作。
## 接口说明
首选项为应用提供key-value键值型的文件数据处理能力，支持应用持久化轻量级数据，并对其修改和查询。数据存储形式为键值对，键的类型为字符串型，值的存储数据类型包括数字型、字符型、布尔型。更多首选项相关接口，请见[首选项API](../reference/apis/js-apis-data-preferences.md)。
首选项为应用提供Key-Value键值型的文件数据处理能力，支持应用持久化轻量级数据，并对其修改和查询。
数据存储形式为键值对，键的类型为字符串型，值的存储数据类型包括数字型、字符型、布尔型以及这3种类型的数组类型。
更多首选项相关接口，请见[首选项API](../reference/apis/js-apis-data-preferences.md)。
### 创建存储实例
......@@ -18,29 +24,26 @@
**表1** 首选项实例创建接口
| 包名 | 接口名 | 描述 |
| ----------------- | ------------------------------------------- | ------------------------------------------- |
| 包名 | 接口名 | 描述 |
| --------------------- | ------------------------------------------------------------ | ------------------------------------------------------------ |
| ohos.data.preferences | getPreferences(context: Context, name: string): Promise\<Preferences> | 读取指定首选项持久化文件，将数据加载到Preferences实例，用于数据操作。 |
### 存入数据
### 存取数据
通过put系列方法，可以增加或修改Preferences实例中的数据。
**表2** 首选项存入接口
| 类名 | 接口名 | 描述 |
| ------- | -------------------------------------------------- | ----------------------------------------------- |
| Preferences | put(key: string, value: ValueType): Promise\<void> | 支持值为number、string、boolean、Array\<number>、Array\<string>、Array\<boolean>类型的数据存入。 |
### 读取数据
通过调用get系列方法，可以读取Preferences中的数据。
**表3** 首选项读取接口
通过调用getAll系列方法，可以获取Preferences中包含所有键值的Object对象。
**表2** 首选项存取接口
| 类名 | 接口名 | 描述 |
| ------- | ---------------------------------------------------------- | ----------------------------------------------- |
| 类名 | 接口名 | 描述 |
| ----------- | ---------------------------------------------------------- | ------------------------------------------------------------ |
| Preferences | put(key: string, value: ValueType): Promise\<void> | 支持存入值为number、string、boolean、Array\<number>、Array\<string>、Array\<boolean>类型的数据。 |
| Preferences | get(key: string, defValue: ValueType): Promise\<ValueType> | 支持获取值为number、string、boolean、Array\<number>、Array\<string>、Array\<boolean>类型的数据。 |
| Preferences | getAll(): Promise<Object> | 支持获取含有所有键值的Object对象。 |
### 数据持久化
......@@ -48,18 +51,18 @@
**表4** 首选项持久化接口
| 类名 | 接口名 | 描述 |
| ------- | ----------------------- | --------------------------------------- |
| 类名 | 接口名 | 描述 |
| ----------- | ----------------------- | ------------------------------------------- |
| Preferences | flush(): Promise\<void> | 将Preferences实例通过异步线程回写入文件中。 |
### 订阅数据变化
订阅数据变更者类，订阅的key的值发生变更后，在执行flush方法后，会执行callback回调。
订阅数据变更者类，订阅的Key的值发生变更后，在执行flush方法后，会触发callback回调。
**表5** 首选项变化订阅接口
| 类名 | 接口名 | 描述 |
| ------- | ------------------------------------------------------------ | -------------- |
| 类名 | 接口名 | 描述 |
| ----------- | ------------------------------------------------------------ | -------------- |
| Preferences | on(type: 'change', callback: Callback<{ key : string }>): void | 订阅数据变化。 |
| Preferences | off(type: 'change', callback: Callback<{ key : string }>): void | 注销订阅。 |
......@@ -69,57 +72,57 @@
**表6** 首选项删除接口
| 包名 | 接口名 | 描述 |
| ----------------- | ---------------------------------------------------- | ------------------------------------------------------------ |
| ohos.data.preferences | deletePreferences(context: Context, name: string): Promise\<void>; | 从缓存中移除已加载的Preferences对象，同时从设备上删除对应的文件。 |
| ohos.data.preferences | removePreferencesFromCache(context: Context, name: string): Promise\<void>; | 仅从缓存中移除已加载的Preferences对象，主要用于释放内存。
| 包名 | 接口名 | 描述 |
| --------------------- | ------------------------------------------------------------ | ------------------------------------------------------------ |
| ohos.data.preferences | deletePreferences(context: Context, name: string): Promise\<void> | 从缓存中移除已加载的Preferences对象，同时从设备上删除对应的文件。 |
| ohos.data.preferences | removePreferencesFromCache(context: Context, name: string): Promise\<void> | 仅从缓存中移除已加载的Preferences对象，主要用于释放内存。 |
## 开发步骤
1. 准备工作，导入@ohos.data.preferences以及相关的模块到开发环境。
```js
import data_preferences from '@ohos.data.preferences'
import data_preferences from '@ohos.data.preferences';
```
2. 获取Preferences实例。
读取指定文件，将数据加载到Preferences实例，用于数据操作。
```js
let promise = data_preferences.getPreferences(this.context, 'mystore')
let promise = data_preferences.getPreferences(this.context, 'mystore');
```
3. 存入数据。
使用Preferences put方法保存数据到缓存的实例中。
使用put方法保存数据到缓存的实例中。
```js
promise.then((preferences) => {
let putPromise = preferences.put('startup', 'auto')
let putPromise = preferences.put('startup', 'auto');
putPromise.then(() => {
console.info("Put the value of startup successfully.")
console.info("Succeeded in putting the value of 'startup'.");
}).catch((err) => {
console.info("Put the value of startup failed with err: " + err)
console.info("Failed to put the value of 'startup'. Cause: " + err);
})
}).catch((err) => {
console.info("Get the storage failed")
console.info("Failed to get preferences.");
})
```
4. 读取数据。
使用Preferences get方法读取数据。
使用get方法读取数据。
```js
promise.then((preferences) => {
let getPromise = preferences.get('startup', 'default')
let getPromise = preferences.get('startup', 'default');
getPromise.then((value) => {
console.info("The value of startup is " + value)
console.info("The value of 'startup' is " + value);
}).catch((err) => {
console.info("Get the value of startup failed with err: " + err)
console.info("Failed to get the value of 'startup'. Cause: " + err);
})
}).catch((err) => {
console.info("Get the storage failed")})
console.info("Failed to get preferences.")});
```
5. 数据持久化。
......@@ -132,25 +135,25 @@
6. 订阅数据变化。
应用订阅数据变化需要指定observer作为回调方法。订阅的key的值发生变更后，当执行flush方法时，observer被触发回调。
应用订阅数据变化需要指定observer作为回调方法。订阅的Key的值发生变更后，当执行flush方法时，observer被触发回调。
```js
var observer = function (key) {
console.info("The key of " + key + " changed.")
console.info("The key" + key + " changed.");
}
preferences.on('change', observer)
preferences.on('change', observer);
preferences.put('startup', 'auto', function (err) {
if (err) {
console.info("Put the value of startup failed with err: " + err)
return
console.info("Failed to put the value of 'startup'. Cause: " + err);
return;
}
console.info("Put the value of startup successfully.")
console.info("Succeeded in putting the value of 'startup'.");
preferences.flush(function (err) {
if (err) {
console.info("Flush to file failed with err: " + err)
return
console.info("Failed to flush. Cause: " + err);
return;
}
console.info("Flushed to file successfully.") // observer will be called.
console.info("Succeeded in flushing."); // observer will be called.
})
})
```
......@@ -160,13 +163,14 @@
使用deletePreferences方法从内存中移除指定文件对应的Preferences单实例，并删除指定文件及其备份文件、损坏文件。删除指定文件时，应用不允许再使用该实例进行数据操作，否则会出现数据一致性问题。删除后，数据及文件将不可恢复。
```js
let proDelete = data_preferences.deletePreferences(context, 'mystore')
let proDelete = data_preferences.deletePreferences(context, 'mystore');
proDelete.then(() => {
console.info("Deleted successfully.")
console.info("Succeeded in deleting.");
}).catch((err) => {
console.info("Deleted failed with err: " + err)
console.info("Failed to delete. Cause: " + err);
})
```
## 相关实例
针对首选项开发，有以下相关实例可供参考：
- [`Preferences`：首选项（eTS）（API9）](https://gitee.com/openharmony/app_samples/tree/master/data/Preferences)
- [`Preferences`：首选项（eTS）（API9）](https://gitee.com/openharmony/app_samples/tree/master/data/Preferences)
\ No newline at end of file
zh-cn/application-dev/database/database-preference-overview.md
浏览文件 @ 3b81471f
# 首选项概述
首选项适用于对Key-Value结构的数据进行存取和持久化操作。应用获取某个Preferences对象后，该存储对象中的数据将会被缓存在内存中，以便应用获得更快的数据存取速度。应用也可以将缓存的数据再次写回文本文件中进行持久化存储，由于文件读写将产生不可避免的系统资源开销，建议应用减少对持久化文件的读写频率。
首选项Preferences，适用于对`Key-Value`结构的数据进行存取和持久化操作。
应用获取某个`Preferences`对象后，该存储对象中的数据将会被缓存在内存中，以便应用获得更快的数据存取速度。
应用也可以将缓存的数据再次写回文本文件中进行持久化存储，由于文件读写将产生不可避免的系统资源开销，建议应用降低对持久化文件的读写频率。
## 基本概念
- **Key-Value数据结构**
一种键值结构数据类型。Key是不重复的关键字，Value是数据值。
一种键值型的数据结构。`Key`是不重复的关键字，`Value`是数据值。
- **非关系型数据库**
区别于关系数据库，不保证遵循ACID（Atomicity, Consistency, Isolation and Durability）特性，不采用关系模型来组织数据，数据之间无关系。
区别于关系数据库，不保证遵循ACID（Atomic、Consistency、Isolation及Durability）特性，不采用关系模型来组织数据，数据之间无关系。比如，以`Key-Value`数据结构组成的数据库。
## 运作机制
1. 应用通过指定首选项持久化文件将其中的数据加载到Preferences实例，系统会通过静态容器将该实例存储在内存中，同一应用或进程中每个文件仅存在一个Preferences实例，直到应用主动从内存中移除该实例或者删除该首选项持久化文件。
2. 应用获取到首选项持久化文件对应的实例后，可以从Preferences实例中读取数据，或者将数据存入Preferences实例中。通过调用flush方法可以将Preferences实例中的数据回写到文件里。
1. 应用通过指定首选项持久化文件将其中的数据加载到`Preferences`实例，系统会通过静态容器将该实例存储在内存中，同一应用或进程中每个文件仅存在一个`Preferences`实例，直到应用主动从内存中移除该实例或者删除该首选项持久化文件。
2. 应用获取到首选项持久化文件对应的实例后，可以从`Preferences`实例中读取数据，或者将数据存入`Preferences`实例中。通过调用flush方法可以将`Preferences`实例中的数据回写到文件里。
**图1** 首选项运作机制
......@@ -23,6 +27,6 @@
## 约束与限制
- 因Preferences实例会加载到内存中，建议存储的数据不超过一万条，并及时清理不再使用的实例，以便减少非内存开销。
- 数据中的key为string类型，要求非空且字符长度不超过80字节。
- 当数据中的value为string类型时，允许为空，字符长度不超过8192字节。
- 因`Preferences`实例会加载到内存中，建议存储的数据不超过一万条，并注意及时清理不再使用的实例，以便减少非内存开销。
- 数据中的`Key`为`string`类型，要求非空且字符长度不超过80个字节。
- 当数据中的`Value`为`string`类型时，允许为空，字符长度不超过8192个字节。
\ No newline at end of file
Markdown is supported
0% 或 .
You are about to add 0 people to the discussion. Proceed with caution.
先完成此消息的编辑！
想要评论请 注册 或