数据管理

1 概述

在移动互联网蓬勃发展的今天，移动应用给我们生活带来了极大的便利，这些便利的本质在于数据的互联互通。因此在应用的开发中数据存储占据了非常重要的位置，HarmonyOS应用开发也不例外。

本文将为您介绍HarmonyOS提供的数据管理能力之一首选项。

2 什么是首选项

首选项为应用提供Key-Value键值型的数据存储能力，支持应用持久化轻量级数据，并对其进行增删改查等。该存储对象中的数据会被缓存在内存中，因此它可以获得更快的存取速度，下面详细介绍下首选项的开发过程。

3 首选项运作机制

首选项的特点是：

1、以Key-Value形式存储数据

Key是不重复的关键字，Value是数据值。

2、非关系型数据库

区别于关系型数据库，它不保证遵循ACID（Atomicity, Consistency, Isolation and Durability）特性，数据之间无关系。

进程中每个文件仅存在一个Preferences实例，应用获取到实例后，可以从中读取数据，或者将数据存入实例中。通过调用flush方法可以将实例中的数据回写到文件里。

与关系数据库的区别

分类	关系型数据库	首选项
数据库类型	关系型	非关系型
使用场景	提供复杂场景下的本地数据库管理机制	对Key-Value结构的数据进行存取和持久化操作
存储方式	SQLite数据库	文件
约束与限制	1.连接池最大4个2.同一时间只支持一个写操作	1.建议数据不超一万条2.Key为string型

4 常用接口介绍

常用接口有：保存数据（put）、获取数据（get）、是否包含指定的key（has）、删除数据（delete）、数据持久化（flush）等，后面依次详细介绍接口使用。

常用接口使用前提

1、需要导入@ohos.data.preferences模块到PreferencesUtil开发环境中，实例名字命名为dataPreferences，同时定义两个常量PREFERENCES_NAME和KEY_APP_FONT_SIZE。（注：把常用接口封装在PreferencesUtil工具类里面，为了方便后面代码直接调用）相关代码实现如下：

// PreferencesUtil.ets
import dataPreferences from '@ohos.data.preferences';
   ...
  const PREFERENCES_NAME = 'myPreferences'; // 首选项名字
  const KEY_APP_FONT_SIZE = 'appFontSize';  // 首选项Key字段

2、需要在entryAbility的onCreate方法获取首选项实例，以便后续能进行保存、读取、删除等操作，获取实例需要上下文context和文件名字PREFERENCES_NAME，相关代码实现如下：

// entryAbility.ets  
  onCreate(want, launchParam) {
    Logger.info(TAG, 'onCreate');
    globalThis.abilityWant = want;
    // 创建首选项
    PreferencesUtil.createFontPreferences(this.context);
    ...
  }

// PreferencesUtil.ets  
  createFontPreferences(context) {
    globalThis.getFontPreferences = (() => {
      // 获取首选项实例
      let preferences: Promise = dataPreferences.getPreferences(context, PREFERENCES_NAME);
      return preferences;
    });
  }

保存数据（put）

1、在entryAbility的onCreate方法，调用PreferencesUtil.saveDefaultFontSize保存默认数据，先用has方法判断当前key是否有存在，如果没有就通过put方法把用户数据保存起来，该方法通过key-value键值对方式保存，常量KEY_APP_FONT_SIZE作为key，用户数据fontSize作为value，再通过flush方法把数据保存到文件，相关代码实现如下：

// entryAbility.ets  
  onCreate(want, launchParam) {
    Logger.info(TAG, 'onCreate');
    globalThis.abilityWant = want;
    ...
    // 设置字体默认大小
    PreferencesUtil.saveDefaultFontSize(Constants.SET_SIZE_STANDARD);
  }

