HarmonyOS：一多能力介绍：一次开发，多端部署

概述

如果一个应用需要在多个设备上提供同样的内容，则需要适配不同的屏幕尺寸和硬件，开发成本较高。HarmonyOS 系统面向多终端提供了“一次开发，多端部署”（后文中简称为“一多”）的能力，可以基于一种设计，高效构建多端可运行的应用

定义和目标

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

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

关键问题

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

问题1：页面如何适配

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

问题2：功能如何兼容

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

问题3：工程如何组织

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

关键问题的解决思路

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

界面级一多

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

布局能力

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

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

布局可以分为自适应布局和响应式布局

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

名称

简介

自适应布局

当外部容器大小发生变化时，元素可以根据相对关系自动变化以适应外部容器变化的布局能力。相对关系如占比、固定宽高比、显示优先级等。当前自适应布局能力有7种：拉伸能力、均分能力、占比能力、缩放能力、延伸能力、隐藏能力、折行能力。自适应布局能力可以实现界面显示随外部容器大小连续变化。

响应式布局

当外部容器大小发生变化时，元素可以根据断点、栅格或特定的特征（如屏幕方向、窗口宽高等）自动变化以适应外部容器变化的布局能力。当前响应式布局能力有3种：断点、媒体查询、栅格布局。响应式布局可以实现界面随外部容器大小有不连续变化，通常不同特征下的界面显示会有较大的差异。

说明

自适应布局多用于解决页面各区域内的布局差异，响应式布局多用于解决页面各区域间的布局差异。

自适应布局和响应式布局常常需要借助容器类组件实现，或与容器类组件搭配使用。

自适应布局常常需要借助Row组件、Column组件或Flex组件实现。

容器组件	组件说明	拉伸能力	均分能力	占比能力
Row	沿水平方向布局子组件的容器	增加Blank子组件	将组件justifyContent属性设置为FlexAlign.SpaceEvenly	通过百分比设置子组件宽高，或配置子组件layoutWeight属性
Column	沿垂直方向布局子组件的容器	增加Blank子组件	将组件justifyContent属性设置为FlexAlign.SpaceEvenly	通过百分比设置子组件宽高，或配置子组件layoutWeight属性
Flex	使用弹性方式布局子组件的容器	增加Blank子组件，或配置子组件flexGrow和flexShrink属性	将组件justifyContent属性设置为FlexAlign.SpaceEvenly	通过百分比设置子组件宽高，或配置子组件layoutWeight属性

容器组件	组件说明	缩放能力	延伸能力	隐藏能力	折行能力
Row	沿水平方向布局子组件的容器	配置组件aspectRatio属性	增加Scroll父组件	配置子组件displayPriority属性	—
Column	沿垂直方向布局子组件的容器	配置组件aspectRatio属性	增加Scroll父组件	配置子组件displayPriority属性	—
Flex	使用弹性方式布局子组件的容器	配置组件aspectRatio属性	—	配置子组件displayPriority属性	将组件wrap属性，设置为FlexWrap.Wrap

容器组件

组件说明

缩放能力

延伸能力

隐藏能力

折行能力

Row

沿水平方向布局子组件的容器

配置组件aspectRatio属性

增加Scroll父组件

配置子组件displayPriority属性

—

Column

沿垂直方向布局子组件的容器

配置组件aspectRatio属性

增加Scroll父组件

配置子组件displayPriority属性

—

Flex

使用弹性方式布局子组件的容器

配置组件aspectRatio属性

—

配置子组件displayPriority属性

将组件wrap属性，

设置为FlexWrap.Wrap

响应式布局常常与GridRow组件、Grid组件、List组件、Swiper组件或Tabs组件搭配使用。

容器组件	组件说明	响应式布局
GridRow	使用断点和栅格方式布局子组件的容器。需配合GridCol子组件使用。	栅格组件自身具有响应式布局能力。
Grid	使用“行”和“列”分割的单元格方式布局子组件的网格容器。需配合GridItem子组件使用。	需配合断点使用，通过改变不同断点下的rowsTemplate和columnsTemplate等属性，实现不同的布局效果。
List	包含一系列相同宽度列表项的容器。需配合ListItem子组件使用。	需配合断点使用，通过改变不同断点下的lanes等属性，实现不同的布局效果。
Swiper	轮播展示子组件的容器。	需配合断点使用，通过改变不同断点下的displayCount和indicator等属性，实现不同的布局效果。
Tabs	使用页签控制内容切换的容器，每个页签对应一个内容视图。需配合TabContent子组件使用。	需配合断点使用，通过改变不同断点下的vertical和barPosition等属性，实现不同的布局效果。

交互归一

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

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

资源使用

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

应用资源：借助资源文件能力，开发者在应用中自定义资源，自行管理这些资源在不同的设备或配置中的表现。
系统资源：开发者直接使用系统预置的资源定义（即分层参数）。

