使用场景

用户首选项为应用提供Key-Value键值型的数据处理能力，支持应用持久化轻量级数据，并对其修改和查询。当用户希望有一个全局唯一存储的地方，可以采用用户首选项来进行存储。Preferences会将该数据缓存在内存中，当用户读取的时候，能够快速从内存中获取数据，当需要持久化时可以使用flush接口将内存中的数据写入持久化文件中。Preferences会随着存放的数据量越多而导致应用占用的内存越大，因此，Preferences不适合存放过多的数据，也不支持通过配置加密，适用的场景一般为应用保存用户的个性化设置（字体大小，是否开启夜间模式）等。

api：12+

运作机制

如图1所示，用户程序通过ArkTS接口调用用户首选项读写对应的数据文件。开发者可以将用户首选项持久化文件的内容加载到Preferences实例，每个文件唯一对应到一个Preferences实例，系统会通过静态容器将该实例存储在内存中，直到主动从内存中移除该实例或者删除该文件。

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

图1 用户首选项运作机制

约束限制

首选项无法保证进程并发安全，会有文件损坏和数据丢失的风险，不支持在多进程场景下使用。
Key键为string类型，要求非空且长度不超过1024个字节。
如果Value值为string类型，请使用UTF-8编码格式，可以为空，不为空时长度不超过16 * 1024 * 1024个字节。
内存会随着存储数据量的增大而增大，所以存储的数据量应该是轻量级的，建议存储的数据不超过一万条，否则会在内存方面产生较大的开销。

接口说明

以下是用户首选项持久化功能的相关接口，更多接口及使用方式请见用户首选项。

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

开发步骤

1.新增/修改数据

代码：

import { preferences } from '@kit.ArkData'
@Entry
  @Component
  struct Index {
    build() {
      Row() {
        Column() {
          // 1.0 利用首选项api对store这个文件做一个新增数据：["鸿蒙","HTML5"]
          Button('新增/修改数据').onClick(() => {
            //   1.0 获取store文件的操作对象
            const pre = preferences.getPreferencesSync(getContext(), { name: 'store' })
            //   2.0 调用操作对象上的putSync方法完成数据的新增 (这是将数据保存到内存中)
            pre.putSync('keyword', ["鸿蒙Next", "huawei"])
            pre.putSync('keyword2', ["HTML5", "JavaScript"])
            pre.flush() //将内存数据写入到磁盘
            AlertDialog.show({ message: '首选项数据写入成功' })
          })
        }
        .width('100%')
      }
    }
  }

结果查询：

修改数据就还是用key值把之前数据修改成需要的就行

2.查询数据

代码：

Button('获取数据').onClick(() => {
  const pre = preferences.getPreferencesSync(getContext(), { name: 'store' })
  AlertDialog.show({ message: JSON.stringify(pre.getAllSync()) })
})

3.删除数据

代码：

Button('删除数据').onClick(() => {
          const pre = preferences.getPreferencesSync(getContext(), { name: 'store' })
          pre.deleteSync('keyword')
          pre.flush()
          AlertDialog.show({ message: '首选项数据删除成功' })
        })

另一种写法

import { preferences } from '@kit.ArkData'
@Entry
@Component
struct Index {
  pre:PreferencesUtil=new PreferencesUtil()
  build() {
    Row() {
      Column() {
        // 利用首选项api对store这个文件做一个新增数据：["鸿蒙","HTML5"]
        Button('新增/修改数据').onClick(() => {
           this.pre.addData("fontSize", 30)
           this.pre.addData("color", "#90BE2A")
        })
        Button('获取全部数据').onClick(() => {
           this.pre.getAllData()
        })
        Button('获取指定数据').onClick(() => {
           this.pre.getData("color")
        })
          .fontSize(this.pre.getData("fontSize") )
          .fontColor(this.pre.getData("color") )
        Button('删除数据').onClick(() => {
           this.pre.deleteData("color")
        })
      }
      .width('100%')
    }

  }
}

class PreferencesUtil{
  pre = preferences.getPreferencesSync(getContext(), { name: 'myPre' })
  addData(key:string,value:string|number){
    this.pre.putSync(key,value)
    this.pre.flush() //将内存数据写入到磁盘
    AlertDialog.show({ message: '首选项数据写入成功'+key+" "+value })
  }
  getAllData(){
    AlertDialog.show({ message: JSON.stringify(this.pre.getAllSync()) })
  }
  getData(key:string):string|number{
    if(!this.pre.has(key)){
      console.log(`Preutils->getValue_Error:>>不存在${key}键值对`)
      return "不存在";
    }
    let value:string|number=this.pre.getSync(key,0) as string|number
    AlertDialog.show({ message: JSON.stringify(value) })
    return value
  }
  deleteData(key:string){
    if(!this.pre.has(key)){
      console.log(`Preutils->getValue_Error:>>不存在${key}键值对`)
      return;
    }
    this.pre.deleteSync(key)
    this.pre.flush()
    AlertDialog.show({ message: '首选项数据删除成功'+key })
  }
}

编程练习

编写注册、登录界面，使用首选项实现保存密码功能