diff --git a/zh-cn/application-dev/database/Readme-CN.md b/zh-cn/application-dev/database/Readme-CN.md index ab2703c93e686776ff8c3a85f06ce6859624f55b..f52d1f24dd42ae50568007e904d13f788574995e 100644 --- a/zh-cn/application-dev/database/Readme-CN.md +++ b/zh-cn/application-dev/database/Readme-CN.md @@ -6,9 +6,9 @@ - 关系型数据库 - [关系型数据库概述](database-relational-overview.md) - [关系型数据库开发指导](database-relational-guidelines.md) -- 轻量级数据存储 - - [轻量级数据存储概述](database-preference-overview.md) - - [轻量级数据存储开发指导](database-preference-guidelines.md) +- 首选项 + - [首选项概述](database-preference-overview.md) + - [首选项开发指导](database-preference-guidelines.md) - 分布式数据对象 - [分布式数据对象概述](database-distributedobject-overview.md) - [分布式数据对象开发指导](database-distributedobject-guidelines.md) diff --git a/zh-cn/application-dev/database/database-preference-guidelines.md b/zh-cn/application-dev/database/database-preference-guidelines.md index b7b7011cf3af45627f86f7085de48dded0ab1957..c0480e7c040af40c3a8d079c4fc263489e0ec21b 100644 --- a/zh-cn/application-dev/database/database-preference-guidelines.md +++ b/zh-cn/application-dev/database/database-preference-guidelines.md @@ -1,103 +1,97 @@ -# 轻量级数据存储开发指导 +# 首选项开发指导 ## 场景介绍 -轻量级数据存储功能通常用于保存应用的一些常用配置信息，并不适合需要存储大量数据和频繁改变数据的场景。应用的数据保存在文件中，这些文件可以持久化地存储在设备上。需要注意的是，应用访问的实例包含文件所有数据，这些数据会一直加载在设备的内存中，直到应用主动从内存中将其移除前，应用可以通过Storage的API进行数据操作。 +首选项功能通常用于保存应用的一些常用配置信息，并不适合需要存储大量数据和频繁改变数据的场景。应用的数据保存在文件中，这些文件可以持久化地存储在设备上。需要注意的是，应用访问的实例包含文件所有数据，这些数据会一直加载在设备的内存中，直到应用主动从内存中将其移除前，应用都可以通过Preferences API进行相关数据操作。 ## 接口说明 -轻量级存储为应用提供key-value键值型的文件数据处理能力，支持应用对数据进行轻量级存储及查询。数据存储形式为键值对，键的类型为字符串型，值的存储数据类型包括数字型、字符型、布尔型。 +首选项为应用提供key-value键值型的文件数据处理能力，支持应用持久化轻量级数据，并对其修改和查询。数据存储形式为键值对，键的类型为字符串型，值的存储数据类型包括数字型、字符型、布尔型。 -**创建存储实例** +### 创建存储实例 -读取指定文件，将数据加载到Storage实例，即可创建一个存储实例，用于数据操作。 +读取指定文件，将数据加载到Preferences实例，即可创建一个存储实例，用于数据操作。 -**表1** 轻量级数据存储实例创建接口 +**表1** 首选项实例创建接口 | 包名 | 接口名 | 描述 | | ----------------- | ------------------------------------------- | ------------------------------------------- | -| ohos.data.storage | getStorage(path: string): Promise\ | 获取文件对应的Storage单实例，用于数据操作。 | +| ohos.data.preferences | getPreferences(context: Context, name: string): Promise\ | 读取指定首选项持久化文件，将数据加载到Preferences实例，用于数据操作。 | -**存入数据** +### 存入数据 -通过put系列方法，可以增加或修改Storage实例中的数据。 +通过put系列方法，可以增加或修改Preferences实例中的数据。 -**表2** 轻量级数据存入接口 +**表2** 首选项存入接口 | 类名 | 接口名 | 描述 | | ------- | -------------------------------------------------- | ----------------------------------------------- | -| Storage | put(key: string, value: ValueType): Promise\ | 支持值为number、string、boolean类型的数据存入。 | +| Preferences | put(key: string, value: ValueType): Promise\ | 支持值为number、string、boolean类型的数据存入。 | -**读取数据** +### 读取数据 -通过调用get系列方法，可以读取Storage中的数据。 +通过调用get系列方法，可以读取Preferences中的数据。 -**表3** 轻量级数据读取接口 +**表3** 首选项读取接口 | 类名 | 接口名 | 描述 | | ------- | ---------------------------------------------------------- | ----------------------------------------------- | -| Storage | get(key: string, defValue: ValueType): Promise\ | 支持获取值为number、string、boolean类型的数据。 | +| Preferences | get(key: string, defValue: ValueType): Promise\ | 支持获取值为number、string、boolean类型的数据。 | -**数据持久化** +### 数据持久化 通过执行flush方法，应用可以将缓存的数据再次写回文本文件中进行持久化存储。 -**表4** 轻量级数据持久化接口 +**表4** 首选项持久化接口 | 类名 | 接口名 | 描述 | | ------- | ----------------------- | --------------------------------------- | -| Storage | flush(): Promise\ | 将Storage实例通过异步线程回写入文件中。 | +| Preferences | flush(): Promise\ | 将Preferences实例通过异步线程回写入文件中。 | -**订阅数据变化** +### 订阅数据变化 -订阅数据变化需要指定StorageObserver作为回调方法。订阅的key的值发生变更后，当执行flush方法时，StorageObserver被回调。 +订阅数据变更者类，订阅的key的值发生变更后，在执行flush方法后，会执行callback回调。 -**表5** 轻量级数据变化订阅接口 +**表5** 首选项变化订阅接口 | 类名 | 接口名 | 描述 | | ------- | ------------------------------------------------------------ | -------------- | -| Storage | on(type: 'change', callback: Callback\): void | 订阅数据变化。 | -| Storage | off(type: 'change', callback: Callback\): void | 注销订阅。 | +| Preferences | on(type: 'change', callback: Callback<{ key : string }>): void | 订阅数据变化。 | +| Preferences | off(type: 'change', callback: Callback<{ key : string }>): void | 注销订阅。 | -**删除数据文件** +### 删除数据文件 通过调用以下两种接口，可以删除数据实例或对应的文件。 -**表6** 轻量级数据存储删除接口 +**表6** 首选项删除接口 | 包名 | 接口名 | 描述 | | ----------------- | ---------------------------------------------------- | ------------------------------------------------------------ | -| ohos.data.storage | deleteStorage(path: string): Promise\ | 从缓存中移除已加载的Storage对象，同时从设备上删除对应的文件。 | -| ohos.data.storage | removeStorageFromCache(path: string): Promise\ | 仅从缓存中移除已加载的Storage对象，主要用于释放内存。 | +| ohos.data.preferences | deletePreferences(context: Context, name: string): Promise; | 从缓存中移除已加载的Preferences对象，同时从设备上删除对应的文件。 | +| ohos.data.preferences | removePreferencesFromCache(context: Context, name: string): Promise\; | 仅从缓存中移除已加载的Preferences对象，主要用于释放内存。 ## 开发步骤 -1. 准备工作，导入@ohos.data.storage以及相关的模块到开发环境。 +1. 准备工作，导入@ohos.data.preferences以及相关的模块到开发环境。 ```js - import dataStorage from '@ohos.data.storage' - import featureAbility from '@ohos.ability.featureAbility' // 用于获取文件存储路径 + import data_preferences from '@ohos.data.preferences' ``` -2. 获取Storage实例。 +2. 获取Preferences实例。 - 读取指定文件，将数据加载到Storage实例，用于数据操作。 + 读取指定文件，将数据加载到Preferences实例，用于数据操作。 ```js - var context = featureAbility.getContext() - context.getFilesDir().then(() => { - console.info("======================>getFilesDirPromsie====================>"); - }); - - let promise = dataStorage.getStorage(path + '/mystore') + let promise = data_preferences.getPreferences(this.context, 'mystore') ``` 3. 存入数据。 - 使用Storage put方法保存数据到缓存的实例中。 + 使用Preferences put方法保存数据到缓存的实例中。 ```js - promise.then((storage) => { - let getPromise = storage.put('startup', 'auto') // 保存数据到缓存的storage示例中。 + promise.then((preferences) => { + let getPromise = preferences.put('startup', 'auto') getPromise.then(() => { console.info("Put the value of startup successfully.") }).catch((err) => { @@ -110,11 +104,11 @@ 4. 读取数据。 - 使用Storage get方法读取数据。 + 使用Preferences get方法读取数据。 ```js - promise.then((storage) => { - let getPromise = storage.get('startup', 'default') + promise.then((preferences) => { + let getPromise = preferences.get('startup', 'default') getPromise.then((value) => { console.info("The value of startup is " + value) }).catch((err) => { @@ -126,44 +120,46 @@ 5. 数据持久化。 - 应用存入数据到Storage实例后，可以通过flush或者flushSync方法将Storage实例回写到文件中。 + 应用存入数据到Preferences实例后，可以通过flush方法将Preferences实例回写到文件中。 ```js - storage.flush(); + preferences.flush(); ``` 6. 订阅数据变化。 - 应用订阅数据变化需要指定StorageObserver作为回调方法。订阅的key的值发生变更后，当执行flush方法时，StorageObserver被触发回调。不再需要StorageObserver时请注销。 + 应用订阅数据变化需要指定observer作为回调方法。订阅的key的值发生变更后，当执行flush方法时，observer被触发回调。 ```js - promise.then((storage) => { - var observer = function (key) { - console.info("The key of " + key + " changed.") - } - storage.on('change', observer) - storage.putSync('startup', 'auto') // 修改storage存储数据 - storage.flushSync() // 触发订阅者回调方法 - - storage.off('change', observer) // 注销数据变化订阅 - }).catch((err) => { - console.info("Get the storage failed") - }) + var observer = function (key) { + console.info("The key of " + key + " changed.") + } + 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("Put the value of startup successfully.") + preferences.flush(function (err) { + if (err) { + console.info("Flush to file failed with err: " + err) + return + } + console.info("Flushed to file successfully.") // observer will be called. + }) + }) ``` 7. 删除指定文件。 - 使用deleteStorage方法从内存中移除指定文件对应的Storage单实例，并删除指定文件及其备份文件、损坏文件。删除指定文件时，应用不允许再使用该实例进行数据操作，否则会出现数据一致性问题。删除后，数据及文件将不可恢复。 + 使用deletePreferences方法从内存中移除指定文件对应的Preferences单实例，并删除指定文件及其备份文件、损坏文件。删除指定文件时，应用不允许再使用该实例进行数据操作，否则会出现数据一致性问题。删除后，数据及文件将不可恢复。 ```js - let promise = dataStorage.deleteStorage(path + '/mystore') - promise.then(() => { - console.info("Deleted successfully.") - }).catch((err) => { - console.info("Deleted failed with err: " + err)}) + let proDelete = data_preferences.deletePreferences(context, 'mystore') + proDelete.then(() => { + console.info("Deleted successfully.") + }).catch((err) => { + console.info("Deleted failed with err: " + err) + }) ``` -## 相关实例 -针对轻量级数据存储开发，有以下相关实例可供参考： -- [`LiteStorage`：轻量级存储（eTS）（API7）](https://gitee.com/openharmony/app_samples/tree/master/data/LiteStorage) -- [轻量级偏好数据库](https://gitee.com/openharmony/codelabs/tree/master/Data/Database) -- [备忘录（eTS）](https://gitee.com/openharmony/codelabs/tree/master/Data/NotePad_OH_ETS) \ No newline at end of file diff --git a/zh-cn/application-dev/database/database-preference-overview.md b/zh-cn/application-dev/database/database-preference-overview.md index 78a87adb1a3caa897cb5c4a1706105c120e8e53d..352a81347e31d67386d514c9d4d40f625a28a26a 100644 --- a/zh-cn/application-dev/database/database-preference-overview.md +++ b/zh-cn/application-dev/database/database-preference-overview.md @@ -1,6 +1,6 @@ -# 轻量级数据存储概述 +# 首选项概述 -轻量级数据存储适用于对Key-Value结构的数据进行存取和持久化操作。应用获取某个轻量级存储对象后，该存储对象中的数据将会被缓存在内存中，以便应用获得更快的数据存取速度。应用也可以将缓存的数据再次写回文本文件中进行持久化存储，由于文件读写将产生不可避免的系统资源开销，建议应用减少对持久化文件的读写频率。 +首选项适用于对Key-Value结构的数据进行存取和持久化操作。应用获取某个Preferences对象后，该存储对象中的数据将会被缓存在内存中，以便应用获得更快的数据存取速度。应用也可以将缓存的数据再次写回文本文件中进行持久化存储，由于文件读写将产生不可避免的系统资源开销，建议应用减少对持久化文件的读写频率。 ## 基本概念 @@ -14,15 +14,15 @@ ## 运作机制 -1. 应用通过指定Storage文件将其中的数据加载到Storage实例，系统会通过静态容器将该实例存储在内存中，同一应用或进程中每个文件仅存在一个Storage实例，直到应用主动从内存中移除该实例或者删除该Storage文件。 -2. 应用获取到Storage文件对应的实例后，可以从Storage实例中读取数据，或者将数据存入Storage实例中。通过调用flush或者flushSync方法可以将Storage实例中的数据回写到文件里。 +1. 应用通过指定首选项持久化文件将其中的数据加载到Preferences实例，系统会通过静态容器将该实例存储在内存中，同一应用或进程中每个文件仅存在一个Preferences实例，直到应用主动从内存中移除该实例或者删除该首选项持久化文件。 +2. 应用获取到首选项持久化文件对应的实例后，可以从Preferences实例中读取数据，或者将数据存入Preferences实例中。通过调用flush方法可以将Preferences实例中的数据回写到文件里。 -**图1** 轻量级数据存储运作机制 +**图1** 首选项运作机制 ![zh-cn_image_0000001199139454](figures/zh-cn_image_0000001199139454.png) ## 约束与限制 -- 因Storage实例会加载到内存中，建议存储的数据不超过一万条，并及时清理不再使用的实例，以便减少非内存开销。 -- 数据中的key为string类型，要求非空且字符长度不超过80。 -- 当数据中的value为string类型时，允许为空，字符长度不超过8192。 \ No newline at end of file +- 因Preferences实例会加载到内存中，建议存储的数据不超过一万条，并及时清理不再使用的实例，以便减少非内存开销。 +- 数据中的key为string类型，要求非空且字符长度不超过80字节。 +- 当数据中的value为string类型时，允许为空，字符长度不超过8192字节。 diff --git a/zh-cn/application-dev/database/figures/zh-cn_image_0000001199139454.png b/zh-cn/application-dev/database/figures/zh-cn_image_0000001199139454.png index 5a6f6879944d0fda3cc24d7e726c842c74476728..6c41abd0be236566acb9ce45ee20de57f0b1e6c8 100644 Binary files a/zh-cn/application-dev/database/figures/zh-cn_image_0000001199139454.png and b/zh-cn/application-dev/database/figures/zh-cn_image_0000001199139454.png differ