LueChan

其他：一多

Fri, 15 Mar 2024 00:00:00 GMT

概述

随着终端设备形态日益多样化，一个应用或服务，需要在不同的硬件设备之间调用，让用户体验无缝的全场景体验。HarmonyOS 系统面向多终端提供了“一次开发，多端部署”（后文中简称为“一多”）的能力，让开发者可以基于一种设计，高效构建多端可运行的应用。

定义和目标

定义：一套代码工程，一次开发上架，多端按需部署。

目标：支撑开发者快速高效的开发支持多种终端设备形态的应用，实现对不同设备兼容的同时，提供跨设备的流转、迁移和协同的分布式体验。

关键问题

为了实现“一多”的目标，需要解决如下三个基础问题：

问题1：页面如何适配

不同设备间的屏幕尺寸、色彩风格等存在差异，页面如何适配。

问题2：功能如何兼容

不同设备的系统能力有差异，如智能穿戴设备是否具备定位能力、智慧屏是否具备摄像头等，功能如何兼容。

问题3：工程如何组织

如何实现一套代码同时能部署到多种不同设备上，代码工程如何组织。

关键问题的解决思路

针对“一多”提出的三个基础问题，可以从界面级、功能级、工程级三个维度给出相关问题的解决思路：

界面级一多

页面级一多需要考虑不同设备间的屏幕尺寸、色彩风格等存在差异，页面如何适配。可以从布局能力、资源使用、交互归一几个方面去考虑。

布局能力

布局决定了页面中的元素按照何种方式排布及显示，是页面设计及开发过程中首先需要考虑的问题。一般情况下，可以通过页面（或自定义组件）内的组件结构（组件个数、组件的父子/兄弟关系、组件类型、组件的相对位置）来判断使用何种布局能力。

对于随尺寸变化组件结构相同的场景，可以在开发过程中灵活使用自适应布局能力来达到目标效果。

对于随尺寸变化组件结构不同的场景，更适合使用响应式布局能力来实现不同尺寸下的不同显示的效果。

布局可以分为自适应布局和响应式布局，二者的介绍如下表所示：

名称	简介
自适应布局	当外部容器大小发生变化时，元素可以根据相对关系自动变化以适应外部容器变化的布局能力。相对关系如占比、固定宽高比、显示优先级等。当前自适应布局能力有7种：拉伸能力、均分能力、占比能力、缩放能力、延伸能力、隐藏能力、折行能力。自适应布局能力可以实现界面显示随外部容器大小连续变化。
响应式布局	当外部容器大小发生变化时，元素可以根据断点、栅格或特定的特征（如屏幕方向、窗口宽高等）自动变化以适应外部容器变化的布局能力。当前响应式布局能力有3种：断点、媒体查询、栅格布局。响应式布局可以实现界面随外部容器大小有级不连续变化，通常不同特征下的界面显示会有较大的差异。

自适应布局

针对常见的开发场景，方舟开发框架提炼了七种自适应布局能力，这些布局可以独立使用，也可多种布局叠加使用。

自适应布局能力	使用场景	实现方式
拉伸能力	容器组件尺寸发生变化时，增加或减小的空间全部分配给容器组件内指定区域。	Flex布局的flexGrow和flexShrink属性
均分能力	容器组件尺寸发生变化时，增加或减小的空间均匀分配给容器组件内所有空白区域。	Row组件、Column组件或Flex组件的justifyContent属性设置为FlexAlign.SpaceEvenly
占比能力	子组件的宽或高按照预设的比例，随容器组件发生变化。	基于通用属性的两种实现方式： - 将子组件的宽高设置为父组件宽高的百分比 - layoutWeight属性
缩放能力	子组件的宽高按照预设的比例，随容器组件发生变化，且变化过程中子组件的宽高比不变。	布局约束的aspectRatio属性
延伸能力	容器组件内的子组件，按照其在列表中的先后顺序，随容器组件尺寸变化显示或隐藏。	基于容器组件的两种实现方式： - 通过List组件实现 - 通过Scroll组件配合Row组件或Column组件实现
隐藏能力	容器组件内的子组件，按照其预设的显示优先级，随容器组件尺寸变化显示或隐藏。相同显示优先级的子组件同时显示或隐藏。	布局约束的displayPriority属性
折行能力	容器组件尺寸发生变化时，如果布局方向尺寸不足以显示完整内容，自动换行。	Flex组件的wrap属性设置为FlexWrap.Wrap

响应式布局

响应式布局是指页面内的元素可以根据特定的特征（如窗口宽度、屏幕方向等）自动变化以适应外部容器变化的布局能力。响应式布局中最常使用的特征是窗口宽度，可以将窗口宽度划分为不同的范围（下文中称为断点）。当窗口宽度从一个断点变化到另一个断点时，改变页面布局（如将页面内容从单列排布调整为双列排布甚至三列排布等）以获得更好的显示效果。

