HarmonyOS开发案例：【用户首选项】

介绍

用户首选项为应用提供Key-Value键值型的数据处理能力，支持应用持久化轻量级数据，常用于保存应用配置信息、用户偏好设置等。本篇Codelab将基于用户首选项实现一个简单的数据管理应用，包含新增、查询和删除的功能。效果如图所示：

相关概念

• [dialog]：自定义弹窗容器。
• [用户首选项]：用户首选项为应用提供Key-Value键值型的数据处理能力，支持应用持久化轻量级数据，并对其修改和查询。

环境搭建

软件要求

• [DevEco Studio]版本：DevEco Studio 3.1 Release及以上版本。
• OpenHarmony SDK版本：API version 9及以上版本。
• 鸿蒙开发文档参考：gitee.com/li-shizhen-skin/harmony-os/blob/master/README.md点击或者复制转到。

硬件要求

• 开发板类型：[润和RK3568开发板]。
• OpenHarmony系统：3.2 Release及以上版本。
• HarmonyOS与OpenHarmony开发文档籽料：mau123789是v直接拿取

环境搭建

完成本篇Codelab我们首先要完成开发环境的搭建，本示例以RK3568开发板为例，参照以下步骤进行：

1. [获取OpenHarmony系统版本]：标准系统解决方案（二进制）。以3.2 Release版本为例：

   

2. 搭建烧录环境。

   1. [完成DevEco Device Tool的安装]
   2. [完成RK3568开发板的烧录]

3. 搭建开发环境。

   1. 开始前请参考[工具准备]，完成DevEco Studio的安装和开发环境配置。
   2. 开发环境配置完成后，请参考[使用工程向导]创建工程（模板选择“Empty Ability”）。
   3. 工程创建完成后，选择使用[真机进行调测]。

代码结构解读

本篇Codelab只对核心代码进行讲解，对于完整代码，我们会在gitee中提供。

├──entry/src/main/js                  // 代码区
│  └──MainAbility
│     ├──common
│     │  ├──constants
│     │  │  └──commonConstants.js     // 公共常量
│     │  ├──database
│     │  │  └──preference.js          // 首选项数据处理
│     │  ├──images                    // 图片图标
│     │  │  ├──ic_delete.png
│     │  │  └──ic_no_data.png
│     │  └──utils    
│     │     └──logger.js              // 日志工具
│     ├──i18n                          // 国际化
│     │  ├──en-US.json            
│     │  └──zh-CN.json            
│     └──pages
│        └──index
│           ├──index.css              // 首页样式文件    
│           ├──index.hml              // 首页布局文件
│           └──index.js               // 首页脚本文件
└──entry/src/main/resources           // 应用资源目录

构建界面

应用主界面由上至下分为四部分：顶部标题栏、搜索栏、数据展示区域、底部按钮区域。

每个区域都位于div容器组件中，通过对容器位置的控制，做好页面整体布局。

• 标题栏区域内仅包含text组件，用于设置标题显示内容。
• 搜索栏区域内仅包含search组件，用于设置搜索框的显示。
• 数据展示区域会根据不同场景呈现不同内容：无数据时，使用image组件展示“暂无数据”图片；存在数据时，则会使用list组件展示数据列表。
• 按钮区域使用button组件，设置“清空”和“添加”按钮。

<!-- index.hml -->
<div class="container">
    <!-- 标题栏 -->
    <div class="title-container">
        <text class="title">DataBase</text>
    </div>
    <!-- 搜索栏 -->
    <div class="search-container">
        <search class="search-bar" hint="{{ $t('strings.search_key') }}" searchbutton="{{ $t('strings.search') }}"
                @submit="searchByKey"></search>
    </div>
    <!-- 数据区域（无数据） -->
    <div class="no-data-container" if="{{ isNoData }}">
        <image src='/common/images/ic_no_data.png'></image>
    </div>
    <!-- 数据区域（有数据） -->
    <list class="data-container" if="{{ ! isNoData }}" scrollbar="auto">
        <list-item for="{{ allDataArray }}" class="list-item">
            <div class="card-container">
                <div class="text-container">
                    <text class="key-text">{{ $item.key }}</text>
                    <text class="value-text">{{ $item.value }}</text>
                </div>
                <image class="delete-img" src="/common/images/ic_delete.png" @click="deleteData({{ $item.key }})">
                </image>
            </div>
        </list-item>
    </list>
    <!-- 按钮区域 -->
    <div class="button-container">
        <button class="remove" type="capsule" value="{{ $t('strings.delete_all') }}" @click="removeAll"></button>
        <button class="add" type="capsule" value="{{ $t('strings.add') }}" @click="addData"></button>
    </div>
