目录

一、HarmonyOS 数据持久化与用户首选项初相识

二、用户首选项运作机制大揭秘

三、开发前须知：约束限制梳理

四、关键接口说明

五、实战：开发步骤详解

（一）导入用户首选项模块

（二）获取 Preferences 实例

（三）写入数据

（四）读取数据

（五）删除数据

（六）数据持久化

（七）订阅数据变更

（八）删除指定文件

六、 拓展资料与展望

一、HarmonyOS 数据持久化与用户首选项初相识

在 HarmonyOS 开发的广袤天地里，数据持久化堪称基石般的存在。它肩负着在应用程序关闭或设备重启后，依然能妥善保存数据的重任，确保用户的 特点化设置、关键配置信息以及重要数据不丢失，让应用的使用体验得以无缝延续。想象一下，你精心设置好的应用主题、字体 大致，下次打开应用却一切归零，那该多么糟糕，而数据持久化就能完美规避这类 难题。

HarmonyOS 为开发者提供了 丰盛多样的数据持久化方案，今天我们聚焦其中轻巧灵活的用户首选项（Preferences） 。简单来说，用户首选项就像 一个便捷的 “小仓库”，为应用提供 Key – Value 键值型的数据处理能力。它以键值对的形式，将数据存储在应用的内存和本地文件中，你可以把它类比为一个超级有条理的字典，通过唯一的键（Key）就能快速找到对应的值（Value） 。

举个例子，当你在应用里设置是否开启夜间模式时，“是否开启夜间模式” 就是 Key，对应的 “开启” 或 “关闭” 就是 Value，通过用户首选项，就能轻松将这样的设置保存下来。它特别适合存储像用户的 特点化设置（字体 大致、是否开启消息提醒）、应用的简单配置信息（默认语言、初始界面）等轻量级数据 。 由于它把数据缓存在内存中，读取速度那叫一个快，能极大提升应用的响应效率。不过，它也有自己的 “小脾气”，随着存储数据量的增加，应用占用的内存也会增大， 因此不太适合存储大量数据 。

二、用户首选项运作机制大揭秘

用户首选项在 HarmonyOS 的数据持久化体系里，就像一位默默 职业的高效管家，有条不紊地管理着轻量级数据。要深入了解它，还得从其内部运作机制说起。

当应用需要使用用户首选项来存储或读取数据时，一切都从 ArkTS 接口调用开始 。开发者首先要做的，就是通过特定的接口，将用户首选项持久化文件的内容加载到 Preferences 实例中。这里的 Preferences 实例就像 一个数据仓库，专门用来存放从文件中读取的数据，每个文件都有且仅有一个对应的 Preferences 实例 ，就好比一把钥匙开一把锁，一一对应，绝不混淆。

体系会借助静态容器，将这些 Preferences 实例妥善存储在内存中。这就好比一个大型的仓库管理 体系，每个实例都有自己特定的存储位置，这样在需要访问时，就能快速定位到 。只要应用不主动从内存中移除该实例，或者不删除对应的文件，这个实例就会一直存在于内存中，随时待命，为应用提供数据支持。

在实际使用 经过中，比如当用户在应用中修改了字体 大致的设置，应用会通过 ArkTS 接口，将新的字体 大致数据，以键值对的形式写入到 Preferences 实例中。此时，数据只是暂存在内存里，如果应用突然崩溃或者被关闭，这些未持久化的数据就会丢失。 因此，开发者需要适时调用 flush 接口，将内存中的数据写入持久化文件中，这样即使应用重启，数据也能完好无损 。当应用下次启动需要读取字体 大致设置时，又会从持久化文件中加载数据到 Preferences 实例， 接着应用就可以顺利获取到用户之前设置的字体 大致数据 。

三、开发前须知：约束限制梳理

在使用用户首选项进行数据持久化开发时，有一些约束限制需要开发者格外留意，这些限制就像是 制度红线，遵循它们能让开发 经过更加顺畅，确保应用稳定运行 。

