hap-view-plugin

HAP 自定义视图插件开发技能

此技能提供创建和开发明道云 HAP 自定义视图插件的完整工作流程和开发规范。

关于此技能

此技能专门用于开发明道云 HAP（High-performance Application Platform）自定义视图插件。通过集成的脚手架工具，可以快速创建 React 基础示例模板项目，安装依赖并启动开发环境。

前置条件

在使用此技能前，确保：

1. 已安装 16.20 或更高版本的 Node.js
2. 拥有明道云开发者账号和插件开发权限
3. 了解基本的 React 开发知识

开发环境配置

Cursor 编辑器配置

下载 mdye-cursorrules.md 文件并复制其中内容到视图开发项目根目录下的 .cursorrules 文件中，即可在 Cursor 编辑器中获得明道云视图插件开发的智能提示和代码规范检查。

教学 DEMO

请下载明道云视图插件开发教学 DEMO，此插件为开发者提供直观、可交互的 API 使用实例。

核心功能

1. 安装 mdye-cli 工具

• 全局安装插件开发专用的命令行工具
• 验证工具安装是否成功

2. 初始化本地项目

• 创建唯一的插件项目文件夹
• 使用 React 基础示例模板
• 生成项目配置文件

3. 安装项目依赖

• 安装项目所需的 npm 依赖包
• 配置开发环境

4. 启动开发环境

• 启动本地开发服务器
• 支持热重载和实时预览
• 提供线上调试能力

开发工作流程

步骤 1：检查并安装 mdye-cli 工具

首先检查是否已安装：

mdye --version

如果显示版本号，说明已安装，可以跳过安装步骤。

如果未安装，根据系统安装：

Mac OS 用户：

sudo npm install -g mdye-cli

Windows/Linux 用户：

npm install -g mdye-cli

验证安装：

mdye --version

步骤 2：初始化本地项目

创建项目命令：

mdye init view --id 693d2fed8474b99be3d3c12e-69563e5df03728c888c04f05 --template React

参数说明：

• --id: 插件 ID（示例 ID，实际使用时需要替换）
• --template React: 使用 React 基础示例模板

项目结构：

mdye_view_69563e5df03728c888c04f05/
├── package.json
├── mdye.json
├── src/
│   ├── index.jsx
│   ├── App.jsx
│   └── styles.less
└── .gitignore

步骤 3：进入项目目录并安装依赖

进入项目目录：

cd mdye_view_69563e5df03728c888c04f05

安装依赖：

npm i

步骤 4：启动开发环境

启动命令：

mdye start

启动后：

• 开发服务器将在 http://localhost:3000/ 启动
• 将调试地址 http://localhost:3000/bundle.js 粘贴到明道云视图配置开发调试输入框
• 支持实时编辑和热重载

API 使用指南

1. 环境变量及配置获取

1.1 获取 env 环境变量

// 使用辅助函数安全获取env中的配置项
function getEnvValue(env, key, defaultValue = null) {
  if (!env || !key) return defaultValue;

  const value = env[key];

  // 处理数组类型(字段选择器)
  if (Array.isArray(value)) {
    return value.length > 0 ? value[0] : defaultValue;
  }

  // 处理普通值
  return value !== undefined ? value : defaultValue;
}

// 使用示例
const titleFieldId = getEnvValue(env, 'title');
const maxRecords = getEnvValue(env, 'maxRecords', '50');

1.2 获取 config 配置

import { config } from "mdye";

// 获取应用、工作表、视图的ID
const { appId, worksheetId, viewId, controls } = config;

// 获取字段控件信息
const fieldControl = _.find(controls, { controlId: fieldId });

2. 数据获取 API

2.1 获取工作表数据 (getFilterRows)

import { api } from "mdye";

async function loadRecords() {
  const result = await api.getFilterRows({
    worksheetId,     // 必填-工作表ID
    viewId,          // 必填-视图ID
    pageIndex: 1,    // 可选-页码
    pageSize: 50,    // 可选-每页记录数
    sortId: "fieldId", // 可选-排序字段
    isAsc: true,     // 可选-升序排序
    // 获取关联字段数据
    requestParams: {
      plugin_detail_control: relationFieldId
    }
  });

  return result.data; // 记录数组
}

2.2 获取记录详情 (getRowDetail)

async function getRecordDetail(rowId) {
  const result = await api.getRowDetail({
    appId,
    worksheetId,
    viewId,
    rowId
  });

  return result.data;
}

2.3 获取关联记录 (getRowRelationRows)

async function loadRelationRows({ controlId, rowId }) {
  const result = await api.getRowRelationRows({
    worksheetId,
    controlId,       // 关联字段ID
    rowId,           // 主记录ID
    pageIndex: 1,
    pageSize: 10
  });

  return result.data;
}

3. 数据操作 API

3.1 新增记录 (addWorksheetRow)

async function addRecord(fieldsData) {
  const response = await api.addWorksheetRow({
    appId,
    worksheetId,
    receiveControls: [
      {
        controlId: "fieldId1",
        type: 2,
        value: "测试文本"
      }
    ]
  });
  return response;
}

3.2 更新记录 (updateWorksheetRow)

async function updateRecord(rowId, fieldId, newValue) {
  const response = await api.updateWorksheetRow({
    appId,
    worksheetId,
    rowId,
    newOldControl: [
      {
        controlId: fieldId,
        type: 2,
        value: newValue
      }
    ]
  });
  return response;
}

3.3 删除记录 (deleteWorksheetRow)

async function deleteRecord(rowId) {
  const response = await api.deleteWorksheetRow({
    appId,
    worksheetId,
    rowIds: [rowId]
  });
  return response;
}

4. 工具函数 (utils)

4.1 打开记录详情（推荐使用！）

