Skip to content

Commit e3764a2

Browse files
wwsunwwsun
committed
docs: update components guide
1 parent 1106f15 commit e3764a2

File tree

5 files changed

+279
-20
lines changed

5 files changed

+279
-20
lines changed

‎docs/designer/customize/editor.mdx

+8-3
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,10 @@
11
# 编辑器自定义
22

3-
:::tip
4-
正在编写中，敬请期待。
5-
:::
3+
Tango 设计器提供了默认基于 monaco-editor 的代码编辑器实现，你可以根据自己的需求，自定义代码编辑器的实现。用户需要将代码文件的变化同步给引擎，具体包括：
4+
5+
- 添加文件: `workspace.addFile`
6+
- 删除文件：`workspace.removeFile`
7+
- 重命名文件：`workspace.renameFile`
8+
- 代码变更：`workspace.updateFile`
9+
10+
具体可以参考引擎的实现：https://github.com/NetEase/tango/blob/main/packages/designer/src/editor.tsx

‎docs/designer/deploy/component.mdx

+144
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,144 @@
1+
# 组件接入
2+
3+
Tango 引擎借助用户传入的 **组件配置** 信息识别组件，并通过组件配置信息渲染组件配置面板。在设计器接入环节中，我们介绍了可以在 `Workspace` 初始化的时候传入 `prototypes` 参数用来提供组件配置信息。组件接入，主要是指将组件的配置信息传入给引擎。
4+
5+
`prototypes` 信息在引擎中的主要使用场景包括：
6+
7+
- 生成代码片段：当用户通过拖拽等手段在设计器中添加组件时，引擎会根据组件配置信息生成对应的代码片段。
8+
- 渲染组件配置面板：当用户选中某个组件时，设计器会根据组件配置信息渲染对应的组件配置面板。
9+
10+
```ts
11+
import { createEngine, Workspace } from '@music163/tango-core';
12+
13+
const mockPrototypes = {
14+
Button: {
15+
/* Button Config */
16+
},
17+
Input: {
18+
/* Input Config */
19+
},
20+
//...其他组件配置
21+
};
22+
23+
// 工作区初始化：将项目文件传入给设计器
24+
const workspace = new Workspace({
25+
entry: '/src/index.js',
26+
files: mockFiles, // 文件参数可以参考示例应用
27+
prototypes: mockPrototypes, // 组件配置信息可以参考示例应用
28+
});
29+
```
30+
31+
组件配置信息的类型定义可以参考 [IComponentPrototype](https://netease.github.io/tango/interfaces/_music163_tango_helpers.IComponentPrototype.html)。
32+
33+
## 组件库
34+
35+
组件库通常包括多个子组件，每个子组件都有自己的配置信息。在设计器中，我们可以通过组件库的方式将多个子组件的配置信息传入给引擎。示例的配置代码如下：
36+
37+
```ts
38+
export const Button: ComponentPrototypeType = {
39+
name: 'Button',
40+
title: '按钮',
41+
package: '@music163/tango-mail',
42+
icon: 'icon-anniu',
43+
help: '按钮用于触发一个操作',
44+
type: 'element',
45+
props: [
46+
{
47+
name: 'href',
48+
title: '跳转链接',
49+
setter: 'textSetter',
50+
},
51+
{
52+
name: 'children',
53+
title: '文案',
54+
setter: 'textSetter',
55+
initValue: '按钮',
56+
},
57+
],
58+
};
59+
60+
export const CodeBlock: ComponentPrototypeType = {
61+
name: 'CodeBlock',
62+
title: '代码块',
63+
package: '@music163/tango-mail',
64+
icon: 'icon-code',
65+
type: 'element',
66+
props: [
67+
{
68+
name: 'code',
69+
title: '代码',
70+
setter: 'codeSetter',
71+
initValue: "export foo = 'foo';",
72+
},
73+
{
74+
name: 'lineNumbers',
75+
title: '展示行号',
76+
setter: 'boolSetter',
77+
initValue: true,
78+
},
79+
{
80+
name: 'language',
81+
title: '语言',
82+
setter: 'textSetter',
83+
initValue: 'javascript',
84+
tip: '语言列表参考 Prism.js',
85+
docs: 'https://prismjs.com/#supported-languages',
86+
},
87+
],
88+
};
89+
```
90+
91+
也可以参考一个示例组件库 `@music163/tango-mail` 的配置信息：[https://github.com/NetEase/tango-components/tree/main/packages/mail/src/prototypes](https://github.com/NetEase/tango-components/tree/main/packages/mail/src/prototypes)
92+
93+
## 业务组件
94+
95+
对于业务组件而言，通常导出为单个组件，如果导出多个组件，可以参考组件库的方式。单个组件的配置信息示例如下：
96+
97+
```ts
98+
const bizToggleButtonPrototype: ComponentPrototypeType = {
99+
name: 'CtPcToggleButton',
100+
exportType: 'defaultExport', // 指定了组件的导出方式为 “默认导出”
101+
package: '@music163/ct-pc-toggle-button',
102+
title: '示例业务组件',
103+
icon: 'icon-tupian',
104+
type: 'element',
105+
hasChildren: false,
106+
props: [
107+
{
108+
name: 'checked',
109+
title: '是否选中',
110+
setter: 'boolSetter',
111+
defaultValue: false,
112+
},
113+
{
114+
name: 'children',
115+
title: '文本',
116+
setter: 'textSetter',
117+
initValue: '按钮',
118+
},
119+
],
120+
};
121+
```
122+
123+
与组件库相比，业务组件的配置信息中多了 `exportType` 字段，用来指定组件的导出方式，对于单个组件而言，通常为 默认导出 模式。导出方式的差异，决定了代码生成时的导入语句的不同。
124+
125+
## 代码片段
126+
127+
在 Tango 设计器中，还支持代码片段级别的配置信息，允许将定义好的代码片段拖拽到设计器中。代码片段的配置信息示例如下：
128+
129+
```ts
130+
const Snippet2ColumnLayout: IComponentPrototype = {
131+
name: 'Snippet2ColumnLayout',
132+
title: '两列布局',
133+
icon: 'icon-columns',
134+
type: 'snippet', // 声明为代码片段类型
135+
package: '@music163/antd',
136+
initChildren: `
137+
<Columns columns={12}>
138+
<Column colSpan={6}></Column>
139+
<Column colSpan={6}></Column>
140+
</Columns>
141+
`,
142+
relatedImports: ['Columns', 'Column'],
143+
};
144+
```

‎docs/designer/deploy/designer.mdx

+120-17
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@
55
1. clone 官方示例代码，按照文档说明直接启动项目。
66
2. 手工引入设计器的 npm 包，自定义配置、启动、运行。
77

8-
## 方法1: 通过示例代码启动设计器
8+
## 通过示例代码启动设计器
99

1010
你可以使用 Tango 代码仓库内的 `/apps/playground` 复制出来，作为基础应用并改造。你需要移除 `.umirc.ts` 中与 `resolvePackageIndex()` 方法相关的配置，具体可直接参考我们的示例应用的 [`.umirc.ts`](https://github.com/NetEase/tango-playground/blob/master/.umirc.ts) 文件，修改后再手动安装 `@music163/tango-designer` 即可启动项目。
1111

@@ -23,15 +23,15 @@
2323
nvm use 16
2424
```
2525

26-
2. 克隆项目仓库：
26+
2. 克隆项目仓库：
2727

2828
```sh
2929
git clone https://github.com/NetEase/tango-playground.git --depth 1
3030
```
3131

3232
也可以直接下载 [最新代码的压缩包](https://github.com/NetEase/tango-playground/archive/refs/heads/master.zip) 并解压。
3333

34-
3. 安装项目依赖：
34+
3. 安装项目依赖：
3535

3636
```sh
3737
cd tango-playground
@@ -45,24 +45,24 @@
4545
127.0.0.1 local.example.com
4646
```
4747

48-
5. 修改 `/src/pages/index.tsx`，将 `<Sandbox>` 的 `bundlerURL` 替换为已部署的沙箱的地址。
48+
5. 修改 `/src/pages/index.tsx`，将 `<Sandbox>` 的 `bundlerURL` 替换为已部署的沙箱的地址。
4949

5050
```jsx
5151
<Sandbox
52-
bundlerURL="https://sandbox.example.com"
53-
onMessage={(e) => {
54-
// ...
55-
}}
52+
bundlerURL="https://sandbox.example.com"
53+
onMessage={(e) => {
54+
// ...
55+
}}
5656
/>
5757
```
5858

59-
6. 修改 `/package.json`，修改 `dev` 脚本的 `HOST` 环境变量，将其改为上述配置在 hosts 文件时定义的开发域名。
59+
6. 修改 `/package.json`，修改 `dev` 脚本的 `HOST` 环境变量，将其改为上述配置在 hosts 文件时定义的开发域名。
6060

6161
```
6262
"dev": "HOST=local.example.com PORT=8001 umi dev",
6363
```
6464

65-
7. 使用脚手架的指令启动项目开始开发，启动后需要通过之前 hosts 配置的域名打开本地项目，并信任自签发的证书。
65+
7. 使用脚手架的指令启动项目开始开发，启动后需要通过之前 hosts 配置的域名打开本地项目，并信任自签发的证书。
6666

6767
```sh
6868
# 经过上述修改启动后，可通过 https://local.example.com:8001 访问项目
@@ -73,12 +73,115 @@
7373

7474
![](https://p6.music.126.net/obj/wo3DlcOGw6DClTvDisK1/33392683897/c72b/f6f2/2944/a481233c752a9e74213fa15aa516b6f0.png)
7575

76-
77-
## 方法2: 手工引入设计器的 npm 包
78-
79-
WIP
80-
81-
8276
## 配置低代码设计器
8377

84-
请参考 [设计器自定义](../customize/panels) 部分。
78+
Tango 设计器是一个独立的基于 React 实现的 npm 包，你可以通过 npm 或 yarn 来安装 `@music163/tango-designer` 使用。
79+
80+
### 引擎初始化
81+
82+
Tango 引擎遵循最小内核的原则，其实现非常的精简，提供了引擎实现的基本规范，和默认的基于源码解析操纵的引擎实现。意味着，你可以快速的初始化一个基于源码解析操纵的设计器引擎。当然，也可以根据自己的需要，按照引擎的规范实现自定义的实现。
83+
84+
```js
85+
import { createEngine, Workspace } from '@music163/tango-core';
86+
// 工作区初始化：将项目文件传入给设计器
87+
const workspace = new Workspace({
88+
entry: '/src/index.js',
89+
files: mockFiles, // 文件参数可以参考示例应用
90+
prototypes: mockPrototypes, // 组件配置信息可以参考示例应用
91+
});
92+
93+
// 引擎初始化：将工作区传入给设计器引擎，完成设计器的初始化
94+
const engine = createEngine({
95+
workspace,
96+
});
97+
```
98+
99+
关于组件配置信息可以参考 [组件接入](./component) 部分。
100+
101+
### 设计器初始化和布局
102+
103+
Tango 提供了基于 React 实现的开箱即用的设计器组件，你可以借助这些组件快速的组装一个基本的低代码设计器。也可以根据实际需要，开发自定义的设计器组件。
104+
105+
关于设计器组件的介绍和使用可以参考 [设计器自定义](../customize/panels) 部分。
106+
107+
```jsx
108+
import {
109+
Designer,
110+
DesignerPanel,
111+
SettingPanel,
112+
Sidebar,
113+
Toolbar,
114+
WorkspacePanel,
115+
WorkspaceView,
116+
CodeEditor,
117+
Sandbox,
118+
} from '@music163/tango-designer';
119+
120+
export default function App() {
121+
return (
122+
<Designer engine={engine}>
123+
<DesignerPanel
124+
logo="Your Logo"
125+
actions={
126+
<Box px="l">
127+
<Toolbar>
128+
<Toolbar.Item key="history" placement="left" />
129+
<Toolbar.Item key="preview" placement="left" />
130+
<Toolbar.Item key="modeSwitch" placement="right" />
131+
<Toolbar.Item key="togglePanel" placement="right" />
132+
</Toolbar>
133+
</Box>
134+
}>
135+
<Sidebar>
136+
<Sidebar.Item
137+
key="components"
138+
label="组件"
139+
icon={<AppstoreAddOutlined />}
140+
widgetProps={{
141+
menuData, // 配置设计器的组件列表
142+
}}
143+
/>
144+
<Sidebar.Item key="outline" label="结构" icon={<BuildOutlined />} />
145+
<Sidebar.Item
146+
key="dependency"
147+
label="依赖"
148+
icon={<ClusterOutlined />}
149+
isFloat
150+
width={800}
151+
/>
152+
</Sidebar>
153+
<WorkspacePanel>
154+
<WorkspaceView mode="design">
155+
<Sandbox />
156+
</WorkspaceView>
157+
<WorkspaceView mode="code">
158+
<CodeEditor />
159+
</WorkspaceView>
160+
</WorkspacePanel>
161+
<SettingPanel />
162+
</DesignerPanel>
163+
</Designer>
164+
);
165+
}
166+
```
167+
168+
### 配置设计器的组件列表
169+
170+
设计器的组件列表供用户快速的了解到当前应用支持的组件，可以通过 menuData 配置项传入给侧边栏的组件面板。定义格式如下：
171+
172+
```js
173+
const menuData = {
174+
common: [
175+
{
176+
title: '常用',
177+
items: ['Button', 'Section', 'Columns', 'Column', 'Box', 'Text'],
178+
},
179+
{
180+
title: '输入',
181+
items: ['Input', 'InputNumber', 'Select'],
182+
},
183+
],
184+
};
185+
```
186+
187+
值得注意的是，menuData 定义的组件名，需要在引擎的 prototypes 参数中提前定义好，以便引擎能够正确的解析和渲染组件的配置参数。

‎sidebars.ts

+1
Original file line numberDiff line numberDiff line change
@@ -22,6 +22,7 @@ const sidebars: SidebarsConfig = {
2222
label: '接入指南',
2323
items: [
2424
'designer/deploy/designer',
25+
'designer/deploy/component',
2526
'designer/deploy/sandbox',
2627
'designer/deploy/server',
2728
],

‎src/css/custom.css

+6
Original file line numberDiff line numberDiff line change
@@ -28,3 +28,9 @@
2828
--ifm-color-primary-lightest: #4fddbf;
2929
--docusaurus-highlighted-code-line-bg: rgba(0, 0, 0, 0.3);
3030
}
31+
32+
.markdown img {
33+
border: 1px solid var(--ifm-color-emphasis-200);
34+
border-radius: var(--ifm-global-radius);
35+
box-shadow: var(--ifm-global-shadow-lw);
36+
}

0 commit comments

Comments
 (0)