基于HarmonyOS鸿蒙Next H5框架的多设备开发指导

基于HarmonyOS鸿蒙Next H5框架的多设备开发指导

1. 概述 应用使用H5开发的历史页面多且冗杂，同时H5相较于ArkUI一多缺乏拿来即用的适配方案。为达到OpenHarmony一多体验，所有页面进行一多适配复杂且工作量大。针对此问题，本文将主要提供一套H5多设备断点和响应式组件方案，实现页签栏响应式、网格响应式、类挪移布局等效果，提升H5一多适配的开发效率。首先介绍多设备断点能力，然后分别介绍组件的使用说明，结合组件效果提供对应场景的开发案例，最终提供示例代码指导实际开发。

以下是使用组件库的一些前置要求：

组件库安装

根据您使用的包管理器和web框架，请选择对应的安装命令。

Npm

// Vue2
npm install web-multidevice-advanced-vue2 
// Vue3
npm install web-multidevice-advanced-vue3 
// React
npm install web-multidevice-advanced-react

Yarn

// Vue2
yarn add web-multidevice-advanced-vue2 
// Vue3
yarn add web-multidevice-advanced-vue3 
// React
yarn add web-multidevice-advanced-react

多设备断点

断点设计原理

H5断点是基于鸿蒙多设备封装的一套断点机制，通过设置断点，让开发者可以结合窗口宽度去实现不同的页面布局效果。 断点以应用窗口宽度为基准，将应用窗口在宽度维度上分成了几个不同的区间即不同的断点，默认提供的断点区间如下所示。

多设备适配指导

在具体开发过程中，使用breakpointManager需先从web-multidevice-advanced-ui/hookInput引用BreakpointManager这个类，然后创建BreakpointManager实例。建议创建BreakpointManager实例放在公共文件里，然后导出。这样的话，设备断点值变更时就只需要调整一个地方。使用breakpointManager时，需调用subscribeToBreakpoint方法订阅断点变化，然后在回调函数里使用useBreakpointValue方法来获取不同断点下属性的不同值。最后在页面销毁前需要取消断点订阅并销毁实例。

具体示例如下所示：

创建断点管理公共实例并导出

// utils/breakpointInit.ts
import { BreakpointManager } from "web-multidevice-advanced-ui/src/hookInput"; 

// 实例化断点管理类，断点区间支持自定义 
export const breakpointManager = new BreakpointManager({
  xs: 0,
  sm: 320,
  md: 600,
  lg: 840,
  xl: 1440,
});

订阅断点变化并获取不同断点下的属性值

// xxx.vue
import { breakpointManager } from "./utils/breakpointInit";

const contentCols = ref("12");
// 订阅断点变化 
const unsubscribe = breakpointManager.subscribeToBreakpoint((bp，vbp) => {
  // bp：实时的横向断点回调，为null时不使用横向断点
  // vbp：实时纵向断点回调，为null时不使用纵向断点
  // 根据当前断点区间，返回对应的属性值 
  contentCols.value = breakpointManager.useBreakpointValue({
    xs: "12",
    sm: "12",
    md: "6",
    lg: "6",
    xl: "6",
  });
  // 获取当前的横向断点值 
  breakpointManager.getCurrentBreakpoint();
  // 获取当前的纵向断点值
  breakpointManager.getCurrentVerticalBreakpoint();
  // 获取当前的内置断点类型和区间 
  breakpointManager.getBreakpoints(); 
});

页面销毁前取消断点订阅并销毁实例

// xxx.vue
onUnmounted(() => {
  // 取消订阅 
  unsubscribe();
  // 销毁实例，移除监听器，清空回调函数集合 
  breakpointManager.destroy();
});

页签栏响应式组件实现多设备适配

组件使用说明

H5页签栏响应式组件MultiTabBar，包含父组件TabBar和子组件TabBarItem两部分，主要用于实现内容视图切换的布局效果。组件结合多设备断点能力，能够适配不同类型的布局场景。

组件导入方式

1. Vue2