键值类型与长度限制：Key 键必须是 string 类型， 并且不能为空，长度也不能超过 1024 字节。这就好比给每个数据贴上的标签，必须是特定格式且长度有限 。Value 值若为 string 类型，需采用 UTF-8 编码格式，当不为空时，长度不超 16MB。如果要存储非 UTF-8 格式字符串，就需要使用 Uint8Array 类型存储，这是为了保证数据在存储和读取 经过中的准确性和一致性。

进程并发与多进程限制：首选项无法保证进程并发安全， 因此不支持在多进程场景中使用。如果在多进程环境下强行使用，可能会出现数据读写冲突，导致数据错误或丢失，就像多个人同时修改同一个文件，却没有协调好顺序，最终文件内容就会混乱 。

数据量建议： 由于内存会随着存储数据量的增大而增大， 因此存储的数据量应该控制在轻量级范畴。一般建议存储的数据不超过一万条，总量最好不要超过 50MB，否则会给应用带来较大的内存开销，影响应用的性能，就像一个小仓库，硬要塞入过多的货物，不仅不好管理，还可能导致仓库 “不堪重负” 。

数据变更订阅注意事项：当调用 removePreferencesFromCache 或 deletePreferences 后，需要重新订阅数据变更，否则可能无法及时获取数据的变化情况。 并且 deletePreferences 不能与其他接口在多线程、多进程中并发调用，不然可能引发意想不到的错误 。

四、关键接口说明

在 HarmonyOS 中使用用户首选项进行数据持久化开发，离不开对一些关键接口的熟练运用 。这些接口就像是开启数据持久化大门的钥匙，掌握它们，就能在数据的存储与读取间游刃有余。

获取 Preferences 实例：使用preferences.getPreferencesSync(context, options) 接口，通过传入应用上下文context和包含name（Preferences 实例的名称）及dataGroupId（应用组 ID，暂不支持）的options参数，就能获取到 Preferences 实例。例如：

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

import application from '@ohos.application';

let context = application.getContext();

let options = {name: 'examplePreferences'};

let preferencesInstance = preferences.getPreferencesSync(context, options);

这个实例就像 一个数据操作的 “控制台”，后续对数据的各种操作都要通过它来进行。

2. 写入数据：有了实例后，写入数据就变得简单了，使用putSync(key, value)接口 。比如要保存用户设置的字体 大致，代码可以这样写：

let fontSize = 16;

preferencesInstance.putSync('fontSize', fontSize);

这里的'fontSize'就是 Key，fontSize变量的值就是 Value 。不过要注意，此时数据只是写入了内存中的实例，如果要持久化到文件，还得调用flush接口 。

3. 读取数据：从 Preferences 实例中读取数据，调用getSync(key, defValue)接口，key是要读取的数据对应的键，defValue是默认值，当键不存在时返回该默认值 。假设要读取刚才保存的字体 大致：

let fontSize = preferencesInstance.getSync('fontSize', 14);

如果存在'fontSize'这个键，就会返回对应的值，否则返回默认值 14 。

4. 删除数据：想要删除某个键值对，调用deleteSync(key)接口 。比如要删除用户之前设置的某个临时数据：

preferencesInstance.deleteSync('tempDataKey');

调用该接口后，内存中的键值对会被删除，但同样要记得调用flush接口，才能将文件中的数据也删除 。

5. 数据持久化：将内存中的数据持久化到本地文件，使用flush()接口 ，它会返回一个 Promise 对象，在操作完成后可以进行相应的处理：

preferencesInstance.flush().then(() => {

console.log('数据已成功持久化到文件');

}).catch((error) => {

console.error('持久化数据时出错:', error);

});

订阅和取消订阅数据变更：如果想监听数据的变化，可以使用on(type, callback)接口订阅数据变更事件 。例如订阅整个实例的数据变更：

preferencesInstance.on('change', (changedKey) => {

console.log(`数据发生变更，变更的键为: ${changedKey}`);

});

当数据发生变更并调用flush时，就会触发这个回调函数 。如果不想再监听了，使用off('type')接口取消订阅 。

7. 删除指定文件：要从缓存中移除指定的 Preferences 实例，并删除对应的持久化文件，调用preferences.deletePreferences(context, options)接口 ；若只是从缓存中移除实例，不删除文件，使用preferences.removePreferencesFromCacheSync(context, name)接口 。这在清理不再使用的数据时非常有用。

