# 鴻蒙通過用戶首選項實現數據持久化

## 1.1 場景介紹

用戶首選項為應用提供Key-Value鍵值型的數據處理能力，支持應用持久化輕量級數據，并對其修改和查詢。當用戶希望有一個全局唯一存儲的地方，可以采用用戶首選項來進行存儲。Preferences會將該數據緩存在內存中，當用戶讀取的時候，能夠快速從內存中獲取數據，當需要持久化時可以使用flush接口將內存中的數據寫入持久化文件中。Preferences會隨著存放的數據量越多而導致應用占用的內存越大，因此，Preferences不適合存放過多的數據，也不支持通過配置加密，適用的場景一般為應用保存用戶的個性化設置（字體大小，是否開啟夜間模式）等。

## 2.1 運作機制

用戶首選項為應用提供Key-Value鍵值型的數據處理能力，支持應用持久化輕量級數據，并對其修改和查詢。當用戶希望有一個全局唯一存儲的地方，可以采用用戶首選項來進行存儲。Preferences會將該數據緩存在內存中，當用戶讀取的時候，能夠快速從內存中獲取數據，當需要持久化時可以使用flush接口將內存中的數據寫入持久化文件中。Preferences會隨著存放的數據量越多而導致應用占用的內存越大，因此，Preferences不適合存放過多的數據，也不支持通過配置加密，適用的場景一般為應用保存用戶的個性化設置（字體大小，是否開啟夜間模式）等。

* 每個key的value的長度最大為8kb
* 創建首選項-倉庫的概念-應用可以有N個倉庫，一個倉庫中可以有N個key


## 3.1 接口說明

| 接口名稱及方法簽名 | 描述 | 參數 | 同步/異步類型 | 約束條件 |
| ------------------------------------------------------------ | ----------------------------------------------------- | ------------------------------------------------------------ | ------------- | ---------------------------------- |
| `getPreferencesSync(context: Context, options: Options): Preferences` | 獲取 `Preferences` 實例 | `context`: 上下文對象
`options`: 配置選項 | 同步 | 存在對應的異步接口 |
| `putSync(key: string, value: ValueType): void` | 寫入鍵值對（需調用 `flush` 持久化存儲） | `key`: 鍵名
`value`: 值（需滿足 `ValueType` 類型要求） | 同步 | 存在異步接口 |
| `hasSync(key: string): boolean` | 檢查是否包含指定鍵的鍵值對 | `key`: 鍵名 | 同步 | - 鍵名不能為空
- 存在異步接口 |
| `getSync(key: string, defValue: ValueType): ValueType` | 獲取鍵對應的值（若為空或類型不匹配則返回 `defValue`） | `key`: 鍵名
`defValue`: 默認值 | 同步 | 存在異步接口 |
| `deleteSync(key: string): void` | 刪除指定鍵的鍵值對 | `key`: 鍵名 | 同步 | 存在異步接口 |
| `flush(callback: AsyncCallback): void` | 將數據異步持久化到文件 | `callback`: 異步回調 | 異步 | - |
| `on(type: 'change', callback: Callback): void` | 訂閱數據變更事件（在 `flush` 后觸發） | `type`: 事件類型（僅支持 `'change'`）
`callback`: 回調函數（參數為變更的 `key`） | - | - |
| `off(type: 'change', callback?: Callback): void` | 取消訂閱數據變更事件 | `type`: 事件類型（`'change'`）
`callback`: 可選回調函數 | - | 若未指定 `callback` 則取消全部訂閱 |
| `deletePreferences(context: Context, options: Options, callback: AsyncCallback): void` | 從內存移除實例并刪除持久化文件（若有） | `context`: 上下文對象
`options`: 配置選項
`callback`: 異步回調 | 異步 | - |

## 4.1 開發步驟

### 1.導入@kit.ArkData模塊。

```ts
import { preferences } from "@kit.ArkData";
```

### 2.獲取preference實例，拿到倉庫

`getPreferenceSync`接受兩個參數，其中一個參數是context,另一個參數是options

* `context`代表了用戶的上下文，是ability的能力級，也是ability的一個環境，這個東西如果想要獲取分兩種情況

1. 在ability中區獲取 在`onWindowStageCreate`寫入這行代碼即可

```ts
MyPreferenceClass.context = this.context
```

2. 在UI界面去拿

```ts
getContext(this)
```

* `options` 是傳遞給 `preferences.getPreferencesSync()` 的配置對象，用于定義存儲實例的倉庫名稱、安全模式等關鍵屬性

```ts
const store = preferences.getPreferencesSync(MyPreferenceClass.context||getContext(),{
//拿到該名稱的倉庫，拿不到就會給你創建該名稱的倉庫，類似數據庫
name:'infoStore'
})
return store
```

### 3.創建增刪改的方法

```ts
//2.寫入字段，持久化存儲
static async putStore(info:string){
const store = MyPreferenceClass.getStore()
store.putSync('info',info)
await store.flush()
}
//3.獲取數據
static getValue(){
const store = MyPreferenceClass.getStore()
const value = store.getSync('info','666666')
return value
}

//4.刪除數據
static async deleteValue(){
const store = MyPreferenceClass.getStore()
//如果不加上flush操作，只是在內存中刪除，需要加上flush操作才能寫入磁盤！
store.deleteSync('info')
await store.flush()
}
//5.判斷數據是否存在
static judjeValue(val:string){
const store = MyPreferenceClass.getStore()
const value = store.hasSync(val)
return value
}
```

### 4.測試代碼

```ts
import { MyPreferenceClass } from './utils/MyPreferenceClass'

@Entry
@Component
struct Mytest {
// @State 實時更新
@State currentValue: string = '今天天氣真不錯！'
@State JudeValue: boolean = false

build() {
//初始化默認值

Column({ space: 10 }) {
Text(this.currentValue)
Text(this.JudeValue + '')
Button('寫入數據')
.onClick(() => {
MyPreferenceClass.putStore('今天天氣并不好')
})
Button('展示數據')
.onClick(() => {
this.currentValue = MyPreferenceClass.getValue() as string
})
Button('刪除數據')
.onClick(() => {
MyPreferenceClass.deleteValue()
})
Button('是否展示該數據')
.onClick(() => {
this.JudeValue = MyPreferenceClass.judjeValue('info')
})
}
.height('100%')
.width('100%')

}
```

審核編輯 黃宇