响应式布局能力	简介
断点	将窗口宽度划分为不同的范围（即断点），监听窗口尺寸变化，当断点改变时同步调整页面布局。
媒体查询	媒体查询支持监听窗口宽度、横竖屏、深浅色、设备类型等多种媒体特征，当媒体特征发生改变时同步调整页面布局。
栅格布局	栅格组件将其所在的区域划分为有规律的多列，通过调整不同断点下的栅格组件的参数以及其子组件占据的列数等，实现不同的布局效果。

资源使用

在页面开发过程中，经常需要用到颜色、字体、间距、图片等资源，在不同的设备或配置中，这些资源的值可能不同。有两种方式处理：

应用资源：借助资源文件能力，开发者在应用中自定义资源，自行管理这些资源在不同的设备或配置中的表现。

系统资源：开发者直接使用系统预置的资源定义（即分层参数）。

交互归一

对于不同类型的智能设备，用户可能有不同的交互方式，如通过触摸屏、鼠标、触控板等。如果针对不同的交互方式单独做适配，会增加开发工作量同时产生大量重复代码。为解决这一问题，我们统一了各种交互方式的API，即实现了交互归一。

常见的基础输入方式及其在各输入设备上的表现如下图所示。

功能级一多

应用开发至少包含两部分工作： UI页面开发和底层功能开发（部分需要联网的应用还会涉及服务端开发）。前面章节介绍了如何解决页面适配的问题，本章节主要介绍应用如何解决设备系统能力差异的兼容问题。

系统能力

系统能力（即SystemCapability，缩写为SysCap）指操作系统中每一个相对独立的特性，如蓝牙，WIFI，NFC，摄像头等，都是系统能力之一。每个系统能力对应多个API，随着目标设备是否支持该系统能力共同存在或消失。

与系统能力相关的，有支持能力集、联想能力集和要求能力集三个核心概念。

支持能力集：设备具备的系统能力集合，在设备配置文件中配置。

要求能力集：应用需要的系统能力集合，在应用配置文件中配置。

联想能力集：开发应用时IDE可联想的API所在的系统能力集合，在应用配置文件中配置。

说明

只有当应用要求能力集是设备支持能力集的子集的时候，应用才可以在该设备上分发、安装和运行。

可以访问系统能力列表了解全量的系统能力。

动态逻辑判断

如果某个系统能力没有写入应用的要求能力集中，那么在使用前需要判断设备是否支持该系统能力。

方法1：HarmonyOS定义了API canIUse帮助开发者来判断该设备是否支持某个特定的syscap。

方法2：开发者可通过import的方式将模块导入，若当前设备不支持该模块，import的结果为undefined，开发者在使用其API时，需要判断其是否存在。

💡

说明

如果某系统能力是应用运行必须的，则要将其写入到应用的要求能力集中，以确保应用不会分发和安装到不符合要求的设备上。

如果某系统能力不是应用运行必须的，则可以在运行时做动态判断，这样可以最大程度扩大应用的适用范围。

配置联想能力集和要求能力集

IDE会根据创建的工程所支持的设备自动配置联想能力集和要求能力集，同时也支持开发者修改。

💡

说明

对于要求能力集，开发者修改时要十分慎重，修改不当会导致应用无法分发和安装到目标设备上。

对于联想能力集，通过增加系统能力可以扩大IDE可联想的API范围。但要注意这些API可能在某些设备上不支持，使用前需要判断。

工程级一多

工程级一多需要考虑如何实现一套代码同时能部署到多种不同设备上，代码工程如何组织。

应用程序包结构

在进行应用开发时，一个应用通常包含一个或多个Module。Module是HarmonyOS应用/服务的基本功能单元，包含了源代码、资源文件、第三方库及应用/服务配置文件，每一个Module都可以独立进行编译和运行。

Module分为“Ability”和“Library”两种类型：

“Ability”类型的Module编译后生成HAP包。

“Library”类型的Module编译后生成HAR包。

HarmonyOS的应用以APP Pack形式发布，其包含一个或多个HAP包。HAP是HarmonyOS应用安装的基本单位，HAP可以分为Entry和Feature两种类型：

Entry类型的HAP：应用的主模块。在同一个应用中，同一设备类型只支持一个Entry类型的HAP，通常用于实现应用的入口界面、入口图标、主特性功能等。

Feature类型的HAP：应用的动态特性模块。Feature类型的HAP通常用于实现应用的特性功能，一个应用程序包可以包含一个或多个Feature类型的HAP，也可以不包含。

部署模型

“一多”有两种部署模型：

部署模型A：不同类型的设备上按照一定的工程结构组织方式，通过一次编译生成相同的HAP（或HAP组合）。

部署模型B：不同类型的设备上按照一定的工程结构组织方式，通过一次编译生成不同的HAP（或HAP组合）。

