程序员Feri  | 13年编程老炮，拆解技术脉络，记录程序员的进化史

Hello，我是Feri。

一、先搞懂：首选项（Preferences）到底是什么？

首选项是 HarmonyOS 方舟数据管理（ArkData）里的「轻量级键值存储工具」，专门用来存 少量、简单的配置类数据。

打个比方：你开发的 APP 里，用户设置的 “字体大小”“是否开启夜间模式”“上次登录的昵称”，这些数据量小、不用复杂查询，就适合用首选项存 —— 它像个 “小记事本”，把关键配置记下来，APP 下次打开还能读到。

它在 ArkData 体系里的定位很明确：「最轻量、最快」，和其他存储工具的区别一眼看清：

二、首选项的核心特点（一看就懂）

1. 存储形式：以「键值对」存在设备的文本文件里（比如 “nightMode=true”“nickname = 小明”），文件存在 APP 的专属文件夹，其他 APP 读不到，安全。
2. 加载速度：APP 打开时，会把整个文件加载到内存里 —— 所以读数据特别快，但如果数据太多（超过 100KB），会占内存，导致 APP 卡顿。
3. 支持的数据类型：能存字符串（string）、数字（number）、布尔值（boolean）、日期（Date）等简单类型，不能直接存复杂对象（比如自定义的 “用户” 类，要转成 JSON 字符串才能存）。
4. 持久化关键：修改数据后，要手动 “同步到磁盘”（调用flushSync()），不然只存在内存里，APP 崩溃或关闭后数据会丢。

三、手把手教你用首选项（步骤 + 代码）

原文的代码不变，这里按 “步骤 + 注意事项” 拆解，新手也能跟着做：

第一步：导入首选项模块

先把工具 “拿过来”，一行代码搞定：

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

👉 小提示：如果你的 APP 要兼容旧版本鸿蒙（API 8 及以下），要换成 import { preferences } from '@ohos.data.preferences'。

第二步：创建首选项实例（相当于打开 “记事本”）

要操作数据，得先创建一个实例（绑定一个文件，比如叫 “app_config”）：

// 1. 配置文件信息（文件名：app_config，不用加后缀）
let option: preferences.Options = { name: "app_config" };
// 2. 创建实例（需要传入“上下文”，简单理解为APP的运行环境）
this.pre = preferences.getPreferencesSync(this.getUIContext().getHostContext(), option);

👉 关键注意：

• 一定要加异常处理（防止文件创建失败，比如磁盘满了）：

try {  
this.pre = preferences.getPreferencesSync(context, option);
} catch (err) {  
console.error("创建首选项失败：", err);
}

• 一个文件名对应一个实例，APP 会自动缓存，不用重复创建。

第三步：增删改查数据（操作 “记事本”）

核心操作就 4 个，结合原文示例理解：

完整示例（原文代码，带注释说明）

//导入 首选项模块
import { preferences } from '@kit.ArkData';

@Entry
@Component
struct Demo8 {
  //定义 首选项 实例对象
  pre?:preferences.Preferences;
  a:string='';
  //aboutToAppear 生命周期函数，页面渲染完成就会执行
  aboutToAppear(): void {
    //实例化首选项参数对象
    let option:preferences.Options={name:"study12"}
    //完成首选项对象的实例化
    this.pre=preferences.getPreferencesSync(this.getUIContext().getHostContext(),option);
  }
  build() {
    Column({space:10}) {
      Text("首选项")
      //显示 首选项的内容
      Text(this.pre?.getSync("author","默认")+"")
      //设置 首选项的内容
      TextInput({placeholder:"请输入"})
        .onChange(v=>{
          this.a=v;
        })
      Button("修改作者名字")
        .onClick(()=>{
          //首选项 新增或修改数据 默认 在 内存中
          this.pre?.putSync("author",this.a)
          //把首选项内存的数据 同步到磁盘上
          this.pre?.flushSync()
        })
    }
    .height('100%')
    .width('100%')
  }
}

四、进阶：封装工具类（不用重复写代码）

如果 APP 多个地方要用首选项，每次都写创建实例、存数据的代码太麻烦 —— 原文的工具类正好解决这个问题，这里说清楚 “怎么用”：

1. 工具类代码（原文不变，直接用）

