opensource/tango
3
0
Fork 0
mirror of https://github.com/NetEase/tango.git synced 2026-08-28 17:41:30 +08:00
Code Issues Packages Projects Releases Wiki Activity

docs: update (#95)

Browse Source 
* docs: update

* docs: update

* docs: update

* docs: add setters

* docs: update

* chore: add typedoc workflow
This commit is contained in:
Wells
2024-02-19 16:58:59 +08:00
committed by GitHub
parent eaff3604f3
commit 63dca2a9b7
30 changed files with 589 additions and 504 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.github/workflows/typedoc.yml
+34
View File
@@ -0,0 +1,34 @@
name: 'typedoc'
on:
push:
branches: [main]
permissions:
contents: read
pages: write
id-token: write
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- uses: actions/setup-node@v3
# Generate your TypeDoc documentation
- run: npx typedoc
# https://github.com/actions/upload-pages-artifact
- uses: actions/upload-pages-artifact@v2
with:
path: ./docs # This should be your TypeDoc "out" path.
deploy:
runs-on: ubuntu-latest
environment:
name: github-pages
url: ${{ steps.deployment.outputs.page_url }}
needs: build
steps:
- name: Deploy to GitHub Pages
id: deployment
# https://github.com/actions/deploy-pages
uses: actions/deploy-pages@v2
apps/website/docs/designer/customize/components.mdx
+135
View File
@@ -0,0 +1,135 @@
# 组件库自定义
Tango 提供了基于源码的低代码开发能力，默认不提供私有的内置组件库，仅提供了一个简单的示例用于说明如何将只有组件库接入到 Tango 中。
:::tip
**组件库接入**意味着开发者可以将自己的组件库接入到 Tango 中，以便于在设计器中使用自己的组件，包括拖拽、配置、生成等行为。
:::
## 基本的目录结构
基本的组件库目录结构如下：
```text
+ src
+ button
- view.tsx // 默认视图文件
- index.ts // 渲染视图入口文件
- designer.ts // 设计器视图入口文件
- prototype.ts // 【新增】组件描述文件
+ date-picker
- index.ts // 组件包默认入口文件
- designer.ts // 【新增】组件包设计器视图入口文件
```
可以发现，相比正常的组件代码，Tango 对于接入的组件库要求提供 2 个全新的文件 `designer.ts` 和 `prototype.ts`。其中 `designer.ts` 为设计视图文件，用来实现在 Tango 设计器中的辅助搭建行为，如果无需定制，可以直接保持 `designer.ts` 文件和 `index.ts` 文件一致。而 `prototype.ts` 文件则是用来描述组件的属性和行为的，用于在设计器中渲染组件的配置项，和控制组件的拖拽行为等。
一个可供参考的示例代码是 <https://github.com/NetEase/tango-components/tree/main/packages/antd/src>
### designer.ts
在 `designer.ts` 文件中，相比原有的组件库入口文件，还需要导出 `menuData` 和 `prototypes` 两个模块。
```jsx
export * from './button';
export * from './card';
//...
// 组件的配置描述列表
export const prototypes = [
{
title: '按钮',
name: 'Button',
props: [
{
name: 'size',
setter: 'textSetter',
},
//...
],
},
//...
];
export const menuData = {
// 常用组件
common: [
{
title: '基本',
items: ['Button'],
},
],
};
```
其中 `menuData` 的 `key` 可选列表如下：
| key | 说明 |
| ------- | -------- |
| common | 常用组件 |
| atom | 原子组件 |
| snippet | 代码片段 |
### prototype.ts
组件的配置描述文件。
## 组件配置描述
### ComponentPrototypeType
组件的配置描述。
| 属性 | 说明 | 类型 | 默认值 |
| -------------- | ----------------------------------------------- | ---------------------------------------------------------------------------- | ------ |
| childrenName | 子组件的名称 | `string` | - |
| docs | 组件的文档地址 | `string` | - |
| exportType | 组件的导出类型 `defaultExport` \| `namedExport` | `string` | - |
| hasChildren | 是否有子组件 | `boolean` | - |
| help | 组件的帮助文档 | `string` | - |
| icon | 组件的图标，图片地址或 iconfont 图标名 | string | - |
| name | 组件的名称 | `string` | - |
| package | 组件的包名，或引入路径 | `string` | - |
| props | 组件的属性描述 | `ComponentPropType[]` | - |
| relatedImports | 组件的相关引入 | `string[]` | - |
| rules | 组件的规则 | `ComponentDndRulesType` | - |
| title | 组件的标题 | `string` | - |
| type | 组件的类型 | "page" \| "container" \| "placeholder" \| "element" \| "snippet" \| "block"` | - |
| usage | 组件的使用说明 | `string` | - |
### ComponentPropType
组件的属性描述。
| 属性 | 说明 | 类型 | 默认值 |
| --------------------- | -------------------------------------------- | ------------------------------------------- | ------ |
| autoCompleteOptions | 自动补全的提示值，仅对 ExpressionSetter 有效 | `string[]` | - |
| autoInitValue | 如果没提供 initValue, 是否自动初始化值 | `boolean` | - |
| defaultValue | 组件的内置默认值 | `any` | - |
| disableVariableSetter | 是否禁用变量设置器 | `boolean` | - |
| docs | 属性的文档地址 | `string` | - |
| getProp | 动态设置属性，覆盖已有的 prop 对象 | `(form) => any` | - |
| getSetterProps | 动态设置属性，覆盖已有的 setterProps 对象 | `(form) => any` | - |
| getVisible | 动态设置表单项是否展示 | `(form) => boolean` | - |
| group | 属性的分组 | `basic` \| `event` \| `style` \| `advanced` | - |
| initValue | 首次拖拽后用来初始化组件的属性值 | `any` | - |
| name | 属性的名称 | `string` | - |
| options | 属性的选项 | `any[]` | - |
| placeholder | 属性的占位符 | `string` | - |
| props | 如果是对象属性，这里声明子属性列表 | `ComponentPropType[]` | - |
| setter | 属性的设置器 | `string` | - |
| setterProps | 设置器的属性设置 | `any` | - |
| tips | 属性的提示 | `string` | - |
| title | 属性的标题 | `string` | - |
### ComponentDndRulesType
组件拖拽规则类型
| 属性 | 说明 | 类型 | 默认值 |
| ------------------------- | ---------------------------------------------------------------------------- | --------------------------- | ------ |
| canDrag | 当前组件是否可以被拖拽 | `() => boolean` | - |
| canDrop | 当前节点是否可以拖拽到目标节点中 | `(targetName) => boolean` | - |
| canMoveIn | 进来的节点是否可以落进来，仅适用于容器节点 | `(incomingName) => boolean` | - |
| canMoveOut | 被拖拽的节点是否可以被拖离当前节点，仅适用于容器节点 | `(outgoingName) => boolean` | - |
| childrenContainerSelector | 子节点的容器选择器，用于快速定位子节点容器，适合组件存在多个可搭建区域时使用 | `string` | - |
apps/website/docs/designer/customize/editor.mdx
+5
View File
@@ -0,0 +1,5 @@
# 编辑器自定义
:::tip
正在编写中，敬请期待。
:::
apps/website/docs/designer/customize/panels.mdx
+72
View File
@@ -0,0 +1,72 @@
# 面板自定义
Tango 设计器由多个可自定义的面板组成，默认提供了一个标准的低代码设计器布局，可以根据实际需求进行自定义。如下图所示，可以对设计器的多个区域进行自定义，包括工具栏、侧边栏、配置面板、选择工具栏等等。
![panels](https://p5.music.126.net/obj/wonDlsKUwrLClGjCm8Kx/33769559515/5564/0630/b437/02cd440a1789b8138ee64d058f86db20.png)
- 工具栏（Toolbar）：设计器的顶部区域，通常用来放置一些全局信息和操作按钮，例如项目信息，顶部工具栏、发布按钮等等。
- 侧边栏（Sidebar）：设计器的左侧区域，通常用来放置一些核心功能的入口，例如k组件库、页面列表、变量配置、数据源配置等。
- 配置面板（Properties）：设计器的右侧区域，通常用来放置一些配置项，例如组件属性配置、页面属性配置等。
- 选择工具栏（SelectionMenu）：设计器的底部区域，通常用来放置一些选择工具，例如复制、删除、定位等。
除了使用预定义的设计器布局组件，Tango 支持完全使用开发者自行开发的组件进行替换。
## 内置设计器布局组件介绍
内置的设计器布局组件包括：
- Designer：设计器的状态容器，用来提供设计器核心状态的上下文容器，包括主题、引擎状态、沙箱状态等。
- DesignerPanel：设计器的主框架，提供了核心的布局容器，便于开发者进行后续的自定义。
- Toolbar：工具栏容器组件，提供了默认的工具栏的布局设置，可以通过 `Toolbar.Item` 进行快捷的定义工具栏的子项。
- Sidebar：侧边栏容器组件，提供了默认的侧边栏的布局设置，可以通过 `Sidebar.Item` 进行快捷的定义侧边栏的子项。
- WorkspacePanel：工作区容器组件，设计器中央的区域，包括画布和编辑等用户核心工作区，提供了默认的工作区的布局配置。
- WorkspaceView：工作区的视图组件，用于快捷定制工作区的多种视图模式，可以实例化多个工作区视图，但同一时间只能由一个工作区视图处于激活状态。
- SettingPanel：配置面板组件，提供了默认的属性配置能力。
## 基本的设计器布局
一个基本的的设计器布局示例如下图所示：
```jsx
export default function App() {
return (
<Designer theme={themeLight} engine={engine} sandboxQuery={sandboxQuery}>
<DesignerPanel
logo={<Logo />}
description={<ProjectDetail />}
actions={
<Box px="l">
<Toolbar>
<Toolbar.Item key="routeSwitch" placement="left" />
<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.Separator />
<Toolbar.Item placement="right">
<Space>
<Button type="primary">发布</Button>
</Space>
</Toolbar.Item>
</Toolbar>
</Box>
}
>
<Sidebar>
<Sidebar.Item key="components" label="组件" icon={<AppstoreAddOutlined />} />
<Sidebar.Item key="outline" label="结构" icon={<BuildOutlined />} />
</Sidebar>
<WorkspacePanel>
<WorkspaceView mode="design">
<CustomDesignView />
</WorkspaceView>
<WorkspaceView mode="code">
<CustomSourceCodeView />
</WorkspaceView>
</WorkspacePanel>
<SettingPanel />
</DesignerPanel>
</Designer>
);
}
```
apps/website/docs/designer/customize/selections.mdx
+4
View File
@@ -0,0 +1,4 @@
# 选择器自定义
提供设计器视图中用户选中某个区域后展示的快捷工具。
apps/website/docs/designer/setters.mdx → apps/website/docs/designer/customize/setters.mdx
+18 -4
View File
@@ -1,7 +1,24 @@
# 属性设置器
# 设置器自定义
属性设置器用于在配置面板中展示特定配置项的配置逻辑。Tango 内置了多种标准的属性设置器，对于一些特殊场景，内置的属性设置器可能无法满足你的需要，此时开发者可以扩展自己的属性设置。
## 设置器组件
### SettingPanel
| 属性 | 说明 | 类型 | 默认值 |
| ---------------- | -------------------------------------- | ---------------------------- | ------ |
| title | 面板标题 | string | - |
| defaultValue | 默认值 | object | - |
| groupOptions | 分组选项 | object | - |
| model | 表单状态管理实例 | FormModel | - |
| onChange | 值变化回调 | (name, value, field) => void | - |
| prototype | 组件的可配置描述 | ComponentPrototype | - |
| renderItemExtra | 自定义渲染表单项的额外内容（标签右侧） | (props) => ReactNode | - |
| showGroups | 是否展示分组 | boolean | - |
| showItemSubtitle | 是否展示表单项的副标题 | boolean | - |
| showSearch | 是否展示搜索框 | boolean | - |
## 内置属性设置器
| 设置器名 | 接收值类型 | 设置器说明 | 可配置项 |
@@ -19,8 +36,6 @@
| expressionSetter | expression | 表达式设置器 | |
| jsonSetter | json expression | JSON 表达式设置器 | |
| jsxSetter | jsx expression | JSX 设置器 | |
| iconSetter | string | Icon 组件设置器 | |
| iconTypeSetter | string | Icon 组件类型设置器 | |
| numberSetter | number | 数字类型设置器 | |
| textSetter | string | 文本设置器 | |
| textAreaSetter | string | 文本域设置器 | |
@@ -29,7 +44,6 @@
| sliderSetter | number | 滑块设置器 | |
| listSetter | `object[]` | 列表值设置器 | |
| renderPropsSetter | Function | render props 设置器 | |
| imageSetter | string | 云鹿图片设置器 | |
## 注册自定义属性设置器
apps/website/docs/designer/customize/sidebar.mdx
+53
View File
@@ -0,0 +1,53 @@
# 侧边栏自定义
提供了默认的设计器左侧边栏的布局设置。
## 侧边栏组件
### Sidebar
侧边栏容器组件。
### Sidebar.Item
侧边栏子项
| 属性 | 说明 | 类型 | 默认值 |
| ----------- | ------------------------------------------------ | ------------------------------------------------- | ------ |
| key | 子项的唯一标识 | `string` | - |
| label | 子项的描述文本，推荐不超过2个字 | `string` | - |
| icon | 图标 | `ReactNode` | - |
| showBadge | 是否显示角标 | `boolean` \| `{ count?: number; dot?: boolean; }` | - |
| title | 展开面板的标题 | `string` | - |
| width | 展开面板的宽度 | `number` | - |
| isFloat | 展开面板是否为浮动面板，浮动面板不压缩工作区宽度 | `boolean` | - |
| widgetProps | 子项的属性 | `object` | - |
| children | 子项的展开面板内容 | `ReactNode` | - |
## 内置的工具栏组件
设计器内置了一些基本的侧边栏组件，当子项的 `key` 使用了特定的值时，会自动的进行渲染。
| key | 组件 |
| ---------- | ---------- |
| components | 组件列表 |
| outline | 结构 |
| dependency | 依赖管理 |
| variables | 变量管理 |
| dataSource | 数据源管理 |
例如，下面的代码会自动渲染一个结构面板：
```jsx
<Sidebar.Item key="outline" label="结构" icon={<BuildOutlined />} />
```
## 自定义侧边栏子项
可以直接在 `Sidebar.Item` 的子节点传入自定义的内容来渲染需要的结果，例如：
```jsx
<Sidebar.Item key="custom" label="自定义" icon={<SmileOutlined />}>
<div>展开的内容部分</div>
</Sidebar.Item>
```
apps/website/docs/designer/customize/tools.mdx
+53
View File
@@ -0,0 +1,53 @@
# 工具栏自定义
提供了默认的设计器工具栏的布局设置。
## 工具栏组件
### Toolbar
工具栏列表容器
### Toolbar.Item
工具栏子项
| 属性 | 说明 | 类型 | 默认值 |
| ----------- | -------------- | --------------------------- | ------- |
| key | 子项的唯一标识 | `string` | - |
| placement | 放置的位置 | `left` \| `right` \| `left` | `right` |
| widgetProps | 子项的属性 | `object` | - |
### Toolbar.Separator
工具栏分隔线，用来对工具栏子项进行分组展示。
## 内置的工具栏组件
设计器内置了一些基本的工具栏组件，当工具栏子项使用了特定的 `key` 值时，会自动的进行渲染。
| key | 组件 |
| ----------- | ------------------------------------ |
| routeSwitch | 路由切换 |
| history | 历史记录 |
| preview | 沙箱预览 |
| modeSwitch | 工作区模式切换，在源码和设计模式切换 |
| togglePanel | 切换布局面板的显示和隐藏 |
例如，下面的代码会自动渲染为一个路由切换的工具项。
```jsx
<Toolbar.Item key="routeSwitch" />
```
## 自定义工具栏项
可以直接在 `Toolbar.Item` 的子节点传入自定义的工具栏项，例如:
```jsx
<Toolbar.Item placement="right">
<Space>
<Button type="primary">发布</Button>
</Space>
</Toolbar.Item>
```
apps/website/docs/designer/deploy/designer.mdx
+18
View File
@@ -0,0 +1,18 @@
# 设计器接入
设计器为用户提供应用搭建的可视化界面。有两种方式初始化低代码设计器：
1. clone 官方示例代码，按照文档说明直接启动项目。
2. 手工引入设计器的 npm 包，自定义配置、启动、运行。
## 方法1: 通过示例代码启动设计器
WIP
:::tip
官方示例是一个包含了低代码设计器前后端低完整项目，可以直接启动。对于后端部分，作为示例而言，仅提供了最基本的逻辑，用户需要按照需求自行扩展。
:::
## 方法2: 手工引入设计器的 npm 包
WIP
apps/website/docs/designer/deploy/sandbox.mdx
+19
View File
@@ -0,0 +1,19 @@
# 低代码沙箱接入
沙箱是搭建产物（对于 Tango 主要是源码）的运行环境，它是一个独立的环境，可以在其中运行搭建产物，以便于开发者可以在不影响生产环境的情况下进行调试和测试。
Tango 沙箱由三个部分构成，包括低代码沙箱前端组件、在线打包器、沙箱后端服务，如下图所示。
![tango sandbox](https://p5.music.126.net/obj/wonDlsKUwrLClGjCm8Kx/30579143007/ab5d/3611/950e/5ae276b6131a4a479d6fb10e50ebbfcb.png)
- 沙箱前端组件：一个开箱即用的沙箱组件，只需要传入代码和配置就可以完成应用的渲染。
- 在线打包器：提供搭建产物的浏览器端构建能力，类似于一个浏览器版本的 webpack，此部分逻辑主要来自于 [sandpack](https://sandpack.codesandbox.io/) 项目。
- 沙箱后端服务：对依赖的资源进行预构建，以及提供资源合并等服务，用来加速沙箱内部的构建打包过程。
## 沙箱的前端组件接入
WIP
## 沙箱的后端服务接入
WIP
apps/website/docs/designer/deploy/server.mdx
+7
View File
@@ -0,0 +1,7 @@
# 服务端接入
介绍一个基本的服务端实现，以及如何接入。
:::tip
正在编写中，敬请期待。
:::
apps/website/docs/designer/design/filesystem.mdx
+5
View File
@@ -0,0 +1,5 @@
# 文件系统
:::tip
正在编写中，敬请期待。
:::
apps/website/docs/designer/design/overview.mdx
+112
View File
@@ -0,0 +1,112 @@
# 技术架构概览
我们在 2023年8月底[正式开源了 Tango 低代码引擎](https://juejin.cn/post/7273051203562749971)。Tango 是一个基于源码的低代码设计器框架，支持直接基于项目源码提供低代码可视化开发能力，可以无缝的与既有的本地开发工作流进行集成，从而提供渐进式的低代码开发能力。
![Tango 低代码引擎使用演示](https://p6.music.126.net/obj/wonDlsKUwrLClGjCm8Kx/30108735057/7ba9/dced/9ac3/420f6e04b371dd47de06e7d71142560d.gif)
按照计划，我们在 2023年9月底[发布了 1.0 alpha 版本](https://github.com/NetEase/tango/releases)，在此版本中我们遵循 **“最小内核”** 的原则对 Tango 的核心实现进行了大幅的重构，剥离了大量冗余的代码实现。
为了帮助大家更近一步的了解 Tango 开源版本的核心构成与代码实现，本文将会详细揭秘 Tango 低代码引擎的设计思考与实现过程。
- Github 仓库：<https://github.com/NetEase/tango>
- 发行历史：<https://github.com/NetEase/tango/releases>
- 文档站点：<https://netease.github.io/tango/>
## 低代码可视化搭建之殇
从实现上看，低代码搭建能力的核心是 UI 可视化编程。借助 UI 可视化编程，可以大大的弱化使用者对于代码编程的感知，但在真实的业务需求场景中，我们面临着大量的复杂的应用逻辑，使用者很难借助 UI 操作表达功能逻辑。例如下图中的合同管理，资金结算等页面。如果借助于传统的低代码方案，通常会发现，很容易一条路走到黑，没有回头路。所以，经常会有开发者抱怨，稍微复杂的场景下，低代码的效率甚至不如写代码。
![在实际业务场景中面临大量难以低代码开发的前端应用](https://p5.music.126.net/obj/wonDlsKUwrLClGjCm8Kx/30577891541/dac5/e050/986b/9466633e32518be2685e882618343251.png)
## 传统低代码方案的问题
我们不妨先简单分析一下传统的低代码方案的问题。传统的低代码搭建方案往往采用定义私有 Schema 协议来可视化表达视图逻辑，也就是将代码逻辑转换为私有的描述，大致的原理可以参考下面这张图。
![基于 Schema 的低代码可视化搭建方案](https://p6.music.126.net/obj/wonDlsKUwrLClGjCm8Kx/30577932595/1456/2196/aeee/a10fbe99c3f6d050629b140ecfbbc257.png)
这类方案很容易面临不断膨胀的私有 JSON 协议。并且，私有协议扩展性和灵活性差，难以达到图灵完备状态。例如在我们的实际开发过程中，传统的低代码方案会面临各种各样的扩展性卡点。此外，开发能力往往受限于内置的组件和模板。且难以复用现有的前端资产，例如组件和代码等等。对于开发者而言，私有协议也导致问题定位难，调试难。
借助于私有协议的搭建方案通常适合于轻业务逻辑的简单类表单，营销类的活动页面等等，很难用于复杂的业务逻辑搭建场景，因为私有协议难以有效的应对这类场景的复杂性和灵活性需求。虽然，有些方案提供了协议转代码的能力，但通常只实现了单向转码，可视化开发和代码开发是两条完全割裂的路径。
**在此基础上，我们就需要重新思考低代码搭建协议的设计问题。**
## 从私有搭建协议到公有协议
那么，我们能否不使用私有协议，而是采用公有协议？
答案是，可以的！[ESTree](https://github.com/estree/estree) 规范作为主流的处理 JavaScript 源代码的标准社区协议，被广泛用于浏览器 JavaScript Parser 的实现。借助于 ESTree 协议，可以完美的实现对源码逻辑的描述，并且社区有大量的工具可以帮助我们完成这个过程。
![基于ESTree规范，实现双向互转的低代码搭建能力](https://p6.music.126.net/obj/wonDlsKUwrLClGjCm8Kx/30578051842/b7b4/f625/9458/3ead74325547a45f501ae99c7270cffa.png)
因此，我们尝试使用 ESTree 规范来实现低代码搭建过程。借助于 ESTree 规范，我们无需定义私有的渲染描述协议，并且可以低成本的实现代码到协议，协议到代码到互转。借助于双向转码的能力，我们获得全新的低代码开发体验。
## Tango 低代码引擎实现原理
基于这个思路，我们设计了基于 ESTree 规范的低代码引擎方案 -- Tango。可以通过下面这张图来简单的描述下实现逻辑：
![Tango 低代码引擎实现分析](https://p5.music.126.net/obj/wonDlsKUwrLClGjCm8Kx/30578073085/61cd/b2db/e103/9ed9dd334a6679c6ec18a02270efe446.png)
首先将源代码解析为 AST。用户的拖拉拽等操作则映射为对 AST 的遍历和修改。最后将新的 AST 重新生成代码，交给设计器沙箱去渲染执行。而对 AST 的解析、遍历、修改、生成，则可以借助大量的社区工具，这里我们选择的是 babel！
> AST 的全称是抽象语法树，是一种分层的程序表达，根据编程语言的语法呈现源代码的结构。
![大量的工具基于 AST 实现](https://p6.music.126.net/obj/wonDlsKUwrLClGjCm8Kx/30578121562/578f/1bac/9dd3/69b5b4e5c1171babf4db427f41981b4d.png)
其实，数量众多的前端工具库都是基于 AST 操纵实现的。我们可以发现，在任意的前端项目中的 package.json 里的 devDependencies 里的很多工具包是基于 AST 解析操纵实现的，例如 JS 的转译，代码压缩，ESLint 等等，我们可以阅读这些工具的源码来进一步的学习。
![将源码转为 AST 描述的基本过程](https://p6.music.126.net/obj/wonDlsKUwrLClGjCm8Kx/30578132788/1f4b/d7d7/56b8/feb4220a611afae0629d76758479118a.png)
如图所示，将源代码转为 AST 描述的基本过程包括词法分析和句法分析两个阶段:
- 词法分析：借助词法分析器将代码字符串分割为标记列表。
- 句法分析：借助句法分析器将标记数据转为 AST 描述。
最后，我们可以获得源代码的结构化描述树。有很多工具可以帮我们来实现这个过程，例如 babel -- 它可以帮助我们轻松的实现代码到 ast，ast 遍历修改，ast 到代码的过程。
## 基于 AST 实现搭建的基本过程
我们来看一下使用 ast 实现搭建逻辑的基本过程。
看一个具体的例子：通过修改 AST，在 Page 中插入一个 Section 节点。
![基于 AST 实现搭建逻辑](https://p6.music.126.net/obj/wonDlsKUwrLClGjCm8Kx/30579119959/aea0/6e5a/6aba/979804c4270f5ad05b84da2220624afd.png)
中间这段代码，展示了核心的逻辑，通过遍历整个 AST 中的所有 JSXElement 节点，找到第一个 Page 元素，然后在 Page 元素的 children 里插入新的 Section 节点。这只是一段演示代码，具体的过程比这个要复杂的多，因为有很多的边际逻辑要处理。最后，我们可以将 ast 重新生成为代码，得到我们想要的结果。
## Tango 的数据变更流程设计
了解了基本的实现原理后，我们来看一下低代码引擎的数据变更流程设计。
![数据变更流程设计](https://p6.music.126.net/obj/wonDlsKUwrLClGjCm8Kx/30579135078/e381/579c/61ed/91e110abd1d17c742e8aa7d407d0327b.png)
首先是引擎初始化。源码文件会被引擎内核解析进行状态初始化。接下来，对于用户的操作，会触发浏览器事件，引擎接收到相应的事件，触发内核中的状态变更，更新 AST。
然后，内核会基于新的 AST 的同步生成代码，由引擎将代码同步给渲染沙箱。渲染沙箱感知到代码变化后，会触发页面重新渲染，也就是沙箱的 HMR 过程。
## 基于源码的在线渲染沙箱设计
接下来，我们需要考虑的是如何在浏览器中执行 JavaScript 源码工程？有很多方案可以选择，我们选择的方案是 [sandpack](https://sandpack.codesandbox.io/)，它是由 CodeSandbox 开源的可以在浏览器中实时运行 JavaScript 项目的的工具库。在具体实现上，[我们对 sandpack 进行了一系列的改造](https://juejin.cn/post/7102243774985666596)，以满足低代码生产环境的需要。
基于 sandpack 的在线渲染沙箱方案如下图图所示。
![Tango 沙箱设计](https://p5.music.126.net/obj/wonDlsKUwrLClGjCm8Kx/30579143007/ab5d/3611/950e/5ae276b6131a4a479d6fb10e50ebbfcb.png)
在实现上，主要包括 3 个部分，分别是：​
- 低代码沙箱：它是一个开箱即用的前端组件，只需要传入源代码和构建配置信息即可完成前端项目的构建和执行。
- 在线 Bundler：是低代码沙箱的核心，用来在浏览器上构建和执行源代码，本质上是一个在浏览器端运行的简化版 webpack。
- 打包服务：是一个 node 服务，用来对 npm 包执行预构建和资源合并。
从沙箱执行流程来看，首先 Sandbox 组件将项目的源代码和 compile 指令使用 postMessage 传递给在线 Bundler，在线 Bundler 在接收到 compile 指令后，bundler 会从 packager 打包服务加载项目的 npm 依赖，然后编译和执行代码，最后发送 success 消息给低代码沙箱。
## Tango 低代码引擎的构成
结合上面的介绍，在构成上，Tango 低代码引擎主要包括 3 个核心组成部分，分别是：
- 引擎内核：扶额建立文件，节点模型，提供输入输出能力。
- 拖拽引擎和可视化面板：提供可视化开发能力
- 渲染沙箱：提供源码在浏览器上的编译执行能力。
![引擎构成](https://p6.music.126.net/obj/wonDlsKUwrLClGjCm8Kx/30579167082/1404/27e2/b8e5/0c719ca82494a282080d73adeff7196e.png)
借助于 Tango 低代码引擎，我们可以为开发者提供全新的在线开发体验，支持源码级的自定义能力。对可视化开发而言，可视化配置会触发 AST 的修改，进而会重新生成对应的源码。而对源码开发而言，修改源码后会同步更新 AST。
apps/website/docs/designer/design/sandbox.mdx
+5
View File
@@ -0,0 +1,5 @@
# 沙箱实现
:::tip
正在编写中，敬请期待。
:::
apps/website/docs/designer/extend/overview.mdx
-58
View File
@@ -1,58 +0,0 @@
# 设计器扩展概览
主要介绍如何扩展 tango 设计器。tango 设计器提供了三个部位的自定义扩展能力，分别是标题栏，工具栏，和侧边栏。可以通过下面这张图进行简要的了解：
<img src="https://p5.music.126.net/obj/wonDlsKUwrLClGjCm8Kx/13359732115/c5ca/c5ae/bbd4/852daf849ac39162baf3bc3a985de6de.png" />
## 标题栏扩展
`DesignerPanel` 提供了 logo, description, actions 三个扩展点，分别对应于 平台标识、应用描述、行动点区域，开发者可以按照需求进行扩展。例如：
```jsx
<DesignerPanel logo={<Logo />} description={<ProjectDetail />} actions={<Box>新版沙箱</Box>}>
</SidebarPanel>
```
## 工具栏扩展
工具栏面板支持任意组合和设置渲染的位置，开发者可以通过 `ToolbarPanel.Item` 添加自定义的工具栏选项，例如下面的代码扩展了一个 newPage 按钮，用于支持在设计器中创建新页面的需求。
```jsx
<ToolbarPanel>
<ToolbarPanel.Item key="history" />
<ToolbarPanel.Item key="viewportRefresh" />
<ToolbarPanel.Item key="preview" />
<ToolbarPanel.Item key="routeSwitch" />
<ToolbarPanel.Item key="newPage">
<Button
onClick={() => {
const { name, code } = genDefaultPage(index);
engine.workspace.addViewPage(`${name}${index++}`, code);
message.success('页面新建成功');
}}
>
添加新页面
</Button>
</ToolbarPanel.Item>
<ToolbarPanel.Item key="modeSwitch" placement="center" />
<ToolbarPanel.Item key="viewportSwitch" placement="right" />
</ToolbarPanel>
```
## 侧边栏扩展
侧边栏面板支持任意组合和调换顺序，用户可以通过 `SidebarPanel.Item` 组件进行自定义扩展，默认情况下根据一些内置的 key 标识，设计器会自动渲染对应的面板，用户也可以根据自己的需求采用自定义渲染子节点的方案进行扩展。
例如，下面的示例代码中扩展了一个 “自定义面板”。
```jsx
<SidebarPanel>
<SidebarPanel.Item key="components" />
<SidebarPanel.Item key="outline" />
<SidebarPanel.Item key="dataSource" />
<SidebarPanel.Item key="dependency" />
<SidebarPanel.Item key="history" />
<SidebarPanel.Item key="custom" title="自定义面板" icon={<BulbOutlined />}>
<Box p="m">这里是一个自定义的面板，你可以任意添加</Box>
</SidebarPanel.Item>
</SidebarPanel>
```
apps/website/docs/designer/extend/remote-service.mdx
-67
View File
@@ -1,67 +0,0 @@
# 外部数据源
如果您的扩展部件需要使用外部数据源，可以参考本文的做法。
## 存在部件共享
如果数据源需要在多个扩展部件中共享，我们推荐您借助 tango 的 `remoteServices` 规范进行接口的实现。
### 外部数据源定义
例如，我们需要调用一组图片素材的接口，此时我们可以定义一个 `ImageService`，如下：
```tsx
import { createServices } from '@music/request';
export const remoteServices = {
ImageService: createServices(
{
listMy: {
url: '/my/upload/list',
},
listFav: {
url: '/my/star/list',
},
listPub: {
url: '/list',
},
},
{
baseURL: 'https://febase-openapi.fn.netease.com/deer/api/deer/pic',
withCredentials: false, // 解决跨域时必须非*问题
}
),
};
```
### 外部数据源引入
我们在设计器初始化的时候可以通过 `remoteServices` 属性进行外部数据源的传入。
```tsx
<Designer remoteServices={remoteServices}></Designer>
```
### 在设计器扩展中使用定义的外部数据源
```tsx
import { useRemoteServices } from '@music163/tango-designer';
export function CustomWidget() {
const remoteServices = useRemoteServices();
}
```
## 仅在单个组件
如果您的外部数据服务没有额外的共享需求，您也可以直接在组件内部进行数据服务的发起。
```tsx
import request from '@music/request';
export function CustomWidget() {
useEffect(() => {
request('//some.domain/get');
}, []);
}
```
apps/website/docs/designer/material-import.mdx
-141
View File
@@ -1,141 +0,0 @@
---
sidebar_position: 3
---
# 物料接入
Tango 提供了低成本的物料接入方式，支持直接复用现有的组件体系。只需要在现有组件包基础上简单的提供配置说明问题，即可轻松接入到 Tango 低代码生态体系中。
import Link from '@docusaurus/Link';
## 预览视图和设计器视图
- 预览视图：是组件默认的渲染模式，通常我们只需要关注此视图行为。
- 设计器视图：为低代码平台定制的渲染视图，当我们需要自定义组件在 Tango 设计器中的部分渲染行为时，可以通过修改设计器视图的渲染逻辑实现。
### 设计器视图和 `withDnd`
通常情况下我们不需要太关注于设计器视图，只需通过 `withDnd` 简单的进行包装即可。例如：
```jsx
// 将 antd Button 包装一层提供设计器视图
export Button = withDnd({
name: 'Button', // 必须，组件的名字，用来正确设置组件的 displayName
isFunctionComponent: true, // 可选，如果包裹的组件为函数组件，可以在此设置
overrideProps: {}, // 可选，覆盖掉包裹组件的默认属性值
})(AntButton);
```
默认情况下 withDnd 会在组件外层包裹一层 dnd 容器，以便于组件能够在设计器中被拖拽：
- draggable 属性表示该区域可以被拖拽
- data-dnd 用来追踪渲染的 dom 元素
```jsx
<div className="dnd-wrapper" draggable data-dnd="button:123">
<button>hello</button>
</div>
```
### 自定义拖拽容器
由于默认情况下拖拽容器是一个 `div` 节点，为[块级元素](https://www.w3schools.com/cssref/pr_class_display.asp)。部分情况下，你可能期望它渲染为一个[行内容器](https://www.w3schools.com/cssref/pr_class_display.asp)，此时可以通过如下方式配置：
```jsx
export Button = withDnd({
name: 'Button',
display: 'inline-block', // 将 dnd 容器渲染为行内元素
wrapperStyle: {}, // 传入 dnd 容器的自定义样式
})(AntButton);
```
### 禁用拖拽容器
某些情况下，你的组件可能会检查子节点的有效性，此时你可能不期望组件被包装额外的容器节点，此时你可以关闭拖拽容器，但你需要保证你的组件能够接收父级元素传入的属性信息并附加到组件的跟节点上，否则将无法正确的设置组件的 dnd 信息。
```jsx
export Button = withDnd({
name: 'Button',
hasWrapper: false, // 禁用拖拽容器
})(MyButton);
const MyButton = (props) => {
const { children, ...rest } = props;
// 此时，需要保证你的组件能够正确的将多余的属性透传到组件的根节点上
return <button {...rest}>{children}</button>
}
```
## 组件包接入
组件包一般包含多个组件导出，例如 `@music163/antd` 就是典型的组件包，它面向中后台场景提供统一的物料层解决方案。组件包接入 Tango 体系，无需修改现有的代码实现，只需要在此基础上提供额外的配置文件即可。如下所示：
```
- src
- button
- designer.tsx # 设计器视图，可以不提供
- index.ts # 默认视图出口
- prototype.ts # 组件可配置描述协议
- index.ts
- prototypes.ts
- designer.ts
```
参考示例：https://g.hz.netease.com/NeteaseMusicUI/music-one/-/tree/master/packages/components/src/action
### 设计器视图的实现
对大部分组件而言，都不需要提供特定的设计器视图，只需要使用 tango 提供的 dnd hoc 进行简单的包裹导出即可。
```tsx
import { Button as Base, ButtonProps } from 'antd';
import { withDnd } from '@music/tango-apps-shared';
export const Button = withDnd<HTMLDivElement, ButtonProps<any>>({
name: 'Button',
})(Base);
```
### 编写 prototypes 文件
可以参考 <Link to="/docs/protocol/material-protocol">物料协议</Link> 编写该文档
### 属性设置器选择
参考属性设置器文档进行选择。
### 可配置项的验证
TangoApps 提供了 SettingFormPlayground 组件用来测试组件的可配置能力，可以直接在组件文档中加入可配置测试示例，例如在 storybook 中进行测试。
```jsx
import React from 'react';
import { SettingFormPlayground } from '@music/tango-apps-setting-form';
import { Input, prototypes } from '@music163/antd';
export default {
title: 'Prototype/Input',
};
export function Basic() {
return (
<SettingFormPlayground prototype={prototypes.Input}>
<Input />
</SettingFormPlayground>
);
}
```
SettingFormPlayground 组件支持实时预览配置结果，预览效果如下：
<img src="https://p6.music.126.net/obj/wonDlsKUwrLClGjCm8Kx/13140796879/edbb/5dad/a330/013a98940e487956b605e1e533f54371.png" />
## 单个业务组件接入
单个组件接入可以参考组件包的接入方案。
:::info
考虑到单组件形态的特点，在云音乐业务场景中，TangoStudio 将会与红石物料中心对接，提供业务组件的自动化接入能力，目前该能力正在开发过程中。
:::
apps/website/docs/designer/modules/designer-panel.mdx
-9
View File
@@ -1,9 +0,0 @@
# DesignerPanel 设计器布局容器
设计器的主框架提供了一个基本的低代码设计器的布局容器，你可以很轻松的通过此布局容器来实现自己的设计器布局。
## 属性列表
import TypesTable from '@site/src/components/TypesTable';
<TypesTable name="DesignerPanelProps" />
apps/website/docs/designer/modules/designer.mdx
-56
View File
@@ -1,56 +0,0 @@
# Designer 设计器容器
设计器根节点，注入全局状态。
## 属性列表
import TypesTable from '@site/src/components/TypesTable';
<TypesTable name="DesignerProps" />
## 设计器初始化
```jsx
<Designer engine={engine} sandboxQuery={sandboxQuery} remoteServices={remoteServices}></Designer>
```
## engine
设计器引擎实例，用于管理设计器的核心状态。
### 基本的初始化方式
```js
const engine = createEngine({
entry: '/src/index.js',
files: sampleFiles,
componentPrototypes: prototypes as any,
});
```
### 自定义 workspace 的初始化方式
默认情况下，引擎采用的是源码解析模式，即将源码解析为 ast 树，后续的搭建逻辑转为对 ast 树的操作。如果你想自定义搭建逻辑，可以通过自定义 workspace 的方式来实现。
引擎在 2.0 本本中提供了新的 JsonWorkspace 来支持自定义搭建逻辑，JsonWorkspace 采用的是 json 格式的数据结构，你可以通过自定义 json 来实现自定义搭建逻辑。
```js
const engine = createEngine({
workspace: new JsonWorkspace({
prototypes: prototypes as any,
files: schemaFiles,
}),
});
```
:::tip
按照这种方式，你可以自定义自己的 Workspace 实现。具体可以参考 Workspace 的实现标准。
:::
## sandboxQuery
沙箱的查询实例，用于向沙箱注册 dom 查询能力。
## remoteServices
远程服务实例，用于注册全局共享的数据服务实例。
apps/website/docs/designer/modules/hooks.mdx
-27
View File
@@ -1,27 +0,0 @@
# Hooks 钩子方法
设计器提供了一组 Hooks 用于快速获取设计器的各种状态。
import TypesTable from '@site/src/components/TypesTable';
## useWorkspace
获取工作区状态。
```js
// App 需要放置在 Designer 容器中
function App() {
const workspace = useWorkspace();
// do what you want
}
```
## useDesigner
```js
// App 需要放置在 Designer 容器中
function App() {
const designer = useDesigner();
// do what you want
}
```
apps/website/docs/designer/modules/sandbox.mdx
-9
View File
@@ -1,9 +0,0 @@
# Sandbox 沙箱
设计器的运行时沙箱，用来执行代码，渲染页面。
import TypesTable from '@site/src/components/TypesTable';
默认沙箱是一个基于 CodeSandbox 的沙箱实例，可以直接在浏览器端执行代码。
<TypesTable name="SandboxProps" />
apps/website/docs/designer/modules/setting-panel.mdx
-9
View File
@@ -1,9 +0,0 @@
# SettingPanel 属性设置面板
属性设置器用于在配置面板中展示特定配置项的配置逻辑。
## 属性列表
import TypesTable from '@site/src/components/TypesTable';
<TypesTable name="SettingPanelProps" />
apps/website/docs/designer/modules/sidebar-panel.mdx
-38
View File
@@ -1,38 +0,0 @@
# SidebarPanel 侧边栏面板
侧边栏面板提供了一个简单易用的主操作面板，可以将一些高频操作和核心部件放置到侧边栏面板中，方便用户快速操作。
## 属性列表
import TypesTable from '@site/src/components/TypesTable';
<TypesTable name="SidebarPanelProps" />
## 创建浮动面板
借助 `isFloat` 和 `width` 属性可以创建浮动自定义宽度面板，脱离框架对侧边栏的宽度限制。
```jsx
<SidebarPanel.Item key="history" isFloat width="40vw" />
```
## 徽标提示
`showBadge` 属性可以设置工具栏是否显示徽标提示，用于某些面板需要对外展现需要被用户注意的时机。
<img
alt="img"
src="https://p6.music.126.net/obj/wonDlsKUwrLClGjCm8Kx/18224398190/2847/b86d/df55/c817e86a0b1b3a6b08f7cc98362caec5.png"
width="300px"
/>
```jsx
<SidebarPanel.Item
key="info"
label="消息"
title="消息列表"
icon={<NotificationOutlined />}
showBadge={{ count: 2 }}>
<Box>info panel</Box>
</SidebarPanel.Item>
```
apps/website/docs/designer/modules/view-panel.mdx
-10
View File
@@ -1,10 +0,0 @@
# ViewPanel 主视图面板
设计器的主视图面板，用来放置设计器的主视图，包括：沙箱，编辑器，预览等。主视图可以放置多个，但只有一个会在激活状态。
## 属性列表
import TypesTable from '@site/src/components/TypesTable';
<TypesTable name="ViewPanelProps" />
apps/website/docs/designer/modules/workspace-panel.mdx
-3
View File
@@ -1,3 +0,0 @@
# WorkspacePanel 工作区面板
主工作区的布局容器，用于放置工作区的多重视图。
apps/website/docusaurus.config.js
+9 -15
View File
@@ -62,13 +62,13 @@ const config = {
({
// Replace with your project's social card
image: 'img/social-card.png',
// announcementBar: {
// id: 'notion_alert',
// content: '🏗 当前版本为测试版，请暂时不要用于生产环境，正式版将于2023年Q4发布！',
// backgroundColor: 'var(--ifm-color-primary-contrast-background)',
// textColor: 'var(--ifm-color-primary-contrast-foreground)',
// isCloseable: false,
// },
announcementBar: {
id: 'notion_alert',
content: '🏗 当前版本为 alpha 版本，相关文档正在编写之中，敬请期待！',
backgroundColor: 'var(--ifm-color-primary-contrast-background)',
textColor: 'var(--ifm-color-primary-contrast-foreground)',
isCloseable: false,
},
navbar: {
title: '',
logo: {
@@ -88,12 +88,6 @@ const config = {
position: 'left',
label: '应用框架',
},
{
type: 'docSidebar',
sidebarId: 'protocol',
position: 'left',
label: '协议',
},
{ to: '/blog', label: '博客', position: 'left' },
{
type: 'html',
@@ -127,8 +121,8 @@ const config = {
title: '社区',
items: [
{
label: 'Stack Overflow',
href: 'https://stackoverflow.com/questions/tagged/netease-tango',
label: 'Discussions',
href: 'https://github.com/NetEase/tango/discussions',
},
{
label: 'Discord',
apps/website/sidebars.js
+26 -23
View File
@@ -20,28 +20,31 @@ const sidebars = {
designer: [
'intro',
'designer/quick-start',
// {
// type: 'category',
// label: '模块',
// items: [
// 'designer/modules/designer',
// 'designer/modules/designer-panel',
// 'designer/modules/sidebar-panel',
// 'designer/modules/setting-panel',
// 'designer/modules/workspace-panel',
// 'designer/modules/view-panel',
// 'designer/modules/sandbox',
// 'designer/modules/hooks',
// ],
// collapsible: false,
// },
// {
// type: 'category',
// label: '扩展',
// items: ['designer/extend/overview', 'designer/extend/remote-service'],
// collapsible: false,
// },
// 'designer/setters',
{
type: 'category',
label: '接入指南',
items: ['designer/deploy/designer', 'designer/deploy/sandbox', 'designer/deploy/server'],
collapsed: false,
},
{
type: 'category',
label: '设计器自定义',
items: [
'designer/customize/panels',
'designer/customize/tools',
'designer/customize/sidebar',
'designer/customize/setters',
'designer/customize/editor',
'designer/customize/components',
],
collapsed: false,
},
{
type: 'category',
label: '设计原理',
items: ['designer/design/overview', 'designer/design/filesystem', 'designer/design/sandbox'],
collapsed: false,
},
],
boot: [
@@ -59,7 +62,7 @@ const sidebars = {
// 'boot/i18n',
],
protocol: ['protocol/material-protocol', 'protocol/material-package-spec'],
// protocol: ['protocol/material-protocol', 'protocol/material-package-spec'],
};
module.exports = sidebars;
apps/website/src/components/Timeline.tsx
+6 -15
View File
@@ -6,37 +6,28 @@ const timelines = [
{
icon: null,
title: 'Alpha',
date: '2023.08.30',
date: '2024.01.31',
description: translate({
id: 'homepage.timeline.alpha',
message: '开源仓库和文档站点上线，发布 alpha 演示版本。',
}),
},
{
icon: null,
title: 'Beta',
date: '2023.09.30',
description: translate({
id: 'homepage.timeline.beta',
message: '核心 API 面向社区场景重构和优化，发布 Beta 测试版本。',
message: '核心 API 重构完成，文档内容优化',
}),
},
{
icon: null,
title: '1.0 RC',
date: '2023.11.30',
date: '2024.04.30',
description: translate({
id: 'homepage.timeline.rc',
message: '核心 API 基本稳定，不再发生 BR，发布 1.0 RC 版本。',
message: '核心 API 基本稳定，能力完善。',
}),
},
{
icon: null,
title: '1.0',
date: 'Before 2023.12.29',
date: 'Before 2024.12.31',
description: translate({
id: 'homepage.timeline.stable',
message: 'API 完全稳定，提供良好的社区支持，可用于生产环境。',
message: '1.0 正式版常规迭代',
}),
},
];
apps/website/src/pages/index.tsx
+7 -19
View File
@@ -24,30 +24,18 @@ function HomepageHeader() {
{translate({ id: 'homepage.hero.tagline', message: siteConfig.tagline })}
</p>
<div className={styles.buttons}>
<Link className="button button--primary button--lg" to="/docs/intro">
{translate({
id: 'homepage.hero.button.document',
message: '快速开始',
})}
</Link>
<Link
className="button button--primary button--lg"
className="button button--secondary button--lg"
to="https://tango-demo.musicfe.com/designer/"
>
{translate({ id: 'homepage.hero.button.playground', message: '演示应用' })}
</Link>
<Link className="button button--secondary button--lg" to="/docs/intro">
{translate({
id: 'homepage.hero.button.document',
message: '使用文档',
})}
</Link>
<a
href="https://www.producthunt.com/posts/tango-b8474917-fbce-4180-9fac-4ac7d7a6fa7d?utm_source=badge-featured&utm_medium=badge&utm_souce=badge-tango&#0045;b8474917&#0045;fbce&#0045;4180&#0045;9fac&#0045;4ac7d7a6fa7d"
target="_blank"
rel="noreferrer"
>
<img
src="https://api.producthunt.com/widgets/embed-image/v1/featured.svg?post_id=412854&theme=light"
alt="Tango - A&#0032;source&#0032;code&#0032;based&#0032;low&#0045;code&#0032;builder | Product Hunt"
width="250px"
height="54px"
/>
</a>
</div>
<div className={styles.heroImageBox}>
<img
package.json
+1 -1
View File
@@ -12,7 +12,7 @@
"deploy:site": "yarn workspace website deploy",
"build": "lerna run build",
"build:site": "yarn workspace website build",
"typedoc": "typedoc --options typedoc.json",
"typedoc": "typedoc",
"docs": "yarn typedoc && open docs/index.html",
"test": "jest",
"test:watch": "jest --watch",