Preferences API是专为轻量级键值对设计的持久化方案，适用于UI偏好、应用状态标记和基础配置项，不支持大文件、复杂结构、多进程共享或敏感信息加密。

Preferences API 是专为轻量级配置数据设计的持久化方案，不适用于大文件或复杂结构，核心价值在于简单、快速、可靠地保存键值对。

适用场景很明确

它适合存那些“关了再开还得在”的小数据：

• 用户界面偏好：深色模式开关、字体大小、语言选择
• 应用状态标记：是否首次启动、推送是否开启、登录令牌（非敏感）、最近搜索关键词
• 基础配置项：自动同步开关、默认排序方式、表单临时缓存标识

别用它存图片 Base64、完整用户列表或日志流水——这类需求该交给数据库或文件系统。

使用方式极简，三步到位

以 HarmonyOS ArkTS 为例，主流写法是同步操作，代码清晰无嵌套：

• 获取实例：preferences.getPreferencesSync(context, { name: 'my_config' }) —— 自动生成 my_config.xml 存于沙箱内
• 写入数据：pref.putSync('theme', 'dark') 或 pref.putSync('recent_ids', [101, 205, 309])
• 立即落盘：pref.flush() —— 关键操作后调用，避免进程意外退出导致丢失

几个关键细节不能错

看似简单，但踩坑多发生在细节上：

• Key 必须是字符串，长度不超过 80 字节，不能为空
• Value 支持 string / number / boolean 及其一维数组，不支持对象、日期、null 或 undefined
• 单个 value 建议 ≤ 8KB，整个文件建议控制在 100KB 内，过大影响启动性能
• 不是多进程安全的，同一文件不可被多个进程同时读写
• 不加密，敏感信息如密码、密钥需另行处理（例如 KeyStore）

Java 和鸿蒙的 Preferences 本质不同

Java 的 java.util.prefs.Preferences 是跨平台抽象层，路径由 JVM 自动编码（比如 org_gs_users_gs_mv_123abc/），你只需调用 API，绝不可手动解析或修改 ~/.java/.userPrefs/ 下的目录；而鸿蒙的 Preferences 是应用私有 XML 文件，路径由系统托管在沙箱中，开发者只管 key-value 操作，完全不用碰文件系统。

大量免费API接口：立即使用
涵盖生活服务API、金融科技API、企业工商API、等相关的API接口服务。免费API接口可安全、合规地连接上下游，为数据API应用能力赋能！