docs: 添加render教程

docs/src/.vuepress/config.ts

@@ -121,6 +121,7 @@ const sidebar = {
       children: [
         '/tutorial/hello-world',
         '/tutorial/runtime',
+        '/tutorial/render',
       ]
     },
   ]

docs/src/api/editor/editor.md

@@ -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

docs/src/guide/advanced/coupling.md

@@ -82,40 +82,26 @@ export default {
   </div>
 </template>
 
-<script lang="ts">
+<script lang="ts" setup>
 import { defineComponent, inject } from 'vue';
 
-export default defineComponent({
+const app: Core | undefined = inject('app');
-  name: 'magic-ui-test',
 
-  setup(props) {
+const onClick = () => {
-    const app: Core | undefined = inject('app');
+  // app.emit 第一个参数为事件名，其余参数为你要传给接受事件组件的参数
-    const hoc = inject('hoc');
+  app?.emit("yourComponent:finishSomething", /*可以传参给接收方*/);
+};
 
-    // 此处实现事件动作
+defineExport({
-    // 由于组件在 @tmagic/ui 中通过基础组件 Component 来封装，即每个组件其实都被 Component 包裹
+  // 此处实现事件动作
-    // 实际触发时，会触发到当前组件的直属父组件 Component 上，我们会 provide 这个父组件为高阶组件 hoc
+  // 实际触发时是调用vue实例上的方法，所以需要将改方法暴露到实例上
-    // 所以将 toast 方法挂载到当前组件的父组件上
+  toast: (/*接收触发事件组件传进来的参数*/) => {
-    hoc.toast = (/*接收触发事件组件传进来的参数*/) => {
+    toast('测试 vue3')
-      toast('测试 vue3')
+  }
-    };
-
-    return {
-      // 此处实现触发事件
-      onClick: () => {
-        // app.emit 第一个参数为事件名，其余参数为你要传给接受事件组件的参数
-        app?.emit("yourComponent:finishSomething", /*可以传参给接收方*/);
-      },
-    };
-  },
 });
 </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 等核心内容
+  // react 和 vue 实现不同，我们通过 useApp 这个 hook 来提供 app 等核心内容
-  // 其中 ref 需要绑定到你的组件上作为 ref。因为一些公共事件会需要使用到你的组件 dom
+  const { app } = useApp({
-  // 同时这个 ref 也会在tmagic-editor的高级函数钩子中，将你的组件 dom 作为参数提供给自定义钩子
-  const { app, ref } = 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}

docs/src/guide/introduction.md

@@ -39,7 +39,7 @@ tmagic-editor可视化开源项目是从魔方平台演化而来的开源项目
 - **runtime** 实现在编辑器中对使用不同框架的组件的渲染。
 - **page** 项目提供最终页面发布的执行环境与组件构建。
 
-可以查阅 Magic 的[源代码](https://github.com/Tencent/tmagic-editor)，与文档描述内容可以逐一对应上，希望文档内容可以为开发者带来比较好的开发体验。
+可以查阅 tmagic 的[源代码](https://github.com/Tencent/tmagic-editor)，与文档描述内容可以逐一对应上，希望文档内容可以为开发者带来比较好的开发体验。
 
 ## 谁在使用
 

docs/src/tutorial/hello-world.md

@@ -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.contentWindow?.magic?.onPageElUpdate(root);
-    renderer.iframe.contentWindow.magic?.onRuntimeReady({});
+    renderer.contentWindow?.magic?.onRuntimeReady({});
   });
 
   return root;

docs/src/tutorial/render.md

@@ -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)

docs/src/tutorial/runtime.md

@@ -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) {
+    updatePageId(id: Id) {
-      page.value = root.value?.items?.find((item: any) => item.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) {
+    update({ config }: UpdateData) {
-      const index = page.value.items?.findIndex((child: any) => child.id === config.id);
+      const index = page.value.items?.findIndex((child: MNode) => child.id === config.id);
       page.value.items.splice(index, 1, reactive(config));
     },
 
     /** 删除组件时调用 */
-    remove({ id }: any) {
+    remove({ id }: RemoveData) {
-      const index = page.value.items?.findIndex((child: any) => child.id === id);
+      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提供了一个比较完善的实现，将在下一节介绍