插件视图开发指南

本文档介绍如何开发明道云插件视图，包括环境配置、项目创建、依赖安装和开发流程。

准备工作

环境要求

• Node.js：>= 16.20
• npm 或 yarn 或 pnpm
• IDE：推荐 VS Code
• 版本管理：推荐 Git（团队开发）

创建插件视图

方式一：从工作表创建

1. 在工作表中，点击「新建视图」
2. 选择「自定义视图」
3. 系统会自动创建一个视图插件，并以当前工作表为开发调试环境

环境配置

1. 创建本地项目

创建好插件后，进入自定义视图页面，按照系统提示创建本地项目。

2. 配置映射参数

在使用 mdye-utils 和 mdye-apis 之前，需要先在插件视图中配置映射参数。

步骤一：进入映射参数配置

1. 在自定义视图页面，找到「映射参数」或「参数配置」入口
2. 点击进入映射参数配置页面

步骤二：添加映射参数

在映射参数配置页面，添加以下三个参数：

• baseURL：API 地址
• appKey：应用密钥
• Sign：签名密钥

步骤三：从代码导入配置

在映射参数配置页面，可以使用「从代码导入」功能，将以下 JSON 配置导入：

[
  {
    "controlName": "appKey",
    "type": 2,
    "attribute": 0,
    "row": 0,
    "col": 0,
    "hint": "请填写",
    "default": "",
    "dot": 0,
    "unit": "",
    "enumDefault": 2,
    "enumDefault2": 0,
    "defaultMen": [],
    "dataSource": "",
    "sourceControlId": "",
    "sourceControlType": 0,
    "showControls": [],
    "noticeItem": 0,
    "userPermission": 0,
    "options": [],
    "required": false,
    "half": false,
    "relationControls": [],
    "viewId": "",
    "unique": false,
    "coverCid": "",
    "strDefault": "",
    "desc": "",
    "fieldPermission": "",
    "advancedSetting": {
      "analysislink": "1",
      "sorttype": "en",
      "min": "",
      "max": "",
      "defsource": "[{\"cid\":\"\",\"rcid\":\"\",\"staticValue\":\"\"}]"
    },
    "alias": "",
    "size": 12,
    "editAttrs": [],
    "deleteAccountId": "",
    "deleteTime": "0001-01-01 08:05:00",
    "encryId": "",
    "sectionId": "",
    "lastEditTime": "0001-01-01 08:05:00",
    "disabled": false,
    "checked": false,
    "fieldId": "appKey"
  },
  {
    "controlName": "Sign",
    "type": 2,
    "attribute": 0,
    "row": 0,
    "col": 0,
    "hint": "请填写",
    "default": "",
    "dot": 0,
    "unit": "",
    "enumDefault": 2,
    "enumDefault2": 0,
    "defaultMen": [],
    "dataSource": "",
    "sourceControlId": "",
    "sourceControlType": 0,
    "showControls": [],
    "noticeItem": 0,
    "userPermission": 0,
    "options": [],
    "required": false,
    "half": false,
    "relationControls": [],
    "viewId": "",
    "unique": false,
    "coverCid": "",
    "strDefault": "",
    "desc": "",
    "fieldPermission": "",
    "advancedSetting": {
      "analysislink": "1",
      "sorttype": "en",
      "min": "",
      "max": "",
      "defsource": "[{\"cid\":\"\",\"rcid\":\"\",\"staticValue\":\"\"}]"
    },
    "alias": "",
    "size": 12,
    "editAttrs": [],
    "deleteAccountId": "",
    "deleteTime": "0001-01-01 08:05:00",
    "encryId": "",
    "sectionId": "",
    "lastEditTime": "0001-01-01 08:05:00",
    "disabled": false,
    "checked": false,
    "fieldId": "Sign"
  },
  {
    "controlName": "baseURL",
    "type": 2,
    "attribute": 0,
    "row": 0,
    "col": 0,
    "hint": "请填写",
    "default": "",
    "dot": 0,
    "unit": "",
    "enumDefault": 2,
    "enumDefault2": 0,
    "defaultMen": [],
    "dataSource": "",
    "sourceControlId": "",
    "sourceControlType": 0,
    "showControls": [],
    "noticeItem": 0,
    "userPermission": 0,
    "options": [],
    "required": false,
    "half": false,
    "relationControls": [],
    "viewId": "",
    "unique": false,
    "coverCid": "",
    "strDefault": "",
    "desc": "",
    "fieldPermission": "",
    "advancedSetting": {
      "analysislink": "1",
      "sorttype": "en",
      "min": "",
      "max": "",
      "defsource": "[{\"cid\":\"\",\"rcid\":\"\",\"staticValue\":\"\"}]"
    },
    "alias": "",
    "size": 12,
    "editAttrs": [],
    "deleteAccountId": "",
    "deleteTime": "0001-01-01 08:05:00",
    "encryId": "",
    "sectionId": "",
    "lastEditTime": "0001-01-01 08:05:00",
    "disabled": false,
    "checked": false,
    "fieldId": "baseURL"
  }
]

