「AI + 低代码引擎」的可视化设计器扩展开发

踩着两条虫
8 阅读5分钟

扩展开发

简介

本指南面向设计器扩展开发者，系统讲解扩展机制、插件系统设计理念、扩展点使用方法，以及自定义组件开发流程。文档结合仓库中的扩展应用、插件与物料模板，给出从创建、开发、调试、测试到打包发布的完整实践路径，并提供架构图与流程图帮助理解扩展体系。

项目结构

扩展开发涉及以下关键模块：

  • 扩展应用：位于 apps/extension，提供扩展入口、调试页面与构建配置
  • 插件示例：位于 apps/plugin，演示如何开发可复用的组件块与物料描述
  • 物料模板：位于 apps/material，展示物料元数据与分类组织方式
  • 设计器核心：位于 packages/designer，提供扩展点、管理器与封装器等基础设施
  • 开发示例：位于 dev/src/extension，演示扩展工厂与适配器注入
  • 脚手架生成器：位于 create-vtj，提供扩展/插件/物料模板的项目生成
graph TB
subgraph "扩展应用"
EXT_APP["apps/extension<br/>扩展入口与调试"]
end
subgraph "插件与物料"
PLUGIN["apps/plugin<br/>组件块与物料描述"]
MATERIAL["apps/material<br/>物料元数据与分类"]
end
subgraph "设计器核心"
DESIGNER["packages/designer<br/>扩展点/管理器/封装器"]
end
subgraph "开发示例"
DEV_EXT["dev/src/extension<br/>扩展工厂与适配器"]
end
subgraph "脚手架"
GEN["create-vtj<br/>项目生成器"]
end
EXT_APP --> DESIGNER
PLUGIN --> DESIGNER
MATERIAL --> DESIGNER
DEV_EXT --> DESIGNER
GEN --> EXT_APP
GEN --> PLUGIN
GEN --> MATERIAL

核心组件

  • 扩展入口与服务
    • 扩展应用入口导出扩展工厂函数，返回包含服务与安装钩子的对象，供设计器在运行时注入与挂载
  • 器件管理器（WidgetManager）
    • 提供注册、获取、修改、删除、区域筛选与远程器件管理等能力
  • 封装器与扩展点
    • 封装器导出骨架、区域、器件、Setter 等封装层，便于扩展渲染与编辑体验
  • 插件与物料
    • 插件组件示例展示属性、插槽、事件与双向绑定的规范写法
    • 物料描述文件定义属性设置器、事件、插槽与默认片段
  • 开发示例扩展工厂
    • 展示如何注册应用型器件、注入请求适配器与全局插件

架构总览

扩展系统围绕“扩展工厂 + 器件管理器 + 封装器 + 物料/插件”协同工作：

  • 扩展工厂在设计器启动时被调用，返回服务与安装钩子
  • 器件管理器集中管理所有器件，支持动态修改与区域筛选
  • 封装器提供渲染与编辑层面的扩展点
  • 插件与物料以标准格式描述组件能力，供设计器读取并渲染
sequenceDiagram
participant Designer as "设计器"
participant ExtFactory as "扩展工厂"
participant WM as "器件管理器"
participant Wrapper as "封装器"
participant Plugin as "插件/物料"
Designer->>ExtFactory : 初始化并调用工厂
ExtFactory-->>Designer : 返回 {service, install}
Designer->>ExtFactory : 调用 install(app, engine)
ExtFactory->>Wrapper : 注入UI适配器/上传器等
ExtFactory->>WM : 注册/修改器件或应用型器件
Designer->>WM : 获取器件并渲染
WM-->>Designer : 返回器件配置
Designer->>Wrapper : 使用封装器渲染/编辑
Designer->>Plugin : 加载物料与组件描述

详细组件分析

扩展应用（apps/extension）

  • 入口职责

    • 导出扩展工厂函数，返回服务实例与安装钩子
    • 可通过器件管理器对内置器件进行修改（如替换 Logo 图标）

  • 调试与构建

    • dev/main.ts 启动调试页面，便于本地联调
    • vtj.config.ts 定义项目ID、平台、库导出名与产物URL
flowchart TD
Start(["加载扩展应用"]) --> Factory["调用扩展工厂"]
Factory --> Service["创建/选择服务实例"]
Factory --> InstallHook["准备 install 钩子"]
InstallHook --> Mount["设计器调用 install(app, engine)"]
Mount --> ModifyWidgets["通过器件管理器修改/注册器件"]
ModifyWidgets --> Done(["完成"])

器件管理器（WidgetManager）

  • 能力概览
    • 注册、获取、修改、删除器件
    • 区域与分组筛选、排序
    • 远程器件识别与批量清理
  • 关键行为
    • set 支持深度合并，特殊处理 component 字段
    • getWidgets 自动补全 order 并按升序排序
  • 使用建议
    • 优先通过 set 动态调整现有器件，避免重复注册
    • 使用 getWidgets 按区域/分组获取有序列表