// PreferencesUtil.ets    
  saveDefaultFontSize(fontSize: number) {
    globalThis.getFontPreferences().then((preferences) => {
      // 判断保存的key是否存在
      preferences.has(KEY_APP_FONT_SIZE).then(async (isExist) => {
        Logger.info(TAG, 'preferences has changeFontSize is ' + isExist);
        if (!isExist) {
          // 保存数据
          await preferences.put(KEY_APP_FONT_SIZE, fontSize);
          preferences.flush();
        }
      }).catch((err) => {
        Logger.error(TAG, 'Has the value failed with err: ' + err);
      });
    }).catch((err) => {
      Logger.error(TAG, 'Get the preferences failed, err: ' + err);
    });
  }

2、在SetFontSizePage页面，当手指移动Slider滑动条时，在onChange方法回调当前进度值，把当前进度值通过PreferencesUtil.saveChangeFontSize方法保存起来，再通过flush方法把数据保存到文件，相关代码实现如下：

// SetFontSizePage.ets
  build() {
    Row() {
      Slider({
       ...
      }).onChange((value: number) => {
          // 保存当前进度值
          PreferencesUtil.saveChangeFontSize(this.changeFontSize);
      })
    }
  }

// PreferencesUtil.ets 
  saveChangeFontSize(fontSize: number) {
    globalThis.getFontPreferences().then(async (preferences) => {
      // 保存数据
      await preferences.put(KEY_APP_FONT_SIZE, fontSize);
      preferences.flush();
    }).catch((err) => {
      Logger.error(TAG, 'put the preferences failed, err: ' + err);
    });
  }

获取数据（get）

在HomePage的onPageShow方法，调用PreferencesUtil.getChangeFontSize方法获取用户数据，调用get方法获取，该方法通过key-value键值对方式读取，常量KEY_APP_FONT_SIZE作为key，默认数据fontSize作为value，把的到的结果赋值给变量fontSize，通过return方式把值返回去，相关代码实现如下：

// HomePage.ets
  onPageShow() {
    PreferencesUtil.getChangeFontSize().then((value) => {
      this.changeFontSize = value;
      Logger.info(TAG, 'Get the value of changeFontSize: ' + this.changeFontSize);
    });
  }

// PreferencesUtil.ets 
  async getChangeFontSize() {
    let fontSize: number = 0;
    const preferences = await globalThis.getFontPreferences();
    fontSize = await preferences.get(KEY_APP_FONT_SIZE, fontSize);
    return fontSize;
  }

是否包含指定的key（has）

通过has方法判断首选项中是否包含指定的key，保证指定的key不会被重复保存，相关代码实现如下：

// PreferencesUtil.ets    
  saveDefaultFontSize(fontSize: number) {
    globalThis.getFontPreferences().then((preferences) => {
      // 判断保存的key是否存在
      preferences.has(KEY_APP_FONT_SIZE).then(async (isExist) => {
        Logger.info(TAG, 'preferences has changeFontSize is ' + isExist);
      }).catch((err) => {
        Logger.error(TAG, 'Has the value failed with err: ' + err);
      });
    }).catch((err) => {
      Logger.error(TAG, 'Get the preferences failed, err: ' + err);
    });
  }

数据持久化（flush）

通过flush方法把应用数据保存到文件中，使得应用数据保存期限变长，相关代码实现如下：

// PreferencesUtil.ets 
  saveChangeFontSize(fontSize: number) {
    globalThis.getFontPreferences().then(async (preferences) => {
      // 保存数据
      await preferences.put(KEY_APP_FONT_SIZE, fontSize);
     // 数据持久化
      preferences.flush();
    }).catch((err) => {
      Logger.error(TAG, 'put the preferences failed, err: ' + err);
    });
  }

删除数据（delete）

删除首选项数据需要获取preferences实例，用delete方法删除指定的key所对应的值，常量KEY_APP_FONT_SIZE作为key，通过Promise异步回调是否删除成功，相关代码实现如下：

// PreferencesUtil.ets 
  async deleteChangeFontSize() {
    const preferences: dataPreferences.Preferences = await globalThis.getFontPreferences();
    // 删除数据
    let deleteValue = preferences.delete(KEY_APP_FONT_SIZE);
    deleteValue.then(() => {
      Logger.info(TAG, 'Succeeded in deleting the key appFontSize.');
    }).catch((err) => {
      Logger.error(TAG, 'Failed to delete the key appFontSize. Cause: ' + err);
    });
  }