</div>

当进行添加、删除、清空等操作，会弹出对应的对话框。对话框使用dialog自定义弹框容器组件，根据对话框需要展示的内容选择不同的元素。

<!-- index.hml -->
<div class="container">
    <!-- 添加对话框 -->
    <dialog id="addDialog" class="add-dialog">
        <div class="add-dialog-container">
            <div class="add-input-container">
                <text class="add-dialog-title">{{ $t('strings.add') }}</text>
                <input id="dataKey" class="add-dialog-input" placeholder="{{ $t('strings.key_input') }}"
                       @change="keyChange"></input>
                <input id="dataValue" class="add-dialog-input" placeholder="{{ $t('strings.value_input') }}"
                       @change="dataChange"></input>
            </div>
            <div class="add-button-container">
                <button type="capsule" value="{{ $t('strings.cancel') }}" onclick="addCancel" class="normal-button">
                </button>
                <button type="capsule" value="{{ $t('strings.confirm') }}" onclick="addConfirm" class="normal-button">
                </button>
            </div>
        </div>
    </dialog>
    <!-- 删除对话框 -->    
    <dialog id="deleteDialog" class="delete-dialog">
        <div class="delete-dialog-container">
            <text>{{ $t('strings.delete_hint') }}</text>
            <div class="delete-button-container">
                <button type="capsule" value="{{ $t('strings.cancel') }}" onclick="deleteCancel" class="normal-button">
                </button>
                <button type="capsule" value="{{ $t('strings.delete') }}" onclick="deleteConfirm" class="delete-button">
                </button>
            </div>
        </div>
    </dialog>
    <!-- 清空对话框 -->    
    <dialog id="clearDialog" class="delete-dialog">
        <div class="delete-dialog-container">
            <text>{{ $t('strings.delete_all_hint') }}</text>
            <div class="delete-button-container">
                <button type="capsule" value="{{ $t('strings.cancel') }}" onclick="clearCancel" class="normal-button">
                </button>
                <button type="capsule" value="{{ $t('strings.delete_all') }}" onclick="clearConfirm"
                        class="delete-button"></button>
            </div>
        </div>
    </dialog>
</div>

使用用户首选项

使用用户首选项，需要先导入对应模块，并获取Preferences实例。

// preference.js
import dataPreferences from '@ohos.data.preferences';

let preference = null;

class Preference {
  ...
  async initPreferences() {
    try {
      let context = featureAbility.getContext();
      preference = await dataPreferences.getPreferences(context, CommonConstants.PREFERENCES_NAME);
    } catch (err) {
      logger.error(`Failed to get preferences. code: ${err.code},message: ${err.message}`);
    }
  }
  ...
}

使用put()方法写入需要添加的数据。使用flush()方法，将用户首选项实例缓存数据持久化到对应文件中。

// preference.js
import dataPreferences from '@ohos.data.preferences';

let preference = null;

class Preference {
  ...
  async addData(key, value) {
    ...
    try {
      await preference.put(key, value);
      await preference.flush();
    } catch (err) {
      logger.error(`Fail to add data. code: ${err.code},message: ${err.message}`);
    }
  }
  ...
}

使用getAll()方法查询所有key值，再根据所有key值查询对应value值。

// preference.js
import dataPreferences from '@ohos.data.preferences';

let preference = null;

class Preference {
  ...
  async getAllData() {
    let allData = [];
    ...
    try {
      let value = await preference.getAll();
      let allKeys = Object.keys(value);
      let keyNum = allKeys.length;
      for (let i = 0; i < keyNum; i++) {
        let dataObj = await this.getDataByKey(allKeys[i]);
        allData.push(dataObj);
      }
    } catch (err) {
      logger.error(`Failed to query all data. code: ${err.code},message: ${err.message}`)
    }
    return allData;
  }
  ...
}

使用delete()方法删除指定键值对，使用clear()方法清除此Preferences实例中的所有数据。

// preference.js
import dataPreferences from '@ohos.data.preferences';

let preference = null;

class Preference {
  ...
  async deleteData(key) {
    ...
    try {
      await preference.delete(key);
      await preference.flush();
    } catch (err) {
      logger.error(`Failed to delete. code: ${err.code},message: ${err.message}`);
    }
  }

  async clearData() {
    ...
    try {
      await preference.clear();
      await preference.flush();
    } catch (err) {
      logger.error(`Failed to clear. code: ${err.code},message: ${err.message}`);
    }
  }  
  ...
}