开发者可以从应用UX设计及应用功能两个维度，结合具体的业务场景，考虑选择哪种部署模型。当然，也可以借助设备类型分类，快速做出判断。

从屏幕尺寸、输入方式及交互距离三个维度考虑，可以将常用类型的设备分为不同泛类：

默认设备、平板

车机、智慧屏

智能穿戴

……

对于相同泛类的设备，优先选择部署模型A，对于不同泛类设备，优先选择部署模型B。

说明

应用在不同泛类设备上的UX设计或功能相似时，可以使用部署模型A。

应用在同一泛类不同类型设备上UX设计或功能差异非常大时，可以使用部署模型B，但同时也应审视应用的UX设计及功能规划是否合理。

本小节引入部署模型A和部署模型B的概念是为了方便开发者理解。实际上在开发多设备应用时，如果目标设备类型较多，往往是部署模型A和部署模型B混合使用。

不管采用哪种部署模型，都应该采用一次编译。

工程结构

“一多”推荐在应用开发过程中使用如下的“三层工程结构”。

common（公共能力层）：用于存放公共基础能力集合（如工具库、公共配置等）。

common层不可分割，需编译成一个HAR包，其只可以被products和features依赖，不可以反向依赖。

features（基础特性层）：用于存放基础特性集合（如应用中相对独立的各个功能的UI及业务逻辑实现等）。

各个feature高内聚、低耦合、可定制，供产品灵活部署。不需要单独部署的feature通常编译为HAR包，供products或其它feature使用。需要单独部署的feature通常编译为Feature类型的HAP包，和products下Entry类型的HAP包进行组合部署。features层可以横向调用及依赖common层，同时可以被products层不同设备形态的HAP所依赖，但是不能反向依赖products层。

products（产品定制层）：用于针对不同设备形态进行功能和特性集成。

products层各个子目录各自编译为一个Entry类型的HAP包，作为应用主入口。products层不可以横向调用。

代码工程结构抽象后一般如下所示：

💡

说明

部署模型不同，相应的代码工程结构也有差异。部署模型A和部署模型B的主要差异点集中在products层：部署模型A在products目录下同一子目录中做功能和特性集成；部署模型B在products目录下不同子目录中对不同的产品做差异化的功能和特性集成。

开发阶段应考虑不同类型设备间最大程度的复用代码，以减少开发及后续维护的工作量。

整个代码工程最终构建出一个APP包，应用以APP包的形式发布到应用市场中。

参考链接

“一次开发，多端部署”的参考指南中详细讲解了一多的相关知识、UX设计、架构规范等，可供开发者参考。

其他：应用程序包结构

Sun, 25 Feb 2024 00:00:00 GMT

为了让开发者能对应用程序包在不同阶段的形态更有清晰的认知，分别对开发态、编译态、发布态的应用程序结构展开介绍。

开发态包结构

在DevEco Studio上创建一个项目工程，并尝试创建多个不同类型的Module。根据实际工程中的目录对照本章节进行学习，可以有助于理解开发态的应用程序结构。

图1 项目工程结构示意图（以实际为准）

工程结构主要包含的文件类型及用途如下：

说明

AppScope目录由DevEco Studio自动生成，不可更改。

Module目录名称可以由DevEco Studio自动生成（比如entry、library等），也可以自定义。为了便于说明，下表中统一采用Module_name表示。

文件类型	说明
配置文件	包括应用级配置信息、以及Module级配置信息： - AppScope > app.json5：app.json5配置文件，用于声明应用的全局配置信息，比如应用Bundle名称、应用名称、应用图标、应用版本号等。 - Module_name > src > main > module.json5：module.json5配置文件，用于声明Module基本信息、支持的设备类型、所含的组件信息、运行所需申请的权限等。
ArkTS源码文件	Module_name > src > main > ets：用于存放Module的ArkTS源码文件（.ets文件）。
资源文件	包括应用级资源文件、以及Module级资源文件，支持图形、多媒体、字符串、布局文件等，详见资源分类与访问。 - AppScope > resources ：用于存放应用需要用到的资源文件。 - Module_name > src > main > resources ：用于存放该Module需要用到的资源文件。
其他配置文件	用于编译构建，包括构建配置文件、编译构建任务脚本、混淆规则文件、依赖的共享包信息等。 - build-profile.json5：工程级或Module级的构建配置文件，包括应用签名、产品配置等。 - hvigorfile.ts：应用级或Module级的编译构建任务脚本，开发者可以自定义编译构建工具版本、控制构建行为的配置参数。 - obfuscation-rules.txt：混淆规则文件。混淆开启后，在使用Release模式进行编译时，会对代码进行编译、混淆及压缩处理，保护代码资产。 - oh-package.json5：用于存放依赖库的信息，包括所依赖的三方库和共享包。

