预览器的使用-预览数据模拟

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

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

使用前提

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

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

UI组件上的Mock

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

说明

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

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
}

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语法要求父容器需要有对应属性的定义，因此更推荐开发者通过定义⼀个预览场景父容器（并通过父容器传递合适的数据）来预览这⼀类的组件。

模块的Mock

系统模块/依赖的模块

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']);

本地模块

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