五、实战：开发步骤详解

（一）导入用户首选项模块

在使用用户首选项进行数据持久化开发时，第一步就是导入相关模块。在 ArkTS 中，通过 下面内容语句导入用户首选项模块：

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

这行代码就像是打开了一个装满工具的宝箱，后续对用户首选项的各种操作，都要依赖这个导入的模块。它为我们提供了一系列操 影响户首选项的 技巧和接口，是整个开发流程的基础。 例如，如果没有导入这个模块，就无法获取 Preferences 实例，更无法进行数据的读写等操作 。

（二）获取 Preferences 实例

获取 Preferences 实例是进行数据操作的关键一步，在 HarmonyOS 中，根据应用模型的不同，获取方式略有差异。

Stage 模型：在 Stage 模型下，可以在UIAbility的onWindowStageCreate 生活周期函数中获取。示例代码如下：

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

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

class EntryAbility extends UIAbility {

onWindowStageCreate(windowStage) {

let options = {name: 'examplePreferences'};

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

// 后续可使用preferences进行数据操作

}

}

这里的this.context表示应用上下文，它包含了应用的各种环境信息，通过它可以获取到应用的各种资源和服务 。options 一个对象，其中name属性指定了 Preferences 实例的名称，就好比给这个数据仓库取了个 特殊的名字，方便后续识别和管理 。通过getPreferencesSync 技巧，就能获取到对应的 Preferences 实例。

FA 模型：在 FA 模型中，获取方式如下：

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

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

let context = featureAbility.getContext();

let options = {name: 'examplePreferences'};

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

同样，先通过featureAbility.getContext()获取应用上下文，再结合options对象，使用getPreferencesSync 技巧获取 Preferences 实例 。

（三）写入数据

获取到 Preferences 实例后，就可以使用putSync 技巧将数据保存到缓存的 Preferences 实例中。假设我们要保存用户设置的主题模式，代码如下：

let themeMode = 'dark';

preferences.putSync('themeMode', themeMode);

这里'themeMode'是键，themeMode变量的值'dark'是对应的值 。当对应的键已经存在时，putSync 技巧会修改其值。如果不确定某个键是否存在，可以使用hasSync 技巧检查 。比如：

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

console.info('The key 'themeMode' is already contained.');

} else {

console.info('The key 'themeMode' does not exist, will add it.');

preferences.putSync('themeMode', themeMode);

}

在写入数据后，如果希望将 Preferences 实例的数据存储到持久化文件，以便在应用重启后数据依然存在，就需要调用flush 技巧 。flush 技巧是异步的，它会返回一个 Promise 对象，我们可以通过then和catch 技巧来处理操作的 结局：

preferences.flush().then(() => {

console.log('数据已成功持久化到文件');

}).catch((error) => {

console.error('持久化数据时出错:', error);

});

（四）读取数据

从 Preferences 实例中读取数据，使用getSync 技巧。该 技巧接受两个参数，第一个参数是要获取的数据对应的键，第二个参数是默认值，当键不存在或者对应的值为 null、非默认值类型时，返回这个默认值 。例如，读取刚才保存的主题模式：

let themeMode = preferences.getSync('themeMode', 'light');

console.log('当前主题模式为:', themeMode);

如果获取到的值是带有 独特字符的字符串， 并且存储时转换为了Uint8Array类型，读取时需要再转换回字符串 。示例代码如下：

import util from '@ohos.util';

let uInt8Array : dataPreferences.ValueType = preferences.getSync('uInt8', new Uint8Array(0));

let textDecoder = util.TextDecoder.create('utf-8');

let specialStr = textDecoder.decodeWithStream(uInt8Array as Uint8Array);

console.log('获取到的 独特字符串为:', specialStr);

（五）删除数据

若要从 Preferences 实例中删除指定的键值对，使用deleteSync 技巧 。比如，要删除一个不再使用的临时配置数据：

preferences.deleteSync('tempConfigKey');

调用该 技巧后，只是在内存中的 Preferences 实例里删除了对应的键值对。如果想要将文件中的数据也删除，同样需要调用flush 技巧 ，以确保持久化文件中的数据也被更新：

preferences.deleteSync('tempConfigKey');

