【HarmonyOS Next之旅】DevEco Studio使用指南(二十一)

1 -> 查看多端设备预览效果

DevEco Studio支持HarmonyOS分布式应用/元服务开发，同一个应用/元服务可以运行在多个设备上。在HarmonyOS分布式应用/元服务的开发阶段，因不同设备的屏幕分辨率、形状、大小等不同，开发者需要在不同的设备上查看应用/元服务的UI布局和交互效果，此时便可以使用多端设备预览器功能，方便开发者在应用/元服务开发过程中，随时查看不同设备上的界面显示效果。

说明

多端设备预览最多同时支持4个设备的预览。

前面介绍了DevEco Studio支持ArkTS、JS应用/元服务的预览器功能，多端设备预览器支持ArkTS、JS应用/元服务在不同设备上的同时预览。如果两个设备支持的编码语言不同，就不能使用多端设备预览功能。

下面以ArkTS应用/元服务为例，介绍多端设备预览器的使用方法，JS应用/元服务的多端设备预览器使用方法相同。

1. 在工程目录中，打开任意一个ets文件(JS请打开hml/css/js文件)。

2. 可以通过如下任意一种方式打开预览器开关，显示效果如下图所示：

• 通过菜单栏，单击View > Tool Windows > Previewer，打开预览器。
• 在编辑窗口右上角的侧边工具栏，单击Previewer，打开预览器。

3. 在Previewer窗口中，打开Profile Manager中的Multi-profile preview开关，同时查看多设备上的应用/元服务运行效果。

说明

多端设备预览不支持动画的预览，如果需要查看动画在设备上的预览效果，请关闭Multi-device preview功能后在单设备预览界面进行查看。

多设备预览效果如下图所示：

2 -> Inspector双向预览

DevEco Studio提供HarmonyOS应用/元服务的UI预览界面与源代码文件间的双向预览功能，支持ets文件与预览器界面的双向预览。使用双向预览功能时，需要在预览器界面单击图标打开双向预览功能。

说明

不支持服务卡片的双向预览功能。

开启双向预览功能后，支持代码编辑器、UI界面和Component Tree组件树三者之间的联动：

• 选中预览器UI界面中的组件，则组件树上对应的组件将被选中，同时代码编辑器中的布局文件中对应的代码块高亮显示。
• 选中布局文件中的代码块，则在UI界面会高亮显示，组件树上的组件节点也会呈现被选中的状态。
• 选中组件树中的组件，则对应的代码块和UI界面也会高亮显示。

在预览界面还可以通过组件的属性面板修改可修改的属性或样式，在预览界面修改后，预览器会自动同步到代码编辑器中修改源码，并实时的刷新UI界面；同样的，如果在代码编辑器中修改源码，也会实时刷新UI界面，并更新组件树信息及组件属性。

说明

• 如果组件有做数据绑定，则其属性不支持在属性面板修改。
• 如果界面有使用动画效果或者带动画效果组件，则其属性不支持在属性面板修改。
• 多设备预览时，不支持双向预览。

3 -> 预览数据模拟

说明

仅API 11及以上版本的Stage工程支持。

在预览场景中，由于代码的运行环境与真机设备上的运行环境不同，调用部分接口时无法获取到有效的返回值(例如获取电池电量信息等，在预览场景下batteryInfo.voltage返回的是一个固定的值0)，这样就无法在预览时查看到不同返回值带来的界面变化。因此，Hamock提供了预览场景的模拟功能，在不改变业务运行逻辑的同时，开发者可以模拟UI组件上的属性或方法，或模拟import的模块接口。

3.1 -> 使用前提

使用Hamock在预览场景模拟，需要在工程或模块的oh-package.json5中添加该依赖，然后重新同步工程。

"devDependencies": {
    "@ohos/hamock": "1.0.0"
}

3.2 -> UI组件上的Mock

Hamock提供了@MockSetup用于修饰Mock方法，仅支持声明式范式的组件。当开发者预览该组件时，预览运行时将在组件初始化时执行被@MockSetup修饰的方法。因此，开发者可以在这个被修饰的方法内重定义组件的方法或重赋值组件的属性，其将在预览时生效。

说明

@MockSetup修饰的方法仅在预览场景会自动触发，并先于组件的aboutToAppear执行。

3.2.1 -> UI组件的方法

1. 在ArkTS页面代码中引入Hamock。

import { MockKit, when, MockSetup } from '@ohos/hamock';

2. 在目标组件中定义一个方法，并用@MockSetup修饰该方法。在这个方法中，使用MockKit模拟目标方法。

import { MockKit, when, MockSetup } from '@ohos/hamock';

