From bc06a868eebc8b7a50a198f5ee7643c8acf3d7ba Mon Sep 17 00:00:00 2001 From: Wells Date: Mon, 19 Feb 2024 16:35:04 +0800 Subject: [PATCH] docs: update --- .../docs/designer/customize/components.mdx | 132 +++++++++++++++++- .../docs/designer/customize/panels.mdx | 73 +++++++++- .../docs/designer/customize/selections.mdx | 5 +- .../docs/designer/customize/setters.mdx | 17 +++ .../docs/designer/customize/sidebar.mdx | 53 +++++++ .../website/docs/designer/customize/tools.mdx | 54 ++++++- .../website/docs/designer/deploy/designer.mdx | 15 +- apps/website/docs/designer/deploy/sandbox.mdx | 20 ++- apps/website/docusaurus.config.js | 6 - apps/website/sidebars.js | 4 +- 10 files changed, 357 insertions(+), 22 deletions(-) create mode 100644 apps/website/docs/designer/customize/sidebar.mdx diff --git a/apps/website/docs/designer/customize/components.mdx b/apps/website/docs/designer/customize/components.mdx index 2ef96420..0567dada 100644 --- a/apps/website/docs/designer/customize/components.mdx +++ b/apps/website/docs/designer/customize/components.mdx @@ -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` 文件则是用来描述组件的属性和行为的，用于在设计器中渲染组件的配置项，和控制组件的拖拽行为等。 + +一个可供参考的示例代码是 + +### 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` | - | diff --git a/apps/website/docs/designer/customize/panels.mdx b/apps/website/docs/designer/customize/panels.mdx index 9c060b2f..ae9cc66f 100644 --- a/apps/website/docs/designer/customize/panels.mdx +++ b/apps/website/docs/designer/customize/panels.mdx @@ -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 ( + + } + description={} + actions={ + + + + + + + + + + + + + + + + } + > + + } /> + } /> + + + + + + + + + + + + + ); +} +``` diff --git a/apps/website/docs/designer/customize/selections.mdx b/apps/website/docs/designer/customize/selections.mdx index 88a0e3ea..d2a474c7 100644 --- a/apps/website/docs/designer/customize/selections.mdx +++ b/apps/website/docs/designer/customize/selections.mdx @@ -1,5 +1,4 @@ # 选择器自定义 -:::tip -正在编写中，敬请期待。 -::: +提供设计器视图中用户选中某个区域后展示的快捷工具。 + diff --git a/apps/website/docs/designer/customize/setters.mdx b/apps/website/docs/designer/customize/setters.mdx index 534a64ba..b92b2ea4 100644 --- a/apps/website/docs/designer/customize/setters.mdx +++ b/apps/website/docs/designer/customize/setters.mdx @@ -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 | - | + ## 内置属性设置器 | 设置器名 | 接收值类型 | 设置器说明 | 可配置项 | diff --git a/apps/website/docs/designer/customize/sidebar.mdx b/apps/website/docs/designer/customize/sidebar.mdx new file mode 100644 index 00000000..e213b823 --- /dev/null +++ b/apps/website/docs/designer/customize/sidebar.mdx @@ -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` 的子节点传入自定义的内容来渲染需要的结果，例如： + +```jsx +}> +
展开的内容部分
+ +``` diff --git a/apps/website/docs/designer/customize/tools.mdx b/apps/website/docs/designer/customize/tools.mdx index f8aaa037..df9f7ffd 100644 --- a/apps/website/docs/designer/customize/tools.mdx +++ b/apps/website/docs/designer/customize/tools.mdx @@ -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` 的子节点传入自定义的工具栏项，例如: + +```jsx + + + + + +``` diff --git a/apps/website/docs/designer/deploy/designer.mdx b/apps/website/docs/designer/deploy/designer.mdx index 197b56dd..53fed846 100644 --- a/apps/website/docs/designer/deploy/designer.mdx +++ b/apps/website/docs/designer/deploy/designer.mdx @@ -1,5 +1,18 @@ # 设计器接入 +设计器为用户提供应用搭建的可视化界面。有两种方式初始化低代码设计器： + +1. clone 官方示例代码，按照文档说明直接启动项目。 +2. 手工引入设计器的 npm 包，自定义配置、启动、运行。 + +## 方法1: 通过示例代码启动设计器 + +WIP + :::tip -正在编写中，敬请期待。 +官方示例是一个包含了低代码设计器前后端低完整项目，可以直接启动。对于后端部分，作为示例而言，仅提供了最基本的逻辑，用户需要按照需求自行扩展。 ::: + +## 方法2: 手工引入设计器的 npm 包 + +WIP diff --git a/apps/website/docs/designer/deploy/sandbox.mdx b/apps/website/docs/designer/deploy/sandbox.mdx index 0cd02fa0..3852b2b9 100644 --- a/apps/website/docs/designer/deploy/sandbox.mdx +++ b/apps/website/docs/designer/deploy/sandbox.mdx @@ -1,5 +1,19 @@ # 低代码沙箱接入 -:::tip -正在编写中，敬请期待。 -::: +沙箱是搭建产物（对于 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 diff --git a/apps/website/docusaurus.config.js b/apps/website/docusaurus.config.js index 4a528e55..887e26a1 100644 --- a/apps/website/docusaurus.config.js +++ b/apps/website/docusaurus.config.js @@ -88,12 +88,6 @@ const config = { position: 'left', label: '应用框架', }, - { - type: 'docSidebar', - sidebarId: 'protocol', - position: 'left', - label: '协议', - }, { to: '/blog', label: '博客', position: 'left' }, { type: 'html', diff --git a/apps/website/sidebars.js b/apps/website/sidebars.js index b192331f..08100087 100644 --- a/apps/website/sidebars.js +++ b/apps/website/sidebars.js @@ -32,7 +32,7 @@ const sidebars = { items: [ 'designer/customize/panels', 'designer/customize/tools', - 'designer/customize/selections', + 'designer/customize/sidebar', 'designer/customize/setters', 'designer/customize/editor', 'designer/customize/components', @@ -62,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;