js-apis-data-preferences.md 21.9 KB
Newer Older
W
wangxiyue 已提交
1
# 首选项
P
PaDoBoo 已提交
2

3
首选项为应用提供key-value键值型的数据处理能力,支持应用持久化轻量级数据,并对其修改和查询。数据存储形式为键值对,键的类型为字符串型,值的存储数据类型包括数字型、字符型、布尔型以及这3种类型的数组类型。
P
PaDoBoo 已提交
4 5


P
PaDaBoo 已提交
6
> **说明:**
7
> 本模块首批接口从API version 9开始支持。后续版本的新增接口,采用上角标单独标记接口的起始版本。
P
PaDoBoo 已提交
8 9 10 11


## 导入模块

W
wangxiyue 已提交
12
```ts
13
import data_preferences from '@ohos.data.preferences';
P
PaDoBoo 已提交
14 15
```

G
ge-yafang 已提交
16
## 常量
P
PaDoBoo 已提交
17

P
PaDaBoo 已提交
18
**系统能力:** 以下各项对应的系统能力均为SystemCapability.DistributedDataManager.Preferences.Core
19

P
PaDoBoo 已提交
20 21
| 名称 | 参数类型 | 可读 | 可写 | 说明 |
| -------- | -------- | -------- | -------- | -------- |
22 23
| MAX_KEY_LENGTH | string | 是 | 否 | key的最大长度限制,需小于80字节。 |
| MAX_VALUE_LENGTH | string | 是 | 否 | value的最大长度限制,需小于8192字节。 |
P
PaDoBoo 已提交
24 25


26
## data_preferences.getPreferences
P
PaDoBoo 已提交
27

P
PaDaBoo 已提交
28
getPreferences(context: Context, name: string, callback: AsyncCallback<Preferences>): void
P
PaDoBoo 已提交
29

W
wangxiyue 已提交
30
读取指定首选项持久化文件,将数据加载到Preferences实例,用于数据操作,该方法使用callback方式作为异步方法。
P
PaDoBoo 已提交
31

P
PaDaBoo 已提交
32

P
PaDaBoo 已提交
33
**系统能力:** SystemCapability.DistributedDataManager.Preferences.Core
34

G
ge-yafang 已提交
35
**参数:**
P
PaDoBoo 已提交
36 37
  | 参数名 | 类型 | 必填 | 说明 |
  | -------- | -------- | -------- | -------- |
P
PaDaBoo 已提交
38
  | context | [Context](js-apis-ability-context.md) | 是 | 应用程序或功能的上下文。 |
