mirror of
https://github.com/Tencent/tmagic-editor.git
synced 2025-04-05 19:41:40 +08:00
docs: add docs
This commit is contained in:
roymondchen
parent
bc8b9f5225
commit
344a032ac3
@ -6,10 +6,14 @@ TMagic 可视化搭建平台。
|
||||
|
||||
# 文档
|
||||
|
||||
文档请移步
|
||||
文档请移步 https://tencent.github.io/tmagic-editor/docs/index.html
|
||||
|
||||
目前文档仍在逐步完善中，如有疑问欢迎给我们提 issue。
|
||||
|
||||
# Playground 体验
|
||||
|
||||
https://tencent.github.io/tmagic-editor/playground/index.html
|
||||
|
||||
## 环境准备
|
||||
|
||||
node.js > 14
|
||||
|
||||
3
docs/.gitignore
vendored
Normal file
3
docs/.gitignore
vendored
Normal file
@ -0,0 +1,3 @@
|
||||
node_modules
|
||||
.temp
|
||||
.cache
|
||||
2030
docs/package-lock.json
generated
Normal file
2030
docs/package-lock.json
generated
Normal file
File diff suppressed because it is too large
Load Diff
17
docs/package.json
Normal file
17
docs/package.json
Normal file
@ -0,0 +1,17 @@
|
||||
{
|
||||
"name": "docs",
|
||||
"private": true,
|
||||
"version": "0.0.0",
|
||||
"scripts": {
|
||||
"dev": "vuepress dev src",
|
||||
"build": "vuepress build src -d dist"
|
||||
},
|
||||
"dependencies": {
|
||||
"element-plus": "^2.0.2",
|
||||
"highlight.js": "^11.2.0"
|
||||
},
|
||||
"devDependencies": {
|
||||
"@vuepress/cli": "^2.0.0-beta.26",
|
||||
"vuepress": "^2.0.0-beta.26"
|
||||
}
|
||||
}
|
||||
13
docs/src/.vuepress/clientAppEnhance.ts
Normal file
13
docs/src/.vuepress/clientAppEnhance.ts
Normal file
@ -0,0 +1,13 @@
|
||||
import 'element-plus/dist/index.css';
|
||||
import 'highlight.js/styles/github.css';
|
||||
|
||||
import { defineClientAppEnhance } from '@vuepress/client';
|
||||
import ElementPlus from 'element-plus';
|
||||
import MagicForm from '@tmagic/form';
|
||||
import DemoBlock from './demo-block.vue';
|
||||
|
||||
export default defineClientAppEnhance(({ app }) => {
|
||||
app.use(ElementPlus);
|
||||
app.use(MagicForm);
|
||||
app.component('demo-block', DemoBlock);
|
||||
});
|
||||
144
docs/src/.vuepress/config.ts
Normal file
144
docs/src/.vuepress/config.ts
Normal file
@ -0,0 +1,144 @@
|
||||
import { defineUserConfig } from '@vuepress/cli'
|
||||
import type { DefaultThemeOptions } from '@vuepress/theme-default'
|
||||
import path from 'path';
|
||||
|
||||
const sidebar = {
|
||||
guide: [
|
||||
{
|
||||
text: '使用指南',
|
||||
children: [
|
||||
'/guide/introduction',
|
||||
'/guide/installation',
|
||||
'/guide/conception',
|
||||
]
|
||||
}, {
|
||||
text: '进阶指南',
|
||||
children: [
|
||||
'/guide/advanced/js-schema.md',
|
||||
'/guide/advanced/layout.md',
|
||||
'/guide/advanced/page.md',
|
||||
'/guide/advanced/high-level-function.md',
|
||||
'/guide/advanced/magic-ui.md',
|
||||
'/guide/advanced/magic-form.md',
|
||||
'/guide/advanced/coupling.md',
|
||||
]
|
||||
}
|
||||
],
|
||||
page: [
|
||||
{
|
||||
text: '页面发布',
|
||||
sidebarDepth: 2,
|
||||
children: [
|
||||
'/page/introduction',
|
||||
'/page/advanced',
|
||||
]
|
||||
}
|
||||
],
|
||||
component: [
|
||||
{
|
||||
text: '组件开发',
|
||||
children: [
|
||||
'/component/introduction',
|
||||
]
|
||||
}
|
||||
],
|
||||
api: [
|
||||
{
|
||||
text: '编辑器',
|
||||
children: [
|
||||
'/api/editor',
|
||||
'/api/model',
|
||||
]
|
||||
},
|
||||
{
|
||||
text: '表单',
|
||||
children: [
|
||||
'/api/form',
|
||||
]
|
||||
},
|
||||
{
|
||||
text: '表单配置协议',
|
||||
children: [
|
||||
'/api/base-config',
|
||||
'/api/field-config',
|
||||
]
|
||||
}
|
||||
]
|
||||
};
|
||||
|
||||
export default defineUserConfig<DefaultThemeOptions>({
|
||||
title: '魔方',
|
||||
description: 'magic',
|
||||
clientAppEnhanceFiles: path.resolve(__dirname, './clientAppEnhance.ts'),
|
||||
themeConfig: {
|
||||
logo: 'https://vfiles.gtimg.cn/vupload/20210811/388ed01628667545737.png',
|
||||
navbar: [
|
||||
{
|
||||
text: '文档',
|
||||
children: [
|
||||
{
|
||||
text: '使用指南',
|
||||
link: '/guide/introduction'
|
||||
},
|
||||
{
|
||||
text: '组件开发',
|
||||
link: '/component/introduction'
|
||||
},
|
||||
{
|
||||
text: '页面发布',
|
||||
link: '/page/introduction'
|
||||
},
|
||||
]
|
||||
},
|
||||
{
|
||||
text: 'API参考',
|
||||
link: '/api/editor'
|
||||
}, {
|
||||
text: '查看源码',
|
||||
link: 'https://github.com/Tencent/tmagic-editor'
|
||||
}, {
|
||||
text: 'Playground',
|
||||
link: 'https://tencent.github.io/tmagic-editor/playground/index.html'
|
||||
}
|
||||
],
|
||||
docsDir: 'src',
|
||||
sidebarDepth: 2,
|
||||
sidebar: {
|
||||
'/guide/': sidebar.guide,
|
||||
'/page/': sidebar.page,
|
||||
'/component/': sidebar.component,
|
||||
'/api/': sidebar.api,
|
||||
},
|
||||
smoothScroll: false,
|
||||
lastUpdated: false,
|
||||
contributors: false,
|
||||
|
||||
},
|
||||
base: '/tmagic-editor/docs/',
|
||||
bundlerConfig: {
|
||||
vuePluginOptions: {
|
||||
template: {
|
||||
ssr: true,
|
||||
compilerOptions: {
|
||||
directiveTransforms: {
|
||||
loading: () => {
|
||||
return {
|
||||
props: [],
|
||||
needRuntime: true,
|
||||
};
|
||||
},
|
||||
},
|
||||
},
|
||||
},
|
||||
},
|
||||
viteOptions: {
|
||||
resolve: {
|
||||
alias:[
|
||||
{ find: /^@tmagic\/form/, replacement: path.join(__dirname, '../../../packages/form/src/index.ts') },
|
||||
{ find: /^@tmagic\/form/, replacement: path.join(__dirname, '../../../packages/form/src/index.ts') },
|
||||
{ find: /^@tmagic\/utils/, replacement: path.join(__dirname, '../../../packages/utils/src/index.ts') },
|
||||
]
|
||||
},
|
||||
},
|
||||
},
|
||||
});
|
||||
360
docs/src/.vuepress/demo-block.vue
Normal file
360
docs/src/.vuepress/demo-block.vue
Normal file
@ -0,0 +1,360 @@
|
||||
<template>
|
||||
<div
|
||||
class="demo-block"
|
||||
:class="[blockClass, { hover: hovering }]"
|
||||
@mouseenter="hovering = true"
|
||||
@mouseleave="hovering = false"
|
||||
>
|
||||
<div class="source">
|
||||
<slot name="source"></slot>
|
||||
<m-form ref="form" :config="formConfig" :init-values="{}"></m-form>
|
||||
</div>
|
||||
<div class="meta" ref="meta">
|
||||
<div class="description">
|
||||
<pre><code lass="language-javascript hljs" v-html="text"></code></pre>
|
||||
</div>
|
||||
<div class="highlight">
|
||||
<slot name="highlight"></slot>
|
||||
</div>
|
||||
</div>
|
||||
<div
|
||||
class="demo-block-control"
|
||||
ref="control"
|
||||
:class="{ 'is-fixed': fixedControl }"
|
||||
@click="isExpanded = !isExpanded"
|
||||
>
|
||||
<transition name="arrow-slide">
|
||||
<i :class="[iconClass, { hovering: hovering }]"></i>
|
||||
</transition>
|
||||
<transition name="text-slide">
|
||||
<span v-show="hovering">{{ controlText }}</span>
|
||||
</transition>
|
||||
<el-tooltip effect="dark" :content="'前往 codepen.io 运行此示例'" placement="right">
|
||||
<transition name="text-slide">
|
||||
<el-button
|
||||
v-show="hovering || isExpanded"
|
||||
size="small"
|
||||
type="text"
|
||||
class="control-button"
|
||||
@click.stop="goCodepen"
|
||||
>
|
||||
{{type === 'form' ? '查看结果' : '在线运行'}}
|
||||
</el-button>
|
||||
</transition>
|
||||
</el-tooltip>
|
||||
</div>
|
||||
|
||||
<el-dialog
|
||||
v-model="resultVisible"
|
||||
title="result"
|
||||
>
|
||||
<pre><code class="language-javascript hljs" v-html="result"></code></pre>
|
||||
</el-dialog>
|
||||
</div>
|
||||
</template>
|
||||
|
||||
<style lang="scss">
|
||||
.demo-block {
|
||||
margin: 10px 0;
|
||||
border: solid 1px #ebebeb;
|
||||
border-radius: 3px;
|
||||
transition: 0.2s;
|
||||
|
||||
&.hover {
|
||||
box-shadow: 0 0 8px 0 rgba(232, 237, 250, 0.6), 0 2px 4px 0 rgba(232, 237, 250, 0.5);
|
||||
}
|
||||
|
||||
code {
|
||||
font-family: Menlo, Monaco, Consolas, Courier, monospace;
|
||||
}
|
||||
|
||||
.demo-button {
|
||||
float: right;
|
||||
}
|
||||
|
||||
.source {
|
||||
padding: 24px;
|
||||
|
||||
p {
|
||||
font-size: 14px;
|
||||
color: rgb(94, 109, 130);
|
||||
line-height: 1.5em;
|
||||
}
|
||||
}
|
||||
|
||||
.meta {
|
||||
background-color: #fafafa;
|
||||
border-top: solid 1px #eaeefb;
|
||||
overflow: hidden;
|
||||
height: 0;
|
||||
transition: height 0.2s;
|
||||
}
|
||||
|
||||
.el-dialog {
|
||||
background-color: #fff;
|
||||
color: #666;
|
||||
|
||||
code {
|
||||
color: #5e6d82;
|
||||
}
|
||||
}
|
||||
|
||||
.description {
|
||||
box-sizing: border-box;
|
||||
border: solid 1px #ebebeb;
|
||||
border-radius: 3px;
|
||||
font-size: 14px;
|
||||
color: #666;
|
||||
word-break: break-word;
|
||||
margin: 10px;
|
||||
background-color: #fff;
|
||||
|
||||
p {
|
||||
margin: 0;
|
||||
line-height: 26px;
|
||||
}
|
||||
|
||||
code {
|
||||
color: #5e6d82;
|
||||
}
|
||||
}
|
||||
|
||||
.highlight {
|
||||
pre {
|
||||
margin: 0;
|
||||
}
|
||||
|
||||
code.hljs {
|
||||
margin: 0;
|
||||
border: none;
|
||||
max-height: none;
|
||||
border-radius: 0;
|
||||
|
||||
&::before {
|
||||
content: none;
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
.demo-block-control {
|
||||
border-top: solid 1px #eaeefb;
|
||||
height: 44px;
|
||||
box-sizing: border-box;
|
||||
background-color: #fff;
|
||||
border-bottom-left-radius: 4px;
|
||||
border-bottom-right-radius: 4px;
|
||||
text-align: center;
|
||||
margin-top: -1px;
|
||||
color: #d3dce6;
|
||||
cursor: pointer;
|
||||
position: relative;
|
||||
|
||||
&.is-fixed {
|
||||
position: fixed;
|
||||
bottom: 0;
|
||||
width: 868px;
|
||||
}
|
||||
|
||||
i {
|
||||
font-size: 16px;
|
||||
line-height: 44px;
|
||||
transition: 0.3s;
|
||||
&.hovering {
|
||||
transform: translateX(-40px);
|
||||
}
|
||||
}
|
||||
|
||||
> span {
|
||||
position: absolute;
|
||||
transform: translateX(-30px);
|
||||
font-size: 14px;
|
||||
line-height: 44px;
|
||||
transition: 0.3s;
|
||||
display: inline-block;
|
||||
}
|
||||
|
||||
&:hover {
|
||||
color: #409eff;
|
||||
background-color: #f9fafc;
|
||||
}
|
||||
|
||||
& .text-slide-enter,
|
||||
& .text-slide-leave-active {
|
||||
opacity: 0;
|
||||
transform: translateX(10px);
|
||||
}
|
||||
|
||||
.control-button {
|
||||
line-height: 26px;
|
||||
position: absolute;
|
||||
top: 0;
|
||||
right: 0;
|
||||
font-size: 14px;
|
||||
padding-left: 5px;
|
||||
padding-right: 25px;
|
||||
}
|
||||
}
|
||||
}
|
||||
</style>
|
||||
|
||||
<script type="text/babel" lang="ts">
|
||||
import hljs from 'highlight.js';
|
||||
|
||||
export function stripScript(content) {
|
||||
const result = content.match(/<(script)>([\s\S]+)<\/\1>/);
|
||||
return result && result[2] ? result[2].trim() : '';
|
||||
}
|
||||
|
||||
export function stripStyle(content) {
|
||||
const result = content.match(/<(style)\s*>([\s\S]+)<\/\1>/);
|
||||
return result && result[2] ? result[2].trim() : '';
|
||||
}
|
||||
|
||||
export function stripTemplate(content) {
|
||||
content = content.trim();
|
||||
if (!content) {
|
||||
return content;
|
||||
}
|
||||
return content.replace(/<(script|style)[\s\S]+<\/\1>/g, '').trim();
|
||||
}
|
||||
|
||||
export default {
|
||||
props: [
|
||||
'type', 'config'
|
||||
],
|
||||
|
||||
data() {
|
||||
return {
|
||||
codepen: {
|
||||
script: '',
|
||||
html: '',
|
||||
style: '',
|
||||
},
|
||||
hovering: false,
|
||||
isExpanded: false,
|
||||
fixedControl: false,
|
||||
scrollParent: null,
|
||||
resultVisible: false,
|
||||
result: {},
|
||||
};
|
||||
},
|
||||
|
||||
methods: {
|
||||
async goCodepen() {
|
||||
if (this.type === 'form') {
|
||||
this.resultVisible = true;
|
||||
const values = await this.$refs.form.submitForm();
|
||||
this.result = hljs.highlight('json', JSON.stringify(values, null, 2)).value;
|
||||
}
|
||||
},
|
||||
|
||||
scrollHandler() {
|
||||
const { top, bottom, left } = this.$refs.meta.getBoundingClientRect();
|
||||
this.fixedControl =
|
||||
bottom > document.documentElement.clientHeight && top + 44 <= document.documentElement.clientHeight;
|
||||
this.$refs.control.style.left = this.fixedControl ? `${left}px` : '0';
|
||||
},
|
||||
|
||||
removeScrollHandler() {
|
||||
this.scrollParent && this.scrollParent.removeEventListener('scroll', this.scrollHandler);
|
||||
},
|
||||
},
|
||||
|
||||
computed: {
|
||||
lang() {
|
||||
return 'zh-CN';
|
||||
},
|
||||
|
||||
blockClass() {
|
||||
return `demo-${this.lang}}`;
|
||||
},
|
||||
|
||||
iconClass() {
|
||||
return this.isExpanded ? 'el-icon-caret-top' : 'el-icon-caret-bottom';
|
||||
},
|
||||
|
||||
controlText() {
|
||||
return this.isExpanded ? '隐藏配置' : '显示配置';
|
||||
},
|
||||
|
||||
codeArea() {
|
||||
return this.$el.getElementsByClassName('meta')[0];
|
||||
},
|
||||
|
||||
codeAreaHeight() {
|
||||
if (this.$el.getElementsByClassName('description').length > 0) {
|
||||
return (
|
||||
this.$el.getElementsByClassName('description')[0].clientHeight +
|
||||
this.$el.getElementsByClassName('highlight')[0].clientHeight +
|
||||
20
|
||||
);
|
||||
}
|
||||
return this.$el.getElementsByClassName('highlight')[0].clientHeight;
|
||||
},
|
||||
|
||||
text() {
|
||||
return this.isStringConfig ?
|
||||
hljs.highlight('js', this.config).value :
|
||||
hljs.highlight('json', JSON.stringify(this.config, null, 2)).value;
|
||||
},
|
||||
|
||||
formConfig() {
|
||||
return this.isStringConfig ? eval(this.config) : this.config;
|
||||
},
|
||||
|
||||
isStringConfig() {
|
||||
return typeof this.config === 'string';
|
||||
}
|
||||
},
|
||||
|
||||
watch: {
|
||||
isExpanded(val) {
|
||||
this.codeArea.style.height = val ? `${this.codeAreaHeight + 1}px` : '0';
|
||||
if (!val) {
|
||||
this.fixedControl = false;
|
||||
this.$refs.control.style.left = '0';
|
||||
this.removeScrollHandler();
|
||||
return;
|
||||
}
|
||||
setTimeout(() => {
|
||||
this.scrollParent = document.querySelector('.page-component__scroll > .el-scrollbar__wrap');
|
||||
this.scrollParent && this.scrollParent.addEventListener('scroll', this.scrollHandler);
|
||||
this.scrollHandler();
|
||||
}, 200);
|
||||
},
|
||||
},
|
||||
|
||||
created() {
|
||||
const { highlight } = this.$slots;
|
||||
if (highlight && highlight[0]) {
|
||||
let code = '';
|
||||
let cur = highlight[0];
|
||||
if (cur.tag === 'pre' && cur.children && cur.children[0]) {
|
||||
cur = cur.children[0];
|
||||
if (cur.tag === 'code') {
|
||||
code = cur.children[0].text;
|
||||
}
|
||||
}
|
||||
if (code) {
|
||||
this.codepen.html = stripTemplate(code);
|
||||
this.codepen.script = stripScript(code);
|
||||
this.codepen.style = stripStyle(code);
|
||||
}
|
||||
}
|
||||
},
|
||||
|
||||
mounted() {
|
||||
this.$nextTick(() => {
|
||||
const highlight = this.$el.getElementsByClassName('highlight')[0];
|
||||
if (this.$el.getElementsByClassName('description').length === 0) {
|
||||
highlight.style.width = '100%';
|
||||
highlight.borderRight = 'none';
|
||||
}
|
||||
});
|
||||
},
|
||||
|
||||
beforeDestroy() {
|
||||
this.removeScrollHandler();
|
||||
},
|
||||
};
|
||||
</script>
|
||||
3
docs/src/.vuepress/styles/index.scss
Normal file
3
docs/src/.vuepress/styles/index.scss
Normal file
@ -0,0 +1,3 @@
|
||||
:root {
|
||||
--c-brand: #2882e0;
|
||||
}
|
||||
22
docs/src/README.md
Normal file
22
docs/src/README.md
Normal file
@ -0,0 +1,22 @@
|
||||
---
|
||||
home: true
|
||||
heroImage: https://vfiles.gtimg.cn/vupload/20210811/388ed01628667545737.png
|
||||
heroText: 魔方页面可视化平台
|
||||
tagline: null
|
||||
|
||||
features:
|
||||
- title: 所见即所得
|
||||
details: 体验友好的拖拽编辑方式。
|
||||
- title: 丰富的拓展能力
|
||||
details: 支持业务方自定义组件、插件。
|
||||
- title: 支持多种布局方式
|
||||
details: 魔方的容器概念，支持配置活动时，自由组合嵌套业务组件，提供超强的组件布局方式。
|
||||
- title: 强大的配置
|
||||
details: 支持表单联动等配置能力。
|
||||
- title: 组件联动
|
||||
details: 支持组件通信、组件联动，允许页面内各组件提供丰富配置能力。
|
||||
- title: 低代码
|
||||
details: 支持在平台写入代码，修改页面样式属性等，提供除组件外的高级编码能力。
|
||||
|
||||
footer: Powered by 腾讯视频会员平台技术中心
|
||||
---
|
||||
179
docs/src/api/base-config.md
Normal file
179
docs/src/api/base-config.md
Normal file
@ -0,0 +1,179 @@
|
||||
# 布局
|
||||
|
||||
## 基础用法
|
||||
|
||||
<demo-block type="form" :config="[{
|
||||
name: 'text',
|
||||
text: '配置1',
|
||||
}, {
|
||||
name: 'text2',
|
||||
text: '配置2',
|
||||
}, {
|
||||
name: 'text3',
|
||||
text: '配置3',
|
||||
}]"></demo-block>
|
||||
|
||||
## 行内布局
|
||||
|
||||
可以通过配置span，来指定行内的配置项占用多少位置，一行为24，例如一行要显示三个配置则 span 可以配置 8；四个则为 6。默认会自动调节在一行中显示。
|
||||
|
||||
<demo-block type="form" :config="[{
|
||||
type: 'row',
|
||||
labelWidth: 100,
|
||||
items: [{
|
||||
name: 'text',
|
||||
text: '配置1',
|
||||
}, {
|
||||
name: 'text2',
|
||||
text: '配置2',
|
||||
}, {
|
||||
name: 'text3',
|
||||
text: '配置3',
|
||||
}]
|
||||
}, {
|
||||
type: 'row',
|
||||
span: 12,
|
||||
labelWidth: 100,
|
||||
items: [{
|
||||
name: 'text4',
|
||||
text: '配置1',
|
||||
}, {
|
||||
name: 'text5',
|
||||
text: '配置2',
|
||||
}, {
|
||||
name: 'text6',
|
||||
text: '配置3',
|
||||
}]
|
||||
}]"></demo-block>
|
||||
|
||||
## 混合布局
|
||||
|
||||
<demo-block type="form" :config="[{
|
||||
name: 'text0',
|
||||
labelWidth: 100,
|
||||
text: '配置0',
|
||||
}, {
|
||||
type: 'row',
|
||||
labelWidth: 100,
|
||||
items: [{
|
||||
name: 'text',
|
||||
text: '配置1',
|
||||
}, {
|
||||
name: 'text2',
|
||||
text: '配置2',
|
||||
}, {
|
||||
name: 'text3',
|
||||
text: '配置3',
|
||||
}]
|
||||
}]"></demo-block>
|
||||
|
||||
## 对象容器
|
||||
|
||||
### Object
|
||||
|
||||
<demo-block type="form" :config="[{
|
||||
name: 'data',
|
||||
items: [{
|
||||
name: 'text2',
|
||||
text: '配置2',
|
||||
}, {
|
||||
name: 'text3',
|
||||
text: '配置3',
|
||||
}]
|
||||
}]"></demo-block>
|
||||
|
||||
### fieldset
|
||||
|
||||
<demo-block type="form" :config="[{
|
||||
type: 'fieldset',
|
||||
labelWidth: 100,
|
||||
legend: 'fieldset',
|
||||
items: [{
|
||||
name: 'text',
|
||||
text: '配置1',
|
||||
}, {
|
||||
type: 'row',
|
||||
items: [{
|
||||
name: 'text2',
|
||||
text: '配置2',
|
||||
}, {
|
||||
name: 'text3',
|
||||
text: '配置3',
|
||||
}]
|
||||
}]
|
||||
}]"></demo-block>
|
||||
|
||||
### panel
|
||||
|
||||
<demo-block type="form" :config="[{
|
||||
type: 'panel',
|
||||
title: 'panel',
|
||||
items: [{
|
||||
name: 'text',
|
||||
text: '配置1',
|
||||
}, {
|
||||
type: 'row',
|
||||
items: [{
|
||||
name: 'text2',
|
||||
text: '配置2',
|
||||
}, {
|
||||
name: 'text3',
|
||||
text: '配置3',
|
||||
}]
|
||||
}]
|
||||
}]"></demo-block>
|
||||
|
||||
### tabs
|
||||
|
||||
<demo-block type="form" :config="[{
|
||||
type: 'tab',
|
||||
items: [{
|
||||
title: 'tab1',
|
||||
items: [{
|
||||
name: 'text',
|
||||
text: '配置1',
|
||||
}]
|
||||
}, {
|
||||
title: 'tab2',
|
||||
items: [{
|
||||
name: 'text2',
|
||||
text: '配置2',
|
||||
}, {
|
||||
name: 'text3',
|
||||
text: '配置3',
|
||||
}]
|
||||
}]
|
||||
}]"></demo-block>
|
||||
|
||||
## 数组容器
|
||||
|
||||
### groupList
|
||||
|
||||
<demo-block type="form" :config="[{
|
||||
type: 'groupList',
|
||||
name: 'group',
|
||||
items: [{
|
||||
name: 'text',
|
||||
text: '配置1',
|
||||
}, {
|
||||
type: 'row',
|
||||
items: [{
|
||||
name: 'text2',
|
||||
text: '配置2',
|
||||
}, {
|
||||
name: 'text3',
|
||||
text: '配置3',
|
||||
}]
|
||||
}]
|
||||
}]"></demo-block>
|
||||
|
||||
### table
|
||||
|
||||
<demo-block type="form" :config="[{
|
||||
type: 'table',
|
||||
name: 'table',
|
||||
items: [{
|
||||
name: 'text',
|
||||
label: '配置1',
|
||||
}]
|
||||
}]"></demo-block>
|
||||
294
docs/src/api/editor.md
Normal file
294
docs/src/api/editor.md
Normal file
@ -0,0 +1,294 @@
|
||||
# m-editor
|
||||
|
||||
## props
|
||||
|
||||
### data
|
||||
|
||||
- **类型：** MApp(https://github.com/Tencent/tmagic-editor/blob/master/packages/schema/src/index.ts)[]
|
||||
|
||||
- **默认值：** {}
|
||||
|
||||
- **详情：**
|
||||
|
||||
页面初始值
|
||||
|
||||
- **示例：**
|
||||
|
||||
```js
|
||||
{
|
||||
type: 'app',
|
||||
id: 'app_1',
|
||||
items: [
|
||||
{
|
||||
type: 'page',
|
||||
id: 'page_1',
|
||||
items: [
|
||||
{
|
||||
type: 'text',
|
||||
id: 'text_1',
|
||||
text: '文本'
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### componentGroupList
|
||||
|
||||
- **类型：** [ComponentGroup](https://github.com/Tencent/tmagic-editor/blob/master/packages/editor/src/type.ts)[]
|
||||
|
||||
- **默认值：** []
|
||||
|
||||
- **详情：**
|
||||
|
||||
左侧面板中的组件列表
|
||||
|
||||
- **示例：**
|
||||
|
||||
```js
|
||||
[
|
||||
{
|
||||
title: '容器',
|
||||
items: [
|
||||
{
|
||||
icon: 'folder-opened',
|
||||
text: '组',
|
||||
type: 'container',
|
||||
},
|
||||
{
|
||||
icon: 'el-icon-files',
|
||||
text: '标签页(tab)',
|
||||
type: 'tabs',
|
||||
},
|
||||
],
|
||||
},
|
||||
{
|
||||
title: '基础组件',
|
||||
items: [
|
||||
{
|
||||
icon: 'tickets',
|
||||
text: '文本',
|
||||
type: 'text',
|
||||
},
|
||||
{
|
||||
icon: 'switch-button',
|
||||
text: '按钮',
|
||||
type: 'button',
|
||||
},
|
||||
],
|
||||
},
|
||||
]
|
||||
```
|
||||
|
||||
::: tip
|
||||
icon使用的是[element-plus icon](https://element-plus.org/zh-CN/component/icon.html)
|
||||
:::
|
||||
|
||||
::: warning
|
||||
此配置仅在[sidebar](#sidebar)中配置了'component-list'时有效
|
||||
:::
|
||||
|
||||
### sidebar
|
||||
|
||||
- **类型：** [SideBarData](https://github.com/Tencent/tmagic-editor/blob/master/packages/editor/src/type.ts)
|
||||
|
||||
- **默认值：** { type: 'tabs', status: '组件', items: ['component-list', 'layer'] }
|
||||
|
||||
- **详情：**
|
||||
|
||||
左侧面板，目前只支持type: 'tabs';
|
||||
|
||||
component-list的text为'组件'
|
||||
|
||||
- **示例：**
|
||||
|
||||
```js
|
||||
import ModListPanel from '../components/sidebars/ModListPanel.vue';
|
||||
|
||||
{
|
||||
type: 'tabs',
|
||||
status: '组件',
|
||||
items: [
|
||||
'component-list',
|
||||
'layer',
|
||||
{
|
||||
type: 'component',
|
||||
icon: 'el-icon-s-order',
|
||||
component: ModListPanel,
|
||||
text: '模块',
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
### menu
|
||||
|
||||
- **类型：** [MenuBarData](https://github.com/Tencent/tmagic-editor/blob/master/packages/editor/src/type.ts)
|
||||
|
||||
- **默认值：** { left: [], center: [], right: [] }
|
||||
|
||||
- **详情：**
|
||||
|
||||
顶部工具栏
|
||||
|
||||
系统提供了几个常用功能： '/' | 'delete' | 'undo' | 'redo' | 'zoom-in' | 'zoom-out'
|
||||
|
||||
'/': 分隔符
|
||||
|
||||
'delete': 删除按钮
|
||||
|
||||
'undo': 撤销按钮
|
||||
|
||||
'redo': 恢复按钮
|
||||
|
||||
'zoom-in': 放大按钮
|
||||
|
||||
'zoom-out': 缩小按钮
|
||||
|
||||
- **示例：**
|
||||
|
||||
```js
|
||||
{
|
||||
left: [
|
||||
{
|
||||
type: 'button',
|
||||
icon: 'el-icon-arrow-left',
|
||||
tooltip: '返回',
|
||||
},
|
||||
'/',
|
||||
{
|
||||
type: 'text',
|
||||
text: '魔方',
|
||||
},
|
||||
],
|
||||
center: ['delete', 'undo', 'redo', 'zoom-in', 'zoom-out'],
|
||||
right: [
|
||||
{
|
||||
type: 'button',
|
||||
text: '保存',
|
||||
icon: 'el-icon-coin',
|
||||
disabled: true,
|
||||
handler: ({ store }) => console.log(toRaw(store.get('root'))),
|
||||
},
|
||||
],
|
||||
}
|
||||
```
|
||||
|
||||
### render
|
||||
|
||||
- **类型：** Function
|
||||
|
||||
- **默认值：** undefined
|
||||
|
||||
- **详情：**
|
||||
|
||||
中间工作区域中画布渲染的内容
|
||||
|
||||
- **示例：**
|
||||
|
||||
```js
|
||||
(renderer) => renderer.contentWindow.document.createElement('div')
|
||||
```
|
||||
|
||||
### runtimeUrl
|
||||
|
||||
- **类型：** string
|
||||
|
||||
- **默认值：** undefined
|
||||
|
||||
- **详情：**
|
||||
|
||||
中间工作区域中画布通过iframe渲染时的页面url
|
||||
|
||||
### propsConfigs
|
||||
|
||||
- **类型：** { [type: string]: [FormConfig](https://github.com/Tencent/tmagic-editor/blob/master/packages/form/src/schema.ts) }
|
||||
|
||||
- **默认值：** {}
|
||||
|
||||
- **详情：**
|
||||
|
||||
组件的属性配置表单的dsl
|
||||
|
||||
- **示例：**
|
||||
|
||||
```js
|
||||
{
|
||||
text: [
|
||||
{
|
||||
name: 'text',
|
||||
text: '文本',
|
||||
},
|
||||
{
|
||||
name: 'multiple',
|
||||
text: '多行文本',
|
||||
type: 'switch',
|
||||
},
|
||||
],
|
||||
button: [
|
||||
{
|
||||
name: 'text',
|
||||
text: '文本',
|
||||
},
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### propsValues
|
||||
|
||||
- **类型：** { [type: string]: Object }
|
||||
|
||||
- **默认值：** {}
|
||||
|
||||
- **详情：**
|
||||
|
||||
添加组件时的默认值
|
||||
|
||||
- **示例：**
|
||||
|
||||
```js
|
||||
{
|
||||
text: {
|
||||
text: '文本',
|
||||
multiple: true,
|
||||
},
|
||||
button: {
|
||||
text: '按钮',
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
### moveableOptions
|
||||
|
||||
- **类型：** ((core: StageCore) => MoveableOptions) | [MoveableOptions](https://daybrush.com/moveable/release/latest/doc/)
|
||||
|
||||
- **默认值：** {}
|
||||
|
||||
- **详情：**
|
||||
|
||||
画布中的选中框配置选项，使用的是[moveable](https://github.com/daybrush/moveable)第三方库
|
||||
## slots
|
||||
|
||||
### nav
|
||||
|
||||
- **详情：** 工具栏
|
||||
|
||||
### sidebar
|
||||
|
||||
- **详情：** 左侧栏
|
||||
|
||||
### workspace
|
||||
|
||||
- **详情：** 中间工作区域
|
||||
|
||||
### workspace-content
|
||||
|
||||
- **详情：** 中间工作区域内部
|
||||
|
||||
:::tip
|
||||
在没有 workspace slots 的时候才可以用
|
||||
:::
|
||||
|
||||
### propsPanel
|
||||
|
||||
- **详情：** 属性面板
|
||||
1222
docs/src/api/field-config.md
Normal file
1222
docs/src/api/field-config.md
Normal file
File diff suppressed because it is too large
Load Diff
163
docs/src/api/form.md
Normal file
163
docs/src/api/form.md
Normal file
@ -0,0 +1,163 @@
|
||||
# m-form
|
||||
|
||||
## props
|
||||
|
||||
### initValues
|
||||
|
||||
- **类型：** Object
|
||||
|
||||
- **默认值：** {}
|
||||
|
||||
- **详情：**
|
||||
|
||||
表单初始化值
|
||||
|
||||
- **示例：**
|
||||
|
||||
```js
|
||||
{
|
||||
text: 'text',
|
||||
multiple: true,
|
||||
}
|
||||
```
|
||||
|
||||
:::tip
|
||||
initValues应该是与config一一对应的，如果initValues中的key没有出现在config的name中，那么这个值将被丢掉
|
||||
:::
|
||||
|
||||
### config
|
||||
|
||||
- **类型：** [FormConfig](https://github.com/Tencent/tmagic-editor/blob/master/packages/form/src/schema.ts)
|
||||
|
||||
- **默认值：** []
|
||||
|
||||
- **详情：**
|
||||
|
||||
表单配置
|
||||
|
||||
- **示例：**
|
||||
|
||||
```js
|
||||
[
|
||||
{
|
||||
name: 'text',
|
||||
text: '文本',
|
||||
},
|
||||
{
|
||||
name: 'multiple',
|
||||
text: '多行文本',
|
||||
type: 'switch',
|
||||
},
|
||||
]
|
||||
```
|
||||
|
||||
### labelWidth
|
||||
|
||||
- **类型：** string | number
|
||||
|
||||
- **默认值：** '200px'
|
||||
|
||||
- **详情：**
|
||||
|
||||
表单域标签的宽度，例如 '50px'。 作为 Form 直接子元素的 form-item 会继承该值。 支持 auto
|
||||
|
||||
### disabled
|
||||
|
||||
- **类型：** boolean
|
||||
|
||||
- **默认值：** false
|
||||
|
||||
- **详情：**
|
||||
|
||||
是否禁用该表单内的所有组件。 若设置为 true，则表单内组件上的 disabled 属性不再生效
|
||||
|
||||
- **示例：**
|
||||
|
||||
### height
|
||||
|
||||
- **类型：** string
|
||||
|
||||
- **默认值：** 'auto'
|
||||
|
||||
- **详情：**
|
||||
|
||||
表单高度
|
||||
|
||||
### stepActive
|
||||
|
||||
- **类型：** string | number
|
||||
|
||||
- **默认值：** 1
|
||||
|
||||
- **详情：**
|
||||
|
||||
使用了 step 组件时，默认的选中的步骤数
|
||||
|
||||
### size
|
||||
|
||||
- **类型：** 'medium' | 'small' | 'mini'
|
||||
|
||||
- **默认值：** 'small'
|
||||
|
||||
- **详情：**
|
||||
|
||||
用于控制该表单内组件的尺寸
|
||||
|
||||
### inline
|
||||
|
||||
- **类型：** boolean
|
||||
|
||||
- **默认值：** false
|
||||
|
||||
- **详情：**
|
||||
|
||||
行内表单模式
|
||||
|
||||
### labelPosition
|
||||
|
||||
- **类型：** 'right' | 'left' | 'top'
|
||||
|
||||
- **默认值：** 'right'
|
||||
|
||||
- **详情：**
|
||||
|
||||
表单域标签的位置， 如果值为 left 或者 right 时，则需要设置 label-width
|
||||
|
||||
### keyProp
|
||||
|
||||
- **类型：** string
|
||||
|
||||
- **默认值：** '__key'
|
||||
|
||||
- **详情：**
|
||||
|
||||
作为表单项的组件实例的key
|
||||
|
||||
- **示例：**
|
||||
|
||||
```js
|
||||
[
|
||||
{
|
||||
name: 'text',
|
||||
type: 'text',
|
||||
text: '文本',
|
||||
__key: 123,
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
## instance methods
|
||||
|
||||
### submitForm
|
||||
|
||||
- **参数：**
|
||||
|
||||
- `{boolean}` native
|
||||
|
||||
- **返回：**
|
||||
|
||||
- `{Object}` 整个表单的值
|
||||
|
||||
- **用法：**
|
||||
|
||||
提交表单，获取表单的值
|
||||
590
docs/src/api/model.md
Normal file
590
docs/src/api/model.md
Normal file
@ -0,0 +1,590 @@
|
||||
# Services
|
||||
|
||||
## editorService
|
||||
|
||||
### set
|
||||
|
||||
- **参数：**
|
||||
|
||||
- `{'root' | 'page' | 'parent' | 'node'} name`
|
||||
- `{MNode} value`
|
||||
|
||||
- **返回：**
|
||||
|
||||
- {[MNode](https://github.com/Tencent/tmagic-editor/blob/master/packages/schema/src/index.ts)}
|
||||
|
||||
- **用法：**
|
||||
|
||||
设置当前指点节点配置
|
||||
|
||||
'root': 当前整个配置，也就是当前编辑器的值
|
||||
|
||||
'page': 当前正在编辑的页面配置
|
||||
|
||||
'parent': 当前选中的节点的父节点
|
||||
|
||||
'node': 当前选中的节点
|
||||
|
||||
- **示例：**
|
||||
|
||||
```js
|
||||
import { editorService } from '@tmagic/editor';
|
||||
|
||||
const node = editorService.get('node');
|
||||
|
||||
node.name = 'new name';
|
||||
|
||||
editorService.set('node', node);
|
||||
|
||||
```
|
||||
|
||||
### get
|
||||
|
||||
|
||||
- **参数：**
|
||||
|
||||
- `{'root' | 'page' | 'parent' | 'node'} name`
|
||||
|
||||
- **返回：**
|
||||
|
||||
- {[MNode](https://github.com/Tencent/tmagic-editor/blob/master/packages/schema/src/index.ts)}
|
||||
|
||||
- **用法：**
|
||||
|
||||
获取当前指点节点配置
|
||||
|
||||
'root': 当前整个配置，也就是当前编辑器的值
|
||||
|
||||
'page': 当前正在编辑的页面配置
|
||||
|
||||
'parent': 当前选中的节点的父节点
|
||||
|
||||
'node': 当前选中的节点
|
||||
|
||||
- **示例：**
|
||||
|
||||
```js
|
||||
import { toRaw } from 'vue';
|
||||
import { editorService } from '@tmagic/editor';
|
||||
|
||||
const node = editorService.get('node');
|
||||
|
||||
console.log(toRaw(node));
|
||||
```
|
||||
|
||||
### getNodeInfo
|
||||
|
||||
- **参数：**
|
||||
|
||||
- `{number | string}` id
|
||||
|
||||
- **返回：**
|
||||
|
||||
- {[EditorNodeInfo](https://github.com/Tencent/tmagic-editor/blob/master/packages/editor/src/type.ts)}
|
||||
|
||||
- **用法：**
|
||||
|
||||
根据id获取组件、组件的父组件以及组件所属的页面节点
|
||||
|
||||
- **示例：**
|
||||
|
||||
```js
|
||||
import { toRaw } from 'vue';
|
||||
import { editorService } from '@tmagic/editor';
|
||||
|
||||
const info = editorService.getNodeInfo('text_123');
|
||||
|
||||
console.log(toRaw(info.node));
|
||||
console.log(toRaw(info.parent));
|
||||
console.log(toRaw(info.page));
|
||||
```
|
||||
|
||||
### getNodeById
|
||||
|
||||
- **参数：**
|
||||
|
||||
- `{number | string}` id
|
||||
|
||||
- **返回：**
|
||||
|
||||
- {[MNode](https://github.com/Tencent/tmagic-editor/blob/master/packages/schema/src/index.ts)} 组件节点配置
|
||||
|
||||
- **用法：**
|
||||
|
||||
根据id获取组件的信息
|
||||
|
||||
- **示例：**
|
||||
|
||||
```js
|
||||
import { toRaw } from 'vue';
|
||||
import { editorService } from '@tmagic/editor';
|
||||
|
||||
const node = editorService.getNodeById('text_123');
|
||||
|
||||
console.log(toRaw(node));
|
||||
```
|
||||
|
||||
### getParentById
|
||||
|
||||
- **参数：**
|
||||
|
||||
- `{number | string}` id
|
||||
|
||||
- **返回：**
|
||||
|
||||
- {[MNode](https://github.com/Tencent/tmagic-editor/blob/master/packages/schema/src/index.ts)} 指点组件的父节点配置
|
||||
|
||||
- **用法：**
|
||||
|
||||
根据ID获取指点节点的父节点配置
|
||||
|
||||
- **示例：**
|
||||
|
||||
```js
|
||||
import { toRaw } from 'vue';
|
||||
import { editorService } from '@tmagic/editor';
|
||||
|
||||
const parent = editorService.getParentById('text_123');
|
||||
|
||||
console.log(toRaw(parent));
|
||||
```
|
||||
|
||||
|
||||
### select
|
||||
|
||||
- **参数：**
|
||||
|
||||
- `{number | string | MNode}` config
|
||||
|
||||
- **返回：**
|
||||
|
||||
当前选中的节点配置
|
||||
|
||||
- **用法：**
|
||||
|
||||
选中指点节点（将指点节点设置成当前选中状态）
|
||||
|
||||
- **示例：**
|
||||
|
||||
```js
|
||||
import { editorService } from '@tmagic/editor';
|
||||
|
||||
editorService.select('text_123');
|
||||
```
|
||||
|
||||
### add
|
||||
|
||||
- **参数：**
|
||||
|
||||
- {[AddMNode](https://github.com/Tencent/tmagic-editor/blob/master/packages/editor/src/type.ts)} param0 将要添加的组件节点配置
|
||||
- {[MContainer](https://github.com/Tencent/tmagic-editor/blob/master/packages/schema/src/index.ts) | null} parent 要添加到的容器组件节点配置，如果不设置，默认为当前选中的组件的父节点
|
||||
|
||||
- **返回：**
|
||||
|
||||
添加后的节点
|
||||
|
||||
- **用法：**
|
||||
|
||||
向指点容器添加组件节点
|
||||
|
||||
- **示例：**
|
||||
|
||||
```js
|
||||
import { editorService } from '@tmagic/editor';
|
||||
|
||||
editorService.add({
|
||||
type: 'text',
|
||||
// ...
|
||||
});
|
||||
|
||||
const parent = editorService.getParentById('text_123');
|
||||
|
||||
editorService.add({
|
||||
type: 'text',
|
||||
// ...
|
||||
}, parent);
|
||||
```
|
||||
|
||||
### remove
|
||||
|
||||
- **参数：**
|
||||
|
||||
- {[MNode](https://github.com/Tencent/tmagic-editor/blob/master/packages/schema/src/index.ts)} node
|
||||
|
||||
- **返回：**
|
||||
|
||||
删除的组件配置
|
||||
|
||||
- **用法：**
|
||||
|
||||
删除组件
|
||||
|
||||
- **示例：**
|
||||
|
||||
|
||||
```js
|
||||
import { editorService } from '@tmagic/editor';
|
||||
|
||||
const node = editorService.get('node');
|
||||
editorService.remove(node);
|
||||
```
|
||||
|
||||
- ### update
|
||||
|
||||
- **参数：**
|
||||
|
||||
- {[MNode](https://github.com/Tencent/tmagic-editor/blob/master/packages/schema/src/index.ts)} config
|
||||
|
||||
- **返回：**
|
||||
|
||||
更新后的节点配置
|
||||
|
||||
- **用法：**
|
||||
|
||||
更新节点
|
||||
|
||||
- **示例：**
|
||||
|
||||
```js
|
||||
import { editorService } from '@tmagic/editor';
|
||||
|
||||
const node = editorService.get('node');
|
||||
node.name = 'new name';
|
||||
editorService.update(node);
|
||||
```
|
||||
|
||||
- ### sort
|
||||
|
||||
- **参数：**
|
||||
|
||||
- `{number | string}` id1
|
||||
- `{number | string}` id2
|
||||
|
||||
- **用法：**
|
||||
|
||||
将id为id1的组件移动到id为id2的组件位置上，例如：[1,2,3,4] -> sort(1,3) -> [2,1,3,4]
|
||||
|
||||
- **示例：**
|
||||
|
||||
```js
|
||||
import { editorService } from '@tmagic/editor';
|
||||
|
||||
const parent = editorService.get('parent');
|
||||
editorService.update(parent[0].id, parent[3].id);
|
||||
```
|
||||
|
||||
- ### copy
|
||||
|
||||
- **参数：**
|
||||
|
||||
- {[MNode](https://github.com/Tencent/tmagic-editor/blob/master/packages/schema/src/index.ts)} config
|
||||
|
||||
- **用法：**
|
||||
|
||||
将组将节点配置转化成string，然后存储到localStorage中
|
||||
|
||||
- **示例：**
|
||||
|
||||
```js
|
||||
import { editorService } from '@tmagic/editor';
|
||||
|
||||
const node = editorService.get('node');
|
||||
editorService.copy(node);
|
||||
```
|
||||
|
||||
- ### paste
|
||||
|
||||
- **参数：**
|
||||
|
||||
- `{Position}` position 可选，如果设置，指定组件位置
|
||||
|
||||
- **返回：**
|
||||
|
||||
添加后的组件节点配置
|
||||
|
||||
- **用法：**
|
||||
|
||||
从localStorage中获取节点，然后添加到当前容器中
|
||||
|
||||
- **示例：**
|
||||
|
||||
```js
|
||||
import { editorService } from '@tmagic/editor';
|
||||
|
||||
editorService.paste({ left: 0, top: 0 });`
|
||||
```
|
||||
|
||||
- ### alignCenter
|
||||
|
||||
- **参数：**
|
||||
|
||||
{[MNode](https://github.com/Tencent/tmagic-editor/blob/master/packages/schema/src/index.ts)} config
|
||||
|
||||
- **返回：**
|
||||
|
||||
当前组件节点配置
|
||||
|
||||
- **用法：**
|
||||
|
||||
将指点节点设置居中
|
||||
|
||||
- **示例：**
|
||||
|
||||
```js
|
||||
import { editorService } from '@tmagic/editor';
|
||||
|
||||
const node = editorService.get('node');
|
||||
editorService.alignCenter(node);
|
||||
```
|
||||
|
||||
- ### swap
|
||||
|
||||
- **参数：**
|
||||
|
||||
- `{number | 'latest' | 'first'` offset
|
||||
|
||||
- **用法：**
|
||||
|
||||
移动当前选中节点位置
|
||||
|
||||
- **示例：**
|
||||
|
||||
```js
|
||||
import { editorService } from '@tmagic/editor';
|
||||
|
||||
editorService.swap('bottom'); // 置底
|
||||
editorService.swap('first'); // 置顶
|
||||
editorService.swap(1); // 上移一层
|
||||
editorService.swap(-1); // 下移一层
|
||||
```
|
||||
|
||||
- ### undo
|
||||
|
||||
- **返回：**
|
||||
|
||||
上一次数据
|
||||
|
||||
- **用法：**
|
||||
|
||||
撤销当前操作
|
||||
|
||||
- **示例：**
|
||||
|
||||
```js
|
||||
import { editorService } from '@tmagic/editor';
|
||||
|
||||
editorService.undo();
|
||||
```
|
||||
|
||||
- ### redo
|
||||
|
||||
- **返回：**
|
||||
|
||||
下一步数据
|
||||
|
||||
- **用法：**
|
||||
|
||||
恢复到下一步
|
||||
|
||||
- **示例：**
|
||||
|
||||
```js
|
||||
import { editorService } from '@tmagic/editor';
|
||||
|
||||
editorService.redo();
|
||||
```
|
||||
|
||||
### usePlugin
|
||||
|
||||
- **参数：**
|
||||
|
||||
- `{Record<string, Function>` options
|
||||
|
||||
|
||||
- **用法：**
|
||||
扩展editorService中的方法（'select', 'add', 'remove', 'update', 'sort', 'copy', 'paste', 'center', 'moveLayer', 'undo', 'redo'）
|
||||
|
||||
对于每一个方法，都可以为其添加before/after两个扩展方法，分别在该方法运行前与运行后调用
|
||||
|
||||
调用时的参数会透传到before方法的参数中, 然后before的return 会作为原方法的参数和after的参数，after最后一个参数则是原方法的return值
|
||||
|
||||
- **示例：**
|
||||
|
||||
```js
|
||||
import { editorService } from '@tmagic/editor';
|
||||
|
||||
editorService.usePlugin({
|
||||
beforeAdd(value) {
|
||||
console.log(value); // { type: 'text' }
|
||||
console.log('before add');
|
||||
return [{
|
||||
type: 'button',
|
||||
}];
|
||||
},
|
||||
afterAdd(value, result) {
|
||||
console.log(value) // { type: 'button' }
|
||||
console.log('after add');
|
||||
},
|
||||
});
|
||||
|
||||
const node = await editorService.add({
|
||||
type: 'text';
|
||||
});
|
||||
|
||||
console.log(node); // { type: 'button' }
|
||||
|
||||
// console 输出如下：
|
||||
// { type: 'text' }
|
||||
// before add
|
||||
// add
|
||||
// { type: 'button' }
|
||||
// after add
|
||||
// { type: 'button' }
|
||||
```
|
||||
|
||||
### use
|
||||
|
||||
- **参数：**
|
||||
|
||||
- `{Record<string, Function>` options
|
||||
|
||||
|
||||
- **用法：**
|
||||
使用中间的方式扩展editorService中的方法（'select', 'add', 'remove', 'update', 'sort', 'copy', 'paste', 'center', 'moveLayer', 'undo', 'redo'）
|
||||
|
||||
- **示例：**
|
||||
|
||||
```js
|
||||
import { editorService } from '@tmagic/editor';
|
||||
|
||||
editorService.use({
|
||||
add(value, next) {
|
||||
console.log('before');
|
||||
next();
|
||||
console.log('after')
|
||||
},
|
||||
});
|
||||
|
||||
editorService.add({
|
||||
type: 'text';
|
||||
});
|
||||
|
||||
// console 输出如下：
|
||||
// before
|
||||
// add
|
||||
// after
|
||||
```
|
||||
|
||||
|
||||
:::tip
|
||||
可以多次为同一个方法添加扩展，运行时会根据添加的顺序依次调用
|
||||
:::
|
||||
|
||||
## propsService
|
||||
|
||||
### setPropsConfig
|
||||
|
||||
- **参数：**
|
||||
|
||||
- `{string}` type 组件类型
|
||||
- [FormConfig](https://github.com/Tencent/tmagic-editor/blob/master/packages/form/src/schema.ts) config 组件属性表单配置
|
||||
|
||||
- **用法：**
|
||||
|
||||
为指定类型组件设置组件属性表单配置
|
||||
|
||||
- **示例：**
|
||||
|
||||
```js
|
||||
import { propsService } from '@tmagic/editor';
|
||||
|
||||
propsService.setPropsConfig('text', [
|
||||
{
|
||||
name: 'text',
|
||||
text: '文本',
|
||||
},
|
||||
{
|
||||
name: 'multiple',
|
||||
text: '多行文本',
|
||||
type: 'switch',
|
||||
},
|
||||
]);
|
||||
```
|
||||
|
||||
### getPropsConfig
|
||||
|
||||
- **参数：**
|
||||
|
||||
- `{string}` type 组件类型
|
||||
|
||||
- **返回：**
|
||||
|
||||
组件属性表单配置
|
||||
|
||||
- **用法：**
|
||||
|
||||
获取指点类型的组件属性表单配置
|
||||
|
||||
- **示例：**
|
||||
|
||||
```js
|
||||
import { propsService } from '@tmagic/editor';
|
||||
|
||||
propsService.getPropsConfig('text');
|
||||
```
|
||||
|
||||
### setPropsValue
|
||||
|
||||
- **参数：**
|
||||
|
||||
- `{string}` type 组件类型
|
||||
- `{Object}` value 组件初始值
|
||||
|
||||
- **用法：**
|
||||
|
||||
为指点类型组件设置组件初始值
|
||||
|
||||
- **示例：**
|
||||
|
||||
```js
|
||||
import { propsService } from '@tmagic/editor';
|
||||
|
||||
propsService.setPropsValue('text', {
|
||||
text: '文本',
|
||||
multiple: true,
|
||||
});
|
||||
```
|
||||
|
||||
### getPropsValue
|
||||
|
||||
- **参数：**
|
||||
|
||||
- `{string}` type 组件类型
|
||||
|
||||
- **返回：**
|
||||
|
||||
组件初始值
|
||||
|
||||
- **用法：**
|
||||
|
||||
获取指定类型的组件初始值
|
||||
|
||||
- **示例：**
|
||||
|
||||
```js
|
||||
import { propsService } from '@tmagic/editor';
|
||||
|
||||
propsService.getPropsValue('text');
|
||||
```
|
||||
|
||||
### usePlugin
|
||||
|
||||
扩展propsService中的方法（'setConfig', 'getConfig', 'setValue', 'getValue'）
|
||||
|
||||
参照[editorService.usePlugin](#useplugin)
|
||||
|
||||
### use
|
||||
|
||||
扩展propsService中的方法（'setConfig', 'getConfig', 'setValue', 'getValue'）
|
||||
|
||||
参照[editorService.use](#use)
|
||||
209
docs/src/component/introduction.md
Normal file
209
docs/src/component/introduction.md
Normal file
@ -0,0 +1,209 @@
|
||||
# 如何开发一个组件
|
||||
魔方支持业务方进行自定义组件开发。在魔方中，组件是以 npm 包形式存在的，组件和插件只要按照规范开发，就可以在魔方的 runtime 中被加入并正确渲染组件。
|
||||
|
||||
## 组件注册
|
||||
在 [playground](https://tencent.github.io/tmagic-editor/playground/index.html#/) 中，我们可以尝试点击添加一个组件，在模拟器区域里，就会出现这个组件。其中就涉及到组件注册。
|
||||
|
||||
这一步需要开发者基于魔方搭建了平台后，实现组件列表的注册、获取机制，魔方组件注册其实就是保存好组件 `type` 的映射关系。`type` 可以参考[组件介绍](/docs/guide/conception.html#组件)。
|
||||
|
||||
可以参考 vue3 版本的 Magic-UI 中，[组件渲染](/docs/guide/advanced/page.html#组件渲染)逻辑里，type 会作为组件名进入渲染。所以在 vue3 的组件开发中，我们也需要在为 vue 组件声明 name 字段时，和 type 值对应起来，才能正确渲染组件。
|
||||
|
||||
## 组件开发
|
||||
以 vue3 的组件开发为例。目前项目中的 playground 代码，会自动加载 vue3 相关的组件库。
|
||||
|
||||
### 组件规范
|
||||
组件的基础形式，需要有四个文件
|
||||
- index 入口文件，引入下面几个文件
|
||||
- formConfig 表单配置描述
|
||||
- initValue 表单初始值
|
||||
- event 定义联动事件，具体可以参考[组件联动](docs/guide/advanced/coupling.html#组件联动)
|
||||
- component.{vue,jsx} 组件样式、逻辑代码
|
||||
|
||||
Magic-UI 中的 button/text 就是基础的组件示例。我们要求声明 index 入口，因为我们希望在后续的配套打包工具实现上，可以有一个统一规范入口。
|
||||
|
||||
### 1. 创建组件
|
||||
在项目中，如 runtime vue3 目录中，创建一个名为 test-comopnent 的组件目录，其中包含上面四个规范文件。
|
||||
```javascript
|
||||
// index.js
|
||||
// vue
|
||||
import Test from './Test.vue';
|
||||
// react
|
||||
import Test from './Test.tsx';
|
||||
|
||||
export { default as config } from './formConfig';
|
||||
export { default as value } from './initValue';
|
||||
|
||||
export default Test;
|
||||
```
|
||||
|
||||
```javascript
|
||||
// formConfig.js
|
||||
export default [
|
||||
{
|
||||
type: 'select',
|
||||
text: '字体颜色',
|
||||
name: 'color',
|
||||
options: [
|
||||
{
|
||||
text: '红色字体',
|
||||
value: 'red',
|
||||
},
|
||||
{
|
||||
text: '蓝色字体',
|
||||
value: 'blue',
|
||||
},
|
||||
],
|
||||
},
|
||||
{
|
||||
name: 'text',
|
||||
text: '配置文案',
|
||||
},
|
||||
];
|
||||
```
|
||||
|
||||
```javascript
|
||||
// initValue.js
|
||||
export default {
|
||||
color: 'red',
|
||||
text: '一段文字',
|
||||
};
|
||||
```
|
||||
|
||||
vue3 版本的组件代码示例
|
||||
```vue
|
||||
<!-- Test.vue -->
|
||||
<template>
|
||||
<div>
|
||||
<span>this is a Test component:</span>
|
||||
<span :style="{ color: config.color }">{{ config.text }}</span>
|
||||
</div>
|
||||
</template>
|
||||
|
||||
<script>
|
||||
export default {
|
||||
name: 'magic-ui-test',
|
||||
|
||||
props: {
|
||||
config: {
|
||||
type: Object,
|
||||
default: () => ({}),
|
||||
},
|
||||
},
|
||||
|
||||
setup() {},
|
||||
};
|
||||
</script>
|
||||
```
|
||||
|
||||
react 版本组件代码示例
|
||||
```javascript
|
||||
// Test.tsx
|
||||
import React, { useContext } from 'react';
|
||||
|
||||
import Core from '@tencent/magic-core';
|
||||
import { AppContent } from '@tencent/magic-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;
|
||||
|
||||
```
|
||||
|
||||
### 2. 打包脚本
|
||||
在 runtime vue3 中，我们已经提供好一份打包脚本示例。在 script 目录中。只需要在 unit.js 中加入你创建的组件到导出的 units 对象中，属性名即上面我们提到的组件 type，属性值为组件路径（如果是个 npm 包，则将路径替换为包名即可），打包脚本就会自动识别到你的组件。
|
||||
|
||||
```
|
||||
const units = {
|
||||
test: path.join(__dirname, '../src/components/test-component/index.js'),
|
||||
};
|
||||
```
|
||||
::: tip 自定义打包脚本
|
||||
scripts目录中的打包脚本仅是一份示例。业务方可以自行处理打包方式。这份示例的目的，在于告诉开发者，我们是如何生成组件入口、表单配置描述、表单初始值三个入口文件，并提供出去的供 runtime 使用的。
|
||||
:::
|
||||
|
||||
### 3. 启动 playground
|
||||
在上面的步骤完成后，在 playground/src/page/Editor.vue 中。找到组件栏的基础组件列表，在其中加入你的开发组件
|
||||
```javascript
|
||||
{
|
||||
title: '基础组件',
|
||||
items: [
|
||||
{
|
||||
text: '文本',
|
||||
type: 'text',
|
||||
},
|
||||
{
|
||||
text: '按钮',
|
||||
type: 'button',
|
||||
},
|
||||
// 加入这个测试组件
|
||||
{
|
||||
text: '测试',
|
||||
type: 'test',
|
||||
},
|
||||
],
|
||||
}
|
||||
```
|
||||
|
||||
然后，在 magic 项目根目录中，运行
|
||||
|
||||
```
|
||||
npm run playground
|
||||
```
|
||||
|
||||
至此，我们打开 playground 后，就能添加开发的中的组件，并且得到这个开发中的组件**在编辑器中的表现**了。
|
||||
|
||||
<img src="https://image.video.qpic.cn/oa_fd3c9c-3_548108267_1636719045199471">
|
||||
|
||||
### 4. 启动 runtime
|
||||
在完成开发中组件在编辑器中的实现后，我们将编辑器中的 uiconfig 源码📄 打开，复制 uiconfig。并在 runtime/vue3/src/page 下。创建一个 page-config.js 文件。将 uiconfig 作为配置导出。
|
||||
|
||||
```javascript
|
||||
window.magicUiConfig = [
|
||||
// uiconfig
|
||||
]
|
||||
```
|
||||
|
||||
在 page/main.ts 中，将这份配置读入
|
||||
```javascript
|
||||
import './page-config.js';
|
||||
```
|
||||
|
||||
然后执行在 runtime/vue3 目录下执行
|
||||
```
|
||||
npm run start
|
||||
```
|
||||
|
||||
至此，我们就可以得到这个开发中组件在编辑器中进行了配置并保存后，在真实页面中应该有的样子。
|
||||
|
||||
<img src="https://image.video.qpic.cn/oa_fd3c9c-3_1731965034_1636719708671597?imageView2/q/70" width="50%">
|
||||
|
||||
## 插件开发
|
||||
插件开发和组件开发形式类似，但是插件开发不需要有组件的规范。在以 vue 为基础的 ui 和 runtime 中，插件其实就是一个 vue 插件。
|
||||
|
||||
我们只需要在插件中提供一个入口文件，其中包含 vue 的 install 方法即可。
|
||||
|
||||
```javascript
|
||||
export default {
|
||||
install() {}
|
||||
}
|
||||
```
|
||||
|
||||
在插件中开发者可以自由实现需要的业务逻辑。插件和组件一样，只需要在 units.js 中，加入导出的 units 对象里即可。
|
||||
|
||||
## 业务定制
|
||||
上述的步骤，如
|
||||
1. 组件/插件初始化
|
||||
2. 编辑器中的组件调试
|
||||
3. 真实页面的组件调试
|
||||
4. 编辑器中的 uiconfig 同步至本地调试页面
|
||||
|
||||
等许多步骤，都可以交由业务方进行定制，开发业务自定义的脚手架工具，或者如示例中一样，使用打包脚本来处理。
|
||||
171
docs/src/guide/advanced/coupling.md
Normal file
171
docs/src/guide/advanced/coupling.md
Normal file
@ -0,0 +1,171 @@
|
||||
# 联动原理
|
||||
魔方的联动，指这两种情况：
|
||||
- 在编辑器中，组件的表单配置项之间需要联动。
|
||||
- 页面中的组件之间，需要联动触发行为。
|
||||
|
||||
## 表单联动
|
||||
表单的详细内容，可以参考[Magic-Form](/docs/guide/advanced/magic-form)。我们通过 [JS Schema](/docs/guide/advanced/js-schema) 描述的表单配置，实现联动的方式，就是写一个简单 js 函数。
|
||||
|
||||
比如下面的例子，我们希望改变选项时，同时改变文本框的内容。
|
||||
|
||||
<demo-block type="form" :config="`[{
|
||||
text: '文本',
|
||||
name: 'text'
|
||||
}, {
|
||||
type: 'select',
|
||||
text: '下拉选项',
|
||||
name: 'select',
|
||||
options: [
|
||||
{ text: '选项1', value: 1 },
|
||||
{ text: '选项2', value: 2 }
|
||||
],
|
||||
onChange: (vm, value, { model }) => {
|
||||
model.text = value;
|
||||
}
|
||||
}]`">
|
||||
</demo-block>
|
||||
|
||||
在经过表单渲染器时，所有指出函数 API 都会传入当前渲染的**表单组件实例(vm)**，**当前项目(value)**，**当前表单model**，**表单值formValue**，model 即 vue 的[表单输入绑定](https://cn.vuejs.org/v2/guide/forms.html#%E5%9C%A8%E7%BB%84%E4%BB%B6%E4%B8%8A%E4%BD%BF%E7%94%A8-v-model)，可以通过修改他来实现值联动。
|
||||
|
||||
当然我们也可以通过上述的参数传入，以及其他函数 API 实现更多灵活的表单联动，具体参考[表单 API](/docs/api/base-config)。
|
||||
|
||||
## 组件联动
|
||||
魔方在 @tencent/magic-core 中，实现了组件的事件绑定/分发机制。在组件渲染时，每个组件在 Magic-UI 中经过基础组件渲染时，会被基础组件注入公共方法的实现。如下对按钮配置了**点击使文本隐藏**的联动事件，那么在对应按钮被点击时，将会触发对应绑定文本的隐藏。
|
||||
|
||||
<img src="https://image.video.qpic.cn/oa_88b7d-10_2117738923_1637238863127559">
|
||||
|
||||
### 添加组件自定义事件
|
||||
如何开发一个完整组件可以参考[组件开发](/docs/component/introduction)，这一节我们主要讲述如何配置定义事件。
|
||||
|
||||
在组件开发过程中，我们可以通过声明组件中的 event 文件，在文件中描述当前组件可以配置的事件名，和可以被触发的动作。
|
||||
```javascript
|
||||
// event.js
|
||||
export default {
|
||||
events: [
|
||||
{
|
||||
label: '完成某事件',
|
||||
value: 'yourComponent:finishSomething',
|
||||
},
|
||||
],
|
||||
methods: [
|
||||
{
|
||||
label: '弹出 Toast',
|
||||
value: 'toast',
|
||||
},
|
||||
],
|
||||
};
|
||||
|
||||
```
|
||||
其中，events 的 value 是个事件名，是 `string` 类型，未了避免和其他组件事件名重复，应该添加上一些前缀。
|
||||
|
||||
而 methods 中的 value 则是一个挂载在组件上的可执行函数。我们会在事件触发时，分发到对应组件上，并执行对应组件实例上的方法。
|
||||
|
||||
配置了上述内容的组件，在编辑器中选中当前组件，要触发其他组件的联动事件时，会有如下选项
|
||||
|
||||
<img src="https://image.video.qpic.cn/oa_88b7d-32_1191352525_1637240258489761">
|
||||
|
||||
在被其他组件选中为联动组件，要触发联动事件，会有如下选项
|
||||
|
||||
<img src="https://image.video.qpic.cn/oa_fd3c9c-3_214972289_1637240375129207">
|
||||
|
||||
### 组件中的代码实现
|
||||
如上面提到的，我们定制了**完成某件事**这个事件，以及要提供一个**弹出 Toast**的方法。在组件中必要的实现内容如下。
|
||||
|
||||
#### vue 版本实现
|
||||
我们主要讲解 vue3 的 setup 实现。vue2 可以根据 vue3 同理转换成 options api 实现即可。
|
||||
|
||||
```vue
|
||||
<!-- Test.vue -->
|
||||
<template>
|
||||
<div @click="onClick">
|
||||
<!-- your component code -->
|
||||
</div>
|
||||
</template>
|
||||
|
||||
<script lang="ts">
|
||||
import { defineComponent, inject } from 'vue';
|
||||
|
||||
export default defineComponent({
|
||||
name: 'magic-ui-test',
|
||||
|
||||
setup(props) {
|
||||
const app: Core | undefined = inject('app');
|
||||
const hoc = inject('hoc');
|
||||
|
||||
// 此处实现事件动作
|
||||
// 由于组件在 Magic-UI 中通过基础组件 Component 来封装，即每个组件其实都被 Component 包裹
|
||||
// 实际触发时，会触发到当前组件的直属父组件 Component 上，我们会 provide 这个父组件为高阶组件 hoc
|
||||
// 所以将 toast 方法挂载到当前组件的父组件上
|
||||
hoc.toast = (/*接收触发事件组件传进来的参数*/) => {
|
||||
toast('测试 vue3')
|
||||
};
|
||||
|
||||
return {
|
||||
// 此处实现触发事件
|
||||
onClick: () => {
|
||||
// app.emit 第一个参数为事件名，其余参数为你要传给接受事件组件的参数
|
||||
app?.emit("yourComponent:finishSomething", /*可以传参给接收方*/);
|
||||
},
|
||||
};
|
||||
},
|
||||
});
|
||||
</script>
|
||||
```
|
||||
|
||||
::: tip
|
||||
在用 vue 实现的 组件中，我们通过 inject 方式来提供核心 app 和高阶组件 hoc。调用联动事件方法时，魔方是通过组件的 ref，并直接调用当前组件的方法。
|
||||
:::
|
||||
|
||||
#### react 版本实现
|
||||
在 react 的实现中，由于魔方提供的 Magic-UI react 版本是用 hook 实现的。所以组件开发我们也相应的需要使用 hook 方式。
|
||||
|
||||
```jsx
|
||||
import React from 'react';
|
||||
|
||||
import { useApp } from '@tencent/magic-ui-react';
|
||||
|
||||
function Test({ config }) {
|
||||
// react 和 vue 实现不同，我们通过 useApp 这个 hook 来提供 app, ref 等核心内容
|
||||
// 其中 ref 需要绑定到你的组件上作为 ref。因为一些公共事件会需要使用到你的组件 dom
|
||||
// 同时这个 ref 也会在魔方的高级函数钩子中，将你的组件 dom 作为参数提供给自定义钩子
|
||||
const { app, ref } = useApp({
|
||||
config,
|
||||
// 此处实现事件动作
|
||||
// 通过向 useApp 这个 hook 提供 methods 方法
|
||||
// 魔方会将该事件注册到事件机制中，在对应事件响应被触发时调用对应方法
|
||||
methods: {
|
||||
toast: (/*接收触发事件组件传进来的参数*/) => {
|
||||
toast('测试 react');
|
||||
},
|
||||
},
|
||||
});
|
||||
|
||||
const onClickFunc = () => {
|
||||
// app.emit 第一个参数为事件名，其余参数为你要传给接受事件组件的参数
|
||||
app?.emit("yourComponent:finishSomething", /*可以传参给接收方*/);
|
||||
}
|
||||
|
||||
return (
|
||||
<div
|
||||
ref={ref}
|
||||
id={config.id}
|
||||
style={app.transformStyle(config.style || {})}
|
||||
onClick={onClick}
|
||||
>
|
||||
// your component code
|
||||
</div>
|
||||
);
|
||||
}
|
||||
|
||||
export default Test;
|
||||
```
|
||||
|
||||
::: tip
|
||||
react 的实现方式需要开发者通过 useApp 来获得我们提供的核心 app 和一个 ref，这个 ref 是需要开发者绑定到组件上的。和 vue 不同，react 的 dom 实例需要用户指定。
|
||||
|
||||
而需要这个 ref 的原因，是在公共事件执行时，可能会需要 dom 实例来进行操作；或者用户使用高级函数时，我们会向用户传入组件的 dom 实例给开发者使用。
|
||||
:::
|
||||
|
||||
按照上述实现触发事件和事件动作，就可以完成组件的联动事件分发响应。
|
||||
|
||||
|
||||
45
docs/src/guide/advanced/high-level-function.md
Normal file
45
docs/src/guide/advanced/high-level-function.md
Normal file
@ -0,0 +1,45 @@
|
||||
# 高级函数
|
||||
魔方的一个高级特性，就是支持开发者在不修改组件代码的情况下，对活动页面进行特定的修改，方式即支持开发者在线编码，让这份代码特定时机执行。
|
||||
|
||||
<img src="https://image.video.qpic.cn/oa_88b7d-37_1895524853_1636348113209218">
|
||||
|
||||
## Magic-Core
|
||||
我们在 @tencent/magic-core 这个包中，实现了魔方组件节点的 Node 类，每个组件在魔方的运行环境被渲染前，都会对应初始化一个 Node 类实例。而这些 Node 实例上包含了一些基础功能，包括触发指定钩子函数。这是一个框架无关的核心库，所以支持在各个语言框架中使用。但是具体触发时机需要由各个框架的渲染器实现。
|
||||
|
||||
在 react 和 vue 两种框架下的执行时机，可以参考我们的 runtime 实现:
|
||||
|
||||
- [react runtime 执行钩子时机](https://github.com/Tencent/tmagic-editor/blob/master/packages/ui-react/src/useApp.ts)
|
||||
- [vue runtime 执行钩子时机](https://github.com/Tencent/tmagic-editor/blob/master/packages/ui/src/useApp.ts)
|
||||
|
||||
## 函数编写
|
||||
在编辑中，即写入一个执行函数，魔方会在对应组件的指定声明周期中执行改函数。同时**传入当前组件的 Node 实例对象**，作为执行参数。
|
||||
|
||||
传入的实例对象，可以根据各语言框架实现的 ui 提供的特性能力，来支持业务组件的能力实现。这个功能提供给开发者自由实现黑科技的机会。
|
||||
|
||||
<img src="https://image.video.qpic.cn/oa_2a552e-0_934618672_1636348294258073">
|
||||
|
||||
### 函数参数
|
||||
在 Magic-Core 中，我们对执行钩子函数传入了对应的 Node 实例对象。在 react 和 vue 中会稍有差异。差异在于 Node 实例的 instance 属性。
|
||||
|
||||
- [Node 实例描述](https://github.com/Tencent/tmagic-editor/blob/master/packages/core/src/Node.ts)
|
||||
|
||||
### instance
|
||||
Magic-Core 会在监听到对应事件时，将 payload 赋值给 Node 实例的 instace 属性。
|
||||
|
||||
其中 instance 属性的值，即我们在上面描述的，各个框架的钩子执行时机时发送的 payload 数据，各个框架发送的 instance 数据依据框架而定。instance 上会挂载一个 $el 对象，是各个框架 runtime 实现后，在组件 mounted 时候会得到的 dom 引用实例。
|
||||
|
||||
在示例中可以找到对应的触发事件和监听事件的形式如下：
|
||||
|
||||
```javascript
|
||||
// runtime 中发送数据
|
||||
app.emit('created', instance)
|
||||
|
||||
// class Node
|
||||
this.once('created', (instance: any) => {
|
||||
this.instance = instance;
|
||||
});
|
||||
```
|
||||
|
||||
- [Node 类监听声明周期](https://github.com/Tencent/tmagic-editor/blob/master/packages/core/src/Node.ts)
|
||||
- [react runtime 执行钩子时机](https://github.com/Tencent/tmagic-editor/blob/master/packages/ui-react/src/useApp.ts)
|
||||
- [vue runtime 执行钩子时机](https://github.com/Tencent/tmagic-editor/blob/master/packages/ui/src/useApp.ts)
|
||||
137
docs/src/guide/advanced/js-schema.md
Normal file
137
docs/src/guide/advanced/js-schema.md
Normal file
@ -0,0 +1,137 @@
|
||||
# JS Schema
|
||||
魔方的业务组件需要有表单配置能力，我们通过一份配置来描述表单，我们采用的描述方案是 JS schema。当我们在编辑器中配置一个页面时，页面的基本信息和页面包含的组件信息，也是采用 JS schema 描述的。JS schema 描述方案，，也是我们提供[高级函数](/docs/guide/advanced/high-level-function)功能的基础。
|
||||
|
||||
组件的**配置描述**，参考[示例](/docs/guide/advanced/magic-form.html#示例)，是由开发者在开发组件时，通过 [Magic-Form](/docs/guide/advanced/magic-form) 支持的表单项来提供的。
|
||||
|
||||
在编辑器中对页面进行编辑，保存得到的是一份关于页面基本信息、页面所包含组件以及组件配置信息的配置，我们称为 **uiconfig**，这份配置是最终页面渲染需要的描述信息。
|
||||
|
||||
JS schema 本质即是一个 js 对象，这个形式可以支持我们在组件的表单配置描述中，直接进行函数编写，功能灵活，对于前端开发来说更符合直觉，几乎没有理解成本。
|
||||
|
||||
## 表单配置
|
||||
组件中的表单配置描述，在经过 Magic-Form 表单渲染器后，可以生成表单栏的配置项。在表单栏中对表单进行配置，配置数据将动态写入 uiconfig 中。
|
||||
|
||||
<img src="https://image.video.qpic.cn/oa_88b7d-36_673631168_1636343947880034?imageView2/q/70">
|
||||
|
||||
## uiconfig
|
||||
编辑器中生成的 uiconfig 序列化存储后，在发布时，将其作为 js 文件发布出去，供生成页使用。一个生成页最终保存的 uiconfig 配置示例如下：
|
||||
|
||||
```javascript
|
||||
{
|
||||
id: "75f0extui9d7yksklx27hff8xg",
|
||||
name: "test_page",
|
||||
type: "app",
|
||||
beginTime: "2021-04-26T16:00:00.000Z",
|
||||
endTime: "2021-05-28T16:00:00.000Z",
|
||||
items: [
|
||||
{
|
||||
type: "page",
|
||||
name: "index",
|
||||
title: "1",
|
||||
isAbsoluteLayout: true,
|
||||
style: {
|
||||
width: "375",
|
||||
height: "1728",
|
||||
backgroundColor: "rgba(218, 192, 192, 1)"
|
||||
},
|
||||
id: "39381280",
|
||||
items: [
|
||||
{
|
||||
dtEid: "container",
|
||||
type: "container",
|
||||
name: "组",
|
||||
id: "98549062",
|
||||
renderType: 0,
|
||||
reportType: "module",
|
||||
time: 1623850856402,
|
||||
report: {
|
||||
module: {
|
||||
_module: "组_98549062",
|
||||
eid: "container"
|
||||
}
|
||||
},
|
||||
devconfig: {
|
||||
lock: false,
|
||||
pack: false,
|
||||
resizable: true,
|
||||
aspectRatio: false,
|
||||
ratio: 1,
|
||||
modify: false
|
||||
},
|
||||
items: [
|
||||
{
|
||||
type: "button",
|
||||
id: "87016850",
|
||||
name: "按钮",
|
||||
style: {
|
||||
position: "absolute",
|
||||
left: 57,
|
||||
top: 152,
|
||||
right: "",
|
||||
bottom: "",
|
||||
width: 270,
|
||||
height: 38,
|
||||
backgroundImage: "",
|
||||
backgroundColor: "#fb6f00",
|
||||
backgroundRepeat: "no-repeat",
|
||||
backgroundSize: "100% 100%",
|
||||
transform: "none",
|
||||
textAlign: "center",
|
||||
border: 0
|
||||
},
|
||||
events: [
|
||||
{
|
||||
name: "magic:common:events:click",
|
||||
to: "button_3877",
|
||||
method: ""
|
||||
}
|
||||
],
|
||||
created: ()=>{},
|
||||
renderType: 1,
|
||||
text: "请输入文本内容",
|
||||
},
|
||||
{
|
||||
id: "text_7909",
|
||||
style: {
|
||||
left: 88,
|
||||
top: -73,
|
||||
position: "absolute",
|
||||
width: 100,
|
||||
height: 14,
|
||||
transform: "none"
|
||||
},
|
||||
type: "text",
|
||||
name: "文本",
|
||||
text: "请输入文本内容",
|
||||
multiple: true,
|
||||
renderType: 1
|
||||
},
|
||||
{
|
||||
type: "button",
|
||||
id: "button_3877",
|
||||
style: {
|
||||
position: "absolute",
|
||||
left: "57",
|
||||
width: "270",
|
||||
height: "37.5",
|
||||
border: 0,
|
||||
backgroundColor: "#fb6f00"
|
||||
},
|
||||
name: "按钮",
|
||||
text: "请输入文本内容",
|
||||
multiple: true,
|
||||
renderType: 1
|
||||
}
|
||||
],
|
||||
style: {
|
||||
width: "100%",
|
||||
height: "100",
|
||||
position: "absolute",
|
||||
left: 0,
|
||||
top: 204
|
||||
}
|
||||
}
|
||||
]
|
||||
},
|
||||
]
|
||||
}
|
||||
```
|
||||
49
docs/src/guide/advanced/layout.md
Normal file
49
docs/src/guide/advanced/layout.md
Normal file
@ -0,0 +1,49 @@
|
||||
# 布局原理
|
||||
魔方的布局实现方式，**关键在于将布局配置指定在容器上，对容器内的所有子组件生效**，这是魔方页面可以支持各种布局方式混合使用的核心方法。
|
||||
|
||||
## 容器
|
||||
前面概念介绍中有提到，魔方的容器是组件的基础。组件必属于某个容器，容器下可以放组件，也可以放容器。页面本身就是一个容器，是所有容器和组件的根，整个页面的容器和组件组成一个树状结构。在 uiconfig 配置中，表现为:
|
||||
|
||||
```javascript
|
||||
[{
|
||||
id: 123456,
|
||||
type: 'page',
|
||||
items: [{
|
||||
id: 222222,
|
||||
type: 'comp-A',
|
||||
}, {
|
||||
id: 333333,
|
||||
type: 'comp-B',
|
||||
}]
|
||||
}]
|
||||
```
|
||||
|
||||
## 顺序/绝对定位
|
||||
组件是绝对或者顺序定位，体现在组件的**直属父级容器**上，比如我们将 page 设置为绝对定位，则它的子组件，全都为绝对定位。在 uiconfig 配置中，表现为：
|
||||
|
||||
```javascript
|
||||
[{
|
||||
id: 123456,
|
||||
type: 'page',
|
||||
isAbsoluteLayout: true,
|
||||
items: [{
|
||||
id: 222222,
|
||||
type: 'comp-A',
|
||||
style: {
|
||||
position: 'absolute',
|
||||
},
|
||||
}, {
|
||||
id: 333333,
|
||||
type: 'comp-B',
|
||||
style: {
|
||||
position: 'absolute',
|
||||
},
|
||||
}]
|
||||
}]
|
||||
```
|
||||
当然，绝对/顺序排布的配置方式，也只存在于容器中。
|
||||
|
||||
## 混合布局
|
||||
因为魔方的布局配置，是指定在容器上的，所以魔方的设计方式，就可以支持在页面中实现各种混合布局的嵌套。
|
||||
|
||||
<img src="https://image.video.qpic.cn/oa_88b7d-37_1417201939_1636341538475155?imageView2/q/70">
|
||||
135
docs/src/guide/advanced/magic-form.md
Normal file
135
docs/src/guide/advanced/magic-form.md
Normal file
@ -0,0 +1,135 @@
|
||||
# Magic-Form
|
||||
魔方的表单配置，核心就是使用了 magic-form 来作为渲染器。magic-form 是一个 npm 包，可以安装它，在你想使用的地方单独使用。
|
||||
|
||||
Magic-Form 接受一个表单配置，详细配置可参考[表单api](/docs/api/form.md)。
|
||||
|
||||
## 安装
|
||||
|
||||
```bash
|
||||
# 最新稳定版
|
||||
$ npm install @tmagic/form@next
|
||||
```
|
||||
|
||||
```bash
|
||||
$ npm install element-plus
|
||||
```
|
||||
|
||||
## 快速上手
|
||||
|
||||
本节将介绍如何在项目中使用 MagicForm。
|
||||
|
||||
### 引入 Magic-Form
|
||||
|
||||
MagicForm使用了element-ui库
|
||||
|
||||
在 main.js 中写入以下内容：
|
||||
|
||||
```javascript
|
||||
import { createApp } from 'vue';
|
||||
import ElementPlus from 'element-plus';
|
||||
import MagicForm from '@tmagic/form';
|
||||
import 'element-plus/lib/theme-chalk/index.css';
|
||||
import App from './App.vue';
|
||||
|
||||
const app = createApp(App);
|
||||
app.use(ElementUI);
|
||||
app.use(MagicForm);
|
||||
app.mount('#app');
|
||||
```
|
||||
|
||||
在 App.Vue 中写入以下内容：
|
||||
|
||||
```html
|
||||
<m-form :config="config" :init-values="initValue"></m-form>
|
||||
|
||||
<script>
|
||||
export default {
|
||||
data() {
|
||||
return {
|
||||
config: [{
|
||||
text: '文本',
|
||||
name: 'text'
|
||||
}, {
|
||||
type: 'number',
|
||||
text: '计数器',
|
||||
name: 'number'
|
||||
}, {
|
||||
type: 'row',
|
||||
items: [{
|
||||
type: 'date',
|
||||
text: '日期',
|
||||
name: 'date'
|
||||
}, {
|
||||
type: 'checkbox',
|
||||
text: '多选框',
|
||||
name: 'checkbox'
|
||||
}]
|
||||
}, {
|
||||
type: 'fieldset',
|
||||
name: 'fieldset',
|
||||
legend: '分组',
|
||||
items: [{
|
||||
type: 'select',
|
||||
text: '下拉选项',
|
||||
name: 'select',
|
||||
options: [
|
||||
{ text: '选项1', value: 1 },
|
||||
{ text: '选项2', value: 2 }
|
||||
]
|
||||
}]
|
||||
}],
|
||||
initValue: {
|
||||
text: '文本',
|
||||
number: 10,
|
||||
fieldset: {
|
||||
select: 1
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
</script>
|
||||
```
|
||||
|
||||
以上代码便完成了 MagicForm 的引入。需要注意的是，ElementUI的样式文件需要单独引入。
|
||||
|
||||
### 开始使用
|
||||
|
||||
至此，一个基于 Vue 和 MagicForm 的开发环境已经搭建完毕，现在就可以编写代码了。
|
||||
|
||||
|
||||
### 示例
|
||||
|
||||
<demo-block type="form" :config="[{
|
||||
text: '文本',
|
||||
name: 'text'
|
||||
}, {
|
||||
type: 'number',
|
||||
text: '计数器',
|
||||
name: 'number'
|
||||
}, {
|
||||
type: 'row',
|
||||
items: [{
|
||||
type: 'date',
|
||||
text: '日期',
|
||||
name: 'date'
|
||||
}, {
|
||||
type: 'checkbox',
|
||||
text: '多选框',
|
||||
name: 'checkbox'
|
||||
}]
|
||||
}, {
|
||||
type: 'fieldset',
|
||||
name: 'fieldset',
|
||||
legend: '分组',
|
||||
items: [{
|
||||
type: 'select',
|
||||
text: '下拉选项',
|
||||
name: 'select',
|
||||
options: [
|
||||
{ text: '选项1', value: 1 },
|
||||
{ text: '选项2', value: 2 }
|
||||
]
|
||||
}]
|
||||
}]">
|
||||
</demo-block>
|
||||
30
docs/src/guide/advanced/magic-ui.md
Normal file
30
docs/src/guide/advanced/magic-ui.md
Normal file
@ -0,0 +1,30 @@
|
||||
# Magic-UI
|
||||
在前面[页面渲染](/docs/guide/advanced/page)中提到的 UI 渲染器，就是包含在 Magic-UI 中的渲染器组件。
|
||||
|
||||
魔方的设计是希望发布的页面支持多个前端框架，即各个业务方可以根据自己熟悉的语言来开发组件、发布页面。也可以通过 [实现一个 runtime](/docs/page/advanced.html#实现一个-runtime) 的方式，来实现一个自己的 Magic-UI。
|
||||
|
||||
所以魔方的设计中，针对每个前端框架，都需要有一个对应的 Magic-UI 来承担渲染器职责。同时，也需要一个使用和 Magic-UI 相同前端框架的 runtime 来 Magic-UI 和业务组件的，具体 runtime 概念，可以参考[页面发布](/docs/page/introduction)。
|
||||
|
||||
Magic-UI 在魔方设计中，承担的是业务逻辑无关的，基础组件渲染的功能。一切和业务相关的逻辑，都应该在 [runtime](/docs/page/introduction.html#runtime) 中实现。这样 Magic-UI 就能保持其通用性。
|
||||
|
||||
我们以项目代码中提供的 vue3 版本的 Magic-UI 作为示例介绍其中包含的内容。
|
||||
|
||||
## 渲染器
|
||||
在 vue3 中，实现渲染器的具体形式参考[页面渲染](/docs/guide/advanced/page)中描述的[容器渲染](/docs/guide/advanced/page.html#容器渲染)和[组件渲染](/docs/guide/advanced/page.html#容器渲染)。
|
||||
|
||||
## 基础组件
|
||||
在 Magic-UI vue3 中，我们提供了几个基础组件，可以在项目源码中找到对应内容。
|
||||
|
||||
- page 魔方的页面基础
|
||||
- container 魔方的容器渲染器
|
||||
- Component.vue 魔方的组件渲染器
|
||||
- button/text 基础组件示例
|
||||
|
||||
其中 page/container/Component 是 UI 的基础，是每个框架的 UI 都应该实现的。
|
||||
|
||||
button/text 其实就是一个组件开发的示例，具体组件开发相关规范可以参考[组件开发](/docs/component/introduction)。
|
||||
|
||||
## Magic-UI 示例
|
||||
- [vue3 渲染器](https://github.com/Tencent/tmagic-editor/blob/master/packages/ui)
|
||||
- [vue2 渲染器](https://github.com/Tencent/tmagic-editor/blob/master/packages/ui-vue2)
|
||||
- [react 渲染器](https://github.com/Tencent/tmagic-editor/blob/master/packages/ui-react)
|
||||
65
docs/src/guide/advanced/page.md
Normal file
65
docs/src/guide/advanced/page.md
Normal file
@ -0,0 +1,65 @@
|
||||
# 页面渲染
|
||||
魔方的页面渲染，是通过在载入编辑器中保存的 uiconfig 配置，通过 ui 渲染器渲染页面。在容器布局原理里我们提到过，容器和组件在配置中呈树状结构，所以渲染页面的时候，渲染器会递归配置内容，从而渲染出页面所有组件。
|
||||
|
||||
<img src="https://vfiles.gtimg.cn/vupload/20211009/f4d3031633778551251.png">
|
||||
|
||||
## 容器渲染
|
||||
页面的渲染器，其实就是两个基础组件，基础容器组件和基础组件。页面在读到 uiconfig 配置之后，根组件必定是一个容器，此时渲染基础容器组件，而容器组件的职责很简单，就是将其子组件渲染出来。具体形式为：
|
||||
|
||||
```vue
|
||||
<template>
|
||||
<div>
|
||||
<magic-ui-component
|
||||
v-for="item in config.items"
|
||||
:key="item.id"
|
||||
:config="item"
|
||||
></magic-ui-component>
|
||||
</div>
|
||||
</template>
|
||||
|
||||
<script>
|
||||
export default {
|
||||
name: 'magic-ui-container',
|
||||
};
|
||||
</script>
|
||||
```
|
||||
|
||||
## 组件渲染
|
||||
所有魔方组件，都通过一个魔方基础组件来渲染，这个基础组件会识别，当前渲染的组件是个普通组件，或者是容器组件，如果是普通组件（包括ui中提供的基础组件和业务开发的业务组件），则直接渲染；如果是个容器，则回到上一步的容器渲染逻辑中。
|
||||
|
||||
基础组件的具体形式为：
|
||||
```vue
|
||||
<template>
|
||||
<component
|
||||
:is="tagName"
|
||||
:config="config"
|
||||
></component>
|
||||
</template>
|
||||
|
||||
<script lang="ts">
|
||||
import { computed, defineComponent } from 'vue';
|
||||
|
||||
export default defineComponent({
|
||||
name: 'magic-ui-component',
|
||||
|
||||
props: {
|
||||
config: {
|
||||
type: Object,
|
||||
default: () => ({}),
|
||||
},
|
||||
},
|
||||
|
||||
setup(props) {
|
||||
return {
|
||||
tagName: computed(() => `magic-ui-${props.config.type}`),
|
||||
};
|
||||
},
|
||||
});
|
||||
</script>
|
||||
```
|
||||
|
||||
## 渲染器示例
|
||||
在魔方的示例项目中，我们提供了三个版本的 Magic-UI。可以参考对应前端框架的渲染器实现。
|
||||
- [vue3 渲染器](https://github.com/Tencent/tmagic-editor/blob/master/packages/ui/src/container/src/Container.vue)
|
||||
- [vue2 渲染器](https://github.com/Tencent/tmagic-editor/blob/master/packages/ui-vue2/src/container/Container.vue)
|
||||
- [react 渲染器](https://github.com/Tencent/tmagic-editor/blob/master/packages/ui-react/src/container/Container.tsx)
|
||||
62
docs/src/guide/conception.md
Normal file
62
docs/src/guide/conception.md
Normal file
@ -0,0 +1,62 @@
|
||||
# 基础概念
|
||||
我们通过讲述魔方的一些基础概念。帮助开发者可以了解魔方是如何运行以及如何在基础项目之上开发、使用它。
|
||||
|
||||
## 编辑器
|
||||
编辑器基础布局上分为：左面板、工作区、右面板、工具栏，如下图。
|
||||
- **左面板**，包含了组件库的展示，以及工作区中已添加组件的组件树展示。
|
||||
- **工作区**，一个页面模拟器，用于实时展示用户添加到当前页面中的组件在真实页面中的展示情况。
|
||||
- **右面板**，展示组件提供出来的表单选项，让用户可以通过配置项来改变组件的行为和样式。
|
||||
- **工具栏**，放置一些如缩放、撤销等工具按键。
|
||||
<img src="https://vfiles.gtimg.cn/vupload/20211009/083dfa1633771059332.png">
|
||||
|
||||
### 组件
|
||||
组件是魔方可配置页面元素的最小单位。我们都会从左面版的组件区中选中组件，加入到工作区的模拟器中，然后在右面板中对组件进行配置。一个组件的基本内容，会包含如下：
|
||||
- 组件样式、逻辑代码（即开发者写的 vue, react 等代码）。
|
||||
- 表单配置描述，魔方的定义是导出一个表单对象，这份配置仅在编辑器中使用。
|
||||
- 拓展描述，这部分内容目前还未有严格定义，但是我们保留这个扩展能力。
|
||||
- 组件 `type`, 是组件的类型，这是用来告诉编辑器，我们要渲染的是什么组件。每个组件在开发时就应该确定这样一个唯一、不和其他组件冲突的组件 `type`。
|
||||
|
||||
### 插件
|
||||
插件和组件类似，但是插件的功能是作为页面逻辑行为的一种补充方式。一般不显式的在模拟器中被渲染出具体内容（除非插件中会生成组件并插入页面），通常我们会用插件实现类似登录，页面环境判断，请求拦截器等等功能。
|
||||
|
||||
插件一般包含如下内容：
|
||||
- 插件逻辑代码。
|
||||
- 插件 `type`，是插件的类型，和组件 `type` 作用相同。在开发时就应该确定这样一个唯一、不和其他组件冲突的组件 `type`。
|
||||
|
||||
|
||||
### 容器
|
||||
容器是魔方编辑器中的一个基础单位，页面本身就是一个容器，在基础组件中称为**组**，魔方通过容器概念，实现了丰富的布局方式，因为我们的布局行为是设置在容器上的，容器内的组件是绝对定位、或是顺序排布，是根据容器的配置行为改变的。魔方的容器理论上可以无限嵌套。
|
||||
|
||||
### 表单配置
|
||||
表单配置是编辑器右面板展示的内容，配置项目都是由组件里的表单描述来决定的，用户可以在表单配置区域里通过配置项来改变组件的行为和样式。
|
||||
|
||||
注意，由于每个组件都需要有一些共同的表单配置项目，所以魔方通过在表单渲染器，统一为所有组件加上了通用的表单配置项目。包括基础组件样式配置、钩子事件配置等。
|
||||
|
||||
### uiconfig
|
||||
uiconfig 是编辑器搭建页面的最终产物（描述文件），其中包含了所有组件信息（组件布局，组件配置等）和插件内容，以及其他可拓展的信息都存放在 uiconfig 中。魔方活动页的展示即是魔方页面在加载 uiconfig 之后，根据 uiconfig 的描述进行渲染的。在魔方中，我们使用 JS schema 来保存这份配置文件。
|
||||
|
||||
## 页面
|
||||
页面是魔方作为一个可视化编辑器经过配置后，最终得到的呈现结果。搭建后的页面会被发布上线，供用户访问。
|
||||
|
||||
### runtime
|
||||
我们把页面统一称为 runtime，更具体的 runtime 概念可以查看[页面发布](/docs/page/introduction.html#runtime)。**runtime 是承载魔方活动页面的运行环境**。编辑器的工作区是 runtime 的一个具体实例，另一个就是我们发布上线后，用户访问的真实活动页面。
|
||||
|
||||
### magic-ui
|
||||
magic-ui 包含了魔方的基础组件库，提供了容器、文本、按钮这样的基础组件。我们提供了不同语言框架的 magic-ui，如 vue2 和 vue3。
|
||||
|
||||
magic-ui 和 runtime 是配套出现的，runtime 必须基于 magic-ui 才可以实现渲染。因为 magic-ui 需要提供 runtime 所需要的渲染器。
|
||||
|
||||
## 联动
|
||||
页面搭建过程中，会涉及到两种联动形式
|
||||
- 在编辑器中，组件的表单配置项之间需要联动。
|
||||
- 页面中的组件之间，需要联动触发行为。
|
||||
|
||||
### 表单联动
|
||||
配置项 A 改变值，希望能触发配置项 B 相应的变成另外一个值，就是表单联动的一个示例。魔方实现表单联动的方式，就是通过渲染的时候，将表单对象注入，在组件的表单配置描述中，可以通过函数声明来获取并且进行逻辑编写，实现表单联动。
|
||||
|
||||
### 组件联动
|
||||
组件 A 在完成点击事件后，希望组件 B 可以展示一个弹窗，就是组件联动的一个示例。魔方通过事件绑定方式，可以为组件 A 和 B 配置事件关联，实现上述的组件联动。
|
||||
<img src="https://image.video.qpic.cn/oa_88b7d-37_723692309_1636032154483681" alt="组件联动">
|
||||
|
||||
|
||||
|
||||
159
docs/src/guide/installation.md
Normal file
159
docs/src/guide/installation.md
Normal file
@ -0,0 +1,159 @@
|
||||
# 快速开始
|
||||
魔方的编辑器我们已经封装成一个 npm 包，可以直接安装使用。编辑器是使用 vue3 开发的，但使用编辑器的业务可以不限框架，可以用vue2、react等开发业务组件。
|
||||
|
||||
## 安装
|
||||
|
||||
node.js > 14
|
||||
|
||||
可以通过[Vite](https://github.com/vitejs/vite) 或 [Vue CLI](https://cli.vuejs.org/zh/)快速创建项目。
|
||||
|
||||
推荐使用 npm 的方式安装，它能更好地和 [webpack](https://webpack.js.org/) 打包工具配合使用。
|
||||
|
||||
```bash
|
||||
# 最新稳定版
|
||||
$ npm install @tmagic/editor@next -S
|
||||
```
|
||||
|
||||
editor中组件自定义属性配置由[magic-form](../form/introduction.md)提供，需要添加@tmagic/form依赖；editor 与 form 中使用到的UI组件都由 [element-plus](https://element-plus.org/)提供，需要添加element-plus依赖。
|
||||
|
||||
```bash
|
||||
$ npm install @tmagic/form@next element-plus -S
|
||||
```
|
||||
|
||||
## 快速上手
|
||||
|
||||
### 引入 @tmagic/editor
|
||||
|
||||
在 main.js 中写入以下内容：
|
||||
```js
|
||||
import { createApp } from 'vue';
|
||||
import ElementPlus from 'element-plus';
|
||||
import zhCn from 'element-plus/es/locale/lang/zh-cn';
|
||||
|
||||
import MagicEditor from '@tmagic/editor';
|
||||
import MagicForm from '@tmagic/form';
|
||||
|
||||
import App from './App.vue';
|
||||
|
||||
import 'element-plus/dist/index.css';
|
||||
import '@tmagic/editor/dist/style.css';
|
||||
import '@tmagic/form/dist/style.css';
|
||||
|
||||
const app = createApp(App);
|
||||
app.use(ElementPlus, {
|
||||
locale: zhCn,
|
||||
});
|
||||
app.use(MagicEditor);
|
||||
app.use(MagicForm);
|
||||
app.mount('#app');
|
||||
|
||||
```
|
||||
以上代码便完成了 @tmagic/editor 的引入。需要注意的是，样式文件需要单独引入。
|
||||
|
||||
### 使用 m-editor 组件
|
||||
|
||||
在 App.vue 中写入以下内容：
|
||||
```html
|
||||
<template>
|
||||
<m-editor
|
||||
v-model="data"
|
||||
:menu="menu"
|
||||
:runtime-url="runtimeUrl"
|
||||
:props-configs="propsConfigs"
|
||||
:props-values="propsValues"
|
||||
:component-group-list="componentGroupList"
|
||||
>
|
||||
</m-editor>
|
||||
</template>
|
||||
|
||||
<script>
|
||||
import { defineComponent, ref } from 'vue';
|
||||
|
||||
export default defineComponent({
|
||||
name: 'App',
|
||||
|
||||
setup() {
|
||||
return {
|
||||
menu: ref({
|
||||
left: [
|
||||
// 顶部左侧菜单按钮
|
||||
],
|
||||
center: [
|
||||
// 顶部中间菜单按钮
|
||||
],
|
||||
right: [
|
||||
// 顶部右侧菜单按钮
|
||||
],
|
||||
}),
|
||||
|
||||
data: ref({
|
||||
// 初始化页面数据
|
||||
}),
|
||||
|
||||
runtimeUrl: '/runtime/vue3/playground.html',
|
||||
propsConfigs: [],
|
||||
propsValues: [],
|
||||
|
||||
componentGroupList: ref([
|
||||
// 组件列表
|
||||
]),
|
||||
};
|
||||
},
|
||||
});
|
||||
</script>
|
||||
|
||||
<style lang="scss">
|
||||
#app {
|
||||
width: 100%;
|
||||
height: 100%;
|
||||
display: flex;
|
||||
}
|
||||
|
||||
.m-editor {
|
||||
flex: 1;
|
||||
height: 100%;
|
||||
}
|
||||
</style>
|
||||
```
|
||||
|
||||
关于 Magic-Editor 组件，更多的属性配置详情请参考[编辑器API](/docs/api/editor.md)。
|
||||
|
||||
其中，**有四个需要注意的属性配置项**：`runtimeUrl` `values` `configs` `componentGroupList`。这是能让我们的编辑器正常运行的关键。
|
||||
|
||||
### runtimeUrl
|
||||
该配置涉及到 [runtime 概念](/docs/guide/conception.html#runtime)，魔方编辑器中心的模拟器画布，是一个 iframe（这里的 `runtimeUrl` 配置的，就是你提供的 iframe 的 url），其中渲染了一个 runtime，用来响应编辑器中的组件增删改等操作。
|
||||
|
||||
::: tip 如何快速得到一个 runtime
|
||||
如果要快速启动，可以使用[魔方项目源码](https://github.com/Tencent/tmagic-editor)中的 runtime，在提供的三个框架 vue2/vue3/react runtime 目录中选择一个，执行 `npm run build` 得到产物，并将产物放到你的项目中，此处的 runtimeUrl 指向你放置 playground.html 的路径。
|
||||
:::
|
||||
|
||||
### componentGroupList
|
||||
`componentGroupList` 是指定左侧组件库内容的配置。此处定义了在编辑器组件库中有什么组件。在添加的时候通过组件 `type` 来确定 runtime 中要渲染什么组件。可以参考 [componentGroupList 配置](/docs/api/editor.html#componentgrouplist)。
|
||||
|
||||
### propsConfigs/propsValues
|
||||
`propsConfigs` `propsValues` 和 `componentGroupList` 中声明的组件是一一对应的，通过 `type` 来识别属于哪个组件，该配置涉及的内容，就是组件的表单配置描述，在[组件开发中](/docs/component/introduction.html#组件开发)会通过 formConfig 配置来声明这份内容。
|
||||
|
||||
`configs` 既可以通过 hardcode 方式写上每个组件的表单配置，也可以通过组件打包方式得到对应内容，然后通过异步加载来载入。比如：
|
||||
```javascript
|
||||
setup() {
|
||||
asyncLoadJs(`/runtime/vue3/assets/config.js`).then(() => {
|
||||
propsConfigs.value = window.magicPresetConfigs;
|
||||
});
|
||||
asyncLoadJs(`/runtime/vue3/assets/value.js`).then(() => {
|
||||
propsValues.value = window.magicPresetValues;
|
||||
});
|
||||
}
|
||||
```
|
||||
|
||||
::: tip 如何快速得到一个 configs/values
|
||||
上述的 runtime 产物中，assets 目录中即包含一个 configs 文件，在你的项目组件初始化之后，异步加载它。并如上面代码中，赋值给 configs/values 即可。
|
||||
:::
|
||||
|
||||
### 更多
|
||||
通过上述步骤，可以快速得到一个初始化的简单编辑器。在编辑器中，对于使用者来说，需要了解的核心内容：
|
||||
- [魔方编辑器的基础概念](/docs/guide/conception)
|
||||
- [编辑器的产物 uiconfig]()
|
||||
- [runtime 的概念](/docs/page/introduction.html)
|
||||
- [如何实现一个 runtime](/docs/page/advanced.html)
|
||||
|
||||
除了上述内容外，文档的其他章节中，也会更深入的描述整个魔方的设计理念和实现细节。同时你也可以查看我们的[项目源码](https://github.com/Tencent/tmagic-editor)，从源码提供的 playground 和 runtime 示例来开发和理解魔方。
|
||||
45
docs/src/guide/introduction.md
Normal file
45
docs/src/guide/introduction.md
Normal file
@ -0,0 +1,45 @@
|
||||
# 介绍
|
||||
|
||||
魔方可视化开源项目（Magic）是从魔方平台演化而来的开源项目，意在提供一个供开发者快速搭建可视化搭建平台的解决方案。
|
||||
|
||||
<img src="https://image.video.qpic.cn/oa_88b7d-32_509802977_1635842258505918" alt="魔方demo图">
|
||||
|
||||
## 特性
|
||||
|
||||
- **所见即所得**，体验友好的拖拽编辑方式。
|
||||
- **丰富的拓展能力**，支持业务方自定义组件、插件、扩展编辑器能力。
|
||||
- **支持多种布局方式**，魔方的容器概念，支持配置活动时，自由组合嵌套业务组件，提供超强的组件布局方式。
|
||||
- **支持不同前端框架**，使用编辑器的业务方可以采用自己熟悉的前端框架，来开发自己的业务组件，比如vue2、vue3、react。
|
||||
- **强大的配置**，支持表单联动的配置能力。
|
||||
- **组件联动**，支持组件通信、组件联动，允许页面内各组件提供丰富配置能力。
|
||||
- **低代码**，支持针对具体配置的页面写代码，修改页面样式属性等，提供除组件外的高级编码能力。
|
||||
|
||||
## 编辑器
|
||||
|
||||
编辑器是可视化搭建平台的主要内容，其中包含以下内容：
|
||||
|
||||
- **编辑器**，承载整个拖拽布局的页面，包含了下述的其他页面可见元素。
|
||||
- **模拟器**，居中位置渲染了当前页面配置的组件内容，模拟真实页面的展示内容。
|
||||
- **组件库**，左侧展示当前业务下的相关组件内容，包含魔方提供的基础组件和业务自定义组件。
|
||||
- **组件树**，左侧展示当前页面添加的组件内容，以树状结构展示。
|
||||
- **表单配置**，右侧表单项目，展示由组件内提供的配置描述，提供修改组件行为的配置项。
|
||||
- **uiconfig 源码**，右上角的 📄 图标可以展示当前页面，各个组件配置，页面基础配置组合而成的配置源码。
|
||||
|
||||
通过编辑器，可以创建、编辑、保存一个活动页面。同时，魔方开源项目提供了一个页面搭建管理平台的示例：magic-admin，可以用于快速构建一个完整的页面可视化搭建系统。
|
||||
|
||||
## 核心库
|
||||
|
||||
- **@tmagic/editor** 实现一个可视化编辑器。
|
||||
- **@tmagic/form** 实现组件在编辑器中自定义表单配置。
|
||||
- **@tencent/magic-core** 实现对组件进行跨框架管理与一些通用复杂逻辑的实现。
|
||||
- **@tencent/magic-stage** 实现在编辑器中对组件的位置拖动与大小拖拉。
|
||||
- **@tencent/magic-ui** 提供一些基础组件。
|
||||
- **runtime** 实现在编辑器中对使用不同框架的组件的渲染。
|
||||
- **page** 项目提供最终页面发布的执行环境与组件构建。
|
||||
|
||||
可以查阅 Magic 的[源代码](https://github.com/Tencent/tmagic-editor)，与文档描述内容可以逐一对应上，希望文档内容可以为开发者带来比较好的开发体验。
|
||||
|
||||
## 谁在使用
|
||||
|
||||
- 腾讯视频：视频会员，体育会员，WETV 国际版，TV，doki 商城，小企鹅，小说，漫画
|
||||
- 腾讯会议
|
||||
142
docs/src/page/advanced.md
Normal file
142
docs/src/page/advanced.md
Normal file
@ -0,0 +1,142 @@
|
||||
# 深入
|
||||
本章详细介绍如何深入理解魔方的打包，以及如何根据需求定制，修改魔方的页面打包发布方案。页面发布、打包相关的定制化开发，需要使用魔方的业务方，搭建好基于开源魔方的管理平台、存储服务等配套设施。
|
||||
|
||||
## 实现一个 runtime
|
||||
在 [Magic-UI](/docs/guide/advanced/magic-ui.html) 部分，我们已经说过，runtime 和 UI 是配套实现的。每个版本的 runtime 都需要一个对应的 UI 来作为渲染器，实现渲染 uiconfig 呈现页面的功能。
|
||||
|
||||
### UI
|
||||
一个 UI 应该至少包含一个渲染器，来实现[页面渲染](/docs/guide/advanced/page.html)。同时可以提供一些基础组件。具体实现可以参考[Magic-UI](/docs/guide/advanced/magic-ui.html)。
|
||||
|
||||
### page
|
||||
runtime 的 `page` 部分，就是真实活动页面的渲染环境。发布出去的活动页都需要基于该部分来实现渲染功能。而 `page` 的主要逻辑，就是需要加载 UI，同时实现业务方需要的业务逻辑，比如：
|
||||
- 提供页面需要的全局 api
|
||||
- 业务需要的特殊实现逻辑
|
||||
- 加载第三方全局组件/插件等
|
||||
|
||||
具体的 page 实现示例，可以参考
|
||||
- [vue3 runtime](https://github.com/Tencent/tmagic-editor/blob/master/runtime/vue3/src/page)
|
||||
- [vue2 runtime](https://github.com/Tencent/tmagic-editor/blob/master/runtime/vue2/src/page)
|
||||
- [react runtime](https://github.com/Tencent/tmagic-editor/blob/master/runtime/react/src/page)
|
||||
|
||||
### playground
|
||||
runtime 的 `playground` 部分，和 `page` 做的事情几乎一致，业务方可以包含上述 `page` 所拥有的全部能力。但是，因为 playground 需要被编辑器加载，作为编辑器中页面模拟器的渲染容器，和编辑器通信，接受编辑器中组件的增删改查。所以，除了保持和 `page` 一样的渲染逻辑之外，`playground` 还要额外实现一套既定通信内容和 api，才能实现和编辑器的通信功能。
|
||||
|
||||
#### onRuntimeReady
|
||||
**在 playground 页面渲染后**，需要调用接口通知编辑器完成加载。该调用需要传入一个参数 API，即挂载了增删改查功能的对象示例，提供给编辑器。
|
||||
```javascript
|
||||
window.magic?.onRuntimeReady(API)
|
||||
```
|
||||
|
||||
#### onPageElUpdate
|
||||
**playground 在每次更新了页面配置后**，调用一次 onPageElUpdate 并传入一个 DOM 节点，该方法作用是传入一个页面渲染组件的根节点，用来告知编辑器的模拟器遮罩如何作出反应。
|
||||
```javascript
|
||||
window.magic.onPageElUpdate(document.querySelector('.magic-ui-page'));
|
||||
```
|
||||
|
||||
#### 提供 API
|
||||
| API | 说明 | 参数 |
|
||||
|---------- |-------- |---------- |
|
||||
|updateRootConfig| 根节点更新 | `root: MApp` |
|
||||
|updatePageId| 更新当前页面 id | `id: string` |
|
||||
|select| 选中组件 | `id: string`|
|
||||
|add| 增加组件 | { `config` , `root` }: `UpdateData` |
|
||||
|update| 更新组件 | { `config` , `root` }: `UpdateData` |
|
||||
|remove| 删除组件 | { `config` , `root` }: `UpdateData` |
|
||||
|sortNode| 组件在容器间排序 |{ `src` , `dist`, `root` }: `SortEventData` |
|
||||
|
||||
runtime 的实现示例，可以参考魔方提供的：
|
||||
- [vue3 runtime](https://github.com/Tencent/tmagic-editor/blob/master/runtime/vue3)
|
||||
- [vue2 runtime](https://github.com/Tencent/tmagic-editor/blob/master/runtime/vue2)
|
||||
- [react runtime](https://github.com/Tencent/tmagic-editor/blob/master/runtime/react)
|
||||
|
||||
## 打包原理
|
||||
在魔方的示例打包方案中，是基于 runtime 代码，以及 runtime 的打包配置进行的打包构建，将构建得到的产物发布，在魔方页面最终发布时，通过加载构建产物和 uiconfig 来实现页面渲染。
|
||||
|
||||
### 打包配置
|
||||
在 vite.config.ts 中有如下配置：
|
||||
```javascript
|
||||
export default {
|
||||
build: {
|
||||
sourcemap: true,
|
||||
minify: false,
|
||||
|
||||
rollupOptions: {
|
||||
input: {
|
||||
page: './page.html',
|
||||
playground: './playground.html',
|
||||
components: './src/comp-entry.ts',
|
||||
config: './src/config-entry.ts',
|
||||
value: './src/value-entry.ts',
|
||||
},
|
||||
output: {
|
||||
entryFileNames: 'assets/[name].js',
|
||||
},
|
||||
},
|
||||
}
|
||||
}
|
||||
```
|
||||
打包时，即会生成对应的静态资源，我们在对应地方使用时，加载对应入口文件的打包产物即可。其中 page.html 和 playground.html 在示例项目中，而另外三个入口是在打包过程中动态生成的。
|
||||
|
||||
### 打包产物
|
||||
执行打包命令`npm run build`后，会在 runtime/src 中生成三个入口文件
|
||||
```
|
||||
comp-entry.ts
|
||||
config-entry.ts
|
||||
value-entry.ts
|
||||
```
|
||||
|
||||
这三个入口文件是基于 scripts/units.js 中描述的组件信息生成的，units.js 中的组件信息如何获取和生成，需要由使用魔方代码的业务方自行处理。更多关于魔方组件规范相关可以查阅[组件开发文档](/docs/component/introduction.html)。示例的 units.js 文件中，组件描述是以组件在魔方中定义的 type 为 key，包名（或本地路径）为 value 的对象。
|
||||
|
||||
魔方的[打包脚本](/docs/page/introduction.html#打包脚本)会根据这个组件声明，进行分析，生成上述三个入口文件：
|
||||
::: tip 生成步骤为
|
||||
1. 分析包结构，是否符合魔方组件规范
|
||||
2. 分析每个组件包内的 config value 和组件逻辑代码的入口
|
||||
3. 生成包含所有组件信息的三个入口文件
|
||||
:::
|
||||
|
||||
同时得到打包产物 dist 目录。包含了如下的主要文件:
|
||||
```
|
||||
|----dist
|
||||
|----assets
|
||||
| |----components.js
|
||||
| |----config.js
|
||||
| |----value.js
|
||||
|----page.html
|
||||
|----playground.html
|
||||
```
|
||||
|
||||
::: tip 各个文件作用说明
|
||||
- page.html 即真实活动页渲染时，用户加载的页面框架，魔方在发布时，会将活动页面所需的信息注入到 page.html 中，让用户加载了页面后，能拉取到对应的活动信息。
|
||||
- playground.html 是编辑器中模拟器使用的静态资源。魔方的模拟器使用 iframe 渲染，即加载了 playground.html，并注入编辑器中的配置信息，实现页面渲染。
|
||||
- component.js 是所有自定义组件的入口，在 runtime 中需要加载组件，交由渲染器渲染页面。
|
||||
- config.js 和 value.js 是编辑器中的各个组件的表单配置信息和表单初始值的入口，仅在编辑器中会被使用到。
|
||||
:::
|
||||
|
||||
|
||||
打开活动页面加载的产物资源：
|
||||
<img src="https://image.video.qpic.cn/oa_88b7d-36_1166112390_1633782654899174" width="100%" alt="魔方 runtime page 示意图">
|
||||
|
||||
在编辑器中加载的产物资源：
|
||||
<img src="https://image.video.qpic.cn/oa_fd3c9c-2_217204702_1633782657315434" width="100%" alt="魔方 runtime playground 示意图">
|
||||
|
||||
### 页面发布
|
||||
如介绍中提到的，魔方页面发布方案，是对构建产物 page.html 进行活动信息注入。活动信息就是搭建平台存储的页面配置。发布时，将注入活动信息的 page.html 发布出去即可。
|
||||
|
||||
## 版本管理
|
||||
基于上一步提到的打包原理，每次执行`npm run build`后，得到的产物都可以进行归档编号，存为版本。涉及到的组件改动和新增修改，体现在各个版本中。
|
||||
|
||||
<img src="https://image.video.qpic.cn/oa_88b7d-32_1233288257_1633783105283986" width="40%" alt="版本选择">
|
||||
|
||||
版本管理具体如何实现取决于使用魔方的业务方相关，拥有版本管理能力，具有如下优点：
|
||||
1. 对于已经配置好发布的活动，使用固定版本，不会被新版本的特性影响，保证活动线上稳定运行
|
||||
2. 发布的新版本如果出现问题，可以及时回退选择使用旧版本
|
||||
|
||||
## 结合业务定制
|
||||
魔方的静态资源构建，活动配置保存，页面发布，在魔方的提供的示例方案中，流程是：
|
||||
1. 触发构建，执行流水线，基于 runtime 执行 build
|
||||
2. 将构建产物归档推送至 cdn，存为一个ui版本
|
||||
3. 活动配保存后，活动发布时，将活动配置发布至 CDN 存储为 uiconfig.js，同时根据当前活动使用的ui版本，获取到 page.html，将 uiconfig.js 引用方式以 script 标签形式写入。
|
||||
4. 将注入信息的 page.html 发布为活动静态资源 act.html
|
||||
5. 线上可加载 act.html 访问活动
|
||||
|
||||
其中各个步骤的定制，可以交由业务方根据魔方提供的示例进行自定义修改。
|
||||
106
docs/src/page/introduction.md
Normal file
106
docs/src/page/introduction.md
Normal file
@ -0,0 +1,106 @@
|
||||
# 介绍
|
||||
本章主要介绍魔方页面打包、发布相关的基础概念，打包原理，打包方案实现。使用了魔方开源代码的业务方可以自由定制页面的打包构建方案。
|
||||
|
||||
## 编辑器产物 uiconfig
|
||||
编辑器中最终保存得到的的配置结果，同时也是魔方页面最终渲染的描述文件，就是一份 JS schema 形式的 uiconfig。其具体形式就是在 [JS Schema](/docs/guide/advanced/js-schema.html#uiconfig) 我们示例中提到的内容。
|
||||
|
||||
在魔方编辑器中，所有的操作和配置信息，最终都保存成这一份 uiconfig。这份配置在魔方 runtime 中被加载和渲染，最终呈现出魔方活动页。
|
||||
|
||||
## runtime
|
||||
runtime 的概念，是理解魔方活动页运行的重要感念，runtime 是承载魔方活动页面的运行环境。可视化页面需要在魔方编辑器中搭建、渲染，通过模拟器所见即所得。搭建完成后，保存配置并发布，然后渲染到真实页面。其中涉及到两个不同的 runtime：
|
||||
- 编辑器中的模拟器
|
||||
- 终端打开真实页面
|
||||
|
||||
所以更深入描述，runtime 是魔方页面的渲染环境，提供不同场景下的能力封装。如果理解了魔方的设计，阅读了魔方的源码，可以发现，runtime 只是对魔方的渲染器做了一层包装，在不同 runtime 中，魔方的渲染逻辑和组件代码都是相同的。
|
||||
|
||||
并且，由于魔方在编辑器中的模拟器是通过 iframe 渲染的，和魔方平台本身可以做到框架解耦，所以 runtime 也可以用不同框架开发。目前魔方提供了 vue2/vue3 和 react 的 runtime 示例。
|
||||
|
||||
各个 runtime 的作用除了作为不同场景下的渲染环境，同时也是不同环境的打包构建载体。魔方示例代码中的打包就是基于 runtime 进行的。
|
||||
|
||||
### 业务相关
|
||||
由于 runtime 是页面渲染的承载环境，其中会加载 Magic-UI 以及各个业务组件，业务发布活动页也是基于 runtime，所以在 runtime 中实现业务方的自定逻辑是最合适的。runtime 可以提供一些全局 API，供业务组件调用。我们可以把下面的模拟器中的 runtime 视为一个业务方runtime。
|
||||
|
||||
魔方提供了三个版本的 runtime 示例，可以参考：
|
||||
- [vue3 runtime](https://github.com/Tencent/tmagic-editor/blob/master/runtime/vue3)
|
||||
- [vue2 runtime](https://github.com/Tencent/tmagic-editor/blob/master/runtime/vue2)
|
||||
- [react runtime](https://github.com/Tencent/tmagic-editor/blob/master/runtime/react)
|
||||
|
||||
### 真实页面渲染（Page）
|
||||
这一部分，对应的是 runtime 中的 page。即把魔方保存后的配置进行加载、解析、渲染，然后呈现页面的过程。
|
||||
<img src="https://image.video.qpic.cn/oa_88b7d-37_1139402464_1633761800125955" width="100%" alt="魔方 runtime page 示意图">
|
||||
|
||||
### 模拟器中的页面渲染（Playground）
|
||||
这一部分，对应的是 runtime 中的 playground。其实仔细查看源码，playground 和 page runtime 的差异，在于 playground 中需要响应编辑器中用户的操作：
|
||||
- 组件的增删改
|
||||
- 表单配置修改
|
||||
|
||||
响应用户配置修改的操作代码并不需要在用户打开的页面被使用到，这是两个 runtime 的主要差异。
|
||||
<img src="https://image.video.qpic.cn/oa_88b7d-32_528694230_1633762153731370" width="100%" alt="魔方 runtime playground 示意图">
|
||||
|
||||
## 打包脚本
|
||||
在魔方各个框架的 runtime 目录中，有对应的 scripts 打包脚本目录。由于各个框架的 runtime 间有可能有不同的打包方式，所以为了架构职责明确，我们将示例打包代码分别放入对应 runtime 的 scripts 目录中。
|
||||
|
||||
详细的打包脚本，可以参考调用[魔方打包脚本 generateEntry](https://github.com/Tencent/tmagic-editor/blob/master/runtime/scripts/generateEntry.js)。
|
||||
|
||||
在 runtime 中，我们通过 vite.config.ts 定义了打包入口文件，在 package.json 中声明了打包命令。你可以进入对应的 runtime 目录中尝试执行
|
||||
```bash
|
||||
npm i
|
||||
npm run build
|
||||
```
|
||||
|
||||
我们就可以得到打包产物 dist 目录。其中有我们在线上活动页面使用的 page.html 和编辑器模拟器使用的 playground.html 两个 runtime 页面框架。
|
||||
|
||||
## 页面发布
|
||||
魔方的页面发布，目前使用的是静态资源发布。而所有配置出的活动页唯一的区别，就是配置信息。我们发布页面时，将页面的配置信息插入到 page.html 中，然后将修改后的 page.html 发布至 CDN，得到活动页面。
|
||||
|
||||
原始的 page.html 页面框架
|
||||
```html
|
||||
<!DOCTYPE html>
|
||||
<html lang="en">
|
||||
<head>
|
||||
<meta charset="UTF-8" />
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
|
||||
<title>Magic App</title>
|
||||
<script src="https://unpkg.com/vue@next/dist/vue.runtime.global.js"></script>
|
||||
<script type="module" crossorigin src="assets/page.js"></script>
|
||||
<link rel="modulepreload" href="assets/App.10f9c9e1.js">
|
||||
<link rel="modulepreload" href="assets/vendor.1dc07625.js">
|
||||
<link rel="modulepreload" href="assets/index.3456a0b9.js">
|
||||
<link rel="modulepreload" href="assets/components.js">
|
||||
<link rel="stylesheet" href="assets/App.91ddd4a6.css">
|
||||
<link rel="stylesheet" href="assets/page.6c73043b.css">
|
||||
</head>
|
||||
<body>
|
||||
<div id="app"></div>
|
||||
|
||||
</body>
|
||||
</html>
|
||||
```
|
||||
|
||||
插入活动信息后的 page.html
|
||||
```html
|
||||
<!DOCTYPE html>
|
||||
<html lang="en">
|
||||
<head>
|
||||
<meta charset="UTF-8" />
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
|
||||
<title>Publish Page</title>
|
||||
<!-- 这里插入了活动相关的 uiconfig.js -->
|
||||
<script type="module" src="./uiconfig.js"></script>
|
||||
<script src="https://unpkg.com/vue@next/dist/vue.runtime.global.js"></script>
|
||||
<script type="module" crossorigin src="assets/page.js"></script>
|
||||
<link rel="modulepreload" href="assets/App.10f9c9e1.js">
|
||||
<link rel="modulepreload" href="assets/vendor.1dc07625.js">
|
||||
<link rel="modulepreload" href="assets/index.3456a0b9.js">
|
||||
<link rel="modulepreload" href="assets/components.js">
|
||||
<link rel="stylesheet" href="assets/App.91ddd4a6.css">
|
||||
<link rel="stylesheet" href="assets/page.6c73043b.css">
|
||||
</head>
|
||||
<body>
|
||||
<div id="app"></div>
|
||||
|
||||
</body>
|
||||
</html>
|
||||
|
||||
```
|
||||
|
||||
@ -10,7 +10,7 @@
|
||||
"lint": "eslint . --ext .js,.vue,.ts,.tsx",
|
||||
"lint-fix": "eslint . --fix --ext .vue,.js,.ts,.tsx",
|
||||
"playground": "npx lerna run dev --scope tmagic-playground --scope runtime-vue3 --parallel",
|
||||
"build": "npx lerna run build --parallel",
|
||||
"build": "npx lerna run build --scope tmagic-playground --scope runtime-vue3 --scope runtime-vue2 --scope runtime-react --scope @tmagic/* --parallel",
|
||||
"postbuild": "npx mkdir playground/dist/runtime && npx cp -r runtime/vue2/dist ./playground/dist/runtime/vue2 && npx cp -r runtime/vue3/dist ./playground/dist/runtime/vue3 && npx cp -r runtime/react/dist ./playground/dist/runtime/react",
|
||||
"docs": "cd docs && npm run doc:dev",
|
||||
"page": "cd page && vite",
|
||||
|
||||
2
playground/package-lock.json
generated
2
playground/package-lock.json
generated
@ -1,5 +1,5 @@
|
||||
{
|
||||
"name": "magic-playground",
|
||||
"name": "tmagic-playground",
|
||||
"version": "1.0.0-beta.1",
|
||||
"lockfileVersion": 1,
|
||||
"requires": true,
|
||||
|
||||
@ -30,19 +30,19 @@ import { Coin, Connection, Document, FolderOpened, SwitchButton, Tickets } from
|
||||
import { ElMessage } from 'element-plus';
|
||||
import serialize from 'serialize-javascript';
|
||||
|
||||
import type { MagicEditor, MenuBarData, MoveableOptions } from '@tmagic/editor';
|
||||
import type { MenuBarData, MoveableOptions, TMagicEditor } from '@tmagic/editor';
|
||||
import StageCore from '@tmagic/stage';
|
||||
import { asyncLoadJs } from '@tmagic/utils';
|
||||
|
||||
import config from '../config';
|
||||
|
||||
const RUNTIME_PATH = '/runtime/vue3';
|
||||
const RUNTIME_PATH = '/tmagic-editor/playground/runtime/vue3';
|
||||
|
||||
export default defineComponent({
|
||||
name: 'EditorApp',
|
||||
|
||||
setup() {
|
||||
const editor = ref<InstanceType<typeof MagicEditor>>();
|
||||
const editor = ref<InstanceType<typeof TMagicEditor>>();
|
||||
const previewVisible = ref(false);
|
||||
const value = ref(config);
|
||||
const defaultSelected = ref(config.items[0].id);
|
||||
|
||||
@ -26,6 +26,8 @@ import vueJsx from '@vitejs/plugin-vue-jsx';
|
||||
export default defineConfig({
|
||||
plugins: [vue(), vueJsx()],
|
||||
|
||||
base: '/tmagic-editor/playground',
|
||||
|
||||
resolve: {
|
||||
alias: [
|
||||
{ find: /@editor/, replacement: path.join(__dirname, '../packages/editor/src') },
|
||||
@ -52,23 +54,20 @@ export default defineConfig({
|
||||
host: '0.0.0.0',
|
||||
port: 8098,
|
||||
proxy: {
|
||||
'^/runtime/react': {
|
||||
'^/tmagic-editor/playground/runtime/react': {
|
||||
target: 'http://127.0.0.1:8076',
|
||||
changeOrigin: true,
|
||||
prependPath: false,
|
||||
rewrite: (path: string) => path.replace(/^\/runtime\/react/, ''),
|
||||
},
|
||||
'^/runtime/vue2': {
|
||||
'^/tmagic-editor/playground/runtime/vue2': {
|
||||
target: 'http://127.0.0.1:8077',
|
||||
changeOrigin: true,
|
||||
prependPath: false,
|
||||
rewrite: (path: string) => path.replace(/^\/runtime\/vue2/, ''),
|
||||
},
|
||||
'^/runtime/vue3': {
|
||||
'^/tmagic-editor/playground/runtime/vue3': {
|
||||
target: 'http://127.0.0.1:8078',
|
||||
changeOrigin: true,
|
||||
prependPath: false,
|
||||
rewrite: (path: string) => path.replace(/^\/runtime\/vue3/, ''),
|
||||
},
|
||||
},
|
||||
},
|
||||
|
||||
@ -27,7 +27,7 @@ import { getUrlParam } from '@tmagic/utils';
|
||||
|
||||
import App from './App';
|
||||
|
||||
const componentUrl = '/runtime/react/assets/components.js';
|
||||
const componentUrl = '/tamgic-editor/playground/runtime/react/assets/components.js';
|
||||
|
||||
import(componentUrl).then(() => {
|
||||
const { components } = window.magicPresetComponents;
|
||||
|
||||
@ -23,7 +23,7 @@ import reactRefresh from '@vitejs/plugin-react-refresh';
|
||||
|
||||
// https://vitejs.dev/config/
|
||||
export default defineConfig({
|
||||
base: '',
|
||||
base: '/tmagic-editor/playground/runtime/react',
|
||||
plugins: [reactRefresh()],
|
||||
|
||||
resolve: {
|
||||
|
||||
@ -20,7 +20,7 @@ import Vue from 'vue';
|
||||
|
||||
import App from './App.vue';
|
||||
|
||||
const componentUrl = '/runtime/vue2/assets/components.js';
|
||||
const componentUrl = '/tamgic-editor/playground/runtime/vue2/assets/components.js';
|
||||
|
||||
import(componentUrl).then(() => {
|
||||
const { components, plugins } = window.magicPresetComponents;
|
||||
|
||||
@ -24,7 +24,7 @@ import { createVuePlugin } from 'vite-plugin-vue2';
|
||||
import externalGlobals from 'rollup-plugin-external-globals';
|
||||
|
||||
export default defineConfig({
|
||||
base: '',
|
||||
base: '/tmagic-editor/playground/runtime/vue2',
|
||||
plugins: [createVuePlugin(), externalGlobals({ vue: 'Vue' }, { exclude: ['page.html', 'playground.html'] })],
|
||||
|
||||
resolve: {
|
||||
|
||||
@ -20,7 +20,7 @@ import { createApp } from 'vue';
|
||||
|
||||
import App from './App.vue';
|
||||
|
||||
const componentUrl = '/runtime/vue3/assets/components.js';
|
||||
const componentUrl = '/tmagic-editor/playground/runtime/vue3/assets/components.js';
|
||||
|
||||
import(componentUrl).then(() => {
|
||||
const magicApp = createApp(App);
|
||||
|
||||
@ -25,7 +25,7 @@ import vueJsx from '@vitejs/plugin-vue-jsx';
|
||||
import externalGlobals from 'rollup-plugin-external-globals';
|
||||
|
||||
export default defineConfig({
|
||||
base: '',
|
||||
base: '/tmagic-editor/playground/runtime/vue3',
|
||||
plugins: [vue(), vueJsx(), externalGlobals({ vue: 'Vue' }, { exclude: ['page.html', 'playground.html'] })],
|
||||
|
||||
resolve: {
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user