// xxx.vue
import { TabBarVue, TabBarItemVue } from "web-multidevice-advanced-vue2/src";

1. Vue3

// xxx.vue
import { TabBarVue, TabBarItemVue } from "web-multidevice-advanced-vue3/src";

1. React

// xxx.tsx
import { TabBarReact, TabBarItemReact } from "web-multidevice-advanced-react/dist/index";

默认布局效果

MultiTabBar组件基于默认断点区间，内置了一套多设备布局效果。

TabBar父组件 API

1. Attribute | 属性 | 说明 | 类型 | 可选值 | 默认值 | |-------------|------------------------------|--------------|---------------------------|---------------------| | vertical | 设置组件是否为纵向 | Boolean | true：纵向Tab
   false：横向Tab | xs：false
   sm：false
   md：false
   lg：true
   xl：true | | barPosition | 设置组件的位置 | String | start：顶部
   end：底部 | xs：bottom
   sm：bottom
   md：bottom
   lg：left
   xl：left | | width | 设置组件的宽度 | String / Number | — | xs：100%
   sm：100%
   md：100%
   lg：58px
   xl：58px | | height | 设置组件的高度 | String / Number | — | xs：78px
   sm：78px
   md：78px
   lg：100%
   xl：100% | | unselectedColor | 设置子组件文本未选中时的颜色 | String | — | #aaacab | | selectedColor | 设置子组件文本选中时的颜色 | String | — | #0b59f7 | | layoutMode | 设置子组件内部元素的排布方式 | String | vertical：垂直
   horizontal：水平 | xs：vertical
   sm：vertical
   md：horizontal
   lg：vertical
   xl：vertical | | verticalAlign | 设置子组件内部元素在垂直方向上的对齐方式 | String | top：顶部对齐
   center：居中对齐
   bottom：底部对齐 | center | | horizontalAlign | 设置子组件内部元素在水平方向上的对齐方式 | String | start：起始端对齐
   center：居中对齐
   end：末端对齐 | center | | bgColor | 设置子组件容器未选中时的背景颜色 | String | — | #ffffff | | selectedBgColor | 设置子组件容器选中时的背景颜色 | String | — | #f1f5ff |

2. Event | 事件名 | 说明 | 参数 | |---------------|----------------------------------------|--------------------------------------------| | onTabItemClick | 点击页签栏子组件容器时触发的自定义事件 | Function({index, name})
   index：选中子组件的索引值
   name：选中子组件的name标识名称 |

推荐使用方式（以Vue3为例）

MultiTabBar组件在使用时建议封装为一个独立的组件，置于嵌套路由RouterView外层，以确保页面切换时组件不会刷新。同时，需要借助断点能力实现路由视图的页签栏避让。

关键代码（以vue3为例）

// web_advanced_ui_sample\vue3_sample\src\App.vue
<template>
  <div>
    <TabBar />
    <div class="template-main">
      <router-view />
    </div>
  </div>
</template>

<script setup>
import { ref, onUnmounted } from "vue";
import { TabBar } from "./components/TabBar/index.vue";
import { breakpointManager } from "./utils/breakpointInit";

const marginLeft = ref("0");
const marginBottom = ref("0");
// 订阅断点变化 
const unsubscribe = breakpointManager.subscribeToBreakpoint(() => {
  // 传入不同断点下的属性值，根据当前断点返回对应的值 
  marginLeft.value = breakpointManager.useBreakpointValue({
    xs: 0,
    sm: 0,
    md: 0,
    lg: "96px",
    xl: "96px",
  });
  marginBottom.value = breakpointManager.useBreakpointValue({
    xs: "78px",
    sm: "78px",
    md: "78px",
    lg: 0,
    xl: 0,
  });
  // 设置CSS变量 
  document.documentElement.style.setProperty("--marginLeft", marginLeft.value);
  document.documentElement.style.setProperty("--marginBottom", marginBottom.value);
});
onUnmounted(() => {
  // 取消订阅断点变化 
  unsubscribe();
  // 销毁实例，移除监听器，清空回调函数集合 
  breakpointManager.destroy();
});
</script>

