HarmonyOS用户首选项开发：从入门到实战

目录

一、HarmonyOS 用户首选项是什么？

二、开发前的准备工作

（一）开发环境搭建

（二）相关概念理解

三、开发流程详细步骤

（一）获取 Preferences 实例

（二）数据操作方法

1. 写入数据

2. 读取数据

3. 删除数据

（三）数据持久化与变更订阅

1. 数据持久化

2. 订阅数据变更

四、开发案例实操

（一）案例背景与需求

（二）代码实现过程

1. 自定义用户首选项类

2. UI 界面设计

（三）案例效果展示

五、开发注意事项

（一）数据大小与类型限制

（二）内存与并发安全限制

六、总结与展望

一、HarmonyOS 用户首选项是什么？

HarmonyOS 用户首选项为应用提供了一种 Key - Value 键值型的数据处理能力，主要用于保存应用配置、用户偏好等轻量级数据。比如，我们日常使用的应用中，用户设置的字体大小、主题模式（白天 / 黑夜模式）、是否接收推送通知 等信息，都可以通过用户首选项来存储。

它将数据以键值对的形式存储，其中键（Key）是用于标识数据的唯一字符串，值（Value）则是对应的数据内容 ，可以是数字、字符串、布尔值等基本数据类型，以及这些类型的数组 。而且，这些数据不仅会缓存在内存中，方便快速读取，还能通过特定操作持久化到本地文件，保证应用关闭再重启后数据不丢失。这一特性使得用户首选项在存储一些频繁读取和修改的小型数据时非常高效 ，能有效提升应用的响应速度和用户体验。

二、开发前的准备工作

（一）开发环境搭建

在开始 HarmonyOS 用户首选项的开发之前，我们需要先搭建好开发环境。

1. 软件要求：确保你的开发环境中安装了 DevEco Studio 3.1 Release 及以上版本 ，这是 HarmonyOS 应用开发的官方集成开发环境（IDE），提供了丰富的工具和功能，能大大提高开发效率。同时，需要下载并配置 OpenHarmony SDK API version 9 及以上版本 ，它包含了开发 HarmonyOS 应用所需的各种库和工具。

1. 硬件要求：如果你使用开发板进行真机调试，需要准备符合条件的硬件开发板 ，如润和 RK3568 开发板等，并确保其运行的 OpenHarmony 系统版本为 3.2 Release 及以上。

1. 环境搭建步骤：首先，从华为开发者联盟官网下载 DevEco Studio 安装包 ，根据安装向导进行安装。安装完成后，打开 DevEco Studio，在欢迎页面选择 “Configure” -> “Settings”，在弹出的窗口中选择 “Appearance & Behavior” -> “System Settings” -> “HTTP Proxy”，配置网络代理（如果需要的话）。接着，在 “SDK Manager” 中下载并安装所需的 OpenHarmony SDK 。下载完成后，SDK 会自动配置到 DevEco Studio 中。

（二）相关概念理解

1. dialog（自定义弹窗容器）：在 HarmonyOS 应用开发中，dialog 是一种常用的 UI 组件，用于创建自定义弹窗 。它可以用来展示用户当前需要或必须关注的信息，比如提示用户保存设置成功、询问用户是否确认退出应用等。dialog 仅支持 width、height、margin 等部分样式，且仅支持单个子组件，属性、样式均不支持动态更新 ，也不支持 focusable、click - effect 属性。例如，在用户点击保存用户首选项设置的按钮后，可以弹出一个 dialog 提示用户 “设置已保存” 。

1. 用户首选项：如前文所述，用户首选项是一种以 Key - Value 键值对形式存储数据的方式 ，用于保存应用配置、用户偏好等轻量级数据。理解用户首选项的工作原理和使用场景，对于后续的开发至关重要。比如，我们要开发一个阅读应用，用户设置的字体大小、行间距、是否开启夜间模式等信息，就可以通过用户首选项来存储和管理 。

三、开发流程详细步骤

（一）获取 Preferences 实例

在 HarmonyOS 中获取 Preferences 实例，不同的应用模型有不同的实现方式 。

• Stage 模型：首先，需要导入相关模块，代码如下：

import UIAbility from '@ohos.app.ability.UIAbility';

import { BusinessError } from '@ohos.base';

import window from '@ohos.window';

import dataPreferences from '@ohos.data.preferences';

然后，在UIAbility的onWindowStageCreate生命周期方法中获取Preferences实例 ：

let preferences: dataPreferences.Preferences | null = null;

class EntryAbility extends UIAbility {

onWindowStageCreate(windowStage: window.WindowStage) {

let options: dataPreferences.Options = { name:'myStore' };

preferences = dataPreferences.getPreferencesSync(this.context, options);

}

}

这里的options是一个配置对象 ，其中name属性用于指定Preferences实例的名称，通过getPreferencesSync方法同步获取Preferences实例，它会返回一个Preferences对象，后续我们就可以使用这个对象对用户首选项数据进行操作 。

• FA 模型：同样先导入必要的模块 ：

import featureAbility from '@ohos.ability.featureAbility';

import { BusinessError } from '@ohos.base';

import dataPreferences from '@ohos.data.preferences';

接着获取context并通过getPreferencesSync方法获取Preferences实例 ：

let context = featureAbility.getContext();

let options: dataPreferences.Options = { name:'myStore' };

let preferences: dataPreferences.Preferences = dataPreferences.getPreferencesSync(context, options);

在 FA 模型中，通过featureAbility.getContext()获取应用上下文context ，再利用context和配置选项options来获取Preferences实例 。

（二）数据操作方法

获取到Preferences实例后，就可以对其中的数据进行写入、读取和删除等操作 。

1. 写入数据

使用putSync()方法可以将数据保存到缓存的Preferences实例中 。如果要确保数据持久化存储到文件中，在写入数据后，需要调用flush()方法 。示例代码如下 ：

import util from '@ohos.util';

if (preferences.hasSync('startup')) {

console.info("The key'startup' is contained.");

} else {

console.info("The key'startup' does not contain.");

// 此处以此键值对不存在时写入数据为例

preferences.putSync('startup', 'auto');