HarmonyOS应用实战-启示散页-44-设置页别直接改全局状态：用 SettingsService 管主题、隐私和诊断开关

HarmonyOS应用实战-启示散页-44-设置页别直接改全局状态：用 SettingsService 管主题、隐私和诊断开关

设置项刚开始通常只有一个深色模式开关，直接在页面里写 Preferences 看起来很快。等到隐私开关、诊断导出、动画偏好陆续加入后，问题就会变成：同一个 key 被多个组件写入，失败时 UI 不知道回滚，其他页面也不知道该刷新哪一块。

这篇文章解决四件事：

从一个开关失控，看设置页为什么要收口

真实项目里，最容易出错的不是开关本身，而是开关背后的副作用。主题切换要刷新颜色，隐私开关要影响导出范围，诊断开关要影响日志口径。若每个组件都直接 set 一个 Preferences key，短期能跑，长期会让排障只剩下全局搜索。

已核对的现状是：当前 AppPreferences 集中管理 schemaVersion、currentDeckId、firstLaunchDone 与种子版本，项目里还没有 SettingsService。本文给出的是未来加入设置页时的工程边界，不把示例代码当成已上线能力。

把设置拆成三层：意图、策略、结果

先写 owner 表，再写代码。否则代码能跑起来，却很难说明失败时该由谁回滚、重启后该由谁恢复、其他页面该根据什么信号刷新。

SettingChange 只表达一次变更，不暴露存储结构

模型要表达本链路需要的稳定事实，不要把页面临时状态或底层存储细节暴露出去。这样后续迁移 Preferences schema、拆模块或增加发布检查时，调用方不必跟着重写。

type SettingKey = 'themeMode' | 'privacyExport' | 'diagnosticsEnabled';

interface SettingChange<T> {
key: SettingKey;
nextValue: T;
source: 'settingsPage' | 'privacyDialog' | 'debugPanel';
}

interface SettingApplyResult<T> {
key: SettingKey;
saved: boolean;
currentValue: T;
message: string;
}

这段模型的重点有三点：字段命名贴近业务；输入输出能覆盖失败分支；没有携带 ArkUI 组件状态。页面拿它展示，Service 拿它做判断，Repository 不需要知道页面长什么样。

SettingsService 按 key 选择保存策略

Service 是规则 owner。凡是涉及校验、回滚、冲突、恢复、隐私或发布证据的逻辑，都不要散落在组件回调里。

class SettingsService {
async applyTheme(change: SettingChange<'light' | 'dark' | 'system'>): Promise<SettingApplyResult<string>> {
const previous = await SettingsRepository.loadThemeMode();
try {
await SettingsRepository.saveThemeMode(change.nextValue);
AppStorage.setOrCreate('settings.theme.changedAt', Date.now());
return { key: change.key, saved: true, currentValue: change.nextValue, message: '主题设置已保存' };
} catch (error) {
return { key: change.key, saved: false, currentValue: previous, message: '保存失败，已恢复原设置' };
}
}

async setDiagnosticsEnabled(enabled: boolean): Promise<SettingApplyResult<boolean>> {
await SettingsRepository.saveDiagnosticsEnabled(enabled);
AppStorage.setOrCreate('settings.diagnostics.changedAt', Date.now());
return { key: 'diagnosticsEnabled', saved: true, currentValue: enabled, message: '诊断开关已更新' };
}
}

这里的 Service 不追求复杂抽象，只做一件事：把输入转成可解释结果。页面可以做乐观交互，但最终事实必须从 Service 返回。

Repository 统一默认值和 schema 迁移

Repository 负责稳定读写、默认值和 schema 兼容。它不弹 Toast，不决定按钮状态，也不拼页面文案。

class SettingsRepository {
static async loadThemeMode(): Promise<'light' | 'dark' | 'system'> {
const value = await PreferencesStore.getString('app_settings', 'theme_mode');
return value === 'light' || value === 'dark' || value === 'system' ? value : 'system';
}

static async saveThemeMode(mode: 'light' | 'dark' | 'system'): Promise<void> {
await PreferencesStore.setString('app_settings', 'theme_mode', mode);
await PreferencesStore.setNumber('app_settings', 'settings_schema_version', 1);
}

static async saveDiagnosticsEnabled(enabled: boolean): Promise<void> {
await PreferencesStore.setBoolean('app_settings', 'diagnostics_enabled', enabled);
}
}