<style lang="less" scoped>
.template-main {
  // 设置margin样式，实现页签栏避让 
  margin-left: var(--marginLeft);
  margin-bottom: var(--marginBottom);
  overflow: scroll;
}
</style>

网格布局响应式组件实现多设备适配

组件使用说明

H5网格布局响应式组件MultiGrid，包含父组件MultiGrid和子组件MultiGridItem两部分，主要用于提供精确的行和列控制，实现复杂的二维布局效果。组件结合多设备断点能力，能够适配不同类型的布局场景。

组件导入方式

1. Vue2

// xxx.vue
import { MultiGridVue, GridItemVue } from "web-multidevice-advanced-vue2/src";

1. Vue3

// xxx.vue
import { MultiGridVue, GridItemVue } from "web-multidevice-advanced-vue3/src";

1. React

// xxx.tsx
import { MultiGridReact, GridItemReact } from "web-multidevice-advanced-react/dist/index";

默认布局效果

MultiGrid组件基于默认断点区间，内置了一套多设备布局效果。

MultiGrid父组件 API

1. Attribute | 属性 | 说明 | 类型 | 可选值 | 默认值 | |---------------|----------------------------|--------------|--------------------------------------------|---------| | columnsTemplate | 设置组件每一列的列宽 | String / Number | — | xs：1fr 1fr 1fr 1fr
   sm：1fr 1fr 1fr 1fr
   md：1fr 1fr 1fr 1fr 1fr 1fr
   lg：1fr 1fr 1fr 1fr 1fr 1fr 1fr 1fr
   xl：1fr 1fr 1fr 1fr 1fr 1fr 1fr 1fr | | rowsTemplate | 设置组件每一行的行高 | String / Number | 同columnsTemplate | auto | | gridRowGap | 设置网格行与行的间隔 | String / Number | — | 0 | | gridColumnGap | 设置网格列与列的间隔 | String / Number | — | 0 | | justifyItems | 设置网格项内容的水平位置 | String | stretch：拉伸以填充网格项
   start：网格项起点位置对齐
   end：网格项终点位置对齐
   center：网格项中间位置对齐 | stretch | | alignItems | 设置网格项内容的垂直位置 | String | stretch：拉伸以填充网格项
   start：网格项起点位置对齐
   end：网格项终点位置对齐
   center：网格项中间位置对齐 | stretch | | justifyContent | 设置整个内容区域在容器里的水平位置 | String | stretch：未指定大小时拉伸填充容器
   start：对齐容器的起始边框
   end：对齐容器的结束边框
   center：容器内容居中
   space-around：子项两侧间隔相等
   space-between：子项间间隔相等，与容器边框无间隔
   space-evenly：子项间间隔相等 | stretch | | alignContent | 设置整个内容区域在容器里的垂直位置 | String | 同justifyContent，方向为垂直方向 | stretch |

2. Event | 事件名 | 说明 | 参数 | |---------------|----------------------------------|-----------------------------------------| | onGridItemClick | 点击网格子组件容器时触发的自定义事件 | Function({index, name})
   index：选中子组件的索引值
   name：选中子组件的name标识名称 |

MultiGridItem子组件 API

推荐使用方式（以Vue3为例）

// MultiGrid/index.vue
<template>
  <MultiGridVue :onGridItemClick="gridItemClick"
                :columnsTemplate="columnsTemplate">
    <GridItemVue v-for="item in gridItems"
                 :name="item.name"
                 :key="item.id">
      <img :src="item.imgSrc" />
      <span>{{ item.name }}</span>
    </GridItemVue>
  </MultiGridVue>
</template>

<script setup>
import { ref, onUnmounted } from "vue";
import { MultiGridVue, GridItemVue } from "web-multidevice-advanced-vue3/src";
import { breakpointManager } from "../../utils/breakpointInit";

const columnsTemplate = ref("1fr 1fr 1fr 1fr 1fr");
const gridItems = ref([
  { id: 1, name: "智慧办公", imgSrc: require("../../assets/categories_1.png") },
  { id: 2, name: "智慧家居", imgSrc: require("../../assets/categories_2.png") },
  { id: 3, name: "智能手机", imgSrc: require("../../assets/categories_3.png") },
]);