5 参考链接

首选项参考：首选项。

如何获取三方库

目前提供了两种途径获取开源三方库：

通过访问Gitee网站开源社区获取

在Gitee中，搜索OpenHarmony-TPC仓库，在tpc_resource中对三方库进行了资源汇总，可以供开发者参考。
通过OpenHarmony三方库中心仓获取

进入OpenHarmony三方库中心仓，根据类型或者直接搜索寻找需要的三方库。

常用三方库介绍

常用的三方库可以分为UI、动画、网络、图片、多媒体、数据存储、安全、工具等。

UI库：
- @ohos/textlayoutbuilder：可以定制任一样式的文本构建工具，包括字体间距、大小、颜色、富文本高亮显示等。
- @ohos/roundedimageview：可以生成圆角矩形、或者椭圆形等图片形状。

网络库：
- @ohos/axios：可以运行在node.js 和浏览器中，基于Axios 原库v1.3.4版本进行适配，并沿用其现有用法和特性。
动画库：
- @ohos/lottie：可以解析Adobe After Effects软件通过Bodymovin插件导出的json格式的动画，并在移动设备上进行本地渲染。
- @ohos/svg：可以解析SVG图片并渲染到页面上。

其他类别不单独介绍，感兴趣的可以前往Gitee或者三方库中心仓了解更多。

三方库在系统能力的基础上，提供了更加方便的使用，在许多场景下，能够极大提升开发者的开发效率，下面将以@ohos/lottie为例介绍三方库的基本使用。

使用开源三方库@ohos/lottie

什么是@ohos/lottie

@ohos/lottie是基于lottie-web开发，集成在三方库社区内的开源版本，是HarmonyOS系统中复杂动画的一种解决方案。

动画是传达想法和创造更好的用户交互体验的工具，常见使用动画的场景如下：

启动动画：APP logo动画的播放。
加载动画：网络请求的loading动画。
上下拉刷新动画：请求更多资源时的刷新动画。
按钮动画：切换按钮、编辑按钮、播放按钮等按钮的切换过渡动画。
视图转场动画：一些场景的转场添加动画能够提升用户体验。

@ohos/lottie提供了使用JSON动画文件的解决方案，开发者可以在原生应用中像使用静态图像一样使用动画，而不用关注动画的实现过程，并且@ohos/lottie具有一套完整的API控制动画的行为，可以让动画更具有交互性。接下来将介绍@ohos/lottie的安装和基本使用。

@ohos/lottie的安装与卸载

安装@ohos/lottie

通过ohpm执行对应的指令，将lottie安装到项目中。
```
ohpm install @ohos/lottie
```
卸载@ohos/lottie

通过ohpm执行卸载指令，将lottie从项目中删除，其程序包和配置信息将会从项目中移除。
```
ohpm uninstall @ohos/lottie
```

使用@ohos/lottie

@ohos/lottie的引入

通过import指令在项目中引入@ohos/lottie到文件中。
```
import lottie from '@ohos/lottie'
```

构建Canvas画布

@ohos/lottie解析JSON动画文件的数据需要基于Canvas 画布进行2D渲染，所以在加载JSON动画之前，要先初始化渲染上下文，并在画面中创建Canvas画布区域，将对应的渲染上下文renderingContext传递给Canvas。

// 初始化渲染上下文  private renderingSettings: RenderingContextSettings = new RenderingContextSettings(true) // 设置开启抗锯齿private renderingContext: CanvasRenderingContext2D = new CanvasRenderingContext2D(this.renderingSettings)  // 创建2D渲染上下文
// 加载Canvas画布   Canvas(this.renderingContext)  ...

使用@ohos/lottie加载JSON动画

加载JSON动画需要用到loadAnimation方法，在方法中需配置相应的初始设置，包括渲染上下文、渲染方式以及JSON动画资源的路径等。可以直接使用lottie.loadAnimation方法，也可以用一个animationItem实例来接收返回的animationItem对象。