编译态包结构

不同类型的Module编译后会生成对应的HAP、HAR、HSP等文件，开发态视图与编译态视图的对照关系如下：

图2 开发态与编译态的工程结构视图

从开发态到编译态，Module中的文件会发生如下变更：

ets目录：ArkTS源码编译生成.abc文件。

resources目录：AppScope目录下的资源文件会合入到Module下面资源目录中，如果两个目录下的存在重名文件，编译打包后只会保留AppScope目录下的资源文件。

module配置文件：AppScope目录下的app.json5文件字段会合入到Module下面的module.json5文件之中，编译后生成HAP或HSP最终的module.json文件。

说明

在编译HAP和HSP时，会把他们所依赖的HAR直接编译到HAP和HSP中。

发布态包结构

每个应用中至少包含一个.hap文件，可能包含若干个.hsp文件、也可能不含，一个应用中的所有.hap与.hsp文件合在一起称为Bundle，其对应的bundleName是应用的唯一标识（详见app.json5配置文件中的bundleName标签）。

当应用发布上架到应用市场时，需要将Bundle打包为一个.app后缀的文件用于上架，这个.app文件称为App Pack（Application Package），与此同时，DevEco Studio工具自动会生成一个pack.info文件。pack.info文件描述了App Pack中每个HAP和HSP的属性，包含APP中的bundleName和versionCode信息、以及Module中的name、type和abilities等信息。

说明

App Pack是发布上架到应用市场的基本单元，但是不能在设备上直接安装和运行。

在应用签名、云端分发、端侧安装时，都是以HAP/HSP为单位进行签名、分发和安装的。

图3 编译发布与上架部署流程图

选择合适的包类型

HAP、HAR、HSP三者的功能和使用场景总结对比如下：

Module类型	包类型	说明
Ability	HAP	应用的功能模块，可以独立安装和运行，必须包含一个entry类型的HAP，可选包含一个或多个feature类型的HAP。
Static Library	HAR	静态共享包，编译态复用。 - 支持应用内共享，也可以发布后供其他应用使用。 - 作为二方库，发布到OHPM私仓，供公司内部其他应用使用。 - 作为三方库，发布到OHPM中心仓，供其他应用使用。 - 多包（HAP/HSP）引用相同的HAR时，会造成多包间代码和资源的重复拷贝，从而导致应用包膨大。
Shared Library	HSP	动态共享包，运行时复用。 - 当前仅支持应用内共享。 - 当多包（HAP/HSP）同时引用同一个共享包时，采用HSP替代HAR，可以避免HAR造成的多包间代码和资源的重复拷贝，从而减小应用包大小。

HAP、HSP、HAR支持的规格对比如下，其中“√”表示是，“×”表示否。

开发者可以根据实际场景所需的能力，选择相应类型的包进行开发。在后续的章节中还会针对如何使用HAP、HAR、HSP分别展开详细介绍。

规格	HAP	HAR	HSP
支持在配置文件中声明UIAbility组件与ExtensionAbility组件	√	×	×
支持在配置文件中声明pages页面	√	×	√
支持包含资源文件与.so文件	√	√	√
支持依赖其他HAR文件	√	√	√
支持依赖其他HSP文件	√	×	√
支持在设备上独立安装运行	√	×	×

说明

HAR虽然不支持在配置文件中声明pages页面，但是可以包含pages页面，并通过命名路由的方式进行跳转。

HAR和HSP均不支持循环依赖，也不支持依赖传递。

进阶：数据存储

Sun, 08 Oct 2023 00:00:00 GMT

概述

数据存储，即应用数据持久化，是指应用将内存中的数据通过文件或数据库的形式保存到设备上。内存中的数据形态通常是任意的数据结构或数据对象，存储介质上的数据形态可能是文本、数据库、二进制文件等。HarmonyOS标准系统支持典型的存储数据形态，包括用户首选项、键值型数据库、关系型数据库。

用户首选项（Preferences）：通常用于保存应用的配置信息。数据通过文本的形式保存在设备中，应用使用过程中会将文本中的数据全量加载到内存中，所以访问速度快、效率高，但不适合需要存储大量数据的场景。

键值型数据库（KV-Store）：一种非关系型数据库，其数据以“键值”对的形式进行组织、索引和存储，其中“键”作为唯一标识符。适合很少数据关系和业务关系的业务数据存储，同时因其在分布式场景中降低了解决数据库版本兼容问题的复杂度，和数据同步过程中冲突解决的复杂度而被广泛使用。相比于关系型数据库，更容易做到跨设备跨版本兼容。

关系型数据库（RelationalStore）：一种关系型数据库，以行和列的形式存储数据，广泛用于应用中的关系型数据的处理，包括一系列的增、删、改、查等接口，开发者也可以运行自己定义的SQL语句来满足复杂业务场景的需要。