// 订阅断点变化 
const unsubscribe = breakpointManager.subscribeToBreakpoint(() => {
  // 传入不同断点下的columnsTemplate属性值，根据当前断点返回对应的值 
  columnsTemplate.value = breakpointManager.useBreakpointValue({
    xs: "1fr 1fr 1fr 1fr 1fr",
    sm: "1fr 1fr 1fr 1fr 1fr",
    md: "1fr 1fr 1fr 1fr 1fr 1fr 1fr",
    lg: "1fr 1fr 1fr 1fr 1fr 1fr 1fr 1fr 1fr 1fr",
    xl: "1fr 1fr 1fr 1fr 1fr 1fr 1fr 1fr 1fr 1fr",
  });
});

// 定义自定义事件 
const gridItemClick = ({ index, name }) => {
  // 添加点击事件逻辑 
};

onUnmounted(() => {
  // 取消订阅断点变化 
  unsubscribe();
  // 销毁实例，移除监听器，清空回调函数集合 
  breakpointManager.destroy();
});
</script>

类挪移布局响应式组件实现多设备适配

组件使用说明

H5类挪移布局响应式组件MultiDiversion，包含父组件MultiDiversion和子组件MultiDiversionItem两部分，主要用于根据布局的宽度选择是上下布局还是左右布局效果。组件结合多设备断点能力，能够适配不同类型的布局场景。

组件导入方式

1. Vue2

// xxx.vue
import { MultiDiversionVue, DiversionItemVue } from "web-multidevice-advanced-vue2/src";

1. Vue3

// xxx.vue
import { MultiDiversionVue, DiversionItemVue } from "web-multidevice-advanced-vue3/src";

1. React

// xxx.tsx
import { MultiDiversionReact, DiversionItemReact } from "web-multidevice-advanced-react/dist/index";

默认布局效果

MultiDiversion组件基于默认断点区间，内置了一套多设备布局效果。

MultiDiversion父组件 API

1. Attribute | 属性 | 说明 | 类型 | 可选值 | 默认值 | |---------------|--------------------------------|------------|---------------------------------|---------| | direction | 设置组件的排列方向 | String | horizontal：横向排列
   vertical：纵向排列 | xs：vertical
   sm：vertical
   md：horizontal
   lg：horizontal
   xl：horizontal | | splitLine | 设置是否显示子组件分割线 | Boolean | true
   false | false | | splitLineMode | 设置子组件分割线的类型 | String | solid：实线
   dashed：虚线
   dotted：点线 | dotted |

MultiDiversionItem子组件 API

推荐使用方式（以Vue3为例）

// MultiDiversion/index.vue
<template>
  <MultiDiversionVue :direction="diversionDirection">
    <DiversionItemVue name="firstContent">
      // 内容区1
    </DiversionItemVue>
    <DiversionItemVue name="secondContent">
      // 内容区2
    </DiversionItemVue>
  </MultiDiversionVue>
</template>

<script setup>
import { ref, onUnmounted } from "vue";
import { MultiDiversionVue, DiversionItemVue } from "web-multidevice-advanced-vue3/src";
import { breakpointManager } from "../../utils/breakpointInit";

const diversionDirection = ref("vertical");
// 订阅断点变化 
const unsubscribe = breakpointManager.subscribeToBreakpoint(() => {
  // 传入不同断点下的diversion属性值，根据当前断点返回对应的值 
  diversionDirection.value = breakpointManager.useBreakpointValue({
    xs: "vertical",
    sm: "vertical",
    md: "horizontal",
    lg: "horizontal",
    xl: "horizontal",
  });
});
onUnmounted(() => {
  // 取消订阅断点变化 
  unsubscribe();
  // 销毁实例，移除监听器，清空回调函数集合 
  breakpointManager.destroy();
});
</script>

示例代码

基于H5框架的多设备开发 sample示例代码地址