Skip to content

Commit

Permalink
docs: update
Browse files Browse the repository at this point in the history
  • Loading branch information
@wwsun
wwsun committed Feb 19, 2024
1 parent 5ca8fc6 commit bc06a86
Show file tree
Hide file tree
Showing 10 changed files with 357 additions and 22 deletions.
132 changes: 131 additions & 1 deletion apps/website/docs/designer/customize/components.mdx
View file
Original file line number Diff line number Diff line change
@@ -1,5 +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` | - |
73 changes: 70 additions & 3 deletions apps/website/docs/designer/customize/panels.mdx
View file
Original file line number Diff line number Diff line change
@@ -1,5 +1,72 @@
# 面板自定义

:::tip
正在编写中，敬请期待。
:::
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>
);
}
```
5 changes: 2 additions & 3 deletions apps/website/docs/designer/customize/selections.mdx
View file
Original file line number Diff line number Diff line change
@@ -1,5 +1,4 @@
# 选择器自定义

:::tip
正在编写中，敬请期待。
:::
提供设计器视图中用户选中某个区域后展示的快捷工具。

17 changes: 17 additions & 0 deletions apps/website/docs/designer/customize/setters.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,23 @@

属性设置器用于在配置面板中展示特定配置项的配置逻辑。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 | - |

## 内置属性设置器

| 设置器名 | 接收值类型 | 设置器说明 | 可配置项 |
Expand Down
53 changes: 53 additions & 0 deletions apps/website/docs/designer/customize/sidebar.mdx
View file
Original file line number Diff line number Diff line change
@@ -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>
```
54 changes: 51 additions & 3 deletions apps/website/docs/designer/customize/tools.mdx
View file
Original file line number Diff line number Diff line change
@@ -1,5 +1,53 @@
# 工具栏自定义

:::tip
正在编写中，敬请期待。
:::
提供了默认的设计器工具栏的布局设置。

## 工具栏组件

### 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>
```
15 changes: 14 additions & 1 deletion apps/website/docs/designer/deploy/designer.mdx
View file
Original file line number Diff line number Diff line change
@@ -1,5 +1,18 @@
# 设计器接入

设计器为用户提供应用搭建的可视化界面。有两种方式初始化低代码设计器：

1. clone 官方示例代码，按照文档说明直接启动项目。
2. 手工引入设计器的 npm 包，自定义配置、启动、运行。

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

WIP

:::tip
正在编写中，敬请期待。
官方示例是一个包含了低代码设计器前后端低完整项目，可以直接启动。对于后端部分，作为示例而言，仅提供了最基本的逻辑，用户需要按照需求自行扩展。
:::

## 方法2: 手工引入设计器的 npm 包

WIP
Loading

0 comments on commit bc06a86

Please sign in to comment.