一、用户首选项

用户首选项Preferences，类似于Android中的SharedPreferences，为应用提供Key-Value键值型的数据存储能力，常用于轻量级的数据存储，如应用配置。进程中每个文件对应一个Preferences实例，应用获取到实例后，可以从中读取数据，或者将数据存入实例中。通过调用flush方法可以将实例中的数据回写到文件里。

1.1 首选项与非关系数据库的对比

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

1.2 接口说明

以下是用户首选项持久化功能的相关接口，大部分为异步接口。异步接口均有callback和Promise两种返回形式，下表均以callback形式为例，更多接口及使用方式请见用户首选项。

接口名称	描述
getPreferences(context: Context, name: string, callback: AsyncCallback): void	获取Preferences实例。
put(key: string, value: ValueType, callback: AsyncCallback): void	将数据写入Preferences实例，可通过flush将Preferences实例持久化。
has(key: string, callback: AsyncCallback): void	检查Preferences实例是否包含名为给定Key的存储键值对。给定的Key值不能为空。
get(key: string, defValue: ValueType, callback: AsyncCallback): void	获取键对应的值，如果值为null或者非默认值类型，返回默认数据defValue。
delete(key: string, callback: AsyncCallback): void	从Preferences实例中删除名为给定Key的存储键值对。
flush(callback: AsyncCallback): void	将当前Preferences实例的数据异步存储到用户首选项持久化文件中。
on(type: 'change', callback: Callback<{ key : string }>): void	订阅数据变更，订阅的Key的值发生变更后，在执行flush方法后，触发callback回调。
off(type: 'change', callback?: Callback<{ key : string }>): void	取消订阅数据变更。
deletePreferences(context: Context, name: string, callback: AsyncCallback): void	从内存中移除指定的Preferences实例。若Preferences实例有对应的持久化文件，则同时删除其持久化文件。

1.3 示例

二、键值型数据库

2.1 场景介绍

键值型数据库存储键值对形式的数据，当需要存储的数据没有复杂的关系模型，比如存储商品名称及对应价格、员工工号及今日是否已出勤等，由于数据复杂度低，更容易兼容不同数据库版本和设备类型，因此推荐使用键值型数据库持久化此类数据。

2.2 约束限制

设备协同数据库，针对每条记录，Key的长度≤896 Byte，Value的长度<4 MB。

单版本数据库，针对每条记录，Key的长度≤1 KB，Value的长度<4 MB。

每个应用程序最多支持同时打开16个键值型分布式数据库。

键值型数据库事件回调方法中不允许进行阻塞操作，例如修改UI组件。

2.3 接口说明

以下是键值型数据库持久化功能的相关接口，大部分为异步接口。异步接口均有callback和Promise两种返回形式，下表均以callback形式为例，更多接口及使用方式请见分布式键值数据库。

接口名称	描述
createKVManager(config: KVManagerConfig): KVManager	创建一个KVManager对象实例，用于管理数据库对象。
getKVStore(storeId: string, options: Options, callback: AsyncCallback): void	指定Options和storeId，创建并得到指定类型的KVStore数据库。
put(key: string, value: Uint8Array\|string\|number\|boolean, callback: AsyncCallback): void	添加指定类型的键值对到数据库。
get(key: string, callback: AsyncCallback): void	获取指定键的值。
delete(key: string, callback: AsyncCallback): void	从数据库中删除指定键值的数据。

2.3 示例

三、关系型数据库

3.1 场景介绍

关系型数据库基于SQLite组件，适用于存储包含复杂关系数据的场景，比如一个班级的学生信息，需要包括姓名、学号、各科成绩等，又或者公司的雇员信息，需要包括姓名、工号、职位等，由于数据之间有较强的对应关系，复杂程度比键值型数据更高，此时需要使用关系型数据库来持久化保存数据。

3.2 基本概念

谓词：数据库中用来代表数据实体的性质、特征或者数据实体之间关系的词项，主要用来定义数据库的操作条件。

结果集：指用户查询之后的结果集合，可以对数据进行访问。结果集提供了灵活的数据访问方式，可以更方便地拿到用户想要的数据。

3.3 运作机制

关系型数据库对应用提供通用的操作接口，底层使用SQLite作为持久化存储引擎，支持SQLite具有的数据库特性，包括但不限于事务、索引、视图、触发器、外键、参数化查询和预编译SQL语句。

3.4 约束限制

系统默认日志方式是WAL（Write Ahead Log）模式，系统默认落盘方式是FULL模式。

数据库中连接池的最大数量是4个，用以管理用户的读操作。

为保证数据的准确性，数据库同一时间只能支持一个写操作。

当应用被卸载完成后，设备上的相关数据库文件及临时文件会被自动清除。

3.5 接口说明