@Entry
@Component
struct Index {
 ...
 @MockSetup
 randomName() {
  let mocker: MockKit = new MockKit();
  let mockfunc: Object = mocker.mockFunc(this, this.method1);
  // mock 指定的方法在指定入参的返回值
  when(mockfunc)('test').afterReturn(1);
 }
 ...
 // 业务场景调用方法
 const result = this.method1('test'); // in previewer, result = 1
}

3.2.2 -> UI组件的属性

1. 在ArkTS页面代码中引入Hamock。

import { MockSetup } from '@ohos/hamock';

2. 在目标组件中定义一个方法，并用@MockSetup修饰该方法。在这个方法中，对于需要Mock的属性，可以重新赋值。

import { MockSetup } from '@ohos/hamock';

@Component
struct Person {
 @Prop species: string;
 // 在@MockSetup片段中，定义对象属性
 @MockSetup
 randomName() {
  this.species = 'primates'
 }
 ...
 // 业务场景调用属性（如果从初始化到调用期间，该属性无变化）
 const result = this.species // in previewer, result = primates
}

说明

• ArkUI部分类型属性不支持Mock，如readonly、@ObjectLink。
• 被@Link/@Consume/@Prop/@BuilderParam装饰器修饰的变量，ArkUI语法要求父容器需要有对应属性的定义，因此更推荐开发者通过定义⼀个预览场景父容器（并通过父容器传递合适的数据）来预览这⼀类的组件。

3.3 -> 模块的Mock

3.3.1 -> 系统模块/依赖的模块

1. 在src/mock目录下新建一个ArkTS文件，在这个文件内定义目标Module的Mock实现。

import router from '@ohos.router';

// 定义或导入 routerParam 的返回值类型
interface PageRouterParam {
 name: string
}

// 定义 mock 实现
const MockRouter: Record<string, Object> = {
 'getParams': () => {
  return { name: 'Mocked' } as PageRouterParam;
 },
 // 复用原始实现
 'pushUrl': router.pushUrl,
 'replaceUrl': router.replaceUrl,
 ...
};

export default MockRouter;

说明

• 如果用户在定义Mock的实现时，未复用原始实现，则在预览运⾏时，当业务代码调用到未被Mock的接口方法时，实际将调用到undefined的对象。
• 目标模块与Mock实现代码是⼀对⼀的关系。对同⼀个模块，只支持有⼀份Mock实现代码。预览运行时所有页面import该模块都将指向为Mock实现代码。

2. 在Mock配置文件(src/mock/mock-config.json5)中定义目标Module与Mock实现的替换关系。该替换关系仅会在预览场景下生效。

{
 "@ohos.router": { // 待替换的moduleName
  "source": "src/mock/module/ohos/router.mock.ets" // mock代码的路径，相对于模块根目录
 },
 ...
}

3. 在原调用处中添加Hilog日志，方便在预览时，在Log中打印获取返回值，从而验证Mock是否生效。

hilog.debug(DomainNumber, logTag, 'Mock %{public}s', router.getParams()['name']);

3.3.2 -> 本地模块

1. 在src/mock目录下新建一个ArkTS文件，在这个文件内定义目标Module的Mock实现。

// import local module
import LibDefaultExport from '../../../main/ets/utils/CommonUtils'; // get origin default export
import { methodA, ObjectB } from '../../../main/ets/utils/CommonUtils'; // get origin export on demand

class DefaultExportMock extends LibDefaultExport {
  // 定义mock实现
  public static getName(): String {
    return "Mocked Name";
  }
};

export {
  methodA,
  ObjectB,
}

export default DefaultExportMock;

其中CommonUtils.ets文件示例如下：

export default class CommonUtils {
  public static getName(): String {
    return "origin name";
  }

  public static getTitle(): String {
    return "origin title";
  }
}

export const methodA = (): string => {
  return "methodA"
}

export const ObjectB: Object = new Object();

说明

本地Module的Mock仅支持src/main/ets目录下的ArkTS或TS文件。

2. 在Mock配置文件(src/mock/mock-config.json5)中定义目标Module与Mock实现的替换关系。该替换关系仅会在预览场景下生效。

{
 "utils/CommonUtils.ets": { // 本地module只支持ets/xxx的相对路径，并需明确文件后缀
  "source": "src/mock/module/utils/CommonUtils.mock.ts"
 },
 ...
}

3. 在原调用处中添加Hilog日志，方便在预览时，在Log中打印获取返回值，从而验证Mock是否生效。

hilog.debug(DomainNumber, logTag, 'Mock %{public}s', CommonUtils.getName());

4 -> 支持使用预览器的API清单

4.1 -> 组件

4.1.1 -> ArkTS组件

4.1.2 -> JS组件

4.2 -> 接口

4.2.1 -> UI界面

4.2.2 -> 网络管理

4.2.3 -> 数据管理

4.2.4 -> 文件管理