mirror of
https://github.com/Tencent/tmagic-editor.git
synced 2025-04-05 19:41:40 +08:00
docs: 添加render教程
This commit is contained in:
roymondchen
jia000
parent
8b70edeaf2
commit
dd1a8e22c5
@ -121,6 +121,7 @@ const sidebar = {
|
||||
children: [
|
||||
'/tutorial/hello-world',
|
||||
'/tutorial/runtime',
|
||||
'/tutorial/render',
|
||||
]
|
||||
},
|
||||
]
|
||||
|
||||
@ -80,6 +80,13 @@ import { FolderOpened, SwitchButton, Tickets } from '@element-plus/icons';
|
||||
|
||||
::: tip
|
||||
icon使用的是[element-plus icon](https://element-plus.org/zh-CN/component/icon.html)
|
||||
|
||||
也可直接使用url，例如
|
||||
```js
|
||||
{
|
||||
icon: 'https://vfiles.gtimg.cn/vupload/20220614/9cc3091655207317835.png'
|
||||
}
|
||||
```
|
||||
:::
|
||||
|
||||
::: warning
|
||||
@ -119,6 +126,17 @@ import ModListPanel from '../components/sidebars/ModListPanel.vue';
|
||||
}
|
||||
```
|
||||
|
||||
::: tip
|
||||
icon使用的是[element-plus icon](https://element-plus.org/zh-CN/component/icon.html)
|
||||
|
||||
也可直接使用url，例如
|
||||
```js
|
||||
{
|
||||
icon: 'https://vfiles.gtimg.cn/vupload/20220614/9cc3091655207317835.png'
|
||||
}
|
||||
```
|
||||
:::
|
||||
|
||||
### menu
|
||||
|
||||
- **类型：** [MenuBarData](https://github.com/Tencent/tmagic-editor/blob/master/packages/editor/src/type.ts)
|
||||
@ -177,6 +195,17 @@ import { ArrowLeft, Coin } from '@element-plus/icons';
|
||||
}
|
||||
```
|
||||
|
||||
::: tip
|
||||
icon使用的是[element-plus icon](https://element-plus.org/zh-CN/component/icon.html)
|
||||
|
||||
也可直接使用url，例如
|
||||
```js
|
||||
{
|
||||
icon: 'https://vfiles.gtimg.cn/vupload/20220614/9cc3091655207317835.png'
|
||||
}
|
||||
```
|
||||
:::
|
||||
|
||||
### render
|
||||
|
||||
- **类型：** Function
|
||||
|
||||
@ -82,40 +82,26 @@ export default {
|
||||
</div>
|
||||
</template>
|
||||
|
||||
<script lang="ts">
|
||||
<script lang="ts" setup>
|
||||
import { defineComponent, inject } from 'vue';
|
||||
|
||||
export default defineComponent({
|
||||
name: 'magic-ui-test',
|
||||
const app: Core | undefined = inject('app');
|
||||
|
||||
setup(props) {
|
||||
const app: Core | undefined = inject('app');
|
||||
const hoc = inject('hoc');
|
||||
const onClick = () => {
|
||||
// app.emit 第一个参数为事件名，其余参数为你要传给接受事件组件的参数
|
||||
app?.emit("yourComponent:finishSomething", /*可以传参给接收方*/);
|
||||
};
|
||||
|
||||
// 此处实现事件动作
|
||||
// 由于组件在 @tmagic/ui 中通过基础组件 Component 来封装，即每个组件其实都被 Component 包裹
|
||||
// 实际触发时，会触发到当前组件的直属父组件 Component 上，我们会 provide 这个父组件为高阶组件 hoc
|
||||
// 所以将 toast 方法挂载到当前组件的父组件上
|
||||
hoc.toast = (/*接收触发事件组件传进来的参数*/) => {
|
||||
toast('测试 vue3')
|
||||
};
|
||||
|
||||
return {
|
||||
// 此处实现触发事件
|
||||
onClick: () => {
|
||||
// app.emit 第一个参数为事件名，其余参数为你要传给接受事件组件的参数
|
||||
app?.emit("yourComponent:finishSomething", /*可以传参给接收方*/);
|
||||
},
|
||||
};
|
||||
},
|
||||
defineExport({
|
||||
// 此处实现事件动作
|
||||
// 实际触发时是调用vue实例上的方法，所以需要将改方法暴露到实例上
|
||||
toast: (/*接收触发事件组件传进来的参数*/) => {
|
||||
toast('测试 vue3')
|
||||
}
|
||||
});
|
||||
</script>
|
||||
```
|
||||
|
||||
::: tip
|
||||
在用 vue 实现的 组件中，我们通过 inject 方式来提供核心 app 和高阶组件 hoc。调用联动事件方法时，tmagic-editor是通过组件的 ref，并直接调用当前组件的方法。
|
||||
:::
|
||||
|
||||
#### react 版本实现
|
||||
在 react 的实现中，由于tmagic-editor提供的 @tmagic/ui-react 版本是用 hook 实现的。所以组件开发我们也相应的需要使用 hook 方式。
|
||||
|
||||
@ -125,10 +111,8 @@ import React from 'react';
|
||||
import { useApp } from '@tmagic/ui-react';
|
||||
|
||||
function Test({ config }) {
|
||||
// react 和 vue 实现不同，我们通过 useApp 这个 hook 来提供 app, ref 等核心内容
|
||||
// 其中 ref 需要绑定到你的组件上作为 ref。因为一些公共事件会需要使用到你的组件 dom
|
||||
// 同时这个 ref 也会在tmagic-editor的高级函数钩子中，将你的组件 dom 作为参数提供给自定义钩子
|
||||
const { app, ref } = useApp({
|
||||
// react 和 vue 实现不同，我们通过 useApp 这个 hook 来提供 app 等核心内容
|
||||
const { app } = useApp({
|
||||
config,
|
||||
// 此处实现事件动作
|
||||
// 通过向 useApp 这个 hook 提供 methods 方法
|
||||
@ -147,7 +131,6 @@ function Test({ config }) {
|
||||
|
||||
return (
|
||||
<div
|
||||
ref={ref}
|
||||
id={config.id}
|
||||
style={app.transformStyle(config.style || {})}
|
||||
onClick={onClick}
|
||||
|
||||
@ -39,7 +39,7 @@ tmagic-editor可视化开源项目是从魔方平台演化而来的开源项目
|
||||
- **runtime** 实现在编辑器中对使用不同框架的组件的渲染。
|
||||
- **page** 项目提供最终页面发布的执行环境与组件构建。
|
||||
|
||||
可以查阅 Magic 的[源代码](https://github.com/Tencent/tmagic-editor)，与文档描述内容可以逐一对应上，希望文档内容可以为开发者带来比较好的开发体验。
|
||||
可以查阅 tmagic 的[源代码](https://github.com/Tencent/tmagic-editor)，与文档描述内容可以逐一对应上，希望文档内容可以为开发者带来比较好的开发体验。
|
||||
|
||||
## 谁在使用
|
||||
|
||||
|
||||
@ -51,7 +51,7 @@ cd hello-world
|
||||
## 添加依赖
|
||||
|
||||
```bash
|
||||
npm install --save @tmagic/editor @tmagic/form element-plus
|
||||
npm install --save @tmagic/editor @tmagic/form @tmagic/stage element-plus
|
||||
```
|
||||
|
||||
## 注册组件
|
||||
@ -227,6 +227,8 @@ renderer.iframe.contentWindow.magic?.onPageElUpdate(root);
|
||||
最终完整的render函数实现
|
||||
|
||||
```ts
|
||||
import type StageCore from '@tmagic/stage';
|
||||
|
||||
const render = async ({ renderer }: StageCore) => {
|
||||
const root = window.document.createElement('div');
|
||||
|
||||
@ -268,10 +270,10 @@ const render = async ({ renderer }: StageCore) => {
|
||||
}
|
||||
`;
|
||||
|
||||
renderer.iframe.contentDocument.head.appendChild(style);
|
||||
renderer.iframe?.contentDocument?.head.appendChild(style);
|
||||
|
||||
renderer.iframe.contentWindow.magic?.onPageElUpdate(root);
|
||||
renderer.iframe.contentWindow.magic?.onRuntimeReady({});
|
||||
renderer.contentWindow?.magic?.onPageElUpdate(root);
|
||||
renderer.contentWindow?.magic?.onRuntimeReady({});
|
||||
});
|
||||
|
||||
return root;
|
||||
|
||||
282
docs/src/tutorial/render.md
Normal file
282
docs/src/tutorial/render.md
Normal file
@ -0,0 +1,282 @@
|
||||
# 3.[DSL](../guide/conception.md#dsl) 解析渲染
|
||||
|
||||
tmagic 提供了 vue3/vue2/react 三个版本的解析渲染组件，可以直接使用
|
||||
|
||||
[@tmagic/ui](https://www.npmjs.com/package/@tmagic/ui)
|
||||
|
||||
[@tmagic/ui-vue2](https://www.npmjs.com/package/@tmagic/ui-vue2)
|
||||
|
||||
[@tmagic/ui-react](https://www.npmjs.com/package/@tmagic/ui-react)
|
||||
|
||||
接下来是已vue3为基础，来讲述如何实现一个[@tmagic/ui](https://www.npmjs.com/package/@tmagic/ui)
|
||||
|
||||
## 准备工作
|
||||
|
||||
### 创建项目
|
||||
|
||||
将[上一教程](./runtime.md)中的[editor-runtime](https://github.com/jia000/tmagic-tutorial/tree/master/course2/editor-runtime)和[hello-editor](https://github.com/jia000/tmagic-tutorial/tree/master/course2/hellow-editor)复制过来
|
||||
|
||||
## 基础概念
|
||||
|
||||
### 节点（Node）
|
||||
|
||||
每一个组件最终都是由一个节点来描述，每个节点至少拥有id,type两个属性
|
||||
|
||||
id: 节点的唯一标识，不可重复
|
||||
|
||||
type: 节点的类型，有业务自行定义
|
||||
|
||||
### 容器（Container）
|
||||
|
||||
容器也是节点的一种，容器可以包含多个节点并且是保存在items属性下
|
||||
|
||||
items: 容器下包含的节点组成的数组，items中不能有page,app
|
||||
|
||||
### 页面（Page)
|
||||
|
||||
页面是容器的一种，type固定为page，items中不能有page
|
||||
|
||||
### 根（Root)
|
||||
|
||||
根节点也是一个容器，type固定为app，items只能是page
|
||||
|
||||
## 实现
|
||||
|
||||
创建hello-ui目录
|
||||
|
||||
```
|
||||
.
|
||||
└─editor-runtime
|
||||
└─hello-editor
|
||||
└─hello-ui
|
||||
```
|
||||
|
||||
### 渲染节点
|
||||
|
||||
在hello-ui下创建 Component.vue 文件
|
||||
|
||||
由于节点的type是由业务自行定义的，所以需要使用动态组件渲染，在vue下可以使用[component](https://cn.vuejs.org/v2/api/#component)组件来实现
|
||||
|
||||
[component](https://cn.vuejs.org/v2/api/#component) 是通过is参数来决定哪个组件被渲染，所以将type与组件做绑定
|
||||
|
||||
例如有组件 HelloWorld，可以将组件全局注册
|
||||
|
||||
```js
|
||||
app.component('hello-world', HelloWorld);
|
||||
```
|
||||
|
||||
然后将'hello-world'作为type，那么is="hello-world"就会渲染 HelloWorld 组件
|
||||
|
||||
为了让组件渲染出来的dom能被编辑器识别到，还需要将节点的id作为dom的id
|
||||
|
||||
```vue
|
||||
<template>
|
||||
<component v-if="config" :is="type" :id="`${id}`" :style="style" :config="config"></component>
|
||||
</template>
|
||||
|
||||
<script lang=ts setup>
|
||||
import { computed } from 'vue';
|
||||
|
||||
import type { MNode } from '@tmagic/schema';
|
||||
|
||||
// 将节点作品参数传入组件中
|
||||
const props = defineProps<{
|
||||
config: MNode;
|
||||
}>();
|
||||
|
||||
const type = computed(() => {
|
||||
if (!props.config.type || ['page', 'container'].includes(props.config.type)) return 'div';
|
||||
return props.config.type;
|
||||
});
|
||||
|
||||
const id = computed(() => props.config.id);
|
||||
</script>
|
||||
```
|
||||
|
||||
接下来就需要解析节点的样式，在tmagic/editor中默认会将样式配置保存到节点的style属性中，如果自行定义到了其他属性，则已实际为准
|
||||
|
||||
解析style需要注意几个地方
|
||||
|
||||
1. 数字
|
||||
|
||||
css中的数值有些是需要单位的，例如px，有些是不需要的，例如opacity
|
||||
|
||||
在tmagic/editor中，默认都是不带单位的，所以需要将需要单位的地方补齐单位
|
||||
|
||||
这里做补齐px处理，如果需要做屏幕大小适应， 可以使用rem或者vw，这个可以根据自身需求处理。
|
||||
|
||||
2. url
|
||||
|
||||
css中的[url](https://developer.mozilla.org/zh-CN/docs/Web/CSS/url)需要是用url()，所以当值为url时，需要转为url(xxx)
|
||||
|
||||
3. transform
|
||||
|
||||
[transform](https://developer.mozilla.org/zh-CN/docs/Web/CSS/transform)属性可以指定为关键字值none 或一个或多个transform-function值。
|
||||
|
||||
```ts
|
||||
const fillBackgroundImage = (value: string) => {
|
||||
if (value && !/^url/.test(value) && !/^linear-gradient/.test(value)) {
|
||||
return `url(${value})`;
|
||||
}
|
||||
return value;
|
||||
};
|
||||
|
||||
const style = computed(() => {
|
||||
if (!props.config.style) {
|
||||
return {};
|
||||
}
|
||||
|
||||
const results: Record<string, any> = {};
|
||||
|
||||
const whiteList = ['zIndex', 'opacity', 'fontWeight'];
|
||||
Object.entries(props.config.style).forEach(([key, value]) => {
|
||||
if (key === 'backgroundImage') {
|
||||
value && (results[key] = fillBackgroundImage(value));
|
||||
} else if (key === 'transform' && typeof value !== 'string') {
|
||||
results[key] = Object.entries(value as Record<string, string>)
|
||||
.map(([transformKey, transformValue]) => {
|
||||
let defaultValue = 0;
|
||||
if (transformKey === 'scale') {
|
||||
defaultValue = 1;
|
||||
}
|
||||
return `${transformKey}(${transformValue || defaultValue})`;
|
||||
})
|
||||
.join(' ');
|
||||
} else if (!whiteList.includes(key) && value && /^[-]?[0-9]*[.]?[0-9]*$/.test(value)) {
|
||||
results[key] = `${value}px`;
|
||||
} else {
|
||||
results[key] = value;
|
||||
}
|
||||
});
|
||||
|
||||
return results;
|
||||
});
|
||||
```
|
||||
|
||||
### 渲染容器
|
||||
|
||||
容器与普通节点的区别，就是需要多一个items的解析
|
||||
|
||||
新增Container.vue文件
|
||||
|
||||
```vue
|
||||
<template>
|
||||
<Component :config="config">
|
||||
<Component v-for="item in config.items" :key="item.id" :config="item"></Component>
|
||||
</Component>
|
||||
</template>
|
||||
|
||||
<script lang="ts" setup>
|
||||
import type { MContainer } from '@tmagic/schema';
|
||||
|
||||
import Component from './Component.vue';
|
||||
|
||||
defineProps<{
|
||||
config: MContainer;
|
||||
}>();
|
||||
</script>
|
||||
```
|
||||
|
||||
### 渲染页面
|
||||
|
||||
页面就是容器，之所以单独存在，是页面会自己的方法，例如reload等
|
||||
|
||||
Page.vue文件
|
||||
|
||||
```vue
|
||||
<template>
|
||||
<Container :config="config"></Container>
|
||||
</template>
|
||||
|
||||
<script lang="ts" setup>
|
||||
import type { MPage } from '@tmagic/schema';
|
||||
|
||||
import Container from './Container.vue';
|
||||
|
||||
defineProps<{
|
||||
config: MPage;
|
||||
}>();
|
||||
|
||||
defineExpose({
|
||||
reload() {
|
||||
window.location.reload();
|
||||
}
|
||||
});
|
||||
</script>
|
||||
```
|
||||
|
||||
## 在runtime中使用 hello-ui
|
||||
|
||||
删除editor-runtime/src/ui-page.vue
|
||||
|
||||
将App.vue中的ui-page改成hello-ui中的Page
|
||||
|
||||
```vue
|
||||
<template>
|
||||
<Page v-if="page" :config="page" ref="pageComp"></Page>
|
||||
</template>
|
||||
|
||||
<script lang="ts" setup>
|
||||
// eslint-disable-next-line
|
||||
import { Page } from 'hello-ui';
|
||||
<script>
|
||||
```
|
||||
|
||||
在editor-runtime/vue.config.js中加上配置
|
||||
|
||||
```ts
|
||||
configureWebpack: {
|
||||
resolve: {
|
||||
alias: {
|
||||
'hello-ui': path.resolve(__dirname, '../hello-ui'),
|
||||
vue$: path.resolve(__dirname, './node_modules/vue'),
|
||||
},
|
||||
},
|
||||
},
|
||||
```
|
||||
|
||||
## 添加HelloWorld组件
|
||||
|
||||
在hello-ui下新增HelloWorld.vue
|
||||
|
||||
```vue
|
||||
<template>
|
||||
<div>hollo-world</div>
|
||||
</template>
|
||||
|
||||
<script lang="ts" setup>
|
||||
import type { MNode } from '@tmagic/schema';
|
||||
|
||||
defineProps<{
|
||||
config: MNode;
|
||||
}>();
|
||||
</script>
|
||||
```
|
||||
|
||||
在editor-runtime main.ts中注册HelloWorld
|
||||
|
||||
```ts
|
||||
import { createApp } from 'vue';
|
||||
|
||||
import type { Magic } from '@tmagic/stage';
|
||||
|
||||
// eslint-disable-next-line
|
||||
import { HelloWorld } from 'hello-ui';
|
||||
|
||||
import App from './App.vue';
|
||||
|
||||
declare global {
|
||||
interface Window {
|
||||
magic?: Magic;
|
||||
}
|
||||
}
|
||||
|
||||
const app = createApp(App);
|
||||
|
||||
app.component('hello-world', HelloWorld);
|
||||
|
||||
app.mount('#app');
|
||||
|
||||
```
|
||||
|
||||
[源码](https://github.com/jia000/tmagic-tutorial/tree/master/course3)
|
||||
@ -19,6 +19,12 @@ cd editor-runtime
|
||||
|
||||
删除src/components/HelloWorld.vue
|
||||
|
||||
按钮需要用的ts types依赖
|
||||
|
||||
```bash
|
||||
npm install --save @tmagic/schema @tmagic/stage
|
||||
```
|
||||
|
||||
## 实现runtime
|
||||
|
||||
将hello-editor中的render函数实现移植到runtime项目中
|
||||
@ -145,40 +151,58 @@ devServer: {
|
||||
|
||||
在App.vue中通过监听message，来准备获取magic注入时机，然后调用magic.onRuntimeReady，示例代码如下
|
||||
|
||||
> 这里可能会出现editor抛出message的时候，runtime还没有执行到监听message的情况
|
||||
> 编辑器只在iframe onload事件中抛出message
|
||||
> 如果出现runtime中接收不到message的情况，可以尝试在onMounted的时候调用magic.onRuntimeReady
|
||||
|
||||
```ts
|
||||
const root = ref();
|
||||
import type { Magic } from '@tmagic/stage';
|
||||
|
||||
declare global {
|
||||
interface Window {
|
||||
magic?: Magic;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
```ts
|
||||
import type { RemoveData, UpdateData } from '@tmagic/stage';
|
||||
import type { Id, MApp, MNode } from '@tmagic/schema';
|
||||
|
||||
const root = ref<MApp>();
|
||||
|
||||
window.addEventListener('message', ({ data }) => {
|
||||
if (!data.tmagicRuntimeReady) {
|
||||
return;
|
||||
}
|
||||
|
||||
(window as any).magic?.onRuntimeReady({
|
||||
window.magic?.onRuntimeReady({
|
||||
/** 当编辑器的dsl对象变化时会调用 */
|
||||
updateRootConfig(config: any) {
|
||||
updateRootConfig(config: MApp) {
|
||||
root.value = config;
|
||||
},
|
||||
|
||||
/** 当编辑器的切换页面时会调用 */
|
||||
updatePageId(id: string) {
|
||||
page.value = root.value?.items?.find((item: any) => item.id === id);
|
||||
updatePageId(id: Id) {
|
||||
page.value = root.value?.items?.find((item) => item.id === id);
|
||||
},
|
||||
|
||||
/** 新增组件时调用 */
|
||||
add({ config }: any) {
|
||||
add({ config }: UpdateData) {
|
||||
const parent = config.type === 'page' ? root.value : page.value;
|
||||
parent.items?.push(config);
|
||||
},
|
||||
|
||||
/** 更新组件时调用 */
|
||||
update({ config }: any) {
|
||||
const index = page.value.items?.findIndex((child: any) => child.id === config.id);
|
||||
update({ config }: UpdateData) {
|
||||
const index = page.value.items?.findIndex((child: MNode) => child.id === config.id);
|
||||
page.value.items.splice(index, 1, reactive(config));
|
||||
},
|
||||
|
||||
/** 删除组件时调用 */
|
||||
remove({ id }: any) {
|
||||
const index = page.value.items?.findIndex((child: any) => child.id === id);
|
||||
remove({ id }: RemoveData) {
|
||||
const index = page.value.items?.findIndex((child: MNode) => child.id === id);
|
||||
page.value.items.splice(index, 1);
|
||||
},
|
||||
});
|
||||
@ -194,11 +218,11 @@ window.addEventListener('message', ({ data }) => {
|
||||
watch(page, async () => {
|
||||
// page配置变化后，需要等dom更新
|
||||
await nextTick();
|
||||
(window as any).magic.onPageElUpdate(pageComp.value?.$el);
|
||||
window?.magic.onPageElUpdate(pageComp.value?.$el);
|
||||
});
|
||||
```
|
||||
|
||||
以上就是一个简单runtime实现，以及与编辑的交互，这是一个不完善的实现，但是其中已经几乎覆盖所有需要关心的内容
|
||||
以上就是一个简单runtime实现，以及与编辑的交互，这是一个不完善的实现(会发现组件再画布中无法自由拖动，是因为没有完整的解析style)，但是其中已经几乎覆盖所有需要关心的内容
|
||||
|
||||
当前教程中实现了一个简单的page，tmagic提供了一个比较完善的实现，将在下一节介绍
|
||||
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user