docs: update components guide

NetEase · Jun 13, 2024 · e3764a2 · e3764a2
1 parent 1106f15
commit e3764a2
Show file tree

Hide file tree

Showing 5 changed files with 279 additions and 20 deletions.
diff --git a/docs/designer/customize/editor.mdx b/docs/designer/customize/editor.mdx
@@ -1,5 +1,10 @@
 # 编辑器自定义
 
-:::tip
-正在编写中，敬请期待。
-:::
+Tango 设计器提供了默认基于 monaco-editor 的代码编辑器实现，你可以根据自己的需求，自定义代码编辑器的实现。用户需要将代码文件的变化同步给引擎，具体包括：
+
+- 添加文件: `workspace.addFile`
+- 删除文件：`workspace.removeFile`
+- 重命名文件：`workspace.renameFile`
+- 代码变更：`workspace.updateFile`
+
+具体可以参考引擎的实现：https://github.com/NetEase/tango/blob/main/packages/designer/src/editor.tsx
diff --git a/docs/designer/deploy/component.mdx b/docs/designer/deploy/component.mdx
@@ -0,0 +1,144 @@
+# 组件接入
+
+Tango 引擎借助用户传入的 **组件配置** 信息识别组件，并通过组件配置信息渲染组件配置面板。在设计器接入环节中，我们介绍了可以在 `Workspace` 初始化的时候传入 `prototypes` 参数用来提供组件配置信息。组件接入，主要是指将组件的配置信息传入给引擎。
+
+`prototypes` 信息在引擎中的主要使用场景包括：
+
+- 生成代码片段：当用户通过拖拽等手段在设计器中添加组件时，引擎会根据组件配置信息生成对应的代码片段。
+- 渲染组件配置面板：当用户选中某个组件时，设计器会根据组件配置信息渲染对应的组件配置面板。
+
+```ts
+import { createEngine, Workspace } from '@music163/tango-core';
+
+const mockPrototypes = {
+  Button: {
+    /* Button Config */
+  },
+  Input: {
+    /* Input Config */
+  },
+  //...其他组件配置
+};
+
+// 工作区初始化：将项目文件传入给设计器
+const workspace = new Workspace({
+  entry: '/src/index.js',
+  files: mockFiles, // 文件参数可以参考示例应用
+  prototypes: mockPrototypes, // 组件配置信息可以参考示例应用
+});
+```
+
+组件配置信息的类型定义可以参考 [IComponentPrototype](https://netease.github.io/tango/interfaces/_music163_tango_helpers.IComponentPrototype.html)。
+
+## 组件库
+
+组件库通常包括多个子组件，每个子组件都有自己的配置信息。在设计器中，我们可以通过组件库的方式将多个子组件的配置信息传入给引擎。示例的配置代码如下：
+
+```ts
+export const Button: ComponentPrototypeType = {
+  name: 'Button',
+  title: '按钮',
+  package: '@music163/tango-mail',
+  icon: 'icon-anniu',
+  help: '按钮用于触发一个操作',
+  type: 'element',
+  props: [
+    {
+      name: 'href',
+      title: '跳转链接',
+      setter: 'textSetter',
+    },
+    {
+      name: 'children',
+      title: '文案',
+      setter: 'textSetter',
+      initValue: '按钮',
+    },
+  ],
+};
+
+export const CodeBlock: ComponentPrototypeType = {
+  name: 'CodeBlock',
+  title: '代码块',
+  package: '@music163/tango-mail',
+  icon: 'icon-code',
+  type: 'element',
+  props: [
+    {
+      name: 'code',
+      title: '代码',
+      setter: 'codeSetter',
+      initValue: "export foo = 'foo';",
+    },
+    {
+      name: 'lineNumbers',
+      title: '展示行号',
+      setter: 'boolSetter',
+      initValue: true,
+    },
+    {
+      name: 'language',
+      title: '语言',
+      setter: 'textSetter',
+      initValue: 'javascript',
+      tip: '语言列表参考 Prism.js',
+      docs: 'https://prismjs.com/#supported-languages',
+    },
+  ],
+};
+```
+
+也可以参考一个示例组件库 `@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)
+
+## 业务组件
+
+对于业务组件而言，通常导出为单个组件，如果导出多个组件，可以参考组件库的方式。单个组件的配置信息示例如下：
+
+```ts
+const bizToggleButtonPrototype: ComponentPrototypeType = {
+  name: 'CtPcToggleButton',
+  exportType: 'defaultExport', // 指定了组件的导出方式为 “默认导出”
+  package: '@music163/ct-pc-toggle-button',
+  title: '示例业务组件',
+  icon: 'icon-tupian',
+  type: 'element',
+  hasChildren: false,
+  props: [
+    {
+      name: 'checked',
+      title: '是否选中',
+      setter: 'boolSetter',
+      defaultValue: false,
+    },
+    {
+      name: 'children',
+      title: '文本',
+      setter: 'textSetter',
+      initValue: '按钮',
+    },
+  ],
+};
+```
+
+与组件库相比，业务组件的配置信息中多了 `exportType` 字段，用来指定组件的导出方式，对于单个组件而言，通常为 默认导出 模式。导出方式的差异，决定了代码生成时的导入语句的不同。
+
+## 代码片段
+
+在 Tango 设计器中，还支持代码片段级别的配置信息，允许将定义好的代码片段拖拽到设计器中。代码片段的配置信息示例如下：
+
+```ts
+const Snippet2ColumnLayout: IComponentPrototype = {
+  name: 'Snippet2ColumnLayout',
+  title: '两列布局',
+  icon: 'icon-columns',
+  type: 'snippet', // 声明为代码片段类型
+  package: '@music163/antd',
+  initChildren: `
+  <Columns columns={12}>
+    <Column colSpan={6}></Column>
+    <Column colSpan={6}></Column>
+  </Columns>
+  `,
+  relatedImports: ['Columns', 'Column'],
+};
+```
diff --git a/docs/designer/deploy/designer.mdx b/docs/designer/deploy/designer.mdx
@@ -5,7 +5,7 @@
 1. clone 官方示例代码，按照文档说明直接启动项目。
 2. 手工引入设计器的 npm 包，自定义配置、启动、运行。
 
-## 方法1: 通过示例代码启动设计器
+## 通过示例代码启动设计器
 
 你可以使用 Tango 代码仓库内的 `/apps/playground` 复制出来，作为基础应用并改造。你需要移除 `.umirc.ts` 中与 `resolvePackageIndex()` 方法相关的配置，具体可直接参考我们的示例应用的 [`.umirc.ts`](https://github.com/NetEase/tango-playground/blob/master/.umirc.ts) 文件，修改后再手动安装 `@music163/tango-designer` 即可启动项目。
 
@@ -23,15 +23,15 @@
     nvm use 16
     ```
 
-2. 克隆项目仓库：
+2.  克隆项目仓库：
 
     ```sh
     git clone https://github.com/NetEase/tango-playground.git --depth 1
     ```
 
     也可以直接下载 [最新代码的压缩包](https://github.com/NetEase/tango-playground/archive/refs/heads/master.zip) 并解压。
 
-3. 安装项目依赖：
+3.  安装项目依赖：
 
     ```sh
     cd tango-playground
@@ -45,24 +45,24 @@
     127.0.0.1 local.example.com
     ```
 
-5. 修改 `/src/pages/index.tsx`，将 `<Sandbox>` 的 `bundlerURL` 替换为已部署的沙箱的地址。
+5.  修改 `/src/pages/index.tsx`，将 `<Sandbox>` 的 `bundlerURL` 替换为已部署的沙箱的地址。
 
     ```jsx
     <Sandbox
-        bundlerURL="https://sandbox.example.com"
-        onMessage={(e) => {
-            // ...
-        }}
+      bundlerURL="https://sandbox.example.com"
+      onMessage={(e) => {
+        // ...
+      }}
     />
     ```
 
-6. 修改 `/package.json`，修改 `dev` 脚本的 `HOST` 环境变量，将其改为上述配置在 hosts 文件时定义的开发域名。
+6.  修改 `/package.json`，修改 `dev` 脚本的 `HOST` 环境变量，将其改为上述配置在 hosts 文件时定义的开发域名。
 
     ```
     "dev": "HOST=local.example.com PORT=8001 umi dev",
     ```
 
-7. 使用脚手架的指令启动项目开始开发，启动后需要通过之前 hosts 配置的域名打开本地项目，并信任自签发的证书。
+7.  使用脚手架的指令启动项目开始开发，启动后需要通过之前 hosts 配置的域名打开本地项目，并信任自签发的证书。
 
     ```sh
     # 经过上述修改启动后，可通过 https://local.example.com:8001 访问项目
@@ -73,12 +73,115 @@
 
     ![](https://p6.music.126.net/obj/wo3DlcOGw6DClTvDisK1/33392683897/c72b/f6f2/2944/a481233c752a9e74213fa15aa516b6f0.png)
 
-
-## 方法2: 手工引入设计器的 npm 包
-
-WIP
-
-
 ## 配置低代码设计器
 
-请参考 [设计器自定义](../customize/panels) 部分。
+Tango 设计器是一个独立的基于 React 实现的 npm 包，你可以通过 npm 或 yarn 来安装 `@music163/tango-designer` 使用。
+
+### 引擎初始化
+
+Tango 引擎遵循最小内核的原则，其实现非常的精简，提供了引擎实现的基本规范，和默认的基于源码解析操纵的引擎实现。意味着，你可以快速的初始化一个基于源码解析操纵的设计器引擎。当然，也可以根据自己的需要，按照引擎的规范实现自定义的实现。
+
+```js
+import { createEngine, Workspace } from '@music163/tango-core';
+// 工作区初始化：将项目文件传入给设计器
+const workspace = new Workspace({
+  entry: '/src/index.js',
+  files: mockFiles, // 文件参数可以参考示例应用
+  prototypes: mockPrototypes, // 组件配置信息可以参考示例应用
+});
+
+// 引擎初始化：将工作区传入给设计器引擎，完成设计器的初始化
+const engine = createEngine({
+  workspace,
+});
+```
+
+关于组件配置信息可以参考 [组件接入](./component) 部分。
+
+### 设计器初始化和布局
+
+Tango 提供了基于 React 实现的开箱即用的设计器组件，你可以借助这些组件快速的组装一个基本的低代码设计器。也可以根据实际需要，开发自定义的设计器组件。
+
+关于设计器组件的介绍和使用可以参考 [设计器自定义](../customize/panels) 部分。
+
+```jsx
+import {
+  Designer,
+  DesignerPanel,
+  SettingPanel,
+  Sidebar,
+  Toolbar,
+  WorkspacePanel,
+  WorkspaceView,
+  CodeEditor,
+  Sandbox,
+} from '@music163/tango-designer';
+
+export default function App() {
+  return (
+    <Designer engine={engine}>
+      <DesignerPanel
+        logo="Your Logo"
+        actions={
+          <Box px="l">
+            <Toolbar>
+              <Toolbar.Item key="history" placement="left" />
+              <Toolbar.Item key="preview" placement="left" />
+              <Toolbar.Item key="modeSwitch" placement="right" />
+              <Toolbar.Item key="togglePanel" placement="right" />
+            </Toolbar>
+          </Box>
+        }>
+        <Sidebar>
+          <Sidebar.Item
+            key="components"
+            label="组件"
+            icon={<AppstoreAddOutlined />}
+            widgetProps={{
+              menuData, // 配置设计器的组件列表
+            }}
+          />
+          <Sidebar.Item key="outline" label="结构" icon={<BuildOutlined />} />
+          <Sidebar.Item
+            key="dependency"
+            label="依赖"
+            icon={<ClusterOutlined />}
+            isFloat
+            width={800}
+          />
+        </Sidebar>
+        <WorkspacePanel>
+          <WorkspaceView mode="design">
+            <Sandbox />
+          </WorkspaceView>
+          <WorkspaceView mode="code">
+            <CodeEditor />
+          </WorkspaceView>
+        </WorkspacePanel>
+        <SettingPanel />
+      </DesignerPanel>
+    </Designer>
+  );
+}
+```
+
+### 配置设计器的组件列表
+
+设计器的组件列表供用户快速的了解到当前应用支持的组件，可以通过 menuData 配置项传入给侧边栏的组件面板。定义格式如下：
+
+```js
+const menuData = {
+  common: [
+    {
+      title: '常用',
+      items: ['Button', 'Section', 'Columns', 'Column', 'Box', 'Text'],
+    },
+    {
+      title: '输入',
+      items: ['Input', 'InputNumber', 'Select'],
+    },
+  ],
+};
+```
+
+值得注意的是，menuData 定义的组件名，需要在引擎的 prototypes 参数中提前定义好，以便引擎能够正确的解析和渲染组件的配置参数。
diff --git a/sidebars.ts b/sidebars.ts
@@ -22,6 +22,7 @@ const sidebars: SidebarsConfig = {
       label: '接入指南',
       items: [
         'designer/deploy/designer',
+        'designer/deploy/component',
         'designer/deploy/sandbox',
         'designer/deploy/server',
       ],

diff --git a/src/css/custom.css b/src/css/custom.css
@@ -28,3 +28,9 @@
   --ifm-color-primary-lightest: #4fddbf;
   --docusaurus-highlighted-code-line-bg: rgba(0, 0, 0, 0.3);
 }
+
+.markdown img {
+  border: 1px solid var(--ifm-color-emphasis-200);
+  border-radius: var(--ifm-global-radius);
+  box-shadow: var(--ifm-global-shadow-lw);
+}