【Journey of HarmonyOS Next】DevEco Studio User Guide (21)

1 -> View the preview effect of the multi-terminal device

DevEco Studio supports the development of distributed applications and meta-services on HarmonyOS, and the same application/meta-service can run on multiple devices. In the development stage of HarmonyOS distributed apps/meta-services, developers need to view the UI layout and interaction effects of the app/meta-service on different devices due to the different screen resolutions, shapes, and sizes of different devices.

illustrate

Multi-device preview supports up to 4 devices at the same time.

As described earlier, DevEco Studio supports the previewer function of ArkTS and JS applications/metaservices, and the multi-terminal device previewer supports simultaneous preview of ArkTS and JS applications/metaservices on different devices. If the two devices support different coding languages, you can't use the multi-device preview feature.

The following uses the ArkTS application/meta service as an example to describe how to use the multi-terminal device previewer, which is the same as that of the JS application/meta service.

1. In the project directory, open any ets file (please open the hml/css/js file for JS).

2. You can turn on the previewer switch in any of the following ways, and the display effect is shown in the following figure:

From the menu bar, click View > Tool Windows > Preview to open the Previewer.
On the side toolbar in the upper-right corner of the editing window, click Preview to open the Previewer.

1. In the Preview window, turn on the Multi-profile preview switch in Profile Manager to view the performance of the application/meta service on multiple devices at the same time.

illustrate

If you want to view the preview effect of the animation on the device, please disable the multi-device preview function and view it on the single-device preview page.

The multi-device preview effect is shown in the following figure:

2 -> Inspector two-way preview

DevEco Studio provides two-way preview between the UI preview interface of HarmonyOS applications/meta services and source code files, and supports two-way preview between ets files and previewer pages. To use the two-way preview feature, you need to click the icon on the previewer page to open the two-way preview feature.

illustrate

The two-way preview feature of service cards is not supported.

After the two-way preview function is enabled, the linkage between the code editor, the UI interface, and the component tree is supported.

If you select a component in the Previewer UI, the corresponding component in the component tree will be selected, and the corresponding code block in the layout file in the code editor will be highlighted.
If you select a code block in the layout file, it will be highlighted on the UI interface, and the component node in the component tree will also be selected.
If you select a component in the component tree, the corresponding code block and UI interface will also be highlighted.

In the preview interface, you can also modify the modifiable properties or styles through the component's property panel, and after the preview interface is modified, the previewer will automatically synchronize to the code editor to modify the source code, and refresh the UI interface in real time. Similarly, if you modify the source code in the code editor, the UI will be refreshed in real time, and the component tree information and component properties will be updated.

illustrate

If a component is data-bound, its properties cannot be modified in the Properties panel.
If the interface uses animated effects or components with animated effects, its properties cannot be modified in the Properties panel.
When previewing multiple devices, two-way preview is not supported.

3 -> Preview the data simulation

illustrate

Only Stage projects with API 11 and later versions are supported.

In the preview scenario, because the running environment of the code is different from that on the real device, you cannot obtain a valid return value when calling some APIs (for example, to obtain battery level information, batteryInfo.voltage returns a fixed value of 0 in the preview scenario), so you cannot view the interface changes caused by different return values during the preview. Therefore, Hamock provides a simulation function for preview scenarios, and developers can simulate properties or methods on UI components, or simulate the module interface of import, without changing the business running logic.

3.1 -> Prerequisites for Use

To use Hamock to preview a scenario simulation, you need to add the dependency to oh-package.json5 of the project or module, and then resynchronize the project.

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

3.2 -> Mocks on UI components

Hamock provides @MockSetup components for decorating mock methods that only support declarative paradigms. When a developer previews the component, the preview runtime will execute the @MockSetup-modified method when the component is initialized. As a result, developers can redefine a component's methods or reassign a component's properties within this modified method, which will take effect during preview.

illustrate

@MockSetup method of retouching is automatically triggered only in the preview scene and is executed before the component's aboutToAppear.

3.2.1 -> Methods of UI components

1. Introduce Hamock into the ArkTS page code.

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

1. Define a method in the target component and decorate it with @MockSetup. In this method, the target method is simulated using 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 -> Properties of UI components

1. Introduce Hamock into the ArkTS page code.

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

1. Define a method in the target component and decorate it with @MockSetup. In this method, properties that require mocking can be re-assigned.

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
}

illustrate

Some ArkUI properties do not support mocks, such as readonly and @ObjectLink.
For variables that are decorated by @link/@Consume/@prop/@BuilderParam decorators, the ArkUI syntax requires that the parent container need to have the corresponding property definitions, so it is recommended that developers preview this type of components by defining a preview scene parent container (and passing the appropriate data through the parent container).

3.3 -> Mock of the module

3.3.1 -> System modules/dependent modules

1. Create a new ArkTS file in the src/mock directory and define the mock implementation of the target module in this file.

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;

illustrate

If the original implementation is not reused when defining the implementation of the mock, when the business code calls the interface method that is not mocked, the undefined object will be actually called when the business code is called to the interface method that has not been mocked.
The target module has a one-to-one relationship with the mock implementation code. For the same module, only one mock implementation code is supported. Preview the runtime, all pages of the import module will point to the implementation code for the mock.

1. Define the substitution relationship between the target module and the mock implementation in the mock configuration file (src/mock/mock-config.json5). The substitution relationship takes effect only in the preview scenario.

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

1. Add the Hilog log to the original call to print the return value in the log to verify whether the mock takes effect.

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

3.3.2 -> Local module

1. Create a new ArkTS file in the src/mock directory and define the mock implementation of the target module in this file.

// 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;

The following is an example of the CommonUtils.ets file:

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();

illustrate

The mock of the local module supports only the ArkTS or TS files in the src/main/ets directory.

1. Define the substitution relationship between the target module and the mock implementation in the mock configuration file (src/mock/mock-config.json5). The substitution relationship takes effect only in the preview scenario.

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

1. Add the Hilog log to the original call to print the return value in the log to verify whether the mock takes effect.

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