小程序调试新方案——WeConsole

作者：袁明宇

本文为原创，转载请注明作者及出处

在传统的 PC Web 前端开发中，浏览器为开发者提供了体验良好、功能丰富且强大的开发调试工具，比如常见的 Chrome devtools 等，这些调试工具极大的方便了开发者，它们普遍提供查看页面结构、监听网络请求、管理本地数据存储、debugger 代码、使用 Console 快速显示数据等功能。

但是在近几年兴起的微信小程序的前端开发中，却少有类似的体验和功能对标的开发调试工具出现。当然微信小程序的官方也提供了类似的工具，那就是 vConsole，但是相比 PC 端提供的工具来说确实无论是功能和体验都有所欠缺，所以我们开发了 weconsole 来提供更加全面的功能和更好的体验。

基于上述背景，我们想开发一款运行在微信小程序环境上，无论在用户体验还是功能等方面都能媲美 PC 端的前端开发调试工具，当然某些（如 debugger 代码等）受限于技术在当前时期无法实现的功能我们暂且忽略。

我们将这款工具命名为 WeimobConsole，简写为 WeConsole。

npm i weconsole -S

可将 npm 包下载到本地，然后将其中的 dist/full文件夹拷贝至项目目录中；

WeConsole 分为 核心和 组件两部分，使用时需要全部引用后方可使用， 核心负责重写系统变量或方法，以达到全局监控的目的；组件负责将监控的数据显示出来。

在 app.js文件中引用 核心：

// NPM方式引用
import"weconsole/init";

// 普通方式引用
import"xxx/weconsole/init";

引入 weconsole/init后，就是默认将 App、Page、Component、Api、Console 全部重写监控！如果想按需重写，可以使用如下方式进行：

import{ replace, restore, showWeConsole, hideWeConsole } from "weconsole"; // scope可选值：App/Page/Component/Console/Api
// 按需替换系统变量或函数以达到监控
replace(scope); // 可还原
restore(scope);

// 通过show/hide方法控制显示入口图标
showWeConsole();

如果没有显式调用过 showWeConsole/hideWeConsole方法，组件第一次初始化时，会根据小程序是否 开启调试模式来决定入口图标的显示性。

在需要的地方引用 组件，需要先将组件注册进 app/page/component.json中：

// NPM方式引用
"usingComponents": {
"weconsole": "weconsole/components/main/index"
}

// 普通方式引用
"usingComponents": {
"weconsole": "xxx/weconsole/components/main/index"
}

然后在 wxml中使用 <weconsole>标签进行初始化：

<!-- page/component.wxml -->
<weconsole/>

<weconsole>标签支持传入以下属性：

properties: {
// 组件全屏化后，距离窗口顶部距离
    fullTop: String,
// 刘海屏机型（如iphone12等）下组件全屏化后，距离窗口顶部距离
    adapFullTop: String,
}

