1# 通过用户首选项实现数据持久化 (ArkTS) 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用户首选项默认使用XML格式进行存储，从API version 18开始，可选择GSKV存储模式。 21 22### XML存储 23XML存储指的是数据会以XML的形式存储到文件中，该模式的优点是通用性强，支持跨平台。当选择该模式时，首选项对数据的操作主要发生在内存中，开发者可以在需要的时候再调用flush接口进行数据持久化。针对单进程、小数据量场景，推荐使用该存储模式。 24 25### GSKV存储 26GSKV是从API version 18起提供的一种存储模式，该模式的优点是支持多进程并发读写。当选择该模式时，首选项对数据的操作会实时落盘。针对多进程并发场景，推荐使用该存储模式。 27 28## 约束限制 29 30### 首选项通用限制 31 32- Key键为string类型，要求非空且长度不超过1024个字节。 33 34- 如果Value值为string类型，请使用UTF-8编码格式，可以为空，不为空时长度不超过16MB。 35 36- 当存储的数据中包含非UTF-8格式的字符串时，请使用Uint8Array类型存储，否则会造成持久化文件出现格式错误造成文件损坏。 37 38- 当调用removePreferencesFromCache或者deletePreferences后，订阅的数据变更会主动取消订阅，重新getPreferences后需要重新订阅数据变更。 39 40- 不允许deletePreferences与其他接口多线程、多进程并发调用，否则会发生不可预期行为。 41 42### XML模式约束限制 43 44- XML模式（首选项的默认模式）无法保证进程并发安全，会有文件损坏和数据丢失的风险，不支持在多进程场景下使用。 45 46- 内存会随着存储数据量的增大而增大，所以存储的数据量应该是轻量级的，建议存储的数据不超过50MB，当存储的数据较大时，在使用同步接口创建Preferences对象和持久化数据时会变成耗时操作，不建议在主线程中使用，否则可能出现appfreeze问题。 47 48### GSKV模式约束限制 49 50- GSKV模式不支持跨平台，使用该模式前需调用isStorageTypeSupported接口判断当前平台是否支持该模式。 51- 在OpenHarmony中，用户组（Group）是具有相同特征用户的逻辑集合，这些用户共享一定的权限。用户组的概念主要是为了方便系统管理和控制用户的访问权限。 多进程使用GSKV模式首选项时，若涉及group权限，需确保不同进程属于同一group权限。 52 53 54 55## 接口说明 56 57以下是用户首选项持久化功能的相关接口，更多接口及使用方式请见[用户首选项](../reference/apis-arkdata/js-apis-data-preferences.md)。 58 59| 接口名称 | 描述 | 60| ------------------------------------------------------------ | ------------------------------------------------------------ | 61| getPreferencesSync(context: Context, options: Options): Preferences | 获取Preferences实例。该接口存在异步接口。 | 62| putSync(key: string, value: ValueType): void | 将数据写入Preferences实例，可通过flush将Preferences实例持久化。该接口存在异步接口。 | 63| hasSync(key: string): boolean | 检查Preferences实例是否包含名为给定Key的存储键值对，true表示包含，false表示不包含。给定的Key值不能为空。该接口存在异步接口。 | 64| getSync(key: string, defValue: ValueType): ValueType | 获取键对应的值，如果值为null或者非默认值类型，返回默认数据defValue。该接口存在异步接口。 | 65| deleteSync(key: string): void | 从Preferences实例中删除名为给定Key的存储键值对。该接口存在异步接口。 | 66| flush(callback: AsyncCallback<void>): void | 将当前Preferences实例的数据异步存储到用户首选项持久化文件中。 | 67| on(type: 'change', callback: Callback<string>): void | 订阅数据变更，订阅的数据发生变更后，在执行flush方法后，触发callback回调。 | 68| off(type: 'change', callback?: Callback<string>): void | 取消订阅数据变更。 | 69| deletePreferences(context: Context, options: Options, callback: AsyncCallback<void>): void | 从内存中移除指定的Preferences实例。若Preferences实例有对应的持久化文件，则同时删除其持久化文件。 | 70| isStorageTypeSupported(type: StorageType): boolean | 判断当前平台是否支持希望使用的存储模式。true表示支持，false表示不支持。| 71 72 73## 开发步骤 74 751. 导入`@kit.ArkData`模块。 76 77 ```ts 78 import { preferences } from '@kit.ArkData'; 79 ``` 80 812. （可选）选择存储模式。 82 83 该步骤为可选步骤。首选项默认使用XML模式存储数据，从API version 18开始，新增提供并支持使用GSKV存储模式。 84 85 在选择GSKV存储模式之前，需要使用isStorageTypeSupported()接口判断当前平台是否支持GSKV模式。 86 87 若接口返回false，则说明当前平台不支持GSKV模式，请使用XML模式进行数据存储。 88 89 ```ts 90 let isGskvSupported = preferences.isStorageTypeSupported(preferences.StorageType.GSKV); 91 console.info("Is gskv supported on this platform: " + isGskvSupported); 92 ``` 93 943. 获取Preferences实例。 95 96 使用默认的XML存储模式获取Preferences实例。 97 98 <!--Del-->Stage模型示例：<!--DelEnd--> 99 100 ```ts 101 import { UIAbility } from '@kit.AbilityKit'; 102 import { BusinessError } from '@kit.BasicServicesKit'; 103 import { window } from '@kit.ArkUI'; 104 105 let dataPreferences: preferences.Preferences | null = null; 106 107 class EntryAbility extends UIAbility { 108 onWindowStageCreate(windowStage: window.WindowStage) { 109 let options: preferences.Options = { name: 'myStore' }; 110 dataPreferences = preferences.getPreferencesSync(this.context, options); 111 } 112 } 113 ``` 114 115 <!--Del-->FA模型示例： 116 117 ```ts 118 // 获取context 119 import { featureAbility } from '@kit.AbilityKit'; 120 import { BusinessError } from '@kit.BasicServicesKit'; 121 122 let context = featureAbility.getContext(); 123 let options: preferences.Options = { name: 'myStore' }; 124 let dataPreferences: preferences.Preferences = preferences.getPreferencesSync(context, options); 125 ``` 126 <!--DelEnd--> 127 128 使用GSKV存储模式获取Preferences实例。 129 130 若希望使用GSKV存储模式且当前平台支持该模式，可以通过以下方式获取GSKV存储模式的Preferences实例。需要注意的是，当选择某一存储模式后，不允许再对存储模式进行切换。 131 <!--Del-->Stage模型示例：<!--DelEnd--> 132 133 ```ts 134 import { UIAbility } from '@kit.AbilityKit'; 135 import { BusinessError } from '@kit.BasicServicesKit'; 136 import { window } from '@kit.ArkUI'; 137 138 let dataPreferences: preferences.Preferences | null = null; 139 140 class EntryAbility extends UIAbility { 141 onWindowStageCreate(windowStage: window.WindowStage) { 142 let options: preferences.Options = { name: 'myStore' , storageType: preferences.StorageType.GSKV}; 143 dataPreferences = preferences.getPreferencesSync(this.context, options); 144 } 145 } 146 ``` 147 148 <!--Del-->FA模型示例： 149 150 ```ts 151 // 获取context 152 import { featureAbility } from '@kit.AbilityKit'; 153 import { BusinessError } from '@kit.BasicServicesKit'; 154 155 let context = featureAbility.getContext(); 156 let options: preferences.Options = { name: 'myStore' , storageType: preferences.StorageType.GSKV}; 157 let dataPreferences: preferences.Preferences = preferences.getPreferencesSync(context, options); 158 ``` 159 <!--DelEnd--> 160 161 1624. 写入数据。 163 164 使用putSync()方法保存数据到缓存的Preferences实例中。 165 166 针对默认存储模式（XML存储模式），在写入数据后，如有需要，可使用flush()方法将Preferences实例的数据存储到持久化文件。 167 168 针对GSKV存储模式，在写入数据后，数据会实时持久化到文件中。 169 170 > **说明：** 171 > 172 > 当对应的键已经存在时，putSync()方法会覆盖其值。可以使用hasSync()方法检查是否存在对应键值对。 173 174 示例代码如下所示： 175 176 ```ts 177 import { util } from '@kit.ArkTS'; 178 if (dataPreferences.hasSync('startup')) { 179 console.info("The key 'startup' is contained."); 180 } else { 181 console.info("The key 'startup' does not contain."); 182 // 此处以此键值对不存在时写入数据为例 183 dataPreferences.putSync('startup', 'auto'); 184 // 当字符串有特殊字符时，需要将字符串转为Uint8Array类型再存储，长度均不超过16 * 1024 * 1024个字节。 185 let uInt8Array1 = new util.TextEncoder().encodeInto("~！@#￥%……&*（）——+？"); 186 dataPreferences.putSync('uInt8', uInt8Array1); 187 } 188 ``` 189 1905. 读取数据。 191 192 使用getSync()方法获取数据，即指定键对应的值。如果值为null或者非默认值类型，则返回默认数据。 193 194 示例代码如下所示： 195 196 ```ts 197 let val = dataPreferences.getSync('startup', 'default'); 198 console.info("The 'startup' value is " + val); 199 // 当获取的值为带有特殊字符的字符串时，需要将获取到的Uint8Array转换为字符串 200 let uInt8Array2 : preferences.ValueType = dataPreferences.getSync('uInt8', new Uint8Array(0)); 201 let textDecoder = util.TextDecoder.create('utf-8'); 202 val = textDecoder.decodeToString(uInt8Array2 as Uint8Array); 203 console.info("The 'uInt8' value is " + val); 204 ``` 205 2066. 删除数据。 207 208 使用deleteSync()方法删除指定键值对，示例代码如下所示： 209 210 ```ts 211 dataPreferences.deleteSync('startup'); 212 ``` 213 2147. 数据持久化。 215 216 应用存入数据到Preferences实例后，可以使用flush()方法实现数据持久化。示例代码如下所示： 217 218 ```ts 219 dataPreferences.flush((err: BusinessError) => { 220 if (err) { 221 console.error(`Failed to flush. Code:${err.code}, message:${err.message}`); 222 return; 223 } 224 console.info('Succeeded in flushing.'); 225 }) 226 ``` 227 2288. 订阅数据变更。 229 230 应用订阅数据变更需要指定observer作为回调方法。 231 232 针对首选项的默认存储模式（XML存储模式），订阅的Key值发生变更后，当执行flush()方法时，observer被触发回调。 233 234 示例代码如下所示： 235 236 ```ts 237 let observer = (key: string) => { 238 console.info('The key' + key + 'changed.'); 239 } 240 dataPreferences.on('change', observer); 241 // 数据产生变更，由'auto'变为'manual' 242 dataPreferences.put('startup', 'manual', (err: BusinessError) => { 243 if (err) { 244 console.error(`Failed to put the value of 'startup'. Code:${err.code},message:${err.message}`); 245 return; 246 } 247 console.info("Succeeded in putting the value of 'startup'."); 248 if (dataPreferences !== null) { 249 dataPreferences.flush((err: BusinessError) => { 250 if (err) { 251 console.error(`Failed to flush. Code:${err.code}, message:${err.message}`); 252 return; 253 } 254 console.info('Succeeded in flushing.'); 255 }) 256 } 257 }) 258 ``` 259 260 针对GSKV存储模式，订阅的Key值发生变更后（无需调用flush），observer被触发回调。 261 262 示例代码如下所示： 263 ```ts 264 let observer = (key: string) => { 265 console.info('The key' + key + 'changed.'); 266 } 267 dataPreferences.on('change', observer); 268 // 数据产生变更，由'auto'变为'manual' 269 dataPreferences.put('startup', 'manual', (err: BusinessError) => { 270 if (err) { 271 console.error(`Failed to put the value of 'startup'. Code:${err.code},message:${err.message}`); 272 return; 273 } 274 console.info("Succeeded in putting the value of 'startup'."); 275 }) 276 ``` 2779. 删除指定文件。 278 279 使用deletePreferences()方法从内存中移除指定文件对应的Preferences实例，包括内存中的数据。若该Preference存在对应的持久化文件，则同时删除该持久化文件，包括指定文件及其备份文件、损坏文件。 280 281 > **说明：** 282 > 283 > - 调用该接口后，应用不允许再使用该Preferences实例进行数据操作，否则会出现数据一致性问题。 284 > 285 > - 成功删除后，数据及文件将不可恢复。 286 > 287 > - 在GSKV模式中，该接口不支持与其他接口并发调用（包括多进程），否则会出现不可预期行为。 288 289 示例代码如下所示： 290 291 ```ts 292 preferences.deletePreferences(this.context, options, (err: BusinessError) => { 293 if (err) { 294 console.error(`Failed to delete preferences. Code:${err.code}, message:${err.message}`); 295 return; 296 } 297 console.info('Succeeded in deleting preferences.'); 298 }) 299 ``` 300 301## 相关实例 302 303针对用户首选项开发，有以下相关实例可供参考： 304 305- [游戏2048（ArkTS）（API9）](https://gitee.com/openharmony/applications_app_samples/tree/master/code/Solutions/Game/Game2048) 306 307- [图案密码锁（ArkTS）（API9）](https://gitee.com/openharmony/applications_app_samples/tree/master/code/Solutions/Tools/PatternLock) 308 309- [首选项（ArkTS）（API9）](https://gitee.com/openharmony/applications_app_samples/tree/master/code/BasicFeature/DataManagement/Preferences) 310 311- [首选项（ArkTS）（API9）](https://gitee.com/openharmony/codelabs/tree/master/Data/Preferences) 312 313- [用户首选项（JS）（API9）](https://gitee.com/openharmony/codelabs/tree/master/Data/PreferenceJS) 314 315- [备忘录（ArkTS）（API9）](https://gitee.com/openharmony/codelabs/tree/master/Data/NotePadOpenHarmony) 316 317- [应用的首次启动（ArkTS）（API9）](https://gitee.com/openharmony/codelabs/tree/master/Data/FirstStartDemo) 318 319- [应用内字体大小调节（ArkTS）（API9）](https://gitee.com/openharmony/codelabs/tree/master/Data/SetAppFontSize) 320 321<!--RP1--><!--RP1End-->