classDiagram
class WidgetManager {
-widgets : any
+register(widget)
+get(name)
+set(name, widget)
+unregister(name)
+getWidgets(region, group)
+getRemoteWidgets()
+removeRemoteWidgets()
}

插件与物料（apps/plugin, apps/material）

  • 插件组件
    • 展示属性、插槽、事件与双向绑定的标准写法
  • 物料描述
    • 定义属性设置器、事件、插槽与默认片段
  • 物料元数据
    • 定义分组、顺序、库名与组件映射
flowchart TD
Props["属性定义"] --> Setters["设置器配置"]
Events["事件定义"] --> Params["事件参数"]
Slots["插槽定义"] --> SlotParams["插槽参数"]
Setters --> MaterialJSON["物料描述文件"]
Events --> MaterialJSON
Slots --> MaterialJSON
MaterialJSON --> MaterialMeta["物料元数据"]
MaterialMeta --> Components["组件集合"]

开发示例扩展工厂（dev/src/extension）

  • 注册应用型器件，打开面板视图
  • 注入请求适配器，统一为请求头添加自定义字段
  • 在 install 中注册全局插件（如上传器适配）
sequenceDiagram
participant Dev as "开发示例"
participant WM as "器件管理器"
participant Req as "请求适配器"
participant App as "Vue应用"
Dev->>WM : register(meta)
Dev->>Req : useRequest(middleware)
Dev->>App : install(...) 注册全局插件

脚手架生成器（create-vtj）

  • 作用
    • 复制模板目录，重写包名与占位符，生成扩展/插件/物料项目
  • 流程
    • 读取模板与 package.json，替换 name 占位符
    • 输出 .gitignore 与 .npmrc（若存在）
flowchart TD
Gen["执行生成器"] --> Copy["复制模板目录"]
Copy --> ReadPkg["读取 package.json"]
ReadPkg --> ReplaceName["替换 name 占位符"]
ReplaceName --> WritePkg["写回 package.json"]
WritePkg --> CopyFiles["复制 .gitignore/.npmrc可选"]
CopyFiles --> Done["生成完成"]

依赖分析

  • 扩展应用依赖设计器核心提供的扩展点与管理器
  • 插件与物料通过标准描述文件与元数据参与设计器渲染
  • 开发示例扩展工厂依赖请求适配器与UI适配插件
graph LR
EXT["扩展应用"] --> WM["器件管理器"]
EXT --> WRAP["封装器"]
PLG["插件组件"] --> MAT["物料描述"]
MAT --> WM
DEVF["开发示例扩展工厂"] --> REQ["请求适配器"]
DEVF --> APP["Vue应用"]

性能考虑

  • 动态修改器件时优先使用 set 的局部更新，减少不必要的重建
  • 使用 getWidgets 的区域/分组筛选，避免全量遍历
  • 将远程器件与本地器件分离管理，必要时批量清理
  • 插件组件尽量避免在模板中做重型计算，将逻辑下沉至工具函数或缓存

故障排查指南

  • 器件未生效

    • 检查是否正确调用 set 或 register，确认名称唯一且顺序正确

  • 器件排序异常

    • 未显式设置 order 时按注册顺序自动编号；调用 getWidgets 后会按 order 升序排序

  • 请求头未生效

    • 确认 useRequest 中间件已正确注入并在 install 阶段注册

  • 调试页面无法启动

    • 检查 dev/main.ts 是否正确挂载路由与应用

结论

通过扩展工厂、器件管理器与封装器的协作，设计器提供了清晰的扩展机制。结合插件与物料的标准描述，开发者可以快速实现自定义组件与业务集成。建议遵循“最小变更、集中管理、分层封装”的原则，确保扩展的可维护性与可移植性。

附录

  • 扩展开发清单
    • 明确扩展目标与范围
    • 选择合适的扩展点（器件、请求、上传器等）
    • 编写插件组件与物料描述
    • 在扩展工厂中注册并注入依赖
    • 在调试环境中验证功能
    • 编写测试用例并完善文档
  • 最佳实践
    • 使用 set 而非重复 register 更新现有器件
    • 将通用能力抽象为工具函数或适配器
    • 保持物料描述与组件实现的一致性
    • 对外暴露稳定的 API，避免频繁破坏性变更
  • 版本与兼容
    • 严格遵循语义化版本，变更日志记录破坏性改动
    • 通过 vtj.config.ts 控制库导出名与产物URL，确保升级平滑

开源仓库：gitee.com/newgateway/…

avatar
文章
阅读
粉丝