一. 數(shù)據(jù)管理概述

功能介紹

數(shù)據(jù)管理為開發(fā)者提供數(shù)據(jù)存儲、數(shù)據(jù)管理能力，比如聯(lián)系人應(yīng)用數(shù)據(jù)可以保存到數(shù)據(jù)庫中，提供數(shù)據(jù)庫的安全、可靠等管理機(jī)制。

• 數(shù)據(jù)存儲：提供通用數(shù)據(jù)持久化能力，根據(jù)數(shù)據(jù)特點，分為用戶首選項、鍵值型數(shù)據(jù)庫和關(guān)系型數(shù)據(jù)庫。
• 數(shù)據(jù)管理：提供高效的數(shù)據(jù)管理能力，包括權(quán)限管理、數(shù)據(jù)備份恢復(fù)、數(shù)據(jù)共享框架等。

應(yīng)用創(chuàng)建的數(shù)據(jù)庫，都保存到應(yīng)用沙盒，當(dāng)應(yīng)用卸載時，數(shù)據(jù)庫也會自動刪除。

運(yùn)作機(jī)制

數(shù)據(jù)管理模塊包括用戶首選項、鍵值型數(shù)據(jù)管理、關(guān)系型數(shù)據(jù)管理、分布式數(shù)據(jù)對象和跨應(yīng)用數(shù)據(jù)管理。Interface接口層提供標(biāo)準(zhǔn)JS?API接口，定義這些部件接口描述，供開發(fā)者參考。Frameworks&System?service層負(fù)責(zé)實現(xiàn)部件數(shù)據(jù)存儲功能，還有一些SQLite和其他子系統(tǒng)的依賴。

圖1?數(shù)據(jù)管理架構(gòu)圖

• 用戶首選項（Preferences）：提供了輕量級配置數(shù)據(jù)的持久化能力，并支持訂閱數(shù)據(jù)變化的通知能力。不支持分布式同步，常用于保存應(yīng)用配置信息、用戶偏好設(shè)置等。
• 鍵值型數(shù)據(jù)管理（KV-Store）：提供了鍵值型數(shù)據(jù)庫的讀寫、加密、手動備份能力。分布式功能暫不支持。
• 關(guān)系型數(shù)據(jù)管理（RelationalStore）：提供了關(guān)系型數(shù)據(jù)庫的增刪改查、加密、手動備份能力。分布式功能暫不支持。
• 分布式數(shù)據(jù)對象（DataObject）：獨立提供對象型結(jié)構(gòu)數(shù)據(jù)的分布式能力。分布式功能暫不支持。
• 跨應(yīng)用數(shù)據(jù)管理（DataShare）：提供了向其他應(yīng)用共享以及管理其數(shù)據(jù)的方法。僅系統(tǒng)應(yīng)用可用，非系統(tǒng)應(yīng)用無需關(guān)注，下文不做具體介紹。

二.?應(yīng)用數(shù)據(jù)持久化概述

應(yīng)用數(shù)據(jù)持久化，是指應(yīng)用將內(nèi)存中的數(shù)據(jù)通過文件或數(shù)據(jù)庫的形式保存到設(shè)備上。內(nèi)存中的數(shù)據(jù)形態(tài)通常是任意的數(shù)據(jù)結(jié)構(gòu)或數(shù)據(jù)對象，存儲介質(zhì)上的數(shù)據(jù)形態(tài)可能是文本、數(shù)據(jù)庫、二進(jìn)制文件等。

HarmonyOS標(biāo)準(zhǔn)系統(tǒng)支持典型的存儲數(shù)據(jù)形態(tài)，包括用戶首選項、鍵值型數(shù)據(jù)庫、關(guān)系型數(shù)據(jù)庫。

開發(fā)者可以根據(jù)如下功能介紹，選擇合適的數(shù)據(jù)形態(tài)以滿足自己應(yīng)用數(shù)據(jù)的持久化需要。

