Kotlin Multiplatform for OpenHarmony 实战：multiplatform-settings 类型安全 Key-Value 持久化适配

wdracky

23人浏览 · 2026-10-18 22:47:02

wdracky · 2026-10-18 22:47:02 发布

在这里插入图片描述

本文属于 KMP 三方库鸿蒙化适配合集，聚焦 multiplatform-settings（russhwolf）的 OpenHarmony 适配。我们只讲本仓库真实落地的代码，不做系列横向对比。

摘要

本文是 KMP 三方库鸿蒙化适配合集的第 17 篇，讲解 multiplatform-settings（russhwolf）在 OpenHarmony 上的适配方案。文章采用「语义层—引擎层—验收页」三层架构：语义层用纯 ArkTS 定义 SettingsEngine 契约，引擎层通过 getPreferencesSync 桥接鸿蒙 Preferences 的同步 API，验收页在真机上验证写入、读回与持久化闭环。同时总结了 as 收窄、flushSync 落盘、Context 注入时机三个关键坑点。

一、为什么选它

multiplatform-settings 是 KMP 生态里最轻量也最常用的一层：用类型安全的 API 封装各端的 Key-Value 持久化（putString/getString/putInt/getInt/putBoolean/...）。Android 上它背后是 SharedPreferences，iOS 上是 UserDefaults，桌面/JS 各有实现。

到了 OpenHarmony，系统没有 SharedPreferences，但有完全对等的 Preferences（@ohos.data.preferences，经 @kit.ArkData 暴露）。而且 Preferences 本身是同步优先的 API，和原库“阻塞式同步读写”的语义几乎一一对应——这是三种适配路线里“真接口真实现”里最干净的一例。

二、适配总思路：三层架构

我们复用本系列统一的三层架构：

语义层（不碰 @kit.*）：只定义 SettingsEngine 契约和 Settings 门面，纯 ArkTS。
引擎层（桥系统 API）：OhosSettingsEngine 把读写落到鸿蒙 Preferences。
验收页：SettingsDemo 在真机/模拟器上写入并读回，验证契约真实生效。

三、语义层：纯契约

Settings.ets 里只声明接口与门面，不引入任何平台依赖：

export interface SettingsEngine {
  getString(key: string, defaultValue: string): string;
  putString(key: string, value: string): void;
  getInt(key: string, defaultValue: number): number;
  putInt(key: string, value: number): void;
  getBoolean(key: string, defaultValue: boolean): boolean;
  putBoolean(key: string, value: boolean): void;
  // ... long / float / remove / hasKey / clear / keys
}

export class Settings {
  constructor(private readonly engine: SettingsEngine) {}
  getString(k: string, d: string): string { return this.engine.getString(k, d); }
  // ... 其余方法逐一对齐原库调用习惯
}

export function PlatformSettings(engine: SettingsEngine): Settings {
  return new Settings(engine);
}

与原库 Settings() 工厂对齐：原生在 Android/iOS 上自动注入平台实现，鸿蒙没有全局 Context，所以由引擎层把 AbilityContext 桥接进来后显式注入。

四、引擎层：桥 Preferences

OhosSettingsEngine.ets 直接复用系统 getPreferencesSync 与一系列 *Sync 方法：

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

export class OhosSettingsEngine implements SettingsEngine {
  private readonly store: preferences.Preferences;
  constructor(ctx: common.UIAbilityContext, name: string = 'kmp_multiplatform_settings') {
    this.store = preferences.getPreferencesSync(ctx, { name: name });
  }
  getString(key: string, defaultValue: string): string {
    return this.store.getSync(key, defaultValue) as string;
  }
  putString(key: string, value: string): void {
    this.store.putSync(key, value);
    this.store.flushSync();   // 落盘持久化
  }
  // ... 其余类型同理，remove→deleteSync，hasKey→hasSync，clear→clearSync，keys→getAllSync+Object.keys
}

几个关键点：

同步语义吻合：getSync/putSync 直接对应原库的同步读写，业务侧调用零心智负担。
持久化：每次 putSync 后 flushSync()，保证进程退出后数据不丢，等价于 SharedPreferences.apply() 的落盘效果。
严格模式：AbilityContext 必须用页面 this.getUIContext().getHostContext() 传入，绝不能模块顶层取——这是 ArkTS 适配里反复踩的坑。

五、验收页：真机上验证

代码开发如下：
在这里插入图片描述

SettingsDemo.ets 演示写入用户名/年龄/开关、读回上屏、清空、keys() 列举。核心逻辑：

aboutToAppear(): void {
  const ctx = this.getUIContext().getHostContext() as common.UIAbilityContext;
  this.settings = PlatformSettings(new OhosSettingsEngine(ctx, 'settings_demo'));
}
// 写入
s.putString('username', this.username);
s.putInt('age', parseInt(this.ageText, 10));
s.putBoolean('enabled', this.enabled);
// 读回
const u = s.getString('username', '(空)');
const a = s.getInt('age', 0);
const e = s.getBoolean('enabled', false);

点“写入并读取”，立刻看到回显；杀掉进程重进，值仍在——证明持久化链路真实闭环。
运行效果如下：
在这里插入图片描述

在这里插入图片描述

六、问题汇总

as string 收窄：getSync 返回联合类型 ValueType，按 key 已知类型用 as 收窄即可，不要滥用 any。
别忘 flushSync：只 putSync 不 flushSync，数据只在内存，进程被杀会丢。
Context 注入时机：getPreferencesSync 需要合法的 UIAbilityContext，必须在组件内 this.getUIContext().getHostContext() 取得后传入。

七、总结

multiplatform-settings 的鸿蒙化适配，核心就一句话：用系统 Preferences 的同步 API 一一映射原库的同步读写语义。我们通过三层架构把平台差异收敛在引擎层——语义层保持纯契约不碰 @kit.*，引擎层桥接 AbilityContext 与 getPreferencesSync，验收页在真机上验证持久化闭环。

三个最容易踩的坑也值得记住：getSync 返回联合类型要用 as 收窄、putSync 后必须 flushSync() 落盘、Context 只能在组件内通过 getUIContext().getHostContext() 获取。把这三点处理好，这套适配就能稳定跑在 OpenHarmony 上。

欢迎加入 KMP&CMP 鸿蒙社区：https://atomgit.com/CPF-KMP-CMP

本适配全部源码已开源在 AtomGit：https://atomgit.com/wdracky/kmp-ohos-adapters/tree/main/multiplatform-settings

如果本文对你有帮助，欢迎通过专属邀请链接加入 AtomCode 一起共建鸿蒙 KMP 生态：
https://developer.huaweicloud.com/codeartsco.html?source=dmzntgwatomgit1&sourcead=dmzntgwatomgiths