资源目录示例：

resources
|---base
|   |---element
|   |   |---string.json
|   |---media
|   |   |---icon.png
|   |---profile
|   |   |---test_profile.json
|---en_US  // 默认存在的目录，设备语言环境是美式英文时，优先匹配此目录下资源
|   |---element
|   |   |---string.json
|   |---media
|   |   |---icon.png
|   |---profile
|   |   |---test_profile.json
|---zh_CN  // 默认存在的目录，设备语言环境是简体中文时，优先匹配此目录下资源
|   |---element
|   |   |---string.json
|   |---media
|   |   |---icon.png
|   |---profile
|   |   |---test_profile.json
|---en_GB-vertical-car-mdpi // 自定义限定词目录示例，由开发者创建
|   |---element
|   |   |---string.json
|   |---media
|   |   |---icon.png
|   |---profile
|   |   |---test_profile.json
|---rawfile // 其他类型文件，原始文件形式保存，不会被集成到resources.index文件中。文件名可自定义。
|---resfile // 其他类型文件，原始文件形式保存，不会被集成到resources.index文件中。文件名可自定义。

功能级一多

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

系统能力

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

可以在SysCap列表中查询HarmonyOS的能力集

支持能力集，联想能力集与要求能力集

支持能力集：设备具备的系统能力集合，在设备配置文件中配置。
要求能力集：应用需要的系统能力集合，在应用配置文件中配置。
联想能力集：开发应用时DevEco Studio可联想的API所在的系统能力集合，在应用配置文件中配置。

支持能力集，联想能力集与要求能力集都是系统能力的集合。

支持能力集描述的是设备能力，要求能力集描述的是应用能力。若应用A的要求能力集是设备N的支持能力集的子集，则应用A可分发到设备N上安装运行，否则不能分发。

联想能力集是该应用开发时，DevEco Studio可联想的API所在的系统能力集合。

设备与支持能力集

每个设备根据其硬件能力，对应不同的支持能力集。

SDK将设备分为两组，典型设备和自定义设备，典型设备的支持能力集由HarmonyOS来定义，自定义设备由设备厂商给出。

设备与SDK能力的对应

SDK向DevEco Studio提供全量API，DevEco Studio识别开发者项目中选择的设备形态，找到该设备的支持能力集，筛选支持能力集包含的API并提供API联想。

加入自定义syscap

在某具体的设备型号上，能力可能超出工程默认设备定义的能力集范围，如果需要使用此部分能力，需要额外配置自定义的syscap。

按如下格式填入所需要使用的SysCaps。以使用NFC能力为例，syscap.json文件示例如下。

{
  "devices": {
    "general": [
      // 每一个典型设备对应一个syscap支持能力集，可配置多个典型设备，应与工程所选择的设备一致
      "phone"
    ]
  },
  "development": {
    // addedSysCaps内的sycap集合与devices中配置的各设备支持的syscap集合的并集共同构成联想能力集。
    "addedSysCaps": [
      "SystemCapability.Communication.NFC.Core",
      "SystemCapability.Communication.NFC.CardEmulation",
      "SystemCapability.Communication.NFC.Tag"
    ]
  }
}

单设备应用开发

默认应用的联想能力集，要求系统能力集和设备的支持系统能力集相等，开发者修改要求能力集需要慎重。

跨设备应用开发

默认应用的联想能力集是多个设备支持能力集的并集，要求能力集则是交集。

判断 API 是否可以使用

当前提供了ArkTS API和Native API用于帮助判断某个API是否可以使用。

ArkTS API

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

if (canIUse("SystemCapability.ArkUI.ArkUI.Full")) {
   console.log("该设备支持SystemCapability.ArkUI.ArkUI.Full");
} else {
   console.log("该设备不支持SystemCapability.ArkUI.ArkUI.Full");
}

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

import geolocationManager from '@ohos.geoLocationManager';

if (geolocationManager) {
geolocationManager.getCurrentLocation((location) => {
    console.log('current location: ' + JSON.stringify(location));
});
} else {
console.log('该设备不支持位置信息');
}

Native API

#include <stdio.h>
#include <stdlib.h>
#include "syscap_ndk.h"

char syscap[] = "SystemCapability.ArkUI.ArkUI.Full";
bool result = canIUse(syscap);
if (result) {
    printf("SysCap: %s is supported!\n", syscap);
} else {
    printf("SysCap: %s is not supported!\n", syscap);
}

除此之外，开发者可以通过API参考文档查询API接口所属的SysCap。

不同设备相同能力的差异检查

即使是相同的系统能力，在不同的设备下，也会有能力的差异。比如同是摄像头的能力，平板设备优于智能穿戴设备。

import userAuth from '@ohos.userIAM.userAuth';