• 用戶首選項（Preferences）：通常用于保存應(yīng)用的配置信息。數(shù)據(jù)通過文本的形式保存在設(shè)備中，應(yīng)用使用過程中會將文本中的數(shù)據(jù)全量加載到內(nèi)存中，所以訪問速度快、效率高，但不適合需要存儲大量數(shù)據(jù)的場景。
• 鍵值型數(shù)據(jù)庫（KV-Store）：一種非關(guān)系型數(shù)據(jù)庫，其數(shù)據(jù)以“鍵值”對的形式進(jìn)行組織、索引和存儲，其中“鍵”作為唯一標(biāo)識符。適合很少數(shù)據(jù)關(guān)系和業(yè)務(wù)關(guān)系的業(yè)務(wù)數(shù)據(jù)存儲，同時因其在分布式場景中降低了解決數(shù)據(jù)庫版本兼容問題的復(fù)雜度，和數(shù)據(jù)同步過程中沖突解決的復(fù)雜度而被廣泛使用。相比于關(guān)系型數(shù)據(jù)庫，更容易做到跨設(shè)備跨版本兼容。
• 關(guān)系型數(shù)據(jù)庫（RelationalStore）：一種關(guān)系型數(shù)據(jù)庫，以行和列的形式存儲數(shù)據(jù)，廣泛用于應(yīng)用中的關(guān)系型數(shù)據(jù)的處理，包括一系列的增、刪、改、查等接口，開發(fā)者也可以運(yùn)行自己定義的SQL語句來滿足復(fù)雜業(yè)務(wù)場景的需要。

三.?通過用戶首選項實現(xiàn)數(shù)據(jù)持久化

場景介紹

用戶首選項為應(yīng)用提供Key-Value鍵值型的數(shù)據(jù)處理能力，支持應(yīng)用持久化輕量級數(shù)據(jù)，并對其修改和查詢。當(dāng)用戶希望有一個全局唯一存儲的地方，可以采用用戶首選項來進(jìn)行存儲。Preferences會將該數(shù)據(jù)緩存在內(nèi)存中，當(dāng)用戶讀取的時候，能夠快速從內(nèi)存中獲取數(shù)據(jù)。Preferences會隨著存放的數(shù)據(jù)量越多而導(dǎo)致應(yīng)用占用的內(nèi)存越大，因此，Preferences不適合存放過多的數(shù)據(jù)，適用的場景一般為應(yīng)用保存用戶的個性化設(shè)置（字體大小，是否開啟夜間模式）等。

運(yùn)作機(jī)制

如圖所示，用戶程序通過JS接口調(diào)用用戶首選項讀寫對應(yīng)的數(shù)據(jù)文件。開發(fā)者可以將用戶首選項持久化文件的內(nèi)容加載到Preferences實例，每個文件唯一對應(yīng)到一個Preferences實例，系統(tǒng)會通過靜態(tài)容器將該實例存儲在內(nèi)存中，直到主動從內(nèi)存中移除該實例或者刪除該文件。

應(yīng)用首選項的持久化文件保存在應(yīng)用沙箱內(nèi)部，可以通過context獲取其路徑。具體可見獲取應(yīng)用開發(fā)路徑。

約束限制

• Key鍵為string類型，要求非空且長度不超過80個字節(jié)。
• 如果Value值為string類型，可以為空，不為空時長度不超過8192個字節(jié)。
• 內(nèi)存會隨著存儲數(shù)據(jù)量的增大而增大，所以存儲的數(shù)據(jù)量應(yīng)該是輕量級的，建議存儲的數(shù)據(jù)不超過一萬條，否則會在內(nèi)存方面產(chǎn)生較大的開銷。

接口說明

以下是用戶首選項持久化功能的相關(guān)接口，大部分為異步接口。異步接口均有callback和Promise兩種返回形式，下表均以callback形式為例，更多接口及使用方式請見用戶首選項。