以下是关系型数据库持久化功能的相关接口，大部分为异步接口。异步接口均有callback和Promise两种返回形式，下表均以callback形式为例，更多接口及使用方式请见关系型数据库。

接口名称	描述
getRdbStore(context: Context, config: StoreConfig, callback: AsyncCallback): void	获得一个相关的RdbStore，操作关系型数据库，用户可以根据自己的需求配置RdbStore的参数，然后通过RdbStore调用相关接口可以执行相关的数据操作。
executeSql(sql: string, bindArgs: Array, callback: AsyncCallback):void	执行包含指定参数但不返回值的SQL语句。
insert(table: string, values: ValuesBucket, callback: AsyncCallback):void	向目标表中插入一行数据。
update(values: ValuesBucket, predicates: RdbPredicates, callback: AsyncCallback):void	根据RdbPredicates的指定实例对象更新数据库中的数据。
delete(predicates: RdbPredicates, callback: AsyncCallback):void	根据RdbPredicates的指定实例对象从数据库中删除数据。
query(predicates: RdbPredicates, columns: Array, callback: AsyncCallback):void	根据指定条件查询数据库中的数据。
deleteRdbStore(context: Context, name: string, callback: AsyncCallback): void	删除数据库。

3.6 示例

附：参考链接

用户首选项参考

数据持久化概述

核心应用组件系列：后台服务

Fri, 29 Sep 2023 00:00:00 GMT

OpenHarmony中，后台服务能力由ServiceExtensionAbility提供；ServiceExtensionAbility支持以启动和连接两种形式运行。

启动和连接后台服务的差别：

启动：AbilityA启动ServiceB，启动后AbilityA和ServiceB为弱关联，AbilityA退出后，ServiceB可以继续存在。

连接：AbilityA绑定ServiceB，绑定后AbilityA和ServiceB为强关联，AbilityA退出后，ServiceB也一起退出。

系统应用和三方应用的差别：

系统应用可以调用startServiceExtensionAbility()方法启动后台服务，也可以调用connectServiceExtensionAbility()方法连接后台服务，

三方应用只能调用connectServiceExtensionAbility()方法连接后台服务。

本文描述中称被启动的ServiceExtensionAbility为服务端，称启动ServiceExtensionAbility的组件为客户端。本章节将从如下场景来介绍ServiceExtensionAbility的基本使用。

实现一个后台服务（Server，仅对系统应用开放）

启动一个后台服务（Client，仅对系统应用开放）

连接一个后台服务（Client）

说明：
OpenHarmony当前不支持三方应用实现ServiceExtensionAbility。如果三方开发者想要实现后台处理相关事务的功能，可以使用后台任务，具体请参见后台任务。
三方应用的UIAbility组件可以通过Context连接系统提供的ServiceExtensionAbility。
三方应用需要在前台获焦的情况下才能连接系统提供的ServiceExtensionAbility。
每个类型的ExtensionAbility都有自己的Context，ServiceExtensionAbility通过ServiceExtensionContext提供相关能力。

实现一个后台服务（Server，仅对系统应用开放）

ServiceExtensionAbility提供了onCreate()、onRequest()、onConnect()、onDisconnect()和onDestory()生命周期回调，根据需要重写对应的回调方法。下图展示了ServiceExtensionAbility的生命周期。

图1 ServiceExtensionAbility生命周期

onCreate 服务被首次创建时触发该回调，开发者可以在此进行一些初始化的操作，例如注册公共事件监听等。

说明：如果服务已创建，再次启动该ServiceExtensionAbility不会触发onCreate()回调。

onRequest 当另一个组件调用startServiceExtensionAbility()方法启动该服务组件时，触发该回调。执行此方法后，服务会启动并在后台运行。

onConnect 当另一个组件调用connectServiceExtensionAbility()方法与该服务连接时，触发该回调。开发者在此方法中，返回一个远端代理对象（IRemoteObject），客户端拿到这个对象后可以通过这个对象与服务端进行RPC通信。

onDisconnect 其他组件调用disconnectServiceExtensionAbility()方法时，如果没有任何其他组件连接该服务，触发该回调。

onDestroy 当不再使用服务且准备将其销毁该实例时，触发该回调。开发者可以在该回调中清理资源，如注销监听等。

开发步骤

开发者在实现一个后台服务时，需要在DevEco Studio工程中手动新建一个ServiceExtensionAbility，具体步骤如下。

在工程Module对应的ets目录下，右键选择“New > Directory”，新建一个目录并命名为serviceextability。

在serviceextability目录，右键选择“New > TypeScript File”，新建一个TypeScript文件并命名为ServiceExtAbility.ts。

打开ServiceExtAbility.ts文件，导入RPC通信模块，重载onRemoteMessageRequest()方法，接收客户端传递过来的消息，并将处理的结果返回给客户端。REQUEST_VALUE用于校验客户端发送的服务请求码。