// 用animationItem实例接收let animationItem = lottie.loadAnimation({            container: this.renderingContext,            // 渲染上下文            renderer: 'canvas',                          // 渲染方式            loop: true,                                  // 是否循环播放,默认true            autoplay: true,                              // 是否自动播放，默认true            path: 'common/lottie/data.json',             // json路径          })          lottie.loadAnimation({                               // 或者直接使用            container: this.renderingContext,            // 渲染上下文            renderer: 'canvas',                          // 渲染方式            loop: true,                                  // 是否循环播放,默认true            autoplay: true,                              // 是否自动播放，默认true            path: 'common/lottie/data.json',             // json路径          })

@ohos/lottie控制动画

@ohos/lottie内封装了包括状态控制，进度控制，播放设置控制和属性控制等多个API，用户可以利用这些API完成对动画的控制，实现更加灵活的交互效果。

// 播放、暂停、停止、销毁  可以使用lottie，也可以使用animationItem实例进行控制lottie.play();        // 从目前停止的帧开始播放lottie.stop();        // 停止播放，回到第0帧lottie.pause();       // 暂停该动画，在当前帧停止并保持lottie.togglePause(); // 切换暂停/播放状态lottie.destroy();     // 删除该动画，移除相应的元素标签等。在unmount的时候，需要调用该方法
// 播放进度控制animationItem.goToAndStop(value, isFrame); // 跳到某个时刻/帧并停止。isFrame(默认false)指示value表示帧还是时间(毫秒)animationItem.goToAndPlay(value, isFrame); // 跳到某个时刻/帧并进行播放animationItem.goToAndStop(30, true);       // 例：跳转到第30帧并停止animationItem.goToAndPlay(300);            // 例：跳转到第300毫秒并播放
// 控制帧播放animationItem.setSegment(5,15);             // 限定动画资源播放时的整体帧范围，即设置动画片段animationItem.resetSegments(5,15);          // 重置播放的动画片段animationItem.playSegments(arr, forceFlag); // arr可以包含两个数字或者两个数字组成的数组，forceFlag表示是否立即强制播放该片段animationItem.playSegments([10,20], false); // 例：播放完之前的片段，播放10-20帧animationItem.playSegments([[5,15],[20,30]], true); //例： 直接播放5-15帧和20-30帧
// 动画基本属性控制lottie.setSpeed(speed);         // 设置播放速度，speed为1表示正常速度lottie.setDirection(direction); // 设置播放方向，1表示正向播放，-1表示反向播放
// 获取动画帧数属性animationItem.getDuration();    //获取动画时长

事件订阅

在一些特殊场景下，比如开始加载动画或者动画播放结束时，可能需要执行相应的操作，在@ohos/lottie中提供了事件订阅和取消订阅的功能，当触发对应的event，会执行传入的回调函数，用户可以在回调函数中完成要实现的功能。

// 订阅事件animationItem.addEventListener(event,function(){    // TODO something})
// 取消订阅事件animationItem.removeEventListener(event,function(){    // TODO something})

常见的event事件类型如下：

// event事件类型'enterFrame'   // 每进入一帧就会触发'loopComplete' // 当前循环下播放（循环播放/非循环播放）结束时触发'complete'     // 播放完成时触发'segmentStart' // 播放指定片段时触发，playSegments、resetSegments等方法刚开始播放指定片段时会发出，如果playSegments播放多个片段，多个片段最开始都会触发。'destroy'      // 销毁动画时触发'data_ready'   // 数据准备完成'DOMLoaded'    // 动画相关dom已经被添加'error'        // 出现错误'data_failed'  // 数据加载失败  ...

参考链接

三方库资源汇总：gitee.com/openharmony…
OpenHarmony三方库中心仓：ohpm.openharmony.cn
@ohos/lottie的使用：gitee.com/openharmony…

HarmonyOS基础学习文档搬运7(数据管理和三方库)