接口名稱	描述
getPreferences(context:?Context,?name:?string,?callback:?AsyncCallback<Preferences>):?void	獲取Preferences實例。
put(key:?string,?value:?ValueType,?callback:?AsyncCallback<void>):?void	將數(shù)據(jù)寫入Preferences實例，可通過flush將Preferences實例持久化。
has(key:?string,?callback:?AsyncCallback<boolean>):?void	檢查Preferences實例是否包含名為給定Key的存儲鍵值對。給定的Key值不能為空。
get(key:?string,?defValue:?ValueType,?callback:?AsyncCallback<ValueType>):?void	獲取鍵對應(yīng)的值，如果值為null或者非默認(rèn)值類型，返回默認(rèn)數(shù)據(jù)defValue。
delete(key:?string,?callback:?AsyncCallback<void>):?void	從Preferences實例中刪除名為給定Key的存儲鍵值對。
flush(callback:?AsyncCallback<void>):?void	將當(dāng)前Preferences實例的數(shù)據(jù)異步存儲到用戶首選項持久化文件中。
on(type:?'change',?callback:?Callback<{?key?:?string?}>):?void	訂閱數(shù)據(jù)變更，訂閱的Key的值發(fā)生變更后，在執(zhí)行flush方法后，觸發(fā)callback回調(diào)。
off(type:?'change',?callback?:?Callback<{?key?:?string?}>):?void	取消訂閱數(shù)據(jù)變更。
deletePreferences(context:?Context,?name:?string,?callback:?AsyncCallback<void>):?void	從內(nèi)存中移除指定的Preferences實例。若Preferences實例有對應(yīng)的持久化文件，則同時刪除其持久化文件。

開發(fā)步驟

1.導(dǎo)入用戶首選項模塊。

import?dataPreferences?from?'@ohos.data.preferences';

2.要通過用戶首選項實現(xiàn)數(shù)據(jù)持久化，首先要獲取Preferences實例。讀取指定文件，將數(shù)據(jù)加載到Preferences實例，用于數(shù)據(jù)操作。Stage模型示例：

