tmagic-editor 自定义组件开发完全指南

前言

tmagic-editor 作为一个强大的可视化编辑器，其核心能力之一就是支持业务方进行自定义组件开发。本文将深入讲解如何在 tmagic-editor 中开发、调试和使用自定义组件，帮助开发者快速掌握组件开发的全流程。

组件开发基础概念

在 tmagic-editor 中，组件是以 npm 包形式存在的模块化单元。每个组件需要遵循特定的开发规范，才能在编辑器中正确注册、配置和渲染。

组件生命周期

1. 开发阶段：创建组件代码和配置文件
2. 注册阶段：将组件注册到编辑器组件列表中
3. 配置阶段：在编辑器中配置组件属性
4. 渲染阶段：在运行时环境中渲染组件

组件开发规范

一个标准的 tmagic-editor 组件需要包含以下核心文件：

1. 入口文件 (index.js)

作为组件的统一入口，负责导出组件和相关配置：

import Component from './Component.vue';  // 或 Component.tsx
export { default as config } from './formConfig';
export { default as value } from './initValue';
export default Component;

2. 表单配置 (formConfig.js)

定义组件在编辑器中可配置的属性表单：

export default [
  {
    type: 'select',       // 表单控件类型
    text: '字体颜色',     // 显示标签
    name: 'color',        // 属性名
    options: [            // 选项（针对选择类控件）
      { text: '红色', value: 'red' },
      { text: '蓝色', value: 'blue' }
    ]
  },
  {
    name: 'text',
    text: '文本内容'
  }
];

3. 初始值 (initValue.js)

定义组件的默认属性值：

export default {
  color: 'red',
  text: '默认文本'
};

4. 组件实现文件

根据技术栈不同，可以是 .vue 或 .tsx 文件：

Vue 组件示例

<template>
  <div class="test-component">
    <span>组件示例：</span>
    <span :style="{ color: config.color }">{{ config.text }}</span>
  </div>
</template>

<script>
export default {
  name: 'magic-ui-test',  // 必须与组件type一致
  props: {
    config: Object       // 接收配置属性
  }
};
</script>

React 组件示例

import React, { useContext } from 'react';
import { AppContent } from '@tmagic/ui-react';

export default function Test({ config }) {
  const app = useContext(AppContent);
  
  return (
    <div style={app.transformStyle(config.style || {})}>
      <span>组件示例：</span>
      <span style={{ color: config.color }}>{config.text}</span>
    </div>
  );
}

组件开发全流程

1. 创建组件项目结构

建议按照以下目录结构组织组件代码：

my-component/
├── src/
│   ├── index.js       # 组件入口
│   ├── formConfig.js  # 表单配置
│   ├── initValue.js   # 初始值
│   └── Component.vue  # 组件实现
├── package.json
└── README.md

2. 配置打包工具

在项目的构建配置中（如 tmagic.config.ts）添加组件路径：

export default {
  packages: [
    './src/components/my-component'  // 组件路径
  ]
};

3. 注册组件到编辑器

在编辑器的组件列表配置中添加新组件：

// componentGroupList.js
export default [
  {
    title: '我的组件',
    items: [
      {
        text: '测试组件',
        type: 'test',  // 必须与组件name一致
        icon: 'icon-name'  // 可选图标
      }
    ]
  }
];

4. 开发环境调试

启动 playground 开发环境：

npm run playground

在编辑器中可以：

1. 从组件面板拖拽添加组件
2. 在属性面板配置组件
3. 实时预览组件效果

5. 运行时环境调试

将编辑器生成的 DSL 配置复制到运行时环境：

// runtime/page-config.js
window.magicDSL = [
  // 粘贴DSL配置
];

启动运行时开发服务器：

npm run dev

高级功能开发

组件联动

通过事件系统实现组件间的交互：

// event.js
export default [
  {
    text: '点击事件',
    name: 'click'
  }
];

在组件中触发事件：

<script>
export default {
  methods: {
    handleClick() {
      this.$emit('click');
    }
  }
};
</script>

自定义表单控件

开发复杂的自定义表单控件：

// formConfig.js
export default [
  {
    type: 'custom-input',  // 自定义控件类型
    name: 'customProp',
    component: CustomInputComponent  // 自定义控件组件
  }
];

最佳实践

1. 命名规范：组件名称前缀保持一致（如 magic-ui-）
2. 样式隔离：使用scoped样式或CSS Modules
3. 性能优化：避免不必要的渲染
4. 响应式设计：考虑不同设备的显示效果
5. 错误边界：添加组件错误处理

常见问题解决

1. 组件不显示：检查type与name是否一致
2. 配置不生效：检查formConfig定义是否正确
3. 样式异常：检查样式作用域和继承关系
4. 事件不触发：检查事件名称是否匹配

结语

通过本文的详细讲解，相信您已经掌握了在 tmagic-editor 中开发自定义组件的方法。组件化开发是可视化编辑器的核心能力，合理设计组件结构、遵循开发规范，可以大大提高开发效率和组件复用性。