import { preferences } from '@kit.ArkData';
//封装首选项Preferences的操作
export class PreferencesUtil{
  static preference:preferences.Preferences;
  /**
   * 完成首选项工具类的初始化，只需调用1次即可*/
  static init(context:Context,dbname:string){
    let opention:preferences.Options={
      name:dbname
    }
    PreferencesUtil.preference=preferences.getPreferencesSync(context,opention);
  }
  /**
   * 验证是否存在 key*/
  static checkKey(key:string):boolean{
    return PreferencesUtil.preference.hasSync(key);
  }
  /**
   * 获取指定key的值，设置默认值*/
  static get(key:string,val?:string):string{
    if(val){
      return PreferencesUtil.preference.getSync(key,val) as string;
    }else {
      return PreferencesUtil.preference.getSync(key,"") as string;
    }
  }
  //存储数据
  /**
   * 存储数据*/
  static put(key:string,val:string){
    PreferencesUtil.preference.putSync(key,val);
    PreferencesUtil.preference.flushSync();
  }
  /**
   * 删除数据*/
  static delete(key:string){
    PreferencesUtil.preference.deleteSync(key);
  }
  /**
   * 获取所有的key*/
  static all():Object{
    return PreferencesUtil.preference.getAllSync()
  }
}

2. 怎么用这个工具类？

两步走：

• 第一步：在 APP 启动时初始化（只调用 1 次）

在EntryAbility的onCreate里初始化，确保 APP 一启动就准备好：

export default class EntryAbility extends UIAbility {
  onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void {
    try {
      this.context.getApplicationContext().setColorMode(ConfigurationConstant.ColorMode.COLOR_MODE_NOT_SET);
    } catch (err) {
      hilog.error(DOMAIN, 'testTag', 'Failed to set colorMode. Cause: %{public}s', JSON.stringify(err));
    }
    hilog.info(DOMAIN, 'testTag', '%{public}s', 'Ability onCreate');
    //调用首选项工具类，完成实例化
    PreferencesUtil.init(this.context,"xxx.db")
  }

• 第二步：在页面中直接用（不用再创建实例）

/**
 * @Author 程序员Feri
 * @PackageName study12
 * @Date 2025/10/28 15:11
 * @Version 1.0
 */
import { PreferencesUtil } from '../utils/PreferencesUtil';

@Entry
@Component
struct Demo9 {
  v:string='';
  @State version:string='';

  build() {
    Column({space:10}) {
      TextInput({placeholder:"请输入版本号"})
        .onChange(v=>{
          this.v=v;
        })
      Button("存储到首选项")
        .onClick(()=>{
          PreferencesUtil.put("version",this.v)
        })
      Button("读取版本号")
        .onClick(()=>{
          this.version=PreferencesUtil.get("version")
        })
      Text("首选项存储的版本号："+this.version)
    }
    .height('100%')
    .width('100%')
  }
}

效果：

五、怎么验证数据真的存下来了？（测试方法）

按这两步测，确保持久化生效：

1. 运行 APP，在输入框输入内容（比如 “1.0.0”），点击 “存储”；
2. 关闭 APP（在模拟器里把 APP 划掉），重新打开；
3. 点击 “读取”，如果能看到之前输入的 “1.0.0”，说明成功了！

六、避坑指南：这些错误别踩！

1. 忘记调用flushSync()：存了数据但没同步，APP 一关数据就丢；
2. 存太多数据：超过 100KB 导致 APP 卡顿，这种情况换 “键值型数据库”；
3. 实例化时没加try-catch：遇到磁盘满、文件名含特殊字符（比如 “/”“:”）会崩溃；
4. 多地方重复创建实例：比如同一个文件创建多个实例，会占内存，甚至数据错乱；
5. 存敏感数据：首选项不加密，密码、验证码等敏感信息别用它存（换 “键值型数据库” 并开启加密）。

七、最后：什么时候用首选项？什么时候换其他工具？

总而言之，HarmonyOS 首选项（Preferences）是专为轻量级键值数据设计的存储工具，以 “文本文件存储、全量加载内存” 为核心特点，适配 APP 个性化配置、简单状态记录等小数据量场景，凭借用法简洁、访问速度快的优势，成为开发中处理基础持久化需求的实用选择。

使用时需牢记 “修改后调用flushSync()同步磁盘”“单文件数据不超 100KB” 等关键要点，也可通过封装工具类提升复用效率；若遇到大量数据、敏感信息或跨设备同步需求，再按需切换至键值型或关系型数据库即可。

掌握首选项的适用边界与使用细节，能为鸿蒙应用开发的基础数据层打下扎实基础，助力高效实现各类轻量存储需求。

关注我，跟着我一起成长！