preferences.flush().then(() => {

console.log('指定键值对已成功从文件中删除');

}).catch((error) => {

console.error('删除文件中的键值对时出错:', error);

});

（六）数据持久化

前面提到，调用flush 技巧可以实现数据持久化 。其原理是将缓存的 Preferences 实例中的数据异步存储到本地文件中 。在实际开发中，一般在数据发生重要变更，或者应用在某些关键 生活周期节点（比如应用进入后台、即将关闭等）时调用flush 技巧 。完整代码示例如下：

preferences.putSync('newDataKey', 'newDataValue');

preferences.flush().then(() => {

console.log('新数据已成功持久化');

}).catch((error) => {

console.error('持久化新数据时出错:', error);

});

在这个 经过中，可能会 由于文件读写权限 难题、磁盘空间不足等 缘故导致持久化失败 。 因此在catch回调中，需要对错误进行处理，比如记录错误日志，以便后续排查 难题。

（七）订阅数据变更

应用可以通过订阅数据变更，来实时感知 Preferences 实例中数据的变化 。使用on 技巧来订阅数据变更事件，指定一个回调 技巧observer 。当订阅的数据发生变更并调用flush 技巧时，observer会被触发回调 。示例代码如下：

let observer = (changedKey) => {

console.log(`数据发生变更，变更的键为: ${changedKey}`);

};

preferences.on('change', observer);

// 模拟数据变更

preferences.putSync('themeMode', 'light');

preferences.flush();

在上述代码中，定义了一个observer回调函数，当themeMode键对应的数据发生变更并执行flush后，就会在控制台输出变更的键名 。如果不再需要订阅数据变更，可以使用off 技巧取消订阅 。

（八）删除指定文件

如果确定某个 Preferences 实例及其对应的持久化文件不再需要，可以使用deletePreferences 技巧从内存中移除指定文件对应的 Preferences 实例，包括内存中的数据 。若该 Preference 存在对应的持久化文件，则同时删除该持久化文件，包括指定文件及其备份文件、损坏文件 。示例代码如下：

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

import application from '@ohos.application';

let context = application.getContext();

let options = {name: 'examplePreferences'};

dataPreferences.deletePreferences(context, options, (err) => {

if (err) {

console.error('删除Preferences实例及文件失败:', err);

} else {

console.log('成功删除Preferences实例及文件');

}

});

需要注意的是，调用该接口后，应用不允许再使用该 Preferences 实例进行数据操作，否则会出现数据一致性 难题 。而且成功删除后，数据及文件将不可恢复， 因此在执行此操作时一定要谨慎确认 。

六、 拓展资料与展望

通过用户首选项实现数据持久化，为 HarmonyOS 应用开发者提供了一种简洁高效的轻量级数据存储解决方案 。我们一起回顾了从导入用户首选项模块开始，逐步获取 Preferences 实例，进行数据的写入、读取、删除、持久化，以及订阅数据变更和删除指定文件的全流程开发步骤 。在这个 经过中，掌握获取 Preferences 实例的 技巧是关键，不同的应用模型（Stage 模型和 FA 模型）有着各自对应的获取方式 。

写入数据时，要注意putSync 技巧对已存在键值对的处理，以及flush 技巧实现数据持久化的时机 。读取数据时，利用getSync 技巧及其默认值参数，能灵活应对键不存在或值类型不符的情况 。删除数据时，务必记得调用flush 技巧确保文件数据也被更新 。订阅数据变更能让应用实时感知数据变化，为用户提供更智能的交互体验 。而删除指定文件则为清理不再使用的数据提供了途径，但操作时一定要谨慎，避免误删重要数据 。

希望各位开发者能将今天所学运用到实际项目中，无论是开发工具类应用记录用户的常用设置，还是社交类应用保存用户的 特点化偏好，用户首选项都能发挥重要 影响 。同时，也期待大家在 操作中不断探索更多的应用场景和优化方案，充分挖掘 HarmonyOS 数据持久化的潜力，为用户带来更优质、更流畅的应用体验 。如果在开发 经过中遇到任何 难题，欢迎在评论区留言交流，让我们一起在 HarmonyOS 开发的道路上共同 提高 。