如果不想将 weconsole 放置在主包中，建议将组件放在分包内使用，利用小程序的分包异步化(https://developers.weixin.qq.com/miniprogram/dev/framework/subpackages/async.html) 的特性，减少主包大小。

import{ setUIRunConfig } from "xxx/weconsole/index.js";

setUIRunConfig({
    customActions: [
{
            id: "test1",
            title: "显示文本",
            autoCase: "show",
            cases: [
{
                    id: "show",
                    button: "查看",
                    showMode: WcCustomActionShowMode.text,
                    handler(): string {
return"测试文本";
},
},
{
                    id: "show2",
                    button: "查看2",
                    showMode: WcCustomActionShowMode.text,
                    handler(): string {
return"测试文本2";
},
},
],
},
{
            id: "test2",
            title: "显示JSON",
            autoCase: "show",
            cases: [
{
                    id: "show",
                    button: "查看",
                    showMode: WcCustomActionShowMode.json,
                    handler() {
return wx;
},
},
],
},
{
            id: "test3",
            title: "显示表格",
            autoCase: "show",
            cases: [
{
                    id: "show",
                    button: "查看",
                    showMode: WcCustomActionShowMode.grid,
                    handler(): WcCustomActionGrid{
return{
                            cols: [
{
                                    title: "Id",
                                    field: "id",
                                    width: 30,
},
{
                                    title: "Name",
                                    field: "name",
                                    width: 70,
},
],
                            data: [
{
                                    id: 1,
                                    name: "Tom",
},
{
                                    id: 2,
                                    name: "Alice",
},
],
};
},
},
],
},
],
});

通过以下方式使用 API

import{ showWeConsole, ... } from 'weconsole';
showWeConsole();

replace(scope:'App'|'Page'|'Component'|'Api'|'Console')

替换系统变量或函数以达到监控，底层控制全局仅替换一次

restore(scope:'App'|'Page'|'Component'|'Api'|'Console')

还原被替换的系统变量或函数，还原后界面将不在显示相关数据

showWeConsole()

显示 WeConsole入口图标

hideWeConsole()

隐藏 WeConsole入口图标

setUIConfig(config: Partial<MpUIConfig>)

设置 WeConsole组件内的相关配置，可接受的配置项及含义如下：

interfaceMpUIConfig{
/**监控小程序API数据后，使用该选项进行该数据的分类值计算，计算后的结果显示在界面上 */
    apiCategoryGetter?: MpProductCategoryMap| MpProductCategoryGetter;
/**监控Console数据后，使用该选项进行该数据的分类值计算，计算后的结果显示在界面上 */
    consoleCategoryGetter?: MpProductCategoryMap| MpProductCategoryGetter;
/**API选项卡下显示的数据分类列表，all、mark、other 分类固定存在 */
    apiCategoryList?: Array<string| MpNameValue<string>>;
/**复制策略，传入复制数据，可通过数据的type字段判断数据哪种类型，比如api/console */
    copyPolicy?: MpProductCopyPolicy;
/**定制化列表 */
    customActions?: WcCustomAction[];
}

/**取数据的category字段值对应的prop */
interfaceMpProductCategoryMap{
[prop: string]: string| MpProductCategoryGetter;
}
interfaceMpProductCategoryGetter{
(product: Partial<MpProduct>): string| string[];
}
interfaceMpProductCopyPolicy{
(product: Partial<MpProduct>);
}
/**定制化 */
interfaceWcCustomAction{
/**标识，需要保持唯一 */
    id: string;
/**标题 */
    title: string;
/**默认执行哪个case？*/
    autoCase?: string;
/**该定制化有哪些情况 */
    cases: WcCustomActionCase[];
}

constenumWcCustomActionShowMode{
/**显示JSON树 */
    json = "json",
/**显示数据表格 */
    grid = "grid",
/** 固定显示<weconsole-customer>组件，该组件需要在app.json中注册，同时需要支持传入data属性，属性值就是case handler执行后的结果 */
    component = "component",
/**显示一段文本 */
    text = "text",
/**什么都不做 */
    none = "none",
}

interfaceWcCustomActionCase{
    id: string;
/**按钮文案 */
    button?: string;
/**执行逻辑 */
    handler: Function;
/**显示方式 */
    showMode?: WcCustomActionShowMode;
}

interfaceWcCustomActionGrid{
    cols: DataGridCol[];
    data: any;
}

addCustomAction(action: WcCustomAction)

添加一个定制化项目；当你添加的项目中需要显示你自己的组件时：

• 请将 case 的 showMode值设置为 component

• 在 app.json中注册名称为 weconsole-customer的组件

• 定制化项目的 case 被执行时，会将执行结果传递给 weconsole-customer的 data属性

• 开发者根据 data属性中的数据自行判断内部显示逻辑

removeCustomAction(actionId: string)

根据 ID 删除一个定制化项目

getWcControlMpViewInstances():any[]

获取小程序内 weconsole 已经监控到的所有的 App/Page/Component 实例

log(type = "log", ...args)

因为 console 被重写，当你想使用最原始的 console 方法时，可以通过该方式，type 就是 console 的方法名

on/once/off/emit

提供一个事件总线功能，全局事件及相关函数定义如下：

const enum WeConsoleEvents {
    /**UIConfig对象发生变化时 */
    WcUIConfigChange = "WcUIConfigChange",
    /**入口图标显示性发生变化时 */
    WcVisableChange = "WcVisableChange",
    /**CanvasContext准备好时，CanvasContext用于JSON树组件的界面文字宽度计算 */
    WcCanvasContextReady = "WcCanvasContextReady",
    /**CanvasContext销毁时 */
    WcCanvasContextDestory = "WcCanvasContextDestory",
    /**主组件的宽高发生变化时 */
    WcMainComponentSizeChange = "WcMainComponentSizeChange",
}

interface IEventEmitter<T = any> {
    on(type: string, handler: EventHandler<T>);
    once(type: string, handler: EventHandler<T>);
    off(type: string, handler?: EventHandler<T>);
    emit(type: string, data?: T);
}

• 优化包大小

• 单元测试

• 体验优化

• 定制化升级

• 基于网络通信的界面化 weconsole

• 标准化

• 支持 H5

• 支持其他小程序平台（支付宝/百度/字节跳动）

WeConsole 使用 MIT 协议。