如果这一层缺失，页面会被迫知道 store name、key、默认值和异常处理细节。写到后面，所有页面都会变成半个仓储层。

页面只做乐观展示，不拥有最终事实

页面只消费结果、展示状态、触发动作。跨页面刷新用轻量信号，完整业务对象继续由 Service 重新读取。

@Component
struct SettingsPage {
@State private themeMode: 'light' | 'dark' | 'system' = 'system';
@State private savingTheme: boolean = false;

private async onThemeSelected(nextMode: 'light' | 'dark' | 'system'): Promise<void> {
const previous = this.themeMode;
this.themeMode = nextMode;
this.savingTheme = true;
const result = await new SettingsService().applyTheme({
key: 'themeMode',
nextValue: nextMode,
source: 'settingsPage'
});
this.savingTheme = false;
if (!result.saved) {
this.themeMode = previous;
}
}
}

这类写法的好处是：入口可以扩展，页面可以重进，数据可以迁移。只要 Service 和 Repository 边界稳定，页面不需要关心底层怎么保存。

反例：短期省事，长期失控

反例是把 PreferencesStore.setString('theme_mode', nextMode) 直接写在按钮 onClick 里。这样页面知道了底层 key，也绕过了失败回滚、刷新信号和诊断记录。后续再加隐私开关时，代码会继续复制这条捷径。

更具体地说，反例通常有三个共同点：直接写持久化、没有失败结果、没有刷新 owner。它们在单次手测里很难暴露，但在重启、返回、跨入口或发布复查时会变成真实问题。

排查顺序：\\n1. 先找唯一写入 owner。\\n2. 再看失败是否返回可展示结果。\\n3. 再看刷新信号是否只通知相关页面。\\n4. 最后才检查 UI 展示。

验证路径不要只走正常操作

• 主题切换成功后关闭页面再进入，确认读到的是持久化值。
• 模拟 Preferences 写入失败，确认页面回滚到 previous 值。
• 打开依赖主题的首页和结果页，确认只订阅 theme.changedAt，不读取完整设置对象。
• 诊断开关打开后导出报告，确认不包含题库、问题和答案全文。

验证时建议把“正常路径、异常输入、重启恢复、跨入口刷新、发布态检查”分开记录。构建通过只能证明语法和资源能打包，不能证明这些运行链路都已经被真机验证。

rg –n "PreferencesStore|AppStorage.setOrCreate|Repository|Service" D:\\\\ProgramData\\\\huawei\\\\lesson\\\\The_Book_of_Answers\\nrg –n "question|answerText|deckName|hilog" D:\\\\ProgramData\\\\huawei\\\\lesson\\\\The_Book_of_Answers

常见问题与处理

处理这些问题时不要先改 UI 文案。先确认写入 owner、读取 owner 和刷新信号是否一致，再看页面是否正确消费结果。若只在页面补一个 Toast，用户当次可能看到了提示，但重启、返回、跨入口和发布复查仍然会暴露同一个根因。

落地取舍

这套方案不是为了把轻量应用写重，而是为了把真正会跨页面、跨启动、跨发布阶段的事实收住。只影响当前展示节奏的变量可以留在页面；会改变用户内容、持久结构、隐私口径或发布证据的逻辑，必须进入 Service、Repository 或发布清单。

真正落地时，可以先从一条最容易复现的路径开始：找出唯一写入点，补上结果模型，再把页面里的直接读写替换成 Service 调用。这个顺序比一次性重构全部页面更稳，也更容易在评审时说明每一行代码解决了哪个故障链。评审记录里最好保留对应的命令、截图或复现步骤，避免方案只停留在口头约定。

小结

设置页的关键不是多写一个服务类，而是把“用户意图”和“持久事实”分开。页面负责表达选择，SettingsService 负责校验与回滚，Repository 负责稳定读写，AppStorage 只负责通知。这个边界守住后，后续加隐私、诊断、动画偏好都不会把全局状态写散。
。评审记录里最好保留对应的命令、截图或复现步骤，避免方案只停留在口头约定。

小结

设置页的关键不是多写一个服务类，而是把“用户意图”和“持久事实”分开。页面负责表达选择，SettingsService 负责校验与回滚，Repository 负责稳定读写，AppStorage 只负责通知。这个边界守住后，后续加隐私、诊断、动画偏好都不会把全局状态写散。