import?UIAbility?from?'@ohos.app.ability.UIAbility';class EntryAbility extends UIAbility {onWindowStageCreate(windowStage) {try {
??????dataPreferences.getPreferences(this.context, 'mystore', (err,?preferences) => {if (err) {
??????????console.error(`Failed?to?get?preferences.?Code:${err.code},message:${err.message}`);return;}
????????console.info('Succeeded?in?getting?preferences.');//?進(jìn)行相關(guān)數(shù)據(jù)操作})} catch (err) {
??????console.error(`Failed?to?get?preferences.?Code:${err.code},message:${err.message}`);}}
}

寫入數(shù)據(jù)。使用put()方法保存數(shù)據(jù)到緩存的Preferences實例中。在寫入數(shù)據(jù)后，如有需要，可使用flush()方法將Preferences實例的數(shù)據(jù)存儲到持久化文件。

說明

當(dāng)對應(yīng)的鍵已經(jīng)存在時，put()方法會修改其值。如果僅需要在鍵值對不存在時新增鍵值對，而不修改已有鍵值對，需使用has()方法檢查是否存在對應(yīng)鍵值對；如果不關(guān)心是否會修改已有鍵值對，則直接使用put()方法即可。

示例代碼如下所示：

try?{
??preferences.has('startup',?function?(err,?val)?{
????if?(err)?{
??????console.error(`Failed?to?check?the?key?'startup'.?Code:${err.code},?message:${err.message}`);
??????return;
????}
????if?(val)?{
??????console.info("The?key?'startup'?is?contained.");
????}?else?{
??????console.info("The?key?'startup'?does?not?contain.");
??????//?此處以此鍵值對不存在時寫入數(shù)據(jù)為例
??????try?{
????????preferences.put('startup',?'auto',?(err)?=>?{
??????????if?(err)?{
????????????console.error(`Failed?to?put?data.?Code:${err.code},?message:${err.message}`);
????????????return;
??????????}
??????????console.info('Succeeded?in?putting?data.');
????????})
??????}?catch?(err)?{
????????console.error(`Failed?to?put?data.?Code:?${err.code},message:${err.message}`);
??????}
????}
??})
}?catch?(err)?{
??console.error(`Failed?to?check?the?key?'startup'.?Code:${err.code},?message:${err.message}`);
}

3.讀取數(shù)據(jù)。使用get()方法獲取數(shù)據(jù)，即指定鍵對應(yīng)的值。如果值為null或者非默認(rèn)值類型，則返回默認(rèn)數(shù)據(jù)。示例代碼如下所示：

try {
??preferences.get('startup', 'default', (err,?val) => {if (err) {
??????console.error(`Failed?to?get?value?of?'startup'.?Code:${err.code},?message:${err.message}`);return;}
????console.info(`Succeeded?in?getting?value?of?'startup'.?val:?${val}.`);})
} catch (err) {
??console.error(`Failed?to?get?value?of?'startup'.?Code:${err.code},?message:${err.message}`);
}

4.刪除數(shù)據(jù)。使用delete()方法刪除指定鍵值對，示例代碼如下所示：

try {
??preferences.delete('startup', (err) => {if (err) {
??????console.error(`Failed?to?delete?the?key?'startup'.?Code:${err.code},?message:${err.message}`);return;}
????console.info("Succeeded?in?deleting?the?key?'startup'.");})
} catch (err) {
??console.error(`Failed?to?delete?the?key?'startup'.?Code:${err.code},?message:${err.message}`);
}

5.數(shù)據(jù)持久化。應(yīng)用存入數(shù)據(jù)到Preferences實例后，可以使用flush()方法實現(xiàn)數(shù)據(jù)持久化。示例代碼如下所示：

try {
??preferences.flush((err) => {if (err) {
??????console.error(`Failed?to?flush.?Code:${err.code},?message:${err.message}`);return;}
????console.info('Succeeded?in?flushing.');})
} catch (err) {
??console.error(`Failed?to?flush.?Code:${err.code},?message:${err.message}`);
}

6.訂閱數(shù)據(jù)變更。應(yīng)用訂閱數(shù)據(jù)變更需要指定observer作為回調(diào)方法。訂閱的Key值發(fā)生變更后，當(dāng)執(zhí)行flush()方法時，observer被觸發(fā)回調(diào)。示例代碼如下所示

let observer = function (key) {
??console.info('The?key' +?key?+ 'changed.');
}
preferences.on('change',?observer);
//?數(shù)據(jù)產(chǎn)生變更，由'auto'變?yōu)?/span>'manual'
preferences.put('startup', 'manual', (err) => {if (err) {
????console.error(`Failed?to?put?the?value?of?'startup'.?Code:${err.code},message:${err.message}`);return;}
??console.info("Succeeded?in?putting?the?value?of?'startup'.");
??preferences.flush((err) => {if (err) {
??????console.error(`Failed?to?flush.?Code:${err.code},?message:${err.message}`);return;}
????console.info('Succeeded?in?flushing.');})
})

刪除指定文件。使用deletePreferences()方法從內(nèi)存中移除指定文件對應(yīng)的Preferences實例，包括內(nèi)存中的數(shù)據(jù)。若該P(yáng)reference存在對應(yīng)的持久化文件，則同時刪除該持久化文件，包括指定文件及其備份文件、損壞文件。

說明

• 調(diào)用該接口后，應(yīng)用不允許再使用該P(yáng)references實例進(jìn)行數(shù)據(jù)操作，否則會出現(xiàn)數(shù)據(jù)一致性問題。
• 成功刪除后，數(shù)據(jù)及文件將不可恢復(fù)。

示例代碼如下所示：

try {
??dataPreferences.deletePreferences(this.context, 'mystore', (err,?val) => {if (err) {
??????console.error(`Failed?to?delete?preferences.?Code:${err.code},?message:${err.message}`);return;}
????console.info('Succeeded?in?deleting?preferences.');})
} catch (err) {
??console.error(`Failed?to?delete?preferences.?Code:${err.code},?message:${err.message}`);
}