1# 通过用户首选项实现数据持久化 2 3 4## 场景介绍 5 6用户首选项为应用提供Key-Value键值型的数据处理能力,支持应用持久化轻量级数据,并对其修改和查询。当用户希望有一个全局唯一存储的地方,可以采用用户首选项来进行存储。Preferences会将该数据缓存在内存中,当用户读取的时候,能够快速从内存中获取数据,当需要持久化时可以使用flush接口将内存中的数据写入持久化文件中。Preferences会随着存放的数据量越多而导致应用占用的内存越大,因此,Preferences不适合存放过多的数据,也不支持通过配置加密,适用的场景一般为应用保存用户的个性化设置(字体大小,是否开启夜间模式)等。 7 8 9## 运作机制 10 11如图所示,用户程序通过ArkTS接口调用用户首选项读写对应的数据文件。开发者可以将用户首选项持久化文件的内容加载到Preferences实例,每个文件唯一对应到一个Preferences实例,系统会通过静态容器将该实例存储在内存中,直到主动从内存中移除该实例或者删除该文件。 12 13应用首选项的持久化文件保存在应用沙箱内部,可以通过context获取其路径。具体可见[获取应用文件路径](../application-models/application-context-stage.md#获取应用文件路径)。 14 15**图1** 用户首选项运作机制 16 17 18 19 20## 约束限制 21 22- 首选项无法保证进程并发安全,会有文件损坏和数据丢失的风险,不支持在多进程场景下使用。 23 24- Key键为string类型,要求非空且长度不超过1024个字节。 25 26- 如果Value值为string类型,请使用UTF-8编码格式,可以为空,不为空时长度不超过16MB。 27 28- 当存储的数据中包含非UTF-8格式的字符串时,请使用Uint8Array类型存储,否则会造成持久化文件出现格式错误造成文件损坏。 29 30- 当调用removePreferencesFromCache或者deletePreferences后,订阅的数据变更会主动取消订阅,重新getPreferences后需要重新订阅数据变更。 31 32- 不允许deletePreferences与其他接口多线程、多进程并发调用,否则会发生不可预期行为。 33 34- 内存会随着存储数据量的增大而增大,所以存储的数据量应该是轻量级的,建议存储的数据不超过50MB,当存储的数据较大时,在使用同步接口创建Preferences对象和持久化数据时会变成耗时操作,不建议在主线程中使用,否则可能出现appfreeze问题。 35 36 37## 接口说明 38 39以下是用户首选项持久化功能的相关接口,更多接口及使用方式请见[用户首选项](../reference/apis-arkdata/js-apis-data-preferences.md)。 40 41| 接口名称 | 描述 | 42| ------------------------------------------------------------ | ------------------------------------------------------------ | 43| getPreferencesSync(context: Context, options: Options): Preferences | 获取Preferences实例。该接口存在异步接口。 | 44| putSync(key: string, value: ValueType): void | 将数据写入Preferences实例,可通过flush将Preferences实例持久化。该接口存在异步接口。 | 45| hasSync(key: string): boolean | 检查Preferences实例是否包含名为给定Key的存储键值对。给定的Key值不能为空。该接口存在异步接口。 | 46| getSync(key: string, defValue: ValueType): ValueType | 获取键对应的值,如果值为null或者非默认值类型,返回默认数据defValue。该接口存在异步接口。 | 47| deleteSync(key: string): void | 从Preferences实例中删除名为给定Key的存储键值对。该接口存在异步接口。 | 48| flush(callback: AsyncCallback<void>): void | 将当前Preferences实例的数据异步存储到用户首选项持久化文件中。 | 49| on(type: 'change', callback: Callback<string>): void | 订阅数据变更,订阅的数据发生变更后,在执行flush方法后,触发callback回调。 | 50| off(type: 'change', callback?: Callback<string>): void | 取消订阅数据变更。 | 51| deletePreferences(context: Context, options: Options, callback: AsyncCallback<void>): void | 从内存中移除指定的Preferences实例。若Preferences实例有对应的持久化文件,则同时删除其持久化文件。 | 52 53 54## 开发步骤 55 561. 导入`@kit.ArkData`模块。 57 58 ```ts 59 import { preferences } from '@kit.ArkData'; 60 ``` 61 622. 获取Preferences实例。 63 64 <!--Del-->Stage模型示例:<!--DelEnd--> 65 66 67 ```ts 68 import { UIAbility } from '@kit.AbilityKit'; 69 import { BusinessError } from '@kit.BasicServicesKit'; 70 import { window } from '@kit.ArkUI'; 71 72 let dataPreferences: preferences.Preferences | null = null; 73 74 class EntryAbility extends UIAbility { 75 onWindowStageCreate(windowStage: window.WindowStage) { 76 let options: preferences.Options = { name: 'myStore' }; 77 dataPreferences = preferences.getPreferencesSync(this.context, options); 78 } 79 } 80 ``` 81 82 <!--Del-->FA模型示例: 83 84 85 ```ts 86 // 获取context 87 import { featureAbility } from '@kit.AbilityKit'; 88 import { BusinessError } from '@kit.BasicServicesKit'; 89 90 let context = featureAbility.getContext(); 91 let options: preferences.Options = { name: 'myStore' }; 92 let dataPreferences: preferences.Preferences = preferences.getPreferencesSync(context, options); 93 ``` 94<!--DelEnd--> 95 963. 写入数据。 97 98 使用putSync()方法保存数据到缓存的Preferences实例中。在写入数据后,如有需要,可使用flush()方法将Preferences实例的数据存储到持久化文件。 99 100 > **说明:** 101 > 102 > 当对应的键已经存在时,putSync()方法会覆盖其值。可以使用hasSync()方法检查是否存在对应键值对。 103 104 示例代码如下所示: 105 106 ```ts 107 import { util } from '@kit.ArkTS'; 108 if (dataPreferences.hasSync('startup')) { 109 console.info("The key 'startup' is contained."); 110 } else { 111 console.info("The key 'startup' does not contain."); 112 // 此处以此键值对不存在时写入数据为例 113 dataPreferences.putSync('startup', 'auto'); 114 // 当字符串有特殊字符时,需要将字符串转为Uint8Array类型再存储 115 let uInt8Array1 = new util.TextEncoder().encodeInto("~!@#¥%……&*()——+?"); 116 dataPreferences.putSync('uInt8', uInt8Array1); 117 } 118 ``` 119 1204. 读取数据。 121 122 使用getSync()方法获取数据,即指定键对应的值。如果值为null或者非默认值类型,则返回默认数据。 123 124 示例代码如下所示: 125 126 ```ts 127 let val = dataPreferences.getSync('startup', 'default'); 128 console.info("The 'startup' value is " + val); 129 // 当获取的值为带有特殊字符的字符串时,需要将获取到的Uint8Array转换为字符串 130 let uInt8Array2 : preferences.ValueType = dataPreferences.getSync('uInt8', new Uint8Array(0)); 131 let textDecoder = util.TextDecoder.create('utf-8'); 132 val = textDecoder.decodeToString(uInt8Array2 as Uint8Array); 133 console.info("The 'uInt8' value is " + val); 134 ``` 135 1365. 删除数据。 137 138 使用deleteSync()方法删除指定键值对,示例代码如下所示: 139 140 141 ```ts 142 dataPreferences.deleteSync('startup'); 143 ``` 144 1456. 数据持久化。 146 147 应用存入数据到Preferences实例后,可以使用flush()方法实现数据持久化。示例代码如下所示: 148 149 ```ts 150 dataPreferences.flush((err: BusinessError) => { 151 if (err) { 152 console.error(`Failed to flush. Code:${err.code}, message:${err.message}`); 153 return; 154 } 155 console.info('Succeeded in flushing.'); 156 }) 157 ``` 158 1597. 订阅数据变更。 160 161 应用订阅数据变更需要指定observer作为回调方法。订阅的Key值发生变更后,当执行flush()方法时,observer被触发回调。示例代码如下所示: 162 163 ```ts 164 let observer = (key: string) => { 165 console.info('The key' + key + 'changed.'); 166 } 167 dataPreferences.on('change', observer); 168 // 数据产生变更,由'auto'变为'manual' 169 dataPreferences.put('startup', 'manual', (err: BusinessError) => { 170 if (err) { 171 console.error(`Failed to put the value of 'startup'. Code:${err.code},message:${err.message}`); 172 return; 173 } 174 console.info("Succeeded in putting the value of 'startup'."); 175 if (dataPreferences !== null) { 176 dataPreferences.flush((err: BusinessError) => { 177 if (err) { 178 console.error(`Failed to flush. Code:${err.code}, message:${err.message}`); 179 return; 180 } 181 console.info('Succeeded in flushing.'); 182 }) 183 } 184 }) 185 ``` 186 1878. 删除指定文件。 188 189 使用deletePreferences()方法从内存中移除指定文件对应的Preferences实例,包括内存中的数据。若该Preference存在对应的持久化文件,则同时删除该持久化文件,包括指定文件及其备份文件、损坏文件。 190 191 > **说明:** 192 > 193 > - 调用该接口后,应用不允许再使用该Preferences实例进行数据操作,否则会出现数据一致性问题。 194 > 195 > - 成功删除后,数据及文件将不可恢复。 196 197 示例代码如下所示: 198 199 200 ```ts 201 preferences.deletePreferences(this.context, options, (err: BusinessError) => { 202 if (err) { 203 console.error(`Failed to delete preferences. Code:${err.code}, message:${err.message}`); 204 return; 205 } 206 console.info('Succeeded in deleting preferences.'); 207 }) 208 ``` 209 210## 相关实例 211 212针对用户首选项开发,有以下相关实例可供参考: 213 214- [游戏2048(ArkTS)(API9)](https://gitee.com/openharmony/applications_app_samples/tree/master/code/Solutions/Game/Game2048) 215 216- [图案密码锁(ArkTS)(API9)](https://gitee.com/openharmony/applications_app_samples/tree/master/code/Solutions/Tools/PatternLock) 217 218- [首选项(ArkTS)(API9)](https://gitee.com/openharmony/applications_app_samples/tree/master/code/BasicFeature/DataManagement/Preferences) 219 220- [首选项(ArkTS)(API9)](https://gitee.com/openharmony/codelabs/tree/master/Data/Preferences) 221 222- [用户首选项(JS)(API9)](https://gitee.com/openharmony/codelabs/tree/master/Data/PreferenceJS) 223 224- [备忘录(ArkTS)(API9)](https://gitee.com/openharmony/codelabs/tree/master/Data/NotePadOpenHarmony) 225 226- [应用的首次启动(ArkTS)(API9)](https://gitee.com/openharmony/codelabs/tree/master/Data/FirstStartDemo) 227 228- [应用内字体大小调节(ArkTS)(API9)](https://gitee.com/openharmony/codelabs/tree/master/Data/SetAppFontSize) 229 230<!--RP1--><!--RP1End-->