【鸿蒙开发】用户首选项

1. 场景介绍

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

Preferences会将数据缓存在内存中

Preferences数据量越多应用占用的内存就越大

2. 运作机制

用户程序通过ArkTS接口调用用户首选项读写对应的数据文件。

开发者可以将用户首选项持久化文件的内容加载到Preferences实例，每个文件唯一对应到一个Preferences实例，系统会通过静态容器将该实例存储在内存中，直到主动从内存中移除该实例或者删除该文件。

应用首选项的持久化文件保存在应用沙箱内部，可以通过context获取其路径。具体可见获取应用开发路径。

3. 约束限制

• Key键为string类型，要求非空且长度不超过80个字节。
• 如果Value值为string类型，可以为空，不为空时长度不超过8192个字节。
• 建议存储的数据不超过一万条。

4. 接口说明

以下是用户首选项持久化功能的相关接口，大部分为异步接口。异步接口均有callback和Promise两种返回形式，下表均以callback形式为例，更多接口及使用方式请见用户首选项。

接口名称	描述
getPreferences(context: Context, name: string, callback: AsyncCallback<Preferences>): void	获取Preferences实例。
put(key: string, value: ValueType, callback: AsyncCallback<void>): void	将数据写入Preferences实例，可通过flush将Preferences实例持久化。
has(key: string, callback: AsyncCallback<boolean>): void	检查Preferences实例是否包含名为给定Key的存储键值对。给定的Key值不能为空。
get(key: string, defValue: ValueType, callback: AsyncCallback<ValueType>): void	获取键对应的值，如果值为null或者非默认值类型，返回默认数据defValue。
delete(key: string, callback: AsyncCallback<void>): void	从Preferences实例中删除名为给定Key的存储键值对。
flush(callback: AsyncCallback<void>): void	将当前Preferences实例的数据异步存储到用户首选项持久化文件中。
on(type: 'change', callback: Callback<{ key : string }>): void	订阅数据变更，订阅的Key的值发生变更后，在执行flush方法后，触发callback回调。
off(type: 'change', callback?: Callback<{ key : string }>): void	取消订阅数据变更。
deletePreferences(context: Context, name: string, callback: AsyncCallback<void>): void	从内存中移除指定的Preferences实例。若Preferences实例有对应的持久化文件，则同时删除其持久化文件。

5. 示例

5.1 创建 utils/StoreUtil.ets

import preferences from '@ohos.data.preferences'

export class StoreUtil {
  constructor(private readonly storeName: string, private readonly key: string) {
  }

  getStore() {
    return preferences.getPreferences(getContext(this), this.storeName)
  }

  async getData<T>(): Promise<T> {
    const store = await this.getStore()
    const data = await store.get(this.key, "{}") as string
    return JSON.parse(data) as T
  }

  async setData<T>(data: T): Promise<void> {
    const store = await this.getStore()
    await store.put(this.key, JSON.stringify(data))
    await store.flush()
  }

  async delData() {
    const store = await this.getStore()
    await store.delete(this.key)
    await store.flush()
  }
}

5.2 修改 Index.ets

import { StoreUtil } from '../utils/StoreUtil'

export class User {
  name: string = ""
  age: number = 0
}

@Entry
@Component
struct Index {
  userStore: StoreUtil = new StoreUtil('userStore', 'userInfo')
  @State user: Partial<User> = {}

  aboutToAppear() {
    // 不能使用 async await
    this.userStore.getData().then((data) => {
      this.user = data
    })
  }

  build() {
    Column() {
      Text(`${this.user?.name}---${this.user?.age}`)

      Button("修改/新增").onClick(async () => {
        await this.userStore.setData<User>({ name: "lisa", age: 28 })
      })

      Button("获取").onClick(async () => {
        this.user = await this.userStore.getData<User>()
      })

      Button("删除").onClick(async () => {
        await this.userStore.delData()
      })
    }
    .width("100%")
    .height("100%")
  }
}