在ServiceExtAbility.ts文件中，增加导入ServiceExtensionAbility的依赖包，自定义类继承ServiceExtensionAbility并加上需要的生命周期回调。

在工程Module对应的module.json5配置文件中注册ServiceExtensionAbility，type标签需要设置为“service”，srcEntrance标签表示当前ExtensionAbility组件所对应的代码路径。

启动一个后台服务（Client，仅对系统应用开放）

系统应用通过startServiceExtensionAbility()方法启动一个后台服务，服务的onRequest()回调就会被调用，并在该回调方法中接收到调用者传递过来的want对象。后台服务启动后，其生命周期独立于客户端，即使客户端已经销毁，该后台服务仍可继续运行。因此，后台服务需要在其工作完成时通过调用ServiceExtensionContext的terminateSelf()来自行停止，或者由另一个组件调用stopServiceExtensionAbility()来将其停止。

说明： ServiceExtensionContext的startServiceExtensionAbility()、stopServiceExtensionAbility()和terminateSelf()为系统接口，三方应用不支持调用。

在系统应用中启动一个新的ServiceExtensionAbility。示例中的context的获取方式请参见获取UIAbility的上下文信息。

在系统应用中停止一个已启动的ServiceExtensionAbility。

已启动的ServiceExtensionAbility停止自身。

说明：后台服务可以在后台长期运行，为了避免资源浪费，需要对后台服务的生命周期进行管理。即一个后台服务完成了请求方的任务，需要及时销毁。销毁已启动的后台服务有两种方式：
后台服务自身调用terminateSelf()方法来自行停止。
由其他组件调用stopServiceExtensionAbility()方法来停止。
调用terminateSelf()或stopServiceExtensionAbility()方法之后，系统将销毁后台服务。

连接一个后台服务（Client）

系统应用或者三方应用可以通过connectServiceExtensionAbility()连接一个服务（在Want对象中指定启动的目标服务），服务的onConnect()就会被调用，并在该回调方法中接收到调用者传递过来的Want对象，从而建立长连接。

ServiceExtensionAbility服务组件在onConnect()中返回IRemoteObject对象，开发者通过该IRemoteObject定义通信接口，用于客户端与服务端进行RPC交互。多个客户端可以同时连接到同一个后台服务，客户端完成与服务的交互后，客户端需要通过调用disconnectServiceExtensionAbility()来断开连接。如果所有连接到某个后台服务的客户端均已断开连接，则系统会销毁该服务。

使用connectServiceExtensionAbility()建立与后台服务的连接。示例中的context的获取方式请参见获取UIAbility的上下文信息。

使用disconnectServiceExtensionAbility()断开与后台服务的连接。

核心应用组件系列：数据共享

Sun, 20 Aug 2023 00:00:00 GMT

跨应用访问数据时，可以通过DataShareExtensionAbility拉起数据提供方的应用以实现对数据的访问。

此种方式支持跨应用拉起数据提供方的DataShareExtension，数据提供方的开发者可以在回调中实现灵活的业务逻辑。用于跨应用复杂业务场景。

运作机制

数据共享可分为数据的提供方和访问方两部分。

数据提供方：DataShareExtensionAbility，可以选择性实现数据的增、删、改、查，以及文件打开等功能，并对外共享这些数据。

数据访问方：由createDataShareHelper()方法所创建的工具类，利用工具类，便可以访问提供方提供的这些数据。

图1 数据共享运作机制

DataShareExtensionAbility模块为数据提供方，实现跨应用数据共享的相关业务。

DataShareHelper模块为数据访问方，提供各种访问数据的接口，包括增删改查等。

数据访问方与提供方通过IPC进行通信，数据提供方可以通过数据库实现，也可以通过其他数据存储方式实现。

ResultSet模块通过共享内存实现，用于存储查询数据得到的结果集，并提供了遍历结果集的方法。

实现说明

数据提供方应用的开发（仅限系统应用）

DataShareExtensionAbility提供以下API，根据需要重写对应回调方法。

onCreate：DataShare客户端连接DataShareExtensionAbility服务端时，服务端需要在此回调中实现初始化业务逻辑，该方法可以选择性重写。

insert：业务函数，客户端请求插入数据时回调此接口，服务端需要在此回调中实现插入数据功能，该方法可以选择性重写。

update：业务函数，客户端请求更新数据时回调此接口，服务端需要在此回调中实现更新数据功能，该方法可以选择性重写。

delete：业务函数，客户端请求删除数据时回调此接口，服务端需要在此回调中实现删除数据功能，该方法可以选择性重写。

query：业务函数，客户端请求查询数据时回调此接口，服务端需要在此回调中实现查询数据功能，该方法可以选择性重写。

batchInsert：业务函数，客户端请求批量插入数据时回调此接口，服务端需要在此回调中实现批量插入数据的功能，该方法可以选择性重写。

