鸿蒙HarmonyOS系统Preference首选项使用全解析 大家好，我是威哥。
在鸿蒙应用开发里，用户偏好设置的管理是极为重要的一环。
HarmonyOS为我们提供了
Preference
组件，它能让我们轻松实现应用设置界面，对用户首选项进行高效管理。
接下来，我会深入剖析
Preference
的使用细节，并且结合实际应用场景给出完整的ArkTS代码案例。
获取 鸿蒙学习资料 Preference基础认知
Preference
组件主要用于应用设置界面，借助它可以方便地实现各种设置选项。
这些选项的数据会自动保存到系统里，还能在应用的不同模块间共享。
鸿蒙系统提供了多种
Preference
子类，像
SwitchPreference
、
SliderPreference
、
RadioPreference
等，能满足多样化的设置需求。
核心属性与事件 在使用
Preference
前，我们得先了解它的核心属性和事件： 基础属性
name
：用来标识首选项的键值
title
：显示在界面上的选项标题
summary
：选项的简要描述
icon
：选项的图标 交互属性
checked
（SwitchPreference）：开关状态
value
（SliderPreference）：滑块数值
selected
（RadioPreference）：单选状态 常用事件
onChange
：选项状态改变时触发
onClick
：选项被点击时触发 应用场景与案例实现 下面，我以一个音乐播放器应用的设置界面为例，为大家详细讲解
Preference
的使用方法。
这个设置界面包含主题切换、音效调节、播放模式选择等功能。
首先，创建一个
SettingsPage.ets
文件：
// SettingsPage.ets
import common from '@ohos.app.ability.common';
import preference from '@ohos.data.preference';
import { BusinessError } from '@ohos.base';
@Entry
@Component
struct SettingsPage {
@State themeMode: boolean = false;
@State soundEffect: number = 50;
@State playMode: string = 'sequence';
@State showTips: boolean = true;
private context: common.UIAbilityContext = getContext(this) as common.UIAbilityContext;
private prefFileName: string = 'music_player_settings';
private preferenceHelper: preference.Preferences | null = null;
aboutToAppear() {
this.initPreferences();
}
// 初始化首选项
async initPreferences() {
try {
this.preferenceHelper = await preference.getPreferences(this.context, this.prefFileName);
// 从首选项加载已有设置
this.themeMode = await this.preferenceHelper.get('theme_mode', false);
this.soundEffect = await this.preferenceHelper.get('sound_effect', 50);
this.playMode = await this.preferenceHelper.get('play_mode', 'sequence');
this.showTips = await this.preferenceHelper.get('show_tips', true);
} catch (error: BusinessError) {
console.error(`Failed to get preferences: ${error.message}`);
}
}
// 保存首选项
async savePreference(key: string, value: any) {
if (!this.preferenceHelper) return;
try {
if (typeof value === 'boolean') {
await this.preferenceHelper.put(key, value);
} else if (typeof value === 'number') {
await this.preferenceHelper.put(key, value);
} else if (typeof value === 'string') {
await this.preferenceHelper.put(key, value);
}
// 提交更改
await this.preferenceHelper.flush();
console.info(`Preference saved: ${key}=${value}`);
} catch (error: BusinessError) {
console.error(`Failed to save preference: ${error.message}`);
}
}
build() {
Column() {
// 标题栏
Stack({ alignContent: Alignment.Center }) {
Text('音乐播放器设置')
.fontSize(24)
.fontWeight(FontWeight.Bold)
}
.width('100%')
.height(80)
.backgroundColor('#F5F5F5')
// 首选项列表
List() {
// 主题模式切换
ListItem() {
SwitchPreference({
name: 'theme_mode',
title: '暗色模式',
summary: '开启后使用暗色主题',
checked: this.themeMode
})
.onChange((newValue: boolean) => {
this.themeMode = newValue;
this.savePreference('theme_mode', newValue);
})
}
// 音效调节
ListItem() {
SliderPreference({
name: 'sound_effect',
title: '音效强度',
summary: `当前: ${this.soundEffect}%`,
value: this.soundEffect,
min: 0,
max: 100,
step: 5
})
.onChange((newValue: number) => {
this.soundEffect = newValue;
this.savePreference('sound_effect', newValue);
})
}
// 播放模式选择
ListItem() {
Column({ space: 10 }) {
Text('播放模式')
.fontSize(18)
.fontWeight(FontWeight.Medium)
.width('100%')
RadioPreferenceGroup() {
RadioPreference({
name: 'play_mode',
title: '顺序播放',
selected: this.playMode === 'sequence'
})
.onChange(() => {
this.playMode = 'sequence';
this.savePreference('play_mode', 'sequence');
})
RadioPreference({
name: 'play_mode',
title: '单曲循环',
selected: this.playMode === 'loop'
})
.onChange(() => {
this.playMode = 'loop';
this.savePreference('play_mode', 'loop');
})
RadioPreference({
name: 'play_mode',
title: '随机播放',
selected: this.playMode === 'shuffle'
})
.onChange(() => {
this.playMode = 'shuffle';
this.savePreference('play_mode', 'shuffle');
})
}
.layoutWeight(1)
}
.width('100%')
.padding(15)
}
// 提示信息开关
ListItem() {
SwitchPreference({
name: 'show_tips',
title: '显示操作提示',
summary: '开启后在操作时显示提示信息',
checked: this.showTips
})
.onChange((newValue: boolean) => {
this.showTips = newValue;
this.savePreference('show_tips', newValue);
})
}
// 关于页面入口
ListItem() {
Preference({
name: 'about',
title: '关于',
summary: '查看应用版本和版权信息'
})
.onClick(() => {
// 这里可以添加跳转到关于页面的逻辑
console.info('Navigate to about page');
})
}
}
.width('100%')
.height('100%')
.margin({ top: 10 })
}
.width('100%')
.height('100%')
}
}
代码详细分析 下面对上述代码进行详细分析： 首选项的初始化与加载 借助
preference.getPreferences
方法获取首选项实例。
在组件加载时，通过
aboutToAppear
生命周期函数加载已有的设置数据。
SwitchPreference（开关设置） 可用于实现二选一的设置，例如主题模式切换、提示信息开关等。
利用
onChange
事件监听状态变化，并调用
savePreference
方法保存设置。
SliderPreference（滑块设置） 适用于数值调节类的设置，像音量、亮度调节等。
能够通过
min
、
max
、
step
属性来设置取值范围和步长。
RadioPreferenceGroup（单选组） 用于互斥选项的设置，比如播放模式选择。
同一组的
RadioPreference
要使用相同的
name
属性。
基础Preference（普通选项） 可作为普通的点击选项，例如关于页面入口。
通过
onClick
事件处理点击操作。
实际应用中的注意要点 数据持久化 首选项数据会自动保存，但在关键操作之后，最好调用
flush()
方法确保数据同步。
要妥善处理
getPreferences
和
put
操作可能出现的异常。
界面优化 可以通过自定义样式来修改
Preference
的外观，不过要保证整体风格的一致性。
对于复杂的设置项，建议进行分组，以提升用户体验。
跨模块数据共享 由于首选项数据是全局存储的，所以可以在应用的不同模块中获取和使用。
通过以上的案例和分析，相信大家已经掌握了鸿蒙
Preference
首选项的使用方法。
合理运用这些组件，能够高效地实现应用设置功能，为用户提供良好的使用体验。
如果在开发过程中遇到问题，欢迎随时留言交流！
威哥 2025年5月22日