diff --git a/docs/.gitignore b/docs/.gitignore new file mode 100644 index 000000000..b2d6de306 --- /dev/null +++ b/docs/.gitignore @@ -0,0 +1,20 @@ +# Dependencies +/node_modules + +# Production +/build + +# Generated files +.docusaurus +.cache-loader + +# Misc +.DS_Store +.env.local +.env.development.local +.env.test.local +.env.production.local + +npm-debug.log* +yarn-debug.log* +yarn-error.log* diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 000000000..12c8f1fbe --- /dev/null +++ b/docs/README.md @@ -0,0 +1,46 @@ +# Low-Code Engine 文档中心（site） + +This website is built using [Docusaurus 2](https://docusaurus.io/), a modern static website generator. + +### 安装 + +``` +$ yarn +``` + +### 本地开发 + +``` +$ yarn start +``` + +This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server. + +### 构建 + +``` +$ yarn build +``` + +### 部署 +```bash +1. npm run build +2. npm publish # 记得改下版本号，比如 1.0.1 + +# 发布完后执行 tnpm sync +3. tnpm sync + +4. 更新 diamond 版本 1.0.1 +5. lowcode-engine.cn 站点生效 +``` + + +## 功能 +- [x] 支持本地离线搜搜 +- [x] 版本化文档管理 +- [x] 离线静态部署 +- [x] 主题（fork 宜搭开发者中心） + +## 使用文档 +https://docusaurus.io/zh-CN/docs/docs-introduction + diff --git a/docs/babel.config.js b/docs/babel.config.js new file mode 100644 index 000000000..e00595dae --- /dev/null +++ b/docs/babel.config.js @@ -0,0 +1,3 @@ +module.exports = { + presets: [require.resolve('@docusaurus/core/lib/babel/preset')], +}; diff --git a/docs/code-specification.md b/docs/community/code-specification.md similarity index 97% rename from docs/code-specification.md rename to docs/community/code-specification.md index 0a7c9f555..f4378ee2c 100644 --- a/docs/code-specification.md +++ b/docs/community/code-specification.md @@ -1,3 +1,7 @@ +--- +title: 编码规约 +--- + 编码规约 --- diff --git a/docs/community/img/i-see.png b/docs/community/img/i-see.png new file mode 100644 index 000000000..43143ea77 Binary files /dev/null and b/docs/community/img/i-see.png differ diff --git a/docs/community/img/you-think.png b/docs/community/img/you-think.png new file mode 100644 index 000000000..26e927578 Binary files /dev/null and b/docs/community/img/you-think.png differ diff --git a/docs/community/issue.md b/docs/community/issue.md new file mode 100644 index 000000000..f0afc90d2 --- /dev/null +++ b/docs/community/issue.md @@ -0,0 +1,112 @@ +--- +title: 关于引擎的 issue 说明 +sidebar_position: 2 +--- +> 提交地址：[https://github.com/alibaba/lowcode-engine/issues](https://github.com/alibaba/lowcode-engine/issues) + +### 提交前必读 +由于引擎项目复杂，很多问题在复现和沟通上无法花费太多时间，需要大家尽力将复现步骤说明白。 + + +![image.png](./img/you-think.png) + +**你以为的 issue** + + +![image.png](./img/i-see.png) + +**我们看到的 issue** + +为了更好的进行协作，对引擎 issue 的处理定了一些处理的优先级。请大家认真阅读 Orz. + +- 【支持快】通过线上 Demo 地址 + 控制台输入 API 可复现。 +- 【支持快】通过线上 Demo + 导入 schema 可复现 +- 【支持稍慢】通过线上 Demo + 完整操作步骤可复现 +- 【支持稍慢】通过线上 Demo + 变更代码可复现，并清楚的说明变更代码的位置和内容 +- 【支持慢】有完整的项目地址，下载下来可直接安装依赖并启动复现的 +- 【支持慢】需求类型的由于人力有限，欢迎大家 PR，如能讲清楚背景上下文和场景，项目维护团队更容易给出方案建议或方向指引。 +- 【不保证提供支持】其他 + - 只有标题没有复现步骤 + - 复现步骤不清晰 + - 和引擎无关的 + +### 不同优先级的示例 +#### 【支持快】通过线上 Demo 地址 + 控制台输入 API 可复现。 +**示例** +![image.png](https://cdn.nlark.com/yuque/0/2022/png/2622706/1656387671833-cd44507b-af59-45ec-b0da-f4f0ef61e92e.png#clientId=uaa040ac3-dccc-4&crop=0&crop=0&crop=1&crop=1&from=paste&height=295&id=ub61f0ab8&margin=%5Bobject%20Object%5D&name=image.png&originHeight=1862&originWidth=3322&originalType=binary&ratio=1&rotation=0&showTitle=false&size=5033674&status=done&style=none&taskId=u3646a3b6-4b22-48e7-94e3-564a09cfa24&title=&width=527) +复现步骤： + +- 打开线上 demo +- 在控制台输入 +```json +// 当前 doc +const doc = window.AliLowCodeEngine.project.currentDocument + +// 新建 doc 并成功切换 +window.AliLowCodeEngine.project.openDocument({ + componentName: 'Page' +}); + +// 无法切换回来 +window.AliLowCodeEngine.project.openDocument('docl4xkca5b') +``` + +预期效果： + +- 使用 openDocument 可以正常的切换回原来的 doc + +#### 【支持快】通过线上 demo + 导入 schema 可复现 +步骤： + +- 使用线上 demo +- 导入下面的 schema +- schema 代码/schema zip 压缩包 +- 页面效果如下 + +期望： + +- 页面中的xxx部分和预期不符合，期望的效果是 xxx + +#### 【支持稍慢】通过线上 demo + 完整操作步骤可复现 +**示例** +1.使用 antd 组件 +![image.png](https://cdn.nlark.com/yuque/0/2022/png/2622706/1656387998779-9f621c7f-82cb-48ad-94fc-84c2cd46065c.png#clientId=uaa040ac3-dccc-4&crop=0&crop=0&crop=1&crop=1&from=paste&height=906&id=u0ad0726a&margin=%5Bobject%20Object%5D&name=image.png&originHeight=1812&originWidth=3584&originalType=binary&ratio=1&rotation=0&showTitle=false&size=838860&status=done&style=none&taskId=u0a0a9e20-f79e-4c8c-8c82-b304f7b7583&title=&width=1792) + +2.拖拽这个组件 +![image.png](https://cdn.nlark.com/yuque/0/2022/png/2622706/1656388046560-e07680ee-809a-4ad1-bc47-47c2c00fdd40.png#clientId=uaa040ac3-dccc-4&crop=0&crop=0&crop=1&crop=1&from=paste&height=901&id=u23c8416a&margin=%5Bobject%20Object%5D&name=image.png&originHeight=1802&originWidth=3584&originalType=binary&ratio=1&rotation=0&showTitle=false&size=890196&status=done&style=none&taskId=u7ac32b55-f32c-4215-ac1d-f81f5e986ac&title=&width=1792) + +3.配置该属性值为 100 +![image.png](https://cdn.nlark.com/yuque/0/2022/png/2622706/1656388075312-7c06f15a-464a-49f0-beb5-19320ea0e454.png#clientId=uaa040ac3-dccc-4&crop=0&crop=0&crop=1&crop=1&from=paste&height=900&id=ua91e7f85&margin=%5Bobject%20Object%5D&name=image.png&originHeight=1800&originWidth=3584&originalType=binary&ratio=1&rotation=0&showTitle=false&size=882142&status=done&style=none&taskId=u61082c8a-1092-4b5b-a2ea-00486cadb71&title=&width=1792) + +期望效果： + +- 组件同配置一致 + +#### 【支持稍慢】通过线上 demo + 变更代码可复现，并清楚的说明变更代码的位置和内容 +**示例** +![image.png](https://cdn.nlark.com/yuque/0/2022/png/2622706/1656387894830-6850815f-e2ee-46bf-a2bf-fdda4d166691.png#clientId=uaa040ac3-dccc-4&crop=0&crop=0&crop=1&crop=1&from=paste&height=377&id=u87419dd1&margin=%5Bobject%20Object%5D&name=image.png&originHeight=754&originWidth=1892&originalType=binary&ratio=1&rotation=0&showTitle=false&size=226627&status=done&style=none&taskId=u88b2bbb8-869c-482c-9510-9d513f6e191&title=&width=946) + +![image.png](https://cdn.nlark.com/yuque/0/2022/png/2622706/1656387911054-771dd7fc-db90-46ae-b1db-f5f9f7537ed4.png#clientId=uaa040ac3-dccc-4&crop=0&crop=0&crop=1&crop=1&from=paste&height=389&id=u0a370108&margin=%5Bobject%20Object%5D&name=image.png&originHeight=778&originWidth=1917&originalType=binary&ratio=1&rotation=0&showTitle=false&size=229881&status=done&style=none&taskId=ucbc7af71-f0e1-4319-9097-8ad6b936c5e&title=&width=958.5) + +![image.png](https://cdn.nlark.com/yuque/0/2022/png/2622706/1656387922644-de3f1d64-0206-407d-82ad-2d1155374e37.png#clientId=uaa040ac3-dccc-4&crop=0&crop=0&crop=1&crop=1&from=paste&height=127&id=u9c5921eb&margin=%5Bobject%20Object%5D&name=image.png&originHeight=253&originWidth=1836&originalType=binary&ratio=1&rotation=0&showTitle=false&size=58615&status=done&style=none&taskId=u5c8af90a-0d20-40c8-a1f2-e387f037d85&title=&width=918) + +![image.png](https://cdn.nlark.com/yuque/0/2022/png/2622706/1656387931330-a5453ba1-264b-4325-b3a8-7cb6e22633ee.png#clientId=uaa040ac3-dccc-4&crop=0&crop=0&crop=1&crop=1&from=paste&height=457&id=u687acf85&margin=%5Bobject%20Object%5D&name=image.png&originHeight=914&originWidth=1912&originalType=binary&ratio=1&rotation=0&showTitle=false&size=129980&status=done&style=none&taskId=u3a706b70-0da6-484d-857d-1d086f7a4e5&title=&width=956) + +#### 【支持慢】有完整的项目地址，下载下来可直接安装依赖并启动复现的 +由于完整的项目中有很多冗余的信息，这部分排查起来十分耗时且困难。不推荐使用改方式。 + +#### 【不保证提供支持】其他 +##### 只有标题没有复现步骤 +![image.png](https://cdn.nlark.com/yuque/0/2022/png/2622706/1656388351815-e086b980-0828-4c49-ba72-142446313d2d.png#clientId=uaa040ac3-dccc-4&crop=0&crop=0&crop=1&crop=1&from=paste&height=510&id=u79a38c3b&margin=%5Bobject%20Object%5D&name=image.png&originHeight=1020&originWidth=2520&originalType=binary&ratio=1&rotation=0&showTitle=false&size=529258&status=done&style=none&taskId=u3540b08e-9dff-4c72-8ee5-123912439b0&title=&width=1260) + +##### 复现步骤不清晰 +![image.png](https://cdn.nlark.com/yuque/0/2022/png/2622706/1656388451393-2168e5ca-20de-4781-9e51-20e282dbc0ca.png#clientId=uaa040ac3-dccc-4&crop=0&crop=0&crop=1&crop=1&from=paste&height=833&id=ubaf001f6&margin=%5Bobject%20Object%5D&name=image.png&originHeight=1666&originWidth=3584&originalType=binary&ratio=1&rotation=0&showTitle=false&size=1228630&status=done&style=none&taskId=ub26ed4ff-e0cf-4644-9a65-00ddee4b9e5&title=&width=1792) + +##### 和引擎无关的 +![image.png](https://cdn.nlark.com/yuque/0/2022/png/2622706/1656388376995-0ab5d7c0-8ff9-49cf-8854-70e9bb3ff87a.png#clientId=uaa040ac3-dccc-4&crop=0&crop=0&crop=1&crop=1&from=paste&height=715&id=uffc59321&margin=%5Bobject%20Object%5D&name=image.png&originHeight=1430&originWidth=2548&originalType=binary&ratio=1&rotation=0&showTitle=false&size=747119&status=done&style=none&taskId=u861d5fa6-f673-4091-8635-ff45adf680e&title=&width=1274) + + + + +### 扩展阅读 +强烈推荐阅读 [《提问的智慧》](https://github.com/ryanhanwu/How-To-Ask-Questions-The-Smart-Way)、[《如何向开源社区提问题》](https://github.com/seajs/seajs/issues/545) 和 [《如何有效地报告 Bug》](http://www.chiark.greenend.org.uk/~sgtatham/bugs-cn.html)、[《如何向开源项目提交无法解答的问题》](https://zhuanlan.zhihu.com/p/25795393)，更好的问题更容易获得帮助。（此段参考 [antd](https://github.com/ant-design/ant-design)） diff --git a/docs/config/navbar.js b/docs/config/navbar.js new file mode 100644 index 000000000..efbe88ec0 --- /dev/null +++ b/docs/config/navbar.js @@ -0,0 +1,82 @@ +/** + * 此配置的修改，如未生效，可以重新启动下即可 + */ +module.exports = { + title: '', + logo: { + alt: 'LowCode-Engine', + src: 'https://img.alicdn.com/imgextra/i2/O1CN01uv6vu822RBCSYLro2_!!6000000007116-55-tps-139-26.svg', + srcDark: 'https://tianshu.alicdn.com/052a190e-c961-4afe-aa4c-49ee9722952d.svg', + }, + items: [ + { + type: 'doc', + docId: 'guide/quickStart/intro', + position: 'left', + label: '文档', + }, + { + type: 'doc', + docId: 'api/index', + position: 'left', + label: 'API', + }, + { + type: 'doc', + docId: 'faq/index', + position: 'left', + label: 'FAQ', + }, + { + type: 'doc', + docId: 'participate/index', + position: 'left', + label: '参与贡献', + }, + { + type: 'doc', + docId: 'article/index', + position: 'left', + label: '文章', + }, + { + type: 'doc', + docId: 'demoUsage/intro', + position: 'left', + label: 'Demo 使用文档', + }, + { + position: 'left', + href: 'https://developer.aliyun.com/ebook/7507', + label: '技术白皮书', + }, + { + position: 'left', + href: 'https://github.com/alibaba/lowcode-engine/releases', + label: '更新日志', + }, + { + to: '/community/issue', + position: 'left', + label: '社区', + activeBaseRegex: '/community/', + }, + // 版本切换，如需，这里开启即可 + // { + // type: 'docsVersionDropdown', + // position: 'right', + // dropdownActiveClassDisabled: true, + // }, + // { + { + href: 'https://github.com/alibaba/lowcode-engine', + position: 'right', + className: 'header-github-link', + 'aria-label': 'GitHub repository', + }, + { + type: 'search', + position: 'right', + }, + ], +}; diff --git a/docs/config/sidebars.js b/docs/config/sidebars.js new file mode 100644 index 000000000..fc14767a3 --- /dev/null +++ b/docs/config/sidebars.js @@ -0,0 +1,55 @@ +/* + * Copyright (c) Facebook, Inc. and its affiliates. + * + * This source code is licensed under the MIT license found in the + * LICENSE file in the root directory of this source tree. + */ +const getDocsFromDir = require('../scripts/getDocsFromDir'); + +module.exports = { + // 手动配置的导航 + // guide: [ + // 'guide/quickStart/intro', + // 'guide/quickStart/start', + // { + // type: 'category', + // label: 'FAQ', + // collapsed: false, + // items: getDocsFromDir('guide/quickStart/faq'), + // }, + // ], + /** + * 根据当前目录自动生成导航配置 + */ + guide: [ + { + type: 'autogenerated', + dirName: 'guide', // '.' 即当前的文档文件夹 + }, + ], + api: [ + { + type: 'autogenerated', + dirName: 'api', + }, + ], + faq: [ + { + type: 'autogenerated', + dirName: 'faq', + }, + ], + participate: [ + { + type: 'autogenerated', + dirName: 'participate', + }, + ], + demoUsage: [ + { + type: 'autogenerated', + dirName: 'demoUsage', + }, + ], + // api: getDocsFromDir('api'), +}; diff --git a/docs/config/sidebarsCommunity.js b/docs/config/sidebarsCommunity.js new file mode 100644 index 000000000..a96aa0521 --- /dev/null +++ b/docs/config/sidebarsCommunity.js @@ -0,0 +1,13 @@ +module.exports = { + community: [ + { + type: 'autogenerated', + dirName: '.', + }, + { + type: 'link', + label: '生态资源', + href: 'https://github.com/lowcode-workspace/awesome-lowcode-engine', + }, + ], +}; diff --git a/docs/docs/api/common.md b/docs/docs/api/common.md new file mode 100644 index 000000000..886ae925a --- /dev/null +++ b/docs/docs/api/common.md @@ -0,0 +1,57 @@ +--- +title: common - 通用 API +sidebar_position: 11 +--- +# 模块简介 +通用模块里包含除了 9 大核心模块 API 之外的所有 API，比如通用 utils、面板扩展相关 等。 +> 高能预警：之所以叫 skeletonCabin / designerCabin 跟兼容上一个版本的引擎有关系。若有必要，后面将用更有意义的命名空间来组织这些 API。 + +# 变量（variables） +### utils +通用 utils，详见下方方法签名 + +### designerCabin +设计器扩展相关，详见下方方法签名 + +### skeletonCabin +面板扩展相关，详见下方方法签名 + +# 方法签名（functions） +## utils +### isNodeSchema +是否为合法的 schema 结构 + +### isFormEvent +是否为表单事件类型 + +### getNodeSchemaById +从 schema 结构中查找指定 id 节点 + +### executeTransaction +批处理事务，用于优化特定场景的性能 +*引擎版本 >= 1.0.16 +```typescript +import { common } from '@alilc/lowcode-engine'; +import { TransitionType } from '@alilc/lowcode-types'; + +common.utils.startTransaction(() => { + node1.setProps(); + node2.setProps(); + node3.setProps(); + // ... +}, TransitionType.repaint); +``` + +## designerCabin +### isSettingField +是否是 SettingField 实例 + +### TransformStage +转换类型枚举对象，包含 init / upgrade / render 等类型，参考 [TransformStage](https://github.com/alibaba/lowcode-engine/blob/4f4ac5115d18357a7399632860808f6cffc33fad/packages/types/src/transform-stage.ts#L1) +## +## skeletonCabin +### Workbench +编辑器框架 View + +# 事件（events） +无 diff --git a/docs/docs/api/config.md b/docs/docs/api/config.md new file mode 100644 index 000000000..40d18eb3a --- /dev/null +++ b/docs/docs/api/config.md @@ -0,0 +1,107 @@ +--- +title: config - 配置 API +sidebar_position: 8 +--- +## 模块简介 +配置模块，负责配置的读、写等操作。 +## +## 变量（variables） +无 +## +## 方法签名（functions） +### get +获取指定 key 的值 + +**类型定义** +```typescript +function get(key: string, defaultValue?: any): any +``` +**调用示例** +```typescript +import { config } from '@alilc/lowcode-engine'; + +config.get('keyA', true); +config.get('keyB', { a: 1 }); +``` +### set +设置指定 key 的值 + +**类型定义** +```typescript +function set(key: string, value: any) +``` +**调用示例** +```typescript +import { config } from '@alilc/lowcode-engine'; + +config.set('keyC', 1); +``` + +### has +判断指定 key 是否有值 + +**类型定义** +```typescript +function has(key: string): boolean +``` +**调用示例** +```typescript +import { config } from '@alilc/lowcode-engine'; + +config.has('keyD'); +``` +### +### setConfig +批量设值，set 的对象版本 + +**类型定义** +```typescript +function setConfig(config: { [key: string]: any }) +``` +**调用示例** +```typescript +import { config } from '@alilc/lowcode-engine'; + +config.setConfig({ keyA: false, keyB: 2 }); +``` + +### onceGot +获取指定 key 的值，若此时还未赋值，则等待，若已有值，则直接返回值 +注：此函数返回 Promise 实例 + +**类型定义** +```typescript +function onceGot(key: string): Promise +``` +**调用示例** +```typescript +import { config } from '@alilc/lowcode-engine'; + +config.onceGot('keyA').then(value => { + console.log(`The value of keyA is ${value}`); +}); + +// or +const value = await config.onceGot('keyA'); +``` + +### onGot +获取指定 key 的值，函数回调模式，若多次被赋值，回调会被多次调用 + +**类型定义** +```typescript +function onGot(key: string, fn: (data: any) => void): () => void +``` +**调用示例** +```typescript +import { config } from '@alilc/lowcode-engine'; + +config.onGot('keyA', (value) => { + console.log(`The value of keyA is ${value}`); +}); + +const.set('keyA', 1); // 'The value of keyA is 1' +const.set('keyA', 2); // 'The value of keyA is 2' +``` +## 事件（events） +无 diff --git a/docs/docs/api/datasource.md b/docs/docs/api/datasource.md new file mode 100644 index 000000000..cadf9cb58 --- /dev/null +++ b/docs/docs/api/datasource.md @@ -0,0 +1,29 @@ +--- +title: DataSource - 数据源 API +sidebar_position: 12 +--- +### 请求数据源 +```javascript +// 请求userList （userList在数据源面板中定义） + +this.dataSourceMap['userList'].load({ + data: {} +}).then(res => {}) + .catch(error => {}); +``` + +### 获取数据源的值 +```javascript +const { userList } = this.state; +``` + +### 手动修改数据源值 +```javascript +// 获取数据源面板中定义的值 +const { user } = this.state; + +// 修改state值 +this.setState({ + user: {} +}); +``` diff --git a/docs/docs/api/event.md b/docs/docs/api/event.md new file mode 100644 index 000000000..26232b7c1 --- /dev/null +++ b/docs/docs/api/event.md @@ -0,0 +1,81 @@ +--- +title: event - 事件 API +sidebar_position: 7 +--- +## 模块简介 +负责事件处理 API，支持自定义监听事件、触发事件。 + +## 方法签名（functions） +### on +监听事件 + +**类型定义** +```typescript +function on(event: string, listener: (...args: unknown[]) => void): void; +``` + +### off +取消监听事件 + +**类型定义** +```typescript +function off(event: string, listener: (...args: unknown[]) => void): void; +``` + +### emit +触发事件 + +**类型定义** + +```typescript +function emit(event: string, ...args: unknown[]): void; +``` + +## 使用示例 +### 事件触发和监听 +```typescript +const eventName = 'eventName'; + +// 事件监听 +event.on(`common:${eventName}`); + +// 触发事件 +event.emit(eventName); +``` + +### setter 和 setter/plugin 之间的联动 +在 A setter 中进行事件注册： +```typescript +import { event } from '@alilc/lowcode-engine'; + +const SETTER_NAME = 'SetterA'; + +class SetterA extends React.Component { + componentDidMount() { + // 这里由于面板上会有多个 setter，使用 field.id 来标记 setter 名 + this.emitEventName = `${SETTER_NAME}-${this.props.field.id}`; + event.on(`common:${this.emitEventName}.bindEvent`, this.bindEvent) + } + + bindEvent = (eventName) => { + // do someting + } + + componentWillUnmount() { + // setter 是以实例为单位的，每个 setter 注销的时候需要把事件也注销掉，避免事件池过多 + event.off(`common:${this.emitEventName}.bindEvent`, this.bindEvent) + } +} +``` +在 B setter 中触发事件，来完成通信： +```typescript +import { event } from '@alilc/lowcode-engine'; + +class SetterB extends React.Component { + bindFunction = () => { + const { field, value } = this.props; + // 这里展示的和插件进行通信, 事件规则是插件名 + 方法 + event.emit('eventBindDialog.openDialog', field.name, this.emitEventName); + } +} +``` diff --git a/docs/docs/api/hotkey.md b/docs/docs/api/hotkey.md new file mode 100644 index 000000000..60e8a3f3f --- /dev/null +++ b/docs/docs/api/hotkey.md @@ -0,0 +1,70 @@ +--- +title: hotkey - 快捷键 API +sidebar_position: 5 +--- +## 模块简介 +绑定快捷键 API，可以自定义项目快捷键使用。 + +## 方法签名（functions） +### bind +绑定快捷键 + +**类型定义** +```typescript +function bind( + combos: string[] | string, + callback: (e: KeyboardEvent, combo?: string) => any | false, + action?: string +): () => void; +``` + +**示例** +```typescript +hotkey.bind('command+s', (e) => { + e.preventDefault(); + // command+s 快捷键按下时需要执行的逻辑 +}); +``` + +## 使用示例 +### 基础示例 +```typescript +hotkey.bind('command+s', (e) => { + e.preventDefault(); + // command+s 快捷键按下时需要执行的逻辑 +}); +``` + +### 同时绑定多个快捷键 +```typescript +hotkey.bind(['command+s', 'command+c'], (e) => { + e.preventDefault(); + // command+s 或者 command+c 快捷键按下时需要执行的逻辑 +}); +``` + +### 保存快捷键配置 +```typescript +import { + hotkey, +} from '@alilc/lowcode-engine'; + +function saveSchema(schema) { + // 保存 schema 相关操作 +} + +const saveSampleHotKey = (ctx: ILowCodePluginContext) => { + return { + name: 'saveSample', + async init() { + hotkey.bind('command+s', (e) => { + e.preventDefault(); + saveSchema(); + }); + }, + }; +} + +saveSampleHotKey.pluginName = 'saveSampleHotKey'; +plugins.register(saveSampleHotKey); +``` diff --git a/docs/docs/api/index.md b/docs/docs/api/index.md new file mode 100644 index 000000000..1afccce18 --- /dev/null +++ b/docs/docs/api/index.md @@ -0,0 +1,16 @@ +--- +title: API 总览 +sidebar_position: 0 +--- + +引擎直接提供 9 大类 API，以及若干间接的 API，具体如下图： + +![image.png](https://cdn.nlark.com/yuque/0/2022/png/110793/1645445575048-cc511d60-3b84-411d-a70e-21b7a596d09c.png#clientId=uaab5e9c4-fa7b-4&crop=0&crop=0&crop=1&crop=1&from=paste&height=695&id=u8e1d0318&margin=%5Bobject%20Object%5D&name=image.png&originHeight=1390&originWidth=1278&originalType=binary&ratio=1&rotation=0&showTitle=false&size=410614&status=done&style=none&taskId=u9fdcdcfb-4e8b-4e22-8865-94181f458d0&title=&width=639) + +### API 设计约定 +一些 API 设计约定： + +1. 所有 API 命名空间都按照 variables / functions / events 来组织 +2. 事件（events）的命名格式为：on[Will|Did]VerbNoun?，参考 [https://code.visualstudio.com/api/references/vscode-api#events](https://code.visualstudio.com/api/references/vscode-api#events) +3. 基于 Disposable 模式，对于事件的绑定、快捷键的绑定函数，返回值则是解绑函数 +4. 对于属性的导出，统一用 .xxx 的 getter 模式，（尽量）不使用 .getXxx() diff --git a/docs/docs/api/init.md b/docs/docs/api/init.md new file mode 100644 index 000000000..50c5cf701 --- /dev/null +++ b/docs/docs/api/init.md @@ -0,0 +1,138 @@ +--- +title: init - 初始化 API +sidebar_position: 10 +--- +## 模块简介 +提供 init 等方法 +## 方法签名 +#### 1. init +初始化引擎 + +**方法定义** +```typescript +function init(container?: Element, options?: EngineOptions): void +``` + +**初始化引擎的参数** +```typescript +interface EngineOptions { + /** + * 指定初始化的 device + */ + device?: 'default' | 'mobile'; + /** + * 指定初始化的 deviceClassName，挂载到画布的顶层节点上 + */ + deviceClassName?: string; + /** + * 是否开启 condition 的能力，默认在设计器中不管 condition 是啥都正常展示 + */ + enableCondition?: boolean; + /** + * 开启拖拽组件时，即将被放入的容器是否有视觉反馈，默认值：false + */ + enableReactiveContainer?: boolean; + /** + * 关闭画布自动渲染，在资产包多重异步加载的场景有效，默认值：false + */ + disableAutoRender?: boolean; + /** + * 打开画布的锁定操作，默认值：false + */ + enableCanvasLock?: boolean; + /** + * 容器锁定后，容器本身是否可以设置属性，仅当画布锁定特性开启时生效， 默认值为：false + */ + enableLockedNodeSetting?: boolean; + /** + * 开启画布上的鼠标事件的冒泡，默认值：false + */ + enableMouseEventPropagationInCanvas?: boolean; + /** + * 关闭拖拽组件时的虚线响应，性能考虑，默认值：false + */ + disableDetecting?: boolean; + /** + * 定制画布中点击被忽略的 selectors，默认值：undefined + */ + customizeIgnoreSelectors?: (defaultIgnoreSelectors: string[]) => string[]; + /** + * 禁止默认的设置面板，默认值：false + */ + disableDefaultSettingPanel?: boolean; + /** + * 禁止默认的设置器，默认值：false + */ + disableDefaultSetters?: boolean; + /** + * 当选中节点切换时，是否停留在相同的设置 tab 上，默认值：false + */ + stayOnTheSameSettingTab?: boolean; + /** + * 自定义 loading 组件 + */ + loadingComponent?: ComponentType; + + /** + * @default true + * JSExpression 是否只支持使用 this 来访问上下文变量，假如需要兼容原来的 'state.xxx'，则设置为 false + */ + thisRequiredInJSE?: boolean; + + /** + * @default false + * >= 1.0.14 + * 当开启组件未找到严格模式时，渲染模块不会默认给一个容器组件 + */ + enableStrictNotFoundMode?: boolean; + + /** + * 配置指定节点为根组件 + * >= 1.0.15 + */ + focusNodeSelector?: (rootNode: Node) => Node; + + /** + * 工具类扩展 + */ + appHelper?: { + utils?: {}; + } + + [key: string]: any; +} +``` +## 使用示例 +```typescript +import { init } from '@alilc/lowcode-engine'; + +init(document.getElementById('engine'), { + enableCondition: false, +}); +``` +### +### 默认打开移动端画布 +```typescript +import { init } from '@alilc/lowcode-engine'; + +init({ + device: 'mobile', +}); +``` + +### 使用 utils 第三方工具扩展 +```json +import { init } from '@alilc/lowcode-engine'; + +init({ + device: 'mobile', + appHelper: { + utils: { + xxx: () => {console.log('123')}, + } + } +}); +``` + +在引擎中即可这样使用。 +![image.png](https://cdn.nlark.com/yuque/0/2022/png/2622706/1657272220368-9ee4430e-9e42-4746-9de8-a233840b0950.png#clientId=u951c1fcc-9dab-4&crop=0&crop=0&crop=1&crop=1&errorMessage=unknown%20error&from=paste&height=292&id=uacb8d50d&margin=%5Bobject%20Object%5D&name=image.png&originHeight=1796&originWidth=3584&originalType=binary&ratio=1&rotation=0&showTitle=false&size=1641368&status=error&style=none&taskId=u559fb5cd-4a48-4732-b169-c9868a6d7b7&title=&width=582) diff --git a/docs/docs/api/logger.md b/docs/docs/api/logger.md new file mode 100644 index 000000000..3fbb7b7fc --- /dev/null +++ b/docs/docs/api/logger.md @@ -0,0 +1,49 @@ +--- +title: logger - 日志 API +sidebar_position: 9 +--- +## 模块简介 +引擎日志模块，可以按照 **日志级别 **和** 业务类型 **两个维度来定制日志，基于 [zen-logger](https://web.npm.alibaba-inc.com/package/zen-logger) 封装。 +> 注：日志级别可以通过 url query 动态调整，详见下方使用示例。 + +## 变量（variables） +无 +## 方法签名（functions） +### log / warn / error / info / debug +日志记录方法 + +**类型定义** +```typescript +function log(args: any[]): void +function warn(args: any[]): void +function error(args: any[]): void +function info(args: any[]): void +function debug(args: any[]): void +``` +**调用示例** +```typescript +import { logger } from '@alilc/lowcode-engine'; + +logger.log('Awesome Low-Code Engine'); +``` +## 事件（events） +无 + +## 使用示例 +```typescript +import { logger } from '@alilc/lowcode-engine'; + +// 内部实现：logger = getLogger({ level: 'warn', bizName: 'designer:pluginManager' }) + +// 若在url query中增加 `__logConf__` 可改变打印日志级别和限定业务类型日志 +// 默认：__logConf__=warn:* +logger.log('log'); // 不输出 +logger.warn('warn'); // 输出 +logger.error('error'); // 输出 + +// 比如：__logConf__=log:designer:pluginManager +logger.log('log'); // 输出 +logger.warn('warn'); // 输出 +logger.error('error'); // 输出 + +``` diff --git a/docs/docs/api/material.md b/docs/docs/api/material.md new file mode 100644 index 000000000..852287f64 --- /dev/null +++ b/docs/docs/api/material.md @@ -0,0 +1,320 @@ +--- +title: material - 物料 API +sidebar_position: 2 +--- +# 模块简介 +负责物料相关的 API，包括资产包、设计器辅助层、物料元数据和物料元数据管道函数。 + +# 变量（variables） +## componentsMap +获取组件 map 结构 + +# 方法签名（functions） +## 资产包 +### setAssets +设置「[资产包](https://www.yuque.com/lce/doc/vgcyf1)」结构 + +**类型定义** +```typescript +function setAssets(assets: AssetsJson): void; +``` + +**示例** +直接在项目中引用 npm 包 +```javascript +import { material } from '@alilc/lowcode-engine'; +import assets from '@alilc/mc-assets-/assets.json'; + +material.setAssets(assets); +``` + +通过物料中心接口动态引入资产包 +```typescript +import { ILowCodePluginContext, material, plugins } from '@alilc/lowcode-engine' + +// 动态加载 assets +plugins.register((ctx: ILowCodePluginContext) => { + return { + name: 'ext-assets', + async init() { + try { + // 将下述链接替换为您的物料即可。无论是通过 utils 从物料中心引入，还是通过其他途径如直接引入物料描述 + const res = await window.fetch('https://fusion.alicdn.com/assets/default@0.1.95/assets.json') + const assets = await res.text() + material.setAssets(assets) + } catch (err) { + console.error(err) + } + }, + } +}).catch(err => console.error(err)) +``` + +### getAssets +获取「资产包」结构 +**类型定义** +```typescript +function getAssets(): AssetsJson; +``` + + +**示例** +```typescript +import { material } from '@alilc/lowcode-engine'; + +material.getAssets(); +``` + +### loadIncrementalAssets +加载增量的「资产包」结构，该增量包会与原有的合并 + +**类型定义** +```typescript +function loadIncrementalAssets(incrementalAssets: AssetsJson): void; +``` +说明：**该增量包会与原有的合并** + +**示例** +```typescript +import { material } from '@alilc/lowcode-engine'; +import assets1 from '@alilc/mc-assets-/assets.json'; +import assets2 from '@alilc/mc-assets-/assets.json'; + +material.setAssets(assets1); +material.loadIncrementalAssets(assets2); +``` +## 设计器辅助层 +### addBuiltinComponentAction +在设计器辅助层增加一个扩展 action +**类型定义** +```typescript +function addBuiltinComponentAction(action: ComponentAction): void; + +export interface ComponentAction { + /** + * behaviorName + */ + name: string; + /** + * 菜单名称 + */ + content: string | ReactNode | ActionContentObject; + /** + * 子集 + */ + items?: ComponentAction[]; + /** + * 显示与否 + * always: 无法禁用 + */ + condition?: boolean | ((currentNode: any) => boolean) | 'always'; + /** + * 显示在工具条上 + */ + important?: boolean; +} + +export interface ActionContentObject { + /** + * 图标 + */ + icon?: IconType; + /** + * 描述 + */ + title?: TipContent; + /** + * 执行动作 + */ + action?: (currentNode: any) => void; +} + +export type IconType = string | ReactElement | ComponentType | IconConfig; +``` + + +**示例** +新增设计扩展位，并绑定事件 +```typescript +import { material } from '@alilc/lowcode-engine'; + +material.addBuiltinComponentAction({ + name: 'myIconName', + content: { + icon: () => 'x', + title: 'hover title', + action(node) { + console.log('myIconName 扩展位被点击'); + } + }, + important: true, + condition: true, +}); +``` +![image.png](https://cdn.nlark.com/yuque/0/2022/png/2622706/1645446545381-aa6f4543-5f6e-4a03-91c1-e88817823153.png#clientId=u51926daa-3723-4&crop=0&crop=0&crop=1&crop=1&from=paste&height=198&id=u34e8d0d9&margin=%5Bobject%20Object%5D&name=image.png&originHeight=198&originWidth=230&originalType=binary&ratio=1&rotation=0&showTitle=false&size=16907&status=done&style=none&taskId=u27bac39f-a38f-43bf-a0e5-157118e3aa6&title=&width=230) + +### removeBuiltinComponentAction +移除设计器辅助层的指定 action +**类型定义** +```typescript +function removeBuiltinComponentAction(name: string): void; +``` + +**示例** +```typescript +import { material } from '@alilc/lowcode-engine'; + +material.removeBuiltinComponentAction('myIconName'); +``` + + +### modifyBuiltinComponentAction +修改已有的设计器辅助层的指定 action +**类型定义** +```typescript +function modifyBuiltinComponentAction( + actionName: string, + handle: (action: ComponentAction) => void +): void; +``` +**内置设计器辅助 name** + +- remove：删除 +- hide：隐藏 +- copy：复制 +- lock：锁定，不可编辑 +- unlock：解锁，可编辑 + + + +**示例** +给原始的 remove 扩展时间添加执行前后的日志 +```typescript +import { material } from '@alilc/lowcode-engine'; + +material.modifyBuiltinComponentAction('remove', (action) => { + const originAction = action.content.action; + action.content.action = (node) => { + console.log('before reomve!'); + originAction(node); + console.log('after remove!'); + } +}); +``` +### +## 物料元数据 +### getComponentMeta +获取指定名称的物料元数据 +**类型定义** +```typescript +function getComponentMeta(componentName: string): ComponentMeta; +``` + +**示例** +```typescript +import { material } from '@alilc/lowcode-engine'; + +material.getComponentMeta('Input'); +``` + +### getComponentMetasMap +获取所有已注册的物料元数据 +**类型定义** +```typescript +function getComponentMetasMap(): new Map; +``` + +**示例** +```typescript +import { material } from '@alilc/lowcode-engine'; + +material.getComponentMetasMap(); +``` + + +## 物料元数据管道函数 +### registerMetadataTransducer +注册物料元数据管道函数，在物料信息初始化时执行。 +**类型定义** +```typescript +function registerMetadataTransducer( + transducer: MetadataTransducer, // 管道函数 + level?: number, // 优先级 + id?: string | undefined, // id +): void; +``` + +**示例** +给每一个组件的配置添加高级配置面板，其中有一个是否渲染配置项 +```typescript +import { material } from '@alilc/lowcode-engine' + +function addonCombine(metadata: TransformedComponentMetadata) { + const { componentName, configure = {} } = metadata; + const advanceGroup = []; + const combined: FieldConfig[] = []; + + advanceGroup.push({ + name: getConvertedExtraKey('condition'), + title: { type: 'i18n', 'zh-CN': '是否渲染', 'en-US': 'Condition' }, + defaultValue: true, + setter: [ + { + componentName: 'BoolSetter', + }, + { + componentName: 'VariableSetter', + }, + ], + extraProps: { + display: 'block', + }, + }); + + combined.push({ + name: '#advanced', + title: { type: 'i18n', 'zh-CN': '高级', 'en-US': 'Advanced' }, + items: advanceGroup, + }); + + return { + ...metadata, + configure: { + ...configure, + combined, + }, + }; +} + +material.registerMetadataTransducer(addonCombine, 1, 'parse-func'); +``` + +### getRegisteredMetadataTransducers +获取所有物料元数据管道函数 +**类型定义** +```typescript +function getRegisteredMetadataTransducers(): MetadataTransducer[]; +``` + +**示例** +```typescript +import { material } from '@alilc/lowcode-engine' + +material.getRegisteredMetadataTransducers('parse-func'); +``` +## +# 事件（Event） +### onChangeAssets +监听 assets 变化的事件 +**类型定义** +```typescript +function onChangeAssets(fn: () => void): void; +``` +**示例** +```typescript +import { material } from '@alilc/lowcode-engine'; + +material.onChangeAssets(() => { + console.log('asset changed'); +}); +``` diff --git a/docs/docs/api/plugins.md b/docs/docs/api/plugins.md new file mode 100644 index 000000000..8762dbacd --- /dev/null +++ b/docs/docs/api/plugins.md @@ -0,0 +1,281 @@ +--- +title: plugins - 插件 API +sidebar_position: 4 +--- +## 模块简介 +插件管理器，提供编排模块中管理插件的能力。 +## 变量（variables） +无 +## 方法签名（functions） +### register +注册插件 + +#### 类型定义 +```typescript +async function register( + pluginConfigCreator: (ctx: ILowCodePluginContext) => ILowCodePluginConfig, + options?: ILowCodeRegisterOptions, +): Promise +``` +pluginConfigCreator 是一个 ILowCodePluginConfig 生成函数，ILowCodePluginConfig 中包含了该插件的 init / destroy 等钩子函数，以及 exports 函数用于返回插件对外暴露的值。 + +另外，pluginConfigCreator 还必须挂载 pluginName 字段，全局确保唯一，否则 register 时会报错，可以选择性挂载 meta 字段，用于描述插件的元数据信息，比如兼容的引擎版本、支持的参数配置、依赖插件声明等。 +> 注：pluginConfigCreator 挂载 pluginName / meta 可以通过低代码工具链的插件脚手架生成，写如 package.json 后将会自动注入到代码中，具体见 [插件元数据工程化示例](#RO9YY) + + +#### 简单示例 +```typescript +import { plugins } from '@alilc/lowcode-engine'; + +const builtinPluginRegistry = (ctx: ILowCodePluginContext) => { + return { + async init() { + const { skeleton } = ctx; + + // 注册组件面板 + const componentsPane = skeleton.add({ + area: 'leftArea', + type: 'PanelDock', + name: 'componentsPane', + content: ComponentsPane, + contentProps: {}, + props: { + align: 'top', + icon: 'zujianku', + description: '组件库', + }, + }); + componentsPane?.disable?.(); + project.onSimulatorRendererReady(() => { + componentsPane?.enable?.(); + }) + }, + }; +} +builtinPluginRegistry.pluginName = 'builtinPluginRegistry'; +await plugins.register(builtinPluginRegistry); +``` +#### 使用 exports 示例 +```typescript +import { plugins } from '@alilc/lowcode-engine'; + +const pluginA = (ctx: ILowCodePluginContext) => { + return { + async init() {}, + exports() { return { x: 1, } }, + }; +} +pluginA.pluginName = 'pluginA'; + +const pluginB = (ctx: ILowCodePluginContext) => { + return { + async init() { + // 获取 pluginA 的导出值 + console.log(ctx.plugins.pluginA.x); // => 1 + }, + }; +} +pluginA.pluginName = 'pluginA'; +pluginB.pluginName = 'pluginB'; +pluginB.meta = { + dependencies: ['pluginA'], +} +await plugins.register(pluginA); +await plugins.register(pluginB); +``` +> 注：ctx 是在插件 creator 中获取引擎 API 的上下文，具体定义参见 [ILowCodePluginContext](#qEhTb) + +#### +#### 设置兼容引擎版本示例 +```typescript +import { plugins } from '@alilc/lowcode-engine'; + +const builtinPluginRegistry = (ctx: ILowCodePluginContext) => { + return { + async init() { + ... + }, + }; +} +builtinPluginRegistry.pluginName = 'builtinPluginRegistry'; +builtinPluginRegistry.meta = { + engines: { + lowcodeEngine: '^1.0.0', // 插件需要配合 ^1.0.0 的引擎才可运行 + }, +} +await plugins.register(builtinPluginRegistry); +``` +#### 设置插件参数版本示例 +```typescript +import { plugins } from '@alilc/lowcode-engine'; + +const builtinPluginRegistry = (ctx: ILowCodePluginContext, options: any) => { + return { + async init() { + // 1.0.4 之后的传值方式，通过 register(xxx, options) + // 取值通过 options + + // 1.0.4 之前的传值方式，通过 init(..., preference) + // 取值通过 ctx.preference.getValue() + }, + }; +} +builtinPluginRegistry.pluginName = 'builtinPluginRegistry'; +builtinPluginRegistry.meta = { + preferenceDeclaration: { + title: 'pluginA 的参数定义', + properties: [ + { + key: 'key1', + type: 'string', + description: 'this is description for key1', + }, + { + key: 'key2', + type: 'boolean', + description: 'this is description for key2', + }, + { + key: 'key3', + type: 'number', + description: 'this is description for key3', + }, + { + key: 'key4', + type: 'string', + description: 'this is description for key4', + }, + ], + }, +} + +// 从 1.0.4 开始，支持直接在 pluginCreator 的第二个参数 options 获取入参 +await plugins.register(builtinPluginRegistry, { key1: 'abc', key5: 'willNotPassToPlugin' }); + +// 1.0.4 之前，通过 preference 来传递 / 获取值 +const preference = new Map(); +preference.set('builtinPluginRegistry', { + key1: 'abc', + key5: 'willNotPassToPlugin', // 因为 key5 不在插件声明可接受的参数里 +}); + +init(document.getElementById('lce'), engineOptions, preference); + +``` + +### get +获取插件实例 + +**类型定义** +```typescript +function get(pluginName: string): ILowCodePlugin | undefined +``` +**调用示例** +```typescript +import { plugins } from '@alilc/lowcode-engine'; + +plugins.get(builtinPluginRegistry); +``` +### +### getAll +获取所有插件实例 + +**类型定义** +```typescript +function getAll(): ILowCodePlugin[] +``` +**调用示例** +```typescript +import { plugins } from '@alilc/lowcode-engine'; + +plugins.getAll(); +``` +### +### has +判断是否已经加载了指定插件 +**类型定义** +```typescript +function has(pluginName: string): boolean +``` +**调用示例** +```typescript +import { plugins } from '@alilc/lowcode-engine'; + +plugins.has('builtinPluginRegistry'); +``` +### delete +删除指定插件 +**类型定义** +```typescript +async function delete(pluginName: string): Promise +``` +**调用示例** +```typescript +import { plugins } from '@alilc/lowcode-engine'; + +plugins.delete('builtinPluginRegistry'); +``` +## +## 事件（events） +无 +## 相关模块 +### ILowCodePluginContext +**类型定义** +```typescript +export interface ILowCodePluginContext { + skeleton: Skeleton; // 参考面板 API + hotkey: Hotkey; // 参考快捷键 API + logger: Logger; // 参考日志 API + plugins: ILowCodePluginManager; // 参考插件 API + setters: Setters; // 参考设置器 API + config: EngineConfig; // 参考配置 API + material: Material; // 参考物料 API + event: Event; // 参考事件 API + project: Project; // 参考模型 API + preference: IPluginPreferenceMananger; +} +``` +### ILowCodePluginConfig +**类型定义** +```typescript +export interface ILowCodePluginConfig { + init?(): void; + destroy?(): void; + exports?(): any; +} +``` +## 插件元数据工程转化示例 +your-plugin/package.json +```json +{ + "name": "@alilc/lowcode-plugin-debug", + "lcMeta": { + "pluginName": "debug", + "meta": { + "engines": { + "lowcodeEgnine": "^1.0.0" + }, + "preferenceDeclaration": { ... } + } + } +} +``` +转换后的结构： +```json +const debug = (ctx: ILowCodePluginContext, options: any) => { + return {}; +} + +debug.pluginName = 'debug'; +debug.meta = { + engines: { + lowcodeEgnine: '^1.51.0', + }, + preferenceDeclaration: { ... } +}; +``` +### + +## 使用示例 + +更多示例参考：[https://github.com/alibaba/lowcode-demo/blob/058450edb584d92be6cb665b1f3a9646ba464ffa/src/universal/plugin.tsx#L36](https://github.com/alibaba/lowcode-demo/blob/058450edb584d92be6cb665b1f3a9646ba464ffa/src/universal/plugin.tsx#L36) diff --git a/docs/docs/api/project.md b/docs/docs/api/project.md new file mode 100644 index 000000000..269184b53 --- /dev/null +++ b/docs/docs/api/project.md @@ -0,0 +1,881 @@ +--- +title: project - 模型 API +sidebar_position: 3 +--- +# 模块简介 +引擎编排模块中包含多种模型，包括[项目模型（project）](#DADnF)、[文档模型（document-model）](#lp7xO)、[节点模型（node）](#m0cJS)、[节点孩子模型（node-children）](#W8seq)、[属性集模型（props）](#IJeRY)以及[属性模型（prop）](#w1diM)。 +他们的依赖关系如下图： +![image.png](https://cdn.nlark.com/yuque/0/2022/png/110793/1645510146964-62f26151-e624-48f6-a422-dacdcb60dbea.png#averageHue=%23fefefe&clientId=ue969b413-090d-4&crop=0&crop=0&crop=1&crop=1&errorMessage=unknown%20error&from=paste&height=676&id=ucd07aeff&margin=%5Bobject%20Object%5D&name=image.png&originHeight=1352&originWidth=1650&originalType=binary&ratio=1&rotation=0&showTitle=false&size=282048&status=error&style=none&taskId=u8ec0cad1-ed80-46f5-8b6b-b7278b4bb7d&title=&width=825) +在文档模型内部，又有一些引申模型，比如[历史操作（history）](#xvIKj)、[画布节点选中（selection）](#GtFkP)、[画布节点悬停（detecting）](#Tjt05)等。 + +整个模型系统，以项目模型为最顶层的模型，其他模型实例均需要通过 project 来获得，比如 project.currentDocument 来获取当前的文档模型，project.currentDocument.nodesMap 来获取当前文档模型里所有的节点列表。 + +# 项目模型（Project） +## 变量（variables） +### currentDocument + +获取当前的 document 实例 +### documents + +获取当前 project 下所有 documents +### simulatorHost + +获取模拟器的 host +## +## 方法签名（functions） +### openDocument + +openDocument(doc?: string | RootSchema | undefined) + +打开一个 document + +### createDocument + +createDocument(data?: RootSchema): DocumentModel | null + +创建一个 document +### +### removeDocument + +removeDocument(doc: DocumentModel) + +删除一个 document + +### getDocumentByFileName + +getDocumentByFileName(fileName: string): DocumentModel | null + +根据 fileName 获取 document + +### getDocumentById + +getDocumentById(id: string): DocumentModel | null + +根据 id 获取 document + +### exportSchema + +exportSchema() + +导出 project + +### importSchema + +importSchema(schema?: ProjectSchema) + +导入 project + +### getCurrentDocument + +getCurrentDocument(): DocumentModel | null + +获取当前的 document + +### addPropsTransducer + +addPropsTransducer(transducer: PropsTransducer, stage: TransformStage) + +增加一个属性的管道处理函数 + +**示例 1：在保存的时候删除每一个组件的 props.hidden** +```typescript +import { ILowCodePluginContext, project } from '@alilc/lowcode-engine'; +import { CompositeObject, TransformStage } from '@alilc/lowcode-types'; + +export const deleteHiddenTransducer = (ctx: ILowCodePluginContext) => { + return { + name: 'deleteHiddenTransducer', + async init() { + project.addPropsTransducer((props: CompositeObject): CompositeObject => { + delete props.hidden; + return props; + }, TransformStage.Save); + }, + }; +} + +deleteHiddenTransducer.pluginName = 'deleteHiddenTransducer'; +``` + +### onRemoveDocument +绑定删除文档事件 +```typescript +function onRemoveDocument(fn: (data: { docId: string}) => void) {} +``` +*引擎版本>=1.0.16 +### setI18n +设置多语言语料 +```typescript +function setI18n(value: object) {} +``` +*引擎版本>=1.0.17 +## 事件（events） +### onChangeDocument + +onChangeDocument(fn: (doc: DocumentModel) => void) + +当前 project 内的 document 变更事件 + +### onSimulatorHostReady + +onSimulatorHostReady(fn: (host: SimulatorHost) => void) + +当前 project 的模拟器 ready 事件 + +### onSimulatorRendererReady + +onSimulatorRendererReady(fn: () => void) + +当前 project 的渲染器 ready 事件 +# +# 文档模型（DocumentModel） +## 变量（variables） +### selection + +画布节点选中区模型实例，具体方法参见 [画布节点选中区模型](#GtFkP) + +### detecting + +画布节点 hover 区模型实例，具体方法参见 [画布节点 hover 区模型](#Tjt05) + +### history + +操作历史模型实例，具体方法参见 [操作历史模型](#xvIKj) +### canvas + +获取当前画布中的一些信息，比如拖拽时的 dropLocation + +### project + +获取当前文档模型所属的 project + +### root + +获取文档的根节点 + +### nodesMap + +获取文档下所有节点 + +### modalNodesManager + +参见 [模态节点管理](#nNRF9) + +## 方法签名（functions） +### getNodeById + +getNodeById(nodeId: string) + +根据 nodeId 返回 [Node](#m0cJS) 实例 + +### importSchema + +importSchema(schema: RootSchema) + +导入 schema +### exportSchema + +exportSchema(stage: TransformStage = TransformStage.Render) + +导出 schema + +### insertNode + +insertNode( + parent: Node, + thing: Node, + at?: number | null | undefined, + copy?: boolean | undefined, + ) + +插入节点 +### createNode + +createNode(data: any) + +创建一个节点 +### removeNode + +removeNode(idOrNode: string | Node) + +移除指定节点/节点id + +### checkNesting +检查拖拽放置的目标节点是否可以放置该拖拽对象 +*引擎版本 > 1.0.16 +```typescript +function checkNesting(dropTarget: Node, dragObject: DragNodeObject | DragNodeDataObject): boolean {} +``` +## +## 事件（events） +### onAddNode + +onAddNode(fn: (node: Node) => void) + +当前 document 新增节点事件 + +```typescript +import { project } from '@alilc/lowcode-engine'; + +project.currentDocument.onAddNode((node) => { + console.log('node', node); +}) +``` + +### onRemoveNode + +onRemoveNode(fn: (node: Node) => void) + +当前 document 删除节点事件 + +### onChangeDetecting + +onChangeDetecting(fn: (node: Node) => void) + +当前 document 的 hover 变更事件 + +### onChangeSelection + +onChangeSelection(fn: (ids: string[]) => void) + +当前 document 的选中变更事件 + +### onChangeNodeVisible + +onChangeNodeVisible(fn: (node: Node, visible: boolean) => void) + +当前 document 的节点显隐状态变更事件 + +### onChangeNodeChildren + +onChangeNodeChildren(fn: (info?: IOnChangeOptions) => void) + +当前 document 的节点 children 变更事件 + +### onChangeNodeProp +当前 document 节点属性修改事件 +```typescript +onChangeNodeProp(fn: (info: PropChangeOptions) => void) +``` + +### onImportSchema +当前 document 导入新的 schema 事件 +版本 >= 1.0.15 +```typescript +onImportSchema(fn: (schema: any) => void) +``` + +# 画布节点选中模型（Selection） +## 变量（variables） +### selected + +返回选中的节点 id + +## 方法签名（functions） +### select + +select(id: string) + +选中指定节点（覆盖方式） + +### selectAll + +selectAll(ids: string[]) + +批量选中指定节点们 + +### remove + +remove(id: string) + +**取消选中**选中的指定节点，不会删除组件 + +### clear + +clear() + +**取消选中**所有选中节点，不会删除组件 + +### has + +has(id: string) + +判断是否选中了指定节点 + +### add + +add(id: string) + +选中指定节点（增量方式） + +### getNodes + +getNodes() + +获取选中的节点实例 + +### getTopNodes +获取选区的顶层节点 +例如选中的节点为： + +- DivA + - ChildrenA +- DivB + +getNodes 返回的是 [DivA、ChildrenA、DivB]，getTopNodes 返回的是 [DivA、DivB]，其中 ChildrenA 由于是二层节点，getTopNodes 不会返回 + +*引擎版本 >= 1.0.16 + + +# 画布节点悬停模型（Detecting） +## 方法签名（functions） +### capture + +capture(id: string) + +hover 指定节点 + +### release + +release(id: string) + +hover 离开指定节点 + +### leave + +leave() + +清空 hover 态 + +### current +当前 hover 的节点 +*引擎版本 >= 1.0.16 + +# 操作历史记录模型（History） +## 方法签名（functions） +### go + +go(cursor: number) + +历史记录跳转到指定位置 + +### back + +back() + +历史记录后退 + +### forward + +forward() + +历史记录前进 +### savePoint + +savePoint() + +保存当前状态 +### isSavePoint + +isSavePoint() + +当前是否是「保存点」，即是否有状态变更但未保存 + +### getState + +getState() + +获取 state，判断当前是否为「可回退」、「可前进」的状态 + +## 事件（events） +### onChangeState + +onChangeState(func: () => any) + +监听 state 变更事件 + +### onChangeCursor + +onChangeCursor(func: () => any) + +监听历史记录游标位置变更事件 + +# 节点模型（Node） +## 变量（variables） +### id + +节点 id + +### title + +节点标题 + +### isContainer + +是否为「容器型」节点 + +### isRoot + +是否为根节点 + +### isEmpty + +是否为空节点（无 children 或者 children 为空） + +### isPage + +是否为 Page 节点 + +### isComponent + +是否为 Component 节点 + +### isModal + +是否为「模态框」节点 + +### isSlot + +是否为插槽节点 + +### isParental + +是否为父类/分支节点 + +### isLeaf +是否为叶子节点 + +### isLocked +获取当前节点的锁定状态 +*引擎版本>=1.0.16 + +### isRGLContainer +设置为磁贴布局节点，使用方式可参考：[磁贴布局在钉钉宜搭报表设计引擎中的实现](https://mp.weixin.qq.com/s/PSTut5ahAB8nlJ9kBpBaxw) +*引擎版本>=1.0.16 + +### index + +下标 + +### icon + +图标 + +### zLevel + +节点所在树的层级深度，根节点深度为 0 + +### componentName + +节点 componentName + +### componentMeta + +节点的物料元数据，参见 物料元数据 + +### document + +获取节点所属的[文档模型](#lp7xO)对象 + +### prevSibling + +获取当前节点的前一个兄弟节点 + +### nextSibling + +获取当前节点的后一个兄弟节点 + +### parent + +获取当前节点的父亲节点 + +### children + +获取当前节点的孩子节点模型 + +### slots + +节点上挂载的插槽节点们 + +### slotFor + +当前节点为插槽节点时，返回节点对应的属性实例 + +### props + +返回节点的属性集 + +### propsData + +返回节点的属性集值 + +## 方法签名（functions） +### getDOMNode + +getDOMNode() + +获取节点实例对应的 dom 节点 + +### getRect + +getRect() + +返回节点的尺寸、位置信息 + +### hasSlots + +hasSlots() + +是否有挂载插槽节点 + +### hasCondition + +hasCondition() + +是否设定了渲染条件 + +### hasLoop + +hasLoop() + +是否设定了循环数据 + +### getProp + +getProp(path: string): Prop | null + +获取指定 path 的属性模型实例 + +### getPropValue + +getPropValue(path: string) + +获取指定 path 的属性模型实例值 + +### getExtraProp + +getExtraProp(path: string): Prop | null + +获取指定 path 的属性模型实例，注：导出时，不同于普通属性，该属性并不挂载在 props 之下，而是与 props 同级 + +### getExtraPropValue + +getExtraPropValue(path: string) + +获取指定 path 的属性模型实例，注：导出时，不同于普通属性，该属性并不挂载在 props 之下，而是与 props 同级 + +### setPropValue + +setPropValue(path: string, value: CompositeValue) + +设置指定 path 的属性模型实例值 + +### setExtraPropValue + +setExtraPropValue(path: string, value: CompositeValue) + +设置指定 path 的属性模型实例值 + +### importSchema + +importSchema(data: NodeSchema) + +导入节点数据 + +### exportSchema + +exportSchema(stage: TransformStage = TransformStage.Render, options?: any) + +导出节点数据 + +### insertBefore + +insertBefore(node: Node, ref?: Node | undefined, useMutator?: boolean) + +在指定位置之前插入一个节点 + +### insertAfter + +insertAfter(node: Node, ref?: Node | undefined, useMutator?: boolean) + +在指定位置之后插入一个节点 + +### replaceChild + +replaceChild(node: Node, data: any) + +替换指定节点 + +### replaceWith + +replaceWith(schema: NodeSchema) + +将当前节点替换成指定节点描述 + +### select + +select() + +选中当前节点实例 + +### hover + +hover(flag = true) + +设置悬停态 + +### lock +设置节点锁定状态 +```typescript +function lock(flag?: boolean){} +``` +*引擎版本>=1.0.16 + +### remove + +remove() + +删除当前节点实例 + +# 节点孩子模型（NodeChildren） +## 变量（variables） +### owner + +返回当前 children 实例所属的节点实例 + +### size + +children 内的节点实例数 + +### isEmpty + +是否为空 + +## 方法签名（functions） +### delete + +delete(node: Node) + +删除指定节点 + +### insert + +insert(node: Node, at?: number | null) + +插入一个节点 + +### indexOf + +indexOf(node: Node) + +返回指定节点的下标 + +### splice + +splice(start: number, deleteCount: number, node?: Node) + +类似数组 splice 操作 + +### get + +get(index: number) + +返回指定下标的节点 + +### has + +has(node: Node) + +是否包含指定节点 + +### forEach + +forEach(fn: (node: Node, index: number) => void) + +类似数组的 forEach + +### map + +map(fn: (node: Node, index: number) => T[]) + +类似数组的 map + +### every + +every(fn: (node: Node, index: number) => boolean) + +类似数组的 every + +### some + +some(fn: (node: Node, index: number) => boolean) + +类似数组的 some + +### filter + +filter(fn: (node: Node, index: number) => boolean) + +类似数组的 filter + +### find + +find(fn: (node: Node, index: number) => boolean) + +类似数组的 find + +### reduce + +reduce(fn: (acc: any, cur: Node) => any, initialValue: any) + +类似数组的 reduce + +### importSchema + +importSchema(data?: NodeData | NodeData[]) + +导入 schema + +### exportSchema + +exportSchema(stage: TransformStage = TransformStage.Render) + +导出 schema + +### mergeChildren + +mergeChildren( + remover: (node: Node, idx: number) => boolean, + adder: (children: Node[]) => any, + sorter: (firstNode: Node, secondNode: Node) => number, + ) + +执行新增、删除、排序等操作 + +# 属性集模型（Props） +## 变量（variables） +### id + +id +### path + +返回当前 props 的路径 +### node + +返回当前属性集所属的节点实例 + +## 方法签名（functions） +### getProp + +getProp(path: string): Prop | null + +获取指定 path 的属性模型实例 + +### getPropValue + +getPropValue(path: string) + +获取指定 path 的属性模型实例值 + +### getExtraProp + +getExtraProp(path: string): Prop | null + +获取指定 path 的属性模型实例，注：导出时，不同于普通属性，该属性并不挂载在 props 之下，而是与 props 同级 +### getExtraPropValue + +getExtraPropValue(path: string) + +获取指定 path 的属性模型实例值，注：导出时，不同于普通属性，该属性并不挂载在 props 之下，而是与 props 同级 +### + +### setPropValue + +setPropValue(path: string, value: CompositeValue) + +设置指定 path 的属性模型实例值 + +### setExtraPropValue + +setExtraPropValue(path: string, value: CompositeValue) + +设置指定 path 的属性模型实例值 + +# 属性模型（Prop） +## 变量（variables） +### id + +id + +### key + +key 值 + +### path + +返回当前 prop 的路径 + +### node + +返回所属的节点实例 + +## 方法签名（functions） +### setValue + +setValue(val: CompositeValue) + +设置值 + +### getValue + +getValue() + +获取值 + +### remove +移除值 +*引擎版本>=1.0.16 + +### exportSchema + +exportSchema(stage: TransformStage = TransformStage.Render) + +导出值 + +# 模态节点管理模型（ModalNodesManager） +## 方法签名（functions） +### getModalNodes + +getModalNodes() + +获取模态节点（们） + +### getVisibleModalNode + +getVisibleModalNode() + +获取当前可见的模态节点 + +### hideModalNodes + +hideModalNodes() + +隐藏模态节点（们） + +### setVisible + +setVisible(node: Node) + +设置指定节点为可见态 + +### setInvisible + +setInvisible(node: Node) + +设置指定节点为不可见态 + +### setNodes + +setNodes() + +设置模态节点，触发内部事件 diff --git a/docs/docs/api/setters.md b/docs/docs/api/setters.md new file mode 100644 index 000000000..ac45831be --- /dev/null +++ b/docs/docs/api/setters.md @@ -0,0 +1,346 @@ +--- +title: setters - 设置器 API +sidebar_position: 6 +--- +## 模块简介 +负责注册设置器、管理设置器的 API。注册自定义设置器之后可以在物料中进行使用。 + +## 方法签名（functions） +### getSetter +获取指定 setter + +**类型定义** +```typescript +function getSetter(type: string): RegisteredSetter; +``` + +### getSettersMap +获取已注册的所有 settersMap + +**类型定义** +```typescript +function getSettersMap(): Map +``` + +### registerSetter +注册一个 setter + +**类型定义** +```typescript +function registerSetter( + typeOrMaps: string | { [key: string]: CustomView | RegisteredSetter }, + setter?: CustomView | RegisteredSetter | undefined, +): void; +``` + +## 使用示例 +### 注册官方内置 Setter 到设计器中 +```typescript +import { setters, skeleton } from '@alilc/lowcode-engine'; +import { setterMap, pluginMap } from '@alilc/lowcode-engine-ext'; + +const setterRegistry = (ctx: ILowCodePluginContext) => { + return { + name: 'ext-setters-registry', + async init() { + // 注册 setterMap + setters.registerSetter(setterMap); + // 注册插件 + // 注册事件绑定面板 + skeleton.add({ + area: 'centerArea', + type: 'Widget', + content: pluginMap.EventBindDialog, + name: 'eventBindDialog', + props: {}, + }); + + // 注册变量绑定面板 + skeleton.add({ + area: 'centerArea', + type: 'Widget', + content: pluginMap.VariableBindDialog, + name: 'variableBindDialog', + props: {}, + }); + }, + }; +} + +setterRegistry.pluginName = 'setterRegistry'; +await plugins.register(setterRegistry); +``` + +### 开发自定义 Setter +AltStringSetter 代码如下： +```typescript +import * as React from "react"; +import { Input } from "@alifd/next"; + +import "./index.scss"; +interface AltStringSetterProps { + // 当前值 + value: string; + // 默认值 + initialValue: string; + // setter唯一输出 + onChange: (val: string) => void; + // AltStringSetter 特殊配置 + placeholder: string; +} +export default class AltStringSetter extends React.PureComponent { + componentDidMount() { + const { onChange, value, defaultValue } = this.props; + if (value == undefined && defaultValue) { + onChange(defaultValue); + } + } + + // 声明 Setter 的 title + static displayName = 'AltStringSetter'; + + render() { + const { onChange, value, placeholder } = this.props; + return ( + onChange(val)} + > + ); + } +} +``` +开发完毕之后，注册 AltStringSetter 到设计器中： +```typescript +import AltStringSetter from './AltStringSetter'; +const registerSetter = window.AliLowCodeEngine.setters.registerSetter; +registerSetter('AltStringSetter', AltStringSetter); +``` +注册之后，我们就可以在物料中使用了，其中核心配置如下： +```typescript +{ + "props": { + "isExtends": true, + "override": [ + { + "name": "type", + "setter": "AltStringSetter" + } + ] + } +} +``` +完整配置如下： +```typescript +{ + "componentName": "Message", + "title": "Message", + "props": [ + { + "name": "title", + "propType": "string", + "description": "标题", + "defaultValue": "标题" + }, + { + "name": "type", + "propType": { + "type": "oneOf", + "value": [ + "success", + "warning", + "error", + "notice", + "help", + "loading" + ] + }, + "description": "反馈类型", + "defaultValue": "success" + } + ], + "configure": { + "props": { + "isExtends": true, + "override": [ + { + "name": "type", + "setter": "AltStringSetter" + } + ] + } + } +} +``` +## 模块简介 +负责注册设置器、管理设置器的 API。注册自定义设置器之后可以在物料中进行使用。 + +## 方法签名（functions） +### getSetter +获取指定 setter + +**类型定义** +```typescript +function getSetter(type: string): RegisteredSetter; +``` + +### getSettersMap +获取已注册的所有 settersMap + +**类型定义** +```typescript +function getSettersMap(): Map +``` + +### registerSetter +注册一个 setter + +**类型定义** +```typescript +function registerSetter( + typeOrMaps: string | { [key: string]: CustomView | RegisteredSetter }, + setter?: CustomView | RegisteredSetter | undefined, +): void; +``` + +## 使用示例 +### 注册官方内置 Setter 到设计器中 +```typescript +import { setters, skeleton } from '@alilc/lowcode-engine'; +import { setterMap, pluginMap } from '@alilc/lowcode-engine-ext'; + +const setterRegistry = (ctx: ILowCodePluginContext) => { + return { + name: 'ext-setters-registry', + async init() { + // 注册 setterMap + setters.registerSetter(setterMap); + // 注册插件 + // 注册事件绑定面板 + skeleton.add({ + area: 'centerArea', + type: 'Widget', + content: pluginMap.EventBindDialog, + name: 'eventBindDialog', + props: {}, + }); + + // 注册变量绑定面板 + skeleton.add({ + area: 'centerArea', + type: 'Widget', + content: pluginMap.VariableBindDialog, + name: 'variableBindDialog', + props: {}, + }); + }, + }; +} + +setterRegistry.pluginName = 'setterRegistry'; +await plugins.register(setterRegistry); +``` + +### 开发自定义 Setter +AltStringSetter 代码如下： +```typescript +import * as React from "react"; +import { Input } from "@alifd/next"; + +import "./index.scss"; +interface AltStringSetterProps { + // 当前值 + value: string; + // 默认值 + initialValue: string; + // setter唯一输出 + onChange: (val: string) => void; + // AltStringSetter 特殊配置 + placeholder: string; +} +export default class AltStringSetter extends React.PureComponent { + componentDidMount() { + const { onChange, value, defaultValue } = this.props; + if (value == undefined && defaultValue) { + onChange(defaultValue); + } + } + + // 声明 Setter 的 title + static displayName = 'AltStringSetter'; + + render() { + const { onChange, value, placeholder } = this.props; + return ( + onChange(val)} + > + ); + } +} +``` +开发完毕之后，注册 AltStringSetter 到设计器中： +```typescript +import AltStringSetter from './AltStringSetter'; +const registerSetter = window.AliLowCodeEngine.setters.registerSetter; +registerSetter('AltStringSetter', AltStringSetter); +``` +注册之后，我们就可以在物料中使用了，其中核心配置如下： +```typescript +{ + "props": { + "isExtends": true, + "override": [ + { + "name": "type", + "setter": "AltStringSetter" + } + ] + } +} +``` +完整配置如下： +```typescript +{ + "componentName": "Message", + "title": "Message", + "props": [ + { + "name": "title", + "propType": "string", + "description": "标题", + "defaultValue": "标题" + }, + { + "name": "type", + "propType": { + "type": "oneOf", + "value": [ + "success", + "warning", + "error", + "notice", + "help", + "loading" + ] + }, + "description": "反馈类型", + "defaultValue": "success" + } + ], + "configure": { + "props": { + "isExtends": true, + "override": [ + { + "name": "type", + "setter": "AltStringSetter" + } + ] + } + } +} +``` diff --git a/docs/docs/api/simulatorHost.md b/docs/docs/api/simulatorHost.md new file mode 100644 index 000000000..fc0009d3a --- /dev/null +++ b/docs/docs/api/simulatorHost.md @@ -0,0 +1,31 @@ +--- +title: simulatorHost - 模拟器 API +sidebar_position: 3 +--- +# 模块简介 +负责模拟器相关的 API，包括画布尺寸、语言等。 + +# 方法（functions） +## set +设置若干用于画布渲染的变量，比如画布大小、locale 等。 + +以设置画布大小为例： +目前支持 3 种定制方式： +```typescript + +// 直接使用内置设备类型 +project.simulatorHost.set('device', 'mobile' / 'iphonex' / 'iphone6' / 'default'); +// 定制 canvas 的样式类 +project.simulatorHost.set('deviceClassName', 'my-canvas-class'); +// 最灵活的方式，直接设置 canvas / viewport 的样式（canvas 是外框，viewport 是内框，可以在 canvas 设置手机 / 平板背景图） +project.simulatorHost.set('deviceStyle', { canvas: { width: '300px', backgroundColor: 'red' }, viewport: { width: '280px' } }); +``` + +## get +获取模拟器中设置的变量，比如画布大小、locale 等。 +```typescript +project.simulatorHost.get('device'); +``` + +## rerender +刷新渲染画布 diff --git a/docs/docs/api/skeleton.md b/docs/docs/api/skeleton.md new file mode 100644 index 000000000..80e3220f6 --- /dev/null +++ b/docs/docs/api/skeleton.md @@ -0,0 +1,278 @@ +--- +title: skeleton - 面板 API +sidebar_position: 1 +--- +## 模块简介 +面板 API 提供了面板扩展和管理的能力，如下图蓝色内容都是扩展出来的。
![image.png](https://cdn.nlark.com/yuque/0/2022/png/110793/1645442085447-d1822e7f-9e5a-4e06-a770-04b1023d5daf.png#clientId=u9aca70b6-1a98-4&crop=0&crop=0&crop=1&crop=1&from=paste&height=498&id=u2dd3deb2&margin=%5Bobject%20Object%5D&name=image.png&originHeight=996&originWidth=1780&originalType=binary&ratio=1&rotation=0&showTitle=false&size=1549904&status=done&style=none&taskId=u28659b69-981c-416e-bed6-b2f06b8e6fc&title=&width=890)
页面上可以扩展的区域共 5 个，具体如下：
![image.png](https://cdn.nlark.com/yuque/0/2022/png/110793/1645431386085-2710d33d-0652-450a-a993-c804368da1ce.png#clientId=u1724eb73-4c0c-4&crop=0&crop=0&crop=1&crop=1&from=paste&height=487&id=ud138f866&margin=%5Bobject%20Object%5D&name=image.png&originHeight=974&originWidth=1892&originalType=binary&ratio=1&rotation=0&showTitle=false&size=228235&status=done&style=none&taskId=u265d50a5-3700-406e-84b2-0158ebadaae&title=&width=946) +### 基本概念 +#### 扩展区域位置(area) +##### topArea +展示在设计器的顶部区域，常见的相关区域的插件主要是：
1）注册设计器 Logo；
2）设计器操作回退和撤销按钮；
3）全局操作按钮，例如：保存、预览等； +##### leftArea +左侧区域的展示形式大多数是 Icon 和对应的面板，通过点击 Icon 可以展示对应的面板并隐藏其他的面板。
该区域相关插件的主要有：
1）大纲树展示，展示该设计器设计页面的大纲。
2）组件库，展示注册到设计器中的组件，点击之后，可以从组件库面板中拖拽到设计器的画布中。
3）数据源面板
4）JS 等代码面板。
可以发现，这个区域的面板大多数操作时是不需要同时并存的，且交互比较复杂的，需要一个更整块的区域来进行操作。 +##### centerArea +画布区域，由于画布大多数是展示作用，所以一般扩展的种类比较少。常见的扩展有：
1）画布大小修改
2）物料选中扩展区域修改 +##### rightArea +右侧区域，常用于组件的配置。常见的扩展有：统一处理组件的配置项，例如统一删除某一个配置项，统一添加某一个配置项的。 +##### toolbar +跟 topArea 类似，按需放置面板插件~ +#### 展示类型(type) +展示类型用于区分插件在设计器内可操作的几种不同界面类型。主要的几种类型为PanelDock、Widget、Dock，另有Panel类型目前不推荐使用。 +##### PanelDock +PanelDock 是以面板的形式展示在设计器的左侧区域的。其中主要有两个部分组成，一个是图标，一个是面板。当点击图标时可以控制面板的显示和隐藏。
下图是组件库插件的展示效果。
![Feb-08-2022 19-44-15.gif](https://cdn.nlark.com/yuque/0/2022/gif/242652/1644320663827-ee9c54a1-f684-40e2-8a6b-875103d04b31.gif#clientId=u221f0bd4-c19e-4&crop=0&crop=0&crop=1&crop=1&from=paste&height=555&id=u5292d9cc&margin=%5Bobject%20Object%5D&name=Feb-08-2022%2019-44-15.gif&originHeight=790&originWidth=1536&originalType=binary&ratio=1&rotation=0&showTitle=false&size=1381641&status=done&style=stroke&taskId=ub28a13a4-3d80-4a02-bcaa-cc9d6127243&title=&width=1080)
其中右上角可以进行固定，可以对弹出的宽度做设定
接入可以参考代码 +```javascript +import { skeleton } from "@alilc/lowcode-engine"; + +skeleton.add({ + area: "leftArea", // 插件区域 + type: "PanelDock", // 插件类型，弹出面板 + name: "sourceEditor", + content: SourceEditor, // 插件组件实例 + props: { + align: "left", + icon: "wenjian", + description: "JS面板", + }, + panelProps: { + floatable: true, // 是否可浮动 + height: 300, + hideTitleBar: false, + maxHeight: 800, + maxWidth: 1200, + title: "JS面板", + width: 600, + }, +}); +``` +##### Widget +Widget 形式是直接渲染在当前编辑器的对应位置上。如 demo 中在设计器顶部的所有组件都是这种展现形式。
![image.png](https://cdn.nlark.com/yuque/0/2022/png/242652/1644320068765-47efc836-30c2-452f-8104-b98b1ea3533d.png#clientId=u221f0bd4-c19e-4&crop=0&crop=0&crop=1&crop=1&from=paste&height=51&id=P60UE&margin=%5Bobject%20Object%5D&name=image.png&originHeight=94&originWidth=1988&originalType=binary&ratio=1&rotation=0&showTitle=false&size=58410&status=done&style=stroke&taskId=u4eadd643-2e63-4be7-8736-b27b9c82b81&title=&width=1080)
接入可以参考代码： +```javascript +import {skeleton} from "@alilc/lowcode-engine"; +// 注册 logo 面板 +skeleton.add({ + area: "topArea", + type: "Widget", + name: "logo", + content: Logo, // Widget 组件实例 + contentProps: { // Widget 插件props + logo: + "https://img.alicdn.com/tfs/TB1_SocGkT2gK0jSZFkXXcIQFXa-66-66.png", + href: "/", + }, + props: { + align: "left", + width: 100, + }, +}); +``` +##### Dock +一个图标的表现形式，可以用于语言切换、跳转到外部链接、打开一个 widget 等场景 +```javascript +import { skeleton } from "@alilc/lowcode-engine"; + +skeleton.add({ + area: "leftArea", + type: "Dock", + name: "opener", + content: Opener, // Widget 组件实例 + contentProps: { // Widget 插件props + xxx: "1", + }, + props: { + align: "bottom", + }, + onClick: function() { + // 打开外部链接 + window.open('https://lowcode-engine.cn'); + // 显示 widget + skeleton.showWidget('xxx'); + } +}); +``` +####
+## 变量（variables） +无 +## 方法签名（functions） +### 1. add +```tsx +add(config: IWidgetBaseConfig & { + area?: string; +}, extraConfig?: object): IWidget | Panel; +``` + +往指定扩展区加入一块面板 + +IWidgetBaseConfig 定义如下： + +| 属性名 | 含义 | 备注 | +| --- | --- | --- | +| name | 面板名称 | | +| area | 扩展区位置，可选值：'topArea' | 'leftArea' | 'rightArea' | 'toolbar' | 'bottomArea' | 'mainArea' | | +| type | 面板类型，可选值：'Widget' | 'PanelDock' | 'Panel' | 详见前文中对**展示类型**的描述 | +| content | 面板的实现类/节点，类型是 ReactClass | ReactElement | | +| props | 面板属性 | align: 'top' | 'bottom' | 'left' | 'center' | 'right'; // 指定面板 icon 位置区域
icon: string | ReactElement;  // icon 为字符串时，请确定当前 fusion 主题包中包含该 icon
description: string;
condition: Function; // 指定当前面板的显影状态 | +| contentProps | 面板的实现类/节点的参数 | | +| panelProps | 假如 type: 'Panel' | 'PanelDock' 时有效，传给 Panel 类的参数 | keepVisibleWhileDragging: boolean; // 当有元素在当前 panel 拖拽时，是否保持 panel 为展开状态，默认值：false
area: 'leftFloatArea' | 'leftFixedArea' // 指定 panel 位于浮动面板还是钉住面板 | +| index | 面板的位置，不传默认按插件注册顺序 | | + + + + +### 2. remove + +remove(config: IWidgetBaseConfig) + +移除一个面板实例 + +### 3. showPanel + +showPanel(name: string) + +展示指定 Panel 实例 + +### 4. hidePanel + +hidePanel(name: string) + +### 5. showWidget + +showWidget(name: string) + +展示指定 Widget 实例 + +### 6. hideWidget + +hideWidget(name: string) + +隐藏指定 widget 实例。 + +### 7. enableWidget + +enableWidget(name: string) + +将 widget 启用。
注：该函数将会触发全局事件 'skeleton.widget.enable' + +### 8. disableWidget + +disableWidget(name: string) + +将 widget 禁用掉，禁用后，所有鼠标事件都会被禁止掉。
适用场景：在该面板还在进行初始化构造时，可以先禁止掉，防止用户点击报错，待初始化完成，重新启用。 + +## 事件（events） +### 1. onShowPanel + +onShowPanel(listener: (...args: unknown[]) => void) + +监听 Panel 实例显示事件 + +### 2. onHidePanel +
onHidePanel(listener: (...args: unknown[]) => void) + +监听 Panel 实例隐藏事件 + +### 3. onShowWidget + +onShowWidget(listener: (...args: unknown[]) => void) + +监听 Widget 实例显示事件 + +### 4. onHideWidget +
onHideWidget(listener: (...args: unknown[]) => void) + +监听 Widget 实例隐藏事件 +## 使用示例 +```typescript +import { skeleton } from '@alilc/lowcode-engine'; + +skeleton.add({ + name: 'logo', + area: 'topArea', + type: 'Widget', + contentProps: {}, + content: LogoContent, +}); + +skeleton.add({ + name: 'sourceEditor', + type: 'PanelDock', + area: 'leftArea', + props: { + align: 'top', + icon: 'wenjian', + description: 'JS面板', + }, + panelProps: { + floatable: true, + height: 300, + help: undefined, + hideTitleBar: false, + maxHeight: 800, + maxWidth: 1200, + title: 'JS面板', + width: 600, + }, + content: SourceEditor, +}); + +// 显隐 panel +skeleton.showPanel('sourceEditor'); +skeleton.hidePanel('sourceEditor'); + + +// 创建一个浮动的 widget +skeleton.add({ + name: 'floatingWidget', + type: 'Widget', + area: 'mainArea', + props: {}, + content: React.createElement('div', {}, 'haha'), + contentProps: { + style: { + position: 'fixed', + top: '200px', + bottom: 0, + width: 'calc(100% - 46px)', + 'background-color': 'lightblue' + } + } +}); + +// 显隐 widget +skeleton.showWidget('floatingWidget'); +skeleton.hideWidget('floatingWidget'); + +// 控制 widget 的可点击态 +skeleton.enableWidget('sourceEditor'); +skeleton.disableWidget('sourceEditor'); +``` +### bottomArea 示例 +```typescript +import { skeleton } from '@alilc/lowcode-engine'; + +skeleton.add({ + name: 'bottomAreaPanelName', + area: 'bottomArea', + type: 'Panel', + content: () => 'demoText', +}); + + +skeleton.showPanel('bottomAreaPanelName'); +``` +### widget 示例 +```typescript +// 注册 logo 面板 +skeleton.add({ + area: 'topArea', + type: 'Widget', + name: 'logo', + content: Logo, + contentProps: { + logo: 'https://img.alicdn.com/imgextra/i4/O1CN013w2bmQ25WAIha4Hx9_!!6000000007533-55-tps-137-26.svg', + href: 'https://lowcode-engine.cn', + }, + props: { + align: 'left', + }, +}); +``` diff --git a/docs/docs/article/index.md b/docs/docs/article/index.md new file mode 100644 index 000000000..d0a65524c --- /dev/null +++ b/docs/docs/article/index.md @@ -0,0 +1,38 @@ +--- +title: 低代码引擎相关文章资料 +--- + +## 官方文章 + +- [低代码引擎半岁啦，来跟大家唠唠嗑...](https://segmentfault.com/a/1190000042884409) +- [低代码技术在研发团队的应用模式探讨](https://mp.weixin.qq.com/s/Ynk_wjJbmNw7fEG6UtGZbQ) +- [关于 LowCode&ProCode 混合研发的思考](https://mp.weixin.qq.com/s/TY3VXjkSmsQoT47xma3wig) +- [低代码渲染那些事](https://mp.weixin.qq.com/s/yqYey76qLGYPfDtpGkVFfA) +- [阿里低代码引擎和生态建设实战及思考](https://mp.weixin.qq.com/s/MI6MrUKKydtnSdO4xq6jwA) +- [磁贴布局在钉钉宜搭报表设计引擎中的实现](https://mp.weixin.qq.com/s/PSTut5ahAB8nlJ9kBpBaxw) +- [2B 领域下的低代码探索之路](https://mp.weixin.qq.com/s/HAxrMHLT43dPH488RiEIdw) +- [阿里低代码引擎 LowCodeEngine 正式开源！](https://mp.weixin.qq.com/s/T66LghtWLz2Oh048XqaniA) + +## Portal设计项目实战 +#### 直播回放 +[https://www.bilibili.com/video/BV1AS4y1K7DP/](https://www.bilibili.com/video/BV1AS4y1K7DP/) + +#### 示例项目 +- 前端: [https://github.com/mark-ck/lowcode-portal](https://github.com/mark-ck/lowcode-portal) +- 后端: [https://github.com/mark-ck/document-solution-site](https://github.com/mark-ck/document-solution-site) +- 组件库：[https://github.com/mark-ck/portal-components](https://github.com/mark-ck/portal-components) + +**注意** +1. 前端项目要把代码里请求接口的域名改成本地或者自己的域名； +2. 后端项目要把 config.default.js 里的 yuque 和 oss 配置补全； + +#### 视频链接 +- [阿里低代码引擎项目实战(1)-引擎 demo 部署到 faas 服务](https://www.bilibili.com/video/BV1B44y1P7GM/) +- [【有翻车】阿里低代码引擎项目实战(2)-保存页面到远端存储](https://www.bilibili.com/video/BV1AS4y1K7DP/) +- [阿里巴巴低代码引擎项目实战(3)-自定义组件接入](https://www.bilibili.com/video/BV1dZ4y1m76S/) +- [阿里低代码引擎项目实战(4)-自定义插件-页面管理](https://www.bilibili.com/video/BV17a411i73f/) +- [阿里低代码引擎项目实战(4)-用户登录](https://www.bilibili.com/video/BV1Wu411e7EQ/) +- [【有翻车】阿里低代码引擎项目实战(5)-表单回显](https://www.bilibili.com/video/BV1UY4y1v7D7/) +- [阿里低代码引擎项目实战(6)-自定义插件-页面管理-后端](https://www.bilibili.com/video/BV1uZ4y1U7Ly/) +- [阿里低代码引擎项目实战(6)-自定义插件-页面管理-前端](https://www.bilibili.com/video/BV1Yq4y1a74P/) +- [阿里低代码引擎项目实战(7)-自定义插件-页面管理(完结)](https://www.bilibili.com/video/BV13Y4y1e7EV/) \ No newline at end of file diff --git a/docs/docs/demoUsage/advanced/_category_.json b/docs/docs/demoUsage/advanced/_category_.json new file mode 100644 index 000000000..b83dbf807 --- /dev/null +++ b/docs/docs/demoUsage/advanced/_category_.json @@ -0,0 +1,6 @@ +{ + "label": "进阶功能", + "position": 3, + "collapsed": false, + "collapsible": false +} diff --git a/docs/docs/demoUsage/advanced/hotkey.md b/docs/docs/demoUsage/advanced/hotkey.md new file mode 100644 index 000000000..a35183f29 --- /dev/null +++ b/docs/docs/demoUsage/advanced/hotkey.md @@ -0,0 +1,24 @@ +--- +title: 8. 编辑器快捷键 +sidebar_position: 0 +--- +- 任意时机： + - `⌘` `S` 保存 + - `⌘` `P` 预览 + - `⌘` `D` 查看 Diff + - `⌘` `Z` 撤销 + - `⇧` `⌘` `Z` 重做 +- 选择任意组件后： + - `Backspace` 删除组件 + - `⌘` `C` 复制组件 + - `⌘` `V` 粘贴组件 + - `⌘` `X` 剪切组件 + - `⌥` `↑` 向外层移动组件 + - `⌥` `↓` 向内层移动组件 + - `⌥` `←` 同级向上移动组件 + - `⌥` `→` 同级向下移动组件 + - `↑` 向上选择组件 + - `↓` 向下选择组件 + - `←` 向左选择组件 + - `→` 向右选择组件 + - `Escape` 取消选择组件 diff --git a/docs/docs/demoUsage/appendix/_category_.json b/docs/docs/demoUsage/appendix/_category_.json new file mode 100644 index 000000000..2021a2aad --- /dev/null +++ b/docs/docs/demoUsage/appendix/_category_.json @@ -0,0 +1,6 @@ +{ + "label": "常见问题", + "position": 4, + "collapsed": false, + "collapsible": false +} diff --git a/docs/docs/demoUsage/appendix/loop.md b/docs/docs/demoUsage/appendix/loop.md new file mode 100644 index 000000000..0afb5c931 --- /dev/null +++ b/docs/docs/demoUsage/appendix/loop.md @@ -0,0 +1,17 @@ +--- +title: 如何使用循环值 +sidebar_position: 0 +--- +1.设置循环数据 +![image.png](https://cdn.nlark.com/yuque/0/2022/png/2622706/1655975447215-026bd3ae-ae2a-4f90-805e-df0d5c4bb7d2.png#clientId=ubd100ffc-952a-4&crop=0&crop=0&crop=1&crop=1&from=paste&height=950&id=u6413eee5&margin=%5Bobject%20Object%5D&name=image.png&originHeight=1900&originWidth=3840&originalType=binary&ratio=1&rotation=0&showTitle=false&size=339030&status=done&style=none&taskId=ued46d732-83a2-441f-a80f-23061587689&title=&width=1920) + +2.给需要的变量绑定 this.item +![image.png](https://cdn.nlark.com/yuque/0/2022/png/2622706/1655975499246-f9d14ef4-6736-46a5-8b24-8eedd4477617.png#clientId=ubd100ffc-952a-4&crop=0&crop=0&crop=1&crop=1&from=paste&height=946&id=u0b50f02a&margin=%5Bobject%20Object%5D&name=image.png&originHeight=1892&originWidth=3840&originalType=binary&ratio=1&rotation=0&showTitle=false&size=451804&status=done&style=none&taskId=uf4916102-2e3d-4277-ac81-604c6761615&title=&width=1920) + +绑定之后的效果如下： +![image.png](https://cdn.nlark.com/yuque/0/2022/png/2622706/1655975540038-ccf3aabc-3f7c-4e33-a701-a9b005b1cf25.png#clientId=uc887596b-8aed-4&crop=0&crop=0&crop=1&crop=1&from=paste&height=942&id=u32901b3a&margin=%5Bobject%20Object%5D&name=image.png&originHeight=1884&originWidth=3840&originalType=binary&ratio=1&rotation=0&showTitle=false&size=333998&status=done&style=none&taskId=u2853d459-4432-4d0a-ba12-494e79e892a&title=&width=1920) + +其中 this.item 的 item 是可以配置的。配置不同的 key 可以方便在多层循环中使用不同层级的循环 item 值。 +![image.png](https://cdn.nlark.com/yuque/0/2022/png/2622706/1655975569197-33d90389-7394-4e65-bc6a-582b7ceb9fee.png#clientId=uc887596b-8aed-4&crop=0&crop=0&crop=1&crop=1&from=paste&height=948&id=u6e6741d2&margin=%5Bobject%20Object%5D&name=image.png&originHeight=1896&originWidth=3840&originalType=binary&ratio=1&rotation=0&showTitle=false&size=311961&status=done&style=none&taskId=u14bbcfbb-e7cf-4307-a58d-3cb58afe8f7&title=&width=1920) + +this.index 是当前循环的索引值。 diff --git a/docs/docs/demoUsage/intro.md b/docs/docs/demoUsage/intro.md new file mode 100644 index 000000000..5154f0ea7 --- /dev/null +++ b/docs/docs/demoUsage/intro.md @@ -0,0 +1,80 @@ +--- +title: 1. 试用低代码引擎 Demo +sidebar_position: 0 +--- +低代码编辑器中的区块主要包含这些功能点： +![image.png](https://cdn.nlark.com/yuque/0/2022/png/242652/1644562161350-50ae7ccd-2e6f-4f50-af56-30e5cc5624dc.png#clientId=u99b5ef7a-7ebb-4&crop=0&crop=0&crop=1&crop=1&from=paste&height=892&id=udd8e7731&margin=%5Bobject%20Object%5D&name=image.png&originHeight=1784&originWidth=3384&originalType=binary&ratio=1&rotation=0&showTitle=false&size=509888&status=done&style=none&taskId=u1621cea1-8e9d-48d0-9273-bf852ef8e82&title=&width=1692) + +## 分区块功能介绍 +### 左侧：面板与操作区 +#### 物料面板 +可以查找组件，并在此拖动组件到编辑器画布中 +![Dec-17-2021 19-12-46.gif](https://cdn.nlark.com/yuque/0/2022/gif/242652/1644562213143-49b9aff8-b538-43f4-a66d-53fac98ce7ae.gif#clientId=u99b5ef7a-7ebb-4&crop=0&crop=0&crop=1&crop=1&from=paste&height=377&id=u3a98c25c&margin=%5Bobject%20Object%5D&name=Dec-17-2021%2019-12-46.gif&originHeight=754&originWidth=1468&originalType=binary&ratio=1&rotation=0&showTitle=false&status=done&style=none&taskId=u265abeb3-a0b1-4cdf-9291-c5fa865d06c&title=&width=734) + +#### 大纲面板 +可以调整页面内的组件树结构： +![Dec-17-2021 19-14-34.gif](https://cdn.nlark.com/yuque/0/2022/gif/242652/1644562213701-39f3e2c3-f52c-4be4-bb56-90842daa58ab.gif#clientId=u99b5ef7a-7ebb-4&crop=0&crop=0&crop=1&crop=1&from=paste&height=377&id=u1d18d088&margin=%5Bobject%20Object%5D&name=Dec-17-2021%2019-14-34.gif&originHeight=754&originWidth=1468&originalType=binary&ratio=1&rotation=0&showTitle=false&status=done&style=none&taskId=u2d6ebf59-3cd5-4e80-8599-a4d594a2cbf&title=&width=734) +可以在这里打开或者关闭模态浮层的展现： +![Dec-17-2021 19-19-18.gif](https://cdn.nlark.com/yuque/0/2022/gif/242652/1644562213674-44d91956-ac82-4909-98b5-e0bd4fcbe12d.gif#clientId=u99b5ef7a-7ebb-4&crop=0&crop=0&crop=1&crop=1&from=paste&height=377&id=u7d3beb31&margin=%5Bobject%20Object%5D&name=Dec-17-2021%2019-19-18.gif&originHeight=754&originWidth=1468&originalType=binary&ratio=1&rotation=0&showTitle=false&status=done&style=none&taskId=u6adfe95e-0c27-4c03-8e3c-ca62cb37387&title=&width=734) + + +#### 源码面板 +可以编辑页面级别的 JavaScript 代码和 CSS 配置 +![Feb-11-2022 14-51-59.gif](https://cdn.nlark.com/yuque/0/2022/gif/242652/1644562356337-9e7f7490-396c-4520-b780-4a43a29050ef.gif#clientId=u99b5ef7a-7ebb-4&crop=0&crop=0&crop=1&crop=1&from=ui&id=u02b5cb05&margin=%5Bobject%20Object%5D&name=Feb-11-2022%2014-51-59.gif&originHeight=614&originWidth=1532&originalType=binary&ratio=1&rotation=0&showTitle=false&size=2080513&status=done&style=none&taskId=u2f95447f-b7a6-453d-8a8c-7d1649581d9&title=) + +#### Schema 编辑 +【开发者专属】可以编辑页面的底层 Schema 数据。 +![image.png](https://cdn.nlark.com/yuque/0/2022/png/242652/1644562411102-a8596fce-fd77-4f20-bd3c-b52e2a0beb52.png#clientId=u99b5ef7a-7ebb-4&crop=0&crop=0&crop=1&crop=1&from=paste&height=824&id=u3488f050&margin=%5Bobject%20Object%5D&name=image.png&originHeight=1648&originWidth=3070&originalType=binary&ratio=1&rotation=0&showTitle=false&size=1082743&status=done&style=none&taskId=u529bf58c-2203-484f-bf9f-19c2a3fe870&title=&width=1535) +搭配顶部操作区的“保存到本地”和“重置页面”功能，可以实验各种 schema 对低代码页面的改变。 + +它们操作的数据关系是： + +- 页面中的 Schema 数据：保存在低代码引擎中的 Schema，点击 Schema 面板中的“保存 Schema” 时将修改引擎中的值，此外低代码引擎中的所有操作都可能修改到 Schema +- localStorage 数据：由“保存到本地”保存到 localStorage 中，页面初始化时将读取，预览页面时也会读取 +- 默认 Schema：保存在 Demo 项目中的默认 Schema（`public/schema.json`），初始化页面时如果不存在 localStorage 数据即会读取，点击“重置页面”时，也会读取 + +#### 中英文切换 +可以切换编辑器的语言；注：需要组件配置配合。 + +![image.png](https://cdn.nlark.com/yuque/0/2022/png/242652/1644562219182-e4233163-b731-4f09-a442-9d5c0e71e7e8.png#clientId=u99b5ef7a-7ebb-4&crop=0&crop=0&crop=1&crop=1&from=paste&height=756&id=ua3adfd78&margin=%5Bobject%20Object%5D&name=image.png&originHeight=1512&originWidth=3018&originalType=binary&ratio=1&rotation=0&showTitle=false&size=384093&status=done&style=none&taskId=uf546934b-ae91-4e3e-9e21-2447de70ed1&title=&width=1509) +![image.png](https://cdn.nlark.com/yuque/0/2022/png/242652/1644562219666-1baf7da2-6d70-45fa-8805-b6cc9ac99f3f.png#clientId=u99b5ef7a-7ebb-4&crop=0&crop=0&crop=1&crop=1&from=paste&height=755&id=u34aad08e&margin=%5Bobject%20Object%5D&name=image.png&originHeight=1510&originWidth=3016&originalType=binary&ratio=1&rotation=0&showTitle=false&size=380190&status=done&style=none&taskId=ud264115a-ae01-4b65-9ccc-4e6efa37b62&title=&width=1508) +## 中部：可视化页面编辑画布区域 + +点击组件在右侧面板中能够显示出对应组件的属性配置选项 +![Dec-17-2021 19-28-28.gif](https://cdn.nlark.com/yuque/0/2022/gif/242652/1644562216925-c4bd5f10-2469-452c-8c2d-fe92ba6d03a7.gif#clientId=u99b5ef7a-7ebb-4&crop=0&crop=0&crop=1&crop=1&from=paste&height=377&id=uff491710&margin=%5Bobject%20Object%5D&name=Dec-17-2021%2019-28-28.gif&originHeight=754&originWidth=1468&originalType=binary&ratio=1&rotation=0&showTitle=false&status=done&style=none&taskId=u2f775208-8b07-4968-9dd4-420c6e4d3c1&title=&width=734) + +拖拽修改组件的排列顺序 +![Dec-17-2021 19-29-40.gif](https://cdn.nlark.com/yuque/0/2022/gif/242652/1644562219867-61a41b16-4513-4827-80bf-f7e4832bcf3a.gif#clientId=u99b5ef7a-7ebb-4&crop=0&crop=0&crop=1&crop=1&from=paste&height=377&id=ueda50ec8&margin=%5Bobject%20Object%5D&name=Dec-17-2021%2019-29-40.gif&originHeight=754&originWidth=1468&originalType=binary&ratio=1&rotation=0&showTitle=false&status=done&style=none&taskId=ue0ec6bea-81f1-4d04-bf82-acde7c9983a&title=&width=734) + +将组件拖拽到容器类型的组件中，注意拖拽时会在右侧提示当前的组件树。 +![Dec-17-2021 19-31-30.gif](https://cdn.nlark.com/yuque/0/2022/gif/242652/1644562220001-4afae72e-f9fd-4564-a904-c87f61ba79b5.gif#clientId=u99b5ef7a-7ebb-4&crop=0&crop=0&crop=1&crop=1&from=paste&height=377&id=ucc719a0e&margin=%5Bobject%20Object%5D&name=Dec-17-2021%2019-31-30.gif&originHeight=754&originWidth=1468&originalType=binary&ratio=1&rotation=0&showTitle=false&status=done&style=none&taskId=u2c46a827-8702-471c-a8c1-eb4f069d108&title=&width=734) + +## 右侧：组件级别配置 + +### 选中的组件 +从页面开始一直到当前选中的组件位置，点击对应的名称可以切换到对应的组件上。 +![Dec-17-2021 19-35-25.gif](https://cdn.nlark.com/yuque/0/2022/gif/242652/1644562220818-c6532319-51df-4698-a3a4-80f3ab70b209.gif#clientId=u99b5ef7a-7ebb-4&crop=0&crop=0&crop=1&crop=1&from=paste&height=377&id=u648c740b&margin=%5Bobject%20Object%5D&name=Dec-17-2021%2019-35-25.gif&originHeight=754&originWidth=1468&originalType=binary&ratio=1&rotation=0&showTitle=false&status=done&style=none&taskId=u03dd1651-8139-47f1-9cd1-a5089b64bf9&title=&width=734) + +### 选中组件的配置 +当前组件的大类目选项，根据组件类型不同，包含如下子类目： + +#### 属性 +组件的基础属性值设置 +![Dec-17-2021 19-37-26.gif](https://cdn.nlark.com/yuque/0/2022/gif/242652/1644562222884-191c8433-2386-47f4-bab4-d3d1fe534f12.gif#clientId=u99b5ef7a-7ebb-4&crop=0&crop=0&crop=1&crop=1&from=paste&height=377&id=u43676a31&margin=%5Bobject%20Object%5D&name=Dec-17-2021%2019-37-26.gif&originHeight=754&originWidth=1468&originalType=binary&ratio=1&rotation=0&showTitle=false&status=done&style=none&taskId=u170b8d2a-c1f9-4acf-a0e2-9825c588dcd&title=&width=734) + +#### 样式 +组件的样式配置，如文字： +![Dec-17-2021 19-38-55.gif](https://cdn.nlark.com/yuque/0/2022/gif/242652/1644562224062-86fcf97b-d229-487f-951d-d2070337c058.gif#clientId=u99b5ef7a-7ebb-4&crop=0&crop=0&crop=1&crop=1&from=paste&height=377&id=u4a9930ae&margin=%5Bobject%20Object%5D&name=Dec-17-2021%2019-38-55.gif&originHeight=754&originWidth=1468&originalType=binary&ratio=1&rotation=0&showTitle=false&status=done&style=none&taskId=u4a81ecb9-5b51-4758-9dd0-eaeb2e1a318&title=&width=734) + +#### 事件 +绑定组件对外暴露的事件。 +![Dec-17-2021 19-41-17.gif](https://cdn.nlark.com/yuque/0/2022/gif/242652/1644562224632-a3ee9b18-97e8-4d31-b4fe-b58720dc6bf5.gif#clientId=u99b5ef7a-7ebb-4&crop=0&crop=0&crop=1&crop=1&from=paste&height=377&id=u534bb1ea&margin=%5Bobject%20Object%5D&name=Dec-17-2021%2019-41-17.gif&originHeight=754&originWidth=1468&originalType=binary&ratio=1&rotation=0&showTitle=false&status=done&style=none&taskId=u50691375-2514-4a6c-8bec-0be44adf141&title=&width=734) + +#### 高级 +循环、条件渲染与 key 设置。 +![Dec-17-2021 19-46-26.gif](https://cdn.nlark.com/yuque/0/2022/gif/242652/1644562226094-899cf104-3c60-439f-8b68-83af595ef275.gif#clientId=u99b5ef7a-7ebb-4&crop=0&crop=0&crop=1&crop=1&from=paste&height=377&id=u9190ed31&margin=%5Bobject%20Object%5D&name=Dec-17-2021%2019-46-26.gif&originHeight=754&originWidth=1468&originalType=binary&ratio=1&rotation=0&showTitle=false&status=done&style=none&taskId=uf02555c1-cd82-486d-8561-ca97e0ec1cd&title=&width=734) + +## 顶部：操作区 + +### 撤回和重做 +![Dec-17-2021 19-52-23.gif](https://cdn.nlark.com/yuque/0/2022/gif/242652/1644562226083-d7f69bff-42e6-4173-8ac8-6e5a0c0262d6.gif#clientId=u99b5ef7a-7ebb-4&crop=0&crop=0&crop=1&crop=1&from=paste&height=377&id=u81f5d842&margin=%5Bobject%20Object%5D&name=Dec-17-2021%2019-52-23.gif&originHeight=754&originWidth=1468&originalType=binary&ratio=1&rotation=0&showTitle=false&status=done&style=none&taskId=ubeb556cd-2349-44d8-b1be-ba6e32bea4e&title=&width=734) diff --git a/docs/docs/demoUsage/makeStuff/_category_.json b/docs/docs/demoUsage/makeStuff/_category_.json new file mode 100644 index 000000000..606d8d658 --- /dev/null +++ b/docs/docs/demoUsage/makeStuff/_category_.json @@ -0,0 +1,6 @@ +{ + "label": "如何制作", + "position": 1, + "collapsed": false, + "collapsible": false +} diff --git a/docs/docs/demoUsage/makeStuff/dialog.md b/docs/docs/demoUsage/makeStuff/dialog.md new file mode 100644 index 000000000..772bd5647 --- /dev/null +++ b/docs/docs/demoUsage/makeStuff/dialog.md @@ -0,0 +1,33 @@ +--- +title: 3. 如何通过按钮展示/隐藏弹窗 +sidebar_position: 1 +--- +### 1.拖拽一个按钮 + +![image.png](https://cdn.nlark.com/yuque/0/2022/png/2622706/1652355202273-1a84b1e5-e33c-4686-b92b-633936423141.png#clientId=udd01ff56-e3fe-4&crop=0&crop=0&crop=1&crop=1&from=paste&height=906&id=u81f6abfa&margin=%5Bobject%20Object%5D&name=image.png&originHeight=1812&originWidth=3584&originalType=binary&ratio=1&rotation=0&showTitle=false&size=749009&status=done&style=none&taskId=u6f4bf7e1-db67-4fca-8107-04021936c00&title=&width=1792) +### 2.拖拽一个弹窗 +![image.png](https://cdn.nlark.com/yuque/0/2022/png/2622706/1652355233863-6d65ee77-b2fa-4d51-a04c-f0582c99eb72.png#clientId=udd01ff56-e3fe-4&crop=0&crop=0&crop=1&crop=1&from=paste&height=811&id=u848a34e1&margin=%5Bobject%20Object%5D&name=image.png&originHeight=1622&originWidth=3578&originalType=binary&ratio=1&rotation=0&showTitle=false&size=774132&status=done&style=none&taskId=ue713e331-7ce0-4bd8-b41d-3ae1e07c69b&title=&width=1789) + +### 3.查看弹窗 refId +![image.png](https://cdn.nlark.com/yuque/0/2022/png/2622706/1652355269097-3e5282ed-2fdd-4a3b-b9b8-d78fac69c42e.png#clientId=udd01ff56-e3fe-4&crop=0&crop=0&crop=1&crop=1&from=paste&height=794&id=ufd9346c1&margin=%5Bobject%20Object%5D&name=image.png&originHeight=1588&originWidth=3574&originalType=binary&ratio=1&rotation=0&showTitle=false&size=843332&status=done&style=none&taskId=ubc630826-e577-4dee-a2c3-5478bdf266a&title=&width=1787) + +- 点击弹窗 +- 点击右侧面板中的高级 +- 找到 refId + +![image.png](https://cdn.nlark.com/yuque/0/2022/png/2622706/1652355320821-dd2c85f7-a75e-495d-896a-67e4761561ac.png#clientId=udd01ff56-e3fe-4&crop=0&crop=0&crop=1&crop=1&from=paste&height=898&id=u4bf6b721&margin=%5Bobject%20Object%5D&name=image.png&originHeight=1796&originWidth=3584&originalType=binary&ratio=1&rotation=0&showTitle=false&size=993930&status=done&style=none&taskId=u8c648fa2-c660-4979-8991-1cf138d2372&title=&width=1792) + +这里我们的 refId 是 "pro-dialog-entryl32xgrus" +### 4.隐藏弹窗 +点击工具栏的隐藏小图标，将弹窗在画布中隐藏 +![image.png](https://cdn.nlark.com/yuque/0/2022/png/2622706/1652355400766-f7bdca37-7ba9-497d-a7e2-ad1d92233a26.png#clientId=udd01ff56-e3fe-4&crop=0&crop=0&crop=1&crop=1&from=paste&height=784&id=ucbbe5086&margin=%5Bobject%20Object%5D&name=image.png&originHeight=1568&originWidth=3578&originalType=binary&ratio=1&rotation=0&showTitle=false&size=774518&status=done&style=none&taskId=u2c8e73cd-10c5-47d3-b96e-30e6840d1af&title=&width=1789) + +### 5.按钮绑定事件 +![image.png](https://cdn.nlark.com/yuque/0/2022/png/2622706/1652355486231-172c5797-c376-4f6f-94f7-8c3c593caa02.png#clientId=udd01ff56-e3fe-4&crop=0&crop=0&crop=1&crop=1&from=paste&height=907&id=ufcf7d50e&margin=%5Bobject%20Object%5D&name=image.png&originHeight=1814&originWidth=3584&originalType=binary&ratio=1&rotation=0&showTitle=false&size=845218&status=done&style=none&taskId=u7c2c54ce-9c18-4b29-a066-f3024a95443&title=&width=1792) + +**通过下面的代码即可打开弹窗** + +```typescript +this.$('pro-dialog-entryl32xgrus').open(); +``` +#### diff --git a/docs/docs/demoUsage/makeStuff/table.md b/docs/docs/demoUsage/makeStuff/table.md new file mode 100644 index 000000000..06999010d --- /dev/null +++ b/docs/docs/demoUsage/makeStuff/table.md @@ -0,0 +1,128 @@ +--- +title: 2. 如何制作表格 +sidebar_position: 0 +--- +# 步骤详解 +## 拖入组件 +一个常见的表格页面会包含查询框、表格和分页按钮。这些都在 Fusion UI 中进行了相应的封装，我们可以在左侧组件面板处找到他们。 +![image.png](https://cdn.nlark.com/yuque/0/2022/png/242652/1645011856718-ed2aa0b1-0c5c-4ec0-a72b-377bc500faf3.png#clientId=uf61aba9b-3a69-4&crop=0&crop=0&crop=1&crop=1&from=paste&height=824&id=ue90ea461&margin=%5Bobject%20Object%5D&name=image.png&originHeight=1648&originWidth=3032&originalType=binary&ratio=1&rotation=0&showTitle=false&size=963971&status=done&style=stroke&taskId=u3b1dfd98-44b7-4a13-be2a-e0124084288&title=&width=1516) + +将他们拖到画布之中： +![Feb-16-2022 16-58-59.gif](https://cdn.nlark.com/yuque/0/2022/gif/242652/1645002115004-4f01eb8d-cf68-4a7c-b0db-bc5aaf2604a3.gif#clientId=uf61aba9b-3a69-4&crop=0&crop=0&crop=1&crop=1&from=paste&height=396&id=uf69dc239&margin=%5Bobject%20Object%5D&name=Feb-16-2022%2016-58-59.gif&originHeight=792&originWidth=1534&originalType=binary&ratio=1&rotation=0&showTitle=false&size=7510570&status=done&style=stroke&taskId=ua6ea2651-6c6c-4762-98cc-cc3ab5734cd&title=&width=767) +## 配置组件 + +选中刚拖入的“查询筛选”组件，您可以配置此组件： +![Feb-14-2022 17-59-47.gif](https://cdn.nlark.com/yuque/0/2022/gif/242652/1644832912542-4b2e66ae-ba15-4e38-ab79-9f83e413a493.gif#clientId=uec0ffd6f-d4e1-4&crop=0&crop=0&crop=1&crop=1&from=ui&id=u83c491b2&margin=%5Bobject%20Object%5D&name=Feb-14-2022%2017-59-47.gif&originHeight=792&originWidth=1532&originalType=binary&ratio=1&rotation=0&showTitle=false&size=2147213&status=done&style=stroke&taskId=uffd7092e-a247-4f48-b831-aaffe3646f7&title=) + +对于形如 Array 的配置项目，我们可以增删项目、修改常用项、修改顺序。 + +![image.png](https://cdn.nlark.com/yuque/0/2022/png/242652/1645012184644-444d82fa-a226-4784-b0df-92a5a52748bc.png#clientId=uf61aba9b-3a69-4&crop=0&crop=0&crop=1&crop=1&from=paste&height=738&id=uc4ea8ded&margin=%5Bobject%20Object%5D&name=image.png&originHeight=1476&originWidth=3060&originalType=binary&ratio=1&rotation=0&showTitle=false&size=375890&status=done&style=none&taskId=u7a1f43d8-eac4-405e-a3c9-38d3047f452&title=&width=1530) + +掌握组件配置功能，我们就可以完成一个常用的查询框的配置： +![Feb-21-2022 18-05-52.gif](https://cdn.nlark.com/yuque/0/2022/gif/242652/1645437973453-1fd1dc10-99ad-4c18-af49-2741bd81c4ae.gif#clientId=u022fc577-71a7-4&crop=0&crop=0&crop=1&crop=1&from=paste&height=395&id=u964ae52f&margin=%5Bobject%20Object%5D&name=Feb-21-2022%2018-05-52.gif&originHeight=790&originWidth=1532&originalType=binary&ratio=1&rotation=0&showTitle=false&size=7210902&status=done&style=stroke&taskId=u9e39c54a-7467-4a96-b716-681cf598f09&title=&width=766) + +## 绑定数据 + +低代码场景下，我们需要绑定动态的数据。通过左侧的源码编辑面板，我们可以创建动态数据和它的相关处理函数： + +![image.png](https://cdn.nlark.com/yuque/0/2022/png/242652/1645012532562-596d4a96-908e-4094-836c-974bda61d8a2.png#clientId=uf61aba9b-3a69-4&crop=0&crop=0&crop=1&crop=1&from=paste&height=739&id=ufa7b81f8&margin=%5Bobject%20Object%5D&name=image.png&originHeight=1478&originWidth=2976&originalType=binary&ratio=1&rotation=0&showTitle=false&size=816197&status=done&style=none&taskId=u5ab9656e-26b6-427a-a52e-5e11dbc4a7a&title=&width=1488) +如图，我们配入如下自定义值进 state 里： +```json + "companies": [ + { company: '测试公司1', id: 1, createTime: +new Date() }, + { company: '测试公司2', id: 2, createTime: +new Date() }, + { company: '测试公司3', id: 3, createTime: +new Date() }, + ] +``` +定义动态数据以后，我们需要绑定它到组件的属性中，我们找到相关属性的配置： +![image.png](https://cdn.nlark.com/yuque/0/2022/png/242652/1645012714358-f3f39d5f-1790-4196-9f16-b45f51fa8f28.png#clientId=uf61aba9b-3a69-4&crop=0&crop=0&crop=1&crop=1&from=paste&height=896&id=u1126fd65&margin=%5Bobject%20Object%5D&name=image.png&originHeight=1792&originWidth=3546&originalType=binary&ratio=1&rotation=0&showTitle=false&size=413958&status=done&style=none&taskId=u976689ac-18a1-4f15-9fc2-60681670fc7&title=&width=1773) +![image.png](https://cdn.nlark.com/yuque/0/2022/png/242652/1645012791356-4fed1bea-bec2-4be9-85ea-b366d0acb4ab.png#clientId=uf61aba9b-3a69-4&crop=0&crop=0&crop=1&crop=1&from=paste&height=820&id=ub81b6dc8&margin=%5Bobject%20Object%5D&name=image.png&originHeight=1640&originWidth=3428&originalType=binary&ratio=1&rotation=0&showTitle=false&size=354847&status=done&style=none&taskId=uc645e654-b293-4c18-86da-a6637083e55&title=&width=1714) +如图，输入表达式： +```json +this.state.companies +``` +再结合上一节的“配置组件”操作，我们已经可以把表格的主体配置出来了： +![image.png](https://cdn.nlark.com/yuque/0/2022/png/242652/1645013130950-4219cf27-760c-4749-8d4e-013dd53dbc83.png#clientId=uf61aba9b-3a69-4&crop=0&crop=0&crop=1&crop=1&from=paste&height=820&id=u73c837e3&margin=%5Bobject%20Object%5D&name=image.png&originHeight=1640&originWidth=3058&originalType=binary&ratio=1&rotation=0&showTitle=false&size=408420&status=done&style=stroke&taskId=u23f7f045-8077-4e9d-9335-fea3ba54273&title=&width=1529) + +## 动态请求 + +我们进入代码区块，使用生命周期方法来完成动态数据的请求。假设提供数据的接口是：[http://rap2api.taobao.org/app/mock/250089/testCompanies](http://rap2api.taobao.org/app/mock/250089/testCompanies)，那么，我们可以在源码面板进行如下配置： +```typescript +class LowcodeComponent extends Component { + state = { + "text": "outer", + "isShowDialog": false, + "loading": false, + "companies": [ + { company: '测试公司1', id: 1, createTime: +new Date() }, + { company: '测试公司2', id: 2, createTime: +new Date() }, + { company: '测试公司3', id: 3, createTime: +new Date() }, + ] + } + componentDidMount() { + this.setState({ loading: true }) + window.fetch('http://rap2api.taobao.org/app/mock/250089/testCompanies') + .then((res) => res.json()) + .then((companies) => { + this.setState({ + companies, + }) + }) + .catch(err => console.error(err)) + .then(() => { + this.setState({ loading: false }) + }) + } +} +``` +在 `componentDidMount` 生命周期，将请求接口并设置 loading 和数据字段。 +点击保存或叉关闭源码面板后，我们可以看到代码已经生效了： +![image.png](https://cdn.nlark.com/yuque/0/2022/png/242652/1645013883960-ca217c38-5c40-4ecc-9e05-277098fef16a.png#clientId=uf61aba9b-3a69-4&crop=0&crop=0&crop=1&crop=1&from=paste&height=817&id=u1a3f852b&margin=%5Bobject%20Object%5D&name=image.png&originHeight=1634&originWidth=3058&originalType=binary&ratio=1&rotation=0&showTitle=false&size=427572&status=done&style=stroke&taskId=ubd2291b7-36c3-48c1-b489-9c61f0f6230&title=&width=1529) + +## 配置插槽 + +我们可以用绑定数据的方法把 loading 绑在加载指示上： +![image.png](https://cdn.nlark.com/yuque/0/2022/png/242652/1645014111323-c45f9b9a-77dd-4724-b6ee-78572863a871.png#clientId=uf61aba9b-3a69-4&crop=0&crop=0&crop=1&crop=1&from=paste&height=952&id=u3bdd353b&margin=%5Bobject%20Object%5D&name=image.png&originHeight=1904&originWidth=3170&originalType=binary&ratio=1&rotation=0&showTitle=false&size=503197&status=done&style=none&taskId=u1faed9f0-3c68-4385-8d08-e59e2a1600a&title=&width=1585) +![Feb-16-2022 20-24-35.gif](https://cdn.nlark.com/yuque/0/2022/gif/242652/1645014292272-68e07740-47dc-4c94-8437-beded0b07c63.gif#clientId=uf61aba9b-3a69-4&crop=0&crop=0&crop=1&crop=1&from=paste&height=396&id=u4506fc72&margin=%5Bobject%20Object%5D&name=Feb-16-2022%2020-24-35.gif&originHeight=792&originWidth=1532&originalType=binary&ratio=1&rotation=0&showTitle=false&size=6960677&status=done&style=stroke&taskId=u9fe02184-e6dc-4886-b371-c48ca1e2832&title=&width=766) +将 Loading 的“是否显示”字段绑定 `this.state.loading` 后，我们可以看到，这里暴露了一个插槽。插槽是可以任意扩展的预设部分，我们可以把其他的部分拖进插槽： +![Feb-16-2022 20-27-03.gif](https://cdn.nlark.com/yuque/0/2022/gif/242652/1645014436894-9b975ae6-76cc-412b-829a-fae3605277dc.gif#clientId=uf61aba9b-3a69-4&crop=0&crop=0&crop=1&crop=1&from=paste&height=396&id=u407467ac&margin=%5Bobject%20Object%5D&name=Feb-16-2022%2020-27-03.gif&originHeight=792&originWidth=1528&originalType=binary&ratio=1&rotation=0&showTitle=false&size=3443266&status=done&style=stroke&taskId=u0a091444-8b12-49a0-a57a-bfa758d351a&title=&width=764) +点击右上角的预览，我们能够看到完整的动态请求效果了： +![Feb-16-2022 20-28-36.gif](https://cdn.nlark.com/yuque/0/2022/gif/242652/1645014527841-b621f38f-2c03-40f1-aa41-19293f96b08f.gif#clientId=uf61aba9b-3a69-4&crop=0&crop=0&crop=1&crop=1&from=paste&height=396&id=u6ee6beea&margin=%5Bobject%20Object%5D&name=Feb-16-2022%2020-28-36.gif&originHeight=792&originWidth=1534&originalType=binary&ratio=1&rotation=0&showTitle=false&size=1968612&status=done&style=stroke&taskId=u2bdcee3f-91c5-4cb3-8405-f44f995cc78&title=&width=767) + +## 列挂钩浮层 + +为了能够让表格里的操作挂钩浮层，我们先拖入一个浮层： +![Feb-16-2022 20-32-09.gif](https://cdn.nlark.com/yuque/0/2022/gif/242652/1645014772471-0fce9b50-0f70-492e-bb53-5f875c00f5b4.gif#clientId=uf61aba9b-3a69-4&crop=0&crop=0&crop=1&crop=1&from=paste&height=396&id=u4d33cd05&margin=%5Bobject%20Object%5D&name=Feb-16-2022%2020-32-09.gif&originHeight=792&originWidth=1532&originalType=binary&ratio=1&rotation=0&showTitle=false&size=7475148&status=done&style=stroke&taskId=u9dc26cba-41eb-4fe8-b96f-fe391968861&title=&width=766) +使用大纲树能够临时显示和隐藏此浮层： +![Feb-16-2022 20-32-39.gif](https://cdn.nlark.com/yuque/0/2022/gif/242652/1645014828329-b2de4db6-9032-4280-b886-db17070eea21.gif#clientId=uf61aba9b-3a69-4&crop=0&crop=0&crop=1&crop=1&from=paste&height=396&id=ue27e6676&margin=%5Bobject%20Object%5D&name=Feb-16-2022%2020-32-39.gif&originHeight=792&originWidth=1530&originalType=binary&ratio=1&rotation=0&showTitle=false&size=7335022&status=done&style=stroke&taskId=u73554a5d-5ebe-48d1-a861-426ba8501b1&title=&width=765) +我们给表格增加一个数据列: +![Feb-16-2022 20-39-41.gif](https://cdn.nlark.com/yuque/0/2022/gif/242652/1645015242447-3e019714-4b86-4c10-9bf7-01e19201bf0c.gif#clientId=uf61aba9b-3a69-4&crop=0&crop=0&crop=1&crop=1&from=paste&height=396&id=uc2c35de3&margin=%5Bobject%20Object%5D&name=Feb-16-2022%2020-39-41.gif&originHeight=792&originWidth=1532&originalType=binary&ratio=1&rotation=0&showTitle=false&size=3415710&status=done&style=stroke&taskId=u5aedc5dd-f361-4e45-88b0-be09af09a6a&title=&width=766) + +然后配置它的行为为“弹窗”： +![Feb-16-2022 20-40-05.gif](https://cdn.nlark.com/yuque/0/2022/gif/242652/1645015223838-7f180e28-43e0-442b-a47e-ea5ff69d4900.gif#clientId=uf61aba9b-3a69-4&crop=0&crop=0&crop=1&crop=1&from=paste&height=396&id=u80f44f38&margin=%5Bobject%20Object%5D&name=Feb-16-2022%2020-40-05.gif&originHeight=792&originWidth=1532&originalType=binary&ratio=1&rotation=0&showTitle=false&size=7261162&status=done&style=stroke&taskId=u3828503a-ecac-452a-8d20-02e4a46ad02&title=&width=766) + +实现的效果如下： +![Feb-16-2022 20-42-51.gif](https://cdn.nlark.com/yuque/0/2022/gif/242652/1645015379808-7d7852b1-5902-42d0-b951-c9c5d8f4c893.gif#clientId=uf61aba9b-3a69-4&crop=0&crop=0&crop=1&crop=1&from=paste&height=396&id=ua2e7ceda&margin=%5Bobject%20Object%5D&name=Feb-16-2022%2020-42-51.gif&originHeight=792&originWidth=1534&originalType=binary&ratio=1&rotation=0&showTitle=false&size=588625&status=done&style=stroke&taskId=uf0466dde-ca4c-41d9-bf42-1ff443d02c5&title=&width=767) + +## 事件回调 + +上述功能点中，我们是把操作行为绑定在数据列上的，这一节我们绑定到操作列中。在操作列按钮处，点击下方的“添加一项”： +![Feb-23-2022 11-58-02.gif](https://cdn.nlark.com/yuque/0/2022/gif/242652/1645588703676-2a36cab4-52f4-4f31-9018-d56b41a55283.gif#clientId=u74bf469f-47f0-4&crop=0&crop=0&crop=1&crop=1&from=paste&height=395&id=u18d8ea0b&margin=%5Bobject%20Object%5D&name=Feb-23-2022%2011-58-02.gif&originHeight=790&originWidth=1534&originalType=binary&ratio=1&rotation=0&showTitle=false&size=8440133&status=done&style=stroke&taskId=u73e25800-c0fa-486b-9b68-4df7db9b9f1&title=&width=767) + +点击左侧的详情按钮，配置它的事件回调： +![Feb-23-2022 12-00-18.gif](https://cdn.nlark.com/yuque/0/2022/gif/242652/1645588832183-7ed0f06b-731d-4bd8-b934-723de43a8b42.gif#clientId=u74bf469f-47f0-4&crop=0&crop=0&crop=1&crop=1&from=paste&height=395&id=u59505da7&margin=%5Bobject%20Object%5D&name=Feb-23-2022%2012-00-18.gif&originHeight=790&originWidth=1534&originalType=binary&ratio=1&rotation=0&showTitle=false&size=9047220&status=done&style=stroke&taskId=ub8ab1b4e-4195-426f-b792-fc8bf91d142&title=&width=767) + +代码侧，我们配置这个回调函数： +```javascript +onClick_new(e, { rowKey, rowIndex, rowRecord }){ + window.Next.Message.show(JSON.stringify({ rowKey, rowIndex, rowRecord })) +} +``` +保存。预览时我们可以看到效果了： +![Feb-23-2022 12-05-25.gif](https://cdn.nlark.com/yuque/0/2022/gif/242652/1645589138764-d6514256-2a1f-4127-9591-747b4808848e.gif#clientId=u74bf469f-47f0-4&crop=0&crop=0&crop=1&crop=1&from=paste&height=395&id=u9f09d078&margin=%5Bobject%20Object%5D&name=Feb-23-2022%2012-05-25.gif&originHeight=790&originWidth=1532&originalType=binary&ratio=1&rotation=0&showTitle=false&size=2238638&status=done&style=stroke&taskId=u460c90f3-d692-45f9-9028-cf45d4cea98&title=&width=766) +# 研究本例的 schema + +我们把本例的 schema 保存在云端，您可以自行下载研究：[https://mo.m.taobao.com/marquex/lowcode-showcase-table](https://mo.m.taobao.com/marquex/lowcode-showcase-table) + +您可以通过左下角的 Schema 面板直接导入本例子的 Schema。 +![image.png](https://cdn.nlark.com/yuque/0/2022/png/242652/1645589288482-0ce8ea2f-c4e1-4956-be9c-143c9b71654b.png#clientId=u74bf469f-47f0-4&crop=0&crop=0&crop=1&crop=1&from=paste&height=810&id=u713729c6&margin=%5Bobject%20Object%5D&name=image.png&originHeight=1620&originWidth=3054&originalType=binary&ratio=1&rotation=0&showTitle=false&size=1074154&status=done&style=stroke&taskId=u783f33a5-241d-43ec-8b46-8385b733810&title=&width=1527) diff --git a/docs/docs/demoUsage/panels/_category_.json b/docs/docs/demoUsage/panels/_category_.json new file mode 100644 index 000000000..71315059f --- /dev/null +++ b/docs/docs/demoUsage/panels/_category_.json @@ -0,0 +1,6 @@ +{ + "label": "面板详解", + "position": 2, + "collapsed": false, + "collapsible": false +} diff --git a/docs/docs/demoUsage/panels/canvas.md b/docs/docs/demoUsage/panels/canvas.md new file mode 100644 index 000000000..0e4678076 --- /dev/null +++ b/docs/docs/demoUsage/panels/canvas.md @@ -0,0 +1,74 @@ +--- +title: 5. 画布详解 +sidebar_position: 1 +--- +## 组件操作 +### 画布操作 +点击组件在右侧面板中能够显示出对应组件的属性配置选项 +![Dec-17-2021 19-28-28.gif](https://cdn.nlark.com/yuque/0/2022/gif/242652/1644562216925-c4bd5f10-2469-452c-8c2d-fe92ba6d03a7.gif#clientId=u99b5ef7a-7ebb-4&crop=0&crop=0&crop=1&crop=1&from=paste&height=377&id=uff491710&margin=%5Bobject%20Object%5D&name=Dec-17-2021%2019-28-28.gif&originHeight=754&originWidth=1468&originalType=binary&ratio=1&rotation=0&showTitle=false&status=done&style=none&taskId=u2f775208-8b07-4968-9dd4-420c6e4d3c1&title=&width=734) + +拖拽修改组件的排列顺序 +![Dec-17-2021 19-29-40.gif](https://cdn.nlark.com/yuque/0/2022/gif/242652/1644562219867-61a41b16-4513-4827-80bf-f7e4832bcf3a.gif#clientId=u99b5ef7a-7ebb-4&crop=0&crop=0&crop=1&crop=1&from=paste&height=377&id=ueda50ec8&margin=%5Bobject%20Object%5D&name=Dec-17-2021%2019-29-40.gif&originHeight=754&originWidth=1468&originalType=binary&ratio=1&rotation=0&showTitle=false&status=done&style=none&taskId=ue0ec6bea-81f1-4d04-bf82-acde7c9983a&title=&width=734) + +拖拽时会在右侧提示当前的组件树。 +![Dec-17-2021 19-31-30.gif](https://cdn.nlark.com/yuque/0/2022/gif/242652/1644562220001-4afae72e-f9fd-4564-a904-c87f61ba79b5.gif#clientId=u99b5ef7a-7ebb-4&crop=0&crop=0&crop=1&crop=1&from=paste&height=377&id=ucc719a0e&margin=%5Bobject%20Object%5D&name=Dec-17-2021%2019-31-30.gif&originHeight=754&originWidth=1468&originalType=binary&ratio=1&rotation=0&showTitle=false&status=done&style=none&taskId=u2c46a827-8702-471c-a8c1-eb4f069d108&title=&width=734) + +### 组件控制 +点击组件右上角的复制按钮，或者按下 `ctrl + c` 再按下 `ctrl + v`，可以将其复制； +点击组件右上角的删除按钮，或者直接使用 `Delete` 键，可以将其删除。 +![Dec-17-2021 19-33-20.gif](https://cdn.nlark.com/yuque/0/2022/gif/242652/1644562220898-a54f0cfa-26bf-461f-a4aa-9708fc367d7c.gif#clientId=u99b5ef7a-7ebb-4&crop=0&crop=0&crop=1&crop=1&from=paste&height=377&id=u2bae31a2&margin=%5Bobject%20Object%5D&name=Dec-17-2021%2019-33-20.gif&originHeight=754&originWidth=1468&originalType=binary&ratio=1&rotation=0&showTitle=false&status=done&style=none&taskId=u2c4c7b00-b316-431a-9c54-949ae4ed766&title=&width=734) + +### 选择组件切换 + +可以用键盘上的按键切换组件选择： + +- `↑` 向上选择组件 +- `↓` 向下选择组件 +- `←` 向左选择组件 +- `→` 向右选择组件 + +可以 hover 到组件操作辅助区的第一项来选中组件的父级节点： +![Feb-22-2022 14-42-30.gif](https://cdn.nlark.com/yuque/0/2022/gif/242652/1645512169966-17f26afa-00fc-47a5-86be-08505ab39a4f.gif#clientId=u5c3042e1-7626-4&crop=0&crop=0&crop=1&crop=1&from=paste&height=395&id=uee0cbe0a&margin=%5Bobject%20Object%5D&name=Feb-22-2022%2014-42-30.gif&originHeight=790&originWidth=1536&originalType=binary&ratio=1&rotation=0&showTitle=false&size=2913977&status=done&style=stroke&taskId=ud9314fe0-0943-48e5-9f0c-b9b9b4a6b47&title=&width=768) + +### 可扩展项简述 + +快捷键、操作辅助区均可扩展。 + +## Slot 区块 + +React 中，可以定义一个 prop 选项为 `JSXElement` 或 `(...args) => JSXElement` 的形式，这个形式在低代码画布中，被定义为 Slot，允许往其内部拖入组件，进行符合直觉的操作。 +![Feb-22-2022 14-46-02.gif](https://cdn.nlark.com/yuque/0/2022/gif/242652/1645512376500-46baf1b5-2335-4fb5-a430-c2f2245c8439.gif#clientId=u5c3042e1-7626-4&crop=0&crop=0&crop=1&crop=1&from=paste&height=395&id=u8c429d95&margin=%5Bobject%20Object%5D&name=Feb-22-2022%2014-46-02.gif&originHeight=790&originWidth=1534&originalType=binary&ratio=1&rotation=0&showTitle=false&size=2389349&status=done&style=stroke&taskId=u7462c2e4-64bf-432a-aa2e-2fef526b4d4&title=&width=767) + +### 锁定 Slot + +您可以对 Slot 进行锁定操作，锁定后内部内容无法选中； +![Feb-22-2022 14-50-03.gif](https://cdn.nlark.com/yuque/0/2022/gif/242652/1645512638545-ae46bcd2-883b-4229-9f78-d59087d03d28.gif#clientId=u5c3042e1-7626-4&crop=0&crop=0&crop=1&crop=1&from=paste&height=395&id=u87ff9fe3&margin=%5Bobject%20Object%5D&name=Feb-22-2022%2014-50-03.gif&originHeight=790&originWidth=1534&originalType=binary&ratio=1&rotation=0&showTitle=false&size=9318074&status=done&style=none&taskId=ua4e1f652-2e72-4dcf-ad78-19b42e179c3&title=&width=767) + +在组件树可以解除操作。 + +## 组件编辑态 + +低代码引擎允许组件在编辑状态下表现得和渲染时不一样。Demo 中的布局组件就是用对应 API 完成布局的高级操作的。 + +它背后的实现有两种方法： + +- 侵入型：组件编辑态下，会往组件内传入 `__designMode: 'design'`，可以在组件中进行相应处理； + +![image.png](https://cdn.nlark.com/yuque/0/2022/png/242652/1645512859914-b51c23b9-50d9-4962-a6f7-96dbdcef6cef.png#clientId=u5c3042e1-7626-4&crop=0&crop=0&crop=1&crop=1&from=paste&height=821&id=uf96a3071&margin=%5Bobject%20Object%5D&name=image.png&originHeight=1642&originWidth=3066&originalType=binary&ratio=1&rotation=0&showTitle=false&size=1024714&status=done&style=none&taskId=u7838e6c7-2349-4224-94ed-4e0e972b2a2&title=&width=1533) + +- 双入口型：通过配置物料的 editUrls，加载专属于编辑态组件的物料。pro-layout 使用的是这种方式 +```json + { + "package": "@alifd/pro-layout", + "version": "1.0.1-beta.6", + "library": "AlifdProLayout", + "urls": [ + "https://alifd.alicdn.com/npm/@alifd/pro-layout@1.0.1-beta.6/dist/AlifdProLayout.js", + "https://alifd.alicdn.com/npm/@alifd/pro-layout@1.0.1-beta.6/dist/AlifdProLayout.css" + ], + "editUrls": [ + "https://alifd.alicdn.com/npm/@alifd/pro-layout@1.0.1-beta.6/build/lowcode/view.js", + "https://alifd.alicdn.com/npm/@alifd/pro-layout@1.0.1-beta.6/build/lowcode/view.css" + ] + } +``` diff --git a/docs/docs/demoUsage/panels/code.md b/docs/docs/demoUsage/panels/code.md new file mode 100644 index 000000000..717c2353a --- /dev/null +++ b/docs/docs/demoUsage/panels/code.md @@ -0,0 +1,165 @@ +--- +title: 7. 源码面板详解 +sidebar_position: 3 +--- +在源码面板中，您可以完成低代码中的代码部分编写。 + +## 面板功能拆解 + +![image.png](https://cdn.nlark.com/yuque/0/2022/png/242652/1644897390779-cefb2c31-82fc-44f4-b824-adc32569ac6f.png#clientId=ud3fa1588-e66f-4&crop=0&crop=0&crop=1&crop=1&from=paste&height=870&id=u23446c19&margin=%5Bobject%20Object%5D&name=image.png&originHeight=1740&originWidth=2502&originalType=binary&ratio=1&rotation=0&showTitle=false&size=865371&status=done&style=none&taskId=u44e2b188-c268-4a30-a628-76a046be9d4&title=&width=1251) + +### 代码编辑面板 + +代码编辑面板允许您书写 JavaScript 代码，并支持 JSX 语法。 +由于依赖了 Babel，所以书写的 JSX 和 Chrome 80+ 以后的新语法也会被自动编译： + +| 编译前 | 编译后 | +| --- | --- | +| ![image.png](https://cdn.nlark.com/yuque/0/2022/png/242652/1644897774925-b54126e0-ff6b-445e-bc68-569731aef8c3.png#clientId=ud3fa1588-e66f-4&crop=0&crop=0&crop=1&crop=1&from=paste&height=95&id=nhuiT&margin=%5Bobject%20Object%5D&name=image.png&originHeight=190&originWidth=670&originalType=binary&ratio=1&rotation=0&showTitle=false&size=25045&status=done&style=none&taskId=u323192f6-7cfa-4d73-a184-2699f648c6f&title=&width=335) | ![image.png](https://cdn.nlark.com/yuque/0/2022/png/242652/1644897840129-83fe9a81-d8b2-4873-8764-904f531ec959.png#clientId=ud3fa1588-e66f-4&crop=0&crop=0&crop=1&crop=1&from=paste&height=55&id=u3ba8300e&margin=%5Bobject%20Object%5D&name=image.png&originHeight=110&originWidth=2094&originalType=binary&ratio=1&rotation=0&showTitle=false&size=44006&status=done&style=none&taskId=uef1552e3-ccdb-45dd-95d5-187a6c6b7df&title=&width=1047) | +| ![image.png](https://cdn.nlark.com/yuque/0/2022/png/242652/1644897884917-641b1547-7b90-4f78-86c1-0cc51996623d.png#clientId=ud3fa1588-e66f-4&crop=0&crop=0&crop=1&crop=1&from=paste&height=60&id=u5fa00781&margin=%5Bobject%20Object%5D&name=image.png&originHeight=120&originWidth=434&originalType=binary&ratio=1&rotation=0&showTitle=false&size=17421&status=done&style=none&taskId=uecee8fbf-a786-4f89-ac9c-f2f8d059fe0&title=&width=217) | ![image.png](https://cdn.nlark.com/yuque/0/2022/png/242652/1644897915892-a1784bc2-693b-4cf6-a082-3c8e0368a987.png#clientId=ud3fa1588-e66f-4&crop=0&crop=0&crop=1&crop=1&from=paste&height=60&id=ubcca6a46&margin=%5Bobject%20Object%5D&name=image.png&originHeight=120&originWidth=2536&originalType=binary&ratio=1&rotation=0&showTitle=false&size=50743&status=done&style=none&taskId=ue0f418e0-4192-4bfd-8912-9b64faedb66&title=&width=1268) | + + +> 注：因为编译结果会被 `@babel/runtime` 干扰，目前面板不支持 `async await`或 `{ ...arr }` 形态的语法编译。如果您需要此类编译，您可以考虑在读取 schema 中的 `originCode` 之后自己手动通过 babel 编译。 + + +#### 全局变量引用 + +在代码中，您可以通过 window 来引用全局变量。资产包中的 packages 都是通过 UMD 方式引入的对应内容，如果您引入了 Fusion Next（Demo 中默认引入），那么可以通过此方法直接唤起 Fusion Next 的内容，如弹窗提示： +```typescript +window.Next.Message.success('成功') +``` +![image.png](https://cdn.nlark.com/yuque/0/2022/png/242652/1644898647058-9a5d6800-31fd-4c62-a577-850b90fc5d21.png#clientId=ud3fa1588-e66f-4&crop=0&crop=0&crop=1&crop=1&from=paste&height=57&id=ue6231d61&margin=%5Bobject%20Object%5D&name=image.png&originHeight=114&originWidth=238&originalType=binary&ratio=1&rotation=0&showTitle=false&size=11360&status=done&style=none&taskId=u869f3709-a599-4ead-a80f-fa3b49c9836&title=&width=119) + +#### 局部变量引用 + +您可以在成员函数中访问到如下变量： + +- `this.state` +- `this.setState` +- `this.context.appHelper.utils` +- `this.context.appHelper.constants` +- `this.context.appHelper.requestHandlerMap` +- `this.context.components` + +#### 读、写与异常处理 + +- 读取：每次打开面板时，都会尝试读取 schema 中的 originCode 字段，如果没有，则从 schema 上的字段还原代码； +- 写入：在关闭代码编辑面板（主动点击叉或者点击非代码编辑区块的被动关闭都算）时，将自动写入到 schema 中；您也可以在编辑过程中点击“保存”按钮手动保存； +| 源码面板中 | schema 中 | +| --- | --- | +| 本地数据初始值设置： +![image.png](https://cdn.nlark.com/yuque/0/2022/png/242652/1644899552013-3de394fd-f530-4b4f-8258-8b9c64f11c11.png#clientId=ud3fa1588-e66f-4&crop=0&crop=0&crop=1&crop=1&from=paste&height=73&id=u291f7733&margin=%5Bobject%20Object%5D&name=image.png&originHeight=146&originWidth=370&originalType=binary&ratio=1&rotation=0&showTitle=false&size=17505&status=done&style=none&taskId=u55496884-bc04-4867-9295-c71f44b77ef&title=&width=185) | ![image.png](https://cdn.nlark.com/yuque/0/2022/png/242652/1644899587782-0ceea074-07bb-4260-a580-7f49a82740ed.png#clientId=ud3fa1588-e66f-4&crop=0&crop=0&crop=1&crop=1&from=paste&height=413&id=u01ae12cb&margin=%5Bobject%20Object%5D&name=image.png&originHeight=826&originWidth=2098&originalType=binary&ratio=1&rotation=0&showTitle=false&size=776122&status=done&style=none&taskId=ube04795b-6244-4aac-9ebc-f4624e605db&title=&width=1049) | +| 生命周期方法： +![image.png](https://cdn.nlark.com/yuque/0/2022/png/242652/1644899759963-d198edc4-a8c7-4a3f-90ee-b42244398958.png#clientId=ud3fa1588-e66f-4&crop=0&crop=0&crop=1&crop=1&from=paste&height=130&id=uafcbf72e&margin=%5Bobject%20Object%5D&name=image.png&originHeight=260&originWidth=478&originalType=binary&ratio=1&rotation=0&showTitle=false&size=37208&status=done&style=none&taskId=u19b58f72-7058-4a22-9a8e-334a9a541bd&title=&width=239) | ![image.png](https://cdn.nlark.com/yuque/0/2022/png/242652/1644899791416-a7969846-8d7d-4c51-9c55-6b1c65faf07b.png#clientId=ud3fa1588-e66f-4&crop=0&crop=0&crop=1&crop=1&from=paste&height=418&id=uc6edd06d&margin=%5Bobject%20Object%5D&name=image.png&originHeight=836&originWidth=2010&originalType=binary&ratio=1&rotation=0&showTitle=false&size=806116&status=done&style=none&taskId=uacb7cf67-ee4b-45ba-962a-24f43b525bc&title=&width=1005) | +| 自定义函数： +![image.png](https://cdn.nlark.com/yuque/0/2022/png/242652/1644899808831-538e59a7-6d40-4e1a-bd72-bd2332bb9d7c.png#clientId=ud3fa1588-e66f-4&crop=0&crop=0&crop=1&crop=1&from=paste&height=321&id=u2ea3e043&margin=%5Bobject%20Object%5D&name=image.png&originHeight=642&originWidth=660&originalType=binary&ratio=1&rotation=0&showTitle=false&size=72124&status=done&style=none&taskId=uc6ec76e1-89a0-4dad-a0ab-053730e2b4d&title=&width=330) | ![image.png](https://cdn.nlark.com/yuque/0/2022/png/242652/1644899830711-e262e41e-8332-4810-9293-bd4ef540c919.png#clientId=ud3fa1588-e66f-4&crop=0&crop=0&crop=1&crop=1&from=paste&height=411&id=ueb7c1ad8&margin=%5Bobject%20Object%5D&name=image.png&originHeight=822&originWidth=1862&originalType=binary&ratio=1&rotation=0&showTitle=false&size=815729&status=done&style=none&taskId=u3aae2a2e-4de4-468a-bd5a-5bec53b908a&title=&width=931) | +| 编译前全量代码： +![image.png](https://cdn.nlark.com/yuque/0/2022/png/242652/1644899850193-0b1990ea-e494-4c5f-94ef-9a1fdbde0a98.png#clientId=ud3fa1588-e66f-4&crop=0&crop=0&crop=1&crop=1&from=paste&height=561&id=u92136fdf&margin=%5Bobject%20Object%5D&name=image.png&originHeight=1122&originWidth=762&originalType=binary&ratio=1&rotation=0&showTitle=false&size=165346&status=done&style=none&taskId=u727c08ae-f56f-4632-acc0-837fa220681&title=&width=381) | ![image.png](https://cdn.nlark.com/yuque/0/2022/png/242652/1644899882162-648366a3-5b0b-4cf3-b103-bf3812f6e807.png#clientId=ud3fa1588-e66f-4&crop=0&crop=0&crop=1&crop=1&from=paste&height=398&id=ub882b04a&margin=%5Bobject%20Object%5D&name=image.png&originHeight=796&originWidth=1906&originalType=binary&ratio=1&rotation=0&showTitle=false&size=716114&status=done&style=none&taskId=u94d53b7d-5ea9-471a-b82c-3dec1a532b5&title=&width=953) | + + +- 异常处理：如果代码解析失败，它将无法被正常保存到 schema 中，此时编辑器会弹层提示： + +![image.png](https://cdn.nlark.com/yuque/0/2022/png/242652/1644899252223-57317fcb-0958-4f38-a37b-00eaa5561512.png#clientId=ud3fa1588-e66f-4&crop=0&crop=0&crop=1&crop=1&from=paste&height=819&id=u2d66f54c&margin=%5Bobject%20Object%5D&name=image.png&originHeight=1638&originWidth=3068&originalType=binary&ratio=1&rotation=0&showTitle=false&size=473979&status=done&style=none&taskId=u9e4a4c69-dd56-4265-93d7-9b2e4e8971a&title=&width=1534) + +### 样式编辑面板 + +您可以在这里书写 CSS 内容。它对应 schema 中的 css 字段： + +| 源码面板中 | Schema 中 | +| --- | --- | +| ![image.png](https://cdn.nlark.com/yuque/0/2022/png/242652/1644899312003-76f4c95e-221f-4b5f-92ae-c51e664385e0.png#clientId=ud3fa1588-e66f-4&crop=0&crop=0&crop=1&crop=1&from=paste&height=194&id=u30912dec&margin=%5Bobject%20Object%5D&name=image.png&originHeight=388&originWidth=634&originalType=binary&ratio=1&rotation=0&showTitle=false&size=42979&status=done&style=none&taskId=ue2a18106-55f3-4cff-8f95-904317d0419&title=&width=317) | ![image.png](https://cdn.nlark.com/yuque/0/2022/png/242652/1644899355488-aa352d2d-a001-434f-9368-021befea52ed.png#clientId=ud3fa1588-e66f-4&crop=0&crop=0&crop=1&crop=1&from=paste&height=291&id=u60b8f9d4&margin=%5Bobject%20Object%5D&name=image.png&originHeight=582&originWidth=1646&originalType=binary&ratio=1&rotation=0&showTitle=false&size=454443&status=done&style=none&taskId=u236b94fb-6c20-4c6c-9fe3-7cd75eef0c4&title=&width=823) | + + +## 对接代码 + +### 生命周期对接 +如果您书写了视图相关的声明周期方法，那么对应的方法会在视图的特定周期被调用。支持的生命周期函数在《阿里巴巴中后台前端搭建协议规范》中被定义，包含： +```typescript +{ + componentDidMount(): void; + constructor(props: Record, context: any); + render(): void; + componentDidUpdate(prevProps: Record, prevState: Record, snapshot: Record): void; + componentWillUnmount(): void; + componentDidCatch(error: Error, info: any): void; +} +``` + +### 设置器面板对接 + +书写完了函数 / state 后，您可以在右侧的设置器面板中配置对代码的部分。 + +通常书写代码是为了对接低代码配置中的“变量绑定”、“事件回调”、“条件判断”和“循环”部分的。 + +#### 变量绑定 +![image.png](https://cdn.nlark.com/yuque/0/2022/png/242652/1644899977727-f4f44171-52e8-4062-b558-436536b84640.png#clientId=ud3fa1588-e66f-4&crop=0&crop=0&crop=1&crop=1&from=paste&height=732&id=ua42e46e3&margin=%5Bobject%20Object%5D&name=image.png&originHeight=1464&originWidth=2738&originalType=binary&ratio=1&rotation=0&showTitle=false&size=957243&status=done&style=stroke&taskId=u56f7f36d-535d-48e9-8a0c-e0cb1f9af1d&title=&width=1369) +![image.png](https://cdn.nlark.com/yuque/0/2022/png/242652/1644900005551-14c356a0-2e51-4b0b-82b5-8a135d1c6c3e.png#clientId=ud3fa1588-e66f-4&crop=0&crop=0&crop=1&crop=1&from=paste&height=583&id=ufcb9db2b&margin=%5Bobject%20Object%5D&name=image.png&originHeight=1166&originWidth=1528&originalType=binary&ratio=1&rotation=0&showTitle=false&size=153133&status=done&style=stroke&taskId=u208e369b-f019-4019-8c2e-4c28b6eba91&title=&width=764) +```json +{ + "componentName": "NextBlockCell", + "id": "node_ockzmje8tf5", + "props": { + "bodyPadding": { + "type": "JSExpression", + "value": "this.state.text", + "mock": "" + } + } +} +``` + + +#### 事件回调 +![image.png](https://cdn.nlark.com/yuque/0/2022/png/242652/1644900095962-2ec54fb5-e1f8-4d4a-a75e-24e1c685a833.png#clientId=ud3fa1588-e66f-4&crop=0&crop=0&crop=1&crop=1&from=paste&height=726&id=ufed11f2e&margin=%5Bobject%20Object%5D&name=image.png&originHeight=1452&originWidth=2734&originalType=binary&ratio=1&rotation=0&showTitle=false&size=749908&status=done&style=stroke&taskId=uc379b8ec-c344-48f8-9b43-8d9be961356&title=&width=1367) +![image.png](https://cdn.nlark.com/yuque/0/2022/png/242652/1644900119673-f9538274-c896-4951-86f2-54d60ac95316.png#clientId=ud3fa1588-e66f-4&crop=0&crop=0&crop=1&crop=1&from=paste&height=581&id=uffdcbbce&margin=%5Bobject%20Object%5D&name=image.png&originHeight=1162&originWidth=1670&originalType=binary&ratio=1&rotation=0&showTitle=false&size=118712&status=done&style=stroke&taskId=u261a9b7f-9f5a-406a-aa55-8a3f33bdd05&title=&width=835) +```json +{ + "componentName": "Filter", + "id": "node_ockzmj0cl11w", + "props": { + "__events": { + "eventDataList": [ + { + "type": "componentEvent", + "name": "onSearch", + "relatedEventName": "closeDialog" + } + ] + }, + "onSearch": { + "type": "JSFunction", + "value": "function(){this.onSearch.apply(this,Array.prototype.slice.call(arguments).concat([])) }" + } + } +} +``` + +#### 条件判断 +![image.png](https://cdn.nlark.com/yuque/0/2022/png/242652/1644900186943-de6b33de-adca-4c1b-8f47-f68cf6ce5f77.png#clientId=ud3fa1588-e66f-4&crop=0&crop=0&crop=1&crop=1&from=paste&height=726&id=u23b46226&margin=%5Bobject%20Object%5D&name=image.png&originHeight=1452&originWidth=2738&originalType=binary&ratio=1&rotation=0&showTitle=false&size=789132&status=done&style=stroke&taskId=u6322e6a8-bea3-47d8-a374-b9ec6558bb9&title=&width=1369) +![image.png](https://cdn.nlark.com/yuque/0/2022/png/242652/1644900005551-14c356a0-2e51-4b0b-82b5-8a135d1c6c3e.png#clientId=ud3fa1588-e66f-4&crop=0&crop=0&crop=1&crop=1&from=paste&height=583&id=G2uKJ&margin=%5Bobject%20Object%5D&name=image.png&originHeight=1166&originWidth=1528&originalType=binary&ratio=1&rotation=0&showTitle=false&size=153133&status=done&style=stroke&taskId=u208e369b-f019-4019-8c2e-4c28b6eba91&title=&width=764) +```json +{ + "componentName": "Filter", + "id": "node_ockzmj0cl11w", + "condition": { + "type": "JSExpression", + "value": "this.state.text", + "mock": true + } +} +``` + +#### 循环 +![image.png](https://cdn.nlark.com/yuque/0/2022/png/242652/1644900265929-c21c9927-1f34-49b6-9dc6-bcb4357190be.png#clientId=ud3fa1588-e66f-4&crop=0&crop=0&crop=1&crop=1&from=paste&height=730&id=u8f457b1e&margin=%5Bobject%20Object%5D&name=image.png&originHeight=1460&originWidth=2746&originalType=binary&ratio=1&rotation=0&showTitle=false&size=781151&status=done&style=stroke&taskId=u92be7d31-2070-4a08-bc1c-6b1a599c682&title=&width=1373) +![image.png](https://cdn.nlark.com/yuque/0/2022/png/242652/1644900005551-14c356a0-2e51-4b0b-82b5-8a135d1c6c3e.png#clientId=ud3fa1588-e66f-4&crop=0&crop=0&crop=1&crop=1&from=paste&height=583&id=ot5cO&margin=%5Bobject%20Object%5D&name=image.png&originHeight=1166&originWidth=1528&originalType=binary&ratio=1&rotation=0&showTitle=false&size=153133&status=done&style=stroke&taskId=u208e369b-f019-4019-8c2e-4c28b6eba91&title=&width=764) +```json +{ + "componentName": "Filter", + "id": "node_ockzmj0cl11w", + "loop": { + "type": "JSExpression", + "value": "this.state.text", + "mock": true + } +} +``` diff --git a/docs/docs/demoUsage/panels/component.md b/docs/docs/demoUsage/panels/component.md new file mode 100644 index 000000000..814792741 --- /dev/null +++ b/docs/docs/demoUsage/panels/component.md @@ -0,0 +1,32 @@ +--- +title: 4. 组件面板详解 +sidebar_position: 0 +--- +## 概述 +组件面板顾名思义就是承载组件的面板，组件面板会获取并解析传入给低代码引擎的资产包数据(数据结构[点此查看](https://lowcode-engine.cn/assets))，得到需要被展示的组件列表，并根据分类、排序规则对组件进行排列，同时也提供了搜索功能。 +![image.png](https://cdn.nlark.com/yuque/0/2022/png/231502/1647964501932-33676243-c42b-4e7c-8663-77c5898d3343.png#clientId=uf38e3cbf-9388-4&crop=0&crop=0&crop=1&crop=1&from=paste&height=438&id=ubb9e4616&margin=%5Bobject%20Object%5D&name=image.png&originHeight=1672&originWidth=3056&originalType=binary&ratio=1&rotation=0&showTitle=true&size=451947&status=done&style=stroke&taskId=u0fc240e1-a792-4bd1-b84d-5bbc8e8fc8b&title=%E7%BB%84%E4%BB%B6%E9%9D%A2%E6%9D%BF&width=800 "组件面板") +## 组件信息 +组件面板承载的组件信息有： + +- 组件标题； +- 组件截图； +- 组件低代码 schema 片段； +- 组件分组； +- 组件分类； +- 是否隐藏组件； +- 关键词：关键词用于搜索，会聚合 name、title、description、keywords 等字段作为搜索匹配的目标； + +其中标题和截图是我们能够看到的，schema 片段则是拖拽到设计器时会自动插入页面 schema 中，面板会根据分组、分类来对组件进行排列； +这些组件信息均通过资产包数据获取，字段对应关系如下图所示： +![image.png](https://cdn.nlark.com/yuque/0/2022/png/231502/1647965256061-d15ad119-471f-43c7-8856-2c91bb3670ad.png#clientId=uf38e3cbf-9388-4&crop=0&crop=0&crop=1&crop=1&from=paste&height=1012&id=u1b3132db&margin=%5Bobject%20Object%5D&name=image.png&originHeight=1678&originWidth=1326&originalType=binary&ratio=1&rotation=0&showTitle=false&size=996705&status=done&style=stroke&taskId=u6730f591-c7e1-42ba-8cb7-fcc95e76e8c&title=&width=800) +## 组件分组、分类排序 +组件面板会把相同分组的组件放在同一个 tab 下，相同分类的组件放在同一个 collapse 中，同时也支持对 tab 和 collapse 进行排序； +由于是整体性的排序，组件自身的信息无法决定此排序，因此在资产包数据根节点新增了 sort 字段用于指定分组和分类的排序，具体定义在[《低代码引擎资产包协议规范》](https://lowcode-engine.cn/assets)2.4 sort 章节； + +| **根属性名称** | **类型** | **说明** | **变量支持** | **默认值** | +| --- | --- | --- | --- | --- | +| sort.groupList | String[] | 组件分组，用于组件面板 tab 展示 | - | ['精选组件', '原子组件'] | +| sort.categoryList | String[] | 组件面板中同一个 tab 下的不同区间用 category 区分，category 的排序依照 categoryList 顺序排列 | - | ['通用', '数据展示', '表格类', '表单类'] | + +## 搜索 +组件面板会提取组件的 name、title、description、keywords 等字段作为搜索匹配的目标，因此除了能够通过组件名称、描述进行搜索外，还可以指定一些关键词-keywords，keywords 是数组也可以是字符串类型。 diff --git a/docs/docs/demoUsage/panels/datasource.md b/docs/docs/demoUsage/panels/datasource.md new file mode 100644 index 000000000..3116f1939 --- /dev/null +++ b/docs/docs/demoUsage/panels/datasource.md @@ -0,0 +1,150 @@ +--- +title: 8. 数据源面板详解 +sidebar_position: 4 +--- +## 🪚 概述 +数据源面板主要负责管理低代码中远程数据源内容，通过可视化编辑的方式操作低代码协议中的数据源Schema，配合 [数据源引擎](https://www.yuque.com/lce/doc/datasource-engine) 即可实现低代码中数据源的生产和消费； +![image.png](https://cdn.nlark.com/yuque/0/2022/png/84508/1648397674378-aec10892-5ee4-414d-807e-39f55f3a5be5.png#clientId=u38847497-05f3-4&crop=0&crop=0&crop=1&crop=1&from=paste&height=821&id=u07e82f8a&margin=%5Bobject%20Object%5D&name=image.png&originHeight=1642&originWidth=2878&originalType=binary&ratio=1&rotation=0&showTitle=false&size=246032&status=done&style=none&taskId=uc18acbc5-1404-4266-a499-e952d1084c4&title=&width=1439) +数据源面板 +## ❓如何使用 +> 面板内包含了数据源创建、删除、编辑、排序、导入导出、复制以及搜索等能力，内置支持了 `fecth` & `JSONP`两种常用远程请求类型； + +### 三步创建一个数据源 +![image.png](https://cdn.nlark.com/yuque/0/2022/png/84508/1648398269436-bd241801-e617-4640-830f-03b44aca80a1.png#clientId=u38847497-05f3-4&crop=0&crop=0&crop=1&crop=1&from=paste&height=819&id=u1ee9fa0d&margin=%5Bobject%20Object%5D&name=image.png&originHeight=1638&originWidth=2878&originalType=binary&ratio=1&rotation=0&showTitle=false&size=279302&status=done&style=none&taskId=ue1248934-df36-423c-86f3-160a4e865da&title=&width=1439) +三步创建数据源 + +### 参数详解 +> TODO + +## ☠️ 更多介绍 +### 数据源顺序 +> 数据源为何支持排序功能，主要原因是数据源的加载存在先后顺序；接下来我们从协议层以及实现层看数据源之间的顺序关系； + +TODO +### 如何定制数据源 +#### 定制数据源类型（设计态） +#### 定制数据源请求实现（运行态） +> 当出现以下两种情况的时，我们需要定制数据源请求实现， +> - 当你默认提供的 `handler`无法满足你的需求 +> - 定制了数据源类型，比如 `GraphQL`，需要实现一个对应的 `handler` + +接下来我们来看一个例子，如何实现一个 `handler` +```javascript +import { RuntimeOptionsConfig } from '@alilc/lowcode-datasource-types'; + +import request from 'universal-request'; +import { RequestOptions, AsObject } from 'universal-request/lib/types'; + +export function createFetchHandler(config?: Record) { + return async function(options: RuntimeOptionsConfig) { + const requestConfig: RequestOptions = { + ...options, + url: options.uri, + method: options.method as RequestOptions['method'], + data: options.params as AsObject, + headers: options.headers as AsObject, + ...config, + }; + const response = await request(requestConfig); + return response; + }; +} +``` +低代码fetch-handler默认实现 + +以上代码是低代码内置的fetch-handler默认实现，内部使用了 `universal-request`，假如你们内部使用的 `axios`，你完全重新实现一个； +```javascript +import axios from 'axios'; +export function createAxiosFetchHandler(config?: Record) { + return async function(options: RuntimeOptionsConfig) { + const requestConfig: RequestOptions = { + ...options, + url: options.uri, + method: options.method as RequestOptions['method'], + data: options.params, + headers: options.headers, + ...config, + }; + const response = await axios(requestConfig); + return response; + }; +} +``` + +##### 注册到render +完成一个Handler后你可以通过以下方式接入到render或者出码中使用 + +###### 渲染Render +```tsx +import React, { memo } from 'react'; +import ReactRenderer from '@alilc/lowcode-react-renderer'; + +const SamplePreview = memo(() => { + return ( + + ); +}); +``` +###### 出码 +> 目前自定义只能通过重新定义类型来完成，接下来我们会给出码添加requestHandlersMap映射能力；如有需求请联系 荣彬(github-id:xingmolu) + + +### 设计态启用数据源引擎 +> 默认情况下设计态没有开启数据源引擎，我们可以在设计器init的时候来传递`requstHandlersMap`来开启；具体代码如下： + +```javascript +import { init, plugins } from '@alilc/lowcode-engine'; +import { RequestHandlersMap } from '@alilc/lowcode-datasource-types'; + +const preference = new Map(); + +(async function main() { + await plugins.register(scenarioSwitcher); + await registerPlugins(); + + init(document.getElementById('lce-container')!, { + // designMode: 'live', + // locale: 'zh-CN', + enableCondition: true, + enableCanvasLock: true, + // 默认绑定变量 + supportVariableGlobally: true, + // simulatorUrl 在当 engine-core.js 同一个父路径下时是不需要配置的！！！ + // 这里因为用的是 alifd cdn，在不同 npm 包，engine-core.js 和 react-simulator-renderer.js 是不同路径 + simulatorUrl: [ + 'https://alifd.alicdn.com/npm/@alilc/lowcode-react-simulator-renderer@latest/dist/css/react-simulator-renderer.css', + 'https://alifd.alicdn.com/npm/@alilc/lowcode-react-simulator-renderer@latest/dist/js/react-simulator-renderer.js' + ], + requestHandlersMap: { + fetch: createAxiosFetchHandler() + } + }, preference); +})(); + +``` +## 🥡 附录 +### 数据源协议 +| **参数** | **说明** | **类型** | **支持变量** | **默认值** | **备注** | +| --- | --- | --- | --- | --- | --- | +| id | 数据请求 ID 标识 | String | - | - | | +| isInit | 是否为初始数据 | Boolean | ✅ | true | 值为 true 时，将在组件初始化渲染时自动发送当前数据请求 | +| isSync | 是否需要串行执行 | Boolean | ✅ | false | 值为 true 时，当前请求将被串行执行 | +| type | 数据请求类型 | String | - | fetch | 支持四种类型：fetch/mtop/jsonp/custom | +| shouldFetch | 本次请求是否可以正常请求 | (options: ComponentDataSourceItemOptions) => boolean | - | () => true | function 参数参考 [ComponentDataSourceItemOptions 对象描述](https://lowcode-engine.cn/lowcode#2315-componentdatasourceitemoptions-%E5%AF%B9%E8%B1%A1%E6%8F%8F%E8%BF%B0) | +| willFetch | 单个数据结果请求参数处理函数 | Function | - | options => options | 只接受一个参数（options），返回值作为请求的 options，当处理异常时，使用原 options。也可以返回一个 Promise，resolve 的值作为请求的 options，reject 时，使用原 options | +| requestHandler | 自定义扩展的外部请求处理器 | Function | - | - | 仅 type=‘custom’ 时生效 | +| dataHandler | request 成功后的回调函数 | Function | - | response => response.data | 参数: 请求成功后 promise 的 value 值 | +| errorHandler | request 失败后的回调函数 | Function | - | - | 参数: 请求出错 promise 的 error 内容 | +| options {} | 请求参数 | **ComponentDataSourceItemOptions** | - | - | 每种请求类型对应不同参数, 详见 [ComponentDataSourceItemOptions 对象描述](https://lowcode-engine.cn/lowcode#2315-componentdatasourceitemoptions-%E5%AF%B9%E8%B1%A1%E6%8F%8F%E8%BF%B0) | + +### 运行时实现层：数据源引擎设计 +[https://www.yuque.com/lce/doc/datasource-engine](https://www.yuque.com/lce/doc/datasource-engine) diff --git a/docs/docs/demoUsage/panels/settings.md b/docs/docs/demoUsage/panels/settings.md new file mode 100644 index 000000000..03c28eabf --- /dev/null +++ b/docs/docs/demoUsage/panels/settings.md @@ -0,0 +1,217 @@ +--- +title: 6. 设置面板详解 +sidebar_position: 2 +--- +# 设置器介绍 +## 展示区域 +设置器，又称为 Setter，主要展示在编辑器的右边区域，如下图： +![image.png](https://cdn.nlark.com/yuque/0/2022/png/2553587/1647695118402-ac146307-f6e2-4755-8be3-67278c505283.png#clientId=u547a37e3-c43d-4&crop=0&crop=0&crop=1&crop=1&from=paste&height=865&id=u3cac31de&margin=%5Bobject%20Object%5D&name=image.png&originHeight=1730&originWidth=3836&originalType=binary&ratio=1&rotation=0&showTitle=false&size=947162&status=done&style=none&taskId=u35373859-102e-4809-adfd-680b2dd4cda&title=&width=1918) +其中包含 属性、样式、事件、高级 + +- 属性：展示该物料常规的属性 +- 样式：展示该物料样式的属性 +- 事件：如果该物料有声明事件，则会出现事件面板，用于绑定事件。 +- 高级：两个逻辑相关的属性，**条件渲染**和**循环** + + + +## 设置器 +上述区域中是有多项设置器的，对于一个组件来说，每一项配置都对应一个设置器，比如我们的配置是一个文本，我们需要的是文本设置器，我们需要配置的是数字，我们需要的就是数字设置器。 +下图中的标题和按钮类型配置就分别是文本设置器和下拉框设置器。 +![image.png](https://cdn.nlark.com/yuque/0/2022/png/2553587/1647695118227-bf6caf7c-4974-4b35-8d6b-0c4969fc316d.png#clientId=u547a37e3-c43d-4&crop=0&crop=0&crop=1&crop=1&from=paste&height=407&id=u51d889e6&margin=%5Bobject%20Object%5D&name=image.png&originHeight=1460&originWidth=2120&originalType=binary&ratio=1&rotation=0&showTitle=false&size=489840&status=done&style=none&taskId=u35d4519f-b82d-43c4-9eb4-bd44e6d67b1&title=&width=591) +我们提供了常用的设置器作为内置设置器，也提供了定制能力帮助大家开发特定需求的设置器。 +# 内置设置器 +| **预置 Setter** | **用途** | +| --- | --- | +| StringSetter | 短文本型数据设置器，不可换行 | +| NumberSetter | 数值型数据设置器， | +| BoolSetter | 布尔型数据设置器， | +| SelectSetter | 枚举型数据设置器，采用下拉的形式展现 | +| VariableSetter | 变量型数据设置器， | +| RadioGroupSetter | 枚举型数据设置器，采用tab选择的形式展现 | +| TextAreaSetter | 长文本型数据设置器，可换行 | +| DateSetter | 日期型数据设置器 | +| TimePicker | 时间型数据设置器 | +| DateYearSetter | 日期型-年数据设置器 | +| DateMonthSetter | 日期型-月数据设置器 | +| DateRangeSetter | 日期型数据设置器，可选择时间区间 | +| EventsSetter | 事件绑定设置器 | +| ColorSetter | 颜色设置器 | +| JsonSetter | json型数据设置器 | +| StyleSetter | 样式设置器 | +| ClassNameSetter | 样式名设置器 | +| FunctionSetter | 函数型数据设置器 | +| MixedSetter | 混合型数据设置器 | +| SlotSetter | 节点型数据设置器 | +| ArraySetter | 列表数组行数据设置器 | +| ObjectSetter | 对象数据设置器，一般内嵌在ArraySetter中 | + + +# 设置器定制 +## 编写 AltStringSetter +我们编写一个简单的 Setter，这里我们编写的 Setter 是 AltStringSetter。代码如下： +```javascript +import * as React from "react"; +import { Input } from "@alifd/next"; + +import "./index.scss"; +interface AltStringSetterProps { + // 当前值 + value: string; + // 默认值 + defaultValue: string; + // setter唯一输出 + onChange: (val: string) => void; + // AltStringSetter 特殊配置 + placeholder: string; +} +export default class AltStringSetter extends React.PureComponent { + componentDidMount() { + const { onChange, value, defaultValue } = this.props; + if (value == undefined && defaultValue) { + onChange(defaultValue); + } + } + + // 声明Setter的title + static displayName = 'AltStringSetter'; + + render() { + const { onChange, value, placeholder } = this.props; + return ( + onChange(val)} + > + ); + } +} +``` + +### setter 和 setter/plugin 之间的联动 +我们采用 emit 来进行相互之前的通信，首先我们在 A setter 中进行事件注册： +```javascript +import { event } from '@ali/lowcode-engine'; + +componentDidMount() { + // 这里由于面板上会有多个setter，这里我用field.id来标记setter名 + this.emitEventName = `${SETTER_NAME}-${this.props.field.id}`; + event.on(`${this.emitEventName}.bindEvent`, this.bindEvent) +} + +bindEvent = (eventName) => { + // do someting +} + +componentWillUnmount() { + // setter是以实例为单位的，每个setter注销的时候需要把事件也注销掉，避免事件池过多 + event.off(`${this.emitEventName}.bindEvent`, this.bindEvent) +} +``` +在 B setter 中触发事件，来完成通信： +```javascript +import { event } from '@ali/lowcode-engine'; + +bindFunction = () => { + const { field, value } = this.props; + // 这里展示的和插件进行通信,事件规则是插件名+方法 + event.emit('eventBindDialog.openDialog', field.name, this.emitEventName); +} +``` +### 修改同级 props 的其他属性值 +setter 本身只影响其中一个 props 的值，如果需要影响其他组件的 props 的值，需要使用 field 的 props： +```javascript +bindFunction = () => { + const { field, value } = this.props; + const propsField = field.parent; + // 获取同级其他属性showJump的值 + const otherValue = propsField.getPropValue('showJump'); + // set同级其他属性showJump的值 + propsField.setPropValue('showJump', false); +} +``` +## 注册 AltStringSetter +我们需要在低代码引擎中注册 Setter，这样就可以通过 AltStringSetter 的名字在物料中使用了。 +```javascript +import AltStringSetter from './AltStringSetter'; +import { setters } from '@alilc/lowcode-engine'; +setters.registerSetter({ + AltStringSetter: { + component: AltStringSetter, + } +}); +``` +## 物料中使用 +我们需要将目标组件的属性值类型值配置到物料资源配置文件中，例如 `packages/demo/public/assets.json`  +其中核心配置如下： +```json +{ + "props": { + "isExtends": true, + "override": [ + { + "name": "type", + "setter": "AltStringSetter" + } + ] + } +} +``` +在物料中的完整配置如下： +```json +{ + "componentName": "Message", + "title": "Message", + "docUrl": "", + "screenshot": "", + "npm": { + "package": "@alifd/next", + "version": "1.19.18", + "exportName": "Message", + "main": "src/index.js", + "destructuring": true, + "subName": "" + }, + "props": [ + { + "name": "title", + "propType": "string", + "description": "标题", + "defaultValue": "标题" + }, + { + "name": "type", + "propType": { + "type": "oneOf", + "value": [ + "success", + "warning", + "error", + "notice", + "help", + "loading" + ] + }, + "description": "反馈类型", + "defaultValue": "success" + } + + ], + + "configure": { + "props": { + "isExtends": true, + "override": [ + { + "name": "type", + "setter": "AltStringSetter" + } + ] + } + } +} +``` +### +# 小结 +本章介绍了设置器是什么，我们有哪些内置的设置器。以及当不满足设置器诉求时，我们如何定制一个设置器。 diff --git a/docs/docs/faq/faq001.md b/docs/docs/faq/faq001.md new file mode 100644 index 000000000..56305cf2d --- /dev/null +++ b/docs/docs/faq/faq001.md @@ -0,0 +1,6 @@ +--- +title: build-scripts 的使用文档 +sidebar_position: 1 +tags: [FAQ] +--- +build-scripts 是一个开源项目，详见 [https://github.com/ice-lab/build-scripts](https://github.com/ice-lab/build-scripts) diff --git a/docs/docs/faq/faq002.md b/docs/docs/faq/faq002.md new file mode 100644 index 000000000..45e1c0c50 --- /dev/null +++ b/docs/docs/faq/faq002.md @@ -0,0 +1,36 @@ +--- +title: 渲染唯一标识（key） +sidebar_position: 2 +tags: [FAQ] +--- +渲染唯一标识（key）和 React 中组件的 key 属性的原理是一致的，都是为了在渲染场景或者组件切换的场景中唯一标识一个组件。 + +你可以在组件右侧配置面板的「高级」中看到此配置项，该配置项一般配合「是否渲染」和「循环」功能使用。 +![image.png](https://cdn.nlark.com/yuque/0/2022/png/110793/1659076591507-f37841b4-a3c2-4c87-b875-5f0458b2a3d2.png#clientId=u87aade85-8350-4&crop=0&crop=0&crop=1&crop=1&height=348&id=dbojA&margin=%5Bobject%20Object%5D&name=image.png&originHeight=696&originWidth=560&originalType=binary&ratio=1&rotation=0&showTitle=false&size=102096&status=done&style=none&taskId=ub4a95aaa-8630-47ad-b0e3-881b5d54ac9&title=&width=280) + +## 以下场景必需设置「渲染唯一标识」 +#### 场景一：同类组件切换 +以下场景中，当「爱好」选择「游戏」时显示「最喜欢的游戏」，选择「运动」时显示「最喜欢的运动」 +![image.png](https://cdn.nlark.com/yuque/0/2022/png/110793/1659076591520-b2e1121b-3f4e-4c7c-88c8-82a761b85fe0.png#clientId=u87aade85-8350-4&crop=0&crop=0&crop=1&crop=1&height=294&id=Xr3NB&margin=%5Bobject%20Object%5D&name=image.png&originHeight=588&originWidth=1560&originalType=binary&ratio=1&rotation=0&showTitle=false&size=78723&status=done&style=none&taskId=u59b975eb-93a1-4c8a-bb3b-17ef8b7005c&title=&width=780) + +配置方式如下： + +1. 增加变量数据源：hobby +2. 「最喜欢的游戏」表单标识设置为 game，「是否渲染」绑定变量「state.hobby === '游戏'」 + +![image.png](https://cdn.nlark.com/yuque/0/2022/png/110793/1659076591653-27fac7ab-bba0-4965-a706-d0c1c867f539.png#clientId=u87aade85-8350-4&crop=0&crop=0&crop=1&crop=1&height=369&id=f8kif&margin=%5Bobject%20Object%5D&name=image.png&originHeight=738&originWidth=2164&originalType=binary&ratio=1&rotation=0&showTitle=false&size=306076&status=done&style=none&taskId=ub6da537a-3bc7-450d-b640-dc0db8defac&title=&width=1082) + +3. 「最喜欢的运动」表单标识设置为 sport，「是否渲染」绑定变量「state.hobby === '运动'」 +4. 「爱好」设置 onChange 动作 + +![image.png](https://cdn.nlark.com/yuque/0/2022/png/110793/1659076591442-2903e2b2-4688-4a5e-98de-7df9933710b5.png#clientId=u87aade85-8350-4&crop=0&crop=0&crop=1&crop=1&height=97&id=hR3Pp&margin=%5Bobject%20Object%5D&name=image.png&originHeight=194&originWidth=892&originalType=binary&ratio=1&rotation=0&showTitle=false&size=53803&status=done&style=none&taskId=ue8919283-2e5f-46a8-9d6b-942c03f8482&title=&width=446) + +5. 「提交」按钮绑定 onClick 动作 + +![image.png](https://cdn.nlark.com/yuque/0/2022/png/110793/1659076591508-ddd3c767-bf22-4dae-a006-5e6c4e0ea956.png#clientId=u87aade85-8350-4&crop=0&crop=0&crop=1&crop=1&height=67&id=VWtPz&margin=%5Bobject%20Object%5D&name=image.png&originHeight=134&originWidth=750&originalType=binary&ratio=1&rotation=0&showTitle=false&size=46519&status=done&style=none&taskId=ud6a5d2b0-481b-4bbb-8fe3-8622e2ebfb3&title=&width=375) + +按以上配置（不配置渲染唯一标识），确实可以实现切换爱好时下方的文本框切换，但在提交数据时会发现，即使选择了「运动」，提交的时候 sport 字段是「最喜欢的游戏」的值。 + +原因：在进行文本框组件切换时，由于没有设置 key，底层会「复用」切换之前的组件 + +以上场景只需要给两个组件配置「渲染唯一标识」即可。 diff --git a/docs/docs/faq/faq003.md b/docs/docs/faq/faq003.md new file mode 100644 index 000000000..96e01c1fd --- /dev/null +++ b/docs/docs/faq/faq003.md @@ -0,0 +1,32 @@ +--- +title: 点击事件如何添加参数 +sidebar_position: 3 +tags: [FAQ] +--- +背景： + +- [Antd Table 下 button 点击事件怎么拿到行数据？](https://github.com/alibaba/lowcode-engine/issues/341) +## 方式1 +![image.png](https://cdn.nlark.com/yuque/0/2022/png/2622706/1657593243427-fb5641b2-4987-475e-88ab-c68d2085edbd.png#clientId=u31b40d04-56f2-4&crop=0&crop=0&crop=1&crop=1&from=paste&height=563&id=u5167bf33&margin=%5Bobject%20Object%5D&name=image.png&originHeight=1126&originWidth=3342&originalType=binary&ratio=1&rotation=0&showTitle=false&size=225551&status=done&style=none&taskId=ud1b89a63-4b6a-4986-a6df-2a463fcf08a&title=&width=1671) + +参考 fusion protable ， 将操作列直接耦合 button 组件，因为 col.render 函数能拿到 行数据record，那么 pro-table 组件封装的时候，就可以在渲染操作列按钮的时候，将 col.render 参数透传给 button 组件 + +## 方式2 +slot + 扩展参数 + +![image.png](https://cdn.nlark.com/yuque/0/2022/png/2622706/1657593299698-9628db14-7b48-4c06-9e6f-bda637c209a8.png#clientId=u31b40d04-56f2-4&crop=0&crop=0&crop=1&crop=1&from=paste&height=574&id=u20b07439&margin=%5Bobject%20Object%5D&name=image.png&originHeight=1148&originWidth=3284&originalType=binary&ratio=1&rotation=0&showTitle=false&size=232140&status=done&style=none&taskId=ubc80905d-0607-4e73-9386-5dde706e572&title=&width=1642) + +将扩展参数写成： +```json +{ + record: this.record, + index: this.index +} +``` + +那事件处理函数的第二个参数即可得到： +```json +onClick_new_new(...args){ + console.log(args) +} +``` diff --git a/docs/docs/faq/faq004.md b/docs/docs/faq/faq004.md new file mode 100644 index 000000000..67431c0e5 --- /dev/null +++ b/docs/docs/faq/faq004.md @@ -0,0 +1,59 @@ +--- +title: 最小渲染单元配置 +sidebar_position: 4 +tags: [FAQ] +--- +## 背景 +在低代码引擎画布中，每一个节点的更新是**增量更新**机制。也就是通过 API 监听到组件的参数配置变化的时候，只更新该节点。 + +一些场景下，父组件需要在子组件的属性变化，获取新的子组件的属性值，也就是从父组件开始渲染。 +例如：父组件需要强制修改 children props 值。示例代码如下： +``` +React.Children.forEach(children, (child: React.ReactElement) => { + // 子元素的参数只有 behavior，且 behavior 为 'READONLY'; + const newChild = React.cloneElement(child, { + behavior: 'READONLY' + }); +}) +``` + +**对于这种场景，需要配置其为“最小渲染单元”****。**即： +> **最小渲染单元下的组件渲染和更新都从单元的根节点开始渲染和更新。如果嵌套了多层最小渲染单元，渲染会从最外层的最小渲染单元开始渲染。** + + +### 组件能力配置 component +| **字段** | **用途** | **类型** | +| --- | --- | --- | +| isContainer(A) | 是否容器组件 | Boolean | +| **isMinimalRenderUnit** | **默认值：false** +**是否是最小渲染单元** | **Boolean** | +| ... | | | + +#### 配置示例 +##### 标准配置文件 +configure.component.isMinimalRenderUnit +```json +{ + "componentName": "Table", + "title": "表格", + "category": "数据展示", + "props": [], + "configure": { + "supports": { + }, + "props": [], + "component": { + // 添加如下配置 + "isMinimalRenderUnit": true + }, + "combined": [] + }, + "snippets": [], + "npm": {} +} +``` +## 更新机制说明 + +1. 没有任何组件被标识为**最小渲染单元**，则是每个组件都伴随自身属性变更而重新渲染； +2. 将根组件标识为**最小渲染单元**，则是整个页面重新渲染； +3. 组件树的分支节点被标识为**最小渲染单元**，则分支节点之下（包括自身）节点属性变更，触发分支节点整体的重新渲染；（若有多个**最小渲染单元**在同一条路径上，从最外层的**最小渲染单元**开始渲染） diff --git a/docs/docs/faq/faq005.md b/docs/docs/faq/faq005.md new file mode 100644 index 000000000..03efb55b4 --- /dev/null +++ b/docs/docs/faq/faq005.md @@ -0,0 +1,23 @@ +--- +title: 如何通过 this.utils 使用第三方工具扩展 +sidebar_position: 5 +tags: [FAQ] +--- +## 设计器 +### 通过引擎 API 配置 +[https://www.yuque.com/lce/doc/dffghx](https://www.yuque.com/lce/doc/dffghx) + +### 通过资产包 + +![image.png](https://cdn.nlark.com/yuque/0/2022/png/2622706/1657273720962-70045da1-7559-4f7f-a3da-35759778066c.png#averageHue=%231f221e&clientId=ueb9290e1-769e-4&crop=0&crop=0&crop=1&crop=1&errorMessage=unknown%20error&from=paste&height=394&id=u698ffae7&margin=%5Bobject%20Object%5D&name=image.png&originHeight=788&originWidth=806&originalType=binary&ratio=1&rotation=0&showTitle=false&size=175357&status=error&style=none&taskId=u2ed6a3cd-5ec4-4b84-a3c0-fd3379b7019&title=&width=403) + +就可以在引擎代码中访问到 moment +![image.png](https://cdn.nlark.com/yuque/0/2022/png/2622706/1657273737110-6c064e4c-6435-456a-b168-480058b14da8.png#averageHue=%23fdfdfc&clientId=ueb9290e1-769e-4&crop=0&crop=0&crop=1&crop=1&errorMessage=unknown%20error&from=paste&height=126&id=u4ec5fba0&margin=%5Bobject%20Object%5D&name=image.png&originHeight=252&originWidth=1248&originalType=binary&ratio=1&rotation=0&showTitle=false&size=128347&status=error&style=none&taskId=udd229103-04e3-4fc5-9fba-9115354bb9d&title=&width=624) + +PS：需要在 packages 中有相关的资源配置，例如： +![image.png](https://cdn.nlark.com/yuque/0/2022/png/2622706/1657273863884-2068444e-5653-4b25-ba3a-fd192409fbaa.png#averageHue=%231f1f1d&clientId=ueb9290e1-769e-4&crop=0&crop=0&crop=1&crop=1&errorMessage=unknown%20error&from=paste&height=210&id=ud2a4b3c6&margin=%5Bobject%20Object%5D&name=image.png&originHeight=420&originWidth=1322&originalType=binary&ratio=1&rotation=0&showTitle=false&size=113099&status=error&style=none&taskId=u7ba0f438-9c39-4398-b048-9d0556e2079&title=&width=661) + +否则在画布中可能会访问不到对应的资源。 + +## 预览态 +参考：[https://www.yuque.com/lce/doc/nhilce#appHelper](https://www.yuque.com/lce/doc/nhilce#appHelper) diff --git a/docs/docs/faq/faq006.md b/docs/docs/faq/faq006.md new file mode 100644 index 000000000..0553d5122 --- /dev/null +++ b/docs/docs/faq/faq006.md @@ -0,0 +1,6 @@ +--- +title: 如何通过 API 手动调用数据源请求 +sidebar_position: 6 +tags: [FAQ] +--- +参考：[https://www.yuque.com/lce/doc/erckcn](https://www.yuque.com/lce/doc/erckcn) \ No newline at end of file diff --git a/docs/docs/faq/faq007.md b/docs/docs/faq/faq007.md new file mode 100644 index 000000000..175d8c73f --- /dev/null +++ b/docs/docs/faq/faq007.md @@ -0,0 +1,9 @@ +--- +title: 设置面板中的高级tab如何配置 +sidebar_position: 7 +tags: [FAQ] +--- +![93DC003C-D9A1-4F4F-98A1-F22C0A89EA92.png](https://cdn.nlark.com/yuque/0/2022/png/1053439/1657161085153-a26657ae-2c6e-4124-b9ab-6f8cf8126d1f.png#clientId=u300df630-5bbe-4&crop=0&crop=0&crop=1&crop=1&from=ui&height=591&id=u2ff7824e&margin=%5Bobject%20Object%5D&name=93DC003C-D9A1-4F4F-98A1-F22C0A89EA92.png&originHeight=1714&originWidth=960&originalType=binary&ratio=1&rotation=0&showTitle=false&size=107040&status=done&style=none&taskId=ub377dc1d-db5a-4234-980f-66f7143950d&title=&width=331) + +默认这个tab下的内容为引擎内置，如需要定制，可以使用以下API +[https://lowcode-engine.cn/docV2/mu7lml#lIK37](https://lowcode-engine.cn/docV2/mu7lml#lIK37) diff --git a/docs/docs/faq/faq008.md b/docs/docs/faq/faq008.md new file mode 100644 index 000000000..c64a09ae2 --- /dev/null +++ b/docs/docs/faq/faq008.md @@ -0,0 +1,7 @@ +--- +title: 某某npm包对应的源码在哪里？ +sidebar_position: 8 +tags: [FAQ] +--- + +详见 [NPM包对应源码位置汇总](https://www.yuque.com/lce/doc/ngm44i) \ No newline at end of file diff --git a/docs/docs/faq/faq009.md b/docs/docs/faq/faq009.md new file mode 100644 index 000000000..131dcba6f --- /dev/null +++ b/docs/docs/faq/faq009.md @@ -0,0 +1,74 @@ +--- +title: 物料出现 Component Not Found 相关报错 +sidebar_position: 9 +tags: [FAQ] +--- +## 预览态，antd 资产包按顺序加载，但是没有按顺序执行 +资产包按顺序加载，但是没有按顺序执行，导致部分 js 执行的时候，依赖的资源没有准备好，报错了。 +传给 @alilc/lowcode-react-renderer 的 components 值为空。 + +**解决方案** +LowCodeEngine 升级到 1.0.8 +> 相关PR：[https://github.com/alibaba/lowcode-engine/pull/383](https://github.com/alibaba/lowcode-engine/pull/383) + + +## 编辑态，snippets 和注入组件不对应 +1.在控制台中输入 +```json +AliLowCodeEngine.material.componentsMap +``` +查看物料配置是否正常。 + +![image.png](https://cdn.nlark.com/yuque/0/2022/png/2622706/1655277296065-40eeae64-1323-4f7d-89c3-bc48c928aca4.png#clientId=u21fd51ec-6ae9-4&crop=0&crop=0&crop=1&crop=1&from=paste&height=408&id=u21239467&margin=%5Bobject%20Object%5D&name=image.png&originHeight=816&originWidth=1640&originalType=binary&ratio=1&rotation=0&showTitle=false&size=379372&status=done&style=none&taskId=u12a736de-695e-45b9-817b-0f9f6b3a601&title=&width=820) + +如果正常继续。 +LowCodeEngine 需要升级到 1.0.10 +```json +AliLowCodeEngine.project.simulator.renderer.components +``` +看看对应的物料是否存在，如果不存在，排查物料问题。 + +2.选中组件，在控制台中输入 +```json +AliLowCodeEngine.project.currentDocument.selection.getNodes()[0].exportSchema('render') +``` +查看 componentName 是否匹配。 + +3.调用 rerender 方法 +```json +AliLowCodeEngine.project.simulator.rerender() +``` +看一下问题是否恢复。 + +## 排查物料问题 +找到对应组件的资产包，比如下图的资产包。 +```json +{ + "package": "@yingzhi8/lowcode-public-package", + "version": "0.1.2", + "library": "BizComps", + "urls": [ + "https://unpkg.com/@yingzhi8/lowcode-public-package@0.1.2/build/lowcode/render/default/view.js", + "https://unpkg.com/@yingzhi8/lowcode-public-package@0.1.2/build/lowcode/render/default/view.css" + ], + "editUrls": [ + "https://unpkg.com/@yingzhi8/lowcode-public-package@0.1.2/build/lowcode/view.js", + "https://unpkg.com/@yingzhi8/lowcode-public-package@0.1.2/build/lowcode/view.css" + ], + "advancedUrls": { + "default": [ + "https://unpkg.com/@yingzhi8/lowcode-public-package@0.1.2/build/lowcode/render/default/view.js", + "https://unpkg.com/@yingzhi8/lowcode-public-package@0.1.2/build/lowcode/render/default/view.css" + ] + }, + "advancedEditUrls": {} +} +``` + +### 查看 urls 是否加载 +通过查看控制台，看加载的 urls +### library 配置是否正确 +library 是可以在画布上访问到全局变量，确定 library 是否正确，在控制台输入： +```json +AliLowCodeEngine.project.simulator.contentWindow.${library} +``` diff --git a/docs/docs/faq/faq010.md b/docs/docs/faq/faq010.md new file mode 100644 index 000000000..e98ac7f68 --- /dev/null +++ b/docs/docs/faq/faq010.md @@ -0,0 +1,18 @@ +--- +title: 插件面板如何调整位置 +sidebar_position: 10 +tags: [FAQ] +--- +使用 index 配置来定义位置，内置的默认都是 0 +```json +AliLowCodeEngine.skeleton.add({ + area: 'leftArea', + type: 'PanelDock', + name: 'xxx', + content: () => 'xxx', + index: -1, // 使用 index 来定义位置，内置的默认都是 0 + props: { icon: () => 'x' /* ReactElement 也可以 */ }, +}); +``` +这里设置 index 为负数，可以将其调整到第一的位置。 +![image.png](https://cdn.nlark.com/yuque/0/2022/png/2622706/1653964459415-694283f6-9c5f-4143-b6d4-51b5aa37f719.png#clientId=uaed53506-efef-4&crop=0&crop=0&crop=1&crop=1&from=paste&height=579&id=u99009edf&margin=%5Bobject%20Object%5D&name=image.png&originHeight=1158&originWidth=1614&originalType=binary&ratio=1&rotation=0&showTitle=false&size=390356&status=done&style=none&taskId=ue153a8c6-13b0-48fa-bfe9-a0d9f7b6cc3&title=&width=807) diff --git a/docs/docs/faq/faq011.md b/docs/docs/faq/faq011.md new file mode 100644 index 000000000..793ff7af1 --- /dev/null +++ b/docs/docs/faq/faq011.md @@ -0,0 +1,29 @@ +--- +title: 如何获取物料当前处于编辑态还是渲染态 +sidebar_position: 11 +tags: [FAQ] +--- +## 简单场景 +可以利用 props.__designMode +![image.png](https://cdn.nlark.com/yuque/0/2022/png/2622706/1653962601596-46e21531-9b8c-45bd-84a7-7522856eb3c9.png#clientId=u8f8d6439-2532-4&crop=0&crop=0&crop=1&crop=1&from=paste&height=220&id=u4d7df210&margin=%5Bobject%20Object%5D&name=image.png&originHeight=440&originWidth=1616&originalType=binary&ratio=1&rotation=0&showTitle=false&size=232329&status=done&style=none&taskId=u85deaa53-ef14-4ce2-a5a2-ac201aa60f5&title=&width=808) + +设计态中，__designMode 值为 "design" + +渲染态中，__designMode 没有设置值 + +## 复杂场景 +在资产包里定义 editUrls +![image.png](https://cdn.nlark.com/yuque/0/2022/png/2622706/1653962648722-ac8ff758-a0c3-4323-8312-11ac9b511ecf.png#clientId=u8f8d6439-2532-4&crop=0&crop=0&crop=1&crop=1&from=paste&height=269&id=uad79aeaf&margin=%5Bobject%20Object%5D&name=image.png&originHeight=538&originWidth=1590&originalType=binary&ratio=1&rotation=0&showTitle=false&size=257391&status=done&style=none&taskId=u3d8d556b-2da7-40b4-b7e6-cd3600cfbd4&title=&width=795) + +### editUrls +在 lowcode/xx/ 下新建一个 view.tsx +![image.png](https://cdn.nlark.com/yuque/0/2022/png/2622706/1653971463822-3335e539-6b97-43a7-adf9-cba221a68d87.png#clientId=u89265c24-4294-4&crop=0&crop=0&crop=1&crop=1&from=paste&height=77&id=u466ed474&margin=%5Bobject%20Object%5D&name=image.png&originHeight=154&originWidth=598&originalType=binary&ratio=1&rotation=0&showTitle=false&size=31756&status=done&style=none&taskId=u1f7eeec2-323c-45c7-a1f7-e18bfa3a1db&title=&width=299) + +再执行 +```json +npm run lowcode:build +``` + +之后，build/lowcode 目录下既有 view.js，可作为 editUrls 配置在资产包中。 + +![image.png](https://cdn.nlark.com/yuque/0/2022/png/2622706/1653971523747-c15e63e6-9fb7-481e-bf5b-c4bd6cb25927.png#clientId=u89265c24-4294-4&crop=0&crop=0&crop=1&crop=1&from=paste&height=493&id=ucaf08028&margin=%5Bobject%20Object%5D&name=image.png&originHeight=986&originWidth=1082&originalType=binary&ratio=1&rotation=0&showTitle=false&size=235573&status=done&style=none&taskId=ue21c1ab4-0d1b-49fb-8889-b7210b90d41&title=&width=541) diff --git a/docs/docs/faq/faq012.md b/docs/docs/faq/faq012.md new file mode 100644 index 000000000..6c0e61db0 --- /dev/null +++ b/docs/docs/faq/faq012.md @@ -0,0 +1,90 @@ +--- +title: Procode 物料如何调用数据源方法 +sidebar_position: 12 +tags: [FAQ] +--- +## 解决方案 +给物料插入如下配置，可以默认给物料提供 reloadDataSource 的参数。 +```json +{ + title: { + label: { + type: 'i18n', + 'en-US': 'reloadDataSource', + 'zh-CN': 'reloadDataSource', + }, + }, + name: 'reloadDataSource', + setter: 'StringSetter', + initialValue: () => ( + { + "type": "JSFunction", + "value": "function(){ return this.reloadDataSource; }" + } + ), +}, +``` + +在物料组件中，即可掉用如下代码来获取到相关方法。 +```json +const reloadDataSource = props.getReloadDataSource() +``` + +## FAQ +### 希望该配置在配置面板中不展示 +在配置中加上 +```json +condition: () => false, +``` + +完整示例 +```json +{ + title: { + label: { + type: 'i18n', + 'en-US': 'reloadDataSource', + 'zh-CN': 'reloadDataSource', + }, + }, + name: 'reloadDataSource', + setter: 'StringSetter', + condition: () => false, + initialValue: () => ( + { + "type": "JSFunction", + "value": "function(){ return this.reloadDataSource; }" + } + ), +}, +``` + +### 配置没有生效 +查看组件中的 schema，对应的配置是否已经正确设置。 +![image.png](https://cdn.nlark.com/yuque/0/2022/png/2622706/1653894934869-963be13a-1d6a-458a-a1e1-fd21fa9fc765.png#clientId=uc4e9cec0-362f-4&crop=0&crop=0&crop=1&crop=1&from=paste&height=577&id=u956bc36a&margin=%5Bobject%20Object%5D&name=image.png&originHeight=1154&originWidth=1046&originalType=binary&ratio=1&rotation=0&showTitle=false&size=339838&status=done&style=none&taskId=uf64dae1b-23e9-4444-ab20-9e5f17a5449&title=&width=523) + +没有正确设置上可能的原因是 +1.snippets 中没有默认值 +需要按照如下的代码中，加上默认的参数配置 +```json +const snippets: Snippet[] = [ + { + title: 'Field', + screenshot: '', + schema: { + componentName: 'ProField', + props: { + type: 'textarea', + value: '我是测试', + getReloadDataSource: { + "type": "JSFunction", + "value": "function(){ return this.reloadDataSource; }" + } + }, + }, + }, +]; +``` + +### 如何全局生效 +通过 [https://www.yuque.com/lce/doc/mu7lml#LRXhp](https://www.yuque.com/lce/doc/mu7lml#LRXhp) 来修改元数据信息，注意如果有 snippets 相关配置也需要修改相关的配置。 diff --git a/docs/docs/faq/faq013.md b/docs/docs/faq/faq013.md new file mode 100644 index 000000000..2d8f6f703 --- /dev/null +++ b/docs/docs/faq/faq013.md @@ -0,0 +1,22 @@ +--- +title: Modal 类组件 hidden 属性被强制设置 true +sidebar_position: 13 +tags: [FAQ] +--- +## 注意 +弹窗的正确弹出方式请参考：[https://www.yuque.com/lce/usage/ozsg2m](https://www.yuque.com/lce/usage/ozsg2m) +## 问题原因 +由于 hidden 属性，导致 Modal 组件在预览的时候不渲染，也就无法获取到实例。 +## 处理方式 +### 【推荐】升级到 Engine Verison 1.0.11 以上 +### 新增 save propsReducer +通过新增 Save 态的 propsReducer，将 hidden props 去掉。 +参考： +[https://github.com/alibaba/lowcode-demo/blob/main/src/sample-plugins/delete-hidden-transducer/index.ts](https://github.com/alibaba/lowcode-demo/blob/main/src/sample-plugins/delete-hidden-transducer/index.ts) + +### 导出 schema 使用 Save 态 +```typescript +import { TransformStage } from '@alilc/lowcode-types'; + +const schema = project.exportSchema(TransformStage.Save) +``` diff --git a/docs/docs/faq/faq014.md b/docs/docs/faq/faq014.md new file mode 100644 index 000000000..9c72b2a2a --- /dev/null +++ b/docs/docs/faq/faq014.md @@ -0,0 +1,20 @@ +--- +title: VERSION_PLACEHOLDER is not defined +sidebar_position: 14 +tags: [FAQ] +--- +# 问题原因 +由于 lowcode-engine 目前只提供 cdn 的使用方式。如果是自己创建的项目，遇到这个报错了，主要是因为将 npm 包打包进去了。 + +# 解决方案 + +## engine-demo 项目 +在项目的 externals 配置里加[一行配置](https://github.com/alibaba/lowcode-demo/blob/f8afad0df3190565caccc0a1dfd750dbf84c680f/build.json#L16) + +## 其他项目 +[相关文档](https://lowcode-engine.cn/docV2/start-with-lce#OMRA2) +### webpack +[https://webpack.docschina.org/configuration/externals/](https://webpack.docschina.org/configuration/externals/) + +### 使用文档 +待补充 diff --git a/docs/docs/faq/faq015.md b/docs/docs/faq/faq015.md new file mode 100644 index 000000000..02ca13915 --- /dev/null +++ b/docs/docs/faq/faq015.md @@ -0,0 +1,7 @@ +--- +title: 已有组件如何快速接入引擎 +sidebar_position: 15 +tags: [FAQ] +--- +你可以通过在线工具 「Parts造物」生产物料描述协议，然后使用到你的项目中去。 +文档地址：[https://www.yuque.com/lce/xhk5hf/qa9pbx](https://www.yuque.com/lce/xhk5hf/qa9pbx) diff --git a/docs/docs/faq/faq016.md b/docs/docs/faq/faq016.md new file mode 100644 index 000000000..bb72e17ec --- /dev/null +++ b/docs/docs/faq/faq016.md @@ -0,0 +1,19 @@ +--- +title: Cannot read property 'Icon' of Undefined +sidebar_position: 16 +tags: [FAQ] +--- +@alifd/next 是 React 画布下必须的资源，不能省略。 +需要在资产包中检查是否有下列代码： +```typescript +{ + "title": "fusion组件库", + "package": "@alifd/next", + "version": "1.23.0", + "urls": [ + "https://g.alicdn.com/code/lib/alifd__next/1.23.18/next.min.css", + "https://g.alicdn.com/code/lib/alifd__next/1.23.18/next-with-locales.min.js" + ], + "library": "Next" +}, +``` diff --git a/docs/docs/faq/faq017.md b/docs/docs/faq/faq017.md new file mode 100644 index 000000000..f2c7afa27 --- /dev/null +++ b/docs/docs/faq/faq017.md @@ -0,0 +1,11 @@ +--- +title: vue 画布支持说明 +sidebar_position: 17 +tags: [FAQ] +--- +#### 低代码引擎官方是否支持 Vue 画布 +短期没有支持的计划 + +#### 社区研发的 Vue 画布 +##### 肯耐珂萨团队实现的 Vue 画布 +github：[https://github.com/KNXCloud/lowcode-engine-vue](https://github.com/KNXCloud/lowcode-engine-vue) diff --git a/docs/docs/faq/faq018.md b/docs/docs/faq/faq018.md new file mode 100644 index 000000000..a7b79e44d --- /dev/null +++ b/docs/docs/faq/faq018.md @@ -0,0 +1,10 @@ +--- +title: 是否可以生成 Vue 页面代码？ +sidebar_position: 18 +tags: [FAQ] +--- +低代码引擎在架构上是和具体语言无关的，通过一定的扩展和插件是可以生成 Vue 页面代码的。 +如果只是用现有的基于 React 的 fusion 物料来搭建，只是在最终出码的时候生成 Vue 页面代码，那您需要准备一套和 fusion 兼容的 vue 物料，并定制个出码方案，将[下面的一些出码插件](https://github.com/alibaba/lowcode-engine/blob/main/modules/code-generator/src/solutions/icejs.ts)替换成生成 Vue 框架的即可： +![image.png](https://cdn.nlark.com/yuque/0/2022/png/263300/1648542644942-c019ffd4-1312-4d31-ad61-4e487a47df71.png#clientId=ue0e8d3cc-f9f8-4&crop=0&crop=0&crop=1&crop=1&from=paste&height=517&id=u64b1f996&margin=%5Bobject%20Object%5D&name=image.png&originHeight=1368&originWidth=974&originalType=binary&ratio=1&rotation=0&showTitle=false&size=771387&status=done&style=none&taskId=u51022017-4248-49b8-b8b3-be9a7bb48fb&title=&width=368) +详细定制方案可以参考下[《自定义出码》](https://lowcode-engine.cn/docV2/cplfv0#857ba793)。 +如果您希望在搭建的时候也使用 Vue 的物料，则还需要扩展定制入料、画布和渲染器等模块，详细方案请参考下[《扩展低代码编辑器》](https://lowcode-engine.cn/docV2/srdo3s) diff --git a/docs/docs/faq/faq019.md b/docs/docs/faq/faq019.md new file mode 100644 index 000000000..9808360d1 --- /dev/null +++ b/docs/docs/faq/faq019.md @@ -0,0 +1,10 @@ +--- +title: windows 下运行出现报错 +sidebar_position: 19 +tags: [FAQ] +--- +由于阿里内部研发人员没有 windows 开发的诉求，windows 环境下相关的技术兼容短期内暂时没有支持计划。 + +辛苦使用 [WSL](https://docs.microsoft.com/zh-cn/windows/wsl/install) 在 windows 下进行低代码引擎相关的开发。 + +如果可以的话，欢迎大佬们提 PR 对 windows 开发环境进行兼容方面的支持。 diff --git a/docs/docs/faq/faq020.md b/docs/docs/faq/faq020.md new file mode 100644 index 000000000..641e64eb1 --- /dev/null +++ b/docs/docs/faq/faq020.md @@ -0,0 +1,44 @@ +--- +title: Can't import the named export from non ECMAScript module +sidebar_position: 20 +tags: [FAQ] +--- +如果您是自己配置的引擎打包，那么可能会遇到这个问题。 + +![image.png](https://cdn.nlark.com/yuque/0/2022/png/242652/1644896737710-a746e04d-bf4a-40a3-b917-a09235363c81.png#clientId=u627d7b4e-5fe3-4&crop=0&crop=0&crop=1&crop=1&from=paste&height=492&id=u06a9f219&margin=%5Bobject%20Object%5D&name=image.png&originHeight=984&originWidth=1912&originalType=binary&ratio=1&rotation=0&showTitle=false&size=1210174&status=done&style=none&taskId=u2b829db8-026d-472a-baf4-d4660fb5a4a&title=&width=956) + +问题的根源是 code-editor 插件运行时直接依赖了 babel 来完成 jsx 编译，babel 从 7.17.0 开始依赖了使用 ESM 编写的 @ampproject/remapping@2.1.0。如果打包工具无法正确处理 ESM，则可能报错。 + +解决方案 1：锁定 babel 版本 + +如果您使用了 yarn，那么可以在 package.json 中： + +```typescript +"resolutions": { + "@babel/core": "~7.16.7", + "@babel/parser": "~7.16.7", + "@babel/preset-env": "~7.16.7", + "@babel/preset-react": "~7.16.7", + "@babel/standalone": "~7.16.7", + "@babel/traverse": "~7.16.7", + "@babel/types": "~7.16.7" +} +``` + +解决方案 2：编译层面配置。本例使用 build-script 配置，您可以用类似方法来配置您的 webpack： + +```typescript +module.exports = ({ onGetWebpackConfig }) => { + // see: https://github.com/ice-lab/build-scripts#%E6%8F%92%E4%BB%B6%E5%BC%80%E5%8F%91 + onGetWebpackConfig((config) => { + config.module // fixes https://github.com/graphql/graphql-js/issues/1272 + .rule('mjs$') + .test(/\.mjs$/) + .include + .add(/node_modules/) + .end() + .type('javascript/auto'); + return config; + }); +}; +``` diff --git a/docs/docs/faq/index.md b/docs/docs/faq/index.md new file mode 100644 index 000000000..ed31bad28 --- /dev/null +++ b/docs/docs/faq/index.md @@ -0,0 +1,7 @@ +--- +title: FAQ 概述 +sidebar_position: 1 +tags: [FAQ] +--- + +不定期将社区常见问题及答案维护到此处 \ No newline at end of file diff --git a/docs/docs/guide/appendix/_category_.json b/docs/docs/guide/appendix/_category_.json new file mode 100644 index 000000000..c5c96d856 --- /dev/null +++ b/docs/docs/guide/appendix/_category_.json @@ -0,0 +1,6 @@ +{ + "label": "附录", + "position": 5, + "collapsed": false, + "collapsible": true +} diff --git a/docs/docs/guide/appendix/glossary.md b/docs/docs/guide/appendix/glossary.md new file mode 100644 index 000000000..e044f3e74 --- /dev/null +++ b/docs/docs/guide/appendix/glossary.md @@ -0,0 +1,5 @@ +--- +title: 名词解释 +sidebar_position: 0 +--- +![glossary](https://cdn.nlark.com/yuque/0/2022/jpeg/2622706/1648103397469-00227a70-e7ab-4a90-8378-c4da977250b2.jpeg) diff --git a/docs/docs/guide/appendix/metaSpec.md b/docs/docs/guide/appendix/metaSpec.md new file mode 100644 index 000000000..6adcc5907 --- /dev/null +++ b/docs/docs/guide/appendix/metaSpec.md @@ -0,0 +1,7 @@ +--- +title: 搭建组件协议结构 +sidebar_position: 1 +--- +完整协议请查看：[http://lowcode-engine.cn/material](http://lowcode-engine.cn/material) + +![](https://cdn.nlark.com/yuque/0/2022/jpeg/2622706/1646040400808-9a4a4d7d-6ad2-43be-8c97-d88f0cab7cc6.jpeg) diff --git a/docs/docs/guide/appendix/npms.md b/docs/docs/guide/appendix/npms.md new file mode 100644 index 000000000..9334140f4 --- /dev/null +++ b/docs/docs/guide/appendix/npms.md @@ -0,0 +1,49 @@ +--- +title: NPM包对应源码位置汇总 +sidebar_position: 3 +--- +| 包名 | 仓库 | 路径 | +| --- | --- | --- | +| @alilc/lowcode-code-generator | [https://github.com/alibaba/lowcode-engine](https://github.com/alibaba/lowcode-engine) | modules/code-generator | +| @alilc/lowcode-material-parser | [https://github.com/alibaba/lowcode-engine](https://github.com/alibaba/lowcode-engine) | modules/material-parser | +| @alilc/lowcode-designer | [https://github.com/alibaba/lowcode-engine](https://github.com/alibaba/lowcode-engine) | packages/designer | +| @alilc/lowcode-editor-core | [https://github.com/alibaba/lowcode-engine](https://github.com/alibaba/lowcode-engine) | packages/editor-core | +| @alilc/lowcode-editor-skeleton | [https://github.com/alibaba/lowcode-engine](https://github.com/alibaba/lowcode-engine) | packages/editor-skeleton | +| @alilc/lowcode-engine | [https://github.com/alibaba/lowcode-engine](https://github.com/alibaba/lowcode-engine) | packages/engine | +| @alilc/lowcode-plugin-designer | [https://github.com/alibaba/lowcode-engine](https://github.com/alibaba/lowcode-engine) | packages/plugin-designer | +| @alilc/lowcode-plugin-outline-pane | [https://github.com/alibaba/lowcode-engine](https://github.com/alibaba/lowcode-engine) | packages/plugin-outline-pane | +| @alilc/lowcode-rax-renderer | [https://github.com/alibaba/lowcode-engine](https://github.com/alibaba/lowcode-engine) | packages/rax-renderer | +| @alilc/lowcode-rax-simulator-renderer | [https://github.com/alibaba/lowcode-engine](https://github.com/alibaba/lowcode-engine) | packages/rax-simulator-renderer | +| @alilc/lowcode-react-renderer | [https://github.com/alibaba/lowcode-engine](https://github.com/alibaba/lowcode-engine) | packages/react-renderer | +| @alilc/lowcode-react-simulator-renderer | [https://github.com/alibaba/lowcode-engine](https://github.com/alibaba/lowcode-engine) | packages/react-simulator-renderer | +| @alilc/lowcode-renderer-core | [https://github.com/alibaba/lowcode-engine](https://github.com/alibaba/lowcode-engine) | packages/renderer-core | +| @alilc/lowcode-shell | [https://github.com/alibaba/lowcode-engine](https://github.com/alibaba/lowcode-engine) | packages/shell | +| @alilc/lowcode-types | [https://github.com/alibaba/lowcode-engine](https://github.com/alibaba/lowcode-engine) | packages/types | +| @alilc/lowcode-utils | [https://github.com/alibaba/lowcode-engine](https://github.com/alibaba/lowcode-engine) | packages/utils | +| @alilc/lowcode-datasource-engine | [https://github.com/alibaba/lowcode-datasource](https://github.com/alibaba/lowcode-datasource) | packages/datasource-engine | +| @alilc/lowcode-datasource-fetch-handler | [https://github.com/alibaba/lowcode-datasource](https://github.com/alibaba/lowcode-datasource) | packages/datasource-fetch-handler | +| @alilc/lowcode-datasource-jsonp-handler | [https://github.com/alibaba/lowcode-datasource](https://github.com/alibaba/lowcode-datasource) | packages/datasource-jsonp-handler | +| @alilc/lowcode-datasource-mopen-handler | [https://github.com/alibaba/lowcode-datasource](https://github.com/alibaba/lowcode-datasource) | packages/datasource-mopen-handler | +| @alilc/lowcode-datasource-mtop-handler | [https://github.com/alibaba/lowcode-datasource](https://github.com/alibaba/lowcode-datasource) | packages/datasource-mtop-handler | +| @alilc/lowcode-datasource-types | [https://github.com/alibaba/lowcode-datasource](https://github.com/alibaba/lowcode-datasource) | packages/datasource-types | +| @alilc/lowcode-datasource-universal-mtop-handler | [https://github.com/alibaba/lowcode-datasource](https://github.com/alibaba/lowcode-datasource) | packages/datasource-universal-mtop-handler | +| @alilc/lowcode-datasource-url-params-handler | [https://github.com/alibaba/lowcode-datasource](https://github.com/alibaba/lowcode-datasource) | packages/datasource-url-params-handler | +| @alilc/build-plugin-alt | [https://github.com/alibaba/lowcode-tools](https://github.com/alibaba/lowcode-tools) | packages/build-plugin-alt | +| @alilc/create-element | [https://github.com/alibaba/lowcode-tools](https://github.com/alibaba/lowcode-tools) | packages/create-element | +| @alilc/lowcode-plugin-inject | [https://github.com/alibaba/lowcode-tools](https://github.com/alibaba/lowcode-tools) | packages/lowcode-plugin-inject | +| @alilc/action-block | [https://github.com/alibaba/lowcode-plugins](https://github.com/alibaba/lowcode-plugins) | packages/action-block | +| @alilc/lowcode-plugin-base-monaco-editor | [https://github.com/alibaba/lowcode-plugins](https://github.com/alibaba/lowcode-plugins) | packages/plugin-base-monaco-editor | +| @alilc/lowcode-plugin-block | [https://github.com/alibaba/lowcode-plugins](https://github.com/alibaba/lowcode-plugins) | packages/plugin-block | +| @alilc/lowcode-plugin-code-editor | [https://github.com/alibaba/lowcode-plugins](https://github.com/alibaba/lowcode-plugins) | packages/plugin-code-editor | +| @alilc/lowcode-plugin-components-pane | [https://github.com/alibaba/lowcode-plugins](https://github.com/alibaba/lowcode-plugins) | packages/plugin-components-pane | +| @alilc/lowcode-plugin-datasource-pane | [https://github.com/alibaba/lowcode-plugins](https://github.com/alibaba/lowcode-plugins) | packages/plugin-datasource-pane | +| @alilc/lowcode-plugin-manual | [https://github.com/alibaba/lowcode-plugins](https://github.com/alibaba/lowcode-plugins) | packages/plugin-manual | +| @alilc/lowcode-plugin-schema | [https://github.com/alibaba/lowcode-plugins](https://github.com/alibaba/lowcode-plugins) | packages/plugin-schema | +| @alilc/lowcode-plugin-undo-redo | [https://github.com/alibaba/lowcode-plugins](https://github.com/alibaba/lowcode-plugins) | packages/plugin-undo-redo | +| @alilc/lowcode-plugin-zh-en | [https://github.com/alibaba/lowcode-plugins](https://github.com/alibaba/lowcode-plugins) | packages/plugin-zh-en | +| @alifd/fusion-ui | [https://github.com/alibaba/lowcode-materials](https://github.com/alibaba/lowcode-materials) | packages/fusion-ui | +| @alilc/lowcode-materials | [https://github.com/alibaba/lowcode-materials](https://github.com/alibaba/lowcode-materials) | packages/fusion-lowcode-materials | +| @alilc/antd-lowcode-materials | [https://github.com/alibaba/lowcode-materials](https://github.com/alibaba/lowcode-materials) | packages/antd-lowcode-materials | +| | | | +| | | | +| | | | diff --git a/docs/docs/guide/appendix/repos.md b/docs/docs/guide/appendix/repos.md new file mode 100644 index 000000000..b4dbca7ac --- /dev/null +++ b/docs/docs/guide/appendix/repos.md @@ -0,0 +1,87 @@ +--- +title: 低代码仓库列表 +sidebar_position: 2 +--- +### 1. 引擎主包 +包含引擎的 4 大模块，入料、编排、渲染和出码。 + +仓库地址：[https://github.com/alibaba/lowcode-engine](https://github.com/alibaba/lowcode-engine) +子包明细： + +1. designer +2. editor-core +3. editor-skeleton +4. engine +5. ignitor +6. plugin-designer +7. plugin-outline-pane +8. rax-renderer +9. rax-simulator-renderer +10. react-renderer +11. react-simulator-renderer +12. renderer-core +13. types +14. utils +15. material-parser +16. code-generator + +### 2. 引擎官方扩展包 +包含了常用的设置器（setter）、跟 setter 绑定的插件等 + +仓库地址：[https://github.com/alibaba/lowcode-engine-ext](https://github.com/alibaba/lowcode-engine-ext) +子包明细： + +- 设置器 setter + - array-setter + - bool-setter + - classname-setter + - color-setter + - events-setter + - expression-setter + - function-setter + - i18n-setter + - icon-setter + - json-setter + - mixed-setter + - number-setter + - object-setter + - out.txt + - radiogroup-setter + - select-setter + - slot-setter + - string-setter + - style-setter + - textarea-setter + - variable-setter +- 插件 plugin + - plugin-event-bind-dialog 事件绑定浮层 + - plugin-variable-bind-dialog 变量绑定浮层 +### 3. 低代码插件 +包含了常用的插件等 + +仓库地址：[https://github.com/alibaba/lowcode-plugins](https://github.com/alibaba/lowcode-plugins) +子包明细： + +- base-monaco-editor 基础代码编辑器 +- plugin-code-editor 源码编辑面板 +- plugin-datasource-pane 数据源面板 +- plugin-manual 产品使用手册面板 +- plugin-schema 页面数据面板 +- plugin-undo-redo 前进/后退功能 +- plugin-zh-cn 中英文切换功能 + +### 4. 引擎 demo +展示使用引擎编排和渲染等模块以及相应的依赖资源配置基础 demo + +仓库地址：[https://github.com/alibaba/lowcode-demo](https://github.com/alibaba/lowcode-demo) +### 5. 工具链包 +包含生成引擎生态元素（setter、物料、插件）的脚手架，启动脚本，调试插件等 + +仓库地址：[https://github.com/alibaba/lowcode-tools](https://github.com/alibaba/lowcode-tools) +### 6. 低代码数据源引擎 +负责在渲染&出码两种运行时实现数据源管理，承担低代码搭建数据请求的能力； +仓库地址：[https://github.com/alibaba/lowcode-datasource](https://github.com/alibaba/lowcode-datasource) +### 7. 基础物料 & 物料描述 +仓库地址：[https://github.com/alibaba/lowcode-materials](https://github.com/alibaba/lowcode-materials) +### 8. 出码 demo +仓库地址：[https://github.com/alibaba/lowcode-code-generator-demo](https://github.com/alibaba/lowcode-code-generator-demo) diff --git a/docs/docs/guide/appendix/setterDetails/_category_.json b/docs/docs/guide/appendix/setterDetails/_category_.json new file mode 100644 index 000000000..facb7b377 --- /dev/null +++ b/docs/docs/guide/appendix/setterDetails/_category_.json @@ -0,0 +1,4 @@ +{ + "label": "预置设置器详情", + "position": 5 +} diff --git a/docs/docs/guide/appendix/setterDetails/array.md b/docs/docs/guide/appendix/setterDetails/array.md new file mode 100644 index 000000000..bbbd4498b --- /dev/null +++ b/docs/docs/guide/appendix/setterDetails/array.md @@ -0,0 +1,68 @@ +--- +title: ArraySetter +--- + +#### 简介 +用来展示属性类型为数组的setter +#### 展示 +![image.png](https://cdn.nlark.com/yuque/0/2022/png/242652/1644395220128-b5d948e3-6a5a-420f-9a7a-a29be25c507d.png#clientId=ud56bf956-0414-4&crop=0&crop=0&crop=1&crop=1&from=paste&height=181&id=u27259ecd&margin=%5Bobject%20Object%5D&name=image.png&originHeight=362&originWidth=584&originalType=binary&ratio=1&rotation=0&showTitle=false&size=27221&status=done&style=none&taskId=u72065990-9557-4dbc-a0ba-eada448e228&title=&width=292) +#### 配置示例 +```javascript +"setter": { + "componentName": "ArraySetter", + "props": { + "itemSetter": { + "componentName": "ObjectSetter", + "props": { + "config": { + "items": [{ + "name": "title", + "description": "标题", + "setter": "StringSetter", + }, + { + "name": "callback", + "description": "callback", + "setter": { + "componentName": "FunctionSetter" + } + } + ] + } + }, + "initialValue": { + "title": "I am title", + "callback": null, + } + } + } +} +``` +#### ArraySetter 配置 +| **属性名** | **类型** | **说明** | +| --- | --- | --- | +| itemSetter | ObjectSetter | ArraySetter的子节点内容必须用ObjectSetter包裹 | + +#### itemSetter 配置 +| **属性名** | **类型** | **说明** | +| --- | --- | --- | +| componentName | String | + | +| props | | | +| initialValue | Object | 新增一项的初始值 | + +#### ObjectSetter 配置 +| **属性名** | **类型** | **说明** | +| --- | --- | --- | +| descriptor | String | Item在列表中展示的item.key名，需要和 config.items[] 中key对应 默认为 “项目X” +![image.png](https://cdn.nlark.com/yuque/0/2022/png/242652/1643448651683-6c44787a-cb6c-4066-9a47-2b22f862cb9c.png#clientId=u05af0495-3e67-4&crop=0&crop=0&crop=1&crop=1&from=paste&height=186&id=ufb6e3681&margin=%5Bobject%20Object%5D&name=image.png&originHeight=372&originWidth=640&originalType=binary&ratio=1&rotation=0&showTitle=false&size=103250&status=done&style=none&taskId=u7a61b6f7-4e26-4d8b-a9e6-a30b5e9e73d&title=&width=320) | +| config | Object | 配置项 | +| config.items | Array | 子属性列表数据 | +| config.items[].name | String | 子属性名称 | +| config.items[].description | String | 子属性描述 | +| config.items[].setter | Object | String | 子属性setter配置 | 子属性setter组件名 | +| config.items[].isRequired | Boolean | 子属性是否开启快捷编辑,最多开启4个 +![image.png](https://cdn.nlark.com/yuque/0/2022/png/242652/1643448651860-f4f80e87-4e80-463d-a1e0-99be8bf2a84f.png#clientId=u6ba2ab37-e0fb-4&crop=0&crop=0&crop=1&crop=1&from=paste&height=211&id=ueea652b0&margin=%5Bobject%20Object%5D&name=image.png&originHeight=422&originWidth=614&originalType=binary&ratio=1&rotation=0&showTitle=false&size=32465&status=done&style=none&taskId=u343405fd-5773-4ebd-b6fc-1367a769fe2&title=&width=307) | +| config.items[].condition | Boolean | () => Boolean | 是否展示 | +| config.items[].getValue | (target, value) => value | 数据获取的 hook，可修改获取数据 | +| config.items[].setValue | (target, value) => value | 数据获取的 hook，可修改设置数据 | diff --git a/docs/docs/guide/appendix/setterDetails/behavior.md b/docs/docs/guide/appendix/setterDetails/behavior.md new file mode 100644 index 000000000..cbb5cfc1f --- /dev/null +++ b/docs/docs/guide/appendix/setterDetails/behavior.md @@ -0,0 +1,5 @@ +--- +title: BehaviorSetter +--- + +详见 [npm 包说明](https://g.alicdn.com/code/npm/@ali/lowcode-setter-behavior/0.1.1/build/index.html) \ No newline at end of file diff --git a/docs/docs/guide/appendix/setterDetails/bool.md b/docs/docs/guide/appendix/setterDetails/bool.md new file mode 100644 index 000000000..d29274893 --- /dev/null +++ b/docs/docs/guide/appendix/setterDetails/bool.md @@ -0,0 +1,15 @@ +--- +title: BoolSetter +--- +#### 简介 +开关选择器 +#### 展示 +![](https://cdn.nlark.com/yuque/0/2022/png/242652/1643448646757-b61019f4-d502-473a-8a11-4974479c55dc.png#from=url&id=dnn2b&margin=%5Bobject%20Object%5D&originHeight=82&originWidth=320&originalType=binary&ratio=1&status=done&style=none) +#### setter 配置 +| 属性名 | 说明 | +| --- | --- | +| disabled | 是否可选 | +| defaultValue | 默认值 | + +#### 返回类型 +Boolean diff --git a/docs/docs/guide/appendix/setterDetails/color.md b/docs/docs/guide/appendix/setterDetails/color.md new file mode 100644 index 000000000..8c09f5883 --- /dev/null +++ b/docs/docs/guide/appendix/setterDetails/color.md @@ -0,0 +1,14 @@ +--- +title: ColorSetter +--- +用来选择颜色。 +#### 展示 +![image.png](https://cdn.nlark.com/yuque/0/2022/png/242652/1643448646203-3eb11d27-0195-4608-91f3-0f3cfb6b7140.png#clientId=u09a8f665-5383-4&from=paste&height=416&id=u417e185d&margin=%5Bobject%20Object%5D&name=image.png&originHeight=728&originWidth=590&originalType=binary&ratio=1&size=230281&status=done&style=none&taskId=u3d246b17-94ab-4eb3-af66-3ffb7fd3145&width=337) +#### setter 配置 +| 属性名 | 说明 | +| --- | --- | +| defaultValue | 默认值 | + +#### 返回类型 +String +会返回options中的value值 diff --git a/docs/docs/guide/appendix/setterDetails/event.md b/docs/docs/guide/appendix/setterDetails/event.md new file mode 100644 index 000000000..26405e908 --- /dev/null +++ b/docs/docs/guide/appendix/setterDetails/event.md @@ -0,0 +1,73 @@ +--- +title: EventSetter +--- +#### 简介 +可以将事件绑定在物料上 +#### 展示 +![image.png](https://cdn.nlark.com/yuque/0/2022/png/242652/1644394906292-0eb3ab0e-0bb0-4c8d-bbc5-7217b33cdcab.png#clientId=ub4e2d6f6-4877-4&crop=0&crop=0&crop=1&crop=1&from=paste&height=507&id=u2a295c86&margin=%5Bobject%20Object%5D&name=image.png&originHeight=1014&originWidth=1202&originalType=binary&ratio=1&rotation=0&showTitle=false&size=293824&status=done&style=none&taskId=u37e95d95-4425-450a-b4aa-9805d9dcf97&title=&width=601) + +#### 组件自带事件列表 +在物料协议的configure.supports.events 中声明 +```json +{ + "configure ": { + "supports": { + "style": true, + "events": [{ + "name": "onChange", + }, { + "name": "onExpand" + }, { + "name": "onVisibleChange" + }] + } + } +} +``` + +#### 事件绑定 +![image.png](https://cdn.nlark.com/yuque/0/2022/png/242652/1643448650540-8b403233-44a5-4b1f-9379-2c55d4694f12.png#clientId=uf9b6db87-aae9-4&crop=0&crop=0&crop=1&crop=1&from=paste&height=621&id=u95bb9c9a&margin=%5Bobject%20Object%5D&name=image.png&originHeight=1242&originWidth=2540&originalType=binary&ratio=1&rotation=0&showTitle=false&size=356836&status=done&style=none&taskId=u13bc14bd-d85c-46c9-aebd-586dcb32f96&title=&width=1270) +可以选择已有的事件(schema中的**methods**节点)进行绑定，也可以选择新建事件，选择新建事件默认会增加_new的事件后缀命名，点确定以后会跳转到对应代码插件对应区块 +#### +#### 参数设置 +如果需要额外传参，需要将扩展参数设置打开，在代码面板中，编辑参数内容 +注意： + +- 额外参数必须被包装成一个对象，如参数模板中所示 +- 可以使用动态变量例如 (this.items，this.state.xxx) +```json +{ + "testKey":this.state.text +} +``` + +- 该参数是额外参数，会加在原有参数后面，例如在onClick中加入扩展传参，最终函数消费的时候应该如下所示 +```javascript +// e为onClick原有函数传参，extParams为自定义传参 +onClick(e, extParams) { + this.setState({ + isShowDialog: extParams.isShowDialog + }) +} +``` +#### 事件新建函数模板 +有时候我们创建的函数会有用到一些通用的函数模板，我们可以在物料协议的events.template中创建一个模板，如下 +```javascript +{ + "configure ": { + "supports": { + "style": true, + "events": [{ + "name": "onChange", + "template": "templeteTest(e,${extParams}){this.setState({isShowDialog: false})}" + }, { + "name": "onExpand" + }, { + "name": "onVisibleChange" + }] + } + } +} +``` +其中 ${extParams} 为扩展参数占位符，如果用户没有声明扩展参数，会移除对应的参数声明，定义模板后，每次创建完函数会自动生成模板函数，如下图 +![image.png](https://cdn.nlark.com/yuque/0/2022/png/242652/1643448650786-62270a89-65d5-42b1-8efd-90b090155c82.png#clientId=uf9b6db87-aae9-4&crop=0&crop=0&crop=1&crop=1&from=paste&height=141&id=u4bb4387b&margin=%5Bobject%20Object%5D&name=image.png&originHeight=282&originWidth=1292&originalType=binary&ratio=1&rotation=0&showTitle=false&size=84790&status=done&style=none&taskId=u2b911f77-a018-4f17-a5df-36c2c142d18&title=&width=646) diff --git a/docs/docs/guide/appendix/setterDetails/icon.md b/docs/docs/guide/appendix/setterDetails/icon.md new file mode 100644 index 000000000..1e98059c3 --- /dev/null +++ b/docs/docs/guide/appendix/setterDetails/icon.md @@ -0,0 +1,81 @@ +--- +title: IconSetter +--- +#### 简介 +用来选择图标 +#### 展示 +![image.png](https://cdn.nlark.com/yuque/0/2022/png/242652/1644394747068-9b8f47e1-06f7-48de-ba73-9ed3d389f913.png#clientId=u144a54e7-b111-4&crop=0&crop=0&crop=1&crop=1&from=paste&height=290&id=uae8bb869&margin=%5Bobject%20Object%5D&name=image.png&originHeight=579&originWidth=1172&originalType=binary&ratio=1&rotation=0&showTitle=false&size=148927&status=done&style=none&taskId=ud281e100-e277-493d-8d4a-0e7b2c1b8f2&title=&width=586) +#### setter 配置 +| **属性名** | **类型** | **说明** | +| --- | --- | --- | +| type | String | 选择器返回类型 +**可选值**: +"string" | "node" | +| defaultValue | String | ReactNode | 默认值 | +| hasClear | Boolean | 选择器是否显示清除按钮 | +| icons | Array | 自定义icon集合；默认值详见[图标可选值](#SWnNn) | +| placeholder | String | 没有值的时候的占位符 | + +#### 返回类型 +String | ReactNode +#### 图标可选值 +```json +[ + 'smile', + 'cry', + 'success', + 'warning', + 'prompt', + 'error', + 'help', + 'clock', + 'success-filling', + 'delete-filling', + 'favorites-filling', + 'add', + 'minus', + 'arrow-up', + 'arrow-down', + 'arrow-left', + 'arrow-right', + 'arrow-double-left', + 'arrow-double-right', + 'switch', + 'sorting', + 'descending', + 'ascending', + 'select', + 'semi-select', + 'loading', + 'search', + 'close', + 'ellipsis', + 'picture', + 'calendar', + 'ashbin', + 'upload', + 'download', + 'set', + 'edit', + 'refresh', + 'filter', + 'attachment', + 'account', + 'email', + 'atm', + 'copy', + 'exit', + 'eye', + 'eye-close', + 'toggle-left', + 'toggle-right', + 'lock', + 'unlock', + 'chart-pie', + 'chart-bar', + 'form', + 'detail', + 'list', + 'dashboard', +] +``` diff --git a/docs/docs/guide/appendix/setterDetails/mixed.md b/docs/docs/guide/appendix/setterDetails/mixed.md new file mode 100644 index 000000000..6ce3df024 --- /dev/null +++ b/docs/docs/guide/appendix/setterDetails/mixed.md @@ -0,0 +1,13 @@ +--- +title: MixedSetter +--- +#### 简介 +可以让属性同时支持多个setter + +#### 展示 +![image.png](https://cdn.nlark.com/yuque/0/2022/png/242652/1644394866233-4b9127cd-3825-4763-9e2a-526ea2b48140.png#clientId=u7c96c5f7-4dd4-4&crop=0&crop=0&crop=1&crop=1&from=paste&height=240&id=u7ca1df47&margin=%5Bobject%20Object%5D&name=image.png&originHeight=480&originWidth=1552&originalType=binary&ratio=1&rotation=0&showTitle=false&size=272344&status=done&style=none&taskId=u07037884-fbf4-411a-be82-29296ad1fb2&title=&width=776) + +#### 配置 +| **属性名** | **类型** | **说明** | +| --- | --- | --- | +| setters | Array | SetterName | diff --git a/docs/docs/guide/appendix/setterDetails/number.md b/docs/docs/guide/appendix/setterDetails/number.md new file mode 100644 index 000000000..cd4d95ab0 --- /dev/null +++ b/docs/docs/guide/appendix/setterDetails/number.md @@ -0,0 +1,19 @@ +--- +title: NumberSetter +--- +#### 简介 +用于输入数字。 +#### 展示 +![](https://cdn.nlark.com/yuque/0/2022/png/242652/1643448648108-fae36b4c-fb3d-4a4e-b83e-c5233e8bae5d.png#from=url&id=czSyt&margin=%5Bobject%20Object%5D&originHeight=402&originWidth=576&originalType=binary&ratio=1&status=done&style=none) +#### setter 配置 +| 属性名 | 说明 | +| --- | --- | +| min, max | 指定最大最小值 | +| defaultValue | 默认值 | +| step | 指定步长 number | +| units | 指定单位 string | +| precision | 设置小数位数 number | + +#### 返回类型 +#### Number +会返回value值 diff --git a/docs/docs/guide/appendix/setterDetails/radioGroup.md b/docs/docs/guide/appendix/setterDetails/radioGroup.md new file mode 100644 index 000000000..10bbc13f4 --- /dev/null +++ b/docs/docs/guide/appendix/setterDetails/radioGroup.md @@ -0,0 +1,24 @@ +--- +title: RadioGroupSetter +--- +#### 简介 +用于直观的展示选择并选择。 +#### 展示 +![image.png](https://cdn.nlark.com/yuque/0/2022/png/242652/1644395469783-17a5f8b5-112a-420b-a64f-09fffea55067.png#clientId=u8044d585-4c1d-4&crop=0&crop=0&crop=1&crop=1&from=paste&height=49&id=ucafe75f2&margin=%5Bobject%20Object%5D&name=image.png&originHeight=98&originWidth=564&originalType=binary&ratio=1&rotation=0&showTitle=false&size=9843&status=done&style=none&taskId=ud3ff8182-f29c-4b81-b4de-e23baa325c1&title=&width=282) +#### setter 配置 +| 属性名 | 说明 | +| --- | --- | +| defaultValue | 默认值 | +| options | 传入的数据源， +**参数格式**: +[ +{img: 'url', +value: 'text', +label/title: 'text'}, ... +] +|| +[ 'text', 'text', ...] | + +#### 返回类型 +String | Number | Boolean +会返回options中的value值 diff --git a/docs/docs/guide/appendix/setterDetails/select.md b/docs/docs/guide/appendix/setterDetails/select.md new file mode 100644 index 000000000..296bafebf --- /dev/null +++ b/docs/docs/guide/appendix/setterDetails/select.md @@ -0,0 +1,24 @@ +--- +title: SelectSetter +--- +#### 简介 +用来选择组件。在限定的可选性内进行选择，核心能力是选择 +#### 展示 +![image.png](https://cdn.nlark.com/yuque/0/2022/png/242652/1644395925308-538eb962-f035-43b9-bdb3-ecc5bc9d1e85.png#clientId=u8b43103b-f292-4&crop=0&crop=0&crop=1&crop=1&from=paste&height=301&id=u7a9a7786&margin=%5Bobject%20Object%5D&name=image.png&originHeight=602&originWidth=574&originalType=binary&ratio=1&rotation=0&showTitle=false&size=36601&status=done&style=none&taskId=u089007a6-76ec-44e8-94b5-127a8ba1a51&title=&width=287) +#### setter 配置 +| 属性名 | 说明 | +| --- | --- | +| mode | 选择器模式 + +可选值: +'single', 'multiple', 'tag' | +| defaultValue | 默认值 | +| options | 传入的数据源， +**参数格式**: +[ +{label/title: '文字', value: 'text'}, ... +] | + +#### 返回类型 +String | Number | Boolean +会返回options中的value值 diff --git a/docs/docs/guide/appendix/setterDetails/slot.md b/docs/docs/guide/appendix/setterDetails/slot.md new file mode 100644 index 000000000..52e3f9f3b --- /dev/null +++ b/docs/docs/guide/appendix/setterDetails/slot.md @@ -0,0 +1,93 @@ +--- +title: SlotSetter +--- +## 简介 +通过一个开启一个slot（插槽），可以在物料特定的一个位置渲染一个或者多个节点。slot比较适合物料的局部自定义渲染。 + +## 展示 +![image.png](https://cdn.nlark.com/yuque/0/2022/png/242652/1643448654034-6f527cc2-cf65-4e79-b904-21416800b5b8.png#clientId=u091bb73f-2e93-4&crop=0&crop=0&crop=1&crop=1&from=paste&height=227&id=gAVIU&margin=%5Bobject%20Object%5D&name=image.png&originHeight=454&originWidth=588&originalType=binary&ratio=1&rotation=0&showTitle=false&size=103838&status=done&style=none&taskId=u45d2e179-54ea-40d1-a654-66151c337ff&title=&width=294) + +![image.png](https://cdn.nlark.com/yuque/0/2022/png/242652/1644395677385-84c39b6d-2356-4d86-a741-edbb7daffd6c.png#clientId=udcc199c0-6236-4&crop=0&crop=0&crop=1&crop=1&from=paste&height=82&id=u999c2367&margin=%5Bobject%20Object%5D&name=image.png&originHeight=164&originWidth=644&originalType=binary&ratio=1&rotation=0&showTitle=false&size=18486&status=done&style=none&taskId=u6c13f469-173f-4ba0-9bfa-866122ef7a4&title=&width=322) + +## setter 配置 + +| 属性名 | 类型 | 说明 | +| --- | --- | --- | +| initialValue | Object | 默认值 +{ +"type": "JSSlot", +"params": [ +"module" + ], +"value": [] +} + +params:接收函数的入参，可以直接在slot节点中消费，通过this.module (这里module是示例值，可根据实际函数入参更改) +value:可以定义一个节点，每次打开插槽的时候默认填充一个节点 + + | +| hideParams | boolean | 是否隐藏入参，注意该值只能隐藏入参的输入框，适合单行展示，实际渲染的时候，还是会传入params的参数，和params:[]不同 | +| checkedText | string | switch选中文案，默认显示"启用" | +| unCheckedText | string | switch取消文案，默认显示"关闭" | + +## 配置示例 +### 普通示例 +#### 配置 +```typescript +{ + name: "propName", + title: "propTitle", + setter: { + componentName: "SlotSetter", + isRequired: true, + title: "组件坑位", + initialValue: { + type: "JSSlot", + value: [] + }, + } + } +``` +#### 组件 +```typescript +function A(props) { + return props.propName; +} +``` +### 带参数的插槽示例 +#### 配置 +```typescript +{ + name: "propName", + title: "propTitle", + setter: { + componentName: "SlotSetter", + isRequired: true, + title: "组件坑位", + initialValue: { + type: "JSSlot", + params: [ + "module" + ], + value: [] + }, + } + } +``` +#### 组件 +组件需要传参数进行渲染，和普通示例的使用不一样。 +```typescript +function A(props) { + const module = [] + return props.propName(module); +} +``` +#### param 使用示例 +1.开启插槽 +![image.png](https://cdn.nlark.com/yuque/0/2022/png/2622706/1652877673290-7a377a36-7da9-40c1-baff-1c7c8ad04a67.png#clientId=udd177887-e136-4&crop=0&crop=0&crop=1&crop=1&from=paste&height=900&id=u9ba2344a&margin=%5Bobject%20Object%5D&name=image.png&originHeight=1800&originWidth=3584&originalType=binary&ratio=1&rotation=0&showTitle=false&size=1291582&status=done&style=none&taskId=u60418282-46e2-46b4-95d2-156288bcbd7&title=&width=1792) +2.拖拽组件到插槽中 +![image.png](https://cdn.nlark.com/yuque/0/2022/png/2622706/1652877759606-6de16048-a5d9-477c-b38b-962690a39254.png#clientId=udd177887-e136-4&crop=0&crop=0&crop=1&crop=1&from=paste&height=903&id=u43b38264&margin=%5Bobject%20Object%5D&name=image.png&originHeight=1806&originWidth=3584&originalType=binary&ratio=1&rotation=0&showTitle=false&size=1230647&status=done&style=none&taskId=u96d44a1e-033f-4cd0-ac81-df6cac8ea18&title=&width=1792) + +3.在插槽内组件中使用变量绑定，绑定 this.xxx +xxx 入参的配置 +![image.png](https://cdn.nlark.com/yuque/0/2022/png/2622706/1652877586491-904d6b18-a41a-4ba2-8664-088cd5feca72.png#clientId=udd177887-e136-4&crop=0&crop=0&crop=1&crop=1&from=paste&height=903&id=u165f1564&margin=%5Bobject%20Object%5D&name=image.png&originHeight=1806&originWidth=3584&originalType=binary&ratio=1&rotation=0&showTitle=false&size=1278387&status=done&style=none&taskId=uc060e73a-b190-480a-8aad-8c20b27290c&title=&width=1792) diff --git a/docs/docs/guide/appendix/setterDetails/string.md b/docs/docs/guide/appendix/setterDetails/string.md new file mode 100644 index 000000000..77e5aacf4 --- /dev/null +++ b/docs/docs/guide/appendix/setterDetails/string.md @@ -0,0 +1,14 @@ +--- +title: StringSetter +--- +#### 简介 +用来展示和修改字符串类型的属性值，不可换行 +#### 展示 +![](https://cdn.nlark.com/yuque/0/2022/png/242652/1643448645493-4a30f02e-1869-4963-8d39-40501891ae84.png#from=url&id=mEkyy&margin=%5Bobject%20Object%5D&originHeight=88&originWidth=714&originalType=binary&ratio=1&status=done&style=none) +#### setter 配置 +| 属性名 | 说明 | +| --- | --- | +| placeholder | 输入提示 | + +#### 返回类型 +String diff --git a/docs/docs/guide/appendix/setterDetails/style.md b/docs/docs/guide/appendix/setterDetails/style.md new file mode 100644 index 000000000..f733baaa3 --- /dev/null +++ b/docs/docs/guide/appendix/setterDetails/style.md @@ -0,0 +1,49 @@ +--- +title: StyleSetter +--- +## 简介 +通过开启StyleSetter,我们可以将样式配置面板来配置样式属性。 + +## 展示 +![image.png](https://cdn.nlark.com/yuque/0/2022/png/2553587/1658650544358-3d97f6b1-6269-4627-ab4a-62a43219fd08.png#clientId=u5d06f6c0-ba35-4&crop=0&crop=0&crop=1&crop=1&from=paste&height=739&id=u3f141635&margin=%5Bobject%20Object%5D&name=image.png&originHeight=1478&originWidth=596&originalType=binary&ratio=1&rotation=0&showTitle=false&size=75996&status=done&style=none&taskId=u16f49c5d-a32e-4cf8-95ab-e0c1059fbef&title=&width=298) + +## setter 配置 + +| 属性名 | 类型 | 说明 | +| --- | --- | --- | +| unit | String | 默认值 px +![image.png](https://cdn.nlark.com/yuque/0/2022/png/2553587/1658650635878-fd920e86-ea28-4e08-8676-238ac367a0ee.png#clientId=u5d06f6c0-ba35-4&crop=0&crop=0&crop=1&crop=1&from=paste&height=49&id=u3f243c11&margin=%5Bobject%20Object%5D&name=image.png&originHeight=98&originWidth=576&originalType=binary&ratio=1&rotation=0&showTitle=false&size=9796&status=done&style=none&taskId=ucc541aa4-0765-4da9-820c-cee48ed0635&title=&width=288) + | +| placeholderScale | Number | 默认计算尺寸缩放 默认值为1 +![image.png](https://cdn.nlark.com/yuque/0/2022/png/2553587/1658650773475-7ecba070-c81e-4a6c-b346-7aad7dd6a897.png#clientId=u5d06f6c0-ba35-4&crop=0&crop=0&crop=1&crop=1&from=paste&height=49&id=u27842257&margin=%5Bobject%20Object%5D&name=image.png&originHeight=98&originWidth=250&originalType=binary&ratio=1&rotation=0&showTitle=false&size=7116&status=done&style=none&taskId=u8ac18c79-d14b-49a6-8788-476524e69da&title=&width=125) +在没有设定数值的时候，系统会通过window.getComputedStyle来计算展示的数值。 +在某些场景下，例如手机场景，在编辑器展示的是375的实际宽度，但是实际设计尺寸是750的宽度，这个时候需要对这个计算尺寸设成2 | +| showModuleList | String[] | 默认值 +['background', 'border', 'font', 'layout', 'position'] +分别对应背景、边框、文字、布局、位置五个区块，可以针对不同的场景按需进行展示。 +例如文字的组件，我不需要修改边框的样式，就可以把边框模块隐藏掉 | +| isShowCssCode | Boolean | 默认值: true, 是否展示css源码编辑 | +| layoutPropsConfig | Object | 布局样式设置 | +| layoutPropsConfig.showDisPlayList | String[] | 默认值 ['inline', 'flex', 'block', 'inline-block', 'none'] +![image.png](https://cdn.nlark.com/yuque/0/2022/png/2553587/1658651295786-48ca3773-1b4e-4f2e-9521-0ebbfcfe5361.png#clientId=u5d06f6c0-ba35-4&crop=0&crop=0&crop=1&crop=1&from=paste&height=36&id=u50dae00c&margin=%5Bobject%20Object%5D&name=image.png&originHeight=72&originWidth=474&originalType=binary&ratio=1&rotation=0&showTitle=false&size=7621&status=done&style=none&taskId=ub5804835-d0b2-45d7-a419-66ac1005afa&title=&width=237) +可按需展示 + | +| layoutPropsConfig.isShowPadding | String | 默认值 true +![image.png](https://cdn.nlark.com/yuque/0/2022/png/2553587/1658651496157-c84348d4-a47f-44b4-b2c5-74b21e97747a.png#clientId=u5d06f6c0-ba35-4&crop=0&crop=0&crop=1&crop=1&from=paste&height=191&id=u70235603&margin=%5Bobject%20Object%5D&name=image.png&originHeight=382&originWidth=548&originalType=binary&ratio=1&rotation=0&showTitle=false&size=20439&status=done&style=none&taskId=udae33336-ce05-41a9-89c5-361a63d061a&title=&width=274) +是否展示内边距 （四个边） | +| layoutPropsConfig.isShowMargin | Boolean | 默认值 true +![image.png](https://cdn.nlark.com/yuque/0/2022/png/2553587/1658651539776-090de3e1-6293-4660-b74f-9bcf027381c6.png#clientId=u5d06f6c0-ba35-4&crop=0&crop=0&crop=1&crop=1&from=paste&height=241&id=uab3771c7&margin=%5Bobject%20Object%5D&name=image.png&originHeight=482&originWidth=536&originalType=binary&ratio=1&rotation=0&showTitle=false&size=29325&status=done&style=none&taskId=uc287d55d-5363-4b37-978b-6e150f36141&title=&width=268) +是否展示外边距 （四个边） | +| layoutPropsConfig.isShowWidthHeight | Boolean | 默认值 true +![image.png](https://cdn.nlark.com/yuque/0/2022/png/2553587/1658651621765-06e81934-9a90-4290-89dd-75ffb56808a5.png#clientId=u5d06f6c0-ba35-4&crop=0&crop=0&crop=1&crop=1&from=paste&height=51&id=u02aa5918&margin=%5Bobject%20Object%5D&name=image.png&originHeight=102&originWidth=546&originalType=binary&ratio=1&rotation=0&showTitle=false&size=9945&status=done&style=none&taskId=u394451ef-266c-440d-a86e-fc1a01320ea&title=&width=273) +是否展示宽高 | +| fontPropsConfig | Object | 文字样式设置 | +| fontPropsConfig.fontFamilyList | Array | [ + { value: 'Helvetica', label: 'Helvetica' }, + { value: 'Arial', label: 'Arial' }, + { value: 'serif', label: 'serif' }, + ] +可以定制文字字体选项 | +| positionPropsConfig | Object | 位置样式设置 | +| positionPropsConfig.isShowFloat | Boolean | 默认true 是否展示浮动 | +| positionPropsConfig.isShowClear | Boolean | 默认true 是否展示清除浮动 | diff --git a/docs/docs/guide/appendix/setterDetails/textArea.md b/docs/docs/guide/appendix/setterDetails/textArea.md new file mode 100644 index 000000000..9188012f8 --- /dev/null +++ b/docs/docs/guide/appendix/setterDetails/textArea.md @@ -0,0 +1,14 @@ +--- +title: StyleSetter +--- +#### 简介 +表单输入组件。 +#### 展示 +![image.png](https://cdn.nlark.com/yuque/0/2022/png/242652/1644395839676-9feaa4d6-dbec-40c0-a93c-6014006a50c5.png#clientId=u01f23b13-e688-4&crop=0&crop=0&crop=1&crop=1&from=paste&height=146&id=u29c456c5&margin=%5Bobject%20Object%5D&name=image.png&originHeight=292&originWidth=1026&originalType=binary&ratio=1&rotation=0&showTitle=false&size=304205&status=done&style=none&taskId=u83ca85c2-3a04-4c41-a055-31d1bb86d84&title=&width=513) +#### setter 配置 +| **属性名** | **类型** | **说明** | +| --- | --- | --- | +| placeholder | String | 输入提示 | + +#### 返回类型 +String diff --git a/docs/docs/guide/appendix/setterDetails/variable.md b/docs/docs/guide/appendix/setterDetails/variable.md new file mode 100644 index 000000000..88e46e0cd --- /dev/null +++ b/docs/docs/guide/appendix/setterDetails/variable.md @@ -0,0 +1,12 @@ +--- +title: VariableSetter +--- +#### 简介 +用来给属性值设定变量 + +#### 展示 +![image.png](https://cdn.nlark.com/yuque/0/2022/png/242652/1644395534301-67aaf74b-2561-4682-a0b2-dcde642a8d7c.png#clientId=u46178fa3-bc0c-4&crop=0&crop=0&crop=1&crop=1&from=paste&height=46&id=ucd7e6f91&margin=%5Bobject%20Object%5D&name=image.png&originHeight=92&originWidth=578&originalType=binary&ratio=1&rotation=0&showTitle=false&size=10671&status=done&style=none&taskId=u854e606f-bbd1-42f4-81a2-d161aa4e2d3&title=&width=289) +![image.png](https://cdn.nlark.com/yuque/0/2022/png/242652/1643448653288-1b5b46c8-5ea1-455d-9ce4-19abade13b31.png#clientId=udec6352b-e220-4&crop=0&crop=0&crop=1&crop=1&from=paste&height=595&id=u2395a6a5&margin=%5Bobject%20Object%5D&name=image.png&originHeight=1190&originWidth=1564&originalType=binary&ratio=1&rotation=0&showTitle=false&size=256705&status=done&style=none&taskId=u3f3418f8-b6ad-464e-8fe6-89586fbc07d&title=&width=782) +#### +#### 变量列表 +包含所有的在协议中的**state**(state属性)节点数据和**methods**(自定义处理函数)节点数据 diff --git a/docs/docs/guide/appendix/setters.md b/docs/docs/guide/appendix/setters.md new file mode 100644 index 000000000..381ef8198 --- /dev/null +++ b/docs/docs/guide/appendix/setters.md @@ -0,0 +1,41 @@ +--- +title: 预置设置器列表 +sidebar_position: 4 +--- +| 预置 Setter | 返回类型 | 用途 | 截图 | +| --- | --- | --- | --- | +| [ArraySetter](https://www.yuque.com/lce/doc/eiegwf?view=doc_embed&from=kb&from=kb&outline=1&title=1) | T[] | 列表数组行数据设置器 | ![](https://cdn.nlark.com/yuque/0/2022/png/242652/1644395227012-97d27c4d-e053-4aae-9de1-726015081a4d.png#crop=0&crop=0&crop=1&crop=1&from=url&id=MHREr&margin=%5Bobject%20Object%5D&originHeight=362&originWidth=584&originalType=binary&ratio=1&rotation=0&showTitle=false&status=done&style=none&title=) | +| [BoolSetter](https://www.yuque.com/lce/doc/mdxryw?view=doc_embed&from=kb&from=kb&outline=1&title=1) | boolean | 布尔型数据设置器， | ![](https://cdn.nlark.com/yuque/0/2022/png/242652/1644394538926-81adaab2-fe44-4cf4-93a0-4f46d790cfc6.png#crop=0&crop=0&crop=1&crop=1&from=url&id=yVcL4&margin=%5Bobject%20Object%5D&originHeight=82&originWidth=320&originalType=binary&ratio=1&rotation=0&showTitle=false&status=done&style=none&title=) | +| ClassNameSetter | string | 样式名设置器 | ![](https://cdn.nlark.com/yuque/0/2022/png/2553587/1644417220734-fd13e249-43f0-4caa-8122-9c1a791cd30f.png#crop=0&crop=0&crop=1&crop=1&from=url&id=RNQQQ&margin=%5Bobject%20Object%5D&originHeight=180&originWidth=502&originalType=binary&ratio=1&rotation=0&showTitle=false&status=done&style=none&title=) | +| [ColorSetter](https://www.yuque.com/lce/doc/hu5ir6?view=doc_embed&from=kb&from=kb&outline=1&title=1) | string | 颜色设置器 | ![](https://cdn.nlark.com/yuque/0/2022/png/242652/1644394553552-2c8c3982-1671-47b3-a569-297bcb838b79.png#crop=0&crop=0&crop=1&crop=1&from=url&id=CxWyj&margin=%5Bobject%20Object%5D&originHeight=728&originWidth=590&originalType=binary&ratio=1&rotation=0&showTitle=false&status=done&style=none&title=) | +| DateMonthSetter | + | 日期型-月数据设置器 | + | +| DateRangeSetter | + | 日期型数据设置器，可选择时间区间 | + | +| DateSetter | + | 日期型数据设置器 | + | +| DateYearSetter | + | 日期型-年数据设置器 | + | +| [EventSetter](https://www.yuque.com/lce/doc/fiu8cz?view=doc_embed&from=kb&from=kb&outline=1&title=1) | function | 事件绑定设置器 | ![](https://cdn.nlark.com/yuque/0/2022/png/242652/1644394913684-e50d5fb4-50f4-4f6a-b5f8-5a6269b56676.png#crop=0&crop=0&crop=1&crop=1&from=url&id=lCP5h&margin=%5Bobject%20Object%5D&originHeight=1014&originWidth=1202&originalType=binary&ratio=1&rotation=0&showTitle=false&status=done&style=none&title=) | +| [IconSetter](https://www.yuque.com/lce/doc/ry138x?view=doc_embed&from=kb&from=kb&outline=1&title=1) | string | 图标设置器 | ![](https://cdn.nlark.com/yuque/0/2022/png/242652/1644394768487-d7b9a492-254e-46bd-a755-f8f73d76b932.png#crop=0&crop=0&crop=1&crop=1&from=url&id=pbQvJ&margin=%5Bobject%20Object%5D&originHeight=579&originWidth=1172&originalType=binary&ratio=1&rotation=0&showTitle=false&status=done&style=none&title=) | +| FunctionSetter | any | 函数型数据设置器 | ![](https://cdn.nlark.com/yuque/0/2022/png/2553587/1644417386132-50215eb0-ca7e-499b-8ca8-bd0b19ce89e1.png#crop=0&crop=0&crop=1&crop=1&from=url&id=YZ16c&margin=%5Bobject%20Object%5D&originHeight=110&originWidth=794&originalType=binary&ratio=1&rotation=0&showTitle=false&status=done&style=none&title=) | +| JsonSetter | object | json型数据设置器 | ![](https://cdn.nlark.com/yuque/0/2022/png/2553587/1644418044457-a50b1621-090a-440d-9735-b3e9b7b3abd8.png#crop=0&crop=0&crop=1&crop=1&from=url&id=OywYO&margin=%5Bobject%20Object%5D&originHeight=1068&originWidth=1076&originalType=binary&ratio=1&rotation=0&showTitle=false&status=done&style=none&title=) | +| [MixedSetter](https://www.yuque.com/lce/doc/ah6o2c?view=doc_embed&from=kb&from=kb&outline=1&title=1) | any | 混合型数据设置器 | ![](https://cdn.nlark.com/yuque/0/2022/png/242652/1644394872594-bb8f8de1-824a-4ba7-8b83-e408434a7d29.png#crop=0&crop=0&crop=1&crop=1&from=url&id=it6Xz&margin=%5Bobject%20Object%5D&originHeight=480&originWidth=1552&originalType=binary&ratio=1&rotation=0&showTitle=false&status=done&style=none&title=) | +| [NumberSetter](https://www.yuque.com/lce/doc/hk65u5?view=doc_embed&from=kb&from=kb&outline=1&title=1) | number | 数值型数据设置器 | ![](https://cdn.nlark.com/yuque/0/2022/png/242652/1644394982613-b1a43863-fd63-4bb4-b5fe-2f36109c449b.png#crop=0&crop=0&crop=1&crop=1&from=url&id=bEZjH&margin=%5Bobject%20Object%5D&originHeight=328&originWidth=1152&originalType=binary&ratio=1&rotation=0&showTitle=false&status=done&style=none&title=) | +| ObjectSetter | Record | 对象数据设置器，一般内嵌在ArraySetter中 | + | +| [RadioGroupSetter](https://www.yuque.com/lce/doc/cmpf0b?view=doc_embed&from=kb&from=kb&outline=1&title=1) | string | number | boolean | 枚举型数据设置器，采用tab选择的形式展现 | ![](https://cdn.nlark.com/yuque/0/2022/png/242652/1644395460363-1fdb034c-69d7-404d-9226-37f1d4562210.png#crop=0&crop=0&crop=1&crop=1&from=url&id=XSyl3&margin=%5Bobject%20Object%5D&originHeight=98&originWidth=564&originalType=binary&ratio=1&rotation=0&showTitle=false&status=done&style=none&title=) | +| [SelectSetter](https://www.yuque.com/lce/doc/po1t1r?view=doc_embed&from=kb&from=kb&outline=1&title=1) | string | number | boolean | 枚举型数据设置器，采用下拉的形式展现 | ![](https://cdn.nlark.com/yuque/0/2022/png/242652/1644395970016-dfe95495-53b1-4f86-afc6-a0c621917440.png#crop=0&crop=0&crop=1&crop=1&from=url&id=NPzvg&margin=%5Bobject%20Object%5D&originHeight=282&originWidth=582&originalType=binary&ratio=1&rotation=0&showTitle=false&status=done&style=none&title=) | +| [SlotSetter](https://www.yuque.com/lce/doc/af5vba?view=doc_embed&from=kb&from=kb&outline=1&title=1) | Element | Element[] | 节点型数据设置器 | ![](https://cdn.nlark.com/yuque/0/2022/png/242652/1644395692198-ca0cb611-0b7b-43b2-9f3b-3f6983cc3b37.png#crop=0&crop=0&crop=1&crop=1&from=url&id=SLNSR&margin=%5Bobject%20Object%5D&originHeight=164&originWidth=644&originalType=binary&ratio=1&rotation=0&showTitle=false&status=done&style=none&title=) | +| [StringSetter](https://www.yuque.com/lce/doc/qogni4?view=doc_embed&from=kb&from=kb&outline=1&title=1) | string | 短文本型数据设置器，不可换行 | ![](https://cdn.nlark.com/yuque/0/2022/png/242652/1644395613012-e7e5db32-9281-4f19-a18d-284765cd1184.png#crop=0&crop=0&crop=1&crop=1&from=url&id=OySEz&margin=%5Bobject%20Object%5D&originHeight=102&originWidth=414&originalType=binary&ratio=1&rotation=0&showTitle=false&status=done&style=none&title=) | +| StyleSetter | + | 样式设置器 | ![](https://cdn.nlark.com/yuque/0/2022/png/2553587/1644416984306-00aca829-3611-4f4c-b6b6-a20d0da0bfe7.png#crop=0&crop=0&crop=1&crop=1&from=url&id=aWlAc&margin=%5Bobject%20Object%5D&originHeight=1214&originWidth=788&originalType=binary&ratio=1&rotation=0&showTitle=false&status=done&style=none&title=) | +| [TextAreaSetter](https://www.yuque.com/lce/doc/gp36z6?view=doc_embed&from=kb&from=kb&outline=1&title=1) | string | 长文本型数据设置器，可换行 | ![](https://cdn.nlark.com/yuque/0/2022/png/242652/1644395843901-4d9c3e04-f6fc-4d50-93ed-44e6d8a99b9a.png#crop=0&crop=0&crop=1&crop=1&from=url&id=grvEZ&margin=%5Bobject%20Object%5D&originHeight=292&originWidth=1026&originalType=binary&ratio=1&rotation=0&showTitle=false&status=done&style=none&title=) | +| TimePicker | + | 时间型数据设置器 | + | +| [VariableSetter](https://www.yuque.com/lce/doc/lkvb36?view=doc_embed&from=kb&from=kb&outline=1&title=1) | any | 变量型数据设置器， | ![](https://cdn.nlark.com/yuque/0/2022/png/242652/1644395524553-dba00e02-f44c-429f-a8f4-c0e5f6d8b35f.png#crop=0&crop=0&crop=1&crop=1&from=url&id=L5BHL&margin=%5Bobject%20Object%5D&originHeight=92&originWidth=578&originalType=binary&ratio=1&rotation=0&showTitle=false&status=done&style=none&title=) | diff --git a/docs/docs/guide/create/_category_.json b/docs/docs/guide/create/_category_.json new file mode 100644 index 000000000..a5b30e063 --- /dev/null +++ b/docs/docs/guide/create/_category_.json @@ -0,0 +1,6 @@ +{ + "label": "创建低代码应用", + "position": 1, + "collapsed": false, + "collapsible": true +} diff --git a/docs/docs/guide/create/useEditor.md b/docs/docs/guide/create/useEditor.md new file mode 100644 index 000000000..aca9faf68 --- /dev/null +++ b/docs/docs/guide/create/useEditor.md @@ -0,0 +1,184 @@ +--- +title: 接入编辑器 +sidebar_position: 0 +--- + +您有两种方式初始化低代码编辑器： + +1. clone 低代码项目的官方 demo，直接启动项目。适合普通人。 +2. 手工引入低代码 UMD 包，手工配置、打包和启动。适合 Webpack 配置工程师。 + +# 方法 1: Clone 并启动 + +可以通过两种方式之一获取低代码编辑器的示例代码： + +1. 直接[在 github 仓库下](https://github.com/alibaba/lowcode-demo)进行下载 + +![Rectangle 2.png](https://cdn.nlark.com/yuque/0/2022/png/242652/1645178084931-b81f6960-f0be-4695-ae38-e2632c859629.png#clientId=u6721b06e-9fb2-4&crop=0&crop=0&crop=1&crop=1&from=paste&height=259&id=ud829c08c&margin=%5Bobject%20Object%5D&name=Rectangle%202.png&originHeight=517&originWidth=1500&originalType=binary&ratio=1&rotation=0&showTitle=false&size=163331&status=done&style=none&taskId=ua56b6104-b23f-4dd6-a95c-4fa8ac8cb3c&title=&width=750) + +2. 如果本地安装了 git，可以通过 git clone 方式进行下载 + +（这个方法的好处是 demo 有了更新，可以通过 merge 方式跟上） +```typescript +git clone https://github.com/alibaba/lowcode-demo.git +``` + +拉取仓库代码后，需要进行如下配置或安装过程： + +1. 确保本地安装了 Node.js 和 npm，如果没有，[您可以通过 nvm 进行快捷的安装](https://github.com/nvm-sh/nvm) +2. 确保为 npm [设置了可以访问的 npm 源，保证安装过程无网络问题](https://npmmirror.com/) +3. 执行 `npm install` + +依赖完全安装完成后，执行 `npm start`，如果看到这个界面，说明项目启动成功。您可以继续看后续章节了。本章节后续内容均为高级配置方式。 + +![image.png](https://cdn.nlark.com/yuque/0/2022/png/242652/1644982015764-35bb5f58-fbd6-4838-9792-3c5b2136162d.png#clientId=ub335956d-fdf2-4&crop=0&crop=0&crop=1&crop=1&from=paste&height=817&id=u01bca493&margin=%5Bobject%20Object%5D&name=image.png&originHeight=1634&originWidth=3060&originalType=binary&ratio=1&rotation=0&showTitle=false&size=216709&status=done&style=stroke&taskId=u467c43dc-35c5-4c84-907d-d6db9a0b839&title=&width=1530) + +# 方法 2: 手工引入低代码 UMD 包，手工配置打包和启动 + +如果您不是从零开始的项目，您可能需要手工引入低代码引擎。 + +## 引入 UMD 包资源 + +我们需要在启动前，正确在项目中通过 UMD 包方式直接依赖如下内容： +（亦可使用异步加载工具，如果您按照正确的顺序进行加载） +```html + + + + + + + + + + + + + + + + + + + + + + + + + + +``` +> 注：如果 unpkg 的服务比较缓慢，您可以使用 alicdn 来获得确定版本的低代码引擎，如对于引擎的 1.0.1 版本，可用 [https://alifd.alicdn.com/npm/@alilc/lowcode-engine@1.0.1/dist/js/engine-core.js](https://alifd.alicdn.com/npm/@alilc/lowcode-engine@1.0.1/dist/js/engine-core.js) + + +## 配置打包 + +因为这些资源已经通过 UMD 方式引入，所以在 Webpack 等构建工具中需要配置它们为 external，不再重复打包： + +```javascript +{ + "externals": { + "react": "var window.React", + "react-dom": "var window.ReactDOM", + "prop-types": "var window.PropTypes", + "@alifd/next": "var window.Next", + "@alilc/lowcode-engine": "var window.AliLowCodeEngine", + "@alilc/lowcode-editor-core": "var window.AliLowCodeEngine.common.editorCabin", + "@alilc/lowcode-editor-skeleton": "var window.AliLowCodeEngine.common.skeletonCabin", + "@alilc/lowcode-designer": "var window.AliLowCodeEngine.common.designerCabin", + "@alilc/lowcode-engine-ext": "var window.AliLowCodeEngineExt", + "@ali/lowcode-engine": "var window.AliLowCodeEngine", + "moment": "var window.moment", + "lodash": "var window._" + } +} +``` + +## 初始化低代码编辑器 + +### 方法 2.1 使用 init 进行初始化 + +正确引入后，我们可以直接通过 window 上的变量进行引用，如 `window.AliLowCodeEngine.init`。您可以直接通过此方式初始化低代码引擎： + +```javascript +// 确保在执行此命令前，在 中已有一个 id 为 lce-container 的
+window.AliLowCodeEngine.init(document.getElementById('lce-container'), { + enableCondition: true, + enableCanvasLock: true, +}); +``` + +如果您的项目中使用了 TypeScript，您可以通过如下 devDependencies 引入相关包，并获得对应的类型推断。 +```javascript +// package.json +{ + "devDependencies": { + "@alilc/lowcode-engine": "beta" + } +} +``` +```javascript +import { init } from '@alilc/lowcode-engine'; + +init(document.getElementById('lce-container'), { + enableCondition: true, + enableCanvasLock: true, +}); +``` + +init 的功能包括但不限于： + +1. 传递 options 并设置 config 对象； +2. 传递 preference 并设置 plugins 入参； +3. 初始化 Workbench； + +> 本节中的低代码编辑器例子可以在 demo 中找到：[https://github.com/alibaba/lowcode-demo/blob/main/src/index.ts#L21-L34](https://github.com/alibaba/lowcode-demo/blob/main/src/index.ts#L21-L34) + + +### 方法 2.2 使用 skeletonCabin.Workbench 方式初始化 + +`init()` 内部会调用 `ReactDOM.render()` 函数，因此这样初始化的内容没有办法与外部的 React 组件进行通信，也就没有办法在一些自定义的 plugin 中获取 redux 上的全局数据等内容。 +因此，这种场景下您可以通过 `skeletonCabin.Workbench` 进行初始化。 + +> 注：您不需要同时使用 2.1 和 2.2 的方法。根据使用场景，只有需要低代码引擎插件和外界进行一定通信时，2.2 提供的方法才是必要的。 + + +```javascript +import React, { useState, useEffect } from 'react' +import { project, plugins, common, skeleton } from '@alilc/lowcode-engine' + +// 此 schema 参考 demo 中的默认 schema 书写 +import userSchema from './schema.json' + +export default function EditorView() { + /** 插件是否已初始化成功，因为必须要等插件初始化后才能渲染 Workbench */ + const [hasPluginInited, setHasPluginInited] = useState(false); + + useEffect(() => { + plugins.init().then(() => { + setHasPluginInited(true) + }).catch(err => console.error(err)) + }, []); + + useEffect(() => { + project.importSchema(userSchema) + }, [userSchema]); + + if (!hasPluginInited) { + return null; + } + + return ( + + ); +} +``` + +> 本节中的低代码编辑器类似的例子可以在 demo 中找到：[https://github.com/alibaba/lowcode-demo/blob/main/src/scenarios/custom-initialization/index.tsx](https://github.com/alibaba/lowcode-demo/blob/main/src/scenarios/custom-initialization/index.tsx) + + +# 配置低代码编辑器 +详见“低代码扩展简述“章节。 diff --git a/docs/docs/guide/create/useRenderer.md b/docs/docs/guide/create/useRenderer.md new file mode 100644 index 000000000..4f7a0a08b --- /dev/null +++ b/docs/docs/guide/create/useRenderer.md @@ -0,0 +1,100 @@ +--- +title: 接入运行时 +sidebar_position: 1 +--- + +低代码引擎的编辑器将产出两份数据： + +- 资产包数据 assets：包含物料名称、包名及其获取方式，对应协议中的[《低代码引擎资产包协议规范》](https://lowcode-engine.cn/assets) +- 页面数据 schema：包含页面结构信息、生命周期和代码信息，对应协议中的[《低代码引擎搭建协议规范》](https://lowcode-engine.cn/lowcode) + +经过上述两份数据，可以直接交由渲染模块或者出码模块来运行，二者的区别在于： + +- 渲染模块：使用资产包数据、页面数据和低代码运行时，并且允许维护者在低代码编辑器中用 Low Code 的方式继续维护； +- 出码模块：不依赖低代码运行时和页面数据，直接生成可直接运行的代码，并且允许维护者用 Pro Code 的方式继续维护，但无法再利用用低代码编辑器； + +## 渲染模块 + +[在 Demo 中](https://lowcode-engine.cn/demo)，右上角有渲染模块的示例使用方式： +![Mar-13-2022 16-52-49.gif](https://cdn.nlark.com/yuque/0/2022/gif/242652/1647161579197-20c72ea4-6d9a-4692-9b23-005182f6387e.gif#clientId=u244806d0-100a-4&crop=0&crop=0&crop=1&crop=1&from=ui&id=u9b403d3d&margin=%5Bobject%20Object%5D&name=Mar-13-2022%2016-52-49.gif&originHeight=514&originWidth=1534&originalType=binary&ratio=1&rotation=0&showTitle=false&size=755539&status=done&style=stroke&taskId=u14f0f4c2-4d6c-4296-b2df-ccda870faff&title=) + +基于官方提供的渲染模块 [@alifd/lowcode-react-renderer](https://github.com/alibaba/lowcode-engine/tree/main/packages/react-renderer)，你可以在 React 上下文渲染低代码编辑器产出的页面。 + +### 构造渲染模块所需数据 + +渲染模块所需要的数据需要通过编辑器产出的数据进行一定的转换，规则如下： + +- schema：从编辑器产出的 projectSchema 中拿到 componentsTree 中的首项，即 `projectSchema.componentsTree[0]`； +- components：需要根据编辑器产出的资产包 assets 中，根据页面 projectSchema 中声明依赖的 componentsMap，来加载所有依赖的资产包，最后获取资产包的实例并生成物料 - 资产包的键值对 components。 + +这个过程可以参考 demo 项目中的 `src/preview.tsx`： +```typescript +async function getSchemaAndComponents() { + const packages = JSON.parse(window.localStorage.getItem('packages') || ''); + const projectSchema = JSON.parse(window.localStorage.getItem('projectSchema') || ''); + const { componentsMap: componentsMapArray, componentsTree } = projectSchema; + const componentsMap: any = {}; + componentsMapArray.forEach((component: any) => { + componentsMap[component.componentName] = component; + }); + const schema = componentsTree[0]; + + const libraryMap = {}; + const libraryAsset = []; + packages.forEach(({ package: _package, library, urls, renderUrls }) => { + libraryMap[_package] = library; + if (renderUrls) { + libraryAsset.push(renderUrls); + } else if (urls) { + libraryAsset.push(urls); + } + }); + + const vendors = [assetBundle(libraryAsset, AssetLevel.Library)]; + + const assetLoader = new AssetLoader(); + await assetLoader.load(libraryAsset); + const components = await injectComponents(buildComponents(libraryMap, componentsMap)); + + return { + schema, + components, + }; +} +``` + +### 进行渲染 + +拿到 schema 和 components 以后，您可以借由资产包数据和页面数据来完成页面的渲染： +```tsx +import React from 'react'; +import ReactRenderer from '@alilc/lowcode-react-renderer'; + +const SamplePreview = () => { + return ( + + ) +} +``` + +> 注：您可以注意到，此处是依赖了 React 进行渲染的，对于 Vue 形态的渲染或编辑器支持，详见[对应公告](https://github.com/alibaba/lowcode-engine/issues/236)。 +> 本节示例可在 Demo 代码里找到：[https://github.com/alibaba/lowcode-demo/blob/main/src/preview.tsx](https://github.com/alibaba/lowcode-demo/blob/main/src/preview.tsx#L54-L58) + + +## 出码模块 + +[在 Demo 中](https://lowcode-engine.cn/demo)，右上角有出码模块的示例使用方式： +![Mar-13-2022 16-55-56.gif](https://cdn.nlark.com/yuque/0/2022/gif/242652/1647161777243-b16045c4-3cac-4920-8e68-ce064a90fe26.gif#clientId=u244806d0-100a-4&crop=0&crop=0&crop=1&crop=1&from=ui&id=ud7bfd5a2&margin=%5Bobject%20Object%5D&name=Mar-13-2022%2016-55-56.gif&originHeight=514&originWidth=1536&originalType=binary&ratio=1&rotation=0&showTitle=false&size=1727314&status=done&style=stroke&taskId=u4e079100-d6a0-4ad2-ac0c-938ab8e7759&title=) + +> 本节示例可在出码插件里找到：[https://github.com/alibaba/lowcode-code-generator-demo](https://github.com/alibaba/lowcode-code-generator-demo) + + +## 低代码的生产和消费 + +经过“接入编辑器” - “接入运行时” 这两节的介绍，我们已经可以了解到低代码所构建的生产和消费流程了，梳理如下图： +![image.png](https://cdn.nlark.com/yuque/0/2022/png/242652/1644405393410-1c54fa37-74de-4c48-a4a9-1cbce359feeb.png#clientId=ua752ee55-c225-4&crop=0&crop=0&crop=1&crop=1&from=paste&height=396&id=u4ceefadb&margin=%5Bobject%20Object%5D&name=image.png&originHeight=1786&originWidth=3206&originalType=binary&ratio=1&rotation=0&showTitle=false&size=312489&status=done&style=none&taskId=uae8eacd1-4c05-4689-bb6a-24ceb76327d&title=&width=710) + +如上述流程所示，您一般需要一个后端项目来保存页面数据信息，如果资产包信息是动态的，也需要保存资产包信息。 diff --git a/docs/docs/guide/design/_category_.json b/docs/docs/guide/design/_category_.json new file mode 100644 index 000000000..1868732be --- /dev/null +++ b/docs/docs/guide/design/_category_.json @@ -0,0 +1,6 @@ +{ + "label": "引擎设计原理", + "position": 3, + "collapsed": false, + "collapsible": true +} diff --git a/docs/docs/guide/design/datasourceEngine.md b/docs/docs/guide/design/datasourceEngine.md new file mode 100644 index 000000000..1ea076866 --- /dev/null +++ b/docs/docs/guide/design/datasourceEngine.md @@ -0,0 +1,153 @@ +--- +title: 数据源引擎设计 +sidebar_position: 7 +--- +## 核心原理 + +考虑之后的扩展性和兼容性，核心分为了 2 类包，一个是 **datasource-engine** ，另一个是 **datasource-engine-x-handler** ，x 的意思其实是对应数据源的 type，比如说 **datasource-engine-mtop-handler**，也就是说我们会将真正的请求工具放在 handler 里面去处理，engine 在使用的时候由使用方自身来决定需要注册哪些 handler，这样的目的有 2 个，一个是如果将所有的 handler 都放到一个包，对于端上来说这个包过大，有一些浪费资源和损耗性能的问题，另一个是如果有新的类型的数据源出现，只需要按照既定的格式去新增一个对应的 handler 处理器即可，达到了高扩展性的目的； + +![](https://intranetproxy.alipay.com/skylark/lark/0/2020/png/275191/1599545889374-73acbe09-3bb6-4df9-b6f9-80a86764afa2.png?x-oss-process=image%2Fresize%2Cw_720#crop=0&crop=0&crop=1&crop=1&id=zq0Rr&originHeight=370&originWidth=720&originalType=binary&ratio=1&rotation=0&showTitle=false&status=done&style=none&title=) + +### DataSourceEngine + +- engine： engine 主要分 2 类，一类是面向 render 引擎的，可以从 engine/interpret 引入，一类是面向出码或者说直接单纯使用数据源引擎的场景，可以从 engine/runtime 引入，代码如下 + +```javascript +import { createInterpret, createRuntime } from '@alilc/lowcode-datasource-engine'; +``` + +create 方法定义如下 + +```javascript +interface IDataSourceEngineFactory { + create(dataSource: DataSource, context: Omit, extraConfig?: { + requestHandlersMap: RequestHandlersMap; + [key: string]: any; + }): IDataSourceEngine; +} +``` + +create 接收三个参数，第一个是 DataSource，对于运行时渲染和出码来说，DataSource 的定义分别如下： + +```javascript +/** + * 数据源对象--运行时渲染 + * @see https://yuque.antfin-inc.com/mo/spec/spec-low-code-building-schema#XMeF5 + */ +export interface DataSource { + list: DataSourceConfig[]; + dataHandler?: JSFunction; +} +/** + * 数据源对象 + * @see https://yuque.antfin-inc.com/mo/spec/spec-low-code-building-schema#XMeF5 + */ +export interface DataSourceConfig { + id: string; + isInit: boolean | JSExpression; + type: string; + requestHandler?: JSFunction; + dataHandler?: JSFunction; + options?: { + uri: string | JSExpression; + params?: JSONObject | JSExpression; + method?: string | JSExpression; + isCors?: boolean | JSExpression; + timeout?: number | JSExpression; + headers?: JSONObject | JSExpression; + [option: string]: CompositeValue; + }; + [otherKey: string]: CompositeValue; +} +``` + +但是对于出码来说，create 和 DataSource 定义如下： + +```javascript +export interface IRuntimeDataSourceEngineFactory { + create(dataSource: RuntimeDataSource, context: Omit, extraConfig?: { + requestHandlersMap: RequestHandlersMap; + [key: string]: any; + }): IDataSourceEngine; +} + +export interface RuntimeOptionsConfig { + uri: string; + params?: Record; + method?: string; + isCors?: boolean; + timeout?: number; + headers?: Record; + shouldFetch?: () => boolean; + [option: string]: unknown; +} +export declare type RuntimeOptions = () => RuntimeOptionsConfig; // 考虑需要动态获取值的情况，这里在运行时会真正的转为一个 function + +export interface RuntimeDataSourceConfig { + id: string; + isInit: boolean; + type: string; + requestHandler?: () => {}; + dataHandler: (data: unknown, err?: Error) => {}; + options?: RuntimeOptions; + [otherKey: string]: unknown; +} +/** + * 数据源对象 + * @see https://yuque.antfin-inc.com/mo/spec/spec-low-code-building-schema#XMeF5 + */ +export interface RuntimeDataSource { + list: RuntimeDataSourceConfig[]; + dataHandler?: (dataMap: DataSourceMap) => void; +} +``` + +2 者的区别还是比较明显的，一个是带 js 表达式一类的字符串，另一个是真正转为直接可以运行的 js 代码，对于出码来说，转为可执行的 js 代码的过程是出码自身负责的，对于渲染引擎来说，它只能接受到初始的 schema json 所以需要数据源引擎来做转化 + +- context：数据源引擎内部有一些使用了 this 的表达式，这些表达式需要求值的时候依赖上下文，因此需要将当前的上下文丢给数据源引擎，另外在 handler 里面去赋值的时候，也会用到诸如 setState 这种上下文里面的 api，当然，这个是可选的，我们后面再说。 + +```javascript +/** + * 运行时上下文--暂时是参考 react，当然可以自己构建，完全没问题 + */ +export interface IRuntimeContext> { + /** 当前容器的状态 */ + readonly state: TState; + /** 设置状态(浅合并) */ + setState(state: Partial): void; + /** 自定义的方法 */ + [customMethod: string]: any; + /** 数据源, key 是数据源的 ID */ + dataSourceMap: Record; + /** 重新加载所有的数据源 */ + reloadDataSource(): Promise; + /** 页面容器 */ + readonly page: IRuntimeContext & { + readonly props: Record; + }; + /** 低代码业务组件容器 */ + readonly component: IRuntimeContext & { + readonly props: Record; + }; +} +``` + +- extraConfig：这个字段是为了留着扩展用的，除了一个必填的字段 **requestHandlersMap** + +```javascript +export declare type RequestHandler = (ds: RuntimeDataSourceConfig, context: IRuntimeContext) => Promise>; +export declare type RequestHandlersMap = Record; +``` + +RequestHandlersMap 是一个把数据源以及对应的数据源 handler 关联起来的桥梁，它的 key 对应的是数据源 DataSourceConfig 的 type，比如 mtop/http/jsonp ... ，每个类型的数据源在真正使用的时候会调用对应的 type-handler，并将当前的参数和上下文带给对应的 handler。 + +create 调用结束后，可以获取到一个 DataSourceEngine 实例 + +```javascript +export interface IDataSourceEngine { + /** 数据源, key 是数据源的 ID */ + dataSourceMap: Record; + /** 重新加载所有的数据源 */ + reloadDataSource(): Promise; +} +``` diff --git a/docs/docs/guide/design/editor.md b/docs/docs/guide/design/editor.md new file mode 100644 index 000000000..d861ae7d6 --- /dev/null +++ b/docs/docs/guide/design/editor.md @@ -0,0 +1,283 @@ +--- +title: 编排模块设计 +sidebar_position: 3 +--- +本篇重点介绍如何从零开始设计编排模块，设计思路是什么？思考编排的本质是什么？围绕着本质，如何设计并实现对应的功能模块。 + +![image.png](https://cdn.nlark.com/yuque/0/2022/png/242652/1644397577227-99a77c7d-6a6e-4d92-b222-eaac0ee7988e.png#clientId=u45d0137b-8a6f-4&crop=0&crop=0&crop=1&crop=1&from=paste&height=540&id=u4613aa03&margin=%5Bobject%20Object%5D&name=image.png&originHeight=1080&originWidth=1920&originalType=binary&ratio=1&rotation=0&showTitle=false&size=911801&status=done&style=none&taskId=u449864e5-516f-41eb-b86a-7c026b797a8&title=&width=960) + +# 编排是什么 +所谓编排，即将设计器中的所有物料，进行布局设置、组件设置、交互设置（JS编写/逻辑编排）后，形成符合业务诉求的 schema 描述。 +# 编排的本质 +首先，思考编排的本质是什么？ +编排的本质是生产符合《阿里巴巴中后台前端搭建协议规范》的数据**，**在这个场景里，协议是通过 JSON 来承载的。如： +```json +{ + "componentName": "Page", + "props": { + "layout": "wide", + }, + "children": [ + { + "componentName": "Button", + "props": { + "size": "large" + } + } + ] +} +``` + +可是在真实场景，节点数可能有成百上千，每个节点都具有新增、删除、修改、移动、插入子节点等操作，同时还有若干约束，JSON 结构操作起来不是很便利，于是我们仿 DOM 设计了 **节点模型 & 属性模型，**用更具可编程性的方式来编排，这是**编排系统的基石**。 +其次，每次编排动作后（CRUD），都需要实时的渲染出视图。广义的视图应该包括各种平台上的展现，浏览器、Rax、小程序、Flutter 等等，所以使用何种渲染器去渲染 JSON 结构应该可以由用户去扩展，我们定义一种机制去衔接设计态和渲染态。 +至此，我们已经完成了**编排模块最基础的功能**，接下来，就是完善细节，逐步丰满功能。比如： +1）编排面板的整体功能区划分设计； +2）节点属性设计；节点删除、移动等操作设计；容器节点设计； +3）节点拖拽功能、拖拽定位设计和实现； +4）节点在画布上的辅助功能，比如 hover、选中、选中时的操作项、resize、拖拽占位符等； +5）设计态和渲染态的坐标系转换，滚动监听等； +6）快捷键机制； +7）历史功能，撤销和重做； +8）结构化的插件扩展机制； +9）原地编辑功能； +有非常多模块，但只要记住一点，这些功能的目的都是辅助用户在画布上有更好的编排体验、扩展能力而逐个增加设计的。 +# 编排功能模块 +## 模型设计 +编排实际上操作 schema，但是实际代码运行的过程中，我们将 schema 分成了很多层，每一层有各自的职责，他们所负责的功能是明确清晰的。这就是低代码引擎中的模型设计。 +我们通过将 schema 和常用的操作等结合起来，最终将低代码引擎的模型分为节点模型、属性模型、文档模型和项目模型。 +### 项目模型（`Project`） +项目模型提供项目管理能力。通常一个引擎启动会默认创建一个 `Project` 实例，有且只有一个。项目模型实例下可以持有多个文档模型的实例，而当前处于设计器设计状态的文档模型，我们将其添加 active 标识，也将其称为 `currentDocument`，可以通过 `project.currentDocument` 获得。 +一个 `Project` 包含若干个 `DocumentModel` 实例，即项目模型和文档模型的关系是 1 对 n，如下图所示： + +![image.png](https://cdn.nlark.com/yuque/0/2022/png/242652/1644397244733-2492a7bf-20bf-4610-a335-99cc047037b7.png#clientId=u45d0137b-8a6f-4&crop=0&crop=0&crop=1&crop=1&from=paste&height=824&id=uadf98e25&margin=%5Bobject%20Object%5D&name=image.png&originHeight=1648&originWidth=1226&originalType=url&ratio=1&rotation=0&showTitle=false&size=1260603&status=done&style=none&taskId=u50b01e40-96f2-4629-a1b9-1b5a22967fc&title=&width=613) +### 文档模型（`DocumentModel`） +文档模型提供文档管理的能力，每一个页面即一个文档流，对应一个文档模型。文档模型包含了一组 Node 组成的一颗树，类似于 DOM。我们可以通过文档模型来操作 `Node` 树，来达到管理文档模型的能力。每一个文档模型对应多个 `Node`，但是根 `Node` 只有一个，即 `rootNode` 和 `nodes`。 +文档模型可以通过 `Node` 树，通过 `doc.schema` 来导出文档的 `schema`，并使用其进行渲染。 +他们的关系如下图： +![image.png](https://cdn.nlark.com/yuque/0/2022/png/242652/1644397244327-d931aff8-40d4-47df-8b1c-b81c06c40c48.png#clientId=u45d0137b-8a6f-4&crop=0&crop=0&crop=1&crop=1&from=paste&height=745&id=L5LAf&margin=%5Bobject%20Object%5D&name=image.png&originHeight=1490&originWidth=960&originalType=url&ratio=1&rotation=0&showTitle=false&size=1110316&status=done&style=none&taskId=u7d873681-f61a-40ea-baaa-8f7b76c769c&title=&width=480) +### 节点模型（`Node`） +我们先看一下一个 `Node` 在 `schema` 中对应的示例： +```json +{ + componentName: 'Text', + id: 'node_k1ow3cbf', + props: { + showTitle: false, + behavior: 'NORMAL', + content: { + use: 'zh_CN', + en_US: 'Title', + zh_CN: '个人信息', + type: 'i18n', + }, + fieldId: 'text_k1ow3h1j', + maxLine: 0, + }, + condition: true, +} +``` +上面的示例是一个 `Text` 的 `Node` 节点，而我们的 `Node` 节点模型就是负责这一层级的 `Schema` 管理。它的功能聚焦于单层级的 schema 相关操作。我们可以看一下节点模型的一些方法，了解其功能。 +```typescript +declare class Node { + // Props + props: Props; + get propsData(): PropsMap | PropsList | null; + getProp(path: string, stash?: boolean): Prop | null; + getPropValue(path: string): any; + setPropValue(path: string, value: any): void; + clearPropValue(path: string): void; + mergeProps(props: PropsMap): void; + setProps(props?: PropsMap | PropsList | Props | null): void; + + // Node + get parent(): ParentalNode | null; + get children(): NodeChildren | null; + get nextSibling(): Node | null; + get prevSibling(): Node | null; + remove(useMutator?: boolean, purge?: boolean): void; + select(): void; + hover(flag?: boolean): void; + replaceChild(node: Node, data: any): Node; + mergeChildren(remover: () => any, adder: (children: Node[]) => NodeData[] | null, sorter: () => any): void; + removeChild(node: Node): void; + insert(node: Node, ref?: Node, useMutator?: boolean): void; + insertBefore(node: any, ref?: Node, useMutator?: boolean): void; + insertAfter(node: any, ref?: Node, useMutator?: boolean): void; + + // Schema + get schema(): Schema; + set schema(data: Schema); + export(stage?: TransformStage): Schema; + replaceWith(schema: Schema, migrate?: boolean): any; +} +``` +这里没有展示全部的方法，但是我们可以发现，`Node` 节点模型核心功能点有三个 +1）`Props` 管理：通过 `Props` 实例管理所有的 `Prop`，包括新增、设置、删除等 `Prop` 相关操作。 +2）`Node` 管理：管理 `Node` 树的关系，修改当前 `Node` 节点或者 `Node` 子节点等。 +3）`Schema` 管理：可以通过 `Node` 获取当前层级的 `Schema` 描述协议内容，并且也可以修改它。 +通过 `Node` 这一层级，对 `Props`、`Node` 树和 `Schema` 的管理粒度控制到最低，这样扩展性也就更强。 +### 属性模型（Prop） +一个 `Props` 对应多个 `Prop`，每一个 `Prop` 对应 schema 的 `props` 下的一个字段。 +`Props` 管理的是 `Node` 节点模型中的 `props` 字段下的内容。而 `Prop` 管理的是 `props` 下的每一个 `key` 的内容，例如下面的示例中，一个 `Props` 管理至少 6 个 `Prop`，而其中一个 `Prop` 管理的是 `showTitle` 的结果。 +```typescript +{ + props: { + showTitle: false, + behavior: 'NORMAL', + content: { + use: 'zh_CN', + en_US: 'Title', + zh_CN: '个人信息', + type: 'i18n', + }, + fieldId: 'text_k1ow3h1j', + maxLine: 0, + }, +} +``` +### 组件描述模型（ComponentMeta） +编排已经等价于直接操作节点 & 属性了，而一个节点和一组对应的属性相当于一个真实的组件，而真实的组件一定是有约束的，比如组件名、组件类型、支持哪些属性以及属性类型、组件能否拖动、支持哪些扩展操作、组件是否是容器型组件、A 组件中能否放入 B 组件等等。 +于是，我们设计了一份协议专门负责组件描述，即《中后台搭建组件描述协议》，而编排模块中也有负责解析和使用符合描述协议规范的模块。 +每一个组件对应一个 `ComponentMeta` 的实例，其属性和方法就是描述协议中的所有字段，所有 `ComponentMeta` 都由设计器器的 `designer` 模块进行创建和管理，其他模块通过 `designer` 来获取指定的 `ComponentMeta` 实例，尤其是每个 `Node` 实例上都会挂载对应的 `ComponentMeta` 实例。 +![image.png](https://cdn.nlark.com/yuque/0/2022/png/242652/1644397244032-8aa176d5-a74e-49c9-a309-251dba81b37c.png#clientId=u45d0137b-8a6f-4&crop=0&crop=0&crop=1&crop=1&from=paste&id=u044bdacd&margin=%5Bobject%20Object%5D&name=image.png&originHeight=756&originWidth=998&originalType=url&ratio=1&rotation=0&showTitle=false&size=294191&status=done&style=none&taskId=uee9dfeef-f646-41db-afd4-a0b1acf8019&title=) +组件描述模型是后续编排辅助的基础，包括设置面板、拖拽定位机制等。 +### 项目、文档、节点和属性模型关系 +整体来看，一个 Project 包含若干个 DocumentModel 实例，每个 DocumentModel 包含一组 Node 构成一颗树（类似 DOM 树），每个 Node 通过 Props 实例管理所有 Prop。整体的关系图如下。 +![image.png](https://cdn.nlark.com/yuque/0/2022/png/110793/1645066478805-57802de7-382e-4105-99cb-161b8c07f117.png#clientId=uf22d1b91-761d-4&crop=0&crop=0&crop=1&crop=1&from=paste&height=678&id=uc2db9afa&margin=%5Bobject%20Object%5D&name=image.png&originHeight=1356&originWidth=1694&originalType=binary&ratio=1&rotation=0&showTitle=false&size=285816&status=done&style=none&taskId=u6526eafb-f082-46dd-8584-9dd9b1bb395&title=&width=847) +节点 & 属性模型是引擎基石，几乎贯穿所有模块，相信从上面的类图已经能看出几个基础类的职责以及依赖关系。 +节点 & 属性模型等价于 JSON 数据结构，而编排的本质是产出 JSON 数据结构，现在可以重新表述为编排的本质是操作节点 & 属性模型了。 +```typescript +// 一段编排的示例代码 +rootNode.insertAfter({ componentName: 'Button', props: { size: 'medium' } }); +rootNode.insertAfter({ componentName: 'Button', props: { size: 'medium' } }); +rootNode.children.get(1).getProp('size').setValue('large'); +rootNode.children.get(2).remove(); +rootNode.export(); +// => 产出 schema +``` + +## 画布渲染 +画布渲染使用了设计态与渲染态的双层架构。![image.png](https://cdn.nlark.com/yuque/0/2022/png/242652/1644397244328-61bb9ce7-a27c-4917-baee-c0a93bd0fd36.png#clientId=u45d0137b-8a6f-4&crop=0&crop=0&crop=1&crop=1&from=paste&id=u3c9164cd&margin=%5Bobject%20Object%5D&name=image.png&originHeight=710&originWidth=1416&originalType=url&ratio=1&rotation=0&showTitle=false&size=287707&status=done&style=none&taskId=u6c993606-238b-478f-9317-397eb0708eb&title=) +如上图，设计器和渲染器其实处在不同的 Frame 下，渲染器以单独的 `iframe` 嵌入。这样做的好处，一是为了给渲染器一个更纯净的运行环境，更贴近生产环境，二是扩展性考虑，让用户基于接口约束自定义自己的渲染器。 + +### xxx-renderer +xxx-renderer 是一个纯 renderer，即一个渲染器，通过给定输入 schema、依赖组件和配置参数之后完成渲染。 + +### xxx-simulator-renderer +xxx-simulator-renderer 通过和 host进行通信来和设计器打交道，提供了 `DocumentModel` 获取 schema 和组件。将其传入 xxx-renderer 来完成渲染。 +另外其提供了一些必要的接口，来帮助设计器完成交互，比如点击渲染画布任意一个位置，需要能计算出点击的组件实例，继而找到设计器对应的 Node 实例，以及组件实例的位置/尺寸信息，让设计器完成辅助 UI 的绘制，如节点选中。 + +### react-simulator-renderer +以官方提供的 react-simulator-renderer 为例，我们看一下点击一个 DOM 节点后编排模块是如何处理的。 +首先在初始化的时候，renderer 渲染的时候会给每一个元素添加 ref，通过 ref 机制在组件创建时将其存储起来。在存储的时候我们给实例添加 `Symbol('_LCNodeId')` 的属性。 +当点击之后，会去根据 `__reactInternalInstance$` 查找相应的 fiberNode，通过递归查找到对应的 React 组件实例。找到一个挂载着 `Symbol('_LCNodeId')` 的实例，也就是上面我们初始化添加的属性。 +通过 `Symbol('_LCNodeId')` 属性，我们可以获取 Node 的 id，这样我们就可以找到 Node 实例。 +通过 `getBoundingClientRect` 我们可以获取到 Node 渲染出来的 DOM 的相关信息，包括 `x`、`y`、`width`、`height` 等。 +通过 DOM 信息，我们将 focus 节点所需的标志渲染到对应的地方。hover、拖拽占位符、resize handler 等辅助 UI 都是类似逻辑。 + +### 通信机制 +既然设计器和渲染器处于两个 Frame，它们之间的事件通信、方法调用是通过各自的代理对象进行的，不允许其他方式，避免代码耦合。 +![image.png](https://cdn.nlark.com/yuque/0/2022/png/242652/1644397245794-927fa812-ea1c-4bc1-967b-4c1dff924fd1.png#clientId=u45d0137b-8a6f-4&crop=0&crop=0&crop=1&crop=1&from=paste&id=u22088dc8&margin=%5Bobject%20Object%5D&name=image.png&originHeight=648&originWidth=1290&originalType=url&ratio=1&rotation=0&showTitle=false&size=223251&status=done&style=none&taskId=uf720b921-07c2-4cda-a101-74e863ce10d&title=) +**host** +host 可以访问设计器的所有模块，由于 renderer 层不负责与设计器相关的交互。所以增加了一层 host，作为通信的中间层。host 可以访问到设计器中所有模块，并提供相关方法供 simulator-renderer 层调用。例如schema 的获取、组件获取等。 +simulator-renderer 通过调用 host 的方法，将 schema、components 等参数传给 renderer，让 renderer 进行渲染。 + +**xxx-simulator-renderer** +为了完成双向交互，simulator-renderer 也需要提供一些方法来供 host 层调用，之后当设计器和用户有交互，例如上述提到的节点选中。这里需要提供的方法有： + +- getClientRects +- getClosestNodeInstance +- findDOMNodes +- getComponent +- setNativeSelection +- setDraggingState +- setCopyState +- clearState + +这样，host 和 simulator-renderer 之间便通过相关方法实现了双向通信，能在隔离设计器的基础上完成设计器到画布和画布到设计器的通信流程。 + +## 编排辅助的核心 +### 设置面板与设置器 +当在渲染画布上点击一个 DOM 节点，我们可以通过 xxx-simulator-renderer 获取 `Node` 节点，我们在 `Node` 上挂载了 `ComponentMeta` 实例。通过 `ComponentMeta` 我们获取到当前组件的描述模型。通过描述模型，我们即可获得组件、即当前 Node 支持的所有属性配置。 +![image.png](https://cdn.nlark.com/yuque/0/2022/png/242652/1644397246381-ed265cc3-b6c1-4a38-985a-df1898862fe8.png#clientId=u45d0137b-8a6f-4&crop=0&crop=0&crop=1&crop=1&from=paste&id=u1422ee5e&margin=%5Bobject%20Object%5D&name=image.png&originHeight=985&originWidth=1500&originalType=url&ratio=1&rotation=0&showTitle=false&size=332497&status=done&style=none&taskId=u2bbbb9ae-7834-48ba-b87f-fa5ccf8fa39&title=) +#### 设置面板 +设置面板对于配置项的呈现结构是通过 `ComponentMeta.configure` 来确定的。 +```json +{ + "component": { + "isContainer": true + }, + "props": { + "isExtends": true, + "override": [ + { + "name": "count", + "title": { + "label": "展示的数字", + "tip": "count|大于 overflowCount 时显示为 ${overflowCount}+，为 0 时默认隐藏", + "docUrl": "https://fusion.alibaba-inc.com/pc/component/basic/badge" + }, + "setter": { + "componentName": "MixedSetter", + "props": { + "setters": [ + "StringSetter", + "ExpressionSetter" + ] + } + } + } + ] + } +} +``` +上述的 `component.isContainer` 描述了这个组件是否是一个容器组件。而 props 下的属性就是我们在设置面板中展示的属性，包含了这个属性的名称、使用的设置器、配置之后影响的是哪个属性等。 +而这只是描述，编排模块的 `SettingTopEntry` 便是管理设置面板的实现模块。 +`SettingTopEntry` 包含了 n 个 `SettingField`，每一个 `SettingField` 就对应下面要将的设置器。即 `SettingTopEntry` 负责管理多个 `SettingField`。 +#### 设置器 +选中节点可供配置的属性都有相应的设置器配置，比如文本、数字、颜色、JSON、Choice、I18N、表达式 等等，或者混合多种。 +设置器本质上是一个 React 组件，但是设置面板在渲染时会传入当前配置项对应的 `SettingField` 实例，`SettingField` 本质上就是包裹了 `Prop` 实例，设置器内部的行为以及 UI 变化都由设置器自己把控，但当属性值发生变化时需要通过 `SettingField` 下的 `Prop` 来修改值，因为修改 `Prop` 实例就相当于修改了 schema。一方面这样的设置器设置之后，保存的 schema 才是正确的，另外一方面，只有 schema 变化了，才能触发渲染画布重新渲染。 +### 拖拽引擎 & 拖拽定位机制 +![](https://cdn.nlark.com/yuque/0/2022/gif/242652/1644397245744-af8b951c-ee22-4fcb-9175-6f1b0eb2ba37.gif#clientId=u45d0137b-8a6f-4&crop=0&crop=0&crop=1&crop=1&from=paste&id=uf8b286a2&margin=%5Bobject%20Object%5D&originHeight=917&originWidth=1425&originalType=url&ratio=1&rotation=0&showTitle=false&status=done&style=none&taskId=u9b4475cb-bb5c-4c86-9b03-b824bc46b12&title=) +拖拽引擎（`Dragon`）核心完成的工作是将被拖拽对象拖拽到目标位置，涉及到几个概念： + +- 被拖拽对象 - `DragObject` +- 拖拽到的目标位置 - `DropLocation` +- 拖拽感应区 - `ISensor` +- 定位事件 - `LocateEvent` + +#### Sensor +在引擎初始化的时候，我们监听 `document` 和 iframe `contentDocument` 的 `mouse`、`keyboard`、`drag` 事件来感知拖拽的发生。而这些监听的区域我们又称为拖拽感应区，也就是 `Sensor`。`Sensor` 会有多个，因为感应器有多个，默认设置器和设置面板是没有 `Sensor`，但是他们是可以注册 `Sensor` 来增加感应区域，例如大纲树就注册了自己的 `Sensor`。 + +`Sensor` 有两个关键职责： +1）用于事件对象转换，比如坐标系换算 +2）根据拖拽过程中提供的位置信息，结合每一层 `Node` 也就是组件包含的描述信息，知道其是否能作为容器等限制条件，来进行进一步的定位，最后计算出精准信息来进行视图渲染。 + +**拖拽流程** +在引擎初始化的时候，初始化多个 `Sensor`。 +当拖拽开始的时候，开启 `mousemove`、`mouseleave`、`mouseover` 等事件的监听。 +拖拽过程中根据 `mousemove` 的 `MouseEvent` 对象封装出 `LocateEvent` 对象，继而交给相应 `sensor` 做进一步定位处理。 +拖拽结束时，根据拖拽的结果进行 schema 变更和视图渲染。 +最后关闭拖拽开始时的事件监听。 + +#### 拖拽方式 +根据拖拽的对象不同，我们将拖拽分为几种方式： +1）**画布内拖拽：**此时 sensor 是 simulatorHost，拖拽完成之后，会根据拖拽的位置来完成节点的精确插入。 +2）**从组件面板拖拽到画布**：此时的 sensor 还是 simulatorHost，因为拖拽结束的目标还是画布。 +3）**大纲树面板拖拽到画布中**：此时有两个 sensor，一个是大纲树，当我们拖拽到画布区域时，画布区域内的 simulatorHost 开始接管。 +4）画布拖拽到画布中：从画布中开始拖拽时，最新生效的是 simulatorHost，当离开画布到大纲树时，大纲树 sensor 开始接管生效。当拖拽到大纲树的某一个节点下时，大纲树会将大纲树中的信息转化为 schema，然后渲染到画布中。 +## 其他 +引擎的编排能力远远不止上述所描述的功能，这里只描述了其核心和关键的功能。在整个引擎的迭代和设计过程中还有很多细节来使我们的引擎更好用、更容易扩展。 +**schema 处理的管道机制** +通过PropsReducer 的管道机制，用户可以定制自己需要的逻辑，来修改 Schema。 +**组件 metadata 处理的管道机制** +组件的描述信息都收拢在各自的 ComponentMeta 实例内，涉及到的消费方几乎遍及整个编排过程，包括但不限于 组件拖拽、拖拽辅助 UI、设置区、原地编辑、大纲树 等等。 +在用户需要自定义的场景，开放 ComponentMeta 的修改能力至关重要，因此我们设计了 metadata 初始化/修改的管道机制。 +**hotkey & builtin-hotkey** +快捷键的实现，以及引擎内核默认绑定的快捷键行为。 +**drag resize 引擎** +对于布局等类型的组件，支持拖拽改变大小。resize 拖拽引擎根据组件 ComponentMeta 声明来开启，拖拽后，触发组件的钩子函数（`onResizeStart` / `onResize` / `onResizeEnd`），完成 resize 过程。 +**OffsetObserver** +设计态的辅助 UI 需要根据渲染态的视图变化而变化，比如渲染容器滚动了，此时通过 OffsetObserver 做一个动态的监听。 +**插件机制** +我们希望保持引擎内核足够小，但拥有足够强的扩展能力，所有扩展功能都通过插件机制来承载。 diff --git a/docs/docs/guide/design/generator.md b/docs/docs/guide/design/generator.md new file mode 100644 index 000000000..19d34560b --- /dev/null +++ b/docs/docs/guide/design/generator.md @@ -0,0 +1,100 @@ +--- +title: 出码模块设计 +sidebar_position: 5 +--- +本篇主要讲解了出码模块实现的基本思路与一些概念。如需接入出码和定制出码方案，可以参考《[使用出码功能](https://www.yuque.com/lce/doc/cplfv0)》一节。 +# npm 包与仓库信息 +| **NPM 包** | **代码仓库** | **说明** | +| --- | --- | --- | +| [@alilc/lowcode-code-generator](https://www.npmjs.com/package/@alilc/lowcode-code-generator) | [alibaba/lowcode-engine](https://github.com/alibaba/lowcode-engine) +(子目录：modules/code-generator) | 出码模块核心库，支持在 node 环境下运行，也提供了浏览器下运行的 standalone 模式 | +| [@alilc/lowcode-plugin-code-generator](https://www.npmjs.com/package/@alilc/lowcode-plugin-code-generator) | [alibaba/lowcode-code-generator-demo](https://github.com/alibaba/lowcode-code-generator-demo) | 出码示例 -- 浏览器端出码插件 | + +# 出码模块原理 + +出码模块的输入和输出很简单： +![](https://cdn.nlark.com/yuque/0/2022/jpeg/263300/1644825891969-1777dbe4-5ffc-4c94-a022-3aba0c116021.jpeg) + +这里有几个概念： + +- schema: 搭建协议内容，指符合《阿里巴巴中后台前端搭建协议规范》的 schema +- solution：出码方案，指具体的项目框架（如 Rax，Ice.js) +- Source Codes：生成的源代码，以目录树的形式进行描述 + +可以看出，这是一个与用户基本没有交互，通过既定的流程完成整个功能链路的模块。其核心暴露的是一个将搭建协议 schema 按既定的 solution 转换为代码的函数。对于使用者来说就是一个输入输出都确定的黑盒系统。 + +## 出码流程概述 +出码模块和编译器很类似，都是将代码的一种表现形式转换成另一种表现形式，如： + +**编译器流程** +![image.png](https://cdn.nlark.com/yuque/0/2022/png/242652/1644403720547-e5021c3c-0c63-47ea-b8f0-1af79bbae3ef.png#clientId=u70bc6751-fff0-4&crop=0&crop=0&crop=1&crop=1&from=paste&height=246&id=u3b3e3126&margin=%5Bobject%20Object%5D&name=image.png&originHeight=492&originWidth=3228&originalType=binary&ratio=1&rotation=0&showTitle=false&size=110319&status=done&style=none&taskId=u32f55257-a18c-4caa-9334-0b3ca5b0bc0&title=&width=1614) + +**出码模块流程** +![image.png](https://cdn.nlark.com/yuque/0/2022/png/242652/1644402753768-02d402da-dd1a-4783-9021-606e276d4c68.png#clientId=u70bc6751-fff0-4&crop=0&crop=0&crop=1&crop=1&from=paste&height=182&id=GlAz4&margin=%5Bobject%20Object%5D&name=image.png&originHeight=182&originWidth=1536&originalType=binary&ratio=1&rotation=0&showTitle=false&size=23743&status=done&style=none&taskId=ubbea9289-cb03-4fcf-9ce7-22da1ce077b&title=&width=1536) + +## 出码流程详解 +### 协议解析 +协议解析主要是将输入的 schema 解析成更适合出码模块内部使用的数据结构的过程。这样在后面的代码生成过程中就可以直接用这些数据，不必重复解析了。 +![](https://intranetproxy.alipay.com/skylark/lark/0/2021/jpeg/154771/1636960093808-624b5e50-18d6-476d-a951-556912832cdb.jpeg) +主要步骤如下： + +- 解析三方组件依赖 +- 分析 ref API 的使用情况 +- 建立容器之间的依赖关系索引 +- 分析容器内的组件依赖关系 +- 分析路由配置 +- 分析 utils 和 NPM 包依赖关系 +- 其他兼容处理 + +### 前置优化 +前置优化是计划基于策略对 schema 做一些优化。 +主要逻辑分为分析、规则和优化三个部分，组合为一个支持通过配置进行一定程度定制化的策略包。每个策略包会先执行分析器，对输入进行特征提取，然后通过规则对特征进行判断，决定是否执行优化动作： +![](https://intranetproxy.alipay.com/skylark/lark/0/2021/jpeg/154771/1636960832211-0db6925b-c4b5-4be4-a883-fdd52a47e19a.jpeg) + +### 代码生成 +代码生成的流程如下： +![](https://intranetproxy.alipay.com/skylark/lark/0/2021/jpeg/154771/1636975834791-e3fe89f9-cd2d-446f-aa9f-fca0bb1d56c3.jpeg) +如果简单粗暴地拼字符串生成源代码将难以扩展和维护，因此出码模块在代码生成过程中将代码进行了一些抽象化。 +日常开发中，我们常常是基于某一个特定的项目框架，将一些配置、UI 代码、逻辑代码放到他们应该在的地方，最终形成一套可以 run 起来的业务系统。那么其实对于出码这件事，我们也可以层层拆解，**项目 -> 插槽 -> 模块 -> 文件 -> 代码块**（代码片段）。这样就能将复杂的项目产出问题，拆分为一个个相对专注且单一的代码块产出问题，同时也支持组合复用。 +![image.png](https://cdn.nlark.com/yuque/0/2022/png/242652/1644402753919-1f063db3-5ad9-406b-9b45-6eeef79ea38b.png#clientId=u70bc6751-fff0-4&crop=0&crop=0&crop=1&crop=1&height=305&id=LgGUo&margin=%5Bobject%20Object%5D&name=image.png&originHeight=454&originWidth=892&originalType=binary&ratio=1&rotation=0&showTitle=false&size=230321&status=done&style=none&taskId=u50d38d84-3a3e-4c77-af05-8bc5f794643&title=&width=600) +注：中间表达结构即为对 Schema 解析后的结构化产物 + +**插槽** +首先来看下插槽，插槽描述了对应模块在项目中相对路径，并且可以对模块做固定的命名。每个插槽都有一系列插件来完成代码产出工作。生成的一个或多个文件，最终会依照插槽的描述放入项目中。 +```typescript +// 项目模版 +export interface IProjectTemplate { + slots: Record; +} + +// 插槽 +interface IProjectSlot { + path: string[]; + fileName?: string; +} + +// 插槽出码插件配置 +interface IProjectPlugins { + [slotName: string]: BuilderComponentPlugin[]; +} +``` +**代码块** +代码块是出码产物的最小单元，由出码模块插件产出，多个代码块最后会被组装为代码文件。每个代码块通过 name 描述自己，再通过 linkAfter 描述应该跟在哪些 name 的代码块后面。 +```typescript +interface ICodeChunk { + type: ChunkType; // 处理类型 ast | string | json + fileType: string; // 文件类型 js | css | ts ... + name: string; // 代码块名称，与 linkAfter 相关 + subModule?: string; // 模块内文件名，默认是 index + content: ChunkContent; // 代码块内容，数据格式与 type 相关 + linkAfter: string[]; // +} +``` + +### 后置优化 +后置优化分为文件级别和项目级别两种： + +- 文件级别：在生成完一个文件后进行处理 +- 项目级别：在所有文件都生成完了之后进行处理 + +文件级别的后置优化目前主要是有 prettier 这个代码格式化工具。 diff --git a/docs/docs/guide/design/materialParser.md b/docs/docs/guide/design/materialParser.md new file mode 100644 index 000000000..42aaadcf0 --- /dev/null +++ b/docs/docs/guide/design/materialParser.md @@ -0,0 +1,70 @@ +--- +title: 入料模块设计 +sidebar_position: 2 +--- +## 介绍 +入料模块负责物料接入，通过自动扫描、解析源码组件，产出一份符合《中后台低代码组件描述协议》的** **JSON Schema。这份 Schema 包含基础信息和属性描述信息部分，低代码引擎会基于它们在运行时自动生成一份configure 配置，用作设置面板展示。 + +## npm 包与仓库信息 + +- npm 包：@alilc/lowcode-material-parser +- 仓库：[https://github.com/alibaba/lowcode-engine](https://github.com/alibaba/lowcode-engine) 下的 modules/material-parser + +## 原理 +入料模块使用动静态分析结合的方案，动态胜在真实，静态胜在细致，不过全都依赖源码中定义的属性，若未定义，或者定义错误，则无法正确入料。 + +### 整体流程 +大体分为本地化、扫描、解析、转换、校验 5 部分，如下图所示。 +![image.png](https://cdn.nlark.com/yuque/0/2022/png/242652/1644396777217-58246e52-b5b9-4509-8bac-db2820535c39.png#clientId=u41c9ba96-15b6-4&crop=0&crop=0&crop=1&crop=1&from=paste&id=u8b5a70fd&margin=%5Bobject%20Object%5D&name=image.png&originHeight=206&originWidth=2116&originalType=url&ratio=1&rotation=0&showTitle=false&size=51634&status=done&style=none&taskId=u76c5b45a-6fa8-404e-8d8b-f1d6f38438e&title=) + +### 静态解析 +在静态分析时，分为 JS 和 TS 两种情况。 + +#### 静态解析 JS +在 JS 情况下，基于 react-docgen 进行扩展，自定义了 resolver 及 handler，前者用于寻找组件定义，后者用于解析 propTypes、defaultProps 等信息，整体流程图如下： + +![image.png](https://cdn.nlark.com/yuque/0/2022/png/242652/1644396777192-c9d3c3b3-c7d2-4780-b7dc-632349b00edb.png#clientId=u41c9ba96-15b6-4&crop=0&crop=0&crop=1&crop=1&from=paste&id=u3edfb33c&margin=%5Bobject%20Object%5D&name=image.png&originHeight=478&originWidth=2176&originalType=url&ratio=1&rotation=0&showTitle=false&size=93513&status=done&style=none&taskId=ua23bd89a-3d0c-43cf-936b-13080cdc5ef&title=) + +react-docgen 使用 babel 生成语法树，再使用 ast-types 进行遍历去寻找组件节点及其属性类型定义。原本的 react-docgen 只能解析单文件，且不能解析 IIFE、逗号表达式等语法结构(一般出现在转码后的代码中)。笔者对其进行改造，使之可以递归解析多文件去查找组件定义，且能够解开 IIFE，以及对逗号表达式进行转换，以方便后续的组件解析。另外，还增加了子组件解析的功能，即类似 `Button.Group = Group` 这种定义。 + +#### 静态解析 TS +在 TS 情况下，还要再细分为 TS 源码和 TS 编译后的代码。 +TS 源码中，React 组件具有类型签名；TS 编译后的代码中，dts 文件(如有)包含全部的 class / interface / type 类型信息。可以从这些类型信息中获取组件属性描述。整体流程图如下： + +![image.png](https://cdn.nlark.com/yuque/0/2022/png/242652/1644396777193-14c74287-d0cb-4864-ba64-9259a88c8b99.png#clientId=u41c9ba96-15b6-4&crop=0&crop=0&crop=1&crop=1&from=paste&id=ud7fc6e1a&margin=%5Bobject%20Object%5D&name=image.png&originHeight=240&originWidth=2280&originalType=url&ratio=1&rotation=0&showTitle=false&size=59331&status=done&style=none&taskId=u711959ae-241a-48c9-a446-59b9fcdc52e&title=) + +react-docgen 内置了 TypeScript 的 babel 插件，所以也具备解析 interface 的能力，可惜能力有限，babel 只能解析 TS 代码，但没法做类型检查，类型处理是由 react-docgen 实现的，它对于extends/implements/utility 的情况处理不好，并且没有类型推断，虽然可以对其功能进行完善，不过这种情况下，应该借助 TypeScript Compiler 的能力，而非自己造轮子。通过调研，发现市面上有 typescript-react-docgen 这个项目。它在底层依赖了 TypeScript，且产出的数据格式与 react-docgen 一致，所以我们选择基于它进行解析。 + +TypeScript Compiler 会递归解析某个文件中出现及引用的全部类型，当然，前提是已经定义或安装了相应的类型声明。typescript-react-docgen 会调用 TypeScript Compiler 的 API，获取每个文件输出的类型，判断其是否为 React 组件。满足下列条件之一的，会被判定为 React 组件： + +1. 获取其函数签名，如果只有一个入参，或者第一个入参名称为 props ，会被判定为函数式组件； +2. 获取其 `constructor` 方法，如果其返回值包含 props 属性，会被判定为有状态组件。 + +然后，遍历组件的 props 类型，获取每个属性的类型签名字符串，比如 `(a: string) => void`。typescript-react-docgen 可以克服 react-docgen 解析 TypeScirpt 类型的问题，但是每个类型都以字符串的形式来呈现，不利于后续的解析。所以，笔者对其进行了扩展，递归解析每一层的属性值。此外，在函数式组件的判定上，笔者做了完善，会看函数的返回值是否为 `ReactElement` ，若是，才为函数式组件。 + +下面讲对于一些特殊情况的处理。 +**循环定义** +TypeScript 类型可以循环定义，比如下面的 JSON 类型： +```typescript +interface Json { + [x: string]: string | number | boolean | Json | JsonArray; +} +type JsonArray = Array; +``` +因为低代码组件描述协议中没有引用功能，而且也不方便在界面上展示出来，所以这种循环定义无需完全解析，入料模块会在检测到循环定义的时候，把类型简化为 `object` 。对于特殊的类型，如 JSON，可以用相应的 Setter 来编辑。 + +**复杂类型** +TypeScript Compiler 会将合成类型的所有属性展开，比如 `boolean | string`，会被展开为 `true | false | string`，这带来了不必要的精确，我们需要的只是 `boolean | string` 而已。当然，对于这个例子，我们很容易把它还原回 `boolean | string`，然而，对于诸如 `React.ButtonHTMLAttributes & {'data-name': string}` 这种类型，它会把 `ButtonHTMLAttributes` 中众多的属性和 `data-name` 混杂在一起，完全无法分辨，只能以展开的形式提供。这 100 多个属性，如果都放在设置面板，绝对是使用者的噩梦，所以，其结果会被简化为 `object` 。当然，即使没有 `{'data-name': string}`，`ButtonHTMLAttributes` 也是没有单独的 Setter 的，同样会被简化为 `object` 。 + +### 动态解析 +当一个组件，使用静态解析无法入料时，会使用动态解析。 +整体流程图如下： +![image.png](https://cdn.nlark.com/yuque/0/2022/png/242652/1644396776984-d390ec0c-33c6-4468-b68c-555a263b097e.png#clientId=u41c9ba96-15b6-4&crop=0&crop=0&crop=1&crop=1&from=paste&id=ube12dcbd&margin=%5Bobject%20Object%5D&name=image.png&originHeight=449&originWidth=2516&originalType=url&ratio=1&rotation=0&showTitle=false&size=84334&status=done&style=none&taskId=ube349a5b-94c0-4a77-9bf3-ffe453226e1&title=) +基本思想很简单，require 组件进来，然后读取其组件类上定义的 propTypes 和 defaultProps 属性。这里使用了 parse-prop-types 库，使用它的时候必须在组件之前引用，因为它会先对 prop-types 库进行修改，在每个 PropTypes 透出的函数上挂上类型，比如 string, number 等等，然后再去遍历。动态解析可以解析出全部的类型信息，因为 PropTypes 有可能引入依赖组件的一些类型定义，这在静态解析中很难做到，或者成本较高，而对于动态解析来说，都由运行时完成了。 + +##### 技术细节 +值得注意的是，有些 js 文件里还会引入 css 文件，而且从笔者了解的情况来看，这种情况在集团内部不在少数。这种组件不配合 webpack 使用，肯定会报错，但是使用 webpack 会明显拖慢速度，所以笔者采用了sandbox 的方式，对 require 进来的类 css 文件进行 mock。这里，笔者使用了 vm2 这个库，它对 node 自带的 vm 进行了封装，可以劫持文件中的 require 方法。因为 parse-prop-types 的修改在沙箱中会失效，所以笔者也 mock 了组件中的 prop-types 库。 + +### 整体大图 +把上述的静态解析和动态解析流程结合起来，可以得到以下大图。 +![image.png](https://cdn.nlark.com/yuque/0/2022/png/242652/1644396777248-9e26dd26-51ac-473e-ae66-c08f8bed3aeb.png#clientId=u41c9ba96-15b6-4&crop=0&crop=0&crop=1&crop=1&from=paste&id=ue6806530&margin=%5Bobject%20Object%5D&name=image.png&originHeight=1072&originWidth=2658&originalType=url&ratio=1&rotation=0&showTitle=false&size=184784&status=done&style=none&taskId=u0d982b36-25b8-442f-8d98-43b9e1629bb&title=) diff --git a/docs/docs/guide/design/renderer.md b/docs/docs/guide/design/renderer.md new file mode 100644 index 000000000..74674bcdb --- /dev/null +++ b/docs/docs/guide/design/renderer.md @@ -0,0 +1,210 @@ +--- +title: 渲染模块设计 +sidebar_position: 4 +--- +# 低代码渲染介绍 + +![image.png](https://cdn.nlark.com/yuque/0/2022/png/242652/1644398134750-7b352564-a400-460e-a189-e72ef551624f.png#clientId=udd4eb4ee-bdb1-4&crop=0&crop=0&crop=1&crop=1&from=paste&height=198&id=OSLhL&margin=%5Bobject%20Object%5D&name=image.png&originHeight=872&originWidth=1440&originalType=binary&ratio=1&rotation=0&showTitle=false&size=193396&status=done&style=none&taskId=ua5d2ae84-0117-4744-a49c-bd3dd1b8a5e&title=&width=327) +基于 Schema 和物料组件，如何渲染出我们的页面？这一节描述的就是这个。 + +# npm 包与仓库信息 + +- React 框架渲染 npm 包：@alilc/lowcode-react-renderer +- Rax 框架渲染 npm 包：@alilc/lowcode-rax-renderer +- 仓库：[https://github.com/alibaba/lowcode-engine](https://github.com/alibaba/lowcode-engine) 下的 + - packages/renderer-core + - packages/react-renderer + - packages/react-simulator-renderer + +# 渲染框架原理 +## 整体架构 +![image.png](https://cdn.nlark.com/yuque/0/2022/png/242652/1644398135242-d83a9d48-c244-4869-b61e-70e825006727.png#clientId=udd4eb4ee-bdb1-4&crop=0&crop=0&crop=1&crop=1&from=paste&height=531&id=udb49df4c&margin=%5Bobject%20Object%5D&name=image.png&originHeight=1062&originWidth=1686&originalType=binary&ratio=1&rotation=0&showTitle=false&size=821823&status=done&style=none&taskId=u90381546-a7a8-4099-b24f-844b8489f4d&title=&width=843) + +- 协议层：基于标准的《阿里巴巴中后台前端搭建协议规范》产出的 Schema 作为我们的规范协议。 +- 能力层：提供组件、区块、页面等渲染所需的核心能力，包括 Props 解析、样式注入、条件渲染等。 +- 适配层：由于我们使用的运行时框架不是统一的，所以统一使用适配层将不同运行框架的差异部分，通过接口对外，让渲染层注册/适配对应所需的方法。能保障渲染层和能力层直接通过适配层连接起来，能起到独立可扩展的作用。 +- 渲染层：提供核心的渲染方法，由于不同运行时框架提供的渲染方法是不同的，所以其通过适配层进行注入，只需要提供适配层所需的接口，即可实现渲染。 +- 应用层：根据渲染层所提供的方法，可以应用到项目中，根据使用的方法和规模即可实现应用、页面、区块的渲染。 + +## 核心解析 +这里主要解析一下刚刚提到的架构中的适配层和渲染层。 +### 适配层 +适配层提供的是各个框架之间的差异项。比如 `React.createElement` 和 `Rax.createElement` 方法是不同的。所以需要在适配层对 API 进行抹平。 + +#### React +```typescript +import { createElement } from 'react'; +import { + adapter, +} from '@ali/lowcode-renderer-core'; + +adapter.setRuntime({ + createElement, +}); +``` +#### Rax +```typescript +import { createElement } from 'rax'; +import { + adapter, +} from '@ali/lowcode-renderer-core'; + +adapter.setRuntime({ + createElement, +}); +``` +这时，在核心层使用的 `createElement` 会基于使用不同的 renderer 而使用不同的方法，自动适配框架所需的运行时方法。 + +所需的方法包括： + +- `setRuntime`：设置运行时相关方法 + - `Component`：组件类，参考 React 的 `Component`。 + - `PureComponent`：组件类，参考 React 的 `PureComponent`。 + - `createContext`：创建一个 `Context` 对象的方法。例如，当 React 渲染一个订阅了这个 `Context` 对象的组件，这个组件会从组件树中离自身最近的那个匹配的 `Provider` 中读取到当前的 `context` 值。 + - `createElement`：创建 `Component` 元素，例如在 React 中即为创建 React 元素。 + - `forwardRef`：ref 转发的方法。Ref 转发是一个可选特性，其允许某些组件接收 ref，并将其向下传递（换句话说，“转发”它）给子组件。 + - `findDOMNode`：是一个访问底层 DOM 节点的方法。如果组件已经被挂载到 DOM 上，此方法会返回浏览器中相应的原生 DOM 元素。 +- `setRenderers` + - `PageRenderer`：页面渲染的方法。可以定制页面渲染的生命周期，定制导航，定制路由等。 + - `ComponentRenderer`：组件渲染的方法。 + - `BlockRenderer`：区块渲染的方法。 + +### 渲染层 +#### React Renderer +内部的技术栈统一都是 React，大多数适配层的 API 都是按照 React 来设计的，所以对于 React Renderer 来说，需要做的不多。 +React Renderer 的代码量很少，主要是将 React API 注册到适配层中。 +```typescript +import React, { Component, PureComponent, createElement, createContext, forwardRef, ReactInstance, ContextType } from 'react'; +import ReactDOM from 'react-dom'; +import { + adapter, + pageRendererFactory, + componentRendererFactory, + blockRendererFactory, + addonRendererFactory, + tempRendererFactory, + rendererFactory, + types, +} from '@ali/lowcode-renderer-core'; +import ConfigProvider from '@alifd/next/lib/config-provider'; + +window.React = React; +(window as any).ReactDom = ReactDOM; + +adapter.setRuntime({ + Component, + PureComponent, + createContext, + createElement, + forwardRef, + findDOMNode: ReactDOM.findDOMNode, +}); + +adapter.setRenderers({ + PageRenderer: pageRendererFactory(), + ComponentRenderer: componentRendererFactory(), + BlockRenderer: blockRendererFactory(), + AddonRenderer: addonRendererFactory(), + TempRenderer: tempRendererFactory(), + DivRenderer: blockRendererFactory(), +}); + +adapter.setConfigProvider(ConfigProvider); +``` + +#### Rax Renderer +Rax 的大多数 API 和 React 基本也是一致的，差异点在于重写了一些方法。 +```typescript +import { Component, PureComponent, createElement, createContext, forwardRef } from 'rax'; +import findDOMNode from 'rax-find-dom-node'; +import { + adapter, + addonRendererFactory, + tempRendererFactory, + rendererFactory, +} from '@ali/lowcode-renderer-core'; +import pageRendererFactory from './renderer/page'; +import componentRendererFactory from './renderer/component'; +import blockRendererFactory from './renderer/block'; +import CompFactory from './hoc/compFactory'; + +adapter.setRuntime({ + Component, + PureComponent, + createContext, + createElement, + forwardRef, + findDOMNode, +}); + +adapter.setRenderers({ + PageRenderer: pageRendererFactory(), + ComponentRenderer: componentRendererFactory(), + BlockRenderer: blockRendererFactory(), + AddonRenderer: addonRendererFactory(), + TempRenderer: tempRendererFactory(), +}); +``` + +## 多模式渲染 +### 预览模式渲染 +预览模式的渲染，主要是通过 Schema、components 即可完成上述的页面渲染能力。 +```typescript +import ReactRenderer from '@ali/lowcode-react-renderer'; +import ReactDOM from 'react-dom'; +import { Button } from '@alifd/next'; + +const schema = { + componentName: 'Page', + props: {}, + children: [ + { + componentName: 'Button', + props: { + type: 'primary', + style: { + color: '#2077ff' + }, + }, + children: '确定', + }, + ], +}; + +const components = { + Button, +}; + +ReactDOM.render(( + +), document.getElementById('root')); +``` + +### 设计模式渲染（Simulator） +设计模式渲染就是将编排生成的《搭建协议》渲染成视图的过程，视图是可以交互的，所以必须要处理好内部数据流、生命周期、事件绑定、国际化等等。也称为画布的渲染，画布是 UI 编排的核心，它一般融合了页面的渲染以及组件/区块的拖拽、选择、快捷配置。 +画布的渲染和预览模式的渲染的区别在于，画布的渲染和设计器之间是有交互的。所以在这里我们新增了一层 `Simulator` 作为设计器和渲染的连接器。 +`Simulator` 是将设计器传入的 `DocumentModel` 和组件/库描述转成相应的 Schema 和 组件类。再调用 Render 层完成渲染。我们这里介绍一下它提供的能力。 +#### 整体架构 +![image.png](https://cdn.nlark.com/yuque/0/2022/png/242652/1644398136330-0f48202b-b581-4b1f-af79-72a667a194d9.png#clientId=udd4eb4ee-bdb1-4&crop=0&crop=0&crop=1&crop=1&from=paste&height=432&id=u734b5c16&margin=%5Bobject%20Object%5D&name=image.png&originHeight=864&originWidth=1500&originalType=binary&ratio=1&rotation=0&showTitle=false&size=572012&status=done&style=none&taskId=u7d7cf569-d5a9-4bea-9b2d-1121b85728f&title=&width=750) + +- `Project`：位于顶层的 Project，保留了对所有文档模型的引用，用于管理应用级 Schema 的导入与导出。 +- `Document`：文档模型包括 Simulator 与数据模型两部分。Simulator 通过一份 Simulator Host 协议与数据模型层通信，达到画布上的 UI 操作驱动数据模型变化。通过多文档的设计及多 Tab 交互方式，能够实现同时设计多个页面，以及在一个浏览器标签里进行搭建与配置应用属性。 +- `Simulator`：模拟器主要承载特定运行时环境的页面渲染及与模型层的通信。 +- `Node`：节点模型是对可视化组件/区块的抽象，保留了组件属性集合 Props 的引用，封装了一系列针对组件的 API，比如修改、编辑、保存、拖拽、复制等。 +- `Props`：描述了当前组件所维系的所有可以「设计」的属性，提供一系列操作、遍历和修改属性的方法。同时保持对单个属性 Prop 的引用。 +- `Prop`：属性模型 Prop 与当前可视化组件/区块的某一具体属性想映射，提供了一系列操作属性变更的 API。 +- `Settings`：`SettingField` 的集合。 +- `SettingField`：它连接属性设置器 `Setter` 与属性模型 `Prop`，它是实现多节点属性批处理的关键。 +- 通用交互模型：内置了拖拽、活跃追踪、悬停探测、剪贴板、滚动、快捷键绑定。 + +#### 模拟器介绍 +![image.png](https://cdn.nlark.com/yuque/0/2022/png/242652/1644398137096-260646a0-f264-48af-9600-6f7141a6a1d8.png#clientId=udd4eb4ee-bdb1-4&crop=0&crop=0&crop=1&crop=1&from=paste&height=370&id=ubfb08f11&margin=%5Bobject%20Object%5D&name=image.png&originHeight=740&originWidth=1500&originalType=binary&ratio=1&rotation=0&showTitle=false&size=353179&status=done&style=none&taskId=u3cd764bb-52f6-47a6-8026-fee6a36d08d&title=&width=750) + +- 运行时环境：从运行时环境来看，目前我们有 React 生态、Rax 生态。而在对外的历程中，我们也会拥有 Vue 生态、Angular 生态等。 +- 布局模式：不同于 C 端营销页的搭建，中后台场景大多是表单、表格，流式布局是主流的选择。对于设计师、产品来说，是需要绝对布局的方式来进行页面研发的。 +- 研发场景：从研发场景来看，低代码搭建不仅有页面编排，还有诸如逻辑编排、业务编排的场景。 + +基于以上思考，我们通过基于沙箱隔离的模拟器技术来实现了多运行时环境（如 React、Rax、小程序、Vue）、多模式（如流式布局、自由布局）、多场景（如页面编排、关系图编排）的 UI 编排。通过注册不同的运行时环境的渲染模块，能够实现编辑器从 React 页面搭建到 Rax 页面搭建的迁移。通过注册不同的模拟器画布，你可以基于 G6或者 mxgraph 来做关系图编排。你可以定制一个流式布局的画布，也可以定制一个自由布局的画布。 diff --git a/docs/docs/guide/design/setter.md b/docs/docs/guide/design/setter.md new file mode 100644 index 000000000..66de03bb1 --- /dev/null +++ b/docs/docs/guide/design/setter.md @@ -0,0 +1,86 @@ +--- +title: 设置器设计 +sidebar_position: 6 +--- +设置器，又称为 Setter，是作为物料属性和用户交互的重要途径，在编辑器日常使用中有着非常重要的作用，本文重点介绍 Setter 的设计原理和使用方式，帮助用户更好的理解 Setter。 +在编辑器的右边区域，Setter 的区块就展现在这里，如下图： +![image.png](https://cdn.nlark.com/yuque/0/2022/png/242652/1644404887956-8ffc8c8c-380c-4843-8bc9-512be77a9b18.png#clientId=u4cc5b992-0df5-4&crop=0&crop=0&crop=1&crop=1&from=paste&height=865&id=wNOuZ&margin=%5Bobject%20Object%5D&name=image.png&originHeight=1730&originWidth=3836&originalType=binary&ratio=1&rotation=0&showTitle=false&size=947162&status=done&style=none&taskId=ue623b488-8774-401a-b80c-c102e8aac8f&title=&width=1918) +其中包含 属性、样式、事件、高级： + +- 属性：展示该物料常规的属性； +- 样式：展示该物料样式的属性； +- 事件：如果该物料有声明事件，则会出现事件面板，用于绑定事件； +- 高级：两个逻辑相关的属性，**条件渲染**和**循环。** +# npm 包与仓库信息 + +- npm 包：@alilc/lowcode-engine-ext +- 仓库：[https://github.com/alibaba/lowcode-engine-ext](https://github.com/alibaba/lowcode-engine-ext) + +# 设置器模块原理 +![image.png](https://cdn.nlark.com/yuque/0/2022/png/242652/1644404909143-eede0a27-e990-4333-816a-d2d0cf2594b3.png#clientId=u4cc5b992-0df5-4&crop=0&crop=0&crop=1&crop=1&height=482&id=PyO6v&name=image.png&originHeight=964&originWidth=1534&originalType=binary&ratio=1&rotation=0&showTitle=false&size=273494&status=done&style=none&taskId=ufb317b56-de50-4693-8c39-8faa9b38307&title=&width=767) + +设置面板依赖于以下三块抽象 + +- 编辑器上下文 `editor`，主要包含：消息通知、插件引用等 +- 设置对象 `settingTarget`，主要包含：选中的节点、是否同一值、值的储存等 +- 设置列 `settingField`，主要和当前设置视图相关，包含视图的 `ref`、以及设置对象 `settingTarget` + +#### SettingTarget 抽象 +如果不是多选，可以直接暴露 `Node` 给到这，但涉及多选编辑的时候，大家的值时通常是不一样的，设置的时候需要批量设置进去，这里主要封装这些逻辑，把多选编辑的复杂性屏蔽掉。 + +所选节点所构成的**设置对象**抽象如下： + +```typescript +interface SettingTarget { + // 所设置的节点集，至少一个 + readonly nodes: Node[]; + // 所有属性值数据 + readonly props: object; + // 设置属性值 + setPropValue(propName: string, value: any): void; + // 获取属性值 + getPropValue(propName: string): any; + // 设置多个属性值，替换原有值 + setProps(data: object): void; + // 设置多个属性值，和原有值合并 + mergeProps(data: object): void; + // 绑定属性值发生变化时 + onPropsChange(fn: () => void): () => void; +} +``` + +基于设置对象所派生的**设置目标属性**抽象如下: + +```typescript +interface SettingTargetProp extends SettingTarget { + // 当前属性名称 + readonly propName: string; + // 当前属性值 + value: any; + // 是否设置对象的值一致 + isSameValue(): boolean; + // 是否是空值 + isEmpty(): boolean; + // 设置属性值 + setValue(value: any): void; + // 移除当前设置 + remove(): void; +} +``` + +#### SettingField 抽象 +![image.png](https://cdn.nlark.com/yuque/0/2022/png/242652/1644396933393-779423e2-29a7-4e97-9ef9-e3c7964a5412.png#clientId=u41c9ba96-15b6-4&crop=0&crop=0&crop=1&crop=1&from=paste&height=201&id=uc71z&margin=%5Bobject%20Object%5D&name=image.png&originHeight=402&originWidth=2022&originalType=binary&ratio=1&rotation=0&showTitle=false&size=218611&status=done&style=none&taskId=u534089f2-363d-464e-8c69-ac79f268f5a&title=&width=1011) + +```typescript +interface SettingField extends SettingTarget { + // 当前 Field 设置的目标属性，为 group 时此值为空 + readonly prop?: SettingTargetProp; + + // 当前设置项的 ref 引用 + readonly ref?: ReactInstance; + + // 属性配置描述传入的配置 + readonly config: SettingConfig; + // others.... +} +``` diff --git a/docs/docs/guide/design/specs.md b/docs/docs/guide/design/specs.md new file mode 100644 index 000000000..be449e3dc --- /dev/null +++ b/docs/docs/guide/design/specs.md @@ -0,0 +1,60 @@ +--- +title: 低代码引擎协议栈简介 +sidebar_position: 1 +--- +# 什么是低代码协议 +这是两份中后台低代码领域的标准协议，即《低代码引擎物料协议规范》和《低代码引擎搭建协议规范》。它们保障了低代码领域的标准化，成为了生态建设和流通的基石。 +![image.png](https://cdn.nlark.com/yuque/0/2022/png/2622706/1648642508161-64dd3a2c-d2d2-43ed-92e4-ead40ab62498.png#clientId=ub4563dfd-c5b1-4&crop=0&crop=0&crop=1&crop=1&from=paste&height=532&id=u60966832&margin=%5Bobject%20Object%5D&name=image.png&originHeight=1064&originWidth=1928&originalType=binary&ratio=1&rotation=0&showTitle=false&size=974317&status=done&style=none&taskId=u88a8512e-a57c-43f6-a01f-19f6878b7a0&title=&width=964) +# 为什么需要协议 +首先，我们做一个不恰当的类比，我们将低代码引擎和 JavaScript 语言做一下类别。还记得之前，大家都被浏览器兼容性支配的恐惧，特别是 IE 和其他浏览器，对上层 API 实现的不一致，导致一份代码需要运行在两端需要做适配。当浏览器 / JavaScript 相关的标准出现之后，各个浏览器进行了 API 的统一，使得我们终于可以从这部分工作中解放出来（PS：Babel 对于语言特性的转换是另一个方面的问题）。 +而在《低代码引擎搭建协议规范》出现之前，低代码领域也有类似的问题。 +## 概念不通 +在交流的过程中，一些对于搭建产品的术语的不一致，导致了一些沟通成本，不管是在文章分享、技术分享、交流会上，都会有这个问题。 +## 物料孤岛 +由于低代码产品实现的方式不同，物料的消费方式也各不相同。这里分为两种物料，低代码物料和 ProCode 物料。 +对于低代码物料来说，A 平台创建的物料无法使用到 B 平台上，如果想在 B 平台实现同样的物料，需要按照 B 平台的标准搭建一份物料。 +对于 ProCode 物料来说，需要在低代码平台进行消费，是需要进行转换的，包括搭建配置项的生成、物料搭建试图等，可能还需要特殊的描述文件进行描述。由于这一层没有统一，同一份 ProCode 物料每接入一个低代码，可能需要的描述文件格式不同，转换的代码不同，使用的工具也不同。 +## 生态隔离 +不同低代码平台的生态体系也不相同，有的低代码平台的物料生态不错，有的低代码平台的搭建体验生态不错。但是这些利好的生态，都是无法互通的，甚至就算知道了代码，也无法复用，因为底层是不一致的。对于集团来说，每一个平台都创建一份自己的生态，这并不是利好的。 +## 技术深度不够 +大家可能觉得，以上问题对于自己造轮子来说，其实也是有利的，因为自己得到了技术上的成长。 +但是对于低代码的平台方，实际上更多的工作，在物料的转化、物料的生成、搭建体验的小优化、部分其他平台生态的实现。这些的技术深度其实并不高。 +## 价值不高 +如果每个业务都要从 0 开始做，做自己的平台，会花费大量的时间来构建底层基础设施，对业务本身而言并不是一件好事；而且前端领域的底层基础设施都大同小异，不同团队重复构建造成了极大的资源浪费。 +这样的建设，会导致从 0 到 1 都需要花费大量的时间，往往在内部人力不足、投入有限时，产品很容易在未发展壮大的时候就面临了死亡相关的决策。 +设想一下，如果可以开发一份全集团低代码平台都可以使用的物料，是否更有成就感呢？如果可以基于已有生态进行低代码平台的快速落地，而不是花费 1-2 年搭建一个可用的低代码平台，再验证市场。在快速的验证之后，再进行更深入的打磨，这其中的思考和技术含量是否更优于之前的模式呢？ +比如不同平台的低代码物料 + +1. vc-deep — vc 协议 + Deep 组件库(企业智能基于 Fusion Next 定制)； +2. Iceluna 协议 + Fusion Next； +3. AIMake 物料； +4. vc-fusion-basic + 业务改造 — vc 协议 + Fusion Next(各业务 Fork 定制)； +5. vision 魔改 + vc 协议扩展 + fusion 业务组件； +6. vc 协议 + antd； + +可以看到，各个搭建平台都需要维护一套自己的基础组件库，这是非常不合理的，对基础组件库的维护会分散开发同学完成业务目标的精力。 +建立统一的低代码领域标准化，是百利而无一害的。于是，在阿里巴巴集团2020财年进行了讨论，建立了搭建治理&物料流通战役，此战役便产出了《低代码引擎物料协议规范》、《低代码引擎搭建协议规范》两份规范，成为了低代码引擎和其生态的基础。 +# 协议的作用 +基于统一的协议，我们完成业务组件、区块、模板等各类物料的标准统一，基于统一的协议，我们完成业务组件、区块、模板等各类物料的标准统一，集团各类中后台研发系统生产的物料可借助物料中心进行跨系统流通，通过丰富物料生态的共享提升阿里巴巴中后台研发系统的效率。同时完成低代码引擎的标准统一以及低代码搭建中台能力的输出，帮助业务方快速孵化本业务域中后台研发系统。 + +## 打破物料孤岛 +### 物料中心 +在《低代码引擎物料协议规范》成立了之后，规范先行建立了阿里巴巴各个中后台研发平台沟通、对话的基础，物料流通的先决条件已经成熟，这个时候我们还需要一个统一的物料源，用于管理物料的上传、存储、检索、分发，一个典型的中心化架构，类似 npm 的管理，这便是我们物料中心。 +Fusion Market 是物料中心的前身，它提供了业务组件的存储、文档展示和全局透出的功能，由于 fusion 体系在集团内的广泛使用，Fusion Market 沉淀了不少的业务组件，但是这个项目却一直不温不火，只看到业务组件数量的增加，却未看到物料流通起来。其中一个原因是，没有阿里巴巴前端委员会的背书，规范很难统一，规范如果不统一，物料就很难流通； +在规范成立之后，物料中心也将有了建设的基础，最终于 2019 年建立了物料中心，提供了物料流通的平台能力。 +### 低代码基础物料 +就像 AntD、Element 之于源码研发模式，在低代码研发模式下各个搭建平台也需要一套统一的、开箱即用的低代码基础组件库。基于低代码描述协议完成了两份低代码基础物料的建设，即“Fusion 低代码基础组件库”和“AntD 低代码基础组件库”。 +### 源码组件低代码化 +将源码组件一键转化为低代码物料，符合低代码物料规范，可以在低代码平台进行流通。 +### 低代码物料中心 +当低代码物料积累到一定的量级之后，所有的搭建平台的业务物料越来越多。这些物料通过低代码物料中心进行统一的管理和消费。 +## Setter 生态的基础 + +Snippet(组件默认搭建 schema )由《低代码引擎搭建协议规范》定义，低代码引擎会按照规范对组件进行渲染，Configure 由《低代码引擎物料协议规范》定义，它描述了组件的 props 以及每个 prop 对应的 setter (Prop 配置面板)，低代码引擎提供了 14 个内置 Setter，但如果我们组件的 props 超出了引擎内置 setter 的范围，就需要我们自己来开发对应 Setter。 +setter 最终也慢慢形成了自己的生态，这使得开发物料更加容易，可以使用已有的 setter 生态，进行物料配置描述。 +## 低代码引擎实现标准 +低代码引擎是以上生态的消费端，它是实现了标准协议的低代码引擎。这是不可或缺的部分，低代码引擎这里就相当于一个标准浏览器，一方面给其他的低代码平台提供了一个 Demo，其他平台可以参考低代码引擎进行实现，满足官方协议，便也可以消费相关的物料生态和其他生态。 +通过物料中心实现集团各业务域物料跨系统流通是第一步，通过低代码引擎快速搭建出来的各业务域低代码平台平滑高效地使用各业务域物料，提升集团中后台研发系统的效率是关键的第二步。 + + +其中入料模块，使得任意符合物料协议的物料都可以被消费，也就打破了物料孤岛，实现物料之间的流通。 diff --git a/docs/docs/guide/design/summary.md b/docs/docs/guide/design/summary.md new file mode 100644 index 000000000..604886e8b --- /dev/null +++ b/docs/docs/guide/design/summary.md @@ -0,0 +1,57 @@ +--- +title: 低代码引擎架构综述 +sidebar_position: 0 +--- +## 分层架构描述 +![image.png](https://cdn.nlark.com/yuque/0/2022/png/242652/1644392855407-44040c3e-f98e-4e93-a7ba-7efc0a7927fb.png#clientId=ue3f00c22-d0cc-4&crop=0&crop=0&crop=1&crop=1&from=paste&height=540&id=u0d1fdc91&margin=%5Bobject%20Object%5D&name=image.png&originHeight=1080&originWidth=1920&originalType=binary&ratio=1&rotation=0&showTitle=false&size=177518&status=done&style=none&taskId=u0ac7d0a3-e838-4982-ad41-e830af33545&title=&width=960) +我们设计了这样一套分层架构，自下而上分别是协议 - 引擎 - 生态 - 平台。 +底层协议栈定义的是标准，**标准的统一让上层产物的互通成为可能**， +**引擎是对协议的实现，同时通过能力的输出，向上支撑生态开放体系，提供各种生态扩展能力，** +那么生态就好理解了，是基于引擎核心能力上扩展出来的，比如物料、设置器、插件等，还有工具链支撑开发体系， +最后，各个平台基于引擎内核以及生态中的产品组合、衔接形成满足其需求的低代码平台。 +**每一层都明确自身的定位，各司其职，协议不会去思考引擎如何实现，引擎也不会实现具体上层平台功能，上层平台的定制化均通过插件来实现，这些理念将会贯穿我们体系设计、实现的过程。** + +## 引擎内核简述 + +![image.png](https://cdn.nlark.com/yuque/0/2022/png/242652/1644393521380-2b5dda70-cd35-4cc2-aeae-6d0ba98deccd.png#clientId=ue3f00c22-d0cc-4&crop=0&crop=0&crop=1&crop=1&from=paste&height=540&id=u6b0dd5f3&margin=%5Bobject%20Object%5D&name=image.png&originHeight=1080&originWidth=1920&originalType=binary&ratio=1&rotation=0&showTitle=false&size=330340&status=done&style=none&taskId=u39127ebd-dbac-4636-9cb5-5c4833146a1&title=&width=960) + +低代码引擎分为 4 大模块，入料 - 编排 - 渲染 - 出码。 +入料模块就是将外部的物料，比如海量的 npm 组件，按照《物料描述协议》进行描述。 +**注意，这里仅是增加描述，而非重写一套，这样我们能最大程度复用ProCode体系已沉淀的组件。** +将描述后的数据通过引擎 API 注册后，在编辑器中使用。 +编排，本质上来讲，就是**不断在生成符合《搭建协议》的页面描述，将编辑器中的所有物料，进行布局设置、组件 CRUD 操作、以及 JS/CSS编写/逻辑编排**等，最终转换成页面描述，技术细节待会儿我们再展开讲讲。 +渲染，顾名思义，就是**将编排生成的页面描述结构渲染成视图的过程**，视图是面向用户的，所以必须处理好内部数据流、生命周期、事件绑定、国际化等。 +出码，就是**将页面描述结构解析和转换成应用代码的机制**。 + +## 引擎生态简述 + +![image.png](https://cdn.nlark.com/yuque/0/2022/png/242652/1644393489755-b9a6a471-c099-480b-b40b-3094b793394d.png#clientId=ue3f00c22-d0cc-4&crop=0&crop=0&crop=1&crop=1&from=paste&height=540&id=u81ccc9e2&margin=%5Bobject%20Object%5D&name=image.png&originHeight=1080&originWidth=1920&originalType=binary&ratio=1&rotation=0&showTitle=false&size=504671&status=done&style=none&taskId=u52008ac0-e9c6-407b-a59e-7dbf4c02c0c&title=&width=960) + +![image.png](https://cdn.nlark.com/yuque/0/2022/png/242652/1644397483218-2b58bfca-94b1-474e-8983-afc757f20e59.png#clientId=uafdaa655-f89e-4&crop=0&crop=0&crop=1&crop=1&from=paste&height=540&id=u3aeacdac&margin=%5Bobject%20Object%5D&name=image.png&originHeight=1080&originWidth=1920&originalType=binary&ratio=1&rotation=0&showTitle=false&size=394834&status=done&style=none&taskId=udcd28484-1df2-484c-9f98-87175972d65&title=&width=960) + +引擎生态主要分为 3 部分，物料、设置器和插件。 +### 物料生态 +物料是低代码平台的生产资料，没有物料低代码平台则变成了无源之水无本之木。低代码平台的物料即低代码组件。因此低代码物料生态指的是： +1）低代码物料生产能力和规范。 +2）对低代码物料进行统一管理的物料中心。 +3）基于 Fusion Next 的低代码基础组件库。 + +### 设置器生态 +对于已接入物料的属性配置，需要不同的设置器。 +比如配置数值类型的 age，需要一个数值设置器，配置对象类型的 hobby，需要一个对象设置器，依次类推。 +每个设置器本质上都是一个 React 组件，接受由引擎传入的参数，比如 value 和 onChange，value 是初始传入的值，onChange 是在设置器的值变化时的回传函数，将值写回到引擎中。 +```json +// 一个最简单的文本设置器示例 +class TextSetter extends Component { + render() { + const { value, onChange } = this.props; + return onChange(e.target.value)} />; + } +} +``` +大多数组件所使用的设置器都是一致或相似的。如同建设低代码基础组件库一样，设置器生态是一组基础的设置器，供大多数组件配置场景使用。 +同时提供了设置器的定制功能。 + +### 插件生态 +低代码引擎本身只包含了最小的内核，而我们所能看到的设计器上的按钮、面板等都是插件提供的。插件是组成设计器的必要部分。 +因此我们提供了一套官方的插件生态，提供最基础的设计器功能。帮助用户通过使用插件，快速完成自己的设计器。 diff --git a/docs/docs/guide/expand/_category_.json b/docs/docs/guide/expand/_category_.json new file mode 100644 index 000000000..36116999b --- /dev/null +++ b/docs/docs/guide/expand/_category_.json @@ -0,0 +1,6 @@ +{ + "label": "扩展低代码应用", + "position": 2, + "collapsed": false, + "collapsible": true +} diff --git a/docs/docs/guide/expand/editor/_category_.json b/docs/docs/guide/expand/editor/_category_.json new file mode 100644 index 000000000..b0c35885c --- /dev/null +++ b/docs/docs/guide/expand/editor/_category_.json @@ -0,0 +1,4 @@ +{ + "label": "扩展低代码编辑器", + "position": 1 +} diff --git a/docs/docs/guide/expand/editor/cli.md b/docs/docs/guide/expand/editor/cli.md new file mode 100644 index 000000000..7f46c7b2e --- /dev/null +++ b/docs/docs/guide/expand/editor/cli.md @@ -0,0 +1,181 @@ +--- +title: 低代码生态脚手架 & 调试机制 +sidebar_position: 7 +--- +## 脚手架简述 + +在 fork 低代码编辑器 demo 项目后，您可以直接在项目中任意扩展低代码编辑器。如果您想要将自己的组件/插件/设置器封装成一个独立的 npm 包并提供给社区，您可以使用我们的低代码脚手架建立低代码扩展。 + +> Windows 开发者请在 WSL 环境下使用开发工具 +> WSL 中文 doc：[https://docs.microsoft.com/zh-cn/windows/wsl/install](https://docs.microsoft.com/zh-cn/windows/wsl/install) +中文教程：[https://blog.csdn.net/weixin_45027467/article/details/106862520](https://blog.csdn.net/weixin_45027467/article/details/106862520) + + +## 脚手架功能 +### 脚手架初始化 +```shell +$ npm init @alilc/element your-element-name +``` +不写 your-element-name 的情况下，则在当前目录创建。 + +> 觉得安装速度比较慢的同学，可以设置 npm 国内镜像，如 + +```bash +$ npm init @alilc/element your-element-name --registry=https://registry.npmmirror.com +``` + +选择对应的元素类型，并填写对应的问题，即可完成创建。 +![截屏2022-02-09 下午8.15.07.png](https://cdn.nlark.com/yuque/0/2022/png/134449/1644408912640-ae7a9a9b-54a4-49c3-a5d8-ccac1db7da0b.png#averageHue=%23f0f0ef&clientId=ue2be1de5-5d30-4&crop=0&crop=0&crop=1&crop=1&errorMessage=unknown%20error&from=drop&height=82&id=uaff32f98&margin=%5Bobject%20Object%5D&name=%E6%88%AA%E5%B1%8F2022-02-09%20%E4%B8%8B%E5%8D%888.15.07.png&originHeight=148&originWidth=688&originalType=binary&ratio=1&rotation=0&showTitle=false&size=72918&status=error&style=none&taskId=uf08c7e98-b502-416d-be39-0029f765203&title=&width=382) +### 脚手架本地环境调试 +```shell +cd your-element-name +npm install +npm start +``` + +### 脚手架构建 +```shell +$ npm run build +``` +### 脚手架发布 +修改版本号后，执行如下指令即可： +```shell +$ npm publish +``` + +# 🔥🔥🔥 调试物料/插件/设置器 + +> 📢📢 📢 低代码生态脚手架提供的调试利器，在启动 setter/插件/物料 项目后，直接在已有的低代码平台就可以调试，不需要 npm link / 手改 npm main 入口等传统方式，轻松上手，强烈推荐使用！！ + + +注：若控制台出现如下错误，直接访问一次该 url 即可~ +![image.png](https://cdn.nlark.com/yuque/0/2022/png/2622706/1652408638502-0509191d-1cd6-435c-9196-5c7abac7cc4d.png#averageHue=%23c8e1be&clientId=u0b1196f0-7f06-4&crop=0&crop=0&crop=1&crop=1&errorMessage=unknown%20error&from=paste&height=113&id=tjF5F&margin=%5Bobject%20Object%5D&name=image.png&originHeight=226&originWidth=1418&originalType=binary&ratio=1&rotation=0&showTitle=false&size=180782&status=error&style=none&taskId=u57eb2bdc-6dfd-4332-b176-c453947be2d&title=&width=709) + +## 组件/插件/Setter 侧 + +1. 插件/setter 在原有 alt 的配置中添加相关的调试配置 +```json +// build.json 中 +{ + "plugins": [ + [ + "@alilc/build-plugin-alt", + { + "type": "plugin", + "inject": true, // 开启注入调试 + // 配置要打开的页面，在注入调试模式下，不配置此项的话不会打开浏览器 + // 支持直接使用官方 demo 项目：https://lowcode-engine.cn/demo/index.html + "openUrl": "https://lowcode-engine.cn/demo/index.html?debug" + } + ], + ] +} +``` + +2. 组件需先安装 @alilc/build-plugin-alt，再将组件内的 `build.lowcode.js`文件修改如下 +```javascript +const { library } = require('./build.json'); + +module.exports = { + alias: { + '@': './src', + }, + plugins: [ + [ + // lowcode 的配置保持不变，这里仅为示意。 + '@alifd/build-plugin-lowcode', + { + library, + engineScope: "@alilc" + }, + ], + [ + '@alilc/build-plugin-alt', + { + type: 'component', + inject: true, + library, + // 配置要打开的页面，在注入调试模式下，不配置此项的话不会打开浏览器 + // 支持直接使用官方 demo 项目：https://lowcode-engine.cn/demo/index.html + openUrl: "https://lowcode-engine.cn/demo/index.html?debug" + } + ]], +}; +``` + +3. 本地组件/插件/Setter正常启动调试，在项目的访问地址增加 debug，即可开启注入调试。 +```typescript +https://lowcode-engine.cn/demo/index.html?debug +``` +## 项目侧的准备 +> 如果你的低代码项目 fork 自官方 demo，那么项目侧的准备已经就绪，不用再看以下内容~ + +1. 安装 @alilc/lowcode-plugin-inject +```shell +npm i @alilc/lowcode-plugin-inject --save-dev +``` + +2. 在引擎初始化侧引入插件 +```json +import Inject, { injectAssets } from '@alilc/lowcode-plugin-inject'; + +export default async () => { + // 注意 Inject 插件必须在其他插件前注册，且所有插件的注册必须 await + await plugins.register(Inject); + await plugins.register(OtherPlugin); + await plugins.register((ctx: ILowCodePluginContext) => { + return { + name: "editor-init", + async init() { + // 设置物料描述前，使用插件提供的 injectAssets 进行处理 + const { material, project } = ctx; + material.setAssets(await injectAssets(assets)); + }, + }; + }); +} +``` + +3. 在 saveSchema 时过滤掉插入的url，避免影响渲染态 +```javascript +import { filterPackages } from '@alilc/lowcode-plugin-inject'; +export const saveSchema = async () => { + // ... + const packages = await filterPackages(editor.get('assets').packages); + window.localStorage.setItem( + 'packages', + JSON.stringify(packages), + ); + // ... +}; + +``` + +4. 如果希望预览态也可以注入调试组件，则需要在 preview 逻辑里插入组件 +```javascript +import { injectComponents } from '@alilc/lowcode-plugin-inject'; + +async function init() { + // 在传递给 ReactRenderer 前，先通过 injectComponents 进行处理 + const components = await injectComponents(buildComponents(libraryMap, componentsMap)); + // ... +} +``` + +# Meta 信息 +meta 信息是放在生态元素 package.json 中的一小段 json，用户可以通过 meta 了解到这个元素的一些基本信息，如元素类型，一些入口信息等。 + +```typescript +interface LcMeta { + type: 'plugin' | 'setter' | 'component'; // 元素类型，尚未实现 + pluginName: string; // 插件名，仅插件包含 + meta: { + dependencies: string[]; // 插件依赖的其他插件列表，仅插件包含 + engines: { + lowcodeEngine: string; // 适配的引擎版本 + } + prototype: string; // 物料描述入口，仅组件包含，尚未实现 + prototypeView: string; // 物料设计态入口，仅组件包含，尚未实现 + } +} +``` diff --git a/docs/docs/guide/expand/editor/material.md b/docs/docs/guide/expand/editor/material.md new file mode 100644 index 000000000..88ea8b908 --- /dev/null +++ b/docs/docs/guide/expand/editor/material.md @@ -0,0 +1,271 @@ +--- +title: 物料扩展 +sidebar_position: 1 +--- +## 物料简述 +物料是页面搭建的原料，按照粒度可分为组件、区块和模板： + +1. 组件：组件是页面搭建最小的可复用单元，其只对外暴露配置项，用户无需感知其内部实现； +2. 区块：区块是一小段符合低代码协议的 schema，其内部会包含一个或多个组件，用户向设计器中拖入一个区块后可以随意修改其内部内容； +3. 模板：模板和区块类似，也是一段符合低代码协议的 schema，不过其根节点的 componentName 需固定为 Page，它常常用于初始化一个页面； + +低代码编辑器中的物料需要进行一定的配置和处理，才能让用户在低代码平台使用起来。这个过程中，需要一份一份配置文件，也就是资产包。资产包文件中，针对每个物料定义了它们在低代码编辑器中的使用描述。 +## 资产包配置 +### 什么是低代码资产包 +![image.png](https://cdn.nlark.com/yuque/0/2022/png/242652/1647671718994-e013a162-37be-4fa7-bd3b-3af06878c3c2.png#clientId=uf20508c2-6786-4&crop=0&crop=0&crop=1&crop=1&from=paste&height=579&id=u7a0c3dae&margin=%5Bobject%20Object%5D&name=image.png&originHeight=1646&originWidth=3068&originalType=binary&ratio=1&rotation=0&showTitle=false&size=635660&status=done&style=stroke&taskId=uc304cc2b-24bf-449d-8e2e-fd25c88b189&title=&width=1080) +在低代码 Demo 中，我们可以看到，组件面板不只提供一个组件，组件是以集合的形式提供给低代码平台的，而低代码资产包正是这些组件构成集合的形式。 +**_它背后的 Interface，_**[**_在引擎中的定义摘抄如下_**](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/assets.ts)**_：_** + +```typescript +export interface Assets { + version: string; // 资产包协议版本号 + packages?: Array; // 大包列表，external与package的概念相似，融合在一起 + components: Array | Array; // 所有组件的描述协议列表 + sort: ComponentSort; // 新增字段，用于描述组件面板中的 tab 和 category +} + +export interface ComponentSort { + groupList?: String[]; // 用于描述组件面板的 tab 项及其排序，例如：["精选组件", "原子组件"] + categoryList?: String[]; // 组件面板中同一个 tab 下的不同区间用 category 区分，category 的排序依照 categoryList 顺序排列； +} + +export interface RemoteComponentDescription { + exportName: string; // 组件描述导出名字，可以通过 window[exportName] 获取到组件描述的 Object 内容； + url: string; // 组件描述的资源链接； + package: { // 组件(库)的 npm 信息； + npm: string; + } +} +``` +资产包协议 TS 描述 +### Demo 中的资产包 +在 Demo 项目中，自带了一份默认的资产包： +> [https://github.com/alibaba/lowcode-demo/blob/main/src/universal/assets.json](https://github.com/alibaba/lowcode-demo/blob/main/src/universal/assets.json) + +这份资产包里的物料是我们内部沉淀出的，用户可以通过这套资产包体验引擎提供的搭建、配置能力。 +**_在项目中正常注册资产包：_** +```json +import { material } from '@alilc/lowcode-engine' +// 以任何方式引入 assets +material.setAssets(assets) +``` +**_以支持调试的方式注册资产包：_** +> 这样启动并部署出来的项目，可以通过在预览地址加上 ?debug 来调试本地物料。 +> 例如： +> - 通过插件初始化一个物料 +> - 按照参考文章配置物料支持调试 +> - 启动物料 +> - 访问：[https://lowcode-engine.cn/demo?debug](https://lowcode-engine.cn/demo?debug) +> +详细参考：[https://www.yuque.com/lce/doc/ulvlkz](https://www.yuque.com/lce/doc/ulvlkz) + +```javascript +import { material } from '@alilc/lowcode-engine' +import Inject, { injectAssets } from '@alilc/lowcode-plugin-inject'; +await material.setAssets(await injectAssets(assets)); +``` + +### 手工配置资产包 +参考 Demo 中的[基础 Fusion Assets 定义](https://github.com/alibaba/lowcode-demo/blob/main/src/scenarios/basic-fusion/assets.json)，如果我们修改 assets.json，我们就能做到配置资产包： + +- packages 对象：我们需要在其中定义这个包的获取方式，如果不定义，就不会被低代码引擎动态加载并对应上组件实例。定义方式是 UMD 的包，低代码引擎会尝试在 window 上寻找对应 library 的实例； +- components 对象：我们需要在其中定义物料描述，物料描述我们将在下一节继续讲解。 +## 物料描述配置 +### 什么是物料描述 +在低代码平台中，用户是不同的，有可能是开发、测试、运营、设计，也有可能是销售、行政、HR 等等各种角色。他们大多数不具备专业的前端开发知识，对于低代码平台来说，我们使用组件的流程如下： + +1. 用户通过拖拽/选择组件，在画布中看到组件； +2. 选中组件，出现组件的配置项； +3. 修改组件配置项； +4. 画布更新生效。 + +**_当我们选中一个组件，我们可以看到面板右侧会显示组件的配置项。_** +![image.png](https://cdn.nlark.com/yuque/0/2022/png/242652/1644312295732-5e0df2b5-065a-4d80-a66c-b5b20c8c32af.png#clientId=ue1d4eb8d-3b5c-4&crop=0&crop=0&crop=1&crop=1&from=url&height=535&id=ML9vP&margin=%5Bobject%20Object%5D&name=image.png&originHeight=743&originWidth=1500&originalType=binary&ratio=1&rotation=0&showTitle=false&size=212807&status=done&style=stroke&taskId=u2458e0f7-6bea-40d8-bb9b-9811562c6fe&title=&width=1080) +**_它包含以下内容：_** + +1. 基础信息：描述组件的基础信息，通常包含包信息、组件名称、标题、描述等。 +2. 组件属性信息：描述组件属性信息，通常包含参数、说明、类型、默认值 4 项内容。 +3. 能力配置/体验增强：推荐用于优化搭建产品编辑体验，定制编辑能力的配置信息。 + +因此，我们设计了[**《中后台低代码组件描述协议》**](http://lowcode-engine.cn/material)来描述一个低代码编辑器中可被配置的内容。 +### Demo 中的物料描述 +我们可以从 Demo 中的 assets.json 找到如下三个物料描述： + +- @alifd/pro-layout：布局组件，放在`window.AlifdProLayoutMeta`，[meta 文件地址](https://alifd.alicdn.com/npm/@alifd/pro-layout@1.0.1-beta.5/build/lowcode/meta.js)； +- @alifd/fusion-ui：精选组件，放在`window.AlifdFusionUiMeta`，[meta 文件地址](https://alifd.alicdn.com/npm/@alifd/fusion-ui@1.0.5-beta.1/build/lowcode/meta.js)； +- @alilc/lowcode-materials：原子组件，放在 `window.AlilcLowcodeMaterialsMeta`，[meta 文件地址](https://alifd.alicdn.com/npm/@alilc/lowcode-materials@1.0.1/build/lowcode/meta.js)； + +**_引擎中，会尝试调用对应 meta 文件，并注入到全局：_** +```tsx +const src = 'https://alifd.alicdn.com/npm/@alifd/pro-layout@1.0.1-beta.5/build/lowcode/meta.js' +const script = document.createElement('script') +script.src = src +document.head.appendChild(script) +``` +然后在 window 上就能拿到对应的物料描述内容了： +![image.png](https://cdn.nlark.com/yuque/0/2022/png/242652/1647672326187-ec19ed1e-645a-4086-8384-ccca19b9f36c.png#clientId=uf20508c2-6786-4&crop=0&crop=0&crop=1&crop=1&from=paste&height=648&id=ue7a84d56&margin=%5Bobject%20Object%5D&name=image.png&originHeight=1138&originWidth=1896&originalType=binary&ratio=1&rotation=0&showTitle=false&size=582492&status=done&style=stroke&taskId=u11707d78-e1c5-4368-9de0-e98b7597815&title=&width=1080) +手工配置物料描述时，可以用这样的方式参考一下 Demo 中的物料描述是如何实现的。 +### 手工配置物料描述 +详见：“物料描述详解”章节。 +## 物料的低代码开发 +> _**注意：引擎提供的 cli 并未对 windows 系统做适配，windows 环境必须使用 **_[_**WSL**_](https://docs.microsoft.com/zh-cn/windows/wsl/install)_**，其他终端不保证能正常运行**_ + +您可以通过本节内容，完成一个组件在低代码编辑器中的配置和调试。 +### 前言（必读） +引擎提供的物料开发脚手架内置了**_入料模块_**，初始化的时候会自动根据源码解析出一份_**低代码描述**_，但是从源码解析出来的低代码描述让用户直接使用是不够精细的，因为源码包含的信息不够，它没办法完全包含配置项的交互； +![image.png](https://cdn.nlark.com/yuque/0/2022/png/231502/1650539267595-c15e6200-9747-46bf-a61d-2a635d295406.png?x-oss-process=image/format,png#clientId=u97daa023-2ae2-4&crop=0&crop=0&crop=1&crop=1&from=paste&height=856&id=u5b22ab2d&name=image.png&originHeight=1830&originWidth=802&originalType=binary&ratio=1&rotation=0&showTitle=false&size=4406602&status=done&style=stroke&taskId=ued90eb0c-b714-401a-bbfe-9f0b04794f6&title=&width=375) +比如设计师出了上面的设计稿，这里面除了有哪些 props 可被配置，通过哪个设置器配置，还包含了 props 之间的聚合、排序，甚至有自定义 setter ，这些信息源码里是不具备的，需要在低代码描述里进行开发； +**_因此我们建议只把 cli 初始化的低代码描述作为启动，要根据用户习惯对配置项进行设计，然后人工地去开发调试直接的低代码描述。_** +### 新开发组件 +#### 组件项目初始化 +```json +npm init @alilc/element your-material-name +``` +#### 选择组件类型 +> 组件 -> <组件组织方式> + +![image.png](https://cdn.nlark.com/yuque/0/2022/png/231502/1647569723981-d0cb5f94-c137-4abf-8165-947b49595c8c.png#clientId=u6b9f3678-e2a3-4&crop=0&crop=0&crop=1&crop=1&from=paste&height=174&id=ud7ad63de&margin=%5Bobject%20Object%5D&name=image.png&originHeight=464&originWidth=1596&originalType=binary&ratio=1&rotation=0&showTitle=false&size=298505&status=done&style=stroke&taskId=ud5e35ff9-c823-41bf-b441-db9e06a1f29&title=&width=600) +这里我们选择 react-组件库，之后便生出我们的组件库项目，目录结构如下： +``` +my-materials +├── README.md +├── components (业务组件目录） +│ ├── ExampleComponent // 业务组件1 +│ │ ├── build // 【编译生成】【必选】 +│ │ │ └── index.html // 【编译生成】【必选】可直接预览文件 +│ │ ├── lib // 【编译生成】【必选】 +│ │ │ ├── index.js // 【编译生成】【必选】js 入口文件 +│ │ │ ├── index.scss // 【编译生成】【必选】css 入口文件 +│ │ │ └── style.js // 【编译生成】【必选】js 版本 css 入口文件，方便去重 +│ │ ├── demo // 【必选】组件文档，用于生成组件开发预览，以及生成组件文档 +│ │ │ └── basic.md +│ │ ├── src // 【必选】组件源码 +│ │ │ ├── index.js // 【必选】，组件出口文件 +│ │ │ └── main.scss // 【必选】，仅包含组件自身样式的源码文件 +│ │ ├── README.md // 【必选】，组件说明及API +│ │ └── package.json // 【必选】 +└── └── ExampleComponent2 // 业务组件2 +``` +#### 组件开发与调试 +``` +# 安装依赖 +npm install + +# 启动 lowcode 环境进行调试预览 +npm run lowcode:dev + +# 构建低代码产物 +npm run lowcode:build +``` +执行上述命令后会在组件(库)根目录生成一个 `lowcode` 文件夹，里面会包含每个组件的低代码描述： +![image.png](https://cdn.nlark.com/yuque/0/2022/png/242652/1644314663918-b2464be7-a65b-447c-af2a-12ea326a7558.png#clientId=ue1d4eb8d-3b5c-4&crop=0&crop=0&crop=1&crop=1&from=paste&height=376&id=AYq7T&margin=%5Bobject%20Object%5D&name=image.png&originHeight=906&originWidth=1446&originalType=binary&ratio=1&rotation=0&showTitle=false&size=347634&status=done&style=stroke&taskId=u25ffbb86-6681-427f-b199-69a22560a9c&title=&width=600) + +在 src/components 目录新增一个组件并在 src/index.tsx 中导出，然后再执行 npm run lowcode:dev 时，低代码插件会在 lowcode/ 目录自动生成新增组件的低代码描述（meta.ts）。 + +用户可以直接修改低代码描述来修改组件的配置： + +- 设置组件的 setter；（上一个章节介绍的设置器，也可以定制设置器用到物料中） +- 新增组件配置项 +- 更改当前配置项； +#### 配置示例 +隐藏一个 prop +```typescript +{ + name: 'dataSource', + condition: () => false, +} +``` +展示样式 +```typescript +{ + name: 'dataSource', + display: 'accordion' | 'inline' | 'block' | 'plain' | 'popup' | 'entry' // 常用的是 inline(默认), block、entry +} +``` +发布组件 +``` +# 在组件根目录下，执行 +$ npm publish +``` +### 现存组件低代码化 +组件低代码化是指，在引入低代码平台之前，我们大多数都是使用源码开发的组件，也就是 ProCode 组件。 +在引入低代码平台之后，原来的源码组件是需要转化为低代码物料，这样才能在低代码平台进行消费。 +所以接下来会说明，对于已有的源码组件，我们如何把它低代码化。 +#### 配置低代码开发环境 +在您的组件开发环境中，安装 [build-scripts](https://github.com/ice-lab/build-scripts) 和它的低代码开发插件： +```shell +npm install -D @alifd/build-plugin-lowcode @alib/build-scripts --save-dev +``` +新增 build-scripts 配置文件：build.lowcode.js +```javascript +module.exports = { + alias: { + '@': './src', + }, + plugins: [ + [ + "@alifd/build-plugin-lowcode", + { + engineScope: '@alilc', + } + ] + ], +}; + +``` +在 package.json 中定义低代码开发相关命令 +```javascript +"lowcode:dev": "build-scripts start --config ./build.lowcode.js", +"lowcode:build": "build-scripts build --config ./build.lowcode.js", +``` +![image.png](https://cdn.nlark.com/yuque/0/2022/png/242652/1644314665584-018b6675-ca7c-4bf5-b755-15a9b629f78f.png#clientId=ue1d4eb8d-3b5c-4&crop=0&crop=0&crop=1&crop=1&from=paste&height=270&id=brUY9&margin=%5Bobject%20Object%5D&name=image.png&originHeight=822&originWidth=1830&originalType=binary&ratio=1&rotation=0&showTitle=false&size=972113&status=done&style=stroke&taskId=u09d05c9e-cf05-417e-bf32-8268d004134&title=&width=600) +#### 开发调试 +```bash +# 启动低代码开发调试环境 +npm run lowcode:dev +``` +组件开发形式还和原来的保持一致，但是新增了一份组件的配置文件，其中配置方式和低代码物料的配置是一样的。 +#### 构建 +```bash +# 构建低代码产物 +npm run lowcode:build +``` +#### 发布组件 +```bash +# 在组件根目录下，执行 +npm publish +``` +## 在项目中引入组件(库) +> 以下内容可观看[《阿里巴巴低代码引擎项目实战(3)-自定义组件接入》](https://www.bilibili.com/video/BV1dZ4y1m76S/)直播回放 + +对于平台或者用户来说，可能所需要的组件集合是不同的。如果需要自定义组件集合，就需要定制资产包，定制的资产包是配置了一系列组件的，将这份资产包用于引擎即可在引擎中使用自定义的组件集合。 +### 管理一份资产包 +项目中使用的组件相关资源都需要在资产包中定义，那么我们自己开发的组件库如果要在项目中使用，只需要把组件构建好的相关资源 merge 到 assets.json 中就可以； +#### 自定义组件加入到资产包 +通过官方脚手架自定义组件构建发布之后，npm 包里会出现一个 `build/lowcode/assets-prod.json`文件，我们只需要把该文件的内容 merge 到项目的 assets.json 中就可以； +#### 资产包托管 + +- 最简单的方式就是类似[引擎 demo 项目](https://github.com/alibaba/lowcode-demo/blob/main/src/universal/assets.json)的做法，在项目中维护一份 assets.json，新增组件或者组件版本更新都需要修改这份资产包； +- 灵活一点的做法是通过 oss 等服务维护一份远程可配置的 assets.json ，新增组件或者组件更新只需要修改这份远程的资产包，项目无需更新； +- 再高级一点的做法是实现一个资产包管理的服务，能够通过用户界面去更新资产包的内容； +### 在项目中引入资产包 +```javascript +import { ILowCodePluginContext, material, plugins } from '@alilc/lowcode-engine' + +// 动态加载 assets +plugins.register((ctx: ILowCodePluginContext) => { + return { + name: 'ext-assets', + async init() { + try { + // 将下述链接替换为您的物料即可。无论是通过 utils 从物料中心引入，还是通过其他途径如直接引入物料描述 + const res = await window.fetch('https://fusion.alicdn.com/assets/default@0.1.95/assets.json') + const assets = await res.text() + material.setAssets(assets) + } catch (err) { + console.error(err) + } + }, + } +}).catch(err => console.error(err)) +``` diff --git a/docs/docs/guide/expand/editor/metaSpec.md b/docs/docs/guide/expand/editor/metaSpec.md new file mode 100644 index 000000000..b1c41dfd9 --- /dev/null +++ b/docs/docs/guide/expand/editor/metaSpec.md @@ -0,0 +1,535 @@ +--- +title: 物料描述详解 +sidebar_position: 2 +--- +## 物料描述概述 + +中后台前端体系中，存在大量的组件，程序员可以通过阅读文档，知悉组件的用法。可是搭建平台无法理解 README，而且很多时候，README 里并没有属性列表。这时，我们需要一份额外的描述，来告诉低代码搭建平台，组件接受哪些属性，又是该用怎样的方式来配置这些属性，于是，[**《中后台低代码组件描述协议》**](http://lowcode-engine.cn/material)应运而生。协议主要包含三部分：基础信息、属性信息 props、能力配置/体验增强 configure。 + +物料配置，就是产出一份符合[**《中后台低代码组件描述协议》**](http://lowcode-engine.cn/material)的 JSON Schema。如果需要补充属性描述信息，或需要定制体验增强部分（如修改 Setter、调整展示顺序等），就可以通过修改这份 Schema 来实现。目前有自动生成、手工配置这两种方式生成物料描述配置。 + +## 可视化生成物料描述 + +使用Parts造物平台：[https://www.yuque.com/lce/xhk5hf/qa9pbx](https://www.yuque.com/lce/xhk5hf/qa9pbx) + +## 自动生成物料描述 + +可以使用官方提供的 `@alilc/lowcode-material-parser` 解析本地组件，自动生成物料描述。把物料描述放到资产包定义中，就能让低代码引擎理解如何制作物料。详见上一个章节“物料扩展”。 + +下面以某个组件代码片段为例： +```typescript +// /path/to/component +import { PureComponent } from 'react'; +import PropTypes from 'prop-types'; + +export default class FusionForm extends PureComponent { + static displayName = 'FusionForm'; + + static defaultProps = { + name: '张三', + age: 18, + friends: ['李四','王五','赵六'] + } + + static propTypes = { + /** + * 这是用于描述姓名 + */ + name: PropTypes.string.isRequired, + /** + * 这是用于描述年龄 + */ + age: PropTypes.number, + /** + * 这是用于描述好友列表 + */ + friends: PropTypes.array + }; + + render() { + return
dumb
+ } +} +``` +引入 parse 工具自动解析 +```typescript +import parse from '@alilc/lowcode-material-parser'; +(async () => { + const result = await parse({ entry: '/path/to/component' }); + console.log(JSON.stringify(result, null, 2)); +})(); +``` +因为一个组件可能输出多个子组件，所以解析结果是个数组。 +```json +[ + { + "componentName": "FusionForm", + "title": "", + "docUrl": "", + "screenshot": "", + "devMode": "proCode", + "npm": { + "package": "", + "version": "", + "exportName": "default", + "main": "", + "destructuring": false, + "subName": "" + }, + "props": [ + { + "name": "name", + "propType": "string", + "description": "这是用于描述姓名", + "defaultValue": "张三" + }, + { + "name": "age", + "propType": "number", + "description": "这是用于描述年龄", + "defaultValue": 18 + }, + { + "name": "friends", + "propType": "array", + "description": "这是用于描述好友列表", + "defaultValue": [ + "李四", + "王五", + "赵六" + ] + } + ] + } +] +``` +## 手工配置物料描述 + +如果自动生成的物料无法满足需求，我们就需要手动配置物料描述。本节将分场景描述物料配置的内容。 + +### 常见配置 + +#### 组件的属性只有有限的值 + +增加一个 size 属性，只能从 'large'、'normal'、'small' 这个候选值中选择。 + +以上面自动解析的物料为例，在此基础上手工加上 size 属性： +```json +[ + { + "componentName": "FusionForm", + "title": "", + "docUrl": "", + "screenshot": "", + "devMode": "proCode", + "npm": { + "package": "", + "version": "", + "exportName": "default", + "main": "", + "destructuring": false, + "subName": "" + }, + "props": [ + { + "name": "name", + "propType": "string", + "description": "这是用于描述姓名", + "defaultValue": "张三" + }, + { + "name": "age", + "propType": "number", + "description": "这是用于描述年龄", + "defaultValue": 18 + }, + { + "name": "friends", + "propType": "array", + "description": "这是用于描述好友列表", + "defaultValue": [ + "李四", + "王五", + "赵六" + ] + } + ], + // 手工增加的 size 属性 + "configure": { + "isExtend": true, + "props": [ + { + "title": "尺寸", + "name": "size", + "setter": { + "componentName": 'RadioGroupSetter', + "isRequired": true, + "props": { + "options": [ + { "title": "大", "value": "large" }, + { "title": "中", "value": "normal" }, + { "title": "小", "value": "small" }, + ] + }, + } + } + ] + } + } +] +``` + +#### 组件的属性既可以设置固定值，也可以绑定到变量 +我们知道一种属性形式就需要一种 setter 来设置，如果想要将 value 属性允许输入字符串，那就需要设置为 `StringSetter`，如果允许绑定变量，就需要设置为 `VariableSetter`，具体设置器请参考[预置 Setter 列表](https://www.yuque.com/lce/doc/oc220p) + +那如果都想要呢？可以使用 `MixedSetter` 来实现 +```json +{ + ..., + configure: { + isExtend: true, + props: [ + { + title: "输入框的值", + name: "activeValue", + setter: { + componentName: 'MixedSetter', + isRequired: true, + props: { + setters: [ + 'StringSetter', + 'NumberSetter', + 'VariableSetter', + ], + }, + } + } + ] + } +} +``` +设置后，就会出现 “切换设置器” 的操作项了 +![image.png](https://cdn.nlark.com/yuque/0/2022/png/189077/1647590065530-b50ed66a-8d24-40fc-91a9-13561663537b.png#clientId=ubd9972cd-765c-4&crop=0&crop=0&crop=1&crop=1&from=paste&height=126&id=ub0e036f6&margin=%5Bobject%20Object%5D&name=image.png&originHeight=252&originWidth=598&originalType=binary&ratio=1&rotation=0&showTitle=false&size=62314&status=done&style=none&taskId=u6545c47c-0fed-44eb-bfab-03694941981&title=&width=299) ![image.png](https://cdn.nlark.com/yuque/0/2022/png/189077/1647590197192-cd0071cf-a90c-4882-9b65-4b46bff13ce9.png#clientId=ubd9972cd-765c-4&crop=0&crop=0&crop=1&crop=1&from=paste&height=154&id=u67de127d&margin=%5Bobject%20Object%5D&name=image.png&originHeight=308&originWidth=244&originalType=binary&ratio=1&rotation=0&showTitle=false&size=24027&status=done&style=none&taskId=u1a44a2d7-3680-4018-8709-9832cd03ad0&title=&width=122) + +#### 开启组件样式设置 + +![image.png](https://cdn.nlark.com/yuque/0/2022/png/231502/1647571003600-48ef05cd-dbac-4aad-b7a5-012727fe1c6f.png#clientId=uad16fa90-b520-4&crop=0&crop=0&crop=1&crop=1&from=paste&id=u467d584c&margin=%5Bobject%20Object%5D&name=image.png&originHeight=772&originWidth=820&originalType=url&ratio=1&rotation=0&showTitle=false&size=128316&status=done&style=none&taskId=ub01cb8bb-e784-485b-b2a6-aead3302c4f&title=) + +```tsx +{ + configure: { + // ..., + supports: { + style: true, + }, + // ... + } +} +``` + +#### 设置组件的默认事件 + +![image.png](https://cdn.nlark.com/yuque/0/2022/png/231502/1647571003649-c0da562f-220c-415e-83ea-e07b71c07552.png#clientId=uad16fa90-b520-4&crop=0&crop=0&crop=1&crop=1&from=paste&id=u7b452a11&margin=%5Bobject%20Object%5D&name=image.png&originHeight=800&originWidth=776&originalType=url&ratio=1&rotation=0&showTitle=false&size=120022&status=done&style=none&taskId=u6805e481-897b-4929-86c8-9321791a21a&title=) + +```tsx +{ + configure: { + // ..., + supports: { + events: ['onPressEnter', 'onClear', 'onChange', 'onKeyDown', 'onFocus', 'onBlur'], + }, + // ... + } +} +``` + +#### 设置 prop 标题的 tip + +![image.png](https://cdn.nlark.com/yuque/0/2022/png/231502/1647571003618-4a1bb1c4-da39-437b-8510-a121329aa91d.png#clientId=uad16fa90-b520-4&crop=0&crop=0&crop=1&crop=1&from=paste&id=u7fe57bc7&margin=%5Bobject%20Object%5D&name=image.png&originHeight=176&originWidth=908&originalType=url&ratio=1&rotation=0&showTitle=false&size=39688&status=done&style=none&taskId=u7e9e26eb-a4c3-423c-b7f1-f096d654d4e&title=) + +```tsx +{ + name: 'label', + setter: 'StringSetter', + title: { + label: { + type: 'i18n', + zh_CN: '标签文本', + en_US: 'Label', + }, + tip: { + type: 'i18n', + zh_CN: '属性: label | 说明: 标签文本内容', + en_US: 'prop: label | description: label content', + }, + }, +} +``` + +#### 配置 prop 对应 setter 在配置面板的展示方式 + +inline:![image.png](https://cdn.nlark.com/yuque/0/2022/png/231502/1647571004529-c879ec4c-18af-46fd-8231-4ab80c937399.png#clientId=uad16fa90-b520-4&crop=0.0174&crop=0.0597&crop=0.9933&crop=0.3909&from=paste&height=260&id=u8cdcc718&margin=%5Bobject%20Object%5D&name=image.png&originHeight=266&originWidth=790&originalType=url&ratio=1&rotation=0&showTitle=false&size=40667&status=done&style=none&taskId=u9390a3bb-0290-46c7-b487-7380f162fd0&title=&width=771) + +```tsx +{ + configure: { + props: [{ + description: '标签文本', + display: 'inline' + }] + } +} +``` + +block: +![image.png](https://cdn.nlark.com/yuque/0/2022/png/231502/1647571004690-22e7dc4f-db0d-43fe-b837-48ed1145bde7.png#clientId=uad16fa90-b520-4&crop=0&crop=0&crop=0.996&crop=1&from=paste&height=273&id=ua1717366&margin=%5Bobject%20Object%5D&name=image.png&originHeight=274&originWidth=792&originalType=url&ratio=1&rotation=0&showTitle=false&size=31246&status=done&style=none&taskId=u9e678772-1217-4c64-ac75-c5928b48834&title=&width=789) +```tsx +{ + configure: { + props: [{ + description: '高级', + display: 'block' + }] + } +} +``` + +accordion + +![image.png](https://cdn.nlark.com/yuque/0/2022/png/231502/1647571005189-552ef14d-6043-48fa-a526-4565d42fa581.png#clientId=uad16fa90-b520-4&crop=0&crop=0.0159&crop=1&crop=1&from=paste&height=740&id=u53a75049&margin=%5Bobject%20Object%5D&name=image.png&originHeight=740&originWidth=798&originalType=url&ratio=1&rotation=0&showTitle=false&size=163685&status=done&style=none&taskId=ub42fca77-545e-435f-bafe-88e2b2ddfd1&title=&width=798) +```tsx +{ + configure: { + props: [{ + description: '表单项配置', + display: 'accordion' + }] + } +} +``` + +entry + +![image.png](https://cdn.nlark.com/yuque/0/2022/png/231502/1647571005244-fb508efb-a2d8-4064-8ff3-d6140e4c20a1.png#clientId=uad16fa90-b520-4&crop=0&crop=0&crop=1&crop=1&from=paste&id=u16645b5c&margin=%5Bobject%20Object%5D&name=image.png&originHeight=424&originWidth=796&originalType=url&ratio=1&rotation=0&showTitle=false&size=91418&status=done&style=none&taskId=u38c7b284-f480-4440-baac-9f7c985104f&title=) +![image.png](https://cdn.nlark.com/yuque/0/2022/png/231502/1647571005468-1c7f4b24-4330-45e2-b6c9-5bf5362874b4.png#clientId=uad16fa90-b520-4&crop=0&crop=0&crop=1&crop=1&from=paste&id=u2fad6ab5&margin=%5Bobject%20Object%5D&name=image.png&originHeight=632&originWidth=794&originalType=url&ratio=1&rotation=0&showTitle=false&size=158094&status=done&style=none&taskId=u7c356adc-4286-46b8-9a2c-d33b4268ddc&title=) + +```tsx +{ + configure: { + props: [{ + description: '风格与样式', + display: 'entry' + }] + } +} +``` + +plain + +![image.png](https://cdn.nlark.com/yuque/0/2022/png/231502/1647571005702-ad979f93-cc47-4c6f-8de7-454cc6305614.png#clientId=uad16fa90-b520-4&crop=0&crop=0&crop=1&crop=1&from=paste&id=u6aa6d230&margin=%5Bobject%20Object%5D&name=image.png&originHeight=438&originWidth=776&originalType=url&ratio=1&rotation=0&showTitle=false&size=133070&status=done&style=none&taskId=u1db8205a-79ed-4d60-91b4-6e7f5bfaff3&title=) + +```tsx +{ + configure: { + props: [{ + description: '返回上级', + display: 'plain' + }] + } +} +``` + + +### 进阶配置 + +#### 组件的 children 属性允许传入 ReactNode +例如有一个如下的 Tab 选项卡组件，每个 TabPane 的 children 都是一个组件 +![image.png](https://cdn.nlark.com/yuque/0/2022/png/189077/1647588145478-fb8b7296-a8ee-4698-9851-846c78de301e.png#clientId=ubd9972cd-765c-4&crop=0&crop=0&crop=1&crop=1&from=paste&height=167&id=bi43p&margin=%5Bobject%20Object%5D&name=image.png&originHeight=334&originWidth=2332&originalType=binary&ratio=1&rotation=0&showTitle=false&size=55470&status=done&style=none&taskId=ub8c8b04a-e2e9-4b5d-9be7-c7ad7154864&title=&width=1166) +只需要增加 `isContainer` 配置即可 +```json +{ + ..., + configure: { + ..., + component: { + // 新增，设置组件为容器组件，可拖入组件 + isContainer: true, + }, + } +} +``` +假设我们希望只允许拖拽 Table、Button 等内容放在 TabPane 里。配置白名单 `childWhitelist` 即可 +```json +{ + ..., + configure: { + ..., + component: { + isContainer: true, + nestingRule: { + // 允许拖入的组件白名单 + childWhitelist: ['Table', 'Button'], + // 同理也可以设置该组件允许被拖入哪些父组件里 + parentWhitelist: ['Tab'], + }, + }, + }, +} +``` +#### 组件的非 children 属性允许传入 ReactNode +这就需要使用 `SlotSetter` 开启插槽了，如下面示例，给 Tab 的 title 开启插槽，允许拖拽组件 +![image.png](https://cdn.nlark.com/yuque/0/2022/png/189077/1647590398244-479c820e-3b2f-4d7e-8742-37cf896bcafb.png#clientId=ubd9972cd-765c-4&crop=0&crop=0&crop=1&crop=1&from=paste&height=290&id=Utp8Y&margin=%5Bobject%20Object%5D&name=image.png&originHeight=580&originWidth=3016&originalType=binary&ratio=1&rotation=0&showTitle=false&size=254405&status=done&style=none&taskId=u0c8f777c-3559-455a-b136-c884312bb67&title=&width=1508) +```json +{ + // ..., + configure: { + isExtend: true, + props: [ + { + title: "选项卡标题", + name: "title", + setter: { + componentName: 'MixedSetter', + props: { + setters: [ + 'StringSetter', + 'SlotSetter', + 'VariableSetter', + ], + }, + } + } + ] + } +} +``` + +#### 屏蔽组件在设计器中的操作按钮 + +正常情况下，组件允许复制： +![image.png](https://cdn.nlark.com/yuque/0/2022/png/231502/1647571003626-06d80381-4d97-4d5b-8621-331674832c82.png#clientId=uad16fa90-b520-4&crop=0&crop=0&crop=1&crop=1&from=paste&id=Sp6IN&margin=%5Bobject%20Object%5D&name=image.png&originHeight=226&originWidth=1158&originalType=url&ratio=1&rotation=0&showTitle=false&size=54949&status=done&style=none&taskId=u7e4b2cbe-5acf-467f-950b-ee48deb9502&title=) +如果希望禁止组件的复制行为，我们可以这样做： + +![image.png](https://cdn.nlark.com/yuque/0/2022/png/242652/1647673808399-2708ff56-70d1-4c58-b93b-aa65269fb179.png#clientId=ufbfe731c-4217-4&crop=0&crop=0&crop=1&crop=1&from=paste&height=150&id=A304J&margin=%5Bobject%20Object%5D&name=image.png&originHeight=300&originWidth=1176&originalType=binary&ratio=1&rotation=0&showTitle=false&size=90147&status=done&style=none&taskId=uf8da0392-c584-4d27-b664-95b3e908103&title=&width=588) +```tsx +{ + configure: { + component: { + disableBehaviors: ['copy'], + } + } +} +``` + +#### 实现一个 BackwardSetter + +![image.png](https://cdn.nlark.com/yuque/0/2022/png/242652/1647674621328-6b0a5afc-eafc-43cc-95ce-bbe00981ac20.png#clientId=ufbfe731c-4217-4&crop=0&crop=0&crop=1&crop=1&from=paste&height=219&id=u9c11597c&margin=%5Bobject%20Object%5D&name=image.png&originHeight=438&originWidth=776&originalType=binary&ratio=1&rotation=0&showTitle=false&size=125336&status=done&style=none&taskId=u01853245-46a8-42dd-9c62-6cdbb909afa&title=&width=388) + +```tsx +{ + name: 'back', + title: ' ', + virtual: () => true, + display: 'plain', + setter: BackwardSetter, +} + +// BackwardSetter +import { SettingTarget, DynamicSetter } from '@alilc/lowcode-types'; +const BackwardSetter: DynamicSetter = (target: SettingTarget) => { + return { + componentName: ( + + ), + }; +}; +``` + +### 高级配置 + +#### 不展现一个 prop 配置 + +- 始终隐藏当前 prop + +```tsx +{ + // 始终隐藏当前 prop 配置 + condition: () => false +} +``` + +- 根据其它 prop 的值展示/隐藏当前 prop + +```tsx +{ + // direction 为 hoz 则展示当前 prop 配置 + condition: (target) => { + return target.getProps().getPropValue('direction') === 'hoz'; + } +} +``` + +#### props 联动 + +```tsx +// 根据当前 prop 的值动态设置其它 prop 的值 +{ + name: 'labelAlign', + // ... + extraProps: { + setValue: (target, value) => { + if (value === 'inset') { + target.getProps().setPropValue('labelCol', null); + target.getProps().setPropValue('wrapperCol', null); + } else if (value === 'left') { + target.getProps().setPropValue('labelCol', { fixedSpan: 4 }); + target.getProps().setPropValue('wrapperCol', null); + } + return target.getProps().setPropValue('labelAlign', value); + }, + }, +} +// 根据其它 prop 的值来设置当前 prop 的值 +{ + name: 'status', + // ... + extraProps: { + getValue: (target) => { + const isPreview = target.getProps().getPropValue('isPreview'); + return isPreview ? 'readonly' : 'editable'; + } + } +} +``` + +#### 动态 setter 配置 + +可以通过 DynamicSetter 传入的 target 获取一些引擎暴露的数据，例如当前有哪些组件被加载到引擎中，将这个数据作为 SelectSetter 的选项，让用户选择: + +```tsx +{ + setter: (target) => { + return { + componentName: 'SelectSetter', + props: { + options: target.designer.props.componentMetadatas.filter( + (item) => item.isFormItemComponent).map( + (item) => { + return { + title: item.title || item.componentName, + value: item.componentName, + }; + } + ), + ), + } + }; + } +} +``` diff --git a/docs/docs/guide/expand/editor/partsIntro.md b/docs/docs/guide/expand/editor/partsIntro.md new file mode 100644 index 000000000..6e56ae1e6 --- /dev/null +++ b/docs/docs/guide/expand/editor/partsIntro.md @@ -0,0 +1,100 @@ +--- +title: 利用Parts造物快速使用react组件 +sidebar_position: 3 +--- +## 介绍 +大家在使用[低代码引擎](https://lowcode-engine.cn/)构建低代码应用平台时，遇到的一个主要问题是如何让已有的 React 组件能够快速低成本地接入进来。这个问题拆解下来主要包括两个子问题：1. 如何给已有组件[配置物料描述](https://lowcode-engine.cn/material)，2. 如何构建出一个低代码引擎能够识别的资产包(Assets)。 +我们的产品 「[Parts·造物](https://parts.lowcode-engine.cn/)」 可以帮助大家解决这个问题。我们通过在线可视化的方式完成物料描述配置，并且提供一键打包的功能生成引擎可以识别的资产包。 + +## 导入物料 +首先，我们需要在 [物料管理](https://parts.lowcode-engine.cn/material#/) 页面导入我们需要进行在线物料描述配置的物料。 +![image.png](https://cdn.nlark.com/yuque/0/2022/png/12718919/1652434800993-0fbf5ed5-63e5-492b-85ab-feafd663ad2d.png#clientId=u0f780a28-b8dc-4&crop=0&crop=0&crop=1&crop=1&from=paste&height=196&id=u918deb34&margin=%5Bobject%20Object%5D&name=image.png&originHeight=342&originWidth=1399&originalType=binary&ratio=1&rotation=0&showTitle=false&size=33102&status=done&style=stroke&taskId=u95c39b84-836c-45f8-aee6-0effc1ccfd1&title=&width=800) + +- 点击列表左上方的 导入已有物料 按钮 +- 在弹框中输入 npm包名 +- 点击 获取包信息 按钮，获取npm包基本信息 +- 点击确定，导入成功 + +![image.png](https://cdn.nlark.com/yuque/0/2022/png/12718919/1652434801003-7bd783f0-8804-445e-b508-8601501dfa60.png#clientId=u0f780a28-b8dc-4&crop=0&crop=0&crop=1&crop=1&from=paste&id=u825d698a&margin=%5Bobject%20Object%5D&name=image.png&originHeight=315&originWidth=640&originalType=binary&ratio=1&rotation=0&showTitle=false&size=21969&status=done&style=stroke&taskId=ued992c2e-822b-4c32-81b5-9c9add84954&title=) +## 配置管理 +第二步：物料导入以后，我们就可以为导入的物料新增[物料描述配置](https://lowcode-engine.cn/material)，点击右侧的组件配置开始配置。 + +![image.png](https://cdn.nlark.com/yuque/0/2022/png/12718919/1652434801125-979e6348-b78a-47b4-bb2e-fa8f1bb4ff90.png#clientId=u0f780a28-b8dc-4&crop=0&crop=0&crop=1&crop=1&from=paste&height=216&id=u7fb954eb&margin=%5Bobject%20Object%5D&name=image.png&originHeight=261&originWidth=965&originalType=binary&ratio=1&rotation=0&showTitle=false&size=15305&status=done&style=stroke&taskId=uc1e18ffd-fe76-4fe4-83a4-c907f308b14&title=&width=800) +### 新增配置 + +- 点击配置管理右上角的 新增配置 + - 选择组件的版本号 + - 填写组件路径，一般和 npm 包的 package.json 里的 main 字段相同 （如果填写错误，后面会渲染不出来） + - 描述字段用于给这份配置增加一些备注信息。 + +![image.png](https://cdn.nlark.com/yuque/0/2022/png/12718919/1652434801095-1957da7f-5d9d-4c17-a762-c576bf0f763f.png#clientId=u0f780a28-b8dc-4&crop=0&crop=0&crop=1&crop=1&from=paste&height=380&id=u9ad0ec47&margin=%5Bobject%20Object%5D&name=image.png&originHeight=418&originWidth=596&originalType=binary&ratio=1&rotation=0&showTitle=false&size=26130&status=done&style=stroke&taskId=u2b592498-195a-4fec-9853-ec5c3b95ef7&title=&width=541.8181700745893) +为了降低配置成本，第一次新增配置的时候会自动解析组件代码，生成一份初始化组件物料描述。所以需要等待片刻，用于代码解析。解析完成后，点击配置按钮即可进入在线配置界面。 +![image.png](https://cdn.nlark.com/yuque/0/2022/png/12718919/1652434801053-1a48b598-e987-4cd5-b657-030d345e0a99.png#clientId=u0f780a28-b8dc-4&crop=0&crop=0&crop=1&crop=1&from=paste&height=193&id=ud384a13d&margin=%5Bobject%20Object%5D&name=image.png&originHeight=232&originWidth=963&originalType=binary&ratio=1&rotation=0&showTitle=false&size=23541&status=done&style=stroke&taskId=ud2efc4d3-6d52-4b77-adbd-14dd5ee4b11&title=&width=800) +### 组件描述配置 +操作界面如下，接下来讲具体的配置流程 +![image.png](https://cdn.nlark.com/yuque/0/2022/png/12718919/1652434802081-6546d0f5-19da-475e-8dec-93ea324cc4e3.png#clientId=u0f780a28-b8dc-4&crop=0&crop=0&crop=1&crop=1&from=paste&height=522&id=uf73c4753&margin=%5Bobject%20Object%5D&name=image.png&originHeight=938&originWidth=1438&originalType=binary&ratio=1&rotation=0&showTitle=false&size=111984&status=done&style=stroke&taskId=u0ce37d2b-8ca3-48b5-ac67-8fb461d17b5&title=&width=800) +#### 新增组件 +如果新增配置的过程中，代码自动解析失败或者解析出来的组件列表不满足开发要求，我们可以点击左侧组件列表插件 新增 按钮，添加新的组件，具体的字段描述可以参考提示内容，以 [react-color](https://github.com/casesandberg/react-color) 为例： +![image.png](https://cdn.nlark.com/yuque/0/2022/png/12718919/1652434802087-eaf4e2f1-2028-4415-b696-9788a6b2d0ed.png#clientId=u0f780a28-b8dc-4&crop=0&crop=0&crop=1&crop=1&from=paste&height=560&id=u4341eb1b&margin=%5Bobject%20Object%5D&name=image.png&originHeight=1005&originWidth=1436&originalType=binary&ratio=1&rotation=0&showTitle=false&size=147918&status=done&style=stroke&taskId=ud921b52d-1961-4be9-b4ec-77d6364b213&title=&width=800) +![image.png](https://cdn.nlark.com/yuque/0/2022/png/12718919/1652434802555-bbd14a55-89a6-42cd-a4b3-76c98febf00c.png#clientId=u0f780a28-b8dc-4&crop=0&crop=0&crop=1&crop=1&from=paste&height=472&id=u06e0b78f&margin=%5Bobject%20Object%5D&name=image.png&originHeight=704&originWidth=1193&originalType=binary&ratio=1&rotation=0&showTitle=false&size=240470&status=done&style=stroke&taskId=u77603c5d-9d14-4379-86d2-deb4deaba50&title=&width=800) +#### 给组件增加物料描述 +选中刚刚新增的BlockPicker组件，然后给它增加描述： + +- 打开左侧 Sette r面板 +- 按照组件的属性拖入需要 Setter 类型 （如图中组件的width属性，拖入数字Setter） +- 各种 Setter 的介绍可以参看这篇文档：[https://www.yuque.com/lce/doc/grfylu](https://www.yuque.com/lce/doc/grfylu) +- 配置属性的基本信息（如图所示） +- 配置完成后点击右上角的保存 + +![image.png](https://cdn.nlark.com/yuque/0/2022/png/12718919/1652434802458-b0fb8a0e-307e-458c-a9f9-af3d2697024c.png#clientId=u0f780a28-b8dc-4&crop=0&crop=0&crop=1&crop=1&from=paste&height=539&id=udeb647da&margin=%5Bobject%20Object%5D&name=image.png&originHeight=967&originWidth=1434&originalType=binary&ratio=1&rotation=0&showTitle=false&size=158958&status=done&style=stroke&taskId=u2950484f-659b-4643-af5e-75d04f14346&title=&width=800) +![image.png](https://cdn.nlark.com/yuque/0/2022/png/12718919/1652434802443-cdc533bf-1b08-4c11-b3d2-7cfd7fe0a5dd.png#clientId=u0f780a28-b8dc-4&crop=0&crop=0&crop=1&crop=1&from=paste&height=311&id=uaaaa88fb&margin=%5Bobject%20Object%5D&name=image.png&originHeight=360&originWidth=925&originalType=binary&ratio=1&rotation=0&showTitle=false&size=64587&status=done&style=stroke&taskId=u7139e8ef-eee3-468b-833c-a42d8f3cb56&title=&width=800) +#### 高级配置（属性联动） +举个栗子：如图所示，如果期望 “设置器” 这个配置项的值 “被修改”的时候，下面的 “默认值” 跟着变化。 +![image.png](https://cdn.nlark.com/yuque/0/2022/png/12718919/1652434803379-009a9783-ec24-4a08-8a46-55ae775ce7ba.png#clientId=u0f780a28-b8dc-4&crop=0&crop=0&crop=1&crop=1&from=paste&height=520&id=u005ad05e&margin=%5Bobject%20Object%5D&name=image.png&originHeight=572&originWidth=371&originalType=binary&ratio=1&rotation=0&showTitle=false&size=96588&status=done&style=stroke&taskId=u97330f9d-6728-4a05-a842-55df114ccee&title=&width=337.27271996253796) +如何使用 +组件的属性配置目前支持3个基本的联动函数： + +- 显示状态：返回true | false，如果返回true，表示组件配置显示，否则配置时不显示 +- 获取值：当调用该配置节点的getValue方法时触发的方法 +- 值变化：当调用该配置节点的setValue方法时触发的方法 + +![image.png](https://cdn.nlark.com/yuque/0/2022/png/12718919/1652434803522-85aed489-4e00-4787-a496-54cc73e25bc5.png#clientId=u0f780a28-b8dc-4&crop=0&crop=0&crop=1&crop=1&from=paste&height=129&id=u0a782260&margin=%5Bobject%20Object%5D&name=image.png&originHeight=142&originWidth=316&originalType=binary&ratio=1&rotation=0&showTitle=false&size=29086&status=done&style=stroke&taskId=u95864da5-4ccf-4e4b-b903-1ce26af4f66&title=&width=287.2727210462587) +方法的第一个参数都是当前配置节点的对象，常用到的有以下几个： + +- getValue(): 获取当前节点的值，如果当前节点是子节点的话，否则为undefined +- setValue(): 设置当前节点的值，如果当前节点是子节点的话 +- parent: 当前节点的父节点 +- getPropValue(propName): 父节点获取子节点的属性值，propName为子节点的属性名称 +- setPropValue(propName, value): 父节点设置子节点的属性值，propName为子节点的属性名称, value 为设置的值 +- getConfig: 获取当前节点的配置，如title、setter等 +#### 调试物料描述 +点击右上角的预览按钮，开始调试我们刚刚配置的属性，如果是组件的首次预览，会有一段组件构建的过程（构建出umd包的过程），构建完成后就可以调试我们的配置了。 +![image.png](https://cdn.nlark.com/yuque/0/2022/png/12718919/1652434804408-717e49bd-26b3-4a28-b3e5-bd1d67cdab00.png#clientId=u0f780a28-b8dc-4&crop=0&crop=0&crop=1&crop=1&from=paste&height=209&id=ucf92cc3e&margin=%5Bobject%20Object%5D&name=image.png&originHeight=373&originWidth=1431&originalType=binary&ratio=1&rotation=0&showTitle=false&size=46363&status=done&style=stroke&taskId=u501edca5-bbef-4fde-b341-b42c28b125a&title=&width=800) +#### 发布物料描述 +物料描述调试没问题后，就可以到项目中去使用了，使用前需要先发布物料描述 + +- 点击右上角的发布按钮 +- 选择需要发布的组件 +- 点击确定发布完成 + +![image.png](https://cdn.nlark.com/yuque/0/2022/png/12718919/1652434804305-276f03e2-4dd2-41e9-9375-1c3bd0c7092a.png#clientId=u0f780a28-b8dc-4&crop=0&crop=0&crop=1&crop=1&from=paste&height=410&id=uf879e7fd&margin=%5Bobject%20Object%5D&name=image.png&originHeight=734&originWidth=1431&originalType=binary&ratio=1&rotation=0&showTitle=false&size=103858&status=done&style=stroke&taskId=udc267585-ffb7-4247-b1f5-b7aca386e10&title=&width=800) +## 资产包构建 +第三步：物料描述发布完成后，接下来我们就需要构建出可用的资产包用于低代码应用中。 +#### 资产包构建 + +- 选择需要构建的组件 +- 点击构建资产包按钮 +- 选择刚刚的物料描述配置 +- 开始构建，构建完成后你将得到一份json文件（里面包含了物料描述和umd包），就可以到项目中使用了 + +![image.png](https://cdn.nlark.com/yuque/0/2022/png/12718919/1652434804769-6f6f60f1-9ee3-4561-972d-610f0616576e.png#clientId=u0f780a28-b8dc-4&crop=0&crop=0&crop=1&crop=1&from=paste&height=430&id=ue119fa2b&margin=%5Bobject%20Object%5D&name=image.png&originHeight=770&originWidth=1431&originalType=binary&ratio=1&rotation=0&showTitle=false&size=93492&status=done&style=stroke&taskId=ubfd97421-964b-4823-adc8-b056a588924&title=&width=800) +#### 资产包使用 +**方式一、在 **[**lowcode-demo**](https://github.com/alibaba/lowcode-demo)**中直接引用，可直接替换demo中原来的资产包文件：** +例如，在basic-fusion demo中，直接用你的资产包文件替换文件[assets.json](https://github.com/alibaba/lowcode-demo/blob/main/src/scenarios/basic-fusion/assets.json)，即可快速使用自己的物料了。 +**方式二、将新的资产包内容和现有的资产包内容融合：** +将上面构建完成的资产包与你项目中的[assets.json文件](https://github.com/alibaba/lowcode-demo/blob/main/src/scenarios/basic-fusion/assets.json)合并，主要合并packages 和 components + +- packages中是构建好的umd包 +- components中是上面配置好的[物料描述](https://lowcode-engine.cn/material)，你也可以在基础上二次加工 + +![image.png](https://cdn.nlark.com/yuque/0/2022/png/12718919/1652434804944-860abc0c-057c-46d5-a6e5-8d33fde8a762.png#clientId=u0f780a28-b8dc-4&crop=0&crop=0&crop=1&crop=1&from=paste&height=676&id=u5499b1c9&margin=%5Bobject%20Object%5D&name=image.png&originHeight=744&originWidth=1140&originalType=binary&ratio=1&rotation=0&showTitle=false&size=116233&status=done&style=stroke&taskId=u7be27934-77ce-4dd7-a406-1d402acef2c&title=&width=1036.36361390106) diff --git a/docs/docs/guide/expand/editor/pluginContextMenu.md b/docs/docs/guide/expand/editor/pluginContextMenu.md new file mode 100644 index 000000000..603aa09c0 --- /dev/null +++ b/docs/docs/guide/expand/editor/pluginContextMenu.md @@ -0,0 +1,69 @@ +--- +title: 插件扩展-编排扩展 +sidebar_position: 6 +--- +## 场景一：扩展选中节点操作项 +### 增加节点操作项 +![image.png](https://cdn.nlark.com/yuque/0/2022/png/110793/1647693318212-173890bc-b0b5-437b-9802-4b1fd9f74c5a.png#clientId=u2eca2bba-d284-4&crop=0&crop=0&crop=1&crop=1&from=paste&height=254&id=u55228975&margin=%5Bobject%20Object%5D&name=image.png&originHeight=292&originWidth=1240&originalType=binary&ratio=1&rotation=0&showTitle=false&size=38144&status=done&style=none&taskId=u426cac9f-24ad-4d06-adbe-faca1896eaa&title=&width=1080) +选中节点后，在选中框的右上角有操作按钮，编排模块默认实现了查看组件直系父节点、复制节点和删除节点按钮外，还可以通过相关 API 来扩展更多操作，如下代码： +```typescript +import { plugins } from '@alilc/lowcode-engine'; +import { Icon, Message } from '@alifd/next'; + +const addHelloAction = (ctx: ILowCodePluginContext) => { + return { + async init() { + const { addBuiltinComponentAction } = ctx.material; + addBuiltinComponentAction({ + name: 'hello', + content: { + icon: , + title: 'hello', + action(node: Node) { + Message.show('Welcome to Low-Code engine'); + }, + }, + condition: (node: Node) => { + return node.componentMeta.componentName === 'NextTable'; + }, + important: true, + }); + } + }; +} +addHelloAction.pluginName = 'addHelloAction'; +await plugins.register(addHelloAction); +``` +**_效果如下：_** +![image.png](https://cdn.nlark.com/yuque/0/2022/png/110793/1647694920149-b8d9a534-b943-45d2-b67e-cc42b906f827.png#clientId=u2eca2bba-d284-4&crop=0&crop=0&crop=1&crop=1&from=paste&height=282&id=ua20a09c8&margin=%5Bobject%20Object%5D&name=image.png&originHeight=343&originWidth=1315&originalType=binary&ratio=1&rotation=0&showTitle=false&size=35131&status=done&style=none&taskId=u3f47b55d-15ff-495c-8615-31e3ccb0222&title=&width=1080) +具体 API 参考：[https://www.yuque.com/lce/doc/mu7lml#ieJzi](https://www.yuque.com/lce/doc/mu7lml#ieJzi) +### 删除节点操作项 +```typescript +import { plugins } from '@alilc/lowcode-engine'; + +const removeCopyAction = (ctx: ILowCodePluginContext) => { + return { + async init() { + const { removeBuiltinComponentAction } = ctx.material; + removeBuiltinComponentAction('copy'); + } + } +} +removeCopyAction.pluginName = 'removeCopyAction'; +await plugins.register(removeCopyAction); +``` +**_效果如下：_** +![image.png](https://cdn.nlark.com/yuque/0/2022/png/110793/1647695353667-e22bef51-3c6a-4b6a-87d2-c144ddb68115.png#clientId=u2eca2bba-d284-4&crop=0&crop=0&crop=1&crop=1&from=paste&height=237&id=ufa1f9434&margin=%5Bobject%20Object%5D&name=image.png&originHeight=290&originWidth=1319&originalType=binary&ratio=1&rotation=0&showTitle=false&size=22495&status=done&style=none&taskId=u73e01acc-96e8-45e7-9d42-a31edca193e&title=&width=1080) +具体 API 参考：[https://www.yuque.com/lce/doc/mu7lml#va9mb](https://www.yuque.com/lce/doc/mu7lml#va9mb) +## 实际案例 +### 区块管理 + +- 仓库地址：[https://github.com/alibaba/lowcode-plugins](https://github.com/alibaba/lowcode-plugins) +- 具体代码：[https://github.com/alibaba/lowcode-plugins/tree/main/packages/action-block](https://github.com/alibaba/lowcode-plugins/tree/main/packages/action-block) +- 直播回放： + - [低代码引擎项目实战(9)-区块管理(1)-保存为区块](https://www.bilibili.com/video/BV1YF411M7RK/) + - [低代码引擎项目实战(10)-区块管理-区块面板](https://www.bilibili.com/video/BV1FB4y1S7tu/) + - [阿里巴巴低代码引擎项目实战(11)-区块管理- ICON优化](https://www.bilibili.com/video/BV1zr4y1H7Km/) + - [阿里巴巴低代码引擎项目实战(11)-区块管理-自动截图](https://www.bilibili.com/video/BV1GZ4y117VH/) + - [阿里巴巴低代码引擎项目实战(11)-区块管理-样式优化](https://www.bilibili.com/video/BV1Pi4y1S7ZT/) + - [阿里低代码引擎项目实战(12)-区块管理(完结)-给引擎插件提个 PR](https://www.bilibili.com/video/BV1hB4y1277o/) diff --git a/docs/docs/guide/expand/editor/pluginWidget.md b/docs/docs/guide/expand/editor/pluginWidget.md new file mode 100644 index 000000000..fd63167e9 --- /dev/null +++ b/docs/docs/guide/expand/editor/pluginWidget.md @@ -0,0 +1,170 @@ +--- +title: 插件扩展-面板扩展 +sidebar_position: 5 +--- +## 插件简述 +插件功能赋予低代码引擎更高的灵活性，低代码引擎的生态提供了一些官方的插件，但是无法满足所有人的需求，所以提供了强大的插件定制功能。 +通过定制插件，在和低代码引擎解耦的基础上，我们可以和引擎核心模块进行交互，从而满足多样化的功能。不仅可以自定义插件的 UI，还可以实现一些非 UI 的逻辑： +1）调用编辑器框架提供的 API 进行编辑器操作或者 schema 操作； +2）通过插件类的生命周期函数实现一些插件初始化的逻辑； +3）通过实现监听编辑器内的消息实现特定的切片逻辑（例如面板打开、面板关闭等） +> 本文仅介绍面板层面的扩展，编辑器插件层面的扩展可以参考 "插件扩展 - 编排扩展" 章节。 + +## 注册插件 API +```typescript +import { plugins, ILowCodePluginContext } from '@alilc/lowcode-engine'; + +const pluginA = (ctx: ILowCodePluginContext, options: any) => { + return { + init() { + console.log(options.key); + // 往引擎增加面板 + ctx.skeleton.add({ + // area 配置见下方说明 + area: 'leftArea', + // type 配置见下方说明 + type: 'PanelDock', + content:
demo
, + }); + ctx.logger.log('打个日志'); + }, + destroy() { + console.log('我被销毁了~'); + } + } +} + +pluginA.pluginName = 'pluginA'; + +plugins.register(pluginA, { key: 'test' }); +``` +> 如果您想了解抽取出来的插件如何封装成为一个 npm 包并提供给社区，可以参考“扩展低代码应用 - 扩展低代码编辑器 - 低代码插件脚手架”章节。 +插件系统的详细设计，可参考“参与低代码引擎开发 - 低代码引擎设计文档 - 插件”章节。 + +## 面板插件配置说明 +面板插件是作用于设计器的，主要是通过按钮、图标等展示在设计器的骨架中。设计器的骨架我们分为下面的几个区域，而我们的插件大多数都是作用于这几个区域的。 +![image.png](https://cdn.nlark.com/yuque/0/2022/png/242652/1644393006009-165e36cd-fa7b-4ee0-b3e3-dc7ba9d80d55.png#averageHue=%237cac76&clientId=u45843f36-7f71-4&crop=0&crop=0&crop=1&crop=1&from=paste&height=608&id=u9e018f89&margin=%5Bobject%20Object%5D&name=image.png&originHeight=1080&originWidth=1920&originalType=binary&ratio=1&rotation=0&showTitle=false&size=149463&status=done&style=stroke&taskId=u74f952e4-c783-47ae-b11c-be48d3c52be&title=&width=1080) +![image.png](https://cdn.nlark.com/yuque/0/2022/png/242652/1644320581783-b8fcd29c-45c2-48df-be2c-7101b12474e3.png#averageHue=%23edf6d4&clientId=u221f0bd4-c19e-4&crop=0&crop=0&crop=1&crop=1&from=paste&height=580&id=ixlrN&margin=%5Bobject%20Object%5D&name=image.png&originHeight=1648&originWidth=3068&originalType=binary&ratio=1&rotation=0&showTitle=false&size=165621&status=done&style=stroke&taskId=u030d9faf-015f-4475-b34a-ba1fbf8868b&title=&width=1080) +### 展示区域 area +#### topArea +展示在设计器的顶部区域，常见的相关区域的插件主要是： +1）注册设计器 Logo； +2）设计器操作回退和撤销按钮； +3）全局操作按钮，例如：保存、预览等； +#### leftArea +左侧区域的展示形式大多数是 Icon 和对应的面板，通过点击 Icon 可以展示对应的面板并隐藏其他的面板。 +该区域相关插件的主要有： +1）大纲树展示，展示该设计器设计页面的大纲。 +2）组件库，展示注册到设计器中的组件，点击之后，可以从组件库面板中拖拽到设计器的画布中。 +3）数据源面板 +4）JS 等代码面板。 +可以发现，这个区域的面板大多数操作时是不需要同时并存的，且交互比较复杂的，需要一个更整块的区域来进行操作。 +#### centerArea +画布区域，由于画布大多数是展示作用，所以一般扩展的种类比较少。常见的扩展有： +1）画布大小修改 +2）物料选中扩展区域修改 +#### rightArea +右侧区域，常用于组件的配置。常见的扩展有：统一处理组件的配置项，例如统一删除某一个配置项，统一添加某一个配置项的。 +#### toolbar +跟 topArea 类似，按需放置面板插件~ +### 展示形式 type +#### PanelDock +PanelDock 是以面板的形式展示在设计器的左侧区域的。其中主要有两个部分组成，一个是图标，一个是面板。当点击图标时可以控制面板的显示和隐藏。 +下图是组件库插件的展示效果。 +![Feb-08-2022 19-44-15.gif](https://cdn.nlark.com/yuque/0/2022/gif/242652/1644320663827-ee9c54a1-f684-40e2-8a6b-875103d04b31.gif#averageHue=%23eaf6d2&clientId=u221f0bd4-c19e-4&crop=0&crop=0&crop=1&crop=1&from=paste&height=555&id=u5292d9cc&margin=%5Bobject%20Object%5D&name=Feb-08-2022%2019-44-15.gif&originHeight=790&originWidth=1536&originalType=binary&ratio=1&rotation=0&showTitle=false&size=1381641&status=done&style=stroke&taskId=ub28a13a4-3d80-4a02-bcaa-cc9d6127243&title=&width=1080) +其中右上角可以进行固定，可以对弹出的宽度做设定 +接入可以参考代码 +```javascript +import { skeleton } from "@alilc/lowcode-engine"; + +skeleton.add({ + area: "leftArea", // 插件区域 + type: "PanelDock", // 插件类型，弹出面板 + name: "sourceEditor", + content: SourceEditor, // 插件组件实例 + props: { + align: "left", + icon: "wenjian", + description: "JS面板", + }, + panelProps: { + floatable: true, // 是否可浮动 + height: 300, + hideTitleBar: false, + maxHeight: 800, + maxWidth: 1200, + title: "JS面板", + width: 600, + }, +}); +``` +#### Widget +Widget 形式是直接渲染在当前编辑器的对应位置上。如 demo 中在设计器顶部的所有组件都是这种展现形式。 +![image.png](https://cdn.nlark.com/yuque/0/2022/png/242652/1644320068765-47efc836-30c2-452f-8104-b98b1ea3533d.png#averageHue=%23fefefb&clientId=u221f0bd4-c19e-4&crop=0&crop=0&crop=1&crop=1&from=paste&height=51&id=u68c58cad&margin=%5Bobject%20Object%5D&name=image.png&originHeight=94&originWidth=1988&originalType=binary&ratio=1&rotation=0&showTitle=false&size=58410&status=done&style=stroke&taskId=u4eadd643-2e63-4be7-8736-b27b9c82b81&title=&width=1080) +接入可以参考代码： +```javascript +import {skeleton} from "@alilc/lowcode-engine"; +// 注册 logo 面板 +skeleton.add({ + area: "topArea", + type: "Widget", + name: "logo", + content: Logo, // Widget 组件实例 + contentProps: { // Widget 插件props + logo: + "https://img.alicdn.com/tfs/TB1_SocGkT2gK0jSZFkXXcIQFXa-66-66.png", + href: "/", + }, + props: { + align: "left", + width: 100, + }, +}); +``` +#### Dock +一个图标的表现形式，可以用于语言切换、跳转到外部链接、打开一个 widget 等场景 +```javascript +import { skeleton } from "@alilc/lowcode-engine"; + +skeleton.add({ + area: "leftArea", + type: "Dock", + name: "opener", + content: Opener, // Widget 组件实例 + contentProps: { // Widget 插件props + xxx: "1", + }, + props: { + align: "bottom", + }, + onClick: function() { + // 打开外部链接 + window.open('https://lowcode-engine.cn'); + // 显示 widget + skeleton.showWidget('xxx'); + } +}); +``` +#### Panel +一般不建议单独使用，通过 PanelDock 使用~ +## 实际案例 +### 页面管理面板 + +- 仓库地址：[https://github.com/mark-ck/lowcode-portal](https://github.com/mark-ck/lowcode-portal) +- 具体代码：[https://github.com/mark-ck/lowcode-portal/blob/master/src/plugins/pages-plugin/index.tsx](https://github.com/mark-ck/lowcode-portal/blob/master/src/plugins/pages-plugin/index.tsx) +- 直播回放： + - [低代码引擎项目实战(4)-自定义插件-页面管理](https://www.bilibili.com/video/BV17a411i73f/) + - [低代码引擎项目实战(4)-自定义插件-页面管理-后端](https://www.bilibili.com/video/BV1uZ4y1U7Ly/) + - [低代码引擎项目实战(4)-自定义插件-页面管理-前端](https://www.bilibili.com/video/BV1Yq4y1a74P/) + - [低代码引擎项目实战(4)-自定义插件-页面管理-完结](https://www.bilibili.com/video/BV13Y4y1e7EV/) +### 区块面板 + +- 仓库地址：[https://github.com/alibaba/lowcode-plugins](https://github.com/alibaba/lowcode-plugins) +- 具体代码：[https://github.com/alibaba/lowcode-plugins/tree/main/packages/plugin-block](https://github.com/alibaba/lowcode-plugins/tree/main/packages/plugin-block) +- 直播回放： + - [低代码引擎项目实战(9)-区块管理(1)-保存为区块](https://www.bilibili.com/video/BV1YF411M7RK/) + - [低代码引擎项目实战(10)-区块管理-区块面板](https://www.bilibili.com/video/BV1FB4y1S7tu/) + - [阿里巴巴低代码引擎项目实战(11)-区块管理- ICON优化](https://www.bilibili.com/video/BV1zr4y1H7Km/) + - [阿里巴巴低代码引擎项目实战(11)-区块管理-自动截图](https://www.bilibili.com/video/BV1GZ4y117VH/) + - [阿里巴巴低代码引擎项目实战(11)-区块管理-样式优化](https://www.bilibili.com/video/BV1Pi4y1S7ZT/) + - [阿里低代码引擎项目实战(12)-区块管理(完结)-给引擎插件提个 PR](https://www.bilibili.com/video/BV1hB4y1277o/) diff --git a/docs/docs/guide/expand/editor/setter.md b/docs/docs/guide/expand/editor/setter.md new file mode 100644 index 000000000..846c60b3e --- /dev/null +++ b/docs/docs/guide/expand/editor/setter.md @@ -0,0 +1,202 @@ +--- +title: 设置器扩展 +sidebar_position: 4 +--- +## 设置器简述 +设置器主要用于低代码组件属性值的设置，顾名思义叫"设置器"，又称为 Setter。由于组件的属性有各种类型，需要有与之对应的设置器支持，每一个设置器对应一个值的类型。 +### 设计器展示位置 +设置器展示在编辑器的右边区域，如下图： +![image.png](https://cdn.nlark.com/yuque/0/2022/png/242652/1644387351052-0be9546e-9e46-41ff-bbb4-a1effe650d7f.png#clientId=u39aebc41-90a1-4&crop=0&crop=0&crop=1&crop=1&from=paste&height=487&id=pi5XH&margin=%5Bobject%20Object%5D&name=image.png&originHeight=1730&originWidth=3836&originalType=binary&ratio=1&rotation=0&showTitle=false&size=947162&status=done&style=stroke&taskId=u4d4deed8-40f5-40a6-b20d-d092c90775c&title=&width=1080) +其中包含四类设置器： + +- 属性：展示该物料常规的属性 +- 样式：展示该物料样式的属性 +- 事件：如果该物料有声明事件，则会出现事件面板，用于绑定事件。 +- 高级：两个逻辑相关的属性，**条件渲染**和**循环** +### 设置器类型 +上述区域中是有多项设置器的，对于一个组件来说，每一项配置都对应一个设置器，比如我们的配置是一个文本，我们需要的是文本设置器，我们需要配置的是数字，我们需要的就是数字设置器。 +下图中的标题和按钮类型配置就分别是文本设置器和下拉框设置器。 +![image.png](https://cdn.nlark.com/yuque/0/2022/png/242652/1644387350762-7337e729-53e9-4a6c-8da1-8f17260e1347.png#clientId=u39aebc41-90a1-4&crop=0&crop=0&crop=1&crop=1&from=paste&height=744&id=ztLvk&margin=%5Bobject%20Object%5D&name=image.png&originHeight=1460&originWidth=2120&originalType=binary&ratio=1&rotation=0&showTitle=false&size=489840&status=done&style=stroke&taskId=u7375a322-b6c8-43f1-a096-07b204656aa&title=&width=1080) +我们提供了常用的设置器作为内置设置器，也提供了定制能力帮助大家开发特定需求的设置器。 +## 为物料配置设置器 +我们提供了[常用的设置器](https://www.yuque.com/lce/doc/oc220p?view=doc_embed&from=kb&from=kb&outline=1&title=1)作为内置设置器。 +我们可以将目标组件的属性值类型值配置到物料资源配置文件中： +```json +{ + "componentName": "Message", + "title": "Message", + "configure": { + "props": [ + { + "name": "type", + "setter": "InputSetter" + } + ] + } +} +``` +props 字段是入料模块扫描自动填入的类型，用户可以通过 configure 节点进行配置通过 override 节点对属性的声明重新定义，setter 就是注册在引擎中的 setter。 +为物料配置引擎内置的 setter 时，均可以使用对应 setter 的高级功能，对应功能参考“全部内置设置器”章节下的对应 setter 文章。 +**_对高级功能的配置如下：_** +例如我们需要在NumberSetter中配置units属性，可以在asset.json中声明 +```json +"configure": { + "component": { + "isContainer": true, + "nestingRule": { + "parentWhitelist": [ + "NextP" + ] + } + }, + "props": [ + { + "name": "width", + "title": "宽度", + "initialValue": "auto", + "defaultValue": "auto", + "condition": { + "type": "JSFunction", + "value": "() => false" + }, + "setter": { + "componentName": "NumberSetter", + "props": { + "units": [ + { + "type": "px", + "list": true + }, + { + "type": "%", + "list": true + } + ] + } + } + }, + ], + "supports": { + "style": true + } +}, +``` +## 自定义设置器 +### 编写 AltStringSetter +我们编写一个简单的 Setter，它的功能如下： +![image.png](https://cdn.nlark.com/yuque/0/2022/png/2553587/1644764687180-0121f0c0-d113-4907-a86d-e4f3a04ff221.png#clientId=ucb27c83c-48cf-4&crop=0&crop=0&crop=1&crop=1&from=paste&height=45&id=u32dc8cd0&margin=%5Bobject%20Object%5D&name=image.png&originHeight=90&originWidth=720&originalType=binary&ratio=1&rotation=0&showTitle=false&size=17539&status=done&style=stroke&taskId=u0f886bda-a93e-4b10-ad7e-9ba9a38a3fb&title=&width=360) +**_代码如下：_** +```typescript +import * as React from "react"; +import { Input } from "@alifd/next"; + +import "./index.scss"; +interface AltStringSetterProps { + // 当前值 + value: string; + // 默认值 + defaultValue: string; + // setter唯一输出 + onChange: (val: string) => void; + // AltStringSetter 特殊配置 + placeholder: string; +} +export default class AltStringSetter extends React.PureComponent { + componentDidMount() { + const { onChange, value, defaultValue } = this.props; + if (value == undefined && defaultValue) { + onChange(defaultValue); + } + } + + // 声明Setter的title + static displayName = 'AltStringSetter'; + + render() { + const { onChange, value, placeholder } = this.props; + return ( + onChange(val)} + > + ); + } +} +``` +#### setter 和 setter/plugin 之间的联动 +我们采用 emit 来进行相互之前的通信，首先我们在 A setter 中进行事件注册： +```javascript +import { event } from '@alilc/lowcode-engine'; + +componentDidMount() { + // 这里由于面板上会有多个setter，这里我用field.id来标记setter名 + this.emitEventName = `${SETTER_NAME}-${this.props.field.id}`; + event.on(`${this.emitEventName}.bindEvent`, this.bindEvent) +} + +bindEvent = (eventName) => { + // do someting +} + +componentWillUnmount() { + // setter是以实例为单位的，每个setter注销的时候需要把事件也注销掉，避免事件池过多 + event.off(`${this.emitEventName}.bindEvent`, this.bindEvent) +} +``` +在 B setter 中触发事件，来完成通信： +```javascript +import { event } from '@alilc/lowcode-engine'; + +bindFunction = () => { + const { field, value } = this.props; + // 这里展示的和插件进行通信,事件规则是插件名+方法 + event.emit('eventBindDialog.openDialog', field.name, this.emitEventName); +} +``` +#### 修改同级 props 的其他属性值 +setter 本身只影响其中一个 props 的值，如果需要影响其他组件的 props 的值，需要使用 field 的 props： +```json +bindFunction = () => { + const { field, value } = this.props; + const propsField = field.parent; + // 获取同级其他属性showJump的值 + const otherValue = propsField.getPropValue('showJump'); + // set同级其他属性showJump的值 + propsField.setPropValue('showJump', false); +} +``` +### 注册 AltStringSetter +我们需要在低代码引擎中注册 Setter，这样就可以通过 AltStringSetter 的名字在物料中使用了。 +```typescript +import AltStringSetter from './AltStringSetter'; +const registerSetter = window.AliLowCodeEngine.setters.registerSetter; +registerSetter('AltStringSetter', AltStringSetter); +``` +### 物料中使用 +我们需要将目标组件的属性值类型值配置到物料资源配置文件中，其中核心配置如下： +```json +{ + "props": [ + { + "name": "type", + "setter": "AltStringSetter" + } + ] +} +``` +在物料中的相关配置如下： +```json +{ + "componentName": "Message", + "title": "Message", + "configure": { + "props": [ + { + "name": "type", + "setter": "AltStringSetter" + } + ] + } +} +``` diff --git a/docs/docs/guide/expand/editor/summary.md b/docs/docs/guide/expand/editor/summary.md new file mode 100644 index 000000000..e8487213c --- /dev/null +++ b/docs/docs/guide/expand/editor/summary.md @@ -0,0 +1,90 @@ +--- +title: 低代码扩展简述 +sidebar_position: 0 +--- +## 扩展点简述 + +我们可以从 Demo 的项目中看到页面中有很多的区块： +![image.png](https://cdn.nlark.com/yuque/0/2022/png/242652/1643447049972-e324320a-7f97-4e48-bef3-a4c5d2b06517.png#clientId=udea0fe9a-4e7e-4&crop=0&crop=0&crop=1&crop=1&from=paste&height=1080&id=rGr7U&margin=%5Bobject%20Object%5D&name=image.png&originHeight=2160&originWidth=3840&originalType=binary&ratio=1&rotation=0&showTitle=false&size=518455&status=done&style=none&taskId=u872d1136-0f18-41b3-900d-710e9fc9eea&title=&width=1920) +这些功能点背后都是可扩展项目，如下图所示： +![image.png](https://cdn.nlark.com/yuque/0/2022/png/242652/1643447052089-8e340da7-3c2c-4a88-9ed8-c89516dccf75.png#clientId=udea0fe9a-4e7e-4&crop=0&crop=0&crop=1&crop=1&from=paste&height=957&id=lL1sN&margin=%5Bobject%20Object%5D&name=image.png&originHeight=1914&originWidth=3838&originalType=binary&ratio=1&rotation=0&showTitle=false&size=538736&status=done&style=none&taskId=u43e8a14e-0d52-4a22-bd19-e5083814daf&title=&width=1919) + +- 插件定制：可以配置低代码编辑器的功能和面板 +- 物料定制：可以配置能够拖入的物料 +- 操作辅助区定制：可以配置编辑器画布中的操作辅助区功能 +- 设置器定制：可以配置编辑器中组件的配置表单 + +我们从可扩展项目的视角，可以把低代码引擎架构理解为下图： + +![image.png](https://cdn.nlark.com/yuque/0/2022/png/242652/1643447051959-7abb91ea-44af-46e0-b73a-dd2127648b32.png#clientId=udea0fe9a-4e7e-4&crop=0&crop=0&crop=1&crop=1&from=paste&height=1080&id=M07o7&margin=%5Bobject%20Object%5D&name=image.png&originHeight=2160&originWidth=3840&originalType=binary&ratio=1&rotation=0&showTitle=false&size=779021&status=done&style=none&taskId=u640e4616-d38d-45fb-a560-e4a98cd1605&title=&width=1920) +（注：引擎内核中大量数据交互的细节被简化，这张图仅仅强调编辑器和外部扩展的交互） + +## 配置扩展点 + +### 配置物料 +通过配置注入物料，这里的配置是物料中心根据物料资产包协议生成的，后面“物料扩展”章节会有详细说明。 +```typescript +import { material } from '@alilc/lowcode-engine' +// 假设您已把物料配置在本地 +import assets from './assets.json' + +// 静态加载 assets +material.setAssets(assets) +``` + +也可以通过异步加载物料中心上的物料。 +```typescript +import { ILowCodePluginContext, material, plugins } from '@alilc/lowcode-engine' + +// 动态加载 assets +plugins.register((ctx: ILowCodePluginContext) => { + return { + name: 'ext-assets', + async init() { + try { + // 将下述链接替换为您的物料即可。无论是通过 utils 从物料中心引入，还是通过其他途径如直接引入物料描述 + const res = await window.fetch('https://fusion.alicdn.com/assets/default@0.1.95/assets.json') + const assets = await res.text() + material.setAssets(assets) + } catch (err) { + console.error(err) + } + }, + } +}).catch(err => console.error(err)) +``` + +### 配置插件 +可以通过 npm 包的方式引入社区插件，配置如下所示： +```typescript +import { ILowCodePluginContext, plugins } from '@alilc/lowcode-engine' +import PluginIssueTracker from '@alilc/lowcode-plugin-issue-tracker' + +// 注册一个提 issue 组件到您的编辑器中，方位默认在左栏下侧 +plugins.register(PluginIssueTracker) + .catch(err => console.error(err)) +``` +后续“插件扩展”章节会详细说明。 + +### 配置设置器 +低代码引擎默认内置了设置器（详见“配置设置器”章节）。您可以通过 npm 包的方式引入自定义的设置器，配置如下所示： +```typescript +import { setters } from '@alilc/lowcode-engine' +// 假设您自定义了一个 setter +import MuxMonacoEditorSetter from './components/setters/MuxMonacoEditorSetter' + +// 注册设置器 +setters.registerSetter({ + MuxMonacoEditorSetter: { + component: MuxMonacoEditorSetter, + title: 'Textarea', + condition: (field) => { + const v = field.getValue() + return typeof v === 'string' + }, + }, +}) +``` +后续“设置器扩展”章节会详细说明。 + +> 本章节所有可扩展配置内容在 demo 中均可找到：[https://github.com/alibaba/lowcode-demo/blob/main/src/universal/plugin.tsx](https://github.com/alibaba/lowcode-demo/blob/main/src/universal/plugin.tsx) diff --git a/docs/docs/guide/expand/runtime/_category_.json b/docs/docs/guide/expand/runtime/_category_.json new file mode 100644 index 000000000..14aafc939 --- /dev/null +++ b/docs/docs/guide/expand/runtime/_category_.json @@ -0,0 +1,4 @@ +{ + "label": "扩展低代码运行时", + "position": 2 +} diff --git a/docs/docs/guide/expand/runtime/codeGeneration.md b/docs/docs/guide/expand/runtime/codeGeneration.md new file mode 100644 index 000000000..e1d9dc3d8 --- /dev/null +++ b/docs/docs/guide/expand/runtime/codeGeneration.md @@ -0,0 +1,132 @@ +--- +title: 使用出码功能 +sidebar_position: 1 +--- + +## 出码简述 +所谓出码，即将低代码编排出的 schema 进行解析并转换成最终可执行的代码的过程。 +## 出码的适用范围 +出码是为了更高效的运行和更灵活地定制渲染，相对而言，基于 Schema 的运行时渲染，有着能实时响应内容的变化和接入成本低的优点，但是也存在着实时解析运行的性能开销比较大和包大小比较大的问题，而且无法自由地进行扩展二次开发，功能自由度受到一定程度限制。 +当然，出码也会存在一些限制：一方面需要额外的接入成本，另一方面通常需要额外的生成代码和打包构建的时间，难以做到基于 Schema 的运行时渲染那样保存即预览的效果。 + +所以不是所有场景都建议做出码，一般来说以下 3 个场景可以考虑使用出码进行优化。 + +### 场景一：想要极致的打开速度，降低 LCP/FID +这种场景比较常见的是 C 端应用，比如手淘上的页面和手机钉钉上的页面，要求能够尽快得响应用户操作，不要出现卡死的情况。当一个流入协议大小比较大的时候，前端进行解析时的开销也比较大。如果能把这部分负担转移到编译时去完成的话，前端依赖包大小就会减少许多。从而也提升了加载速度，降低了带宽消耗。页面越简单，这其中的 gap 就会越明显。 + +### 场景二：老项目 + 新需求，想用搭建产出 +这是一个很常见的场景，毕竟迁移或者重构都是有一个过程的，阿里的业务都是一边跑一边换发动机。在这种场景中，我们不可能要求使用运行时方案来做实现，因为运行时是一个项目级别的能力，最好是项目中统一使用他这一种方式，保证体验的一致性与连贯性。所以我们可以只在低代码平台上搭建新的业务页面，然后通过出码模块导出这些页面的源码，连同一些全局依赖模块，一起 Merge 到老项目中。完成开发体验的优化。 + +### 场景三：协议不能描述部分代码逻辑（协议功能不足或特别定制化的逻辑） +当我们发现一些逻辑诉求不能在目前协议中很好地表达的时候，这其实是项目复杂度较高的一个信号。比较好的方式就是将低代码研发和源码研发结合起来。这种模式下最大的诉求点之一就是，需要将搭建的内容输出为可读性和确定性都比较良好的代码模块。这也就是出码模块需要支持好的使用场景了。 + +## 如何使用 +### 1) 通过命令行快速体验 + +欢迎使用命令行工具快速体验：`npx @alilc/lowcode-code-generator -i example-schema.json -o generated -s icejs` + +--其中 example-schema.json 可以从[这里下载](https://unpkg.com/@alilc/lowcode-code-generator@beta/example-schema.json) + +### 2) 通过设计器插件快速体验 + +1. 安装依赖: `npm install --save @alilc/lowcode-plugin-code-generator` +2. 注册插件: + +```typescript +import { plugins } from '@alilc/lowcode-engine'; +import CodeGenPlugin from '@alilc/lowcode-plugin-code-generator'; + +// 在你的初始化函数中： +await plugins.register(CodeGenPlugin); + +// 如果您不希望自动加上出码按钮，则可以这样注册 +await plugins.register(CodeGenPlugin, { disableCodeGenActionBtn: true }); +``` + +然后运行你的低代码编辑器项目即可 -- 在设计器的右上角会出现一个“出码”按钮，点击即可在浏览器中出码并预览。 + +### 3）服务端出码接入 + +此代码生成器一开始就是为服务端出码设计的，你可以直接这样来在 node.js 环境中使用： + +1. 安装依赖: `npm install --save @alilc/lowcode-code-generator` +2. 引入代码生成器: + +```javascript +import CodeGenerator from '@alilc/lowcode-code-generator'; +``` + +3. 创建项目构建器: + +```javascript +const projectBuilder = CodeGenerator.solutions.icejs(); +``` + +4. 生成代码 + +```javascript +const project = await projectBuilder.generateProject( + schema, // 编排搭建出来的 schema +); +``` + +5. 将生成的代码写入到磁盘中(也可以生成一个 zip 包) + +```javascript +// 写入磁盘 +await CodeGenerator.publishers.disk().publish({ + project, // 上一步生成的 project + outputPath: '/path/to/your/output/dir', // 输出目录 + projectSlug: 'your-project-slug', // 项目标识 +}); + +// 写入到 zip 包 +await CodeGenerator.publishers.zip().publish({ + project, // 上一步生成的 project + outputPath: '/path/to/your/output/dir', // 输出目录 + projectSlug: 'your-project-slug', // 项目标识 -- 对应生成 your-project-slug.zip 文件 +}); +``` + +注：一般来说在服务端出码可以跟 github/gitlab, CI 和 CD 流程等一起串起来使用，通常用于优化性能。 + +### 4）浏览器中出码接入 + +随着现在电脑性能和浏览器技术的发展，出码其实已经不必非得在服务端做了，借助于 Web Worker 特性，可以在浏览器中进行出码： + +1. 安装依赖: `npm install --save @alilc/lowcode-code-generator` +2. 引入代码生成器: + +```javascript +import * as CodeGenerator from '@alilc/lowcode-code-generator/standalone-loader'; +``` + +3. 【可选】提前初始化代码生成器: + +```javascript +// 提前初始化下，这样后面用的时候更快(这个 init 内部会提前准备好创建 worker 的一些资源) +await CodeGenerator.init(); +``` + +4. 出码 + +```javascript +const result = await CodeGenerator.generateCode({ + solution: 'icejs', // 出码方案 (目前内置有 icejs 和 rax ) + schema, // 编排搭建出来的 schema +}); + +console.log(result); // 出码结果(默认是递归结构描述的，可以传 flattenResult: true 以生成扁平结构的结果) +``` + +注：一般来说在浏览器中出码适合做即时预览功能。 + +### 5）自定义出码 +前端框架灵活多变，默认内置的出码方案很难满足所有人的需求，好在此代码生成器支持非常灵活的插件机制 -- 内置功能大多都是通过插件完成的（在 `src/plugins`下），比如： +![image.png](https://cdn.nlark.com/yuque/0/2022/png/263300/1644824565650-584c2be5-4be3-4c9a-96d9-e27990111b0b.png#averageHue=%232b2b2e&clientId=u8b65d964-7bef-4&crop=0&crop=0&crop=1&crop=1&from=paste&height=376&id=u3e0a61a8&margin=%5Bobject%20Object%5D&name=image.png&originHeight=376&originWidth=457&originalType=binary&ratio=1&rotation=0&showTitle=false&size=151355&status=done&style=none&taskId=ueef52494-2e18-45a2-8409-7f68e200f63&title=&width=457) +所以您可以通过添加自己的插件或替换掉默认内置的插件来实现您的自定义功能。 +为了方便自定义出码方案，出码模块还提供自定义出码方案的脚手架功能，即执行下面脚本即可生成一个自定义出码方案： +```shell +npx @alilc/lowcode-code-generator init-solution +``` +里面内置了一个示例的插件(在 `src/plugins/example.ts`中)，您可以根据注释引导来完善相关插件，从而组合生成您的专属出码方案(`src/index.ts`)。您所生成的出码方案可以发布成 NPM 包，从而能按上文 1~4 中的使用方案进行使用。 diff --git a/docs/docs/guide/expand/runtime/renderer.md b/docs/docs/guide/expand/runtime/renderer.md new file mode 100644 index 000000000..20cc35bae --- /dev/null +++ b/docs/docs/guide/expand/runtime/renderer.md @@ -0,0 +1,349 @@ +--- +title: 使用渲染模块 +sidebar_position: 0 +--- +## 快速使用 +渲染依赖于 schema 和 components。其中 schema 和 components 需要一一对应，schema 中使用到的组件都需要在 components 中进行声明，否则无法正常渲染。 +### 简单示例 + +```jsx +import ReactRenderer from '@alilc/lowcode-react-renderer'; +import ReactDOM from 'react-dom'; +import { Button } from '@alifd/next'; + +const schema = { + componentName: 'Page', + props: {}, + children: [ + { + componentName: 'Button', + props: { + type: 'primary', + style: { + color: '#2077ff' + }, + }, + children: '确定', + }, + ], +}; + +const components = { + Button, +}; + +ReactDOM.render(( + +), document.getElementById('root')); +``` + +- rax-renderer：npm 包替换为 @alilc/lowcode-rax-renderer +#### +### 项目使用示例 +> 设计器 demo：[https://lowcode-engine.cn/demo](https://lowcode-engine.cn/demo) +> 项目代码完整示例：[https://github.com/alibaba/lowcode-demo](https://github.com/alibaba/lowcode-demo) + +**step 1：在设计器中获取组件列表** +```typescript +import { material, project } from '@alilc/lowcode-engine'; +const packages = material.getAssets().packages +``` +**step 2：在设计器中获取当前配置页面的 schema** +```typescript +import { material, project } from '@alilc/lowcode-engine'; + +const schema = project.exportSchema(); +``` + + +**step 3：以某种方式存储 schema 和 packages** +这里用 localStorage 作为存储示例，真实项目中使用数据库或者其他存储方式。 +```typescript +window.localStorage.setItem( + 'projectSchema', + JSON.stringify(project.exportSchema()) +); +const packages = await filterPackages(material.getAssets().packages); +window.localStorage.setItem( + 'packages', + JSON.stringify(packages) +); +``` +**step 4：预览时，获取存储的 schema 和 packages** +```typescript +const packages = JSON.parse(window.localStorage.getItem('packages') || ''); +const projectSchema = JSON.parse(window.localStorage.getItem('projectSchema') || ''); +const { componentsMap: componentsMapArray, componentsTree } = projectSchema; +``` +**step 5：通过整合 schema 和 packages 信息，进行渲染** +```typescript +import ReactDOM from 'react-dom'; +import React, { useState } from 'react'; +import { Loading } from '@alifd/next'; +import { buildComponents, assetBundle, AssetLevel, AssetLoader } from '@alilc/lowcode-utils'; +import ReactRenderer from '@alilc/lowcode-react-renderer'; +import { injectComponents } from '@alilc/lowcode-plugin-inject'; + +const SamplePreview = () => { + const [data, setData] = useState({}); + + async function init() { + // 渲染前置处理，初始化项目 schema 和资产包为渲染模块所需的 schema prop 和 components prop + const packages = JSON.parse(window.localStorage.getItem('packages') || ''); + const projectSchema = JSON.parse(window.localStorage.getItem('projectSchema') || ''); + const { componentsMap: componentsMapArray, componentsTree } = projectSchema; + const componentsMap: any = {}; + componentsMapArray.forEach((component: any) => { + componentsMap[component.componentName] = component; + }); + const schema = componentsTree[0]; + + const libraryMap = {}; + const libraryAsset = []; + packages.forEach(({ package: _package, library, urls, renderUrls }) => { + libraryMap[_package] = library; + if (renderUrls) { + libraryAsset.push(renderUrls); + } else if (urls) { + libraryAsset.push(urls); + } + }); + + const vendors = [assetBundle(libraryAsset, AssetLevel.Library)]; + + const assetLoader = new AssetLoader(); + await assetLoader.load(libraryAsset); + const components = await injectComponents(buildComponents(libraryMap, componentsMap)); + + setData({ + schema, + components, + }); + } + + const { schema, components } = data; + + if (!schema || !components) { + init(); + return ; + } + + return ( +
+ +
+ ); +}; + +ReactDOM.render(, document.getElementById('ice-container')); + +``` +### 国际化示例 +```typescript +class Demo extends PureComponent { + static displayName = 'renderer-demo'; + render() { + return ( +
+ +
+ ); + } +} +``` + +## API + +| 参数 | 说明 | 类型 | 必选 | +| --- | --- | --- | --- | +| schema | 符合[搭建协议](https://lowcode-engine.cn/lowcode)的数据 | Object | 是 | +| components | 组件依赖的实例 | Object | 是 | +| componentsMap | 组件的配置信息 | Object | 否 | +| appHelper | 渲染模块全局上下文 | Object | 否 | +| designMode | 设计模式，可选值：extend、border、preview | String | 否 | +| suspended | 是否挂起 | Boolean | 否 | +| onCompGetRef | 组件 ref 回调（schema, ref）=> {} | Function | 否 | +| onCompGetCtx | 组件 ctx 更新回调 (schema, ctx) => {} | Function | 否 | +| rendererName | 渲染类型，标识当前模块是以什么类型进行渲染的 | string | 否 | +| customCreateElement | 自定义创建 element 的钩子 +(Component, props, children) => {} | Function | 否 | +| notFoundComponent | 当组件找不到时，可以通过这个参数自定义展示文案。 | Component | 否 | +| thisRequiredInJSE | 为 true 的情况下 JSExpression 仅支持通过 this 来访问。假如需要兼容原来的 'state.xxx'，则设置为 false，推荐使用 true。 | Boolean | 否 | +| locale | 国际化语言类型 | string | 否 | +| messages | 国际化语言对象 | Object | 否 | + + +### schema + +搭建基础协议数据，渲染模块将基于 schema 中的内容进行实时渲染。 + +### messages +国际化内容，需要配合 locale 使用 +messages 格式示例： +```typescript +{ + 'zh-CN': { + 'hello-world': '你好，世界！', + }, + 'en-US': { + 'hello-world': 'Hello world!', + }, +} +``` + +### locale +当前语言类型 +示例：'zh-CN' | 'en-US' + +### components + +渲染模块渲染页面需要用到的组件依赖的实例，`components` 对象中的 Key 需要和搭建 schema 中的`componentName` 字段对应。 + +### componentsMap + +> 在生产环境下不需要设置。 + + +配置规范参见[《低代码引擎搭建协议规范》](https://lowcode-engine.cn/lowcode)，主要在搭建场景中使用，用于提升用户搭建体验。 + +- 属性配置校验：用户可以配置组件特定属性的 `propTypes`，在搭建场景中用户输入的属性值不满足 `propType` 配置时，渲染模块会将当前属性设置为 `undefined`，避免组件抛错导致编辑器崩溃； +- `isContainer` 标记：当组件被设置为容器组件且当前容器组件内没有其他组件时，用户可以通过拖拽方式将组件直接添加到容器组件内部； +- `parentRule` 校验：当用户使用的组件未出现在组件配置的 `parentRule` 组件内部时，渲染模块会使用 `visualDom` 组件进行占位，避免组件抛错的同时在下钻编辑场景也能够不阻塞用户配置，典型的场景如`Step.Item`、`Table.Column`、`Tab.Item` 等等。 + +### appHelper + +appHelper 主要用于设置渲染模块的全局上下文，目前 appHelper 支持设置以下上下文： + +- `utils`：全局公共函数 +- `constants`：全局常量 +- `location`：react-router 的 `location` 实例 +- `history`：react-router 的 `history` 实例 + +设置了 appHelper 以后，上下文会直接挂载到容器组件的 this 上，用户可以在搭建协议中的 function 及变量表达式场景使用上下文，具体使用方式如下所示： +**schema：** + +```javascript +export default { + "componentName": "Page", + "fileName": "test", + "props": {}, + "children": [{ + "componentName": "Div", + "props": {}, + "children": [{ + "componentName": "Text", + "props": { + "text": { + "type": "JSExpression", + "value": "this.location.pathname" + } + } + }, { + "componentName": "Button", + "props": { + "type": "primary", + "style": { + "marginLeft": 10 + }, + "onClick": { + "type": "JSExpression", + "value": "function onClick(e) { this.utils.xxx(this.constants.yyy);}" + } + }, + "children": "click me" + }] + }] +} +``` + +```typescript +import ReactRenderer from '@alilc/lowcode-react-renderer'; +import ReactDOM from 'react-dom'; +import { Button } from '@alifd/next'; +import schema from './schema' + +const components = { + Button, +}; + +ReactDOM.render(( + {} + } + }} + /> +), document.getElementById('root')); +``` +### designMode + +> 在生产环境下不需要设置。 + + +designMode 属性主要在搭建场景中使用，主要有以下作用： + +- 当 `designMode` 改变时，触发当前 schema 中所有组件重新渲染 +- 当 `designMode` 设置为 `design` 时，渲染模块会为 `Dialog`、`Overlay` 等初始状态无 dom 渲染的组件外层包裹一层 div，使其在画布中能够展示边框供用户选中 + +### suspended + +渲染模块是否挂起，当设置为 `true` 时，渲染模块最外层容器的 `shouldComponentUpdate` 将始终返回false，在下钻编辑或者多引擎渲染的场景会用到该参数。 + +### onCompGetRef + +组件 ref 的回调，在搭建场景下编排模块可以根据该回调获取组件实例并实现生命周期注入或者组件 DOM 操作等功能，回调函数主要包含两个参数： + +- `schema`： 当前组件的 schema 模型结构 +- `ref`：当前组件的 ref 实例 + +### onCompGetCtx +组件 ctx 更新的回调，在组件每次 render 渲染周期我们都会为组件构造新的上下文环境，因此该回调函数会在组件每次 render 过程中触发，主要包含两个参数： + +- `schema`：当前组件的 schema 模型结构 +- `ctx`：当前组件的上下文信息，主要包含以下内容： + - `page`：当前页面容器实例 + - `this`: 当前组件所属的容器组件实例 + - `item`/`index`: 循环上下文（属性 key 可以根据 loopArgs 进行定制） + - `form`: 表单上下文 + +### rendererName +渲染类型，标识当前模块是以什么类型进行渲染的 + +- `LowCodeRenderer`: 低代码组件 +- `PageRenderer`: 页面 + +### customCreateElement +自定义创建 element 的钩子，用于在渲染前后对组件进行一些处理，包括但不限于增加 props、删除部分 props。主要包含三个参数： + +- `Component`：要渲染的组件 +- `props`：要渲染的组件的 props +- `children`：要渲染的组件的子元素 + +### thisRequiredInJSE +> 版本 >= 1.0.11 + +默认值：true +为 true 的情况下 JSExpression 仅支持通过 this 来访问。假如需要兼容原来的 'state.xxx'，则设置为 false，推荐使用 true。 diff --git a/docs/docs/guide/quickStart/_category_.json b/docs/docs/guide/quickStart/_category_.json new file mode 100644 index 000000000..0a47c9da5 --- /dev/null +++ b/docs/docs/guide/quickStart/_category_.json @@ -0,0 +1,6 @@ +{ + "label": "入门", + "position": 0, + "collapsed": false, + "collapsible": true +} diff --git a/docs/docs/guide/quickStart/demo.md b/docs/docs/guide/quickStart/demo.md new file mode 100644 index 000000000..536c8efab --- /dev/null +++ b/docs/docs/guide/quickStart/demo.md @@ -0,0 +1,47 @@ +--- +title: 试用低代码引擎 Demo +sidebar_position: 1 +--- +# 访问地址 + +低代码引擎的 Demo 可以通过如下永久链接访问到： + +[https://lowcode-engine.cn/demo](https://lowcode-engine.cn/demo) + +> 注意我们会经常更新 demo，所以您可以通过上述链接得到最新版地址。 + + +# 低代码引擎 Demo 功能概览 + +我们可以从 Demo 的项目中看到页面中有很多的区块：
![image.png](https://cdn.nlark.com/yuque/0/2022/png/242652/1643447049972-e324320a-7f97-4e48-bef3-a4c5d2b06517.png#clientId=udea0fe9a-4e7e-4&crop=0&crop=0&crop=1&crop=1&from=paste&height=1080&id=rGr7U&margin=%5Bobject%20Object%5D&name=image.png&originHeight=2160&originWidth=3840&originalType=binary&ratio=1&rotation=0&showTitle=false&size=518455&status=done&style=none&taskId=u872d1136-0f18-41b3-900d-710e9fc9eea&title=&width=1920)
它主要包含这些功能点：
![image.png](https://cdn.nlark.com/yuque/0/2022/png/242652/1643447051103-de714f27-ec70-4982-b180-e1ebe444b0fe.png#clientId=udea0fe9a-4e7e-4&crop=0&crop=0&crop=1&crop=1&from=paste&height=1080&id=lD0YM&margin=%5Bobject%20Object%5D&name=image.png&originHeight=2160&originWidth=3840&originalType=binary&ratio=1&rotation=0&showTitle=false&size=616472&status=done&style=none&taskId=u61de17fa-6df0-43c8-9171-96388fda32e&title=&width=1920) + +- 顶部：操作区 + - 右侧：撤回和重做、保存到本地、重置页面、预览、异步加载资源 +- 左侧：面板与操作区 + - 大纲面板：可以调整页面内的组件树结构 + - 物料面板：可以查找组件，并在此拖动组件到编辑器画布中 + - 源码面板：可以编辑页面级别的 JavaScript 代码和 CSS 配置 + - 提交 Issue：可以给引擎开发提 bug + - Schema 编辑：可以编辑页面的底层数据 + - 中英文切换：可以切换编辑器的语言 +- 中部：可视化页面编辑画布区域 + - 点击组件在右侧面板中能够显示出对应组件的属性配置选项 + - 拖拽修改组件的排列顺序 + - 将组件拖拽到容器类型的组件中 + - 复制组件：点击组件右上角的复制按钮 + - 删除组件：点击组件右上角的 X 或者直接使用 `Delete` 键 +- 右侧：组件级别配置 + - 选中的组件：从页面开始一直到当前选中的组件位置，点击对应的名称可以切换到对应的组件上 + - 选中组件的配置：当前组件的大类目选项，根据组件类型不同，包含如下子类目： + - 属性：组件的基础属性值设置 + - 样式：组件的样式配置 + - 事件：绑定组件对外暴露的事件 + - 高级：循环、条件渲染与 key 设置 + +# 深入使用低代码引擎 Demo + +我们在低代码引擎 Demo 中直接内置了产品使用文档，对常见场景中的使用进行了向导，它的入口如下： + +![image.png](https://cdn.nlark.com/yuque/0/2022/png/242652/1647163471895-a12d0f5d-e09e-462d-bd0b-b633c64afb15.png#clientId=uecc3752b-3539-4&crop=0&crop=0&crop=1&crop=1&from=paste&height=825&id=u86d6fa24&margin=%5Bobject%20Object%5D&name=image.png&originHeight=1650&originWidth=3070&originalType=binary&ratio=1&rotation=0&showTitle=false&size=1040703&status=done&style=none&taskId=u54aeddda-78e0-4259-b184-d06e2dba10b&title=&width=1535) + +如果暂时没有看到对应的产品使用文档，可以通过此永久链接直接访问：[https://www.yuque.com/lce/usage](https://www.yuque.com/lce/usage) diff --git a/docs/docs/guide/quickStart/intro.md b/docs/docs/guide/quickStart/intro.md new file mode 100644 index 000000000..67750b2a9 --- /dev/null +++ b/docs/docs/guide/quickStart/intro.md @@ -0,0 +1,48 @@ +--- +title: 简介 +sidebar_position: 0 +--- + +# 阿里低代码引擎简介 + +## 低代码介绍 + +零代码、低代码的概念在整个全球行业内已经流行了很长一段时间。通常意义上的低代码定义会有三个关键点： + +1. 一个用于生产软件的可视化编辑器 +2. 中间包含了一些用于组装的物料，可以通过编排、组合和配置它们以生成丰富的功能或表现 +3. 最后的实施结果是成本降低 + +通常情况下低代码平台会具备以下的几个能力： + +- **可视化页面搭建**，通过简单的拖拽完成应用页面开发，对前端技能没有要求或不需要特别专业的了解； +- **可视化模型设计**，与业务相关的数据存储变得更容易理解，甚至大多数简单场景可以做到表单即模型，模型字段的类型更加业务化； +- **可视化流程设计**，不管是业务流程还是审批流程，都可以通过简单的点线连接来进行配置； +- **可视化报表及数据分析**，BI数据分析能力成为标配，随时随地通过拖拽选择来定义自定义分析报表； +- **可视化服务与数据开放、集成**，具备与其他系统互联互通的配置； +- **权限、角色设置标准化和业务化**，通过策略规则配置来将数据、操作的权限进行精细化管理； +- **无需关心服务器、数据库等底层运维、计算设施设备、网络等等复杂技术概念**，具备安全、性能的统一解决方案，开发者只需要专注于业务本身； + +有了上面这些，你会发现即使是个技术小白，只要你了解业务，就能不受束缚的完成大多数业务应用的搭建。但低代码本身也不仅仅是为技术小白准备的。在实践中，低代码因为通过组件化、模块化的思路让业务的抽象更加容易，而且在扩展及配置化上带来了更加新鲜的模式探索，技术人员的架构设计成本和实施成本也就降了很多。 + +市面上常见的低代码产品[可以看 Golden 的梳理](https://golden.com/wiki/No-code_%2F_low-code_development-NMGMEA6)。 + +## 低代码引擎介绍 + +**低代码引擎是一款为低代码平台开发者提供的，具备强大定制扩展能力的低代码设计器研发框架。** + +下面简单描述定义中的子部分： + +**低代码设计器** +现如今低代码平台越来越多，而每一个低代码平台中都会有的一个能力就是搭建和配置页面、模块的页面，这个页面我们称为设计器。例如，下图是中后台低代码平台的设计器。 +![image.png](https://img.alicdn.com/imgextra/i4/O1CN01LunuQh23b5NtP8k86_!!6000000007273-2-tps-1682-969.png?originHeight=1914&originWidth=3838&originalType=binary&ratio=1&rotation=0&showTitle=false&size=538736&status=done&style=stroke&taskId=u9a19d4d1-4d87-4b4e-b7cc-3aedfb00aaa&title=&width=1080) +设计器承载着低代码平台的核心功能，包括入料、编排、组件配置、画布渲染等等。由于其功能多，打磨精细难，也是低代码平台建设最耗时的地方。 + +**定制扩展能力** + +什么是扩展能力呢，一方面我们可以快速拥有一份标准的低代码设计器，另外一方面如果有业务独特的功能需要，我们可以不用看它的源码、不用关心其实现，可以使用 API、插件等方式快速完成能力的开发。 +而低代码引擎对于设计器的扩展能力支持基本上覆盖了低代码设计器的所有功能点。下图是针对标准的设计器提供了扩展功能的区域。 +![](https://cdn.nlark.com/yuque/0/2022/png/242652/1643446752531-8b1493d4-ea8a-463b-9631-6bb4fc681719.png#clientId=u2b839b63-1827-4&crop=0&crop=0&crop=1&crop=1&from=drop&height=539&id=ucff2881c&margin=%5Bobject%20Object%5D&name=image.png&originHeight=1914&originWidth=3838&originalType=binary&ratio=1&rotation=0&showTitle=false&size=538736&status=done&style=stroke&taskId=u9a19d4d1-4d87-4b4e-b7cc-3aedfb00aaa&title=&width=1080) +**低代码设计器研发框架** + +低代码引擎的核心是设计器，通过扩展、周边生态等可以产出各式各样的设计器。它不是一套可以适合所有人的低代码平台，而是帮助低代码平台的开发者，快速生产低代码平台的工具。 diff --git a/docs/docs/guide/quickStart/start.md b/docs/docs/guide/quickStart/start.md new file mode 100644 index 000000000..001e4e789 --- /dev/null +++ b/docs/docs/guide/quickStart/start.md @@ -0,0 +1,296 @@ +--- +sidebar_position: 2 +title: 快速开始 +--- +# 前置知识 +我们假定你已经对 HTML 和 JavaScript 都比较熟悉了。即便你之前使用其他编程语言，你也可以跟上这篇教程的。除此之外，我们假定你也已经熟悉了一些编程的概念，例如，函数、对象、数组，以及 class 的一些内容。
如果你想回顾一下 JavaScript，你可以阅读[这篇教程](https://developer.mozilla.org/zh-CN/docs/Web/JavaScript/A_re-introduction_to_JavaScript)。注意，我们也用到了一些 ES6（较新的 JavaScript 版本）的特性。在这篇教程里，我们主要使用了[箭头函数（arrow functions）](https://developer.mozilla.org/zh-CN/docs/Web/JavaScript/Reference/Functions/Arrow_functions)、[class](https://developer.mozilla.org/zh-CN/docs/Web/JavaScript/Reference/Classes)、[let](https://developer.mozilla.org/zh-CN/docs/Web/JavaScript/Reference/Statements/let) 语句和 [const](https://developer.mozilla.org/zh-CN/docs/Web/JavaScript/Reference/Statements/const) 语句。你可以使用 [Babel REPL](https://babeljs.io/repl/#?presets=react&code_lz=MYewdgzgLgBApgGzgWzmWBeGAeAFgRgD4AJRBEAGhgHcQAnBAEwEJsB6AwgbgChRJY_KAEMAlmDh0YWRiGABXVOgB0AczhQAokiVQAQgE8AkowAUAcjogQUcwEpeAJTjDgUACIB5ALLK6aRklTRBQ0KCohMQk6Bx4gA) 在线预览 ES6 的编译结果。 + +# 环境准备 +## WSL（Window 电脑） +Window 环境需要使用 WSL 在 windows 下进行低代码引擎相关的开发。安装教程 ➡️ [WSL 安装教程](https://docs.microsoft.com/zh-cn/windows/wsl/install)。
**对于 Window 环境来说，之后所有需要执行命令的操作都是在 WSL 终端执行的。** +## Node +node 版本推荐 14.17.0。 + +### 查看 Node 版本 +![image.png](https://cdn.nlark.com/yuque/0/2022/png/2622706/1660653856191-128d8e3f-9636-4b73-94ab-c03cf6965365.png#clientId=ubcf63daf-5747-4&crop=0&crop=0&crop=1&crop=1&from=paste&height=35&id=u44a9af04&margin=%5Bobject%20Object%5D&name=image.png&originHeight=70&originWidth=238&originalType=binary&ratio=1&rotation=0&showTitle=false&size=11948&status=done&style=none&taskId=udb616117-a27c-409d-9e1c-1b89931a714&title=&width=119) + +### 变更 node 版本 +可以安装 [n](https://www.npmjs.com/package/n) 来管理和变更 node 版本。 + +#### 安装 +```json +npm install -g n +``` + +#### 变更 node 版本 +```json +n 14.17.0 +``` + +## React +低代码引擎的扩展能力都是基于 React 来研发的，在继续阅读之前最好有一定的 React 基础，React 学习教程 ➡️ [React 快速开始教程](https://zh-hans.reactjs.org/docs/getting-started.html)。 + +## 下载 Demo +可以前往 github（https://github.com/alibaba/lowcode-demo）将 DEMO 下载到本地。 + +### git clone +#### HTTPS +需要使用到 git 工具 +```json +git clone https://github.com/alibaba/lowcode-demo.git +``` +#### SSH +需要配置 SSH key，如果没有配置可以 +```json +git clone git@github.com:alibaba/lowcode-demo.git +``` + +### 下载 Zip 包 +![image.png](https://cdn.nlark.com/yuque/0/2022/png/2622706/1660653725650-ab734ba4-64a7-4801-9d2f-5c496879054f.png#clientId=ubcf63daf-5747-4&crop=0&crop=0&crop=1&crop=1&from=paste&height=897&id=uc1b07458&margin=%5Bobject%20Object%5D&name=image.png&originHeight=1794&originWidth=3584&originalType=binary&ratio=1&rotation=0&showTitle=false&size=1306258&status=done&style=stroke&taskId=ubaa4eb12-0e87-464e-b3da-306ed9685b7&title=&width=1792) + +## 安装依赖 +在 lowcode-demo 目录下执行： +```json +npm install +``` + +## 启动 demo +在 lowcode-demo 目录下执行： +```json +npm run start +``` + +之后就可以通过 [http://localhost:5556/](http://localhost:5556/) 来访问我们的 DEMO 了。 +# 认识 Demo +我们的 Demo 是一个**低代码平台的设计器**。它是一个低代码平台中最重要的一环，用户可以在这里通过拖拽、配置、写代码等等来完成一个页面的开发。由于用户的人群不同、场景不同、诉求不同等等，这个页面的功能就会有所差异。
这里记住**设计器**这个词，它描述的就是下面的这个页面，后面我们会经常看到它。
![image.png](https://cdn.nlark.com/yuque/0/2022/png/2622706/1660654189055-45fd0c7e-75cb-4072-a4d4-7cf244405c7d.png#clientId=ubcf63daf-5747-4&crop=0&crop=0.008&crop=1&crop=1&from=paste&height=904&id=LBi2j&margin=%5Bobject%20Object%5D&name=image.png&originHeight=1808&originWidth=3584&originalType=binary&ratio=1&rotation=0&showTitle=false&size=763122&status=done&style=stroke&taskId=u82753ad5-3b5d-43b2-b309-a99c2a7bb24&title=&width=1792) + +## 场景介绍 +![image.png](https://cdn.nlark.com/yuque/0/2022/png/2622706/1660654738730-490fc94a-8b42-4c48-b21e-4c0694416b07.png#clientId=ubcf63daf-5747-4&crop=0&crop=0&crop=1&crop=1&from=paste&height=903&id=ub700edc2&margin=%5Bobject%20Object%5D&name=image.png&originHeight=1806&originWidth=3584&originalType=binary&ratio=1&rotation=0&showTitle=false&size=802013&status=done&style=stroke&taskId=u317bff98-636d-402a-98f2-f9e0b08293b&title=&width=1792) + +Demo 根据**不同的设计器所需要的物料不同**，分为了下面的 8 个场景： + +- 综合场景 +- 基础 fusion 组件 +- 基础 fusion 组件 + 单自定义组件 +- 基础 antd 组件 +- 自定义初始化引擎 +- 扩展节点操作项 +- 基于next实现的高级表单低代码物料 +- antd 高级组件 + formily 表单组件 + +可以点开不同的场景，看看他们使用的物料。 + +## 目录介绍 +仓库下的 src/scenarios 目录就对应刚刚介绍的场景。
![image.png](https://cdn.nlark.com/yuque/0/2022/png/2622706/1660655237007-fddd8534-d4ed-4a25-ba2f-f335f8ac3c36.png#clientId=ubcf63daf-5747-4&crop=0&crop=0&crop=1&crop=1&from=paste&height=348&id=ubf68019d&margin=%5Bobject%20Object%5D&name=image.png&originHeight=696&originWidth=696&originalType=binary&ratio=1&rotation=0&showTitle=false&size=148777&status=done&style=stroke&taskId=u68648c51-7648-494e-bd41-4f29fb144f9&title=&width=348) + +不同场景的目录结构实际上都是类似的，这里我们主要介绍一下综合场景的目录结构即可。
![image.png](https://cdn.nlark.com/yuque/0/2022/png/2622706/1660655399364-b40d206a-977d-4000-9be1-681823f8a995.png#clientId=ubcf63daf-5747-4&crop=0&crop=0&crop=1&crop=1&from=paste&height=1010&id=ub727a7fa&margin=%5Bobject%20Object%5D&name=image.png&originHeight=2020&originWidth=3584&originalType=binary&ratio=1&rotation=0&showTitle=false&size=1373541&status=done&style=stroke&taskId=ue55dc86f-375d-4c7f-a63f-d5208683035&title=&width=1792)
综合场景目录下只有一个文件，这个文件做了几个事情： + +- 通过 plugins.register 注册「切换场景」的插件，也就是上面介绍的切换场景的功能。 +- 通过 registerPlugins 注册更多的插件： + - ManualPlugin：增加弹出「低代码产品使用文档」按钮 + - Inject：支持调试功能 + - registerRefProp：支持给每个组件注入 ref + - ... +- 通过 init 初始化低代码设计器 + +做了这些事情之后，我们的低代码设计器就已经有了基本的能力了。也就是最开始我们看到的这样。
![image.png](https://cdn.nlark.com/yuque/0/2022/png/2622706/1660654189055-45fd0c7e-75cb-4072-a4d4-7cf244405c7d.png#clientId=ubcf63daf-5747-4&crop=0&crop=0.008&crop=1&crop=1&from=paste&height=904&id=MZdfk&margin=%5Bobject%20Object%5D&name=image.png&originHeight=1808&originWidth=3584&originalType=binary&ratio=1&rotation=0&showTitle=false&size=763122&status=done&style=stroke&taskId=u82753ad5-3b5d-43b2-b309-a99c2a7bb24&title=&width=1792) + +接下来我们就根据我们自己的诉求通过对设计器进行扩展，改动成我们需要的设计器功能。 +# 开发一个插件 +## 方式1：在 DEMO 中直接新增插件 +![image.png](https://cdn.nlark.com/yuque/0/2022/png/2622706/1660656064139-8da57c37-7e0b-4e8d-9f2d-8ea86d5af134.png#clientId=ubcf63daf-5747-4&crop=0&crop=0&crop=1&crop=1&from=paste&height=280&id=uc7f75c37&margin=%5Bobject%20Object%5D&name=image.png&originHeight=560&originWidth=820&originalType=binary&ratio=1&rotation=0&showTitle=false&size=125690&status=done&style=stroke&taskId=u53c07118-a2ca-4a77-a27f-3b2b20085ac&title=&width=410) + +可以在 demo/sample-plugins 直接新增插件，这里我新增的插件目录是 plugin-demo。并且新增了 index.tsx 文件，将下面的代码粘贴到 index.tsx 中。 +```javascript +import * as React from 'react'; +import { ILowCodePluginContext } from '@alilc/lowcode-engine'; + +const LowcodePluginPluginDemo = (ctx: ILowCodePluginContext) => { + return { + // 插件对外暴露的数据和方法 + exports() { + return { + data: '你可以把插件的数据这样对外暴露', + func: () => { + console.log('方法也是一样'); + }, + } + }, + // 插件的初始化函数，在引擎初始化之后会立刻调用 + init() { + // 你可以拿到其他插件暴露的方法和属性 + // const { data, func } = ctx.plugins.pluginA; + // func(); + + // console.log(options.name); + + // 往引擎增加面板 + ctx.skeleton.add({ + area: 'leftArea', + name: 'LowcodePluginPluginDemoPane', + type: 'PanelDock', + props: { + description: 'Demo', + }, + content:
这是一个 Demo 面板
, + }); + + ctx.logger.log('打个日志'); + }, + }; +}; + +// 插件名，注册环境下唯一 +LowcodePluginPluginDemo.pluginName = 'LowcodePluginPluginDemo'; +LowcodePluginPluginDemo.meta = { + // 依赖的插件（插件名数组） + dependencies: [], + engines: { + lowcodeEngine: '^1.0.0', // 插件需要配合 ^1.0.0 的引擎才可运行 + }, +} + +export default LowcodePluginPluginDemo; +``` + +在 src/scenarios/index/index.ts 中新增下面代码
![image.png](https://cdn.nlark.com/yuque/0/2022/png/2622706/1660656497051-49e08633-2d78-428c-becc-c282905cdb90.png#clientId=ubcf63daf-5747-4&crop=0&crop=0&crop=1&crop=1&from=paste&height=1010&id=u426edc7b&margin=%5Bobject%20Object%5D&name=image.png&originHeight=2020&originWidth=3584&originalType=binary&ratio=1&rotation=0&showTitle=false&size=1458910&status=done&style=stroke&taskId=uf1e42399-caf7-4d82-a797-698fa730486&title=&width=1792) + +这样在我们的设计器中就新增了一个 Demo 面板。
![image.png](https://cdn.nlark.com/yuque/0/2022/png/2622706/1660656566260-86dfed37-60d0-45ca-967e-5df8ea7a34d0.png#clientId=ubcf63daf-5747-4&crop=0&crop=0.0053&crop=1&crop=1&from=paste&height=903&id=u17565cd3&margin=%5Bobject%20Object%5D&name=image.png&originHeight=1806&originWidth=3584&originalType=binary&ratio=1&rotation=0&showTitle=false&size=734227&status=done&style=stroke&taskId=u5dbe00f3-447b-451e-ac48-9b02281afc3&title=&width=1792) +## 方式2：在新的仓库下开发插件 +初始化 +```json +npm init @alilc/element your-plugin-name +``` + +选择设计器插件（plugin）
![image.png](https://cdn.nlark.com/yuque/0/2022/png/2622706/1660702297326-ccfe60f9-ee22-4a24-a293-26351d107663.png#clientId=udb19495f-ea47-4&crop=0&crop=0&crop=1&crop=1&from=paste&height=107&id=ub2bf5248&margin=%5Bobject%20Object%5D&name=image.png&originHeight=214&originWidth=730&originalType=binary&ratio=1&rotation=0&showTitle=false&size=82091&status=done&style=stroke&taskId=u82628265-73f0-4d57-b4ba-1b18600a1f0&title=&width=365) + +根据操作完善信息
![image.png](https://cdn.nlark.com/yuque/0/2022/png/2622706/1660702439529-867a893f-f27a-4e48-8a5a-ee45aa97e355.png#clientId=udb19495f-ea47-4&crop=0&crop=0&crop=1&crop=1&from=paste&height=109&id=uc9b09fec&margin=%5Bobject%20Object%5D&name=image.png&originHeight=218&originWidth=866&originalType=binary&ratio=1&rotation=0&showTitle=false&size=102705&status=done&style=stroke&taskId=ue4a95f21-43d3-4da8-9c0e-b21dfe239bf&title=&width=433) + +插件项目就初始化完成了
![image.png](https://cdn.nlark.com/yuque/0/2022/png/2622706/1660702464438-3d7e07eb-53c7-417c-9e6d-06fdf9acfb86.png#clientId=udb19495f-ea47-4&crop=0&crop=0&crop=1&crop=1&from=paste&height=280&id=u0ee65b4e&margin=%5Bobject%20Object%5D&name=image.png&originHeight=2020&originWidth=3584&originalType=binary&ratio=1&rotation=0&showTitle=false&size=1197702&status=done&style=stroke&taskId=u5f9fdae3-1adc-4b02-969c-5c43c3d4c9c&title=&width=496) + +在插件项目下安装依赖 +```json +npm install +``` + +启动项目 +```json +npm run start +``` + +调试项目
![image.png](https://cdn.nlark.com/yuque/0/2022/png/2622706/1660705712773-f2446689-2b5f-42e7-9e85-30857270dfbb.png#clientId=udb19495f-ea47-4&crop=0&crop=0&crop=1&crop=1&from=paste&height=346&id=u448649c5&margin=%5Bobject%20Object%5D&name=image.png&originHeight=1936&originWidth=3584&originalType=binary&ratio=1&rotation=0&showTitle=false&size=757713&status=done&style=stroke&taskId=u0b617456-826e-4993-951e-303da417172&title=&width=641) + +在 Demo 中调试项目
在 build.json 下面新增 "inject": true，就可以在 [https://lowcode-engine.cn/demo/index.html?debug](https://lowcode-engine.cn/demo/index.html?debug) 页面下进行调试了。
![image.png](https://cdn.nlark.com/yuque/0/2022/png/2622706/1660705860117-5a11a5fa-9215-4b94-84b7-497899cafe10.png#clientId=udb19495f-ea47-4&crop=0&crop=0&crop=1&crop=1&from=paste&height=1010&id=u3a36c42f&margin=%5Bobject%20Object%5D&name=image.png&originHeight=2020&originWidth=3584&originalType=binary&ratio=1&rotation=0&showTitle=false&size=887101&status=done&style=stroke&taskId=u747bc337-5212-4a8b-a88f-127c53ea621&title=&width=1792) +# 开发一个自定义物料 +## 初始化物料 +```json +npm init @alilc/element your-material-demo +``` +选择组件/物料栏
![image.png](https://cdn.nlark.com/yuque/0/2022/png/2622706/1660706045985-db73ca55-925a-446b-ace4-b59fa1e18469.png#clientId=udb19495f-ea47-4&crop=0&crop=0&crop=1&crop=1&from=paste&height=104&id=kuWIf&margin=%5Bobject%20Object%5D&name=image.png&originHeight=208&originWidth=824&originalType=binary&ratio=1&rotation=0&showTitle=false&size=88910&status=done&style=stroke&taskId=u92f5fa65-386a-4f52-a093-bcbbebdc2d7&title=&width=412) + +配置其他信息
![image.png](https://cdn.nlark.com/yuque/0/2022/png/2622706/1660706116845-9b3b938f-c132-426b-81bd-d49283ebf9e8.png#clientId=udb19495f-ea47-4&crop=0&crop=0&crop=1&crop=1&from=paste&height=124&id=u941c9808&margin=%5Bobject%20Object%5D&name=image.png&originHeight=248&originWidth=800&originalType=binary&ratio=1&rotation=0&showTitle=false&size=111864&status=done&style=stroke&taskId=ue4ff4dab-3a53-4811-bf70-7fa6fc0c8b6&title=&width=400) + +这样我们就初始化好了一个 React 物料。
![image.png](https://cdn.nlark.com/yuque/0/2022/png/2622706/1660706173968-3e5db25a-e08d-4852-90c9-ffaa0968fd62.png#clientId=udb19495f-ea47-4&crop=0&crop=0&crop=1&crop=1&from=paste&height=1010&id=u854b37cc&margin=%5Bobject%20Object%5D&name=image.png&originHeight=2020&originWidth=3584&originalType=binary&ratio=1&rotation=0&showTitle=false&size=1080400&status=done&style=stroke&taskId=u10e21350-23d4-4d8f-8c16-0c5a221fc2e&title=&width=1792) +## 启动并调试物料 +### 安装依赖 +```json +npm i +``` +### 启动 +```json +npm run lowcode:dev +``` + +我们就可以通过 [http://localhost:3333/](http://localhost:3333/) 看到我们的研发的物料了。
![image.png](https://cdn.nlark.com/yuque/0/2022/png/2622706/1660706484894-73798e35-1e58-4ffe-bb3c-bfba7b014433.png#clientId=udb19495f-ea47-4&crop=0&crop=0&crop=1&crop=1&from=paste&height=895&id=zVMiy&margin=%5Bobject%20Object%5D&name=image.png&originHeight=1790&originWidth=3584&originalType=binary&ratio=1&rotation=0&showTitle=false&size=678753&status=done&style=stroke&taskId=u241f50c0-1a43-4854-8443-7e972f15623&title=&width=1792) +### 在 Demo 中调试 +```json +npm i @alilc/build-plugin-alt +``` + +修改 build.lowcode.js
![image.png](https://cdn.nlark.com/yuque/0/2022/png/2622706/1660706733149-0170b2fb-88de-40e3-8204-f510d7e42f77.png#clientId=udb19495f-ea47-4&crop=0&crop=0&crop=1&crop=1&from=paste&height=311&id=u8a1a8bea&margin=%5Bobject%20Object%5D&name=image.png&originHeight=1046&originWidth=1388&originalType=binary&ratio=1&rotation=0&showTitle=false&size=291155&status=done&style=stroke&taskId=u61ede7d2-f92d-43b9-8582-a2362a9ea14&title=&width=413) + +如图，新增如下代码 +```json +[ + '@alilc/build-plugin-alt', + { + type: 'component', + inject: true, + library, + // 配置要打开的页面，在注入调试模式下，不配置此项的话不会打开浏览器 + // 支持直接使用官方 demo 项目：https://lowcode-engine.cn/demo/index.html + openUrl: 'https://lowcode-engine.cn/demo/index.html?debug', + }, +], +``` + +我们重新启动项目，就可以在 Demo 中找到我们的自定义组件。
![image.png](https://cdn.nlark.com/yuque/0/2022/png/2622706/1660706823666-ca28a08d-6241-4112-bc78-b9078c81fb75.png#clientId=udb19495f-ea47-4&crop=0&crop=0&crop=1&crop=1&from=paste&height=906&id=u31bdc31a&margin=%5Bobject%20Object%5D&name=image.png&originHeight=1812&originWidth=3584&originalType=binary&ratio=1&rotation=0&showTitle=false&size=788013&status=done&style=stroke&taskId=uaa4789a2-452f-4b04-8894-759989e4568&title=&width=1792) + +## 发布 +首先进行构建 +```json +npm run lowcode:build +``` + +发布组件 +```json +npm publish +``` + +这里我发布的组件是 [my-material-demo](https://www.npmjs.com/package/my-material-demo)。在发布之后我们就会有两个重要的文件： + +- 低代码描述：[https://unpkg.com/my-material-demo@0.1.0/build/lowcode/meta.js](https://unpkg.com/my-material-demo@0.1.0/build/lowcode/meta.js) +- 组件代码：[https://unpkg.com/my-material-demo@0.1.0/build/lowcode/render/default/view.js](https://unpkg.com/my-material-demo@0.1.0/build/lowcode/render/default/view.js) + +我们也可以从 [https://unpkg.com/my-material-demo@0.1.0/build/lowcode/assets-prod.json](https://unpkg.com/my-material-demo@0.1.0/build/lowcode/assets-prod.json) 找到我们的资产包描述。 +```json +{ + "packages": [ + { + "package": "my-material-demo", + "version": "0.1.0", + "library": "BizComp", + "urls": [ + "https://unpkg.com/my-material-demo@0.1.0/build/lowcode/render/default/view.js", + "https://unpkg.com/my-material-demo@0.1.0/build/lowcode/render/default/view.css" + ], + "editUrls": [ + "https://unpkg.com/my-material-demo@0.1.0/build/lowcode/view.js", + "https://unpkg.com/my-material-demo@0.1.0/build/lowcode/view.css" + ], + "advancedUrls": { + "default": [ + "https://unpkg.com/my-material-demo@0.1.0/build/lowcode/render/default/view.js", + "https://unpkg.com/my-material-demo@0.1.0/build/lowcode/render/default/view.css" + ] + }, + "advancedEditUrls": {} + } + ], + "components": [ + { + "exportName": "MyMaterialDemoMeta", + "npm": { + "package": "my-material-demo", + "version": "0.1.0" + }, + "url": "https://unpkg.com/my-material-demo@0.1.0/build/lowcode/meta.js", + "urls": { + "default": "https://unpkg.com/my-material-demo@0.1.0/build/lowcode/meta.js" + }, + "advancedUrls": { + "default": [ + "https://unpkg.com/my-material-demo@0.1.0/build/lowcode/meta.js" + ] + } + } + ], +} +``` + +## 使用 +我们将刚刚发布的组件的 assets-prod.json 的内容放到 demo 的 src/universal/assets.json 中。
*最好放到最后，防止因为资源加载顺序问题导致出现报错。
如图，新增 packages 配置
![image.png](https://cdn.nlark.com/yuque/0/2022/png/2622706/1660707789785-ea75a399-6845-45a8-8c53-08402749c9a8.png#clientId=udb19495f-ea47-4&crop=0&crop=0&crop=1&crop=1&from=paste&height=1010&id=uf0f75c17&margin=%5Bobject%20Object%5D&name=image.png&originHeight=2020&originWidth=3584&originalType=binary&ratio=1&rotation=0&showTitle=false&size=1327766&status=done&style=stroke&taskId=ub053d846-69fd-4a55-8e9e-b41d1e06e47&title=&width=1792)
如图，新增 components 配置
![image.png](https://cdn.nlark.com/yuque/0/2022/png/2622706/1660707811725-a0e36f48-910d-45b5-b162-3aa4e2f87e9b.png#clientId=udb19495f-ea47-4&crop=0&crop=0&crop=1&crop=1&from=paste&height=1010&id=uf8c9506f&margin=%5Bobject%20Object%5D&name=image.png&originHeight=2020&originWidth=3584&originalType=binary&ratio=1&rotation=0&showTitle=false&size=1222080&status=done&style=stroke&taskId=u10147f1f-27ed-4cec-bfc9-2cb3d61d6a2&title=&width=1792) + +这时候再启动 DEMO 项目，就会有新的低代码物料了。接下来就按照你们的需求，继续扩展物料吧。 +# 总结 +这里只是简单的介绍了一些低代码引擎的基础能力，带大家简单的对低代码 DEMO 进行扩展，定制一些新的功能。低代码引擎的能力还有很多很多，可以继续去探索更多的功能。 diff --git a/docs/docs/participate/config.md b/docs/docs/participate/config.md new file mode 100644 index 000000000..4e032ad1b --- /dev/null +++ b/docs/docs/participate/config.md @@ -0,0 +1,80 @@ +--- +title: 引擎的工程化配置 +sidebar_position: 3 +--- +目前引擎体系共包含 3 个 js 文件，即： +```html + + + + +``` + +工程化配置我们进行了统一，具体如下： +```shell +{ + "entry": { + ... + }, + "library": "...", + "libraryTarget": "umd", + "externals": { + "react": "var window.React", + "react-dom": "var window.ReactDOM", + "prop-types": "var window.PropTypes", + "rax": "var window.Rax", + "@alilc/lowcode-engine": "var window.AliLowCodeEngine", + "@alilc/lowcode-engine-ext": "var window.AliLowCodeEngineExt", + "moment": "var moment", + "lodash": "var _", + "@alifd/next": "var Next" + }, + "polyfill": false, + "outputDir": "dist", + "vendor": false, + "ignoreHtmlTemplate": true, + "sourceMap": true, + "plugins": [ + "build-plugin-react-app", + ["build-plugin-fusion", { + }], + ["build-plugin-moment-locales", { + "locales": ["zh-cn"] + }], + "./build.plugin.js" + ] +} + +``` +总结一下，有 2 点： + +1. **都不包含 polyfill，**需要应用级别单独引入 polyfill，推荐动态 polyfill +2. **都不包含 lodash / moment / next** + + +#### 前置依赖资源： +```html + + + + + + +``` + + +#### 所有资源： +```html + + + + + + + + + + + + +``` diff --git a/docs/docs/participate/flow.md b/docs/docs/participate/flow.md new file mode 100644 index 000000000..d80e779ee --- /dev/null +++ b/docs/docs/participate/flow.md @@ -0,0 +1,96 @@ +--- +title: 关于引擎的研发协作流程 +sidebar_position: 2 +--- +## 代码风格 +引擎项目配置了 eslint 和 stylelint，在每次 git commit 前都会检查代码风格，假如有报错，请修改后再提交。（**严禁 -n 提交，-n 也逃脱不了 github workflow 的 lint 检查，放弃吧，骚年~**） + +## 测试机制 +每次提交代码前，务必本地跑一次单元测试，通过后再提交 MR。 +假如涉及新的功能，需要**补充相应的单元测试，**目前引擎核心模块的单测覆盖率都在 80%+，假如降低了覆盖率，将会不予以通过。 + +跑单测流程： + +1. 项目根目录下执行 npm run build +2. 只改了一个包，比如 designer，则在 designer 目录下，执行 npm test +3. （or）改了多个包，则在根目录下执行 npm test +## commit 风格 +几点要求： + +1. commit message 格式遵循 [ConvensionalCommits](https://www.conventionalcommits.org/en/v1.0.0/#summary) +![image.png](https://cdn.nlark.com/yuque/0/2022/png/110793/1645066644352-4de1c64c-bff6-4482-90d1-1fb610aa91f2.png#averageHue=%23eceef0&clientId=u6dcee4f0-35df-4&crop=0&crop=0&crop=1&crop=1&height=297&id=CfpQy&margin=%5Bobject%20Object%5D&name=image.png&originHeight=594&originWidth=2070&originalType=binary&ratio=1&rotation=0&showTitle=false&size=341605&status=done&style=none&taskId=u4499b752-5e24-42f6-9186-280fd5a51aa&title=&width=1035) +2. 请按照一个 bugfix / feature 对应一个 commit，假如不是，请 rebase 后再提交 MR，不要一堆无用的、试验性的 commit + +好处：从引擎的整体 commit 历史来看，会很清晰，**每个 commit 完成一件确定的事，changelog 也能自动生成。**另外，假如因为某个 commit 导致了 bug，也很容易通过 rebase drop 等方式快速修复。 +## 引擎发布机制 +日常迭代先从 develop 拉分支，然后自测、单测通过后，提交 MR 到 develop 分支，由发布负责人基于 develop 拉 release/1.0.z 分支~ + +### 分支用途 + +- main 分支，最稳定的分支，跟 npm latest 包的内容保持一致 +- develop 分支，开发分支，拥有最新的、已经验证过的 feature / bugfix，Pull Request 的**目标合入分支** +- release 分支 + - 正式发布分支，命名规则为 release/x.y.z，一般从 develop 拉出来进行发布，x.y.z 为待发布的版本号 + - beta 发布分支，命名规则为 release/x.y.z-beta(\.\d+)?，可以快速验证修改，发布 npm beta 版本。 +验证通过后，因为 beta 发布分支上会存在无用的 commit（比如 lerna 修改 package.json 这种），所以不直接 PR 到 develop，而是从 develop 拉分支，从 beta 发布分支 cherry pick 有用的 commit 到新分支，然后 PR 到 develop。 + +### 发布步骤 +> **发布需要权限，如果提 PR 之后着急发布可以**[**加入贡献者交流群**](https://www.yuque.com/lce/doc/pctr1f#d5WKy)**。** + +如果是发布正式版本，步骤如下（以发布 1.0.0 版本为例）： + +1. git checkout develop +2. git checkout -b release/1.0.0 +3. npm run build +4. npm run pub +5. tnpm run sync（此步骤将发布在 npm 源的包同步到阿里内网源，因为 alifd cdn 将依赖内网 npm 源） +6. 更新[发布日志](https://github.com/alibaba/lowcode-engine/releases) +7. 合并 release/x.x.x 到 main 分支 +8. 合并 main 分支到 develop 分支 + +如果是发布beta 版本，步骤如下（以发布 1.0.1 版本为例）： + +1. git checkout develop +2. git checkout -b release/1.0.1-beta +3. npm run build +4. npm run pub:prepatch（将 lerna 版本号从 1.0.0 改到 1.0.1-beta.0，若是从 1.0.1-beta.0 改到 1.0.1-beta.1，则用 npm run pub:prerelease） +5. tnpm run sync + +注：在 release/1.0.1-beta 上可以直接提交，以便快速测试和验证，不过如何合入 develop，参考 [分支用途](#uem7W) 一节说明。 + +### 发布周期 +**发布周期暂时不固定，按需发布~** + +## 物料发布机制 + + +## DEMO 发布机制 +**修改版本号** +手动修改 package.json 的版本号 + +**build** +```typescript +npm run build +``` + +**publish** +```typescript +npm run pub +``` +需要权限 + +*发布 beta 版本 +```typescript +npm publish --tag beta +``` + +**同步** +```typescript +tnpm run sync +``` +缺少这一步相关的 cdn 地址可能 404 + + + +**官网生效** +需要在通过阿里内部系统更新 demo 版本 diff --git a/docs/docs/participate/index.md b/docs/docs/participate/index.md new file mode 100644 index 000000000..7a652e59a --- /dev/null +++ b/docs/docs/participate/index.md @@ -0,0 +1,26 @@ +--- +title: 低代码引擎贡献者指南 +sidebar_position: 0 +--- +### 首个 Pull Request +在写第一个 Pull Request？你可以从这一系列视频中学习怎么做： +[How to Contribute to an Open Source Project on GitHub](https://egghead.io/courses/how-to-contribute-to-an-open-source-project-on-github) +为了使你能够快速上手和熟悉贡献流程，我们这里有个列表 [good first issues](https://github.com/alibaba/lowcode-engine/issues?q=is:open+is:issue+label:%22good+first+issue%22)，里面有相对没那么笼统的漏洞，从这开始是个不错的选择。 +如果你想解决一个 issue，请确定检查了该 issue 下的评论以防有人正在处理它。如果目前没人在处理该 issue，那么请留下评论去表明你想处理该 issue 以便其他人不会意外重复你的工作。 +如果有人留言表明要处理该 issue 但是超过两周没有跟进，你可以接手工作，不过也应该留言说明。 + +### 提交 Pull Request +核心团队时刻关注 pull requests，我们会先评审你的 pull request，之后可能会合并，可能会要求再次更改，也可能会关闭该 pull request 并对此作出解释。我们会尽力全程更新和反馈。 + +**提交 pull request 前**，请确保完成以下步骤： + +1. Fork [此仓库](https://github.com/alibaba/lowcode-engine)，从 main 创建分支。 +2. 在仓库根目录下执行 yarn。 +3. 如果你修复了 bug 或者添加了代码，而这些内容需要测试，请添加测试！ +4. 确保通过测试套件（yarn test）。 +5. 请签订贡献者许可证协议（Contributor License Agreement）。 + +### 核心贡献者交流 +如果你想长期参与到项目维护中，我们提供了一个核心贡献者交流群。 +1.可以通过[填写问卷](https://survey.taobao.com/apps/zhiliao/4YEtu9gHF)的方式，参与到其中。 +2.填写问卷后加微信号 wxidvlalalalal，说明一下 diff --git a/docs/docs/participate/prepare.md b/docs/docs/participate/prepare.md new file mode 100644 index 000000000..f0fbeb394 --- /dev/null +++ b/docs/docs/participate/prepare.md @@ -0,0 +1,61 @@ +--- +title: 如何配置引擎调试环境 +sidebar_position: 1 +--- +低代码引擎的核心仓库是不包含任何物料、插件、setter 的，它本身用于生成低代码引擎的主包。 +如果您需要对低代码的主包进行开发和调试，需要用到本文里介绍的知识。 +如果您需要对低代码编辑器进行定制，您可能只需要 clone [lowcode-demo 项目](https://github.com/alibaba/lowcode-demo)并进行修改，参考“[配置低代码扩展点](https://www.yuque.com/lce/doc/srdo3s#oPhoE)”章节。 + +> 前置条件： +> node >= 14 + +### 1. 拉取代码，启动项目 +```bash +git clone git@github.com:alibaba/lowcode-engine.git +cd lowcode-engine +npm install && npm run setup +npm start + + +git clone git@github.com:alibaba/lowcode-demo.git +cd lowcode-demo +npm install && npm start +``` + +### 2. 配置资源代理 +本质上是将 demo 页面引入的几个 js/css 代理到 engine 项目，可以使用趁手的代理工具，这里推荐 [XSwitch](https://chrome.google.com/webstore/detail/xswitch/idkjhjggpffolpidfkikidcokdkdaogg?hl=en-US)。 + +本地开发代理规则如下： +```json +{ + "proxy": [ + [ + "https://alifd.alicdn.com/npm/@alilc/lowcode-engine@(.*)/dist/js/engine-core.js", + "http://localhost:5555/js/engine-core.js" + ], + [ + "https://alifd.alicdn.com/npm/@alilc/lowcode-engine@(.*)/dist/css/engine-core.css", + "http://localhost:5555/css/engine-core.css" + ], + [ + "https?://alifd.alicdn.com/npm/@alilc/lowcode-engine@(.*)/dist/js/react-simulator-renderer.js", + "http://localhost:5555/js/react-simulator-renderer.js" + ], + [ + "https?://alifd.alicdn.com/npm/@alilc/lowcode-engine@(.*)/dist/css/react-simulator-renderer.css", + "http://localhost:5555/css/react-simulator-renderer.css" + ], + [ + "https?://alifd.alicdn.com/npm/@alilc/lowcode-engine@(.*)/dist/js/rax-simulator-renderer.js", + "http://localhost:5555/js/rax-simulator-renderer.js" + ], + [ + "https?://alifd.alicdn.com/npm/@alilc/lowcode-engine@(.*)/dist/css/rax-simulator-renderer.css", + "http://localhost:5555/css/rax-simulator-renderer.css" + ], + ] +} +``` + +### 3. 本地调试物料/插件/设置器 +[详见](https://www.yuque.com/lce/doc/ulvlkz#Ioc87) diff --git a/docs/docusaurus.config.js b/docs/docusaurus.config.js new file mode 100644 index 000000000..68728ca21 --- /dev/null +++ b/docs/docusaurus.config.js @@ -0,0 +1,132 @@ +/* eslint-disable @typescript-eslint/no-require-imports */ +// Note: type annotations allow type checking and IDEs autocompletion + +const lightCodeTheme = require('prism-react-renderer/themes/github'); +const darkCodeTheme = require('prism-react-renderer/themes/dracula'); +const navbar = require('./config/navbar'); + +/** @type {import('@docusaurus/types').Config} */ +const config = { + title: 'Low-Code Engine', + tagline: 'Low-Code Engine is awesome!', + url: 'https://lowcode-engine.cn', + baseUrl: '/site/', + onBrokenLinks: 'throw', + onBrokenMarkdownLinks: 'warn', + favicon: + 'https://img.alicdn.com/imgextra/i2/O1CN01TNJDDg20pKniPOkN4_!!6000000006898-2-tps-66-78.png', + + organizationName: 'alibaba', // Usually your GitHub org/user name. + projectName: 'lowcode-engine', // Usually your repo name. + + i18n: { + defaultLocale: 'zh-Hans', + locales: ['zh-Hans'], + }, + + plugins: [ + [ + '@docusaurus/plugin-content-docs', + { + id: 'community', + path: 'community', + routeBasePath: 'community', + sidebarPath: require.resolve('./config/sidebarsCommunity.js'), + }, + ], + ], + + presets: [ + [ + 'classic', + /** @type {import('@docusaurus/preset-classic').Options} */ + ({ + docs: { + sidebarPath: require.resolve('./config/sidebars.js'), + // lastVersion: 'current', + editUrl: + 'https://github.com/alibaba/lowcode-engine/tree/develop/docs/', + }, + theme: { + customCss: require.resolve('./src/css/custom.css'), + }, + }), + ], + ], + + themeConfig: + /** @type {import('@docusaurus/preset-classic').ThemeConfig} */ + ({ + docs: { + sidebar: { + hideable: true, + }, + }, + navbar, + footer: { + // style: 'dark', + links: [ + {}, + { + title: '低代码引擎协议栈', + items: [ + { + label: '《低代码引擎搭建协议规范》', + href: 'https://lowcode-engine.cn/lowcode', + }, + { + label: '《低代码引擎物料协议规范》', + href: 'https://lowcode-engine.cn/material', + }, + { + label: '《低代码引擎资产包协议规范》', + href: 'https://lowcode-engine.cn/assets', + }, + ], + }, + {}, + { + title: '案例产品', + items: [ + { + label: '钉钉宜搭', + href: 'https://www.aliwork.com/', + }, + { + label: 'Parts 造物', + href: 'https://parts.lowcode-engine.cn/', + }, + { + label: 'UIPaaS 低代码平台孵化器', + href: 'https://uipaas.net', + }, + ], + }, + {}, + ], + copyright: `Copyright © ${new Date().getFullYear()} 阿里巴巴集团, Inc. Built with Docusaurus.`, + }, + // 主题切换 + prism: { + theme: lightCodeTheme, + darkTheme: darkCodeTheme, + }, + // 语雀文档导出的图片，会进行 referrer 校验，这里设置关闭，不然加载不了语雀的图片 + metadata: [{ name: 'referrer', content: 'no-referrer' }], + }), + + themes: [ + [ + require.resolve('@easyops-cn/docusaurus-search-local'), + { + hashed: true, + // For Docs using Chinese, The `language` is recommended to set to: + // ``` + language: ['en', 'zh'], + // ``` + }, + ], + ], +}; + +module.exports = config; diff --git a/docs/package.json b/docs/package.json new file mode 100644 index 000000000..306b58cac --- /dev/null +++ b/docs/package.json @@ -0,0 +1,62 @@ +{ + "name": "@alilc/lowcode-engine-docs", + "version": "0.0.1-beta.3", + "description": "低代码引擎版本化文档", + "license": "MIT", + "files": [ + "build" + ], + "scripts": { + "docusaurus": "docusaurus", + "start": "docusaurus start --host 0.0.0.0", + "build": "docusaurus build", + "swizzle": "docusaurus swizzle", + "deploy": "docusaurus deploy", + "clear": "docusaurus clear", + "serve": "docusaurus serve", + "write-translations": "docusaurus write-translations", + "write-heading-ids": "docusaurus write-heading-ids", + "typecheck": "tsc" + }, + "dependencies": { + "@docusaurus/core": "^2.2.0", + "@docusaurus/preset-classic": "^2.2.0", + "@easyops-cn/docusaurus-search-local": "^0.32.0", + "@mdx-js/react": "^1.6.22", + "axios": "^1.1.3", + "clsx": "^1.2.1", + "fs-extra": "^10.1.0", + "prism-react-renderer": "^1.3.5", + "react": "^17.0.2", + "react-dom": "^17.0.2" + }, + "devDependencies": { + "@docusaurus/module-type-aliases": "^2.2.0", + "@tsconfig/docusaurus": "^1.0.5", + "typescript": "^4.7.4" + }, + "browserslist": { + "production": [ + ">0.5%", + "not dead", + "not op_mini all" + ], + "development": [ + "last 1 chrome version", + "last 1 firefox version", + "last 1 safari version" + ] + }, + "engines": { + "node": ">=16.14" + }, + "publishConfig": { + "access": "public", + "registry": "https://registry.npmjs.org/" + }, + "repository": { + "type": "http", + "url": "https://github.com/alibaba/lowcode-engine/tree/main" + }, + "gitHead": "2669f179e6f899d395ce1942d0fe04f9c5ed48a6" +} diff --git a/docs/scripts/getDocsFromDir.js b/docs/scripts/getDocsFromDir.js new file mode 100644 index 000000000..1d3236fe6 --- /dev/null +++ b/docs/scripts/getDocsFromDir.js @@ -0,0 +1,60 @@ +const fs = require('fs'); +const path = require('path'); +const glob = require('glob'); +const matter = require('gray-matter'); + +module.exports = function getDocsFromDir(dir, cateList) { + // docs/ + const baseDir = path.join(__dirname, '../docs/'); + const docsDir = path.join(baseDir, dir); + + function getMarkdownOrder(filepath) { + return (matter(fs.readFileSync(filepath, 'utf-8')).data || {}).order || 100; + } + + const docs = glob.sync('*.md?(x)', { + cwd: docsDir, + // ignore: 'README.md', + }); + + const result = docs + .filter(doc => !/^index.md(x)?$/.test(doc)) + .map(doc => { + return path.join(docsDir, doc); + }) + .sort((a, b) => { + const orderA = getMarkdownOrder(a); + const orderB = getMarkdownOrder(b); + + return orderA - orderB; + }) + .map(filepath => { + // /Users/xxx/site/docs/guide/basic/router.md => guide/basic/router + const id = path + .relative(baseDir, filepath) + .replace(/\\/g, '/') + .replace(/\.mdx?/, ''); + return id; + }); + + (cateList || []).forEach(item => { + const { dir, subCategory, ...otherConfig } = item; + const indexList = glob.sync('index.md?(x)', { + cwd: path.join(baseDir, dir), + }); + if (indexList.length > 0) { + otherConfig.link = { + type: 'doc', + id: `${dir}/index`, + }; + } + result.push({ + type: 'category', + collapsed: false, + ...otherConfig, + items: getDocsFromDir(dir, subCategory), + }); + }); + + return result; +}; diff --git a/docs/src/css/custom.css b/docs/src/css/custom.css new file mode 100644 index 000000000..9b929baae --- /dev/null +++ b/docs/src/css/custom.css @@ -0,0 +1,103 @@ + +/** + * Any CSS included here will be global. The classic template + * bundles Infima by default. Infima is a CSS framework designed to + * work well for content-centric websites. + */ + +/* You can override the default Infima variables here. */ +:root { + --ifm-font-size-base: 14px; + --ifm-color-primary: #0089ff; + --ifm-color-primary-dark: #007be6; + --ifm-color-primary-darker: #0074d9; + --ifm-color-primary-darkest: #0060b3; + --ifm-color-primary-light: #1a95ff; + --ifm-color-primary-lighter: #269bff; + --ifm-color-primary-lightest: #4dacff; + --ifm-code-font-size: 95%; + --ifm-container-width-xl: 2000px; + --aa-search-input-height: 32px; + --ifm-font-family-base: -apple-system, Segoe UI, Roboto, Ubuntu, Cantarell, Noto Sans, sans-serif, BlinkMacSystemFont, + 'Segoe UI', Helvetica, Arial, sans-serif, 'Apple Color Emoji'; + --ifm-font-family-monospace: Menlo, Monaco, Consolas, "Courier New", monospace; + --ifm-global-spacing: 1.5rem; + --ifm-line-height-base: 1.85; + /* --ifm-font-color-base: #333; */ +} + +.header-github-link::before { + content: ''; + width: 24px; + height: 24px; + display: flex; + background: url("data:image/svg+xml,%3Csvg viewBox='0 0 24 24' xmlns='http://www.w3.org/2000/svg'%3E%3Cpath d='M12 .297c-6.63 0-12 5.373-12 12 0 5.303 3.438 9.8 8.205 11.385.6.113.82-.258.82-.577 0-.285-.01-1.04-.015-2.04-3.338.724-4.042-1.61-4.042-1.61C4.422 18.07 3.633 17.7 3.633 17.7c-1.087-.744.084-.729.084-.729 1.205.084 1.838 1.236 1.838 1.236 1.07 1.835 2.809 1.305 3.495.998.108-.776.417-1.305.76-1.605-2.665-.3-5.466-1.332-5.466-5.93 0-1.31.465-2.38 1.235-3.22-.135-.303-.54-1.523.105-3.176 0 0 1.005-.322 3.3 1.23.96-.267 1.98-.399 3-.405 1.02.006 2.04.138 3 .405 2.28-1.552 3.285-1.23 3.285-1.23.645 1.653.24 2.873.12 3.176.765.84 1.23 1.91 1.23 3.22 0 4.61-2.805 5.625-5.475 5.92.42.36.81 1.096.81 2.22 0 1.606-.015 2.896-.015 3.286 0 .315.21.69.825.57C20.565 22.092 24 17.592 24 12.297c0-6.627-5.373-12-12-12'/%3E%3C/svg%3E") + no-repeat; +} + +[data-theme='dark'] .header-github-link::before { + background: url("data:image/svg+xml,%3Csvg viewBox='0 0 24 24' xmlns='http://www.w3.org/2000/svg'%3E%3Cpath fill='white' d='M12 .297c-6.63 0-12 5.373-12 12 0 5.303 3.438 9.8 8.205 11.385.6.113.82-.258.82-.577 0-.285-.01-1.04-.015-2.04-3.338.724-4.042-1.61-4.042-1.61C4.422 18.07 3.633 17.7 3.633 17.7c-1.087-.744.084-.729.084-.729 1.205.084 1.838 1.236 1.838 1.236 1.07 1.835 2.809 1.305 3.495.998.108-.776.417-1.305.76-1.605-2.665-.3-5.466-1.332-5.466-5.93 0-1.31.465-2.38 1.235-3.22-.135-.303-.54-1.523.105-3.176 0 0 1.005-.322 3.3 1.23.96-.267 1.98-.399 3-.405 1.02.006 2.04.138 3 .405 2.28-1.552 3.285-1.23 3.285-1.23.645 1.653.24 2.873.12 3.176.765.84 1.23 1.91 1.23 3.22 0 4.61-2.805 5.625-5.475 5.92.42.36.81 1.096.81 2.22 0 1.606-.015 2.896-.015 3.286 0 .315.21.69.825.57C20.565 22.092 24 17.592 24 12.297c0-6.627-5.373-12-12-12'/%3E%3C/svg%3E") + no-repeat; +} + +.docusaurus-highlight-code-line { + background-color: rgba(0, 0, 0, 0.1); + display: block; + margin: 0 calc(-1 * var(--ifm-pre-padding)); + padding: 0 var(--ifm-pre-padding); +} + +html[data-theme='dark'] .docusaurus-highlight-code-line { + background-color: rgba(0, 0, 0, 0.3); +} + +.navbar__logo, +.navbar__search { + margin-right: 2rem; +} + +.hero { + padding: 5rem 0 !important; + box-shadow: var(--ifm-navbar-shadow); +} + +.homepage-content { + max-width: 1400px; + margin: 0 auto; +} + +.heroBanner { + padding: 4rem 0; + text-align: center; + position: relative; + overflow: hidden; +} + +.hero__title{ + font-size: 2.4rem; + background: -webkit-linear-gradient(315deg,#0089ff 25%,#30e724); + background-clip: text; + -webkit-background-clip: text; + -webkit-text-fill-color: transparent; + display: inline-block; +} + +.pagination-nav__link { + padding: 0.5rem 1.5rem; +} + +.markdown h1:first-child { + --ifm-h1-font-size: 2rem; +} + +.markdown > h2{ + --ifm-h2-font-size: 1.5rem; +} + +.markdown > h3{ + --ifm-h3-font-size: 1.25rem; +} + +.markdown img { + box-shadow: 9px 8px 10px 0px rgb(0 0 0 / 15%); +} diff --git a/docs/src/pages/index.module.css b/docs/src/pages/index.module.css new file mode 100644 index 000000000..ac3d44996 --- /dev/null +++ b/docs/src/pages/index.module.css @@ -0,0 +1,29 @@ +/** + * CSS files with the .module.css suffix will be treated as CSS modules + * and scoped locally. + */ + +.heroBanner { + padding: 4rem 0; + text-align: center; + position: relative; + overflow: hidden; + height: 60rem; +} + +.heroTitle { + color: #30e724; + font-size: 3rem; +} + +@media screen and (max-width: 996px) { + .heroBanner { + padding: 2rem; + } +} + +.buttons { + display: flex; + align-items: center; + justify-content: center; +} \ No newline at end of file diff --git a/docs/src/pages/index.tsx b/docs/src/pages/index.tsx new file mode 100644 index 000000000..13be38e6e --- /dev/null +++ b/docs/src/pages/index.tsx @@ -0,0 +1,40 @@ +import React from 'react'; +import clsx from 'clsx'; +import Link from '@docusaurus/Link'; +import useDocusaurusContext from '@docusaurus/useDocusaurusContext'; +import Layout from '@theme/Layout'; + +import styles from './index.module.css'; + +function HomepageHeader() { + const { siteConfig } = useDocusaurusContext(); + return ( +
+
+

{siteConfig.title}

+

欢迎光临 低代码引擎文档站

+

{siteConfig.tagline}

+
+ + 快速开始 + +
+
+
+ ); +} + +export default function Home(): JSX.Element { + const { siteConfig } = useDocusaurusContext(); + return ( + + + + ); +} diff --git a/docs/src/pages/markdown-page.md b/docs/src/pages/markdown-page.md new file mode 100644 index 000000000..7d2421c8a --- /dev/null +++ b/docs/src/pages/markdown-page.md @@ -0,0 +1,15 @@ + + +# 文档能力介绍 + +这是一个使用 Markdown 编写的任意页面，访问地址为 /markdown-page + +Product Docs Capability Introduction. + +## 功能 + +- ✅ 支持本地离线搜搜 +- ✅ 版本化文档管理 +- ✅ 离线静态部署 diff --git a/docs/static/img/docusaurus.png b/docs/static/img/docusaurus.png new file mode 100644 index 000000000..f458149e3 Binary files /dev/null and b/docs/static/img/docusaurus.png differ diff --git a/docs/static/img/logo.svg b/docs/static/img/logo.svg new file mode 100644 index 000000000..9db6d0d06 --- /dev/null +++ b/docs/static/img/logo.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/docs/static/img/undraw_docusaurus_mountain.svg b/docs/static/img/undraw_docusaurus_mountain.svg new file mode 100644 index 000000000..af961c49a --- /dev/null +++ b/docs/static/img/undraw_docusaurus_mountain.svg @@ -0,0 +1,171 @@ + + Easy to Use + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/static/img/undraw_docusaurus_react.svg b/docs/static/img/undraw_docusaurus_react.svg new file mode 100644 index 000000000..94b5cf08f --- /dev/null +++ b/docs/static/img/undraw_docusaurus_react.svg @@ -0,0 +1,170 @@ + + Powered by React + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/static/img/undraw_docusaurus_tree.svg b/docs/static/img/undraw_docusaurus_tree.svg new file mode 100644 index 000000000..d9161d339 --- /dev/null +++ b/docs/static/img/undraw_docusaurus_tree.svg @@ -0,0 +1,40 @@ + + Focus on What Matters + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/tsconfig.json b/docs/tsconfig.json new file mode 100644 index 000000000..6f4756980 --- /dev/null +++ b/docs/tsconfig.json @@ -0,0 +1,7 @@ +{ + // This file is not used in compilation. It is here just for a nice editor experience. + "extends": "@tsconfig/docusaurus/tsconfig.json", + "compilerOptions": { + "baseUrl": "." + } +}