如何开发一个组件

tmagic-editor支持业务方进行自定义组件开发。在tmagic-editor中，组件是以 npm 包形式存在的，组件和插件只要按照规范开发，就可以在tmagic-editor的 runtime 中被加入并正确渲染组件。

组件规范

组件的基础形式，需要有四个文件

index 入口文件，引入下面几个文件
form-config 表单配置描述
init-value 表单初始值
event 定义联动事件，具体可以参考组件联动
component.{vue,jsx} 组件样式、逻辑代码

1. 创建组件

可以使用npm create tmagic 选择 components:组件库(组件/插件/数据源) 来快速创建一个组件库。

然后继续使用npm create tmagic 选择 component:组件 来快速创建一个组件。

:::tip

组件库并不是必须，组件如何管理可以根据具体情况来选择。直接放到 runtime 目录中也是一个不错的选择，如果选择放到runtime中可以在runtime中的package.json添加"tmagicComponentsPath": "./components" 来指定组件库的路径。这样在使用npm create tmagic 来创建组件时，会自动将组件添加到组件库中。

:::

手动创建组件，可以在项目中，如 runtime 目录中，创建一个名为 test-component 的组件目录，其中包含上面四个规范文件。

// index.js
// vue
import Test from './Test.vue';
// react 
import Test from './Test.tsx';

export { default as config } from './form-config';
export { default as value } from './init-value';

export default Test;

:::tip 如果在runtime中使用了@tmagic/cli，则必须保持此规范；不使用则可以自由书写。 :::

// form-config.js
export default [
  {
    type: 'select',
    text: '字体颜色',
    name: 'color',
    options: [
      {
        text: '红色字体',
        value: 'red',
      },
      {
        text: '蓝色字体',
        value: 'blue',
      },
    ],
  },
  {
    name: 'text',
    text: '配置文案',
  },
];

:::tip 配置内容必须是一个数组，每个元素是一个对象，包含 type、text、name 等属性，每个对象代表一个表单项。

type 是表单项的类型

text 是表单项的文本

name 是表单项值的key。

上述实例对应生成的值为

{
  "color": "red",
  "text": "一段文字",
}

type 在@tmagic/form 和 @tmagic/editor 中默认提供了种，@tmagic/form提供的可以前往表单配置查看。 :::

// init-value.js
export default {
  color: 'red',
  text: '一段文字',
};

:::tip 在编辑器中添加组件时使用，作为初始值。 :::

Vue版本的组件代码示例

<!-- Test.vue -->
<template>
  <div>
    <span>this is a Test component:</span>
    <span :style="{ color: config.color }">{{ config.text }}</span>
  </div>
</template>

<script setup>
defineOptions({
  name: 'magic-ui-test',
});

defineProps({
  config: {
    type: Object,
    default: () => ({}),
  },
}):
</script>

:::tip 编辑器中配置的 config 对象，会作为 props 传入组件中。 :::

react 版本组件代码示例

// Test.tsx
import React, { useContext } from 'react';

import Core from '@tmagic/core';
import { AppContent } from '@tmagic/ui-react';

function Test({ config }: { config: any }) {
  const app = useContext<Core | undefined>(AppContent);
  console.log(app)

  return (<div id={config.id}
    style={app.transformStyle(config.style || {})}>
    <span>this is a Test component:</span>
    <span style={ { color: config.color }}>{ config.text }</span>
  </div>);
}

export default Test;

插件开发

插件开发和组件开发形式类似，但是插件开发不需要有组件的规范。

我们只需要在插件中提供一个入口文件。插件需要提供一个 install 方法。

// 在Vue的runtime中
export default {
  install(vueApp, { app: tmagicApp }) {}
}

// 在React的runtime中
export default {
  install({ app: tmagicApp }) {}
}

在插件中开发者可以自由实现需要的业务逻辑。

集成到runtime中

使用@tmagic/cli

在使用npm create tmagic 创建的runtime中，自动集成了@tmagic/cli，将组件集成到此runtime中只需要在tmagic.config.ts中的packages字段中添加

import { defineConfig } from '@tmagic/cli';

export default defineConfig({
  // other config
  packages: [
    {
      '组件type': '组件目录或者npm包名',
    },
  ],
});

:::tip 组件type需要与componentGroupList中的type对应。 :::

配置到packages字段中后，执行npm run tmagic来创建组件库的入口文件。

然后使用npm run build:libs命令来构建用于编辑器中的组件配置、组件初始值、组件事件联动的资源文件。

4.8 KiB Raw Blame History Unescape Escape