const authenticator = userAuth.getAuthenticator();
const result = authenticator.checkAbility('FACE_ONLY', 'S1');

if (result == authenticator.CheckAvailabilityResult.AUTH_NOT_SUPPORT) {
    console.log('该设备不支持人脸识别');
}
//强行调用不支持的 API 会返回错误信息，但不会出现语法错误。
authenticator.execute('FACE_ONLY', 'S1', (err, result) => {
    if (err) {
        console.log(err.message);
        return;
    }
})

设备间的SysCap差异如何产生的

设备的SysCap因产品解决方案厂商拼装的部件组合不同而不同，整体流程如下图：

一套操作系统源码由可选和必选部件集组成，不同的部件为对外体现的系统能力不同，即部件与 SysCap 之间映射关系。
发布归一化的SDK，API与SysCap之间存在映射关系。
产品解决方案厂商按硬件能力和产品诉求，可按需拼装部件。
产品配置的部件可以是系统部件，也可以是三方开发的私有部件，由于部件与SysCap间存在映射，所有拼装后即可得到该产品的SysCap集合。
SysCap集编码生成 PCID (Product Compatibility ID，产品兼容性标识)，应用开发者可将PCID导入IDE解码成SysCap，开发时对设备的SysCap差异做兼容性处理。
部署到设备上的系统参数中包含了SysCap集，系统提供了native的接口和应用接口，可供系统内的部件和应用查询某个SysCap是否存在。
应用开发过程中，应用必要的SysCap将被编码成RPCID（Required Product Compatibility ID），并写入应用安装包中。应用安装时，包管理器将解码RPCID得到应用需要的 SysCap，与设备当前具备的SysCap比较，若应用要求的SysCap都被满足，则安装成功。
应用运行时，可通过canIUse接口查询设备的SysCap，保证在不同设备上的兼容性。

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

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

// syscap.json
{
    "devices": {
        "general": [            // 每一个典型设备对应一个syscap支持能力集，可配置多个典型设备
            "default",
            "tablet"
        ],
        "custom": [             // 厂家自定义设备
            {
                "某自定义设备": [
                    "SystemCapability.Communication.SoftBus.Core"
                ]
            }
        ]
    },
    "development": {             // addedSysCaps内的sycap集合与devices中配置的各设备支持的syscap集合的并集共同构成联想能力集
        "addedSysCaps": [
            "SystemCapability.Communication.NFC.Core"
        ]
    },
    "production": {              // 用于生成rpcid，慎重添加，可能导致应用无法分发到目标设备上
        "addedSysCaps": [],      // devices中配置的各设备支持的syscap集合的交集，添加addedSysCaps集合再除去removedSysCaps集合，共同构成要求能力集
        "removedSysCaps": []     // 当该要求能力集为某设备的子集时，应用才可被分发到该设备上
    }
}

说明

对于要求能力集，开发者修改时要十分慎重，修改不当会导致应用无法分发和安装到目标设备上。
对于联想能力集，通过增加系统能力可以扩大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，也可以不包含。

说明

关于Entry类型的HAP包、Feature类型的HAP包、HAR包、HSP包以及APP Pack的详细介绍请参考应用程序包结构说明

部署模型

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

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

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

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

默认设备、平板
车机、智慧屏
智能穿戴
……

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

说明

部署模型不同，相应的代码工程结构也有差异。部署模型A和部署模型B的主要差异点集中在products层：部署模型A在products目录下同一子目录中做功能和特性集成；部署模型B在products目录下不同子目录中对不同的产品做差异化的功能和特性集成。
开发阶段应考虑不同类型设备间最大程度的复用代码，以减少开发及后续维护的工作量。
整个代码工程最终构建出一个APP包，应用以APP包的形式发布到应用市场中。

工程结构

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

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

common层可编译成一个或多个HAR包或HSP包（HAR中的代码和资源跟随使用方编译，如果有多个使用方，它们的编译产物中会存在多份相同拷贝；而HSP中的代码和资源可以独立编译，运行时在一个进程中代码也只会存在一份），其只可以被products和features依赖，不可以反向依赖。
features（基础特性层）：用于存放基础特性集合（如应用中相对独立的各个功能的UI及业务逻辑实现等）。

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

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

可以看到DevEco Studio创建出的默认工程，仅包含一个的entry类型的模块。

更推荐使用本文部署模型小节中介绍的common、features、product三层工程结构。工程结构示例如下所示：

/application
 ├── common                  # 公共特性目录
 │
 ├── features                # 功能模块目录
 │   ├── feature1            # 子功能
 │   ├── feature2            # 子功能2
 │   └── ...                 # 子功能n
 │
 └── product                 # 产品层目录
     ├── wearable            # 智能穿戴泛类目录
     ├── default             # 默认设备泛类目录
     └── ...