HarmonyOS 鸿蒙Next数据持久化之用户首选项

HarmonyOS 鸿蒙Next数据持久化之用户首选项

指南：https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/data-persistence-by-preferences

内存中的数据可以写道硬盘里面，这个过程就是数据持久化。

用户首选项提供了一个全局存储数据的能力，这个数据存储在内存中的时候，你可以选择持久化数据到硬盘。如果从磁盘里面读取出来。一次性加载数据到内存。

适合存储一些项目中全局的变量。比如全局主题颜色、全局字体大小等等。

不适合存储大量产品、订单、日志等等。

Preferences 与 AppStorage 的主要区别？

一、定位与作用域

AppStorage

• 是应用级的全局状态管理存储，由 UI 框架在应用启动时自动创建的单例对象。
• 作用范围：应用内所有 UIAbility 和页面均可访问，支持双向数据绑定，适合存储全局 UI 状态属性。
• 默认非持久化，关闭应用后数据清空；需通过 PersistentStorage 关联才能持久化到本地。

Preferences

• 是轻量级的持久化键值存储，通过 ohos.data.preferences API 操作，直接与本地磁盘交互。
• 作用范围：存储用户个性化配置（如字体大小、夜间模式开关等），数据全局可访问且持久化到沙箱文件。

二、数据管理与性能

三、典型使用场景

AppStorage

适用于全局 UI 状态共享（如主题切换、多页面交互参数），且需通过 PersistentStorage 实现重启后状态恢复。

// 配合 PersistentStorage 持久化
PersistentStorage.PersistProp('theme', 'light'); 
AppStorage.setOrCreate('theme', 'light');

Preferences

适用于用户偏好设置（如音量、语言选项）、轻量配置数据持久化，无需跨组件状态同步。

// 首选项操作示例
let prefs = preferences.getPreferencesSync(context, 'settings'); 
prefs.putSync('volume', 80).flushSync();

四、核心差异总结

封装代码：

import { preferences } from "@kit.ArkData";
import { Context } from "@kit.AbilityKit";
import { BusinessError } from "@kit.BasicServicesKit";

export class PreferencesUtil{
  private dataPreferences:preferences.Preferences | null=null

  /**
   * 初始化preferences 对象
   * @param context
   * @param storeName
   */
  init(context:Context,storeName:string){
    let options: preferences.Options={name:storeName}
    this.dataPreferences=preferences.getPreferencesSync(context,options)

    let observer =(key:string)=>{
      console.info(`the key:${key} changed`)
      // 持久化到硬盘
      (this.dataPreferences as preferences.Preferences).flush((err:BusinessError)=>{
        if(err){
          console.error(`failed to flush ,Code :${err.code} ,message :${err.message}`)
          return
        }
        console.info('Succeeded in flushing')
      })
    }
    // 给数据设置监听效果
    this.dataPreferences.on('change',observer)
  }

  insert(key:string,value:string){
    if(this.dataPreferences){
      if(this.dataPreferences.hasSync(key)){
        console.log(`当前已经存在key${key}`)
      }else{
        this.dataPreferences.putSync(key,value)
        console.log(`添加${key}成功`)
      }
    }
  }
  readDate(key:string,value?:string){
    if(this.dataPreferences){
      let val=this.dataPreferences.getSync(key,value?value:'default')
      console.log(`The ${key} value is ${val}`)
      return val
    }else{
      return '查询不到'
    }
  }

  delData(key:string){
    if(this.dataPreferences){
      this.dataPreferences.deleteSync(key)
    }
  }
}

const preferencesUtil= new PreferencesUtil()
export  {preferencesUtil}

Abiltuty中

onWindowStageCreate(windowStage: window.WindowStage): void {
  // 初始化preferences
  preferencesUtil.init(this.context,'myStore')
  preferencesUtil.insert('theme','pink')
}

页面中

Button('主题设置blue').onClick((event:ClickEvent)=>{
  preferencesUtil.insert('theme','blue')
})

Button('获取主题').onClick((event:ClickEvent)=>{
  const result=preferencesUtil.readData('theme')
  console.log(`result:${result}`)
})