P
PaDoBoo 已提交
39 40 41
  | name | string | 是 | 应用程序内部数据存储名称。 |
  | callback | AsyncCallback<[Preferences](#preferences)> | 是 | 回调函数。 |

G
ge-yafang 已提交
42
**示例:**
P
PaDaBoo 已提交
43
```ts
44
data_preferences.getPreferences(this.context, 'mystore', function (err, preferences) {
P
PaDaBoo 已提交
45 46 47 48 49 50 51
    if (err) {
        console.info("Get preferences failed.")
        return;
    }
    console.info("Get preferences successfully.")
})
```
P
PaDoBoo 已提交
52 53


54
## data_preferences.getPreferences
P
PaDoBoo 已提交
55

P
PaDaBoo 已提交
56
getPreferences(context: Context, name: string): Promise<Preferences>
P
PaDoBoo 已提交
57

W
wangxiyue 已提交
58
读取指定首选项持久化文件,将数据加载到Preferences实例,用于数据操作,该方法使用Promise方式作为异步方法。
P
PaDoBoo 已提交
59

P
PaDaBoo 已提交
60
**系统能力:** SystemCapability.DistributedDataManager.Preferences.Core
61

G
ge-yafang 已提交
62
**参数:**
P
PaDoBoo 已提交
63 64
  | 参数名 | 类型 | 必填 | 说明 |
  | -------- | -------- | -------- | -------- |
P
PaDaBoo 已提交
65
  | context | [Context](js-apis-ability-context.md) | 是 | 应用程序或功能的上下文。 |
P
PaDoBoo 已提交
66 67
  | name | string | 是 | 应用程序内部数据存储名称。 |

G
ge-yafang 已提交
68
**返回值:**
P
PaDoBoo 已提交
69 70 71 72
  | 类型 | 说明 |
  | -------- | -------- |
  | Promise<[Preferences](#preferences)> | Promise实例,用于异步获取结果。 |

G
ge-yafang 已提交
73
**示例:**
P
PaDaBoo 已提交
74
```ts
75 76
let promise = data_preferences.getPreferences(this.context, 'mystore')
promise.then((preferences) => {
P
PaDaBoo 已提交
77 78 79 80 81
    console.info("Get preferences successfully.")
}).catch((err) => {
    console.info("Get preferences failed.")
})
```
P
PaDoBoo 已提交
82 83


84
## data_preferences.deletePreferences
P
PaDoBoo 已提交
85

86
deletePreferences(context: Context, name: string, callback: AsyncCallback<void>): void
P
PaDoBoo 已提交
87

W
wangxiyue 已提交
88 89
从内存中移除指定首选项持久化文件对应的Preferences单实例,并删除指定文件及其备份文件和损坏文件。
删除指定首选项持久化文件时,应用不允许再使用该实例进行数据操作,否则会出现数据一致性问题,该方法使用callback方式作为异步方法。
P
PaDoBoo 已提交
90

P
PaDaBoo 已提交
91
**系统能力:** SystemCapability.DistributedDataManager.Preferences.Core
92

G
ge-yafang 已提交
93
**参数:**
P
PaDoBoo 已提交
94 95
  | 参数名 | 类型 | 必填 | 说明 |
  | -------- | -------- | -------- | -------- |
P
PaDaBoo 已提交
96
  | context | [Context](js-apis-ability-context.md) | 是 | 应用程序或功能的上下文。 |
P
PaDaBoo 已提交
97
  | name | string | 是 | 应用程序内部数据存储名称。 |
P
PaDoBoo 已提交
98 99
  | callback | AsyncCallback<void> | 是 | 回调函数。 |

G
ge-yafang 已提交
100
**示例:**
P
PaDaBoo 已提交
101
```ts
102
data_preferences.deletePreferences(this.context, 'mystore', function (err) {
P
PaDaBoo 已提交
103 104 105 106 107 108 109
    if (err) {
        console.info("Deleted preferences failed, err: " + err)
        return
    }
    console.info("Deleted preferences successfully.")
})
```
P
PaDoBoo 已提交
110 111


112
## data_preferences.deletePreferences
P
PaDoBoo 已提交
113

P
PaDaBoo 已提交
114
deletePreferences(context: Context, name: string): Promise<void>
P
PaDoBoo 已提交
115

W
wangxiyue 已提交
116 117
从内存中移除指定首选项持久化文件对应的Preferences单实例,并删除指定文件及其备份文件和损坏文件。
删除指定首选项持久化文件时,应用不允许再使用该实例进行数据操作,否则会出现数据一致性问题,该方法使用Promise方式作为异步方法。
P
PaDoBoo 已提交
118

P
PaDaBoo 已提交
119
**系统能力:** SystemCapability.DistributedDataManager.Preferences.Core
120

G
ge-yafang 已提交
121
**参数:**
P
PaDoBoo 已提交
122 123
  | 参数名 | 类型 | 必填 | 说明 |
  | -------- | -------- | -------- | -------- |
P
PaDaBoo 已提交
124
  | context | [Context](js-apis-ability-context.md) | 是 | 应用程序或功能的上下文。 |
P
PaDaBoo 已提交
125
  | name | string | 是 | 应用程序内部数据存储名称。 |
P
PaDoBoo 已提交
126

G
ge-yafang 已提交
127
**返回值:**
P
PaDoBoo 已提交
128 129 130 131
  | 类型 | 说明 |
  | -------- | -------- |
  | Promise<void> | Promise实例,用于异步获取结果。 |

G
ge-yafang 已提交
132
**示例:**
P
PaDaBoo 已提交
133
```ts
134
let promise = data_preferences.deletePreferences(this.context, 'mystore')
P
PaDaBoo 已提交
135 136 137 138 139 140
promise.then(() => {
    console.info("Deleted preferences successfully.")
}).catch((err) => {
    console.info("Deleted preferences failed, err: " + err)
})
```
P
PaDoBoo 已提交
141 142


143
## data_preferences.removePreferencesFromCache
P
PaDoBoo 已提交
144

145
removePreferencesFromCache(context: Context, name: string, callback: AsyncCallback<void>): void
P
PaDoBoo 已提交
146

G
ge-yafang 已提交
147 148 149
从内存中移除指定首选项持久化文件对应的Preferences单实例。

移除Preferences单实例时,应用不允许再使用该实例进行数据操作,否则会出现数据一致性问题,该方法使用callback方式作为异步方法。
P
PaDoBoo 已提交
150

P
PaDaBoo 已提交
151
**系统能力:** SystemCapability.DistributedDataManager.Preferences.Core
152

G
ge-yafang 已提交
153
**参数:**
P
PaDoBoo 已提交
154 155
  | 参数名 | 类型 | 必填 | 说明 |
  | -------- | -------- | -------- | -------- |
P
PaDaBoo 已提交
156
  | context | [Context](js-apis-ability-context.md) | 是 | 应用程序或功能的上下文。 |
P
PaDaBoo 已提交
157
  | name | string | 是 | 应用程序内部数据存储名称。 |
158
  | callback | AsyncCallback<void> | 是 | 回调函数。 |
P
PaDoBoo 已提交
159

G
ge-yafang 已提交
160
**示例:**
P
PaDaBoo 已提交
161
```ts
162
data_preferences.removePreferencesFromCache(this.context, 'mystore', function (err) {
P
PaDaBoo 已提交
163 164 165 166 167 168 169
    if (err) {
        console.info("Removed preferences from cache failed, err: " + err)
        return
    }
    console.info("Removed preferences from cache successfully.")
})
```
P
PaDoBoo 已提交
170 171


172
## data_preferences.removePreferencesFromCache
P
PaDoBoo 已提交
173

P
PaDaBoo 已提交
174
removePreferencesFromCache(context: Context, name: string): Promise<void>
P
PaDoBoo 已提交
175

G
ge-yafang 已提交
176 177 178
从内存中移除指定首选项持久化文件对应的Preferences单实例。

移除Preferences单实例时,应用不允许再使用该实例进行数据操作,否则会出现数据一致性问题,该方法使用Promise方式作为异步方法。
P
PaDoBoo 已提交
179

P
PaDaBoo 已提交
180
**系统能力:** SystemCapability.DistributedDataManager.Preferences.Core
181

G
ge-yafang 已提交
182
**参数:**
P
PaDoBoo 已提交
183 184
  | 参数名 | 类型 | 必填 | 说明 |
  | -------- | -------- | -------- | -------- |
P
PaDaBoo 已提交
185
  | context | [Context](js-apis-ability-context.md) | 是 | 应用程序或功能的上下文。 |
P
PaDaBoo 已提交
186
  | name | string | 是 | 应用程序内部数据存储名称。 |
P
PaDoBoo 已提交
187

G
ge-yafang 已提交
188
**返回值:**
P
PaDoBoo 已提交
189 190 191 192
  | 类型 | 说明 |
  | -------- | -------- |
  | Promise<void> | Promise实例,用于异步获取结果。 |

G
ge-yafang 已提交
193
**示例:**
P
PaDaBoo 已提交
194
```ts
195
let promise = data_preferences.removePreferencesFromCache(this.context, 'mystore')
P
PaDaBoo 已提交
196 197 198 199 200 201
promise.then(() => {
    console.info("Removed preferences from cache successfully.")
}).catch((err) => {
    console.info("Removed preferences from cache failed, err: " + err)
})
```
P
PaDoBoo 已提交
202 203 204 205 206 207 208 209 210 211 212


## Preferences

提供获取和修改存储数据的接口。


### get

get(key: string, defValue: ValueType, callback: AsyncCallback<ValueType>): void

W
wangxiyue 已提交
213
获取键对应的值,如果值为null或者非默认值类型,返回默认数据,该方法使用callback方式作为异步方法。
P
PaDoBoo 已提交
214

P
PaDaBoo 已提交
215
**系统能力:** SystemCapability.DistributedDataManager.Preferences.Core
216

G
ge-yafang 已提交
217
**参数:**
L
li_juntao 已提交
218 219 220 221 222
| 参数名 | 类型 | 必填 | 说明 |
| -------- | -------- | -------- | -------- |
| key | string | 是 | 要获取的存储key名称,不能为空。 |
| defValue | [ValueType](#valuetype) | 是 | 默认返回值。支持number、string、boolean、Array\<number>、Array\<string>、Array\<boolean>。 |
| callback | AsyncCallback&lt;ValueType&gt; | 是 | 回调函数。 |
P
PaDoBoo 已提交
223

G
ge-yafang 已提交
224
**示例:**
P
PaDaBoo 已提交
225
```ts
226
preferences.get('startup', 'default', function(err, value) {
P
PaDaBoo 已提交
227 228 229 230 231 232 233
    if (err) {
        console.info("Get value of startup failed, err: " + err)
        return
    }
    console.info("Get value of startup is " + value)
})
```
P
PaDoBoo 已提交
234 235 236 237 238 239


### get

get(key: string, defValue: ValueType): Promise&lt;ValueType&gt;

W
wangxiyue 已提交
240
获取键对应的值,如果值为null或者非默认值类型,返回默认数据,该方法使用Promise方式作为异步方法。
P
PaDoBoo 已提交
241

P
PaDaBoo 已提交
242
**系统能力:** SystemCapability.DistributedDataManager.Preferences.Core
243

P
PaDoBoo 已提交
244 245 246
- **参数:**
  | 参数名 | 类型 | 必填 | 说明 |
  | -------- | -------- | -------- | -------- |
W
wangxiyue 已提交
247
  | key | string | 是 | 要获取的存储key名称,不能为空。 |
L
li_juntao 已提交
248
  | defValue | [ValueType](#valuetype) | 是 | 默认返回值。支持number、string、boolean、Array\<number>、Array\<string>、Array\<boolean>。 |
P
PaDoBoo 已提交
249

G
ge-yafang 已提交
250
**返回值:**
P
PaDoBoo 已提交
251 252 253 254
  | 类型 | 说明 |
  | -------- | -------- |
  | Promise&lt;ValueType&gt; | Promise实例,用于异步获取结果。 |

G
ge-yafang 已提交
255
**示例:**
P
PaDaBoo 已提交
256
```ts
257
let promise = preferences.get('startup', 'default')
P
PaDaBoo 已提交
258 259 260 261 262 263
promise.then((value) => {
    console.info("Get value of startup is " + value)
}).catch((err) => {
    console.info("Get value of startup failed, err: " + err)
})
```
P
PaDoBoo 已提交
264

265 266 267 268
### getAll

getAll(callback: AsyncCallback&lt;Object&gt;): void;

269
返回含有所有键值的Object对象。
270 271 272 273 274 275

**系统能力:** SystemCapability.DistributedDataManager.Preferences.Core

**参数:**
  | 参数名 | 类型 | 必填 | 说明 |
  | -------- | -------- | -------- | -------- |
276
  | callback | AsyncCallback&lt;Object&gt; | 是 | 回调函数。返回含有所有键值的Object对象。 |
277 278 279

**示例:**
```ts
L
li_juntao 已提交
280
preferences.getAll(function (err, value) {
281 282 283 284 285 286 287 288 289 290 291 292 293 294 295
    if (err) {
        console.info("getAll failed, err: " + err)
        return
    }
    let keys = Object.keys(value)
    console.info('getAll keys = ' + keys)
    console.info("getAll object = " + JSON.stringify(value))
});
```


### getAll

getAll(): Promise&lt;Object&gt;

296
返回含有所有键值的Object对象。
297 298 299 300 301 302

**系统能力:** SystemCapability.DistributedDataManager.Preferences.Core

**返回值:**
  | 类型 | 说明 |
  | -------- | -------- |
303
  | Promise&lt;Object&gt; | Promise对象。返回含有所有键值的Object对象。 |
304 305 306

**示例:**
```ts
307
let promise = preferences.getAll()
308
promise.then((value) => {
309 310 311 312 313 314 315
    let keys = Object.keys(value)
    console.info('getAll keys = ' + keys)
    console.info("getAll object = " + JSON.stringify(value))
}).catch((err) => {
    console.info("getAll failed, err: " + err)
})
```
P
PaDoBoo 已提交
316 317 318 319 320

### put

put(key: string, value: ValueType, callback: AsyncCallback&lt;void&gt;): void

W
wangxiyue 已提交
321
首先获取指定首选项持久化文件对应的Preferences实例,然后借助Preferences API将数据写入Preferences实例,通过flush或者flushSync将Preferences实例持久化,该方法使用callback方式作为异步方法。
P
PaDoBoo 已提交
322

P
PaDaBoo 已提交
323
**系统能力:** SystemCapability.DistributedDataManager.Preferences.Core
324

G
ge-yafang 已提交
325
**参数:**
P
PaDoBoo 已提交
326 327
  | 参数名 | 类型 | 必填 | 说明 |
  | -------- | -------- | -------- | -------- |
W
wangxiyue 已提交
328
  | key | string | 是 | 要修改的存储的key,不能为空。 |
L
li_juntao 已提交
329
  | value | [ValueType](#valuetype) | 是 | 存储的新值。支持number、string、boolean、Array\<number>、Array\<string>、Array\<boolean>。 |
P
PaDoBoo 已提交
330 331
  | callback | AsyncCallback&lt;void&gt; | 是 | 回调函数。 |

G
ge-yafang 已提交
332
**示例:**
P
PaDaBoo 已提交
333
```ts
334
preferences.put('startup', 'auto', function (err) {
P
PaDaBoo 已提交
335 336 337 338 339 340 341
    if (err) {
        console.info("Put value of startup failed, err: " + err)
        return
    }
    console.info("Put value of startup successfully.")
})
```
P
PaDoBoo 已提交
342 343 344 345 346 347


### put

put(key: string, value: ValueType): Promise&lt;void&gt;

W
wangxiyue 已提交
348
首先获取指定首选项持久化文件对应的Preferences实例,然后借助Preferences API将数据写入Preferences实例,通过flush或者flushSync将Preferences实例持久化,该方法使用Promise方式作为异步方法。
P
PaDoBoo 已提交
349

P
PaDaBoo 已提交
350
**系统能力:** SystemCapability.DistributedDataManager.Preferences.Core
351

G
ge-yafang 已提交
352
**参数:**
P
PaDoBoo 已提交
353 354
  | 参数名 | 类型 | 必填 | 说明 |
  | -------- | -------- | -------- | -------- |
W
wangxiyue 已提交
355
  | key | string | 是 | 要修改的存储的key,不能为空。 |
L
li_juntao 已提交
356
  | value | [ValueType](#valuetype) | 是 | 存储的新值。支持number、string、boolean、Array\<number>、Array\<string>、Array\<boolean>。 |
P
PaDoBoo 已提交
357

G
ge-yafang 已提交
358
**返回值:**
P
PaDoBoo 已提交
359 360 361 362
  | 类型 | 说明 |
  | -------- | -------- |
  | Promise&lt;void&gt; | Promise实例,用于异步处理。 |

G
ge-yafang 已提交
363
**示例:**
P
PaDaBoo 已提交
364
```ts
365
let promise = preferences.put('startup', 'auto')
P
PaDaBoo 已提交
366 367 368 369 370 371
promise.then(() => {
    console.info("Put value of startup successfully.")
}).catch((err) => {
    console.info("Put value of startup failed, err: " + err)
})
```
P
PaDoBoo 已提交
372 373 374 375


### has

376
has(key: string, callback: AsyncCallback&lt;boolean&gt;): void
P
PaDoBoo 已提交
377

W
wangxiyue 已提交
378
检查存储对象是否包含名为给定key的存储键值对,该方法使用callback方式作为异步方法。
P
PaDoBoo 已提交
379

P
PaDaBoo 已提交
380
**系统能力:** SystemCapability.DistributedDataManager.Preferences.Core
381

G
ge-yafang 已提交
382
**参数:**
P
PaDoBoo 已提交
383 384
  | 参数名 | 类型 | 必填 | 说明 |
  | -------- | -------- | -------- | -------- |
W
wangxiyue 已提交
385
  | key | string | 是 | 要检查的存储key名称,不能为空。 |
386
  | callback | AsyncCallback&lt;boolean&gt; | 是 | 回调函数。返回存储对象是否包含给定key的存储键值对,true表示存在,false表示不存在。 |
P
PaDoBoo 已提交
387

G
ge-yafang 已提交
388
**示例:**
P
PaDaBoo 已提交
389
```ts
390
preferences.has('startup', function (err, isExist) {
P
PaDaBoo 已提交
391 392 393 394 395 396 397 398 399 400 401
    if (err) {
        console.info("Check the key of startup failed, err: " + err)
        return
    }
    if (isExist) {
        console.info("The key of startup is contained.")
    } else {
        console.info("The key of startup dose not contain.")
    }
})
```
P
PaDoBoo 已提交
402 403 404 405 406 407


### has

has(key: string): Promise&lt;boolean&gt;

W
wangxiyue 已提交
408
检查存储对象是否包含名为给定key的存储键值对,该方法使用Promise方式作为异步方法。
P
PaDoBoo 已提交
409

P
PaDaBoo 已提交
410
**系统能力:** SystemCapability.DistributedDataManager.Preferences.Core
411

G
ge-yafang 已提交
412
**参数:**
P
PaDoBoo 已提交
413 414
  | 参数名 | 类型 | 必填 | 说明 |
  | -------- | -------- | -------- | -------- |
W
wangxiyue 已提交
415
  | key | string | 是 | 要检查的存储key名称,不能为空。 |
P
PaDoBoo 已提交
416

G
ge-yafang 已提交
417
**返回值:**
P
PaDoBoo 已提交
418 419
  | 类型 | 说明 |
  | -------- | -------- |
420
  | Promise&lt;boolean&gt; | Promise对象。返回存储对象是否包含给定key的存储键值对,true表示存在,false表示不存在。 |
P
PaDoBoo 已提交
421

G
ge-yafang 已提交
422
**示例:**
P
PaDaBoo 已提交
423
```ts
424
let promise = preferences.has('startup')
P
PaDaBoo 已提交
425 426 427 428 429 430 431 432 433 434
promise.then((isExist) => {
    if (isExist) {
        console.info("The key of startup is contained.")
    } else {
        console.info("The key of startup dose not contain.")
    }
}).catch((err) => {
    console.info("Check the key of startup failed, err: " + err)
})
```
P
PaDoBoo 已提交
435 436 437 438 439 440


### delete

delete(key: string, callback: AsyncCallback&lt;void&gt;): void

W
wangxiyue 已提交
441
从存储对象中删除名为给定key的存储键值对,该方法使用callback方式作为异步方法。
P
PaDoBoo 已提交
442

P
PaDaBoo 已提交
443
**系统能力:** SystemCapability.DistributedDataManager.Preferences.Core
444

G
ge-yafang 已提交
445
**参数:**
P
PaDoBoo 已提交
446 447
  | 参数名 | 类型 | 必填 | 说明 |
  | -------- | -------- | -------- | -------- |
W
wangxiyue 已提交
448
  | key | string | 是 | 要删除的存储key名称,不能为空。 |
P
PaDoBoo 已提交
449 450
  | callback | AsyncCallback&lt;void&gt; | 是 | 回调函数。 |

G
ge-yafang 已提交
451
**示例:**
P
PaDaBoo 已提交
452
```ts
453
preferences.delete('startup', function (err) {
P
PaDaBoo 已提交
454 455 456 457 458 459 460
    if (err) {
        console.info("Delete startup key failed, err: " + err)
        return
    }
    console.info("Deleted startup key successfully.")
})
```
P
PaDoBoo 已提交
461 462 463 464 465 466


### delete

delete(key: string): Promise&lt;void&gt;

W
wangxiyue 已提交
467
从存储对象删除名为给定key的存储键值对,该方法使用Promise方式作为异步方法。
P
PaDoBoo 已提交
468

P
PaDaBoo 已提交
469
**系统能力:** SystemCapability.DistributedDataManager.Preferences.Core
470

G
ge-yafang 已提交
471
**参数:**
P
PaDoBoo 已提交
472 473
  | 参数名 | 类型 | 必填 | 说明 |
  | -------- | -------- | -------- | -------- |
W
wangxiyue 已提交
474
  | key | string | 是 | 要删除的存储key名称,不能为空。 |
P
PaDoBoo 已提交
475

G
ge-yafang 已提交
476
**返回值:**
P
PaDoBoo 已提交
477 478 479 480
  | 类型 | 说明 |
  | -------- | -------- |
  | Promise&lt;void&gt; | Promise实例,用于异步处理。 |

G
ge-yafang 已提交
481
**示例:**
P
PaDaBoo 已提交
482
```ts
483
let promise = preferences.delete('startup')
P
PaDaBoo 已提交
484 485 486 487 488 489
promise.then(() => {
    console.info("Deleted startup key successfully.")
}).catch((err) => {
    console.info("Delete startup key failed, err: " + err)
})
```
P
PaDoBoo 已提交
490 491 492 493 494 495


### flush

flush(callback: AsyncCallback&lt;void&gt;): void

W
wangxiyue 已提交
496
将当前preferences对象中的修改保存到当前的preferences,并异步存储到首选项持久化文件中,该方法使用callback方式作为异步方法。
P
PaDoBoo 已提交
497

P
PaDaBoo 已提交
498
**系统能力:** SystemCapability.DistributedDataManager.Preferences.Core
499

G
ge-yafang 已提交
500
**参数:**
P
PaDoBoo 已提交
501 502 503 504
  | 参数名 | 类型 | 必填 | 说明 |
  | -------- | -------- | -------- | -------- |
  | callback | AsyncCallback&lt;void&gt; | 是 | 回调函数。 |

G
ge-yafang 已提交
505
**示例:**
P
PaDaBoo 已提交
506
```ts
507
preferences.flush(function (err) {
P
PaDaBoo 已提交
508 509 510 511 512 513 514
    if (err) {
        console.info("Flush to file failed, err: " + err)
        return
    }
    console.info("Flushed to file successfully.")
})
```
P
PaDoBoo 已提交
515 516 517 518 519 520


### flush

flush(): Promise&lt;void&gt;

W
wangxiyue 已提交
521
将当前preferences对象中的修改保存到当前的preferences,并异步存储到首选项持久化文件中,该方法使用Promise方式作为异步方法。
P
PaDoBoo 已提交
522

P
PaDaBoo 已提交
523
**系统能力:** SystemCapability.DistributedDataManager.Preferences.Core
524

G
ge-yafang 已提交
525
**返回值:**
P
PaDoBoo 已提交
526 527 528 529
  | 类型 | 说明 |
  | -------- | -------- |
  | Promise&lt;void&gt; | Promise实例,用于异步处理。 |

G
ge-yafang 已提交
530
**示例:**
P
PaDaBoo 已提交
531
```ts
532
let promise = preferences.flush()
P
PaDaBoo 已提交
533 534 535 536 537 538
promise.then(() => {
    console.info("Flushed to file successfully.")
}).catch((err) => {
    console.info("Flush to file failed, err: " + err)
})
```
P
PaDoBoo 已提交
539 540 541 542 543 544


### clear

clear(callback: AsyncCallback&lt;void&gt;): void

W
wangxiyue 已提交
545
清除此存储对象中的所有存储,该方法使用callback方式作为异步方法。
P
PaDoBoo 已提交
546

P
PaDaBoo 已提交
547
**系统能力:** SystemCapability.DistributedDataManager.Preferences.Core
548

G
ge-yafang 已提交
549
**参数:**
P
PaDoBoo 已提交
550 551 552 553
  | 参数名 | 类型 | 必填 | 说明 |
  | -------- | -------- | -------- | -------- |
  | callback | AsyncCallback&lt;void&gt; | 是 | 回调函数。 |

G
ge-yafang 已提交
554
**示例:**
P
PaDaBoo 已提交
555
```ts
556
preferences.clear(function (err) {
P
PaDaBoo 已提交
557 558 559 560 561 562 563
    if (err) {
        console.info("Clear to file failed, err: " + err)
        return
    }
    console.info("Cleared to file successfully.")
})
```
P
PaDoBoo 已提交
564 565 566 567 568 569


### clear

clear(): Promise&lt;void&gt;

W
wangxiyue 已提交
570
清除此存储对象中的所有存储,该方法使用Promise方式作为异步方法。
P
PaDoBoo 已提交
571

P
PaDaBoo 已提交
572
**系统能力:** SystemCapability.DistributedDataManager.Preferences.Core
573

G
ge-yafang 已提交
574
**返回值:**
P
PaDoBoo 已提交
575 576 577 578
  | 类型 | 说明 |
  | -------- | -------- |
  | Promise&lt;void&gt; | Promise实例,用于异步处理。 |

G
ge-yafang 已提交
579
**示例:**
P
PaDaBoo 已提交
580
```ts
581
let promise = preferences.clear()
P
PaDaBoo 已提交
582 583 584 585 586 587
promise.then(() => {
    console.info("Cleared to file successfully.")
}).catch((err) => {
    console.info("Clear to file failed, err: " + err)
})
```
P
PaDoBoo 已提交
588 589 590 591 592 593 594 595


### on('change')

on(type: 'change', callback: Callback&lt;{ key : string }&gt;): void

订阅数据变更者类,订阅的key的值发生变更后,在执行flush方法后,callback方法会被回调。

P
PaDaBoo 已提交
596
**系统能力:** SystemCapability.DistributedDataManager.Preferences.Core
597

G
ge-yafang 已提交
598
**参数:**
599 600 601 602
  | 参数名 | 类型 | 必填 | 说明 |
  | -------- | -------- | -------- | -------- |
  | type | string | 是 |  事件类型,固定值'change',表示数据变更。 |
  | callback | Callback&lt;{ key : string }&gt;  | 是| 回调对象实例。 |
P
PaDoBoo 已提交
603

G
ge-yafang 已提交
604
**示例:**
P
PaDaBoo 已提交
605
```ts
L
li_juntao 已提交
606
data_preferences.getPreferences(this.context, 'mystore', function (err, preferences) {
P
PaDaBoo 已提交
607
    if (err) {
L
li_juntao 已提交
608 609
        console.info("Get preferences failed.")
        return;
P
PaDaBoo 已提交
610
    }
L
li_juntao 已提交
611 612 613 614 615
    var observer = function (key) {
        console.info("The key of " + key + " changed.")
    }
    preferences.on('change', observer)
    preferences.put('startup', 'auto', function (err) {
P
PaDaBoo 已提交
616
        if (err) {
L
li_juntao 已提交
617
            console.info("Put the value of startup failed, err: " + err)
P
PaDaBoo 已提交
618 619
            return
        }
L
li_juntao 已提交
620 621 622 623 624 625 626 627 628
        console.info("Put the value of startup successfully.")

        preferences.flush(function (err) {
            if (err) {
                console.info("Flush to file failed, err: " + err)
                return
            }
            console.info("Flushed to file successfully.") // observer will be called.
        })
P
PaDaBoo 已提交
629 630 631
    })
})
```
P
PaDoBoo 已提交
632 633 634 635


### off('change')

636
off(type: 'change', callback?: Callback&lt;{ key : string }&gt;): void
P
PaDoBoo 已提交
637 638 639

当不再进行订阅数据变更时,使用此接口取消订阅。

P
PaDaBoo 已提交
640
**系统能力:** SystemCapability.DistributedDataManager.Preferences.Core
641

G
ge-yafang 已提交
642
**参数:**
643 644 645 646
  | 参数名 | 类型 | 必填 | 说明 |
  | -------- | -------- | -------- | -------- |
  | type | string | 是 | 事件类型,固定值'change',表示数据变更。 |
  | callback | Callback&lt;{ key : string }&gt;  | 否| 需要取消的回调对象实例,不填则全部取消。 |
P
PaDoBoo 已提交
647

G
ge-yafang 已提交
648
**示例:**
P
PaDaBoo 已提交
649
```ts
L
li_juntao 已提交
650
data_preferences.getPreferences(this.context, 'mystore', function (err, preferences) {
P
PaDaBoo 已提交
651
    if (err) {
L
li_juntao 已提交
652 653
        console.info("Get preferences failed.")
        return;
P
PaDaBoo 已提交
654
    }
L
li_juntao 已提交
655 656 657 658 659
    var observer = function (key) {
        console.info("The key of " + key + " changed.")
    }
    preferences.on('change', observer)
    preferences.put('startup', 'auto', function (err) {
P
PaDaBoo 已提交
660
        if (err) {
L
li_juntao 已提交
661
            console.info("Put the value of startup failed, err: " + err)
P
PaDaBoo 已提交
662 663
            return
        }
L
li_juntao 已提交
664 665 666 667 668 669 670 671 672
        console.info("Put the value of startup successfully.")

        preferences.flush(function (err) {
            if (err) {
                console.info("Flush to file failed, err: " + err)
                return
            }
            console.info("Flushed to file successfully.") // observer will be called.
        })
673
        preferences.off('change', observer)
P
PaDaBoo 已提交
674 675 676
    })
})
```
G
ge-yafang 已提交
677 678 679 680 681

## ValueType

用于表示允许的数据字段类型。

P
PaDaBoo 已提交
682
**系统能力:** SystemCapability.DistributedDataManager.Preferences.Core
G
ge-yafang 已提交
683

684 685 686 687 688 689 690 691
| 名称           | 说明                           |
| -------------- | ------------------------------ |
| number         | 表示值类型为数字。             |
| string         | 表示值类型为字符串。           |
| boolean        | 表示值类型为布尔值。           |
| Array\<number>  | 表示值类型为数字类型的数组。   |
| Array\<boolean> | 表示值类型为布尔类型的数组。   |
| Array\<string>  | 表示值类型为字符串类型的数组。 |