1# 首选项开发指导 2 3> **说明：** 4> 5> 该功能特性从API Version 9开始支持。API Version 9之前可使用[轻量级存储](../reference/apis/js-apis-data-storage.md)的相关功能接口。 6 7## 场景介绍 8 9首选项功能通常用于保存应用的一些常用配置信息，并不适合需要存储大量数据和频繁改变数据的场景。应用的数据保存在文件中，这些文件可以持久化地存储在设备上。 10 11需要注意的是，应用访问的实例包含文件所有数据，这些数据会一直加载在设备的内存中，直到应用主动从内存中将其移除前，应用都可以通过Preferences API进行相关数据操作。 12 13## 接口说明 14 15首选项为应用提供Key-Value键值型的文件数据处理能力，支持应用持久化轻量级数据，并对其修改和查询。 16 17数据存储形式为键值对，键的类型为字符串型，值的存储数据类型包括数字型、字符型、布尔型以及这3种类型的数组类型。 18 19更多首选项相关接口，请见[首选项API](../reference/apis/js-apis-data-preferences.md)。 20 21### 创建存储实例 22 23读取指定文件，将数据加载到Preferences实例，即可创建一个存储实例，用于数据操作。 24 25**表1** 首选项实例创建接口 26 27| 包名 | 接口名 | 描述 | 28| --------------------- | ------------------------------------------------------------ | ------------------------------------------------------------ | 29| ohos.data.preferences | getPreferences(context: Context, name: string): Promise\<Preferences> | 读取指定首选项持久化文件，将数据加载到Preferences实例，用于数据操作。 | 30 31### 数据处理 32 33通过put系列方法，可以增加或修改Preferences实例中的数据。 34 35通过调用get系列方法，可以读取Preferences中的数据。 36 37通过调用getAll系列方法，可以获取Preferences中包含所有键值的Object对象。 38 39通过调用delete系列方法，可以删除Preferences中名为给定Key的存储键值对。 40 41**表2** 首选项数据处理接口 42 43| 类名 | 接口名 | 描述 | 44| ----------- | ---------------------------------------------------------- | ------------------------------------------------------------ | 45| Preferences | put(key: string, value: ValueType): Promise\<void> | 支持存入值为number、string、boolean、Array\<number>、Array\<string>、Array\<boolean>类型的数据。 | 46| Preferences | get(key: string, defValue: ValueType): Promise\<ValueType> | 支持获取值为number、string、boolean、Array\<number>、Array\<string>、Array\<boolean>类型的数据。 | 47| Preferences | getAll(): Promise\<Object> | 支持获取含有所有键值的Object对象。 | 48| Preferences | delete(key: string): Promise\<void> | 支持从Preferences实例中删除名为给定Key的存储键值对。 | 49 50 51### 数据持久化 52 53通过执行flush方法，应用可以将缓存的数据再次写回文本文件中进行持久化存储。 54 55**表4** 首选项持久化接口 56 57| 类名 | 接口名 | 描述 | 58| ----------- | ----------------------- | ------------------------------------------- | 59| Preferences | flush(): Promise\<void> | 将Preferences实例通过异步线程回写入文件中。 | 60 61### 订阅数据变更 62 63订阅数据变更，订阅的Key的值发生变更后，在执行flush方法后，会触发callback回调。 64 65**表5** 首选项变化订阅接口 66 67| 类名 | 接口名 | 描述 | 68| ----------- | ------------------------------------------------------------ | -------------- | 69| Preferences | on(type: 'change', callback: Callback<{ key : string }>): void | 订阅数据变更。 | 70| Preferences | off(type: 'change', callback: Callback<{ key : string }>): void | 注销订阅。 | 71 72### 删除数据文件 73 74通过调用以下两种接口，可以删除数据实例或对应的文件。 75 76**表6** 首选项删除接口 77 78| 包名 | 接口名 | 描述 | 79| --------------------- | ------------------------------------------------------------ | ------------------------------------------------------------ | 80| ohos.data.preferences | deletePreferences(context: Context, name: string): Promise\<void> | 从缓存中移除已加载的Preferences对象，同时从设备上删除对应的文件。 | 81| ohos.data.preferences | removePreferencesFromCache(context: Context, name: string): Promise\<void> | 仅从缓存中移除已加载的Preferences对象，主要用于释放内存。 | 82 83## 开发步骤 84 851. 准备工作，导入@ohos.data.preferences以及相关的模块到开发环境。 86 87 ```js 88 import data_preferences from '@ohos.data.preferences'; 89 ``` 90 912. 获取Preferences实例。 92 93 读取指定文件，将数据加载到Preferences实例，用于数据操作。 94 95 FA模型示例： 96 97 ```js 98 // 获取context 99 import featureAbility from '@ohos.ability.featureAbility' 100 let context = featureAbility.getContext(); 101 102 let preferences = null; 103 let promise = data_preferences.getPreferences(context, 'mystore'); 104 105 promise.then((pref) => { 106 preferences = pref; 107 }).catch((err) => { 108 console.info("Failed to get preferences."); 109 }) 110 ``` 111 112 Stage模型示例： 113 114 ```ts 115 // 获取context 116 import UIAbility from '@ohos.app.ability.UIAbility'; 117 let preferences = null; 118 export default class EntryAbility extends UIAbility { 119 onWindowStageCreate(windowStage) { 120 let promise = data_preferences.getPreferences(this.context, 'mystore'); 121 promise.then((pref) => { 122 preferences = pref; 123 }).catch((err) => { 124 console.info("Failed to get preferences."); 125 }) 126 } 127 } 128 129 130 ``` 131 1323. 存入数据。 133 134 使用put方法保存数据到缓存的实例中。 135 136 ```js 137 let putPromise = preferences.put('startup', 'auto'); 138 putPromise.then(() => { 139 console.info("Succeeded in putting the value of 'startup'."); 140 }).catch((err) => { 141 console.info("Failed to put the value of 'startup'. Cause: " + err); 142 }) 143 ``` 144 1454. 读取数据。 146 147 使用get方法读取数据。 148 149 ```js 150 let getPromise = preferences.get('startup', 'default'); 151 getPromise.then((value) => { 152 console.info("The value of 'startup' is " + value); 153 }).catch((err) => { 154 console.info("Failed to get the value of 'startup'. Cause: " + err); 155 }) 156 ``` 157 1585. 数据持久化。 159 160 应用存入数据到Preferences实例后，可以通过flush方法将Preferences实例回写到文件中。 161 162 ```js 163 preferences.flush(); 164 ``` 165 1666. 订阅数据变更。 167 168 应用订阅数据变更需要指定observer作为回调方法。订阅的Key的值发生变更后，当执行flush方法时，observer被触发回调。 169 170 ```js 171 let observer = function (key) { 172 console.info("The key" + key + " changed."); 173 } 174 preferences.on('change', observer); 175 // 数据产生变更，由'auto'变为'manual' 176 preferences.put('startup', 'manual', function (err) { 177 if (err) { 178 console.info("Failed to put the value of 'startup'. Cause: " + err); 179 return; 180 } 181 console.info("Succeeded in putting the value of 'startup'."); 182 preferences.flush(function (err) { 183 if (err) { 184 console.info("Failed to flush. Cause: " + err); 185 return; 186 } 187 console.info("Succeeded in flushing."); // observer will be called. 188 }) 189 }) 190 ``` 191 1927. 删除指定文件。 193 194 使用deletePreferences方法从内存中移除指定文件对应的Preferences单实例，并删除指定文件及其备份文件、损坏文件。删除指定文件时，应用不允许再使用该实例进行数据操作，否则会出现数据一致性问题。删除后，数据及文件将不可恢复。 195 196 ```js 197 let proDelete = data_preferences.deletePreferences(context, 'mystore'); 198 proDelete.then(() => { 199 console.info("Succeeded in deleting."); 200 }).catch((err) => { 201 console.info("Failed to delete. Cause: " + err); 202 }) 203 ``` 204 205## 相关实例 206 207针对首选项开发，有以下相关实例可供参考： 208 209- [`Preferences`：首选项（ArkTS）（API9）](https://gitee.com/openharmony/applications_app_samples/tree/OpenHarmony-3.2-Release/data/Preferences) 210 211- [首选项（ArkTS）（API9）](https://gitee.com/openharmony/codelabs/tree/master/Data/Preferences)