HarmonyOS NEXT鸿蒙开发：数据持久化-用户首选项

作者：马育民 • • 阅读：10102

介绍

官网指南

官网API

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

特点

将该数据 缓存在内存中，当用户读取的时候，能够 快速从内存中获取数据

当需要持久化时可以使用 flush 接口将内存中的数据，写入持久化文件中。

缺点

随着存放的数据量越多而导致应用占用的内存越大，因此，不适合存放过多的数据，也不支持通过配置加密

应用场景

  • 当用户希望有一个全局唯一存储的地方，可以采用用户首选项来进行存储。

  • 应用保存用户的个性化设置（字体大小，是否开启夜间模式）等。

约束限制

  • 首选项无法保证进程并发安全，会有文件损坏和数据丢失的风险，不支持在多进程场景下使用。

  • Key键为string类型，要求非空且长度 不超过1024个字节。

  • 如果Value值为string类型，请使用 UTF-8 编码格式，可以为空，不为空时长度不超过 16 * 1024 * 1024 个字节。

  • 内存会随着存储数据量的增大而增大，所以存储的数据量应该是轻量级的，建议存储的数据 不超过一万条，否则会在内存方面产生较大的开销。

key的类型

数据存储形式为键值对，键的类型为字符串型

value的类型

值的存储数据类型包括：

  • number
  • string
  • boolean
  • number 数组
  • string 数组
  • boolean 数组

开发步骤

  1. 导入模块
  2. 获取Preferences实例
  3. 写入数据
  4. 读取数据
  5. 删除数据
  6. 数据持久化

导入模块

import { preferences } from '@kit.ArkData';

同步接口(新版支持)

新版本中支持 同步接口，因为在读写数据时，要等待处理成功后，再进行下一步操作，所以通常使用 同步接口 较多

本文中介绍的多是 同步接口，异步接口可参见 官网

获取Preferences实例

获取Preferences实例，此为同步接口。

getPreferencesSync(context: Context, options: Options): Preferences

参数：

  • context：必填，应用上下文，一般为：getContext()

  • options：类型：Options，必填，与Preferences实例相关的配置选项。

返回值：返回Preferences实例。

例子

import { preferences } from '@kit.ArkData';

// 获得首选项实例
const options: preferences.Options = { name: 'config' }
const prefer = preferences.getPreferencesSync(getContext(), options)

Options

Preferences实例配置选项，有以下属性：

  • name：类型：string，必填，Preferences实例的名称。

  • dataGroupId：类型：string|null|undefined，应用组ID，需要向 应用市场获取，暂不支持。指定在此dataGroupId对应的沙箱路径下创建Preferences实例。当此参数不填时，默认在本应用沙箱目录下创建Preferences实例。

写数据

将数据写入缓存的Preferences实例中，可通过 flush 将Preferences实例持久化，此为同步接口。

当对应的键已经存在时，putSync() 方法会覆盖其值。可以使用 hasSync() 方法检查是否存在对应键值对。

putSync(key: string, value: ValueType): void

参数：

  • key：类型：string，必填，要修改的存储的Key，不能为空。
  • value：类型：ValueType，必填，存储的新值。

例子

保存字体大小：

prefer.putSync('fontSize', 20)

ValueType

以下类型：

  • number：表示值类型为数字。
  • string：表示值类型为字符串。
  • boolean：表示值类型为布尔值。
  • Array<number>： 表示值类型为数字类型的数组。
  • Array<boolean>： 表示值类型为布尔类型的数组。
  • Array<string>： 表示值类型为字符串类型的数组。
  • Uint8Array： 表示值类型为8位无符号整型的数组。
  • object： 表示值类型为对象。
  • bigint： 表示值类型为任意精度格式的整数。

根据key获取value

从缓存的Preferences实例中获取键对应的值，如果值为null或者非默认值类型，返回默认数据defValue，此为同步接口。

getSync(key: string, defValue: ValueType): ValueType

参数：

  • key：类型：string，必填，根据该key，获取与之对应的value
  • defValue：类型：ValueType，必填，如果没有值，则默认返回该值。

返回值：类型：ValueType，与key对应的值。

例子

获取字体大小

const fontSize = prefer.getSync('fontSize', 20)

获取所有key

从缓存的Preferences实例中获取所有键值数据，此为同步接口

getAllSync(): Object

返回值：类型：Object，返回含有所有键值数据。

例子

const all = prefer.getAllSync()
Object.entries(all).forEach((value: [key: string,value: object], index: number) => {
  console.log("遍历--",value[0],":",value[1])
});

根据key删除数据

从缓存的Preferences实例中删除名为给定Key的存储键值对，可通过flush将Preferences实例持久化，此为同步接口。

deleteSync(key: string): void

参数：

  • key：类型：string，必填，要删除的存储key名称，不能为空。

例子

prefer.deleteSync('fontSize');

清空数据

清除缓存的Preferences实例中的所有数据，可通过 flush() 将Preferences实例持久化，此为同步接口。

clearSync(): void

持久化到文件

接口1

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

flush(callback: AsyncCallback<void>): void

参数：

  • callback：类型：AsyncCallback<void>，必填，回调函数。当保存成功，err 为 undefined；否则为错误对象。

例子

import { BusinessError } from '@kit.BasicServicesKit';

prefer.flush((err: BusinessError) => {
  if (err) {
    console.error("Failed to flush. code =" + err.code + ", message =" + err.message);
    return;
  }
  console.info("Succeeded in flushing.");
})

接口2

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

flush(): Promise<void>

返回值： Promise<void>，无返回结果的Promise对象。

import { BusinessError } from '@kit.BasicServicesKit';

let promise = prefer.flush();
promise.then(() => {
  console.info("Succeeded in flushing.");
}).catch((err: BusinessError) => {
  console.error("Failed to flush. code =" + err.code + ", message =" + err.message);
})

原文出处：/show_1GWBeHMO72.html

吉ICP备15003043号