配置说明

导入配置后，需要在映射参数配置页面中填写实际值：

• appKey：在明道云「开放对接」→「授权管理」中获取
• Sign：在明道云「开放对接」→「授权管理」中获取
• baseURL：根据你的明道云部署环境填写（公有云或私有部署地址）

这些值不需要在 JSON 代码中填写，导入配置后直接在页面中填写即可。

3. 安装依赖

配置好映射参数后，在本地项目中安装以下两个包，它们对明道云的开放接口 API 进行了封装，支持 TypeScript 类型提示：

npm install mdye-utils mdye-apis
# 或
yarn add mdye-utils mdye-apis
# 或
pnpm add mdye-utils mdye-apis

重要提示：必须先配置好映射参数（baseURL、appKey、Sign），然后才能使用这两个包。配置后即可直接使用封装好的方法，无需再写 axios 请求，避免重复代码。

4. 样式方案推荐

建议在项目中使用 Tailwind CSS，配合 AI 工具可以大幅提升样式开发效率。

npm install -D tailwindcss postcss autoprefixer
npx tailwindcss init -p

开发流程

1. 启动开发服务器

npm run dev
# 或
yarn dev
# 或
pnpm dev

2. 获取调试地址

启动后，控制台会输出本地开发地址，例如：

Local:   http://localhost:5173
Network: http://192.168.1.100:5173

3. 配置调试地址

1. 在明道云的自定义视图页面，找到「调试台」
2. 将控制台输出的地址复制到调试台
3. 保存后即可在明道云中实时预览插件视图

基础代码结构

引入 mdye

import { env, config, api, utils, md_emitter } from "mdye";

获取配置信息

const { appId, worksheetId, viewId, controls } = config;
const { baseURL, appKey, Sign } = env; // 从映射参数获取

监听页面事件

import { useEffect } from "react";
import { md_emitter } from "mdye";

useEffect(() => {
  // 监听筛选条件变更
  const handleFiltersUpdate = (newFilters) => {
    console.log('筛选条件变更:', newFilters);
    // 重新加载数据
    loadRecords(newFilters);
  };

  md_emitter.addListener("filters-update", handleFiltersUpdate);
  
  return () => {
    md_emitter.removeListener("filters-update", handleFiltersUpdate);
  };
}, []);

获取数据

import { api } from "mdye";

async function loadRecords(filters = {}) {
  const res = await api.getFilterRows({
    worksheetId,
    viewId,
    pageIndex: 1,
    pageSize: 20,
    ...filters,
  });
  console.log('数据:', res.data);
}

常用 API

mdye.api

• getFilterRows(params) - 获取筛选后的记录
• getFilterRowsTotalNum(params) - 获取记录总数
• getRowDetail(params) - 获取记录详情
• addWorksheetRow(params) - 新增记录
• updateWorksheetRow(params) - 更新记录
• deleteWorksheetRow(params) - 删除记录

mdye.utils

• openRecordInfo(params) - 打开记录详情弹窗
• openNewRecord(params) - 打开新建记录窗口
• selectUsers(params) - 选择用户
• selectRecord(params) - 选择记录

详细 API 文档请参考：明道云视图插件开发文档 - API 文档

开发技巧

1. 使用 TypeScript

使用 mdye-utils 和 mdye-apis 可以获得完整的 TypeScript 类型提示，提升开发体验。

2. 使用 Tailwind CSS

配合 AI 工具，可以快速生成样式代码，提升开发效率。

3. 调试技巧

• 使用浏览器开发者工具查看网络请求
• 使用 console.log 输出调试信息
• 在明道云调试台中查看错误信息

发布插件

开发完成后，按照以下步骤发布插件：

1. 在插件中心进入「我开发的」
2. 找到对应插件，点击「发布」
3. 填写插件信息（名称、描述、图标等）
4. 提交审核

参考资源

• 明道云视图插件开发文档
• 视图插件源码示例
• HAP 前端开源项目