使用 utils.openRecordInfo 打开明道云原生行记录组件是最佳实践:

优势:

• ✅ 原生体验,与明道云界面一致
• ✅ 功能完整:支持编辑、删除、讨论、日志、附件等所有功能
• ✅ 自动处理权限验证
• ✅ 无需自己开发弹窗 UI
• ✅ 返回操作结果,方便进行数据同步

基础用法:

import { utils } from "mdye";

// 打开记录详情
const handleRecordClick = async (recordId) => {
  try {
    const result = await utils.openRecordInfo({
      appId,
      worksheetId,
      viewId,
      recordId
    });

    // 处理返回结果
    if (result) {
      console.log('操作结果:', result);

      // 根据操作类型处理
      switch (result.action) {
        case 'update':
          // 记录被更新,刷新数据
          console.log('记录已更新:', result.value);
          loadRecords(); // 重新加载数据
          break;
        case 'delete':
          // 记录被删除,刷新列表
          console.log('记录已删除');
          loadRecords(); // 重新加载数据
          break;
        case 'close':
          // 用户关闭弹窗(无修改)
          console.log('用户关闭了弹窗');
          break;
      }
    }
  } catch (error) {
    console.error('打开记录详情失败:', error);
  }
};

返回值说明:

{
  action: 'update' | 'delete' | 'close',  // 操作类型
  value: object | null                     // 更新后的记录数据(仅 action='update' 时)
}

完整的 React Hook 示例(包含自动刷新):

import React, { useEffect, useState } from 'react';
import { config, api, utils } from 'mdye';

function RecordsList() {
  const { appId, worksheetId, viewId } = config;
  const [records, setRecords] = useState([]);
  const [loading, setLoading] = useState(false);

  // 加载记录列表
  const loadRecords = async () => {
    try {
      setLoading(true);
      const result = await api.getFilterRows({
        worksheetId,
        viewId,
        pageSize: 100,
        pageIndex: 1
      });
      setRecords(result.data || []);
    } catch (error) {
      console.error('加载记录失败:', error);
    } finally {
      setLoading(false);
    }
  };

  // 打开记录详情
  const handleRecordClick = async (recordId) => {
    try {
      const result = await utils.openRecordInfo({
        appId,
        worksheetId,
        viewId,
        recordId
      });

      // 自动刷新列表
      if (result?.action === 'update' || result?.action === 'delete') {
        loadRecords(); // 刷新数据
      }
    } catch (error) {
      console.error('打开记录详情失败:', error);
    }
  };

  // 初始加载
  useEffect(() => {
    loadRecords();
  }, []);

  return (
    <div>
      {loading ? (
        <div>加载中...</div>
      ) : (
        <div>
          {records.map(record => (
            <div
              key={record.rowid}
              onClick={() => handleRecordClick(record.rowid)}
              style={{ cursor: 'pointer' }}
            >
              {record.title}
            </div>
          ))}
        </div>
      )}
    </div>
  );
}

性能优化建议:

// 1. 使用 useCallback 避免重复创建函数
const handleRecordClick = useCallback(async (recordId) => {
  const result = await utils.openRecordInfo({
    appId, worksheetId, viewId, recordId
  });
  if (result?.action === 'update' || result?.action === 'delete') {
    loadRecords();
  }
}, [appId, worksheetId, viewId]);

// 2. 只在需要时刷新
const handleRecordClick = async (recordId) => {
  const result = await utils.openRecordInfo({
    appId, worksheetId, viewId, recordId
  });

  // 根据具体操作决定是否刷新
  if (result?.action === 'update') {
    // 局部更新(性能更好)
    setRecords(prev =>
      prev.map(r => r.rowid === recordId ? result.value : r)
    );
  } else if (result?.action === 'delete') {
    // 从列表中移除
    setRecords(prev => prev.filter(r => r.rowid !== recordId));
  }
};

4.2 打开新建记录窗口

utils.openNewRecord({
  appId,
  worksheetId
}).then(newRecord => {
  if (newRecord) {
    addLocalRecord(newRecord);
  }
});

4.3 选择用户

const users = await utils.selectUsers({
  projectId: "orgId1",
  unique: false  // 是否单选
});

4.4 选择部门

const departments = await utils.selectDepartments({
  projectId: "orgId1",
  unique: false
});

4.5 选择位置

const location = await utils.selectLocation({
  distance: 1000,
  defaultPosition: { lat: 39.915, lng: 116.404 },
  multiple: false
});

4.6 选择记录

const records = await utils.selectRecord({
  projectId: "orgId1",
  relateSheetId: "worksheetId1",
  multiple: true
});

5. 事件监听

5.1 筛选条件变更事件

import { md_emitter } from "mdye";

useEffect(() => {
  const handleFiltersUpdate = (newFilters) => {
    console.log('筛选条件已更新:', newFilters);
    // 重新获取数据
  };

  md_emitter.addListener('filters-update', handleFiltersUpdate);

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

5.2 新增记录事件

useEffect(() => {
  const handleNewRecord = (newRecord) => {
    console.log('新增记录:', newRecord);
    setRecords(prev => [...prev, newRecord]);
  };

  md_emitter.addListener('new-record', handleNewRecord);

  return () => {
    md_emitter.removeListener('new-record', handleNewRecord);
  };
}, []);

特殊字段类型处理

⚠️ 重要提示:字段类型编号

明道云字段类型编号与文档中的枚举值不完全一致,开发时务必注意:

根据明道云 API V3 版本的实际字段类型定义:

• Type 9 = 单选 (SingleSelect) ⚠️ 注意不是 type 11
• Type 10 = 多选 (MultipleSelect)
• Type 11 = 下拉 (Dropdown)

完整字段类型对照表(V3 实用版)

Content truncated.