Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: update #95

Merged
merged 6 commits into from
Feb 19, 2024
Merged

docs: update #95

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
4c0f58a
docs: update
wwsun Jan 23, 2024
e6ca089
docs: update
wwsun Jan 25, 2024
24d8413
docs: update
wwsun Jan 25, 2024
5ca8fc6
docs: add setters
wwsun Jan 25, 2024
bc06a86
docs: update
wwsun Feb 19, 2024
ad2d859
chore: add typedoc workflow
wwsun Feb 19, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
34 changes: 34 additions & 0 deletions .github/workflows/typedoc.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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
135 changes: 135 additions & 0 deletions apps/website/docs/designer/customize/components.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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` | - |
5 changes: 5 additions & 0 deletions apps/website/docs/designer/customize/editor.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
# 编辑器自定义

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

提供设计器视图中用户选中某个区域后展示的快捷工具。

22 changes: 18 additions & 4 deletions apps/website/docs/designer/setters.mdx → ...bsite/docs/designer/customize/setters.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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 | - |

## 内置属性设置器

| 设置器名 | 接收值类型 | 设置器说明 | 可配置项 |
Expand All @@ -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 | 文本域设置器 | |
Expand All @@ -29,7 +44,6 @@
| sliderSetter | number | 滑块设置器 | |
| listSetter | `object[]` | 列表值设置器 | |
| renderPropsSetter | Function | render props 设置器 | |
| imageSetter | string | 云鹿图片设置器 | |

## 注册自定义属性设置器

Expand Down
53 changes: 53 additions & 0 deletions apps/website/docs/designer/customize/sidebar.mdx
View file
Open in desktop
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>
```
Loading
Loading