normalizeUri：业务函数，客户端给定的URI转换为服务端使用的URI时回调此接口，该方法可以选择性重写。

denormalizeUri：业务函数，服务端使用的URI转换为客户端传入的初始URI时服务端回调此接口，该方法可以选择性重写。

开发者在实现一个数据共享服务时，需要在DevEco Studio工程中手动新建一个DataShareExtensionAbility，具体步骤如下。

在工程Module对应的ets目录下，右键选择“New > Directory”，新建一个目录并命名为DataShareExtAbility。

在DataShareAbility目录，右键选择“New > TypeScript File”，新建一个TypeScript文件并命名为DataShareExtAbility.ts。

在DataShareExtAbility.ts文件中，导入

@ohos.application.DataShareExtensionAbility模块，开发者可根据应用需求选择性重写其业务实现。例如数据提供方只提供插入、删除和查询服务，则可只重写这些接口，并导入对应的基础依赖模块。

数据提供方的业务实现由开发者自定义。例如可以通过数据库、读写文件或访问网络等各方式实现数据提供方的数据存储。

在module.json5中定义DataShareExtensionAbility。

表1 module.json5对应属性字段

属性名称	备注说明	必填
name	Ability名称，对应Ability派生的ExtensionAbility类名。	是
type	Ability类型，DataShare对应的Ability类型为“dataShare”，表示基于datashare模板开发的。	是
uri	通信使用的URI，是客户端链接服务端的唯一标识。	是
exported	对其他应用是否可见，设置为true时，才能与其他应用进行通信传输数据。	是
readPermission	访问数据时需要的权限，不配置默认不进行读权限校验。	否
writePermission	修改数据时需要的权限，不配置默认不进行写权限校验。	否
metadata	增加静默访问所需的额外配置项，包含name和resource字段。 name类型固定为"ohos.extension.dataShare"，是配置的唯一标识。 resource类型固定为"$profile:data_share_config"，表示配置文件的名称为data_share_config.json。	若Ability启动模式为"singleton"，则metadata必填，Ability启动模式可见abilities对象的内部结构-launchType；其他情况下无需填写。

module.json5配置样例：

表2 data_share_config.json对应属性字段

属性名称	备注说明	必填
tableConfig	配置标签。	是
uri	指定配置生效的范围，uri支持以下三种格式，优先级为表配置>库配置>，如果同时配置，高优先级会覆盖低优先级。 1. "" : 所有的数据库和表。 2. "datashare:///{bundleName}/{moduleName}/{storeName}" : 指定数据库。 3. "datashare:///{bundleName}/{moduleName}/{storeName}/{tableName}" : 指定表。	是
crossUserMode	标识数据是否为多用户共享，配置为1则多用户数据共享，配置为2则多用户数据隔离。	是

data_share_config.json配置样例

数据访问方应用的开发 1. 导入基础依赖包。

2. 定义与数据提供方通信的URI字符串。

3. 创建工具接口类对象。

4. 获取到接口类对象后，便可利用其提供的接口访问提供方提供的服务，如进行数据的增删改查等。

核心应用组件系列：公共事件 ~

Wed, 16 Aug 2023 00:00:00 GMT

CES（Common Event Service，公共事件服务）为应用程序提供订阅、发布、退订公共事件的能力。

公共事件从系统角度可分为：系统公共事件和自定义公共事件。

系统公共事件：CES内部定义的公共事件，当前仅支持系统应用和系统服务发布，例如HAP安装，更新，卸载等公共事件。目前支持的系统公共事件请参见系统公共事件列表。

自定义公共事件：应用定义的公共事件，可用于实现跨进程的事件通信能力。

公共事件按发送方式可分为：无序公共事件、有序公共事件和粘性公共事件。

无序公共事件：CES在转发公共事件时，不考虑订阅者是否接收到该事件，也不保证订阅者接收到该事件的顺序与其订阅顺序一致。

有序公共事件：CES在转发公共事件时，根据订阅者设置的优先级等级，优先将公共事件发送给优先级较高的订阅者，等待其成功接收该公共事件之后再将事件发送给优先级较低的订阅者。如果有多个订阅者具有相同的优先级，则他们将随机接收到公共事件。

粘性公共事件：能够让订阅者收到在订阅前已经发送的公共事件就是粘性公共事件。普通的公共事件只能在订阅后发送才能收到，而粘性公共事件的特殊性就是可以先发送后订阅，同时也支持先订阅后发送。发送粘性事件必须是系统应用或系统服务，粘性事件发送后会一直存在系统中，且发送者需要申请ohos.permission.COMMONEVENT_STICKY权限，配置方式请参见声明权限。

每个应用都可以按需订阅公共事件，订阅成功，当公共事件发布时，系统会将其发送给对应的应用。这些公共事件可能来自系统、其他应用和应用自身。

图1 公共事件示意图