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![preferences](figures/preferences.jpg)
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-->