diff --git a/.eslintrc.js b/.eslintrc.js index 5a8fe9e979..972882ce73 100644 --- a/.eslintrc.js +++ b/.eslintrc.js @@ -15,12 +15,11 @@ module.exports = { 'no-prototype-builtins': 1, 'no-useless-constructor': 1, 'no-empty-function': 1, - '@typescript-eslint/member-ordering': 0, 'lines-between-class-members': 0, 'no-await-in-loop': 0, 'no-plusplus': 0, '@typescript-eslint/no-parameter-properties': 0, - '@typescript-eslint/no-unused-vars': 1, + 'no-restricted-exports': ['error'], 'no-multi-assign': 1, 'no-dupe-class-members': 1, 'react/no-deprecated': 1, @@ -35,10 +34,26 @@ module.exports = { '@typescript-eslint/indent': 0, 'import/no-cycle': 0, '@typescript-eslint/no-shadow': 0, - "@typescript-eslint/method-signature-style": 0, - "@typescript-eslint/consistent-type-assertions": 0, - "@typescript-eslint/no-useless-constructor": 0, + '@typescript-eslint/method-signature-style': 0, + '@typescript-eslint/consistent-type-assertions': 0, + '@typescript-eslint/no-useless-constructor': 0, '@typescript-eslint/dot-notation': 0, // for lint performance '@typescript-eslint/restrict-plus-operands': 0, // for lint performance - } + 'no-unexpected-multiline': 1, + 'no-multiple-empty-lines': ['error', { max: 1 }], + 'lines-around-comment': ['error', { + beforeBlockComment: true, + afterBlockComment: false, + afterLineComment: false, + allowBlockStart: true, + }], + 'comma-dangle': ['error', 'always-multiline'], + '@typescript-eslint/member-ordering': [ + 'error', + { default: ['signature', 'field', 'constructor', 'method'] } + ], + '@typescript-eslint/no-unused-vars': ['error'], + 'no-redeclare': 0, + '@typescript-eslint/no-redeclare': 1, + }, }; diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS index c2e49b783f..670db7dfbd 100644 --- a/.github/CODEOWNERS +++ b/.github/CODEOWNERS @@ -2,7 +2,7 @@ # These owners will be the default owners for everything in # the repo. Unless a later match takes precedence -* @liujuping @JackLian +* @liujuping @1ncounter /modules/material-parser @akirakai -/modules/code-generator @leoyuan +/modules/code-generator @qingniaotonghua diff --git a/.github/workflows/check base branch.yml b/.github/workflows/check base branch.yml new file mode 100644 index 0000000000..cef996c75a --- /dev/null +++ b/.github/workflows/check base branch.yml @@ -0,0 +1,33 @@ +name: Check Base Branch + +on: + pull_request: + types: [opened] + +jobs: + code-review: + name: Check + runs-on: ubuntu-latest + + steps: + # 判断用户是否有写仓库权限 + - name: 'Check User Permission' + uses: 'lannonbr/repo-permission-check-action@2.0.0' + with: + permission: 'write' + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + + - name: 'Check base branch name is develop or not' + if: github.event.pull_request.base.ref != 'develop' # check the target branch if it's master + uses: actions-cool/issues-helper@v2 + with: + actions: 'create-comment' + token: ${{ secrets.GITHUB_TOKEN }} + issue-number: ${{ github.event.pull_request.number }} + body: | + 感谢你的 PR,根据引擎的 [研发协作流程](https://lowcode-engine.cn/site/docs/participate/flow),请将目标合入分支设置为 **develop**。 + + Thanks in advance, according to the [Contribution Guideline](https://lowcode-engine.cn/site/docs/participate/flow), please set the base branch to **develop**. + + @${{ github.event.pull_request.user.login }} \ No newline at end of file diff --git a/.github/workflows/cov packages.yml b/.github/workflows/cov packages.yml index 228e1cf989..7f92e1009c 100644 --- a/.github/workflows/cov packages.yml +++ b/.github/workflows/cov packages.yml @@ -71,4 +71,26 @@ jobs: working-directory: packages/react-simulator-renderer test-script: npm test -- --jest-ci --jest-json --jest-coverage --jest-testLocationInResults --jest-outputFile=report.json package-manager: yarn + annotations: none + + cov-utils: + runs-on: ubuntu-latest + # skip fork's PR, otherwise it fails while making a comment + if: ${{ github.event.pull_request.head.repo.full_name == 'alibaba/lowcode-engine' }} + steps: + - name: checkout + uses: actions/checkout@v2 + + - uses: actions/setup-node@v2 + with: + node-version: '14' + + - name: install + run: npm i && npm run setup:skip-build + + - uses: ArtiomTr/jest-coverage-report-action@v2 + with: + working-directory: packages/utils + test-script: npm test -- --jest-ci --jest-json --jest-coverage --jest-testLocationInResults --jest-outputFile=report.json + package-manager: yarn annotations: none \ No newline at end of file diff --git a/.github/workflows/help wanted.yml b/.github/workflows/help wanted.yml index 94927ad28f..619d08b936 100644 --- a/.github/workflows/help wanted.yml +++ b/.github/workflows/help wanted.yml @@ -1,4 +1,4 @@ -name: Issue Reply +name: Help Wanted on: issues: diff --git a/.github/workflows/insufficient information.yml b/.github/workflows/insufficient information.yml index 15885043a0..c49e133f16 100644 --- a/.github/workflows/insufficient information.yml +++ b/.github/workflows/insufficient information.yml @@ -1,4 +1,4 @@ -name: Issue Reply +name: Insufficient Info on: issues: diff --git a/.github/workflows/pr comment by chatgpt.yml b/.github/workflows/pr comment by chatgpt.yml new file mode 100644 index 0000000000..52585c4778 --- /dev/null +++ b/.github/workflows/pr comment by chatgpt.yml @@ -0,0 +1,23 @@ +name: Pull Request Review By ChatGPT + +on: + pull_request: + types: [opened, synchronize, reopened] + +jobs: + code-review: + name: Code Review + runs-on: ubuntu-latest + + steps: + # 判断用户是否有写仓库权限 + - name: 'Check User Permission' + uses: 'lannonbr/repo-permission-check-action@2.0.0' + with: + permission: 'write' + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + + - uses: opensumi/actions/.github/actions/code-review@main + env: + OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }} \ No newline at end of file diff --git a/.github/workflows/pre build.yml b/.github/workflows/pre build.yml new file mode 100644 index 0000000000..e6f7d6479d --- /dev/null +++ b/.github/workflows/pre build.yml @@ -0,0 +1,34 @@ +name: Pre Build + +on: + push: + paths: + - 'packages/**' + - '!packages/**.md' + pull_request: + paths: + - 'packages/**' + - '!packages/**.md' + +jobs: + build: + runs-on: ubuntu-latest + + steps: + - name: Checkout repository + uses: actions/checkout@v2 + + - name: Install dependencies and setup + run: npm install && npm run setup + + - name: Build + run: npm run build + + - name: Check build status + run: | + if [ $? -eq 0 ]; then + echo "Build succeeded!" + else + echo "Build failed!" + exit 1 + fi diff --git a/.github/workflows/publish docs.yml b/.github/workflows/publish docs.yml new file mode 100644 index 0000000000..139b70239f --- /dev/null +++ b/.github/workflows/publish docs.yml @@ -0,0 +1,53 @@ +name: Update and Publish Docs + +on: + push: + branches: + - develop + paths: + - 'docs/docs/**' + workflow_dispatch: + +jobs: + publish-docs: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v2 + - name: Setup Node.js + uses: actions/setup-node@v2 + with: + ref: 'develop' + node-version: '16' + registry-url: 'https://registry.npmjs.org' + - run: cd docs && npm install + - run: | + cd docs + npm version patch + git config --local user.email "action@github.com" + git config --local user.name "GitHub Action" + git add package.json + git commit -m "chore(docs): publish documentation" + git push + - run: cd docs && npm run build && npm publish + env: + NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }} + - name: Get version + id: get_version + run: echo "version=$(node -p "require('./docs/package.json').version")" >> $GITHUB_OUTPUT + + comment-pr: + needs: publish-docs + runs-on: ubuntu-latest + steps: + - name: Comment on PR + if: github.event_name == 'pull_request' && github.event.action == 'closed' && github.event.pull_request.merged == true + uses: actions/github-script@v4 + with: + github-token: ${{ secrets.GITHUB_TOKEN }} + script: | + github.issues.createComment({ + issue_number: context.issue.number, + owner: context.repo.owner, + repo: context.repo.repo, + body: '🚀 New version has been released: ' + '${{ needs.publish-docs.outputs.version }}' + }) diff --git a/.github/workflows/publish engine beta.yml b/.github/workflows/publish engine beta.yml new file mode 100644 index 0000000000..ed4c374756 --- /dev/null +++ b/.github/workflows/publish engine beta.yml @@ -0,0 +1,30 @@ +name: Publish Engine Beta + +on: + push: + branches: + - 'release/[0-9]+.[0-9]+.[0-9]+-beta' + paths: + - 'packages/**' + +jobs: + publish-engine: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v2 + - name: Setup Node.js + uses: actions/setup-node@v2 + with: + node-version: '14' + registry-url: 'https://registry.npmjs.org' + - run: npm install && npm run setup + - run: | + npm run build + git config --local user.email "action@github.com" + git config --local user.name "GitHub Action" + - run: npm run pub:prerelease + env: + NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }} + - name: Get version + id: get_version + run: echo "version=$(node -p "require('./package.json').version")" >> $GITHUB_OUTPUT diff --git a/.github/workflows/publish engine.yml b/.github/workflows/publish engine.yml new file mode 100644 index 0000000000..ddbefcde55 --- /dev/null +++ b/.github/workflows/publish engine.yml @@ -0,0 +1,33 @@ +name: Publish Engine + +on: + workflow_dispatch: + inputs: + publishCommand: + description: 'publish command' + required: true + +jobs: + publish-engine: + runs-on: ubuntu-latest + if: >- + contains(github.ref, 'refs/heads/release/') && + (github.actor == '1ncounter' || github.actor == 'liujuping') + steps: + - uses: actions/checkout@v2 + - name: Setup Node.js + uses: actions/setup-node@v2 + with: + node-version: '16' + registry-url: 'https://registry.npmjs.org' + - run: npm install && npm run setup + - run: | + npm run build + git config --local user.email "action@github.com" + git config --local user.name "GitHub Action" + - run: npm run ${{ github.event.inputs.publishCommand }} + env: + NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }} + - name: Get version + id: get_version + run: echo "version=$(node -p "require('./package.json').version")" >> $GITHUB_OUTPUT diff --git a/.github/workflows/test modules.yml b/.github/workflows/test modules.yml index 9410626e88..b2464cc40c 100644 --- a/.github/workflows/test modules.yml +++ b/.github/workflows/test modules.yml @@ -1,4 +1,4 @@ -name: lint & test +name: Lint & Test (Mods) on: push: diff --git a/.github/workflows/test packages.yml b/.github/workflows/test packages.yml index cc05742d54..45fa665465 100644 --- a/.github/workflows/test packages.yml +++ b/.github/workflows/test packages.yml @@ -1,4 +1,4 @@ -name: lint & test +name: Lint & Test (Pkgs) on: push: @@ -41,4 +41,100 @@ jobs: run: npm i && npm run setup:skip-build - name: test - run: cd packages/designer && npm test \ No newline at end of file + run: cd packages/designer && npm test + + test-editor-skeleton: + runs-on: ubuntu-latest + steps: + - name: checkout + uses: actions/checkout@v2 + + - uses: actions/setup-node@v2 + with: + node-version: '14' + + - name: install + run: npm i && npm run setup:skip-build + + - name: test + run: cd packages/editor-skeleton && npm test + + test-renderer-core: + runs-on: ubuntu-latest + steps: + - name: checkout + uses: actions/checkout@v2 + + - uses: actions/setup-node@v2 + with: + node-version: '14' + + - name: install + run: npm i && npm run setup:skip-build + + - name: test + run: cd packages/renderer-core && npm test + + test-react-simulator-renderer: + runs-on: ubuntu-latest + steps: + - name: checkout + uses: actions/checkout@v2 + + - uses: actions/setup-node@v2 + with: + node-version: '14' + + - name: install + run: npm i && npm run setup:skip-build + + - name: test + run: cd packages/react-simulator-renderer && npm test + + test-utils: + runs-on: ubuntu-latest + steps: + - name: checkout + uses: actions/checkout@v2 + + - uses: actions/setup-node@v2 + with: + node-version: '14' + + - name: install + run: npm i && npm run setup:skip-build + + - name: test + run: cd packages/utils && npm test + + test-editor-core: + runs-on: ubuntu-latest + steps: + - name: checkout + uses: actions/checkout@v2 + + - uses: actions/setup-node@v2 + with: + node-version: '14' + + - name: install + run: npm i && npm run setup:skip-build + + - name: test + run: cd packages/editor-core && npm test + + test-plugin-command: + runs-on: ubuntu-latest + steps: + - name: checkout + uses: actions/checkout@v2 + + - uses: actions/setup-node@v2 + with: + node-version: '14' + + - name: install + run: npm i && npm run setup:skip-build + + - name: test + run: cd packages/plugin-command && npm test \ No newline at end of file diff --git a/.gitignore b/.gitignore index 05159f0473..6a19ae3e0c 100644 --- a/.gitignore +++ b/.gitignore @@ -108,3 +108,5 @@ typings/ # codealike codealike.json .node + +.must.config.js \ No newline at end of file diff --git a/CONTRIBUTOR.md b/CONTRIBUTOR.md index 89757bac92..11d50baade 100644 --- a/CONTRIBUTOR.md +++ b/CONTRIBUTOR.md @@ -24,5 +24,6 @@ - [Ychangqing](https://github.com/Ychangqing) - [yize](https://github.com/yize) - [youluna](https://github.com/youluna) +- [ibreathebsb](https://github.com/ibreathebsb) 如果您贡献过低代码引擎,但是没有看到您的名字,为我们的疏忽感到抱歉。欢迎您通过 PR 补充上自己的名字。 diff --git a/babel.config.js b/babel.config.js new file mode 100644 index 0000000000..a089167a78 --- /dev/null +++ b/babel.config.js @@ -0,0 +1,6 @@ +module.exports = { + plugins: [ + ['@babel/plugin-proposal-decorators', { legacy: true }], + [require.resolve('@babel/plugin-proposal-class-properties'), { loose: true }], + ], +}; \ No newline at end of file diff --git a/docs/README.md b/docs/README.md index 12c8f1fbe9..85da75163c 100644 --- a/docs/README.md +++ b/docs/README.md @@ -27,8 +27,8 @@ $ yarn build 1. npm run build 2. npm publish # 记得改下版本号,比如 1.0.1 -# 发布完后执行 tnpm sync -3. tnpm sync +# 发布完后执行 tnpm syncOss 同步到 uipaas CDN +3. tnpm syncOss 4. 更新 diamond 版本 1.0.1 5. lowcode-engine.cn 站点生效 @@ -37,10 +37,9 @@ $ yarn build ## 功能 - [x] 支持本地离线搜搜 -- [x] 版本化文档管理 +- [x] 版本化文档管理 - [x] 离线静态部署 - [x] 主题(fork 宜搭开发者中心) ## 使用文档 https://docusaurus.io/zh-CN/docs/docs-introduction - diff --git a/docs/config/navbar.js b/docs/config/navbar.js index 0f0486398b..24f8a39376 100644 --- a/docs/config/navbar.js +++ b/docs/config/navbar.js @@ -35,15 +35,15 @@ module.exports = { }, { type: 'doc', - docId: 'participate/index', + docId: 'article/index', position: 'left', - label: '参与贡献', + label: '文章', }, { type: 'doc', - docId: 'article/index', + docId: 'video/index', position: 'left', - label: '文章', + label: '视频', }, { type: 'doc', @@ -51,16 +51,6 @@ module.exports = { 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', @@ -80,6 +70,12 @@ module.exports = { className: 'header-github-link', 'aria-label': 'GitHub repository', }, + { + type: 'doc', + docId: 'participate/index', + position: 'right', + label: '参与贡献', + }, { type: 'search', position: 'right', diff --git a/docs/config/sidebars.js b/docs/config/sidebars.js index e2de2d49cd..b8a7587d91 100644 --- a/docs/config/sidebars.js +++ b/docs/config/sidebars.js @@ -22,10 +22,61 @@ module.exports = { * 根据当前目录自动生成导航配置 */ guide: [ - { - type: 'autogenerated', - dirName: 'guide', // '.' 即当前的文档文件夹 - }, + [ + { + type: 'category', + label: '入门', + collapsed: false, + items: getDocsFromDir('guide/quickStart'), + }, + { + type: 'category', + label: '创建编辑器', + collapsed: false, + items: getDocsFromDir('guide/create'), + }, + { + type: 'category', + label: '扩展编辑器', + collapsed: false, + items: getDocsFromDir('guide/expand/editor', [{ dir: 'guide/expand/editor/parts', label: 'Parts·造物' }]), + }, + { + type: 'category', + label: '扩展运行时', + collapsed: false, + items: getDocsFromDir('guide/expand/runtime'), + }, + { + type: 'category', + label: '设计原理', + collapsed: false, + items: getDocsFromDir('guide/design'), + }, + { + type: 'category', + label: '附录', + collapsed: false, + items: [ + { + type: 'link', + label: '更新日志', + href: 'https://github.com/alibaba/lowcode-engine/releases', + }, + ...getDocsFromDir('guide/appendix'), + { + type: 'category', + label: '预置设置器详情', + items: getDocsFromDir('guide/appendix/setterDetails'), + }, + ], + }, + { + type: 'link', + label: '技术白皮书', + href: 'https://developer.aliyun.com/ebook/7507', + }, + ], ], api: [ { @@ -57,5 +108,4 @@ module.exports = { dirName: 'demoUsage', }, ], - // api: getDocsFromDir('api'), }; diff --git a/docs/docs/api/canvas.md b/docs/docs/api/canvas.md new file mode 100644 index 0000000000..865b9ac311 --- /dev/null +++ b/docs/docs/api/canvas.md @@ -0,0 +1,87 @@ +--- +title: canvas - 画布 API +sidebar_position: 10 +--- + +> **@types** [IPublicApiCanvas](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/api/canvas.ts)
+> **@since** v1.1.0 + + +## 模块简介 + +通过该模块可以触达对画布拖拽相关的一些能力。 + +## 变量 + +### dragon + +获取拖拽操作对象的实例 + +`@type {IPublicModelDragon | null}` + + +相关类型:[IPublicModelDragon](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/model/dragon.ts) + +### activeTracker + +获取活动追踪器实例 + +`@type {IPublicModelActiveTracker | null}` + +相关类型:[IPublicModelActiveTracker](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/model/active-tracker.ts) + +### isInLiveEditing + +是否处于 LiveEditing 状态 + +`@type {boolean}` + +### clipboard +全局剪贴板实例 + +`@type {IPublicModelClipboard}` + +相关类型:[IPublicModelClipboard](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/model/clipboard.ts) + +## 方法 + +### createLocation +创建一个文档插入位置对象,该对象用来描述一个即将插入的节点在文档中的位置 + +```typescript +/** + * 创建一个文档插入位置对象,该对象用来描述一个即将插入的节点在文档中的位置 + * create a drop location for document, drop location describes a location in document + * @since v1.1.0 + */ +createLocation(locationData: IPublicTypeLocationData): IPublicModelDropLocation; +``` + +### createScroller +创建一个滚动控制器 Scroller,赋予一个视图滚动的基本能力, +```typescript +/** + * 创建一个滚动控制器 Scroller,赋予一个视图滚动的基本能力, + * a Scroller is a controller that gives a view (IPublicTypeScrollable) the ability scrolling + * to some cordination by api scrollTo. + * + * when a scroller is inited, will need to pass is a scrollable, which has a scrollTarget. + * and when scrollTo(options: { left?: number; top?: number }) is called, scroller will + * move scrollTarget`s top-left corner to (options.left, options.top) that passed in. + * @since v1.1.0 + */ +createScroller(scrollable: IPublicTypeScrollable): IPublicModelScroller; + +``` + +### createScrollTarget +创建一个 ScrollTarget,与 Scroller 一起发挥作用,详见 [createScroller](#createscroller) 中的描述 + +```typescript +/** + * 创建一个 ScrollTarget,与 Scroller 一起发挥作用,详见 createScroller 中的描述 + * this works with Scroller, refer to createScroller`s description + * @since v1.1.0 + */ +createScrollTarget(shell: HTMLDivElement): IPublicModelScrollTarget; +``` diff --git a/docs/docs/api/command.md b/docs/docs/api/command.md new file mode 100644 index 0000000000..fc36c8ad89 --- /dev/null +++ b/docs/docs/api/command.md @@ -0,0 +1,101 @@ +--- +title: command - 指令 API +sidebar_position: 10 +--- + + + +## 模块概览 + +该模块使得与命令系统的交互成为可能,提供了一种全面的方式来处理、执行和管理应用程序中的命令。 + + + +## 接口 + +### IPublicApiCommand + +与命令交互的接口。它提供了注册、注销、执行和管理命令的方法。 + + + +## 方法 + +### registerCommand + +注册一个新命令及其处理函数。 + +``` +typescriptCopy code +/** + * 注册一个新的命令及其处理程序。 + * @param command {IPublicTypeCommand} - 要注册的命令。 + */ +registerCommand(command: IPublicTypeCommand): void; +``` + +### unregisterCommand + +注销一个已存在的命令。 + +``` +typescriptCopy code +/** + * 注销一个已存在的命令。 + * @param name {string} - 要注销的命令的名称。 + */ +unregisterCommand(name: string): void; +``` + +### executeCommand + +根据名称和提供的参数执行命令,确保参数符合命令的定义。 + +``` +typescriptCopy code +/** + * 根据名称和提供的参数执行命令。 + * @param name {string} - 要执行的命令的名称。 + * @param args {IPublicTypeCommandHandlerArgs} - 命令的参数。 + */ +executeCommand(name: string, args?: IPublicTypeCommandHandlerArgs): void; +``` + +### batchExecuteCommand + +批量执行命令,在所有命令执行后进行重绘,历史记录中只记录一次。 + +``` +typescriptCopy code +/** + * 批量执行命令,随后进行重绘,历史记录中只记录一次。 + * @param commands {Array} - 命令对象的数组,包含名称和可选参数。 + */ +batchExecuteCommand(commands: { name: string; args?: IPublicTypeCommandHandlerArgs }[]): void; +``` + +### listCommands + +列出所有已注册的命令。 + +``` +typescriptCopy code +/** + * 列出所有已注册的命令。 + * @returns {IPublicTypeListCommand[]} - 已注册命令的数组。 + */ +listCommands(): IPublicTypeListCommand[]; +``` + +### onCommandError + +为命令执行过程中的错误注册错误处理回调函数。 + +``` +typescriptCopy code +/** + * 为命令执行过程中的错误注册一个回调函数。 + * @param callback {(name: string, error: Error) => void} - 错误处理的回调函数。 + */ +onCommandError(callback: (name: string, error: Error) => void): void; +``` diff --git a/docs/docs/api/common.md b/docs/docs/api/common.md index c16d220432..c278bf2ad8 100644 --- a/docs/docs/api/common.md +++ b/docs/docs/api/common.md @@ -1,50 +1,139 @@ --- title: common - 通用 API -sidebar_position: 11 +sidebar_position: 10 --- -# 模块简介 -通用模块里包含除了 9 大核心模块 API 之外的所有 API,比如通用 utils、面板扩展相关 等。 + +> **@types** [IPublicApiCommon](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/api/common.ts)
+> **@since** v1.0.0 + + +## 模块简介 +通用模块里包含除了几大核心模块 API 之外的所有 API,比如通用 utils、面板扩展相关 等。 > 高能预警:之所以叫 skeletonCabin / designerCabin 跟兼容上一个版本的引擎有关系。若有必要,后面将用更有意义的命名空间来组织这些 API。 -# 变量(variables) -### utils +## 变量 +#### utils 通用 utils,详见下方方法签名 -### designerCabin -设计器扩展相关,详见下方方法签名 +相关类型:[IPublicApiCommonUtils](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/api/common.ts) -### skeletonCabin +#### skeletonCabin 面板扩展相关,详见下方方法签名 -# 方法签名(functions) -## utils -### isNodeSchema +## 方法 +### utils +#### isNodeSchema 是否为合法的 schema 结构 -### isFormEvent +```typscript +/** + * 是否为合法的 schema 结构 + * check if data is valid NodeSchema + * + * @param {*} data + * @returns {boolean} + */ +isNodeSchema(data: any): boolean; +``` + +#### isFormEvent 是否为表单事件类型 -### getNodeSchemaById +```typescript +/** + * 是否为表单事件类型 + * check if e is a form event + * @param {(KeyboardEvent | MouseEvent)} e + * @returns {boolean} + */ +isFormEvent(e: KeyboardEvent | MouseEvent): boolean; +``` + +#### getNodeSchemaById 从 schema 结构中查找指定 id 节点 +```typescript +/** + * 从 schema 结构中查找指定 id 节点 + * get node schema from a larger schema with node id + * @param {IPublicTypeNodeSchema} schema + * @param {string} nodeId + * @returns {(IPublicTypeNodeSchema | undefined)} + */ +getNodeSchemaById( + schema: IPublicTypeNodeSchema, + nodeId: string, + ): IPublicTypeNodeSchema | undefined; +``` +相关类型:[IPublicTypeNodeSchema](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/type/node-schema.ts) -### executeTransaction +#### executeTransaction 批处理事务,用于优化特定场景的性能 -*引擎版本 >= 1.0.16 + +```typescript +/** + * 批处理事务,用于优化特定场景的性能 + * excute something in a transaction for performence + * + * @param {() => void} fn + * @param {IPublicEnumTransitionType} type + * @since v1.0.16 + */ +executeTransaction(fn: () => void, type: IPublicEnumTransitionType): void; +``` +**@since v1.0.16** + +**示例** ```typescript import { common } from '@alilc/lowcode-engine'; -import { TransitionType } from '@alilc/lowcode-types'; +import { IPublicEnumTransitionType } from '@alilc/lowcode-types'; common.utils.startTransaction(() => { node1.setProps(); node2.setProps(); node3.setProps(); // ... -}, TransitionType.repaint); +}, IPublicEnumTransitionType.repaint); ``` -### createIntl +#### getConvertedExtraKey + +props key 转化工具 + +```typescript +getConvertedExtraKey(key: string): string + +``` + +**@since v1.0.17** + +#### createIntl i18n 相关工具 -*引擎版本 >= 1.0.17 +```typescript +/** + * i18n 相关工具 + * i18n tools + * + * @param {(string | object)} instance + * @returns {{ + * intlNode(id: string, params?: object): ReactNode; + * intl(id: string, params?: object): string; + * getLocale(): string; + * setLocale(locale: string): void; + * }} + * @since v1.0.17 + */ +createIntl(instance: string | object): { + intlNode(id: string, params?: object): ReactNode; + intl(id: string, params?: object): string; + getLocale(): string; + setLocale(locale: string): void; +}; +``` + +**@since v1.0.17** + +**示例** + ```typescript import { common } from '@alilc/lowcode-engine'; import enUS from './en-US.json'; @@ -56,16 +145,31 @@ const { intl, getLocale, setLocale } = common.utils.createIntl({ }); ``` -## 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 + +#### intl + +i18n 转换方法 + +```typescript +/** + * i18n 转换方法 + */ +intl(data: IPublicTypeI18nData | string, params?: object): string; +``` + +**示例** +``` +const title = common.utils.intl(node.title) +``` + +### skeletonCabin +#### Workbench 编辑器框架 View -# 事件(events) -无 +```typescript +/** + * 编辑器框架 View + * get Workbench Component + */ +get Workbench(): Component; +``` diff --git a/docs/docs/api/commonUI.md b/docs/docs/api/commonUI.md new file mode 100644 index 0000000000..45640051f2 --- /dev/null +++ b/docs/docs/api/commonUI.md @@ -0,0 +1,210 @@ +--- +title: commonUI - UI 组件库 +sidebar_position: 10 +--- + +## 简介 +CommonUI API 是一个专为低代码引擎设计的组件 UI 库,使用它开发的插件,可以保证在不同项目和主题切换中能够保持一致性和兼容性。 + +## 组件列表 + +### Tip + +提示组件 + +| 参数 | 说明 | 类型 | 默认值 | +|-----------|--------------|---------------------------------------|--------| +| className | className | string (optional) | | +| children | tip 的内容 | IPublicTypeI18nData \| ReactNode | | +| direction | tip 的方向 | 'top' \| 'bottom' \| 'left' \| 'right' | | + + +### HelpTip + +带 help icon 的提示组件 + +| 参数 | 说明 | 类型 | 默认值 | +|-----------|--------|-----------------------------------|--------| +| help | 描述 | IPublicTypeHelpTipConfig | | +| direction | 方向 | IPublicTypeTipConfig['direction'] | 'top' | +| size | 方向 | IconProps['size'] | 'small'| + +### Title + +标题组件 + +| 参数 | 说明 | 类型 | 默认值 | +|-----------|------------|-----------------------------|--------| +| title | 标题内容 | IPublicTypeTitleContent | | +| className | className | string (optional) | | +| onClick | 点击事件 | () => void (optional) | | + +### ContextMenu + +| 参数 | 说明 | 类型 | 默认值 | +|--------|----------------------------------------------------|------------------------------------|--------| +| menus | 定义上下文菜单的动作数组 | IPublicTypeContextMenuAction[] | | +| children | 组件的子元素 | React.ReactElement[] | | + +**IPublicTypeContextMenuAction Interface** + +| 参数 | 说明 | 类型 | 默认值 | +|------------|--------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------|----------------------------------------| +| name | 动作的唯一标识符
Unique identifier for the action | string | | +| title | 显示的标题,可以是字符串或国际化数据
Display title, can be a string or internationalized data | string \| IPublicTypeI18nData (optional) | | +| type | 菜单项类型
Menu item type | IPublicEnumContextMenuType (optional) | IPublicEnumContextMenuType.MENU_ITEM | +| action | 点击时执行的动作,可选
Action to execute on click, optional | (nodes: IPublicModelNode[]) => void (optional) | | +| items | 子菜单项或生成子节点的函数,可选,仅支持两级
Sub-menu items or function to generate child node, optional | Omit[] \| ((nodes: IPublicModelNode[]) => Omit[]) (optional) | | +| condition | 显示条件函数
Function to determine display condition | (nodes: IPublicModelNode[]) => boolean (optional) | | +| disabled | 禁用条件函数,可选
Function to determine disabled condition, optional | (nodes: IPublicModelNode[]) => boolean (optional) | | + +**ContextMenu 示例** + +```typescript +const App = () => { + const menuItems: IPublicTypeContextMenuAction[] = [ + { + name: 'a', + title: '选项 1', + action: () => console.log('选项 1 被点击'), + }, + { + name: 'b', + title: '选项 2', + action: () => console.log('选项 2 被点击'), + }, + ]; + + const ContextMenu = ctx.commonUI.ContextMenu; + + return ( +
+ +
右键点击这里
+
+
+ ); +}; + +export default App; +``` + +**ContextMenu.create 示例** + +```typescript +const App = () => { + const menuItems: IPublicTypeContextMenuAction[] = [ + { + name: 'a', + title: '选项 1', + action: () => console.log('选项 1 被点击'), + }, + { + name: 'b', + title: '选项 2', + action: () => console.log('选项 2 被点击'), + }, + ]; + + const ContextMenu = ctx.commonUI.ContextMenu; + + return ( +
+
{ + ContextMenu.create(menuItems, e); + }}>点击这里
+
+ ); +}; + +export default App; +``` + +### Balloon + +详细文档: [Balloon Documentation](https://fusion.design/pc/component/balloon) + +### Breadcrumb +详细文档: [Breadcrumb Documentation](https://fusion.design/pc/component/breadcrumb) + +### Button +详细文档: [Button Documentation](https://fusion.design/pc/component/button) + +### Card +详细文档:[Card Documentation](https://fusion.design/pc/component/card) + +### Checkbox +详细文档:[Checkbox Documentation](https://fusion.design/pc/component/checkbox) + +### DatePicker +详细文档:[DatePicker Documentation](https://fusion.design/pc/component/datepicker) + +### Dialog +详细文档:[Dialog Documentation](https://fusion.design/pc/component/dialog) + +### Dropdown +详细文档:[Dropdown Documentation](https://fusion.design/pc/component/dropdown) + +### Form +详细文档:[Form Documentation](https://fusion.design/pc/component/form) + +### Icon +详细文档:[Icon Documentation](https://fusion.design/pc/component/icon) + +引擎默认主题支持的 icon 列表:https://fusion.design/64063/component/icon?themeid=20133 + + +### Input +详细文档:[Input Documentation](https://fusion.design/pc/component/input) + +### Loading +详细文档:[Loading Documentation](https://fusion.design/pc/component/loading) + +### Message +详细文档:[Message Documentation](https://fusion.design/pc/component/message) + +### Overlay +详细文档:[Overlay Documentation](https://fusion.design/pc/component/overlay) + +### Pagination +详细文档:[Pagination Documentation](https://fusion.design/pc/component/pagination) + +### Radio +详细文档:[Radio Documentation](https://fusion.design/pc/component/radio) + +### Search +详细文档:[Search Documentation](https://fusion.design/pc/component/search) + +### Select +详细文档:[Select Documentation](https://fusion.design/pc/component/select) + +### SplitButton +详细文档:[SplitButton Documentation](https://fusion.design/pc/component/splitbutton) + +### Step +详细文档:[Step Documentation](https://fusion.design/pc/component/step) + +### Switch +详细文档:[Switch Documentation](https://fusion.design/pc/component/switch) + +### Tab +详细文档:[Tab Documentation](https://fusion.design/pc/component/tab) + +### Table +详细文档:[Table Documentation](https://fusion.design/pc/component/table) + +### Tree +详细文档:[Tree Documentation](https://fusion.design/pc/component/tree) + +### TreeSelect +详细文档:[TreeSelect Documentation](https://fusion.design/pc/component/treeselect) + +### Upload +详细文档:[Upload Documentation](https://fusion.design/pc/component/upload) + +### Divider +详细文档:[Divider Documentation](https://fusion.design/pc/component/divider) + +## 说明 + +如果需要其他组件,可以提 issue 给我们。 diff --git a/docs/docs/api/config.md b/docs/docs/api/config.md index 40d18eb3af..414cfc979f 100644 --- a/docs/docs/api/config.md +++ b/docs/docs/api/config.md @@ -1,22 +1,30 @@ --- title: config - 配置 API -sidebar_position: 8 +sidebar_position: 5 --- + +> **@types** [IPublicModelEngineConfig](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/model/engine-config.ts)
+> **@since** v1.0.0 + + ## 模块简介 配置模块,负责配置的读、写等操作。 -## -## 变量(variables) -无 -## -## 方法签名(functions) + +## 方法 ### get 获取指定 key 的值 -**类型定义** ```typescript -function get(key: string, defaultValue?: any): any +/** + * 获取指定 key 的值 + * get value by key + * @param key + * @param defaultValue + * @returns + */ +get(key: string, defaultValue?: any): any; ``` -**调用示例** +**示例** ```typescript import { config } from '@alilc/lowcode-engine'; @@ -26,11 +34,16 @@ config.get('keyB', { a: 1 }); ### set 设置指定 key 的值 -**类型定义** ```typescript -function set(key: string, value: any) +/** + * 设置指定 key 的值 + * set value for certain key + * @param key + * @param value + */ +set(key: string, value: any): void; ``` -**调用示例** +**示例** ```typescript import { config } from '@alilc/lowcode-engine'; @@ -40,40 +53,88 @@ config.set('keyC', 1); ### has 判断指定 key 是否有值 -**类型定义** ```typescript -function has(key: string): boolean +/** + * 判断指定 key 是否有值 + * check if config has certain key configed + * @param key + * @returns + */ +has(key: string): boolean; ``` -**调用示例** + +**示例** ```typescript import { config } from '@alilc/lowcode-engine'; config.has('keyD'); ``` -### + ### setConfig 批量设值,set 的对象版本 -**类型定义** ```typescript -function setConfig(config: { [key: string]: any }) +/** + * 批量设值,set 的对象版本 + * set multiple config key-values + * @param config + */ +setConfig(config: { [key: string]: any }): void; ``` -**调用示例** +**示例** ```typescript import { config } from '@alilc/lowcode-engine'; config.setConfig({ keyA: false, keyB: 2 }); ``` +### getPreference +获取全局 Preference 管理器,用于管理全局浏览器侧用户 Preference,如 Panel 是否钉住 + +```typescript +/** + * 获取全局 Preference, 用于管理全局浏览器侧用户 Preference,如 Panel 是否钉住 + * get global user preference manager, which can be use to store + * user`s preference in user localstorage, such as a panel is pinned or not. + * @returns {IPublicModelPreference} + * @since v1.1.0 + */ +getPreference(): IPublicModelPreference; +``` +相关类型:[IPublicModelPreference](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/model/preference.ts) + +**@since v1.1.0** + +示例 + +```javascript +import { config } from '@alilc/lowcode-engine'; + +const panelName = 'outline-master-pane'; + +// 设置大纲树面板钉住,在大纲树下次重新打开时生效 +config.getPreference().set(`${panelName}-pinned-status-isFloat`, false, 'skeleton') +``` + +## 事件 + ### onceGot 获取指定 key 的值,若此时还未赋值,则等待,若已有值,则直接返回值 注:此函数返回 Promise 实例 -**类型定义** + ```typescript -function onceGot(key: string): Promise +/** + * 获取指定 key 的值,若此时还未赋值,则等待,若已有值,则直接返回值 + * 注:此函数返回 Promise 实例,只会执行(fullfill)一次 + * wait until value of certain key is set, will only be + * triggered once. + * @param key + * @returns + */ +onceGot(key: string): Promise; ``` -**调用示例** +**示例** ```typescript import { config } from '@alilc/lowcode-engine'; @@ -88,11 +149,18 @@ const value = await config.onceGot('keyA'); ### onGot 获取指定 key 的值,函数回调模式,若多次被赋值,回调会被多次调用 -**类型定义** ```typescript -function onGot(key: string, fn: (data: any) => void): () => void + /** + * 获取指定 key 的值,函数回调模式,若多次被赋值,回调会被多次调用 + * set callback for event of value set for some key + * this will be called each time the value is set + * @param key + * @param fn + * @returns + */ + onGot(key: string, fn: (data: any) => void): () => void; ``` -**调用示例** +**示例** ```typescript import { config } from '@alilc/lowcode-engine'; @@ -102,6 +170,4 @@ config.onGot('keyA', (value) => { const.set('keyA', 1); // 'The value of keyA is 1' const.set('keyA', 2); // 'The value of keyA is 2' -``` -## 事件(events) -无 +``` \ No newline at end of file diff --git a/docs/docs/api/configOptions.md b/docs/docs/api/configOptions.md new file mode 100644 index 0000000000..5d6e8d7abb --- /dev/null +++ b/docs/docs/api/configOptions.md @@ -0,0 +1,306 @@ +--- +title: config options - 配置列表 +sidebar_position: 5 +--- + +> **@types** [IPublicTypeEngineOptions](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/type/engine-options.ts)
+ +## 配置方式 + +#### init API + +```javascript +import { init } from '@alilc/lowcode-engine'; + +init(document.getElementById('engine'), { + enableCondition: false, +}); +``` + +[**init api**](./init) + +#### config API + +```javascript +import { config } from '@alilc/lowcode-engine'; + +config.set('enableCondition', false) +``` + +[**config api**](./config) + +## 配置详情 + +> 源码详见 [IPublicTypeEngineOptions](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/type/engine-options.ts) + + +### 画布 + +#### locale - 语言 + +`@type {string}`、`@default {zh-CN}` + +语言 + +#### device - 设备类型 + +`@type {string}` + +引擎默认支持的 device 类型有 `default`、`mobile`、`iphonex`、`iphone6`。 + +插件 `@alilc/lowcode-plugin-simulator-select` 支持的 device 类型有 `default`、`phone`、`tablet`、`desktop`。 + +如果需要自定义的 device 类型,需要补充 device 类型对应的样式,例如 device 为 phone 时,需要补充样式如下: + +```css +.lc-simulator-device-phone { + top: 16px; + bottom: 16px; + left: 50%; + width: 375px; + transform: translateX(-50%); + margin: auto; +} +``` + +#### deviceClassName + +`@type {string}` + +指定初始化的 deviceClassName,挂载到画布的顶层节点上 + +#### appHelper + +与 react-renderer 的 appHelper 一致,https://lowcode-engine.cn/site/docs/guide/expand/runtime/renderer#apphelper + + +#### enableCondition + +`@type {boolean}` + +是否开启 condition 的能力,默认在设计器中不管 condition 是啥都正常展示 + +#### disableAutoRender + +`@type {boolean}` `@default {false}` + +关闭画布自动渲染,在资产包多重异步加载的场景有效 + +#### renderEnv - 渲染器类型 + +渲染器类型 + +`@type {string}`、`@default {react}` + +#### simulatorUrl + +`@type {string[]}` + +设置 simulator 相关的 url + +#### enableStrictNotFoundMode + +`@type {boolean}` `@default {false}` + +当开启组件未找到严格模式时,渲染模块不会默认给一个容器组件 + +### 编排 + +#### focusNodeSelector - 指定根组件 + +配置指定节点为根组件 + +类型定义 + +```typescript + focusNodeSelector?: (rootNode: IPublicModelNode) => Node; +``` + +#### supportVariableGlobally - 全局变量配置 + +`@type {boolean}` `@default {false}` + +设置所有属性支持变量配置 + +开启拖拽组件时,即将被放入的容器是否有视觉反馈 + +#### customizeIgnoreSelectors - 点击忽略 + +配置画布中,需要屏蔽点击事件的元素,即配置的元素默认点击行为均不生效。 + +类型定义: + +```typescript + customizeIgnoreSelectors?: (defaultIgnoreSelectors: string[], e: MouseEvent) => string[]; +``` + +默认值: + +```javascript +() => { + return [ + '.next-input-group', + '.next-checkbox-group', + '.next-checkbox-wrapper', + '.next-date-picker', + '.next-input', + '.next-month-picker', + '.next-number-picker', + '.next-radio-group', + '.next-range', + '.next-range-picker', + '.next-rating', + '.next-select', + '.next-switch', + '.next-time-picker', + '.next-upload', + '.next-year-picker', + '.next-breadcrumb-item', + '.next-calendar-header', + '.next-calendar-table', + '.editor-container', // 富文本组件 + ] +} +``` + +#### enableCanvasLock + +`@type {boolean}` `@default {false}` + +打开画布的锁定操作 + +#### enableLockedNodeSetting + +`@type {boolean}` `@default {false}` + +容器锁定后,容器本身是否可以设置属性,仅当画布锁定特性开启时生效 + +#### enableMouseEventPropagationInCanvas + +`@type {boolean}` `@default {false}` + +鼠标事件(mouseover、mouseleave、mousemove)在画布中是否允许冒泡,默认不允许。 + +#### enableReactiveContainer + +`@type {boolean}` `@default {false}` + +#### enableContextMenu - 开启右键菜单 + +`@type {boolean}` `@default {false}` + +是否开启右键菜单 + +#### disableDetecting + +`@type {boolean}` `@default {false}` + +关闭拖拽组件时的虚线响应,性能考虑 + + +#### disableDefaultSettingPanel + +`@type {boolean}` `@default {false}` + +禁止默认的设置面板 + +#### disableDefaultSetters + +`@type {boolean}` `@default {false}` + +禁止默认的设置器 + +#### stayOnTheSameSettingTab + +`@type {boolean}` `@default {false}` + +当选中节点切换时,是否停留在相同的设置 tab 上 + +#### hideSettingsTabsWhenOnlyOneItem + +`@type {boolean}` `@default {false}` + +是否在只有一个 item 的时候隐藏设置 tabs + +#### hideComponentAction + +`@type {boolean}` `@default {false}` + +隐藏设计器辅助层 + +#### thisRequiredInJSE + +`@type {boolean}` `@default {true}` + +JSExpression 是否只支持使用 this 来访问上下文变量,假如需要兼容原来的 'state.xxx',则设置为 false + +### 应用级设计器 + +#### enableWorkspaceMode - 应用级设计模式 + +`@type {boolean}` `@default {false}` + +开启应用级设计模式 + +#### enableAutoOpenFirstWindow + +`@type {boolean}` `@default {true}` + +应用级设计模式下,自动打开第一个窗口 + +#### workspaceEmptyComponent + +应用级设计模式下,当窗口为空时,展示的占位组件 + +### 定制组件 + +#### faultComponent + +组件渲染错误时的占位组件 + +#### notFoundComponent + +组件不存在时的占位组件 + +#### loadingComponent - loading 组件 + +自定义 loading 组件 + +### 插件 + +#### defaultSettingPanelProps + +内置设置面板插件的 panelProps + +#### defaultOutlinePaneProps + +内置大纲树面板插件的 panelProps + +### 其他 + +#### enableStrictPluginMode + +`@type {boolean}` + +开启严格插件模式,默认值:STRICT_PLUGIN_MODE_DEFAULT , 严格模式下,插件将无法通过 engineOptions 传递自定义配置项 + +#### requestHandlersMap + +数据源引擎的请求处理器映射 + +#### customPluginTransducer + +插件处理中间件,方便提供插件调试能力 + +类型定义 + +```typescript +customPluginTransducer: async (originPlugin: IPublicTypePlugin, ctx: IPublicModelPluginContext, options): IPublicTypePlugin; +``` + +#### defaultOutlinePaneProps + +`@type {object}` + +大纲树插件面板默认 props + diff --git a/docs/docs/api/event.md b/docs/docs/api/event.md index b24c91054a..c2e86f7106 100644 --- a/docs/docs/api/event.md +++ b/docs/docs/api/event.md @@ -1,42 +1,78 @@ --- title: event - 事件 API -sidebar_position: 7 +sidebar_position: 10 --- + +> **@types** [IPublicApiEvent](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/api/event.ts)
+> **@since** v1.0.0 + + ## 模块简介 负责事件处理 API,支持自定义监听事件、触发事件。 -## 方法签名(functions) +## 方法 ### on 监听事件 -**类型定义** ```typescript -function on(event: string, listener: (...args: unknown[]) => void): void; +/** + * 监听事件 + * add monitor to a event + * @param event 事件名称 + * @param listener 事件回调 + */ +on(event: string, listener: (...args: any[]) => void): IPublicTypeDisposable; ``` +相关类型:[IPublicTypeDisposable](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/type/disposable.ts) + +### prependListener +监听事件,会在其他回调函数之前执行 + +```typescript +/** + * 监听事件,会在其他回调函数之前执行 + * @param event 事件名称 + * @param listener 事件回调 + */ +prependListener(event: string, listener: (...args: any[]) => void): IPublicTypeDisposable; +``` +相关类型:[IPublicTypeDisposable](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/type/disposable.ts) ### off 取消监听事件 -**类型定义** ```typescript -function off(event: string, listener: (...args: unknown[]) => void): void; +/** + * 取消监听事件 + * cancel a monitor from a event + * @param event 事件名称 + * @param listener 事件回调 + */ +off(event: string, listener: (...args: any[]) => void): void; ``` ### emit 触发事件 -**类型定义** - ```typescript -function emit(event: string, ...args: unknown[]): void; +/** + * 触发事件 + * emit a message for a event + * @param event 事件名称 + * @param args 事件参数 + * @returns + */ +emit(event: string, ...args: any[]): void; ``` ## 使用示例 ### 事件触发和监听 + ```typescript const eventName = 'eventName'; // 事件监听 +// 插件中发出的事件,默认以 `common` 为前缀,监听时需要注意下 event.on(`common:${eventName}`); // 触发事件 diff --git a/docs/docs/api/hotkey.md b/docs/docs/api/hotkey.md index 60e8a3f3f7..be6a3033d0 100644 --- a/docs/docs/api/hotkey.md +++ b/docs/docs/api/hotkey.md @@ -1,30 +1,37 @@ --- title: hotkey - 快捷键 API -sidebar_position: 5 +sidebar_position: 10 --- + +> **@types** [IPublicApiHotkey](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/api/hotkey.ts)
+> **@since** v1.0.0 + ## 模块简介 绑定快捷键 API,可以自定义项目快捷键使用。 -## 方法签名(functions) +## 方法 ### bind 绑定快捷键 -**类型定义** ```typescript -function bind( - combos: string[] | string, - callback: (e: KeyboardEvent, combo?: string) => any | false, - action?: string -): () => void; +/** + * 绑定快捷键 + * bind hotkey/hotkeys, + * @param combos 快捷键,格式如:['command + s'] 、['ctrl + shift + s'] 等 + * @param callback 回调函数 + * @param action + * @returns + */ +bind( + combos: string[] | string, + callback: IPublicTypeHotkeyCallback, + action?: string, + ): IPublicTypeDisposable; ``` +相关 types +- [IPublicTypeHotkeyCallback](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/type/hotkey-callback.ts) +- [IPublicTypeDisposable](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/type/disposable.ts) -**示例** -```typescript -hotkey.bind('command+s', (e) => { - e.preventDefault(); - // command+s 快捷键按下时需要执行的逻辑 -}); -``` ## 使用示例 ### 基础示例 @@ -53,7 +60,7 @@ function saveSchema(schema) { // 保存 schema 相关操作 } -const saveSampleHotKey = (ctx: ILowCodePluginContext) => { +const saveSampleHotKey = (ctx: IPublicModelPluginContext) => { return { name: 'saveSample', async init() { diff --git a/docs/docs/api/index.md b/docs/docs/api/index.md index 212337a620..383b2952ce 100644 --- a/docs/docs/api/index.md +++ b/docs/docs/api/index.md @@ -5,7 +5,7 @@ sidebar_position: 0 引擎提供的公开 API 分为`命名空间`和`模型`两类,其中`命名空间`用于聚合一大类的 API,`模型`为各 API 涉及到的对象模型。 -### 命名空间 +## 命名空间 引擎直接提供以下几大类 API @@ -21,7 +21,7 @@ sidebar_position: 0 - logger 日志 API - init 初始化 API -### 模型 +## 模型 以下模型通过前面的 API 以返回值等形式间接透出。 - document-model 文档 @@ -29,18 +29,27 @@ sidebar_position: 0 - node-children 节点孩子 - props 属性集 - prop 属性 -- setting-prop-entry 设置属性 +- setting-field 设置属性 - setting-top-entry 设置属性集 - component-meta 物料元数据 - selection 画布选中 - detecting 画布 hover - history 操作历史 +- window 低代码设计器窗口模型 +- detecting 画布节点悬停模型 +- modal-nodes-manager 模态节点管理器模型 +- plugin-instance 插件实例 +- drop-location 拖拽放置位置模型 -### API 设计约定 +## 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() + +## experimental + +说明此模块处于公测阶段, API 可能会发生改变. \ No newline at end of file diff --git a/docs/docs/api/init.md b/docs/docs/api/init.md index 93ad133d32..dd84d9c00f 100644 --- a/docs/docs/api/init.md +++ b/docs/docs/api/init.md @@ -1,107 +1,25 @@ --- title: init - 初始化 API -sidebar_position: 10 +sidebar_position: 0 --- + +> **@since** v1.0.0 + + ## 模块简介 提供 init 等方法 -## 方法签名 -#### 1. init +## 方法 +#### init 初始化引擎 **方法定义** ```typescript -function init(container?: Element, options?: EngineOptions): void +function init(container?: Element, options?: IPublicTypeEngineOptions): 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; +[**初始化引擎配置参数列表**](./configOptions) - /** - * @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'; @@ -110,7 +28,7 @@ init(document.getElementById('engine'), { enableCondition: false, }); ``` -### + ### 默认打开移动端画布 ```typescript import { init } from '@alilc/lowcode-engine'; diff --git a/docs/docs/api/logger.md b/docs/docs/api/logger.md index d523622d80..38d986258b 100644 --- a/docs/docs/api/logger.md +++ b/docs/docs/api/logger.md @@ -1,49 +1,80 @@ --- title: logger - 日志 API -sidebar_position: 9 +sidebar_position: 10 --- + +> **@types** [IPublicApiLogger](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/api/logger.ts)
+> **@since** v1.0.0 + + ## 模块简介 -引擎日志模块,可以按照 **日志级别 **和** 业务类型 **两个维度来定制日志,基于 [zen-logger](https://web.npm.alibaba-inc.com/package/zen-logger) 封装。 -> 注:日志级别可以通过 url query 动态调整,详见下方使用示例。 +引擎日志模块,可以按照 **日志级别 **和** 业务类型 **两个维度来定制日志。 +> 注:日志级别可以通过 url query 动态调整,详见下方[查看示例](#查看示例)。
+> 参考 [zen-logger](https://web.npm.alibaba-inc.com/package/zen-logger) 实现进行封装 + +## 方法 -## 变量(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 +/** + * debug info + */ +debug(...args: any | any[]): void; + +/** + * normal info output + */ +info(...args: any | any[]): void; + +/** + * warning info output + */ +warn(...args: any | any[]): void; + +/** + * error info output + */ +error(...args: any | any[]): void; + +/** + * log info output + */ +log(...args: any | any[]): void; ``` -**调用示例** -```typescript -import { logger } from '@alilc/lowcode-engine'; +## 输出示例 + +```typescript +import { Logger } from '@alilc/lowcode-utils'; +const logger = new Logger({ level: 'warn', bizName: 'myPlugin:moduleA' }); logger.log('Awesome Low-Code Engine'); ``` -## 事件(events) -无 -## 使用示例 -```typescript -import { logger } from '@alilc/lowcode-engine'; +## 查看示例 + +开启查看方式: + +- 方式 1:所有 logger 创建时会有默认输出的 level, 默认为 warn , 即只展示 warn , error +- 方式 2:url 上追加 __logConf__进行开启,示例如下 + +``` +https://lowcode-engine.cn/demo/demo-general/index.html?__logConf__=warn +// 开启所有 bizName的 warn 和 error + +https://lowcode-engine.cn/demo/demo-general/index.html?__logConf__=debug +// 开启所有 bizName的 debug, log, info, warn 和 error + +https://lowcode-engine.cn/demo/demo-general/index.html?__logConf__=log +// 开启所有 bizName的 log, info, warn 和 error -// 内部实现:logger = getLogger({ level: 'warn', bizName: 'designer:pluginManager' }) +https://lowcode-engine.cn/demo/demo-general/index.html?__logConf__=warn|* +// 同 __logConf__=warn -// 若在 url query 中增加 `__logConf__` 可改变打印日志级别和限定业务类型日志 -// 默认:__logConf__=warn:* -logger.log('log'); // 不输出 -logger.warn('warn'); // 输出 -logger.error('error'); // 输出 +https://lowcode-engine.cn/demo/demo-general/index.html?__logConf__=warn|bizName +// 开启 bizName 的 debug, log, info, warn 和 error -// 比如:__logConf__=log:designer:pluginManager -logger.log('log'); // 输出 -logger.warn('warn'); // 输出 -logger.error('error'); // 输出 +https://lowcode-engine.cn/demo/demo-general/index.html?__logConf__=warn|partOfBizName +// 开启 bizName like '%partOfBizName%' 的 debug, log, info, warn 和 error ``` diff --git a/docs/docs/api/material.md b/docs/docs/api/material.md index 4cf1948cfd..0e09441275 100644 --- a/docs/docs/api/material.md +++ b/docs/docs/api/material.md @@ -1,23 +1,43 @@ --- title: material - 物料 API -sidebar_position: 2 +sidebar_position: 10 --- -# 模块简介 + +> **@types** [IPublicApiMaterial](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/api/material.ts)
+> **@since** v1.0.0 + + +## 模块简介 负责物料相关的 API,包括资产包、设计器辅助层、物料元数据和物料元数据管道函数。 -# 变量(variables) -## componentsMap +## 变量 +### componentsMap 获取组件 map 结构 +```typescript +/** + * 获取组件 map 结构 + * get map of components + */ +get componentsMap(): { [key: string]: IPublicTypeNpmInfo | ComponentType | object } ; +``` +相关类型:[IPublicTypeNpmInfo](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/type/npm-info.ts) + +## 方法 -# 方法签名(functions) -## 资产包 -### setAssets +### 资产包 +#### setAssets 设置「[资产包](/site/docs/specs/lowcode-spec#2-协议结构)」结构 -**类型定义** ```typescript -function setAssets(assets: AssetsJson): void; +/** + * 设置「资产包」结构 + * set data for Assets + * @returns void + */ +setAssets(assets: IPublicTypeAssetsJson): void; ``` +相关类型:[IPublicTypeAssetsJson](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/type/assets-json.ts) + **示例** 直接在项目中引用 npm 包 @@ -28,34 +48,41 @@ import assets from '@alilc/mc-assets-/assets.json'; material.setAssets(assets); ``` -通过物料中心接口动态引入资产包 +通过接口动态引入资产包 ```typescript -import { ILowCodePluginContext, material, plugins } from '@alilc/lowcode-engine' +import { material, plugins } from '@alilc/lowcode-engine'; +import { IPublicModelPluginContext } from '@alilc/lowcode-types'; // 动态加载 assets -plugins.register((ctx: ILowCodePluginContext) => { +plugins.register((ctx: IPublicModelPluginContext) => { 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) + // 将下述链接替换为您的物料描述地址即可。 + 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) - } + console.error(err); + }; }, - } -}).catch(err => console.error(err)) + }; +}).catch(err => console.error(err)); ``` -### getAssets +#### getAssets 获取「资产包」结构 -**类型定义** + ```typescript -function getAssets(): AssetsJson; +/** + * 获取「资产包」结构 + * get AssetsJson data + * @returns IPublicTypeAssetsJson + */ +getAssets(): IPublicTypeAssetsJson; ``` +相关类型:[IPublicTypeAssetsJson](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/type/assets-json.ts) **示例** @@ -65,14 +92,19 @@ import { material } from '@alilc/lowcode-engine'; material.getAssets(); ``` -### loadIncrementalAssets +#### loadIncrementalAssets 加载增量的「资产包」结构,该增量包会与原有的合并 -**类型定义** ```typescript -function loadIncrementalAssets(incrementalAssets: AssetsJson): void; +/** + * 加载增量的「资产包」结构,该增量包会与原有的合并 + * load Assets incrementally, and will merge this with exiting assets + * @param incrementalAssets + * @returns + */ +loadIncrementalAssets(incrementalAssets: IPublicTypeAssetsJson): Promise; ``` -说明:**该增量包会与原有的合并** +相关类型:[IPublicTypeAssetsJson](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/type/assets-json.ts) **示例** ```typescript @@ -83,54 +115,35 @@ 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; -} +```typescript +import { material } from '@alilc/lowcode-engine'; +material.loadIncrementalAssets({ + version: '', + components: [ + { + "componentName": 'Button', + "props": [{ name: 'new', title: 'new', propType: 'string' }] + } + ], +}) +``` + +### 设计器辅助层 +#### addBuiltinComponentAction +在设计器辅助层增加一个扩展 action -export type IconType = string | ReactElement | ComponentType | IconConfig; +```typescript +/** + * 在设计器辅助层增加一个扩展 action + * add an action button in canvas context menu area + * @param action + */ +addBuiltinComponentAction(action: IPublicTypeComponentAction): void; ``` +相关类型:[IPublicTypeComponentAction](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/type/component-action.ts) **示例** @@ -153,13 +166,26 @@ material.addBuiltinComponentAction({ ``` ![image.png](https://img.alicdn.com/imgextra/i4/O1CN01jDbN7B1KfWVzJ16tw_!!6000000001191-2-tps-230-198.png) -### removeBuiltinComponentAction +#### removeBuiltinComponentAction 移除设计器辅助层的指定 action -**类型定义** + ```typescript -function removeBuiltinComponentAction(name: string): void; +/** + * 移除设计器辅助层的指定 action + * remove a builtin action button from canvas context menu area + * @param name + */ +removeBuiltinComponentAction(name: string): void; ``` +##### 内置设计器辅助 name + +- remove:删除 +- hide:隐藏 +- copy:复制 +- lock:锁定,不可编辑 +- unlock:解锁,可编辑 + **示例** ```typescript import { material } from '@alilc/lowcode-engine'; @@ -168,16 +194,25 @@ material.removeBuiltinComponentAction('myIconName'); ``` -### modifyBuiltinComponentAction +#### modifyBuiltinComponentAction 修改已有的设计器辅助层的指定 action -**类型定义** + ```typescript -function modifyBuiltinComponentAction( - actionName: string, - handle: (action: ComponentAction) => void -): void; +/** + * 修改已有的设计器辅助层的指定 action + * modify a builtin action button in canvas context menu area + * @param actionName + * @param handle + */ +modifyBuiltinComponentAction( + actionName: string, + handle: (action: IPublicTypeComponentAction) => void, + ): void; ``` -**内置设计器辅助 name** +相关类型:[IPublicTypeComponentAction](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/type/component-action.ts) + + +##### 内置设计器辅助 name - remove:删除 - hide:隐藏 @@ -201,14 +236,104 @@ material.modifyBuiltinComponentAction('remove', (action) => { } }); ``` -### -## 物料元数据 -### getComponentMeta + +### 右键菜单项 +#### addContextMenuOption + +添加右键菜单项 + +```typescript +/** + * 添加右键菜单项 + * @param action + */ +addContextMenuOption(action: IPublicTypeContextMenuAction): void; +``` + +示例 + +```typescript +import { IPublicEnumContextMenuType } from '@alilc/lowcode-types'; + +material.addContextMenuOption({ + name: 'parentItem', + title: 'Parent Item', + condition: (nodes) => true, + items: [ + { + name: 'childItem1', + title: 'Child Item 1', + action: (nodes) => console.log('Child Item 1 clicked', nodes), + condition: (nodes) => true + }, + // 分割线 + { + type: IPublicEnumContextMenuType.SEPARATOR + name: 'separator.1' + } + // 更多子菜单项... + ] +}); + +``` + +#### removeContextMenuOption + +删除特定右键菜单项 + +```typescript +/** + * 删除特定右键菜单项 + * @param name + */ +removeContextMenuOption(name: string): void; +``` + +#### adjustContextMenuLayout + +调整右键菜单项布局,每次调用都会覆盖之前注册的调整函数,只有最后注册的函数会被应用。 + +```typescript +/** + * 调整右键菜单项布局 + * @param actions + */ +adjustContextMenuLayout(fn: (actions: IPublicTypeContextMenuItem[]) => IPublicTypeContextMenuItem[]): void; +``` + +**示例** + +通过 adjustContextMenuLayout 补充分割线 + +```typescript +material.adjustContextMenuLayout((actions: IPublicTypeContextMenuAction) => { + const names = ['a', 'b']; + const newActions = []; + actions.forEach(d => { + newActions.push(d); + if (names.include(d.name)) { + newActions.push({ type: 'separator' }) + } + }); + return newActions +}) +``` + +### 物料元数据 + +#### getComponentMeta 获取指定名称的物料元数据 -**类型定义** + ```typescript -function getComponentMeta(componentName: string): ComponentMeta; +/** + * 获取指定名称的物料元数据 + * get component meta by component name + * @param componentName + * @returns + */ +getComponentMeta(componentName: string): IPublicModelComponentMeta | null; ``` +相关类型:[IPublicModelComponentMeta](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/model/component-meta.ts) **示例** ```typescript @@ -217,12 +342,19 @@ import { material } from '@alilc/lowcode-engine'; material.getComponentMeta('Input'); ``` -### getComponentMetasMap +#### getComponentMetasMap + 获取所有已注册的物料元数据 -**类型定义** + ```typescript -function getComponentMetasMap(): new Map; + /** + * 获取所有已注册的物料元数据 + * get map of all component metas + * @returns + */ + getComponentMetasMap(): Map; ``` +相关类型:[IPublicModelComponentMeta](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/model/component-meta.ts) **示例** ```typescript @@ -231,16 +363,33 @@ import { material } from '@alilc/lowcode-engine'; material.getComponentMetasMap(); ``` +#### refreshComponentMetasMap + +刷新 componentMetasMap,可触发模拟器里的 components 重新构建 + +**@since v1.1.7** + +```typescript + refreshComponentMetasMap(): void; +``` -## 物料元数据管道函数 -### registerMetadataTransducer +### 物料元数据管道函数 +#### registerMetadataTransducer 注册物料元数据管道函数,在物料信息初始化时执行。 -**类型定义** + ```typescript -function registerMetadataTransducer( - transducer: MetadataTransducer, // 管道函数 - level?: number, // 优先级 - id?: string | undefined, // id +/** + * 注册物料元数据管道函数,在物料信息初始化时执行。 + * register transducer to process component meta, which will be + * excuted during component meta`s initialization + * @param transducer + * @param level + * @param id + */ +registerMetadataTransducer( + transducer: IPublicTypeMetadataTransducer, + level?: number, + id?: string | undefined ): void; ``` @@ -289,27 +438,64 @@ function addonCombine(metadata: TransformedComponentMetadata) { material.registerMetadataTransducer(addonCombine, 1, 'parse-func'); ``` -### getRegisteredMetadataTransducers +删除高级 Tab + +```typescript +import { material } from '@alilc/lowcode-engine'; +import { IPublicTypeFieldConfig } from '@alilc/lowcode-types'; + +material.registerMetadataTransducer((transducer) => { + const combined: IPublicTypeFieldConfig[] = []; + + transducer.configure.combined?.forEach(d => { + if (d.name !== '#advanced') { + combined.push(d); + } + }); + + return { + ...transducer, + configure: { + ...transducer.configure, + combined, + } + }; +}, 111, 'parse-func'); +``` + +#### getRegisteredMetadataTransducers 获取所有物料元数据管道函数 -**类型定义** + ```typescript -function getRegisteredMetadataTransducers(): MetadataTransducer[]; +/** + * 获取所有物料元数据管道函数 + * get all registered metadata transducers + * @returns {IPublicTypeMetadataTransducer[]} + */ +getRegisteredMetadataTransducers(): IPublicTypeMetadataTransducer[]; ``` **示例** ```typescript import { material } from '@alilc/lowcode-engine' -material.getRegisteredMetadataTransducers('parse-func'); +material.getRegisteredMetadataTransducers(); ``` -## -# 事件(Event) +## 事件 ### onChangeAssets 监听 assets 变化的事件 -**类型定义** + ```typescript -function onChangeAssets(fn: () => void): void; +/** + * 监听 assets 变化的事件 + * add callback for assets changed event + * @param fn + */ +onChangeAssets(fn: () => void): IPublicTypeDisposable; ``` + +相关类型:[IPublicTypeDisposable](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/type/disposable.ts) + **示例** ```typescript import { material } from '@alilc/lowcode-engine'; diff --git a/docs/docs/api/model/_category_.json b/docs/docs/api/model/_category_.json new file mode 100644 index 0000000000..3afc4f79b5 --- /dev/null +++ b/docs/docs/api/model/_category_.json @@ -0,0 +1,6 @@ +{ + "label": "模型定义 Models", + "position": 100, + "collapsed": false, + "collapsible": true +} diff --git a/docs/docs/api/model/clipboard.md b/docs/docs/api/model/clipboard.md new file mode 100644 index 0000000000..15d9e280ca --- /dev/null +++ b/docs/docs/api/model/clipboard.md @@ -0,0 +1,43 @@ +--- +title: Clipboard +sidebar_position: 14 +--- + +> **@types** [IPublicModelClipboard](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/model/clipboard.ts)
+> **@since** v1.1.0 + +## 方法 + +### setData + +给剪贴板赋值 + +```typescript +/** + * 给剪贴板赋值 + * set data to clipboard + * + * @param {*} data + * @since v1.1.0 + */ +setData(data: any): void; +``` + +### waitPasteData + +设置剪贴板数据设置的回调 + +```typescript +/** + * 设置剪贴板数据设置的回调 + * set callback for clipboard provide paste data + * + * @param {KeyboardEvent} keyboardEvent + * @param {(data: any, clipboardEvent: ClipboardEvent) => void} cb + * @since v1.1.0 + */ +waitPasteData( + keyboardEvent: KeyboardEvent, + cb: (data: any, clipboardEvent: ClipboardEvent) => void, + ): void; +``` \ No newline at end of file diff --git a/docs/docs/api/model/component-meta.md b/docs/docs/api/model/component-meta.md new file mode 100644 index 0000000000..28f7fe7407 --- /dev/null +++ b/docs/docs/api/model/component-meta.md @@ -0,0 +1,173 @@ +--- +title: ComponentMeta +sidebar_position: 15 +--- + +> **@types** [IPublicModelComponentMeta](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/model/component-meta.ts)
+> **@since** v1.0.0 + +## 基本介绍 + +组件元数据信息模型 + +## 属性 + +### componentName + +组件名 + +`@type {string}` + +### isContainer + +是否是「容器型」组件 + +`@type {boolean}` + +### isMinimalRenderUnit +是否是最小渲染单元 + +当组件需要重新渲染时: +- 若为最小渲染单元,则只渲染当前组件, +- 若不为最小渲染单元,则寻找到上层最近的最小渲染单元进行重新渲染,直至根节点。 + +`@type {boolean}` + +### isModal + +是否为「模态框」组件 + +`@type {boolean}` + +### configure + +获取用于设置面板显示用的配置 + +`@type {IPublicTypeFieldConfig[]}` + +相关类型:[IPublicTypeFieldConfig](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/type/field-config.ts) + +### title + +标题 + +`@type {string | IPublicTypeI18nData | ReactElement}` + +相关类型:[IPublicTypeI18nData](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/type/i18n-data.ts) + +### icon + +图标 + +`@type {IPublicTypeIconType}` + +相关类型:[IPublicTypeIconType](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/type/icon-type.ts) + +### npm + +组件 npm 信息 + +`@type {IPublicTypeNpmInfo}` + +相关类型:[IPublicTypeNpmInfo](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/type/npm-info.ts) + +### availableActions + +获取元数据 + +`@type {IPublicTypeTransformedComponentMetadata}` + +相关类型:[IPublicTypeTransformedComponentMetadata](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/type/transformed-component-metadata.ts) + +### advanced + +组件元数据中高级配置部分 + +`@type {IPublicTypeAdvanced}` + +相关类型:[IPublicTypeAdvanced](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/type/advanced.ts) + +## 方法 + +### setNpm + +设置 npm 信息 + +```typescript +/** + * 设置 npm 信息 + * set method for npm inforamtion + * @param npm + */ +setNpm(npm: IPublicTypeNpmInfo): void; +``` + +相关类型:[IPublicTypeNpmInfo](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/type/npm-info.ts) + +### getMetadata + +获取元数据 + +```typescript +/** + * 获取元数据 + * get component metadata + */ +getMetadata(): IPublicTypeTransformedComponentMetadata; +``` + +相关类型:[IPublicTypeTransformedComponentMetadata](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/type/transformed-component-metadata.ts) + +### checkNestingUp + +检测当前对应节点是否可被放置在父节点中 + +```typescript +/** + * 检测当前对应节点是否可被放置在父节点中 + * check if the current node could be placed in parent node + * @param my 当前节点 + * @param parent 父节点 + */ +checkNestingUp(my: IPublicModelNode | IPublicTypeNodeData, parent: any): boolean; +``` + +相关类型: +- [IPublicModelNode](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/model/node.ts) +- [IPublicTypeNodeData](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/type/node-data.ts) + + +### checkNestingDown + +检测目标节点是否可被放置在父节点中 + +```typescript +/** + * 检测目标节点是否可被放置在父节点中 + * check if the target node(s) could be placed in current node + * @param my 当前节点 + * @param parent 父节点 + */ +checkNestingDown( + my: IPublicModelNode | IPublicTypeNodeData, + target: IPublicTypeNodeSchema | IPublicModelNode | IPublicTypeNodeSchema[], + ): boolean; +``` + +相关类型: +- [IPublicModelNode](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/model/node.ts) +- [IPublicTypeNodeData](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/type/node-data.ts) +- [IPublicTypeNodeSchema](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/type/node-schema.ts) + + +### refreshMetadata + +刷新元数据,会触发元数据的重新解析和刷新 + +```typescript +/** + * 刷新元数据,会触发元数据的重新解析和刷新 + * refresh metadata + */ +refreshMetadata(): void; +``` diff --git a/docs/docs/api/model/detecting.md b/docs/docs/api/model/detecting.md new file mode 100644 index 0000000000..ccd60e3a65 --- /dev/null +++ b/docs/docs/api/model/detecting.md @@ -0,0 +1,87 @@ +--- +title: Detecting +sidebar_position: 6 +--- +> **@types** [IPublicModelDetecting](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/model/detecting.ts)
+> **@since** v1.0.0 + +## 基本介绍 + +画布节点悬停模型 + +## 属性 + +### current + +当前 hover 的节点 + +`@type {IPublicModelNode | null}` + +相关类型:[IPublicModelNode](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/model/node.ts) + +**@since v1.0.16** + +### enable + +是否启用 + +`@type {boolean}` + + +## 方法 +### capture + +hover 指定节点 + +```typescript +/** + * hover 指定节点 + * capture node with nodeId + * @param id 节点 id + */ +capture(id: string): void; +``` + +### release + +hover 离开指定节点 + +```typescript +/** + * hover 离开指定节点 + * release node with nodeId + * @param id 节点 id + */ +release(id: string): void; +``` + +### leave + +清空 hover 态 + +```typescript +/** + * 清空 hover 态 + * clear all hover state + */ +leave(): void; +``` + +## 事件 +### onDetectingChange +hover 节点变化事件 + +```typescript +/** + * hover 节点变化事件 + * set callback which will be called when hovering object changed. + * @since v1.1.0 + */ +onDetectingChange(fn: (node: IPublicModelNode | null) => void): IPublicTypeDisposable; +``` + +相关类型: +- [IPublicModelNode](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/model/node.ts) +- [IPublicTypeDisposable](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/type/disposable.ts) + +**@since v1.1.0** \ No newline at end of file diff --git a/docs/docs/api/model/document-model.md b/docs/docs/api/model/document-model.md new file mode 100644 index 0000000000..8d813e7678 --- /dev/null +++ b/docs/docs/api/model/document-model.md @@ -0,0 +1,408 @@ +--- +title: DocumentModel +sidebar_position: 0 +--- +> **@types** [IPublicModelDocumentModel](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/model/document-model.ts)
+> **@since** v1.0.0 + +## 基本介绍 + +文档模型 + +## 属性 + +### id + +唯一 ID + +`@type {string}` + +### selection + +画布节点选中区模型实例 + +`@type {IPublicModelSelection}` + +相关章节:[节点选中区模型](./selection) + +相关类型:[IPublicModelSelection](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/model/selection.ts) + +### detecting + +画布节点 hover 区模型实例 + +`@type {IPublicModelDetecting}` + +相关章节:[画布节点悬停模型](./detecting) + +相关类型:[IPublicModelDetecting](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/model/detecting.ts) + +### history + +操作历史模型实例 + +`@type {IPublicModelHistory}` + +相关章节:[操作历史模型](./history) + +相关类型:[IPublicModelHistory](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/model/history.ts) + +### project + +获取当前文档模型所属的 project + +`@type {IPublicApiProject}` + +相关类型:[IPublicApiProject](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/api/project.ts) + +### root + +获取文档的根节点 + +`@type {IPublicModelNode | null}` + +相关类型:[IPublicModelNode](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/model/node.ts) + +### nodesMap + +获取文档下所有节点 Map, key 为 nodeId + +`@type {Map} ` + + +相关章节:[节点模型](./node) + +相关类型:[IPublicModelNode](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/model/node.ts) + +### modalNodesManager + +模态节点管理器 + +`@type {IPublicModelModalNodesManager | null}` + +相关章节:[模态节点管理](./modal-nodes-manager) + +相关类型:[IPublicModelModalNodesManager](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/model/modal-nodes-manager.ts) + +### dropLocation + +文档的 dropLocation + +`@type {IPublicModelDropLocation | null}` + + +相关类型:[IPublicModelDropLocation](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/model/drop-location.ts) + +**@since v1.1.0** + +## 方法 +### getNodeById + +根据 nodeId 返回 [Node](./node) 实例 + +```typescript +/** + * 根据 nodeId 返回 Node 实例 + * get node by nodeId + * @param nodeId + * @returns + */ +getNodeById(nodeId: string): IPublicModelNode | null; +``` + +相关类型:[IPublicModelNode](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/model/node.ts) + + +### importSchema + +导入 schema + +```typescript +/** + * 导入 schema + * import schema data + * @param schema + */ +importSchema(schema: IPublicTypeRootSchema): void; +``` + +相关类型:[IPublicTypeRootSchema](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/type/root-schema.ts) + + +### exportSchema +导出 schema + +```typescript +/** + * 导出 schema + * export schema + * @param stage + * @returns + */ +exportSchema(stage: IPublicEnumTransformStage): IPublicTypeRootSchema | undefined; +``` + +相关类型: +- [IPublicEnumTransformStage](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/enum/transform-stage.ts) +- [IPublicTypeRootSchema](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/type/root-schema.ts) + +### insertNode + +插入节点 + +```typescript +/** + * 插入节点 + * insert a node + */ +insertNode( + parent: IPublicModelNode, + thing: IPublicModelNode, + at?: number | null | undefined, + copy?: boolean | undefined +): IPublicModelNode | null; +``` + +相关类型:[IPublicModelNode](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/model/node.ts) + +### createNode + +创建一个节点 + +```typescript +/** + * 创建一个节点 + * create a node + * @param data + * @returns + */ +createNode(data: any): IPublicModelNode | null; +``` + +相关类型:[IPublicModelNode](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/model/node.ts) + +### removeNode + +移除指定节点/节点id + +```typescript +/** + * 移除指定节点/节点id + * remove a node by node instance or nodeId + * @param idOrNode + */ +removeNode(idOrNode: string | IPublicModelNode): void; +``` + +相关类型:[IPublicModelNode](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/model/node.ts) + +### checkNesting +检查拖拽放置的目标节点是否可以放置该拖拽对象 + +```typescript +/** + * 检查拖拽放置的目标节点是否可以放置该拖拽对象 + * check if dragOjbect can be put in this dragTarget + * @param dropTarget 拖拽放置的目标节点 + * @param dragObject 拖拽的对象 + * @returns boolean 是否可以放置 + * @since v1.0.16 + */ +checkNesting( + dropTarget: IPublicModelNode, + dragObject: IPublicTypeDragNodeObject | IPublicTypeDragNodeDataObject +): boolean; +``` + +相关类型: +- [IPublicModelNode](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/model/node.ts) +- [IPublicTypeDragNodeObject](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/type/drag-node-object.ts) +- [IPublicTypeDragNodeDataObject](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/type/drag-node-object-data.ts) + +**@since v1.0.16** + +### isDetectingNode +判断是否当前节点处于被探测状态 + +```typescript +/** + * 判断是否当前节点处于被探测状态 + * check is node being detected + * @param node + * @since v1.1.0 + */ +isDetectingNode(node: IPublicModelNode): boolean; +``` +相关类型:[IPublicModelNode](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/model/node.ts) + + +**@since v1.1.0** + + +## 事件 +### onAddNode + +当前 document 新增节点事件 + +```typescript +/** + * 当前 document 新增节点事件 + * set callback for event on node is created for a document + */ +onAddNode(fn: (node: IPublicModelNode) => void): IPublicTypeDisposable; +``` + +相关类型: +- [IPublicModelNode](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/model/node.ts) +- [IPublicTypeDisposable](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/type/disposable.ts) + +### onMountNode + +当前 document 新增节点事件,此时节点已经挂载到 document 上 + +```typescript +/** + * 当前 document 新增节点事件,此时节点已经挂载到 document 上 + * set callback for event on node is mounted to canvas + */ +onMountNode(fn: (payload: { node: IPublicModelNode }) => void): IPublicTypeDisposable; +``` + +相关类型: +- [IPublicModelNode](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/model/node.ts) +- [IPublicTypeDisposable](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/type/disposable.ts) + +### onRemoveNode +当前 document 删除节点事件 + +```typescript +/** + * 当前 document 删除节点事件 + * set callback for event on node is removed + */ +onRemoveNode(fn: (node: IPublicModelNode) => void): IPublicTypeDisposable; +``` + +相关类型: +- [IPublicModelNode](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/model/node.ts) +- [IPublicTypeDisposable](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/type/disposable.ts) + + +### onChangeDetecting + +当前 document 的 hover 变更事件 + +```typescript +/** + * 当前 document 的 hover 变更事件 + * + * set callback for event on detecting changed + */ +onChangeDetecting(fn: (node: IPublicModelNode) => void): IPublicTypeDisposable; +``` + +相关类型: +- [IPublicModelNode](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/model/node.ts) +- [IPublicTypeDisposable](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/type/disposable.ts) + +### onChangeSelection + +当前 document 的选中变更事件 + +```typescript +/** + * 当前 document 的选中变更事件 + * set callback for event on selection changed + */ +onChangeSelection(fn: (ids: string[]) => void): IPublicTypeDisposable; +``` + +相关类型:[IPublicTypeDisposable](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/type/disposable.ts) + +### onChangeNodeVisible + +当前 document 的节点显隐状态变更事件 + +```typescript +/** + * 当前 document 的节点显隐状态变更事件 + * set callback for event on visibility changed for certain node + * @param fn + */ +onChangeNodeVisible(fn: (node: IPublicModelNode, visible: boolean) => void): IPublicTypeDisposable; +``` + +- 相关类型:[IPublicModelNode](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/model/node.ts) +- 相关类型:[IPublicTypeDisposable](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/type/disposable.ts) + +### onChangeNodeChildren + +当前 document 的节点 children 变更事件 + +```typescript +onChangeNodeChildren(fn: (info?: IPublicTypeOnChangeOptions) => void): IPublicTypeDisposable; +``` + +相关类型:[IPublicTypeDisposable](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/type/disposable.ts) + +### onChangeNodeProp +当前 document 节点属性修改事件 + +```typescript +onChangeNodeProp(fn: (info: IPublicTypePropChangeOptions) => void): IPublicTypeDisposable; +``` + +相关类型:[IPublicTypeDisposable](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/type/disposable.ts) + +### onImportSchema +当前 document 导入新的 schema 事件 +```typescript +/** + * import schema event + * @param fn + * @since v1.0.15 + */ +onImportSchema(fn: (schema: IPublicTypeRootSchema) => void): IPublicTypeDisposable; +``` +相关类型: +- [IPublicTypeDisposable](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/type/disposable.ts) +- [IPublicTypeRootSchema](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/type/root-schema.ts) + +**@since v1.0.15** + +### onFocusNodeChanged +设置聚焦节点变化的回调 + +```typescript +/** + * 设置聚焦节点变化的回调 + * triggered focused node is set mannually from plugin + * @param fn + * @since v1.1.0 + */ +onFocusNodeChanged( + fn: (doc: IPublicModelDocumentModel, focusNode: IPublicModelNode) => void, +): IPublicTypeDisposable; +``` +相关类型: +- [IPublicTypeDisposable](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/type/disposable.ts) +- [IPublicModelNode](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/model/node.ts) + +**@since v1.1.0** + +### onDropLocationChanged +设置 DropLocation 变化的回调 + +```typescript +/** + * 设置 DropLocation 变化的回调 + * triggered when drop location changed + * @param fn + * @since v1.1.0 + */ +onDropLocationChanged(fn: (doc: IPublicModelDocumentModel) => void): IPublicTypeDisposable; +``` + +相关类型:[IPublicTypeDisposable](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/type/disposable.ts) + +**@since v1.1.0** \ No newline at end of file diff --git a/docs/docs/api/model/dragon.md b/docs/docs/api/model/dragon.md new file mode 100644 index 0000000000..c6feca4329 --- /dev/null +++ b/docs/docs/api/model/dragon.md @@ -0,0 +1,129 @@ +--- +title: Dragon +sidebar_position: 99 +--- +> **@types** [IPublicModelDragon](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/model/dragon.ts)
+> **@since** v1.0.0 + +## 基本介绍 + +拖拽对象 + +### 对应接口 +```typescript +import { IPublicModelDragon } from '@alilc/lowcode-types'; +``` + +### 支持版本 + +**@since** v1.1.0 + +## 属性 + +### dragging + +是否正在拖动 + +```typescript +/** + * is dragging or not + */ +get dragging(): boolean; +``` + +## 方法 + +### onDragstart + +绑定 dragstart 事件 + +```typescript +/** + * 绑定 dragstart 事件 + * bind a callback function which will be called on dragging start + * @param func + * @returns + */ +onDragstart(func: (e: IPublicModelLocateEvent) => any): () => void; +``` + +### onDrag + +绑定 drag 事件 +```typescript +/** + * 绑定 drag 事件 + * bind a callback function which will be called on dragging + * @param func + * @returns + */ +onDrag(func: (e: IPublicModelLocateEvent) => any): () => void; +``` + +### onDragend + +绑定 dragend 事件 + +```typescript +/** + * 绑定 dragend 事件 + * bind a callback function which will be called on dragging end + * @param func + * @returns + */ +onDragend(func: (o: { dragObject: IPublicModelDragObject; copy?: boolean }) => any): () => void; +``` + +### from + +设置拖拽监听的区域 shell,以及自定义拖拽转换函数 boost + +```typescript +/** + * 设置拖拽监听的区域 shell,以及自定义拖拽转换函数 boost +* set a html element as shell to dragon as monitoring target, and +* set boost function which is used to transform a MouseEvent to type +* IPublicTypeDragNodeDataObject. + * @param shell 拖拽监听的区域 + * @param boost 拖拽转换函数 + */ +from(shell: Element, boost: (e: MouseEvent) => IPublicTypeDragNodeDataObject | null): any; +``` + +### boost + +发射拖拽对象 +```typescript +/** + * 发射拖拽对象 + * boost your dragObject for dragging(flying) + * + * @param dragObject 拖拽对象 + * @param boostEvent 拖拽初始时事件 + */ +boost(dragObject: IPublicTypeDragObject, boostEvent: MouseEvent | DragEvent, fromRglNode?: IPublicModelNode): void; +``` + +### addSensor + +添加投放感应区 + +```typescript +/** + * 添加投放感应区 + * add sensor area + */ +addSensor(sensor: any): void; +``` + +### removeSensor + +移除投放感应 + +```typescript +/** + * 移除投放感应 + * remove sensor area + */ +removeSensor(sensor: any): void; +``` \ No newline at end of file diff --git a/docs/docs/api/model/drop-location.md b/docs/docs/api/model/drop-location.md new file mode 100644 index 0000000000..dc6a684e42 --- /dev/null +++ b/docs/docs/api/model/drop-location.md @@ -0,0 +1,54 @@ +--- +title: DropLocation +sidebar_position: 13 +--- + +> **@types** [IPublicModelDropLocation](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/model/drop-location.ts)
+> **@since** v1.1.0 + + +## 基本介绍 + +拖拽放置位置模型 + +## 属性 + +### target + +拖拽放置位置目标 + +`@type {IPublicModelNode | null}` + +相关类型:[IPublicModelNode](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/model/node.ts) + +### detail + +拖拽放置位置详情 + +`@type {IPublicTypeLocationDetail}` + +相关类型:[IPublicTypeLocationDetail](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/type/location-detail.ts) + +### event + +拖拽放置位置对应的事件 + +`@type {IPublicTypeLocationDetail}` + +相关类型:[IPublicModelLocateEvent](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/model/location-event.ts) + +## 方法 + +### clone + +获取一份当前对象的克隆 + +```typescript +/** + * 获取一份当前对象的克隆 + * get a clone object of current dropLocation + */ +clone(event: IPublicModelLocateEvent): IPublicModelDropLocation; +``` + +相关类型:[IPublicModelLocateEvent](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/model/location-event.ts) \ No newline at end of file diff --git a/docs/docs/api/model/editor-view.md b/docs/docs/api/model/editor-view.md new file mode 100644 index 0000000000..a3cc83e1f2 --- /dev/null +++ b/docs/docs/api/model/editor-view.md @@ -0,0 +1,21 @@ +--- +title: EditorView +sidebar_position: 12 +--- + +> **[@experimental](./#experimental)**
+> **@types** [IPublicModelEditorView](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/model/editor-view.ts)
+> **@since** v1.1.7 + +窗口编辑视图 + +## 类型定义 + +``` +import { IPublicModelPluginContext } from "./plugin-context"; + +export interface IPublicModelEditorView extends IPublicModelPluginContext {}; + +``` + +相关类型定义: [IPublicModelPluginContext](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/model/plugin-context.ts) diff --git a/docs/docs/api/model/history.md b/docs/docs/api/model/history.md new file mode 100644 index 0000000000..b8c4d791b1 --- /dev/null +++ b/docs/docs/api/model/history.md @@ -0,0 +1,124 @@ +--- +title: History +sidebar_position: 5 +--- +> **@types** [IPublicModelHistory](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/model/history.ts)
+> **@since** v1.0.0 + +## 基本介绍 + +操作历史记录模型 + +## 方法 +### go + +历史记录跳转到指定位置 + +```typescript +/** + * 历史记录跳转到指定位置 + * go to a specific history + * @param cursor + */ +go(cursor: number): void; +``` + +### back + +历史记录后退 + +```typescript +/** + * 历史记录后退 + * go backward in history + */ +back(): void; +``` + +### forward + +forward() + +历史记录前进 + +```typescript +/** + * 历史记录前进 + * go forward in history + */ +forward(): void; +``` + +### savePoint + +保存当前状态 + +```typescript +/** + * 保存当前状态 + * do save current change as a record in history + */ +savePoint(): void; +``` + +### isSavePoint + +当前是否是「保存点」,即是否有状态变更但未保存 + +```typescript +/** + * 当前是否是「保存点」,即是否有状态变更但未保存 + * check if there is unsaved change for history + */ +isSavePoint(): boolean; +``` + +### getState + +获取 state,判断当前是否为「可回退」、「可前进」的状态 + +```typescript +/** + * 获取 state,判断当前是否为「可回退」、「可前进」的状态 + * get flags in number which indicat current change state + * + * | 1 | 1 | 1 | + * | -------- | -------- | -------- | + * | modified | redoable | undoable | + * eg: + * 7 means : modified && redoable && undoable + * 5 means : modified && undoable + */ +getState(): number; +``` + +## 事件 +### onChangeState + +监听 state 变更事件 + +```typescript +/** + * 监听 state 变更事件 + * monitor on stateChange event + * @param func + */ +onChangeState(func: () => any): IPublicTypeDisposable; +``` + +相关类型:[IPublicTypeDisposable](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/type/disposable.ts) + +### onChangeCursor + +监听历史记录游标位置变更事件 + +```typescript +/** + * 监听历史记录游标位置变更事件 + * monitor on cursorChange event + * @param func + */ +onChangeCursor(func: () => any): IPublicTypeDisposable; +``` + +相关类型:[IPublicTypeDisposable](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/type/disposable.ts) \ No newline at end of file diff --git a/docs/docs/api/model/modal-nodes-manager.md b/docs/docs/api/model/modal-nodes-manager.md new file mode 100644 index 0000000000..fead53f0a1 --- /dev/null +++ b/docs/docs/api/model/modal-nodes-manager.md @@ -0,0 +1,94 @@ +--- +title: ModalNodesManager +sidebar_position: 7 +--- +> **@types** [IPublicModelModalNodesManager](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/model/modal-nodes-manager.ts)
+> **@since** v1.0.0 + +## 基本介绍 + +模态节点管理器模型 + +## 方法 + +### setNodes + +设置模态节点,触发内部事件 + +```typescript +/** + * 设置模态节点,触发内部事件 + * set modal nodes, trigger internal events + */ +setNodes(): void; +``` + +### getModalNodes + +获取模态节点(们) + +```typescript +/** + * 获取模态节点(们) + * get modal nodes + */ +getModalNodes(): IPublicModelNode[]; +``` + +相关类型:[IPublicModelNode](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/model/node.ts) + +### getVisibleModalNode + +获取当前可见的模态节点 + +```typescript +/** + * 获取当前可见的模态节点 + * get current visible modal node + */ +getVisibleModalNode(): IPublicModelNode | null; +``` + +相关类型:[IPublicModelNode](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/model/node.ts) + +### hideModalNodes + +隐藏模态节点(们) + +```typescript +/** + * 隐藏模态节点(们) + * hide modal nodes + */ +hideModalNodes(): void; +``` + +### setVisible + +设置指定节点为可见态 + +```typescript +/** + * 设置指定节点为可见态 + * set specific model node as visible + * @param node IPublicModelNode + */ +setVisible(node: IPublicModelNode): void; +``` + +相关类型:[IPublicModelNode](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/model/node.ts) + +### setInvisible + +设置指定节点为不可见态 + +```typescript +/** + * 设置指定节点为不可见态 + * set specific model node as invisible + * @param node IPublicModelNode + */ +setInvisible(node: IPublicModelNode): void; +``` + +相关类型:[IPublicModelNode](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/model/node.ts) diff --git a/docs/docs/api/model/node-children.md b/docs/docs/api/model/node-children.md new file mode 100644 index 0000000000..5507fcbfb8 --- /dev/null +++ b/docs/docs/api/model/node-children.md @@ -0,0 +1,325 @@ +--- +title: NodeChildren +sidebar_position: 2 +--- +> **@types** [IPublicModelNodeChildren](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/model/node-children.ts)
+> **@since** v1.0.0 + +## 基本介绍 +节点孩子模型 + +## 属性 +### owner + +返回当前 children 实例所属的节点实例 + +`@type {IPublicModelNode | null}` + +相关类型:[IPublicModelNode](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/model/node.ts) + +### size + +children 内的节点实例数 + +`@type {number}` + + +### isEmptyNode + +是否为空 + +`@type {boolean}` + +**@since v1.1.0** +> v1.1.0 之前请使用 `isEmpty` + +### notEmptyNode + +是否不为空 + +`@type {boolean}` + +**@since v1.1.0** + +## 方法 +### delete +删除指定节点 + +```typescript +/** + * 删除指定节点 + * delete the node + * @param node + */ +delete(node: IPublicModelNode): boolean; +``` + +相关类型:[IPublicModelNode](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/model/node.ts) + +### insert + +插入一个节点 + +```typescript +/** + * 插入一个节点 + * insert the node + * @param node + */ +insert(node: IPublicModelNode): boolean; +``` + +相关类型:[IPublicModelNode](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/model/node.ts) + + +### indexOf + +返回指定节点的下标 + +```typescript +/** + * 返回指定节点的下标 + * get index of node in current children + * @param node + * @returns + */ +indexOf(node: IPublicModelNode): number; +``` + +相关类型:[IPublicModelNode](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/model/node.ts) + +### splice + +类似数组 splice 操作 + +```typescript +/** + * 类似数组 splice 操作 + * provide the same function with {Array.prototype.splice} + * @param start + * @param deleteCount + * @param node + */ +splice(start: number, deleteCount: number, node?: IPublicModelNode): any; +``` + +相关类型:[IPublicModelNode](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/model/node.ts) + + +### get + +返回指定下标的节点 + +```typescript +/** + * 返回指定下标的节点 + * get node with index + * @param index + * @returns + */ +get(index: number): IPublicModelNode | null; +``` + +相关类型:[IPublicModelNode](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/model/node.ts) + + +### has + +是否包含指定节点 + +```typescript +/** + * 是否包含指定节点 + * check if node exists in current children + * @param node + * @returns + */ +has(node: IPublicModelNode): boolean; +``` + +相关类型:[IPublicModelNode](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/model/node.ts) + + +### forEach + +类似数组的 forEach + +```typescript +/** + * 类似数组的 forEach + * provide the same function with {Array.prototype.forEach} + * @param fn + */ +forEach(fn: (node: IPublicModelNode, index: number) => void): void; + +``` + +相关类型:[IPublicModelNode](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/model/node.ts) + +### reverse + +类似数组的 reverse + +```typescript +/** + * 类似数组的 reverse + * provide the same function with {Array.prototype.reverse} + */ +reverse(): IPublicModelNode[]; + +``` + +相关类型:[IPublicModelNode](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/model/node.ts) + + +### map + +类似数组的 map + +```typescript +/** + * 类似数组的 map + * provide the same function with {Array.prototype.map} + * @param fn + */ +map(fn: (node: IPublicModelNode, index: number) => T[]): any[] | null; +``` + +相关类型:[IPublicModelNode](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/model/node.ts) + + +### every + +类似数组的 every + +```typescript +/** + * 类似数组的 every + * provide the same function with {Array.prototype.every} + * @param fn + */ +every(fn: (node: IPublicModelNode, index: number) => boolean): boolean; +``` + +相关类型:[IPublicModelNode](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/model/node.ts) + + +### some + +类似数组的 some + +```typescript +/** + * 类似数组的 some + * provide the same function with {Array.prototype.some} + * @param fn + */ +some(fn: (node: IPublicModelNode, index: number) => boolean): boolean; +``` + +相关类型:[IPublicModelNode](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/model/node.ts) + + +### filter + +类似数组的 filter + +```typescript +/** + * 类似数组的 filter + * provide the same function with {Array.prototype.filter} + * @param fn + */ +filter(fn: (node: IPublicModelNode, index: number) => boolean): any; +``` + +相关类型:[IPublicModelNode](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/model/node.ts) + + +### find + +类似数组的 find + +```typescript +/** + * 类似数组的 find + * provide the same function with {Array.prototype.find} + * @param fn + */ +find(fn: (node: IPublicModelNode, index: number) => boolean): IPublicModelNode | null; +``` + +相关类型:[IPublicModelNode](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/model/node.ts) + + +### reduce + +类似数组的 reduce + +```typescript +/** + * 类似数组的 reduce + * provide the same function with {Array.prototype.reduce} + * @param fn + */ +reduce(fn: (acc: any, cur: IPublicModelNode) => any, initialValue: any): void; +``` + +相关类型:[IPublicModelNode](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/model/node.ts) + + +### importSchema + +导入 schema + +```typescript +/** + * 导入 schema + * import schema + * @param data + */ +importSchema(data?: IPublicTypeNodeData | IPublicTypeNodeData[]): void; +``` + +相关类型:[IPublicTypeNodeData](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/type/node-data.ts) + + +### exportSchema +导出 schema + +```typescript +/** + * 导出 schema + * export schema + * @param stage + */ +exportSchema(stage: IPublicEnumTransformStage): IPublicTypeNodeSchema; +``` + +相关类型: +- [IPublicEnumTransformStage](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/enum/transform-stage.ts) +- [IPublicTypeNodeSchema](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/type/node-schema.ts) + + +### mergeChildren + +执行新增、删除、排序等操作 + +```typescript +/** + * 执行新增、删除、排序等操作 + * excute remove/add/sort operations + * @param remover + * @param adder + * @param sorter + */ +mergeChildren( + remover: (node: IPublicModelNode, idx: number) => boolean, + adder: (children: IPublicModelNode[]) => IPublicTypeNodeData[] | null, + sorter: (firstNode: IPublicModelNode, secondNode: IPublicModelNode) => number +): any; +``` + +相关类型: +- [IPublicModelNode](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/model/node.ts) +- [IPublicTypeNodeData](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/type/node-data.ts) diff --git a/docs/docs/api/model/node.md b/docs/docs/api/model/node.md new file mode 100644 index 0000000000..43de96a33d --- /dev/null +++ b/docs/docs/api/model/node.md @@ -0,0 +1,678 @@ +--- +title: Node +sidebar_position: 1 +--- +> **@types** [IPublicModelNode](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/model/node.ts)
+> **@since** v1.0.0 + +## 基本介绍 + +节点模型 + +## 属性 +### id + +节点 id + +`@type {string}` + +### title + +节点标题 + +`@type {string | IPublicTypeI18nData | ReactElement}` + +相关类型:[IPublicTypeI18nData](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/type/i18n-data.ts) + +### isContainerNode + +是否为「容器型」节点 + +`@type {boolean}` + +**@since v1.1.0** +> v1.1.0 之前请使用 `isContainer` + +### isRootNode + +是否为根节点 + +`@type {boolean}` + +**@since v1.1.0** + +> v1.1.0 之前请使用 `isRoot` + +### isEmptyNode + +是否为空节点(无 children 或者 children 为空) + +`@type {boolean}` + +**@since v1.1.0** + +> v1.1.0 之前请使用 `isEmpty` + +### isPageNode + +是否为 Page 节点 + +`@type {boolean}` + +**@since v1.1.0** + +> v1.1.0 之前请使用 `isPage` + +### isComponentNode + +是否为 Component 节点 + +`@type {boolean}` + +**@since v1.1.0** + +> v1.1.0 之前请使用 `isComponent` + +### isModalNode + +是否为「模态框」节点 + +`@type {boolean}` + +**@since v1.1.0** + +> v1.1.0 之前请使用 `isModal` + +### isSlotNode + +是否为插槽节点 + +`@type {boolean}` + +**@since v1.1.0** + +> v1.1.0 之前请使用 `isSlot` + +### isParentalNode + +是否为父类/分支节点 + +`@type {boolean}` + +**@since v1.1.0** + +> v1.1.0 之前请使用 `isParental` + +### isLeafNode + +是否为叶子节点 + +`@type {boolean}` + +**@since v1.1.0** + +> v1.1.0 之前请使用 `isLeaf` + +### isLocked + +获取当前节点的锁定状态 + +**@since v1.0.16** + +### isRGLContainerNode +设置为磁贴布局节点,使用方式可参考:[磁贴布局在钉钉宜搭报表设计引擎中的实现](https://mp.weixin.qq.com/s/PSTut5ahAB8nlJ9kBpBaxw) + +`@type {boolean}` + +**@since v1.1.0** + +> v1.0.16 - v1.1.0 请使用 `isRGLContainer` + +### index + +下标 + +`@type {number}` + +### icon + +图标 + +`@type {IPublicTypeIconType}` + +相关类型:[IPublicTypeIconType](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/type/icon-type.ts) + +### zLevel + +节点所在树的层级深度,根节点深度为 0 + +`@type {number}` + +### componentName + +节点 componentName + +`@type {string}` + +### componentMeta + +节点的物料元数据 + +`@type {IPublicModelComponentMeta | null}` + +相关类型:[IPublicModelComponentMeta](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/model/component-meta.ts) + + +### document + +获取节点所属的[文档模型](./document-model)对象 + +`@type {IPublicModelDocumentModel | null}` + +相关类型:[IPublicModelDocumentModel](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/model/document-model.ts) + +### prevSibling + +获取当前节点的前一个兄弟节点 + +`@type {IPublicModelNode | null}` + +### nextSibling + +获取当前节点的后一个兄弟节点 + +`@type {IPublicModelNode | null}` + +### parent + +获取当前节点的父亲节点 + +`@type {IPublicModelNode | null}` + +### children + +获取当前节点的孩子节点模型 + +`@type {IPublicModelNodeChildren | null}` + +相关类型:[IPublicModelNodeChildren](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/model/node-children.ts) + +### slots + +节点上挂载的插槽节点们 + +`@type {IPublicModelNode[]}` + +### slotFor + +当前节点为插槽节点时,返回节点对应的属性实例 + +`@type {IPublicModelProp | null}` + +相关类型:[IPublicModelProp](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/model/prop.ts) + +### props + +返回节点的属性集 + +`@type {IPublicModelProps | null}` + +相关类型:[IPublicModelProps](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/model/props.ts) + + +### propsData + +返回节点的属性集值 + +`@type {IPublicTypePropsMap | IPublicTypePropsList | null}` + +相关类型: +- [IPublicTypePropsMap](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/type/props-map.ts) +- [IPublicTypePropsList](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/type/props-list.ts) + +### conditionGroup + +获取条件组 + +`@type {IPublicModelExclusiveGroup | null}` + +相关类型:[IPublicModelExclusiveGroup](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/model/exclusive-group.ts) + +**@since v1.1.0** + +### schema + +获取符合搭建协议 - 节点 schema 结构 + +`@type {IPublicTypeNodeSchema | null}` + +相关类型:[IPublicTypeNodeSchema](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/type/node-schema.ts) + +### settingEntry + +获取对应的 setting entry + +`@type {IPublicModelSettingTopEntry}` + +相关章节:[设置器顶层操作对象](./setting-top-entry) + +相关类型:[IPublicModelSettingTopEntry](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/model/setting-top-entry.ts) + +### visible +当前节点是否可见 + +`@type {boolean}` + +**@since v1.1.0** + +## 方法 + +### getRect + +返回节点的尺寸、位置信息 + +```typescript +/** + * 返回节点的尺寸、位置信息 + * get rect information for this node + */ +getRect(): DOMRect | null; +``` + +### hasSlots + +是否有挂载插槽节点 + +```typescript +/** + * 是否有挂载插槽节点 + * check if current node has slots + */ +hasSlots(): boolean; +``` + +### hasCondition + +是否设定了渲染条件 + +```typescript +/** + * 是否设定了渲染条件 + * check if current node has condition value set + */ +hasCondition(): boolean; +``` + +### hasLoop + +是否设定了循环数据 + +```typescript +/** + * 是否设定了循环数据 + * check if loop is set for this node + */ +hasLoop(): boolean; +``` + +### getProp + +获取指定 path 的属性模型实例 + +```typescript +/** + * 获取指定 path 的属性模型实例 + * get prop by path + * @param path 属性路径,支持 a / a.b / a.0 等格式 + */ +getProp(path: string, createIfNone: boolean): IPublicModelProp | null; +``` + +相关类型:[IPublicModelProp](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/model/prop.ts) + +### getPropValue + +获取指定 path 的属性模型实例值 + +```typescript +/** + * 获取指定 path 的属性模型实例值 + * get prop value by path + * @param path 属性路径,支持 a / a.b / a.0 等格式 + */ +getPropValue(path: string): any; +``` + +### getExtraProp + +获取指定 path 的属性模型实例,注:导出时,不同于普通属性,该属性并不挂载在 props 之下,而是与 props 同级 + +```typescript +/** + * 获取指定 path 的属性模型实例, + * 注:导出时,不同于普通属性,该属性并不挂载在 props 之下,而是与 props 同级 + * + * get extra prop by path, an extra prop means a prop not exists in the `props` + * but as siblint of the `props` + * @param path 属性路径,支持 a / a.b / a.0 等格式 + * @param createIfNone 当没有属性的时候,是否创建一个属性 + */ +getExtraProp(path: string, createIfNone?: boolean): IPublicModelProp | null; +``` + +相关类型:[IPublicModelProp](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/model/prop.ts) + +### getExtraPropValue + +获取指定 path 的属性模型实例,注:导出时,不同于普通属性,该属性并不挂载在 props 之下,而是与 props 同级 + +```typescript +/** + * 获取指定 path 的属性模型实例, + * 注:导出时,不同于普通属性,该属性并不挂载在 props 之下,而是与 props 同级 + * + * get extra prop value by path, an extra prop means a prop not exists in the `props` + * but as siblint of the `props` + * @param path 属性路径,支持 a / a.b / a.0 等格式 + * @returns + */ +getExtraPropValue(path: string): any; +``` + +### setPropValue + +setPropValue(path: string, value: CompositeValue) + +设置指定 path 的属性模型实例值 + +```typescript +/** + * 设置指定 path 的属性模型实例值 + * set value for prop with path + * @param path 属性路径,支持 a / a.b / a.0 等格式 + * @param value 值 + */ +setPropValue(path: string, value: IPublicTypeCompositeValue): void; +``` + +相关类型:[IPublicTypeCompositeValue](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/type/composite-value.ts) + + +### setExtraPropValue + +设置指定 path 的属性模型实例值 + +```typescript +/** + * 设置指定 path 的属性模型实例值 + * set value for extra prop with path + * @param path 属性路径,支持 a / a.b / a.0 等格式 + * @param value 值 + */ +setExtraPropValue(path: string, value: IPublicTypeCompositeValue): void; +``` + +相关类型:[IPublicTypeCompositeValue](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/type/composite-value.ts) + +### importSchema + +导入节点数据 + +```typescript +/** + * 导入节点数据 + * import node schema + * @param data + */ +importSchema(data: IPublicTypeNodeSchema): void; +``` + +相关类型:[IPublicTypeNodeSchema](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/type/node-schema.ts) + +### exportSchema + +导出节点数据 + +```typescript +/** + * 导出节点数据 + * export schema from this node + * @param stage + * @param options + */ +exportSchema(stage: IPublicEnumTransformStage, options?: any): IPublicTypeNodeSchema; +``` + +相关类型: +- [IPublicEnumTransformStage](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/enum/transform-stage.ts) +- [IPublicTypeNodeSchema](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/type/node-schema.ts) + +### insertBefore + +在指定位置之前插入一个节点 + +```typescript +/** + * 在指定位置之前插入一个节点 + * insert a node befor current node + * @param node + * @param ref + * @param useMutator + */ +insertBefore( + node: IPublicModelNode, + ref?: IPublicModelNode | undefined, + useMutator?: boolean, + ): void; +``` + +### insertAfter + +在指定位置之后插入一个节点 + +```typescript +/** + * 在指定位置之后插入一个节点 + * insert a node after this node + * @param node + * @param ref + * @param useMutator + */ +insertAfter( + node: IPublicModelNode, + ref?: IPublicModelNode | undefined, + useMutator?: boolean, + ): void; +``` + +### replaceChild + +替换指定子节点 + +```typescript +/** + * 替换指定子节点 + * replace a child node with data provided + * @param node 待替换的子节点 + * @param data 用作替换的节点对象或者节点描述 + * @returns + */ +replaceChild(node: IPublicModelNode, data: any): IPublicModelNode | null; +``` + +### replaceWith + +将当前节点替换成指定节点描述 + +```typescript +/** + * 将当前节点替换成指定节点描述 + * replace current node with a new node schema + * @param schema + */ +replaceWith(schema: IPublicTypeNodeSchema): any; +``` + +相关类型:[IPublicTypeNodeSchema](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/type/node-schema.ts) + +### select + +选中当前节点实例 + +```typescript +/** + * 选中当前节点实例 + * select current node + */ +select(): void; +``` + +### hover + +设置悬停态 + +```typescript +/** + * 设置悬停态 + * set hover value for current node + * @param flag + */ +hover(flag: boolean): void; +``` + +### lock +设置节点锁定状态 + +```typescript +/** + * 设置节点锁定状态 + * set lock value for current node + * @param flag + * @since v1.0.16 + */ +lock(flag?: boolean): void; +``` + +**@since v1.0.16** + +### remove + +删除当前节点实例 + +```typescript +/** + * 删除当前节点实例 + * remove current node + */ +remove(): void; +``` + +### mergeChildren + +执行新增、删除、排序等操作 + +```typescript +/** + * 执行新增、删除、排序等操作 + * excute remove/add/sort operations on node`s children + * + * @since v1.1.0 + */ +mergeChildren( + remover: (node: IPublicModelNode, idx: number) => boolean, + adder: (children: IPublicModelNode[]) => any, + sorter: (firstNode: IPublicModelNode, secondNode: IPublicModelNode) => number +): any; +``` + +**@since v1.1.0** + +### contains + +当前节点是否包含某子节点 + +```typescript +/** + * 当前节点是否包含某子节点 + * check if current node contains another node as a child + * @param node + * @since v1.1.0 + */ +contains(node: IPublicModelNode): boolean; +``` + +**@since v1.1.0** + +### canPerformAction + +是否可执行某 action + +```typescript +/** + * 是否可执行某 action + * check if current node can perform certain aciton with actionName + * @param actionName action 名字 + * @since v1.1.0 + */ +canPerformAction(actionName: string): boolean; +``` + +**@since v1.1.0** + +### isConditionalVisible + +获取该节点的 ConditionalVisible 值 + +```typescript +/** + * 获取该节点的 ConditionalVisible 值 + * check if current node ConditionalVisible + * @since v1.1.0 + */ +isConditionalVisible(): boolean | undefined; +``` + +**@since v1.1.0** + +### setConditionalVisible +设置该节点的 ConditionalVisible 为 true + +```typescript +/** + * 设置该节点的 ConditionalVisible 为 true + * make this node as conditionalVisible === true + * @since v1.1.0 + */ +setConditionalVisible(): void; +``` + +**@since v1.1.0** + +### getDOMNode +获取节点实例对应的 dom 节点 + +```typescript +/** + * 获取节点实例对应的 dom 节点 + */ +getDOMNode(): HTMLElement; + +``` + +### getRGL + +获取磁贴相关信息 + +```typescript +/** + * 获取磁贴相关信息 + */ +getRGL(): { + isContainerNode: boolean; + isEmptyNode: boolean; + isRGLContainerNode: boolean; + isRGLNode: boolean; + isRGL: boolean; + rglNode: IPublicModelNode | null; +} +``` \ No newline at end of file diff --git a/docs/docs/api/model/plugin-instance.md b/docs/docs/api/model/plugin-instance.md new file mode 100644 index 0000000000..14ce388376 --- /dev/null +++ b/docs/docs/api/model/plugin-instance.md @@ -0,0 +1,40 @@ +--- +title: PluginInstance +sidebar_position: 12 +--- + +> **@types** [IPublicModelPluginInstance](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/model/plugin-instance.ts)
+> **@since** v1.1.0 + + +## 基本介绍 + +插件实例 + +## 属性 + +### pluginName + +插件名字 + +`@type {string}` + +### dep + +插件依赖 + +`@type {string[]}` + +### disabled + +插件是否禁用 + +`@type {boolean}` + +### meta + +插件 meta 信息 + +`@type {IPublicTypePluginMeta}` + +相关类型:[IPublicTypePluginMeta](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/type/plugin-meta.ts) diff --git a/docs/docs/api/model/prop.md b/docs/docs/api/model/prop.md new file mode 100644 index 0000000000..d9b0d14f42 --- /dev/null +++ b/docs/docs/api/model/prop.md @@ -0,0 +1,108 @@ +--- +title: Prop +sidebar_position: 3 +--- +> **@types** [IPublicModelProp](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/model/prop.ts)
+> **@since** v1.0.0 + +## 基本介绍 + +属性模型 + +## 属性 + +### id + +id + +`@type {string}` + +### key + +key 值 + +`@type {string | number | undefined}` + +### path + +返回当前 prop 的路径 + +`@type {string[]}` + +### node + +返回所属的节点实例 + +`@type {IPublicModelNode | null}` + +相关类型:[IPublicModelNode](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/model/node.ts) + +### slotNode + +当本 prop 代表一个 Slot 时,返回对应的 slotNode + +`@type {IPublicModelNode | undefined | null}` + +相关类型:[IPublicModelNode](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/model/node.ts) + + +## 方法 + +### setValue + +设置值 + +```typescript +/** + * 设置值 + * set value for this prop + * @param val + */ +setValue(val: IPublicTypeCompositeValue): void; +``` + +相关类型:[IPublicTypeCompositeValue](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/type/composite-value.ts) + +### getValue + +获取值 + +```typescript +/** + * 获取值 + * get value of this prop + */ +getValue(): any; +``` + +### remove + +移除值 + +```typescript +/** + * 移除值 + * remove value of this prop + * @since v1.0.16 + */ +remove(): void; +``` + +**@since v1.0.16** + +### exportSchema + +导出值 + +```typescript +/** + * 导出值 + * export schema + * @param stage + */ +exportSchema(stage: IPublicEnumTransformStage): IPublicTypeCompositeValue; +``` + +相关类型: +- [IPublicEnumTransformStage](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/enum/transform-stage.ts) +- [IPublicTypeCompositeValue](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/type/composite-value.ts) \ No newline at end of file diff --git a/docs/docs/api/model/props.md b/docs/docs/api/model/props.md new file mode 100644 index 0000000000..9bd6eaa66b --- /dev/null +++ b/docs/docs/api/model/props.md @@ -0,0 +1,160 @@ +--- +title: Props +sidebar_position: 4 +--- +> **@types** [IPublicModelProps](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/model/props.ts)
+> **@since** v1.0.0 + +## 基本介绍 + +属性集模型 + +## 属性 +### id + +id + +`@type {string}` + + +### path + +返回当前 props 的路径 + +`@type {string[]}` + + +### node + +返回当前属性集所属的节点实例 + +`@type {IPublicModelNode | null}` + +相关类型:[IPublicModelNode](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/model/node.ts) + +## 方法 +### getProp + +获取指定 path 的属性模型实例 + +```typescript +/** + * 获取指定 path 的属性模型实例 + * get prop by path + * @param path 属性路径,支持 a / a.b / a.0 等格式 + */ +getProp(path: string): IPublicModelProp | null; +``` + +相关类型:[IPublicModelProp](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/model/prop.ts) + +### getPropValue + +获取指定 path 的属性模型实例值 + +```typescript +/** + * 获取指定 path 的属性模型实例值 + * get value of prop by path + * @param path 属性路径,支持 a / a.b / a.0 等格式 + */ +getPropValue(path: string): any; +``` + +### getExtraProp + +获取指定 path 的属性模型实例,注:导出时,不同于普通属性,该属性并不挂载在 props 之下,而是与 props 同级 + +```typescript +/** + * 获取指定 path 的属性模型实例, + * 注:导出时,不同于普通属性,该属性并不挂载在 props 之下,而是与 props 同级 + * get extra prop by path + * @param path 属性路径,支持 a / a.b / a.0 等格式 + */ +getExtraProp(path: string): IPublicModelProp | null; +``` + +相关类型:[IPublicModelProp](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/model/prop.ts) + +### getExtraPropValue + +获取指定 path 的属性模型实例值,注:导出时,不同于普通属性,该属性并不挂载在 props 之下,而是与 props 同级 + +```typescript +/** + * 获取指定 path 的属性模型实例值 + * 注:导出时,不同于普通属性,该属性并不挂载在 props 之下,而是与 props 同级 + * get value of extra prop by path + * @param path 属性路径,支持 a / a.b / a.0 等格式 + */ +getExtraPropValue(path: string): any; +``` + +### setPropValue + +设置指定 path 的属性模型实例值 + +```typescript +/** + * 设置指定 path 的属性模型实例值 + * set value of prop by path + * @param path 属性路径,支持 a / a.b / a.0 等格式 + * @param value 值 + */ +setPropValue(path: string, value: IPublicTypeCompositeValue): void; +``` + +相关类型:[IPublicTypeCompositeValue](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/type/composite-value.ts) + +### setExtraPropValue + +设置指定 path 的属性模型实例值 + +```typescript +/** + * 设置指定 path 的属性模型实例值 + * set value of extra prop by path + * @param path 属性路径,支持 a / a.b / a.0 等格式 + * @param value 值 + */ +setExtraPropValue(path: string, value: IPublicTypeCompositeValue): void; +``` + +相关类型:[IPublicTypeCompositeValue](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/type/composite-value.ts) + + +### has + +当前 props 是否包含某 prop + +```typescript +/** + * 当前 props 是否包含某 prop + * check if the specified key is existing or not. + * @param key + * @since v1.1.0 + */ +has(key: string): boolean; +``` + +**@since v1.1.0** + +### add + +添加一个 prop + +```typescript +/** + * 添加一个 prop + * add a key with given value + * @param value + * @param key + * @since v1.1.0 + */ +add(value: IPublicTypeCompositeValue, key?: string | number | undefined): any; +``` + +相关类型:[IPublicTypeCompositeValue](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/type/composite-value.ts) + +**@since v1.1.0** \ No newline at end of file diff --git a/docs/docs/api/model/resource.md b/docs/docs/api/model/resource.md new file mode 100644 index 0000000000..a5fdeaf782 --- /dev/null +++ b/docs/docs/api/model/resource.md @@ -0,0 +1,58 @@ +--- +title: Resource +sidebar_position: 13 +--- + +> **[@experimental](./#experimental)**
+> **@types** [IPublicModelResource](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/model/resource.ts)
+> **@since** v1.1.0 + +## 属性 + +### title + +资源标题 + +`@type {string}` + +### id + +资源 id + +`@type {string}` + +### name + +资源名字 + +`@type {string}` + +### type + +资源类型 + +`@type {string}` + +### category + +资源分类 + +`@type {string}` + +### icon + +资源 icon + +`@type {ReactElement}` + +### options + +资源配置信息 + +`@type {Object}` + +### config + +资源配置信息 + +`@type {Object}` \ No newline at end of file diff --git a/docs/docs/api/model/selection.md b/docs/docs/api/model/selection.md new file mode 100644 index 0000000000..9fc2e3a1cc --- /dev/null +++ b/docs/docs/api/model/selection.md @@ -0,0 +1,161 @@ +--- +title: Selection +sidebar_position: 6 +--- +> **@types** [IPublicModelSelection](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/model/selection.ts)
+> **@since** v1.0.0 + +## 基本介绍 + +画布节点选中模型 + +## 属性 +### selected + +返回选中的节点 id + +`@type {string[]}` + +### node +返回选中的节点(如多个节点只返回第一个) + +`@type {IPublicModelNode | null}` + +相关类型:[IPublicModelNode](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/model/node.ts) + +**@since v1.1.0** + +## 方法 +### select + +选中指定节点(覆盖方式) + +```typescript +/** +* 选中指定节点(覆盖方式) +* select node with id, this will override current selection +* @param id +*/ +select(id: string): void; +``` + +### selectAll + +批量选中指定节点们 + +```typescript +/** +* 批量选中指定节点们 +* select node with ids, this will override current selection +* +* @param ids +*/ +selectAll(ids: string[]): void; +``` + +### remove + +**取消选中**选中的指定节点,不会删除组件 + +```typescript +/** +* 移除选中的指定节点 +* remove node from selection with node id +* @param id +*/ +remove(id: string): void; +``` + +### clear + +**取消选中**所有选中节点,不会删除组件 + +```typescript +/** +* 清除所有选中节点 +* clear current selection +*/ +clear(): void; +``` + +### has + +判断是否选中了指定节点 + +```typescript +/** +* 判断是否选中了指定节点 +* check if node with specific id is selected +* @param id +*/ +has(id: string): boolean; +``` + +### add + +选中指定节点(增量方式) + +```typescript +/** +* 选中指定节点(增量方式) +* add node with specific id to selection +* @param id +*/ +add(id: string): void; +``` + +### getNodes + +获取选中的节点实例 + +```typescript +/** +* 获取选中的节点实例 +* get selected nodes +*/ +getNodes(): IPublicModelNode[]; +``` + +相关类型:[IPublicModelNode](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/model/node.ts) + +### getTopNodes +获取选区的顶层节点 +例如选中的节点为: + +- DivA + - ChildrenA +- DivB + +getNodes 返回的是 [DivA、ChildrenA、DivB],getTopNodes 返回的是 [DivA、DivB],其中 ChildrenA 由于是二层节点,getTopNodes 不会返回 + +```typescript +/** +* 获取选区的顶层节点 +* get seleted top nodes +* for example: +* getNodes() returns [A, subA, B], then +* getTopNodes() will return [A, B], subA will be removed +* @since v1.0.16 +*/ +getTopNodes(includeRoot?: boolean): IPublicModelNode[]; +``` + +**@since v1.0.16** + +## 事件 +### onSelectionChange + +注册 selection 变化事件回调 + +```typescript +/** +* 注册 selection 变化事件回调 +* set callback which will be called when selection is changed +* @since v1.1.0 +*/ +onSelectionChange(fn: (ids: string[]) => void): IPublicTypeDisposable; +``` + +相关类型:[IPublicTypeDisposable](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/type/disposable.ts) + +**@since v1.1.0** \ No newline at end of file diff --git a/docs/docs/api/model/setting-field.md b/docs/docs/api/model/setting-field.md new file mode 100644 index 0000000000..226a0c7e5b --- /dev/null +++ b/docs/docs/api/model/setting-field.md @@ -0,0 +1,342 @@ +--- +title: SettingField +sidebar_position: 6 +--- +> **@types** [IPublicModelSettingField](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/model/setting-field.ts)
+ +## 基本介绍 + +setter 设置器操作对象 + +## 属性 + +#### isGroup + +获取设置属性的 isGroup + +`@type {boolean}` + + +#### id + +获取设置属性的 id + +`@type {string}` + +#### name + +获取设置属性的 name + +`@type {string | number | undefined}` + +#### key + +获取设置属性的 key + +`@type {string | number | undefined}` + +#### path + +获取设置属性的 path + +`@type {(string | number)[]}` + +#### title + +获取设置属性的 title + +`@type {string}` + +#### setter + +获取设置属性的 setter + +`@type {IPublicTypeSetterType | null}` + +#### expanded + +获取设置属性的 expanded + +`@type {boolean}` + +#### extraProps + +获取设置属性的 extraProps + +`@type {IPublicTypeFieldExtraProps}` + +#### props + +`@type {IPublicModelSettingTopEntry}` + +相关章节:[设置器顶层操作对象](./setting-top-entry) + +相关类型:[IPublicModelSettingTopEntry](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/model/setting-top-entry.ts) + +#### node + +获取设置属性对应的节点实例 + +`@type {IPublicModelNode | null}` + + +#### parent + +获取设置属性的父设置属性 + +`@type {IPublicModelSettingTopEntry | IPublicModelSettingField}` + +相关章节:[设置器顶层操作对象](./setting-top-entry) + +相关类型:[IPublicModelSettingTopEntry](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/model/setting-top-entry.ts) + +#### top + +获取顶级设置属性 + +`@type {IPublicModelSettingTopEntry}` + +相关章节:[设置器顶层操作对象](./setting-top-entry) + +相关类型:[IPublicModelSettingTopEntry](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/model/setting-top-entry.ts) + +#### isSettingField + +是否是 SettingField 实例 + +`@type {boolean}` + +#### componentMeta + +`@type {IPublicModelComponentMeta}` + +相关类型:[IPublicModelComponentMeta](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/model/component-meta.ts) + +#### items + +获取设置属性的 items + +`@type {Array}` + +相关类型:[IPublicTypeCustomView](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/type/custom-view.ts) + +## 方法 + +#### setKey + +设置 key 值 + +``` +/** + * 设置 key 值 + * @param key + */ +setKey(key: string | number): void; +``` + +#### setValue + +设置值 + +``` +/** + * 设置值 + * @param val 值 + */ +setValue(val: IPublicTypeCompositeValue, extraOptions?: IPublicTypeSetValueOptions): void; +``` + +相关类型: +- [IPublicTypeCompositeValue](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/type/composite-value.ts) +- [IPublicTypeSetValueOptions](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/type/set-value-options.ts) + +#### setPropValue + +设置子级属性值 + +``` +/** + * 设置子级属性值 + * @param propName 子属性名 + * @param value 值 + */ +setPropValue(propName: string | number, value: any): void; +``` + +#### clearPropValue + +清空指定属性值 + +``` +/** + * 清空指定属性值 + * @param propName + */ +clearPropValue(propName: string | number): void; +``` + +#### getDefaultValue + +获取配置的默认值 + +``` +/** + * 获取配置的默认值 + * @returns + */ +getDefaultValue(): any; +``` + +#### getValue + +获取值 + +``` +/** + * 获取值 + * @returns + */ +getValue(): any; +``` + +#### getPropValue + +获取子级属性值 + +``` +/** + * 获取子级属性值 + * @param propName 子属性名 + * @returns + */ +getPropValue(propName: string | number): any; +``` + +#### getExtraPropValue + +获取顶层附属属性值 + +``` +/** + * 获取顶层附属属性值 + */ +getExtraPropValue(propName: string): any; +``` + +#### setExtraPropValue + +设置顶层附属属性值 + +``` +/** + * 设置顶层附属属性值 + */ +setExtraPropValue(propName: string, value: any): void; +``` + +#### getProps + +获取设置属性集 + +``` +/** + * 获取设置属性集 + * @returns + */ +getProps(): IPublicModelSettingTopEntry; +``` + +相关章节:[设置器顶层操作对象](./setting-top-entry) + +相关类型:[IPublicModelSettingTopEntry](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/model/setting-top-entry.ts) + +#### isUseVariable + +是否绑定了变量 + +``` +/** + * 是否绑定了变量 + * @returns + */ +isUseVariable(): boolean; +``` + +#### setUseVariable + +设置绑定变量 + +``` +/** + * 设置绑定变量 + * @param flag + */ +setUseVariable(flag: boolean): void; +``` + +#### createField + +创建一个设置 field 实例 + +``` +/** + * 创建一个设置 field 实例 + * @param config + * @returns + */ +createField(config: IPublicTypeFieldConfig): IPublicModelSettingField; +``` + +相关类型:[IPublicTypeFieldConfig](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/type/field-config.ts) + +#### getMockOrValue + +获取值,当为变量时,返回 mock + +``` +/** + * 获取值,当为变量时,返回 mock + * @returns + */ +getMockOrValue(): any; + +``` + +#### purge + +销毁当前 field 实例 + +``` +/** + * 销毁当前 field 实例 + */ +purge(): void; +``` + +#### remove + +移除当前 field 实例 + +``` +/** + * 移除当前 field 实例 + */ +remove(): void; +``` + +## 事件 + +#### onEffect + +设置 autorun + +``` +/** + * 设置 autorun + * @param action + * @returns + */ +onEffect(action: () => void): IPublicTypeDisposable; +``` + +相关类型:[IPublicTypeDisposable](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/type/disposable.ts) \ No newline at end of file diff --git a/docs/docs/api/model/setting-top-entry.md b/docs/docs/api/model/setting-top-entry.md new file mode 100644 index 0000000000..2e2cad52be --- /dev/null +++ b/docs/docs/api/model/setting-top-entry.md @@ -0,0 +1,74 @@ +--- +title: SettingTopEntry +sidebar_position: 6 +--- +> **@types** [IPublicModelSettingTopEntry](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/model/setting-top-entry.ts)
+ +## 基本介绍 + +setter 设置器顶层操作对象 + +## 属性 + +#### node + +返回所属的节点实例 + +`@type {IPublicModelNode | null}` + +## 方法 + +#### get + +获取子级属性对象 + +``` +/** + * 获取子级属性对象 + * @param propName + * @returns + */ +get(propName: string | number): IPublicModelSettingField | null; +``` +相关章节:[设置器操作对象](./setting-field) + +相关类型:[IPublicModelSettingField](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/model/setting-field.ts) + + +#### getPropValue + +获取指定 propName 的值 + +``` +/** + * 获取指定 propName 的值 + * @param propName + * @returns + */ +getPropValue(propName: string | number): any; +``` + +#### setPropValue + +设置指定 propName 的值 + +``` +/** + * 设置指定 propName 的值 + * @param propName + * @param value + */ +setPropValue(propName: string | number, value: any): void; +``` + +#### clearPropValue + +清除指定 propName 的值 + +``` +/** + * 清除指定 propName 的值 + * @param propName + */ +clearPropValue(propName: string | number): void; +``` \ No newline at end of file diff --git a/docs/docs/api/model/simulatorRender.md b/docs/docs/api/model/simulatorRender.md new file mode 100644 index 0000000000..f5bacec493 --- /dev/null +++ b/docs/docs/api/model/simulatorRender.md @@ -0,0 +1,38 @@ +--- +title: SimulatorRender +sidebar_position: 6 +--- +> **@types** [IPublicModelSimulatorRender](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/model/simulator-render.ts)
+> **@since** v1.0.0 + +## 基本介绍 + +画布节点选中模型 + +## 属性 +### components + +画布组件列表 + +```typescript +/** + * 画布组件列表 + */ +components: { + [key: string]: any; +} +``` + +## 方法 + +### rerender + +触发画布重新渲染 + +```typescript +/** + * 触发画布重新渲染 + */ +rerender: () => void; +``` + diff --git a/docs/docs/api/model/window.md b/docs/docs/api/model/window.md new file mode 100644 index 0000000000..9db39996fa --- /dev/null +++ b/docs/docs/api/model/window.md @@ -0,0 +1,107 @@ +--- +title: Window +sidebar_position: 12 +--- + +> **[@experimental](./#experimental)**
+> **@types** [IPublicModelWindow](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/model/window.ts)
+> **@since** v1.1.0 + + +## 基本介绍 + +低代码设计器窗口模型 + +## 属性 + +### id + +窗口唯一 id + +`@type {string}` + +### title + +窗口标题 + +`@type {string}` + +### icon + +`@type {ReactElement}` + +### resource + +窗口对应资源 + +`@type {IPublicModelResource}` + +关联模型 [IPublicModelResource](./resource) + +### currentEditorView +窗口当前视图 + +`@type {IPublicModelEditorView}` + +关联模型 [IPublicModelEditorView](./editor-view) + +**@since v1.1.7** + +### editorViews + +窗口所有视图 + +`@type {IPublicModelEditorView[]}` + +关联模型 [IPublicModelEditorView](./editor-view) + +**@since v1.1.7** + +## 方法 + +### importSchema +当前窗口导入 schema, 会调用当前窗口对应资源的 import 钩子 + +```typescript +function importSchema(schema: IPublicTypeNodeSchema): void +``` + +相关类型:[IPublicTypeNodeSchema](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/type/node-schema.ts) + +### changeViewType +修改当前窗口视图类型 + +```typescript +function changeViewType(viewName: string): void +``` + +### save +当前窗口的保存方法,会调用当前窗口对应资源的 save 钩子 + +```typescript +function save(): Promise(void) +``` + +## 事件 + +### onChangeViewType + +窗口视图变更事件 + +``` +onChangeViewType(fn: (viewName: string) => void): IPublicTypeDisposable; +``` + +相关类型:[IPublicTypeDisposable](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/type/disposable.ts) + +### onSave + +窗口视图保存事件 + +``` +onSave(fn: () => void): IPublicTypeDisposable; +``` + +相关类型:[IPublicTypeDisposable](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/type/disposable.ts) + +**@since v1.1.7** diff --git a/docs/docs/api/plugins.md b/docs/docs/api/plugins.md index f225386fc2..df025f49e9 100644 --- a/docs/docs/api/plugins.md +++ b/docs/docs/api/plugins.md @@ -1,33 +1,36 @@ --- title: plugins - 插件 API -sidebar_position: 4 +sidebar_position: 2 --- +> **@types** [IPublicApiPlugins](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/api/plugins.ts)
+> **@since** v1.0.0 + ## 模块简介 插件管理器,提供编排模块中管理插件的能力。 -## 变量(variables) -无 -## 方法签名(functions) + +## 方法 ### register 注册插件 -#### 类型定义 ```typescript async function register( - pluginConfigCreator: (ctx: ILowCodePluginContext) => ILowCodePluginConfig, - options?: ILowCodeRegisterOptions, + plugin: IPublicTypePlugin, + options?: IPublicTypePluginRegisterOptions, ): Promise ``` -pluginConfigCreator 是一个 ILowCodePluginConfig 生成函数,ILowCodePluginConfig 中包含了该插件的 init / destroy 等钩子函数,以及 exports 函数用于返回插件对外暴露的值。 +相关 types: +- [IPublicTypePlugin](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/type/plugin.ts) +- [IPublicTypePluginRegisterOptions](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/type/plugin-register-options.ts) -另外,pluginConfigCreator 还必须挂载 pluginName 字段,全局确保唯一,否则 register 时会报错,可以选择性挂载 meta 字段,用于描述插件的元数据信息,比如兼容的引擎版本、支持的参数配置、依赖插件声明等。 -> 注:pluginConfigCreator 挂载 pluginName / meta 可以通过低代码工具链的插件脚手架生成,写如 package.json 后将会自动注入到代码中,具体见 [插件元数据工程化示例](#RO9YY) +其中第一个参数 plugin 通过低代码工具链的插件脚手架生成编写模板,开发者可以参考[这个章节](/site/docs/guide/expand/editor/cli)进行创建 #### 简单示例 ```typescript import { plugins } from '@alilc/lowcode-engine'; +import { IPublicModelPluginContext } from '@alilc/lowcode-types'; -const builtinPluginRegistry = (ctx: ILowCodePluginContext) => { +const builtinPluginRegistry = (ctx: IPublicModelPluginContext) => { return { async init() { const { skeleton } = ctx; @@ -58,70 +61,75 @@ await plugins.register(builtinPluginRegistry); #### 使用 exports 示例 ```typescript import { plugins } from '@alilc/lowcode-engine'; +import { IPublicModelPluginContext } from '@alilc/lowcode-types'; -const pluginA = (ctx: ILowCodePluginContext) => { +const PluginA = (ctx: IPublicModelPluginContext) => { return { async init() {}, exports() { return { x: 1, } }, }; } -pluginA.pluginName = 'pluginA'; +PluginA.pluginName = 'PluginA'; -const pluginB = (ctx: ILowCodePluginContext) => { +const PluginB = (ctx: IPublicModelPluginContext) => { return { async init() { // 获取 pluginA 的导出值 - console.log(ctx.plugins.pluginA.x); // => 1 + console.log(ctx.plugins.PluginA.x); // => 1 }, }; } -pluginA.pluginName = 'pluginA'; -pluginB.pluginName = 'pluginB'; -pluginB.meta = { - dependencies: ['pluginA'], +PluginA.pluginName = 'pluginA'; +PluginB.pluginName = 'PluginB'; +PluginB.meta = { + dependencies: ['PluginA'], } -await plugins.register(pluginA); -await plugins.register(pluginB); +await plugins.register(PluginA); +await plugins.register(PluginB); ``` -> 注:ctx 是在插件 creator 中获取引擎 API 的上下文,具体定义参见 [ILowCodePluginContext](#qEhTb) +> 注:ctx 是在插件中获取引擎 API 的唯一渠道,具体定义参见 [IPublicModelPluginContext](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/model/plugin-context.ts) + -#### #### 设置兼容引擎版本示例 ```typescript import { plugins } from '@alilc/lowcode-engine'; +import { IPublicModelPluginContext } from '@alilc/lowcode-types'; -const builtinPluginRegistry = (ctx: ILowCodePluginContext) => { +const BuiltinPluginRegistry = (ctx: IPublicModelPluginContext) => { return { async init() { ... }, }; } -builtinPluginRegistry.pluginName = 'builtinPluginRegistry'; -builtinPluginRegistry.meta = { +BuiltinPluginRegistry.pluginName = 'BuiltinPluginRegistry'; +BuiltinPluginRegistry.meta = { engines: { lowcodeEngine: '^1.0.0', // 插件需要配合 ^1.0.0 的引擎才可运行 }, } -await plugins.register(builtinPluginRegistry); +await plugins.register(BuiltinPluginRegistry); ``` #### 设置插件参数版本示例 ```typescript import { plugins } from '@alilc/lowcode-engine'; +import { IPublicModelPluginContext } from '@alilc/lowcode-types'; -const builtinPluginRegistry = (ctx: ILowCodePluginContext, options: any) => { +const BuiltinPluginRegistry = (ctx: IPublicModelPluginContext, options: any) => { return { async init() { - // 1.0.4 之后的传值方式,通过 register(xxx, options) - // 取值通过 options + // 直接传值方式: + // 通过 register(xxx, options) 传入 + // 通过 options 取出 - // 1.0.4 之前的传值方式,通过 init(..., preference) - // 取值通过 ctx.preference.getValue() + // 引擎初始化时也可以设置某插件的全局配置项: + // 通过 engine.init(..., preference) 传入 + // 通过 ctx.preference.getValue() 取出 }, }; } -builtinPluginRegistry.pluginName = 'builtinPluginRegistry'; -builtinPluginRegistry.meta = { +BuiltinPluginRegistry.pluginName = 'BuiltinPluginRegistry'; +BuiltinPluginRegistry.meta = { preferenceDeclaration: { title: 'pluginA 的参数定义', properties: [ @@ -149,102 +157,81 @@ builtinPluginRegistry.meta = { }, } -// 从 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); - +await plugins.register(BuiltinPluginRegistry, { key1: 'abc', key5: 'willNotPassToPlugin' }); ``` ### get -获取插件实例 -**类型定义** +获取指定插件 + ```typescript -function get(pluginName: string): ILowCodePlugin | undefined +/** + * 获取指定插件 + * get plugin instance by name + */ +get(pluginName: string): IPublicModelPluginInstance | null; ``` -**调用示例** -```typescript -import { plugins } from '@alilc/lowcode-engine'; -plugins.get(builtinPluginRegistry); -``` -### +关联模型 [IPublicModelPluginInstance](./model/plugin-instance) + ### getAll -获取所有插件实例 -**类型定义** +获取所有的插件实例 + ```typescript -function getAll(): ILowCodePlugin[] +/** + * 获取所有的插件实例 + * get all plugin instances + */ +getAll(): IPublicModelPluginInstance[]; ``` -**调用示例** -```typescript -import { plugins } from '@alilc/lowcode-engine'; -plugins.getAll(); -``` -### +关联模型 [IPublicModelPluginInstance](./model/plugin-instance) + ### has -判断是否已经加载了指定插件 -**类型定义** + +判断是否有指定插件 + ```typescript -function has(pluginName: string): boolean +/** + * 判断是否有指定插件 + * check if plugin with certain name exists + */ +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 - setters: Setters; // 参考设置器 API - config: EngineConfig; // 参考配置 API - material: Material; // 参考物料 API - event: Event; // 参考事件 API - project: Project; // 参考模型 API - common: Common; // 参考模型 API - logger: Logger; // 参考日志 API - plugins: ILowCodePluginManager; // 即本文档描述内容 - preference: IPluginPreferenceMananger; -} +/** + * 删除指定插件 + * delete plugin instance by name + */ +delete(pluginName: string): void; ``` -### ILowCodePluginConfig -**类型定义** + +### getPluginPreference + +引擎初始化时可以提供全局配置给到各插件,通过这个方法可以获得本插件对应的配置 + ```typescript -export interface ILowCodePluginConfig { - init?(): void; - destroy?(): void; - exports?(): any; -} +/** + * 引擎初始化时可以提供全局配置给到各插件,通过这个方法可以获得本插件对应的配置 + * use this to get preference config for this plugin when engine.init() called + */ +getPluginPreference( + pluginName: string, + ): Record | null | undefined; ``` + +## 相关类型定义 + +- [IPublicModelPluginContext](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/model/plugin-context.ts) +- [IPublicTypePluginConfig](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/type/plugin-config.ts) +- [IPublicModelPluginInstance](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/model/plugin-instance.ts) + ## 插件元数据工程转化示例 your-plugin/package.json ```json @@ -262,8 +249,8 @@ your-plugin/package.json } ``` 转换后的结构: -```json -const debug = (ctx: ILowCodePluginContext, options: any) => { +```typescript +const debug = (ctx: IPublicModelPluginContext, options: any) => { return {}; } @@ -275,8 +262,3 @@ debug.meta = { 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 index 7c58968526..54bd1474cf 100644 --- a/docs/docs/api/project.md +++ b/docs/docs/api/project.md @@ -1,881 +1,333 @@ --- title: project - 模型 API -sidebar_position: 3 +sidebar_position: 10 --- -# 模块简介 -引擎编排模块中包含多种模型,包括[项目模型(project)](#DADnF)、[文档模型(document-model)](#lp7xO)、[节点模型(node)](#m0cJS)、[节点孩子模型(node-children)](#W8seq)、[属性集模型(props)](#IJeRY)以及[属性模型(prop)](#w1diM)。 +## 模块简介 + +引擎编排模块中包含多种模型,包括: +- [文档模型 DocumentModel](./model/document-model) +- [节点模型 Node](./model/node) +- [节点孩子模型 NodeChildren](./model/node-children) +- [属性模型 Prop](./model/prop) +- [属性集模型 Props](./model/props) + 他们的依赖关系如下图: ![image.png](https://img.alicdn.com/imgextra/i3/O1CN01B1bAZi1asNU3KaSUJ_!!6000000003385-2-tps-1650-1352.png) -在文档模型内部,又有一些引申模型,比如[历史操作(history)](#xvIKj)、[画布节点选中(selection)](#GtFkP)、[画布节点悬停(detecting)](#Tjt05)等。 -整个模型系统,以项目模型为最顶层的模型,其他模型实例均需要通过 project 来获得,比如 project.currentDocument 来获取当前的文档模型,project.currentDocument.nodesMap 来获取当前文档模型里所有的节点列表。 +在文档模型内部,又有一些引申模型,比如: +- [历史操作 History)](./model/history) +- [画布节点选中 Selection)](./model/selection) +- [画布节点悬停 Detecting)](./model/detecting) +- [模态节点管理器 ModalNodesManager](./model/modal-nodes-manager) + +整个模型系统,以 project API 为入口,所有模型实例均需要通过 project 来获得,比如 project.currentDocument 来获取当前的文档模型,project.currentDocument.nodesMap 来获取当前文档模型里所有的节点列表。 + +下面来看看 project API 的具体介绍 -# 项目模型(Project) -## 变量(variables) +## 变量 ### currentDocument 获取当前的 document 实例 + +```typescript +/** + * 获取当前的 document + * get current document + */ +get currentDocument(): IPublicModelDocumentModel | null; +``` + +相关类型:[IPublicModelDocumentModel](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/model/document-model.ts) + ### documents 获取当前 project 下所有 documents + +```typescript +/** + * 获取当前 project 下所有 documents + * get all documents of this project + * @returns + */ +get documents(): IPublicModelDocumentModel[]; +``` + +相关类型:[IPublicModelDocumentModel](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/model/document-model.ts) + ### simulatorHost 获取模拟器的 host -## -## 方法签名(functions) -### openDocument -openDocument(doc?: string | RootSchema | undefined) +```typescript +/** + * 获取模拟器的 host + * get simulator host + */ +get simulatorHost(): IPublicApiSimulatorHost | null; +``` + +相关类型:[IPublicApiSimulatorHost](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/api/simulator-host.ts) + + +## 方法 +### openDocument 打开一个 document -### createDocument +```typescript +/** + * 打开一个 document + * @param doc + * @returns + */ +openDocument(doc?: string | IPublicTypeRootSchema | undefined): IPublicModelDocumentModel | null; +``` + +相关类型: +- [IPublicApiSimulatorHost](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/api/simulator-host.ts) +- [IPublicTypeRootSchema](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/type/root-schema.ts) -createDocument(data?: RootSchema): DocumentModel | null +### createDocument 创建一个 document -### -### removeDocument -removeDocument(doc: DocumentModel) +```typescript +/** + * 创建一个 document + * create a document + * @param data + * @returns + */ +createDocument(data?: IPublicTypeRootSchema): IPublicModelDocumentModel | null; +``` + +相关类型: +- [IPublicApiSimulatorHost](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/api/simulator-host.ts) +- [IPublicTypeRootSchema](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/type/root-schema.ts) + +### removeDocument 删除一个 document -### getDocumentByFileName +```typescript +/** + * 删除一个 document + * remove a document + * @param doc + */ +removeDocument(doc: IPublicModelDocumentModel): void; +``` + +相关类型:[IPublicApiSimulatorHost](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/api/simulator-host.ts) -getDocumentByFileName(fileName: string): DocumentModel | null +### getDocumentByFileName 根据 fileName 获取 document +```typescript +/** + * 根据 fileName 获取 document + * get a document by filename + * @param fileName + * @returns + */ +getDocumentByFileName(fileName: string): IPublicModelDocumentModel | null; +``` -### getDocumentById +相关类型:[IPublicApiSimulatorHost](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/api/simulator-host.ts) -getDocumentById(id: string): DocumentModel | null +### getDocumentById 根据 id 获取 document -### exportSchema +```typescript +/** + * 根据 id 获取 document + * get a document by id + * @param id + * @returns + */ +getDocumentById(id: string): IPublicModelDocumentModel | null; +``` -exportSchema() +相关类型:[IPublicApiSimulatorHost](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/api/simulator-host.ts) -导出 project +### exportSchema -### importSchema +导出 project schema -importSchema(schema?: ProjectSchema) +```typescript +/** + * 导出 project + * export project to schema + * @returns + */ +exportSchema(stage: IPublicEnumTransformStage): IPublicTypeProjectSchema; +``` -导入 project +相关类型: +- [IPublicEnumTransformStage](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/enum/transform-stage.ts) +- [IPublicTypeProjectSchema](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/type/project-schema.ts) -### getCurrentDocument +### importSchema -getCurrentDocument(): DocumentModel | null +导入 project -获取当前的 document +```typescript +/** + * 导入 project schema + * import schema to project + * @param schema 待导入的 project 数据 + */ +importSchema(schema?: IPublicTypeProjectSchema): void; +``` +相关类型:[IPublicTypeProjectSchema](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/type/project-schema.ts) ### addPropsTransducer - -addPropsTransducer(transducer: PropsTransducer, stage: TransformStage) - 增加一个属性的管道处理函数 -**示例 1:在保存的时候删除每一个组件的 props.hidden** ```typescript -import { ILowCodePluginContext, project } from '@alilc/lowcode-engine'; -import { CompositeObject, TransformStage } from '@alilc/lowcode-types'; +/** + * 增加一个属性的管道处理函数 + * add a transducer to process prop + * @param transducer + * @param stage + */ +addPropsTransducer( + transducer: IPublicTypePropsTransducer, + stage: IPublicEnumTransformStage, + ): void; +``` +相关类型: +- [IPublicTypePropsTransducer](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/type/props-transducer.ts) +- [IPublicEnumTransformStage](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/enum/transform-stage.ts) + +**示例** +在保存的时候删除每一个组件的 props.hidden +```typescript +import { project } from '@alilc/lowcode-engine'; +import { IPublicTypeCompositeObject, IPublicEnumTransformStage, IPublicModelPluginContext } from '@alilc/lowcode-types'; -export const deleteHiddenTransducer = (ctx: ILowCodePluginContext) => { +export const DeleteHiddenTransducer = (ctx: IPublicModelPluginContext) => { return { - name: 'deleteHiddenTransducer', async init() { - project.addPropsTransducer((props: CompositeObject): CompositeObject => { + const { project } = ctx; + project.addPropsTransducer((props: IPublicTypeCompositeObject): IPublicTypeCompositeObject => { delete props.hidden; return props; - }, TransformStage.Save); + }, IPublicEnumTransformStage.Save); }, }; } -deleteHiddenTransducer.pluginName = 'deleteHiddenTransducer'; +DeleteHiddenTransducer.pluginName = 'DeleteHiddenTransducer'; ``` -### onRemoveDocument -绑定删除文档事件 -```typescript -function onRemoveDocument(fn: (data: { docId: string}) => void) {} -``` -*引擎版本>=1.0.16 ### setI18n 设置多语言语料 + ```typescript -function setI18n(value: object) {} +/** + * 设置多语言语料 + * 数据格式参考 https://github.com/alibaba/lowcode-engine/blob/main/specs/lowcode-spec.md#2434%E5%9B%BD%E9%99%85%E5%8C%96%E5%A4%9A%E8%AF%AD%E8%A8%80%E7%B1%BB%E5%9E%8Baa + * + * set I18n data for this project + * @param value object + * @since v1.0.17 + */ +setI18n(value: object): void; ``` -*引擎版本>=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, - ) +**@since v1.0.17** -插入节点 -### createNode +### setConfig +设置当前项目配置 -createNode(data: any) - -创建一个节点 -### removeNode - -removeNode(idOrNode: string | Node) - -移除指定节点/节点id - -### checkNesting -检查拖拽放置的目标节点是否可以放置该拖拽对象 -*引擎版本 > 1.0.16 ```typescript -function checkNesting(dropTarget: Node, dragObject: DragNodeObject | DragNodeDataObject): boolean {} +/** + * 设置当前项目配置 + * set config for this project + * @param value object + * @since v1.1.4 + */ + setConfig(value: IPublicTypeAppConfig): void; + setConfig(key: T, value: IPublicTypeAppConfig[T]): void; ``` -## -## 事件(events) -### onAddNode -onAddNode(fn: (node: Node) => void) +**@since v1.1.4** -当前 document 新增节点事件 +#### 如何扩展项目配置 ```typescript -import { project } from '@alilc/lowcode-engine'; +// shims.d.ts +declare module '@alilc/lowcode-types' { + export interface IPublicTypeAppConfig { + customProp: CustomPropType + } +} -project.currentDocument.onAddNode((node) => { - console.log('node', node); -}) +export {}; ``` -### 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?: IPublicOnChangeOptions) => void) - -当前 document 的节点 children 变更事件 - -### onChangeNodeProp -当前 document 节点属性修改事件 -```typescript -onChangeNodeProp(fn: (info: PropChangeOptions) => void) -``` +### onRemoveDocument +绑定删除文档事件 -### onImportSchema -当前 document 导入新的 schema 事件 -版本 >= 1.0.15 ```typescript -onImportSchema(fn: (schema: any) => void) +/** + * 绑定删除文档事件 + * set callback for event onDocumentRemoved + * @param fn + * @since v1.0.16 + */ +onRemoveDocument(fn: (data: { id: string }) => void): IPublicTypeDisposable; ``` +相关类型:[IPublicTypeDisposable](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/type/disposable.ts) -# 画布节点选中模型(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 -是否为叶子节点 +**@since v1.0.16** -### 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) +### onChangeDocument -设置悬停态 +当前 project 内的 document 变更事件 -### lock -设置节点锁定状态 ```typescript -function lock(flag?: boolean){} +/** + * 当前 project 内的 document 变更事件 + * set callback for event onDocumentChanged + */ +onChangeDocument(fn: (doc: IPublicModelDocumentModel) => void): IPublicTypeDisposable; ``` -*引擎版本>=1.0.16 - -### remove - -remove() - -删除当前节点实例 - -# 节点孩子模型(NodeChildren) -## 变量(variables) -### owner - -返回当前 children 实例所属的节点实例 - -### size - -children 内的节点实例数 - -### isEmpty - -是否为空 - -## 方法签名(functions) -### delete - -delete(node: Node) - -删除指定节点 - -### insert - -insert(node: Node, at?: number | null) -插入一个节点 +相关类型: +- [IPublicModelDocumentModel](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/model/document-model.ts) +- [IPublicTypeDisposable](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/type/disposable.ts) -### 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) - -设置指定节点为可见态 +### onSimulatorHostReady -### setInvisible +当前 project 的模拟器 ready 事件 -setInvisible(node: Node) +```typescript +/** + * 当前 project 的模拟器 ready 事件 + * set callback for event onSimulatorHostReady + */ +onSimulatorHostReady(fn: (host: IPublicApiSimulatorHost) => void): IPublicTypeDisposable; +``` +相关类型: +- [IPublicApiSimulatorHost](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/api/simulator-host.ts) +- [IPublicTypeDisposable](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/type/disposable.ts) -设置指定节点为不可见态 +### onSimulatorRendererReady -### setNodes +当前 project 的渲染器 ready 事件 -setNodes() +```typescript +/** + * 当前 project 的渲染器 ready 事件 + * set callback for event onSimulatorRendererReady + */ +onSimulatorRendererReady(fn: () => void): IPublicTypeDisposable; +``` -设置模态节点,触发内部事件 +相关类型:[IPublicTypeDisposable](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/type/disposable.ts) diff --git a/docs/docs/api/setters.md b/docs/docs/api/setters.md index 41c992e16d..0d3435b3d3 100644 --- a/docs/docs/api/setters.md +++ b/docs/docs/api/setters.md @@ -1,216 +1,73 @@ --- title: setters - 设置器 API -sidebar_position: 6 +sidebar_position: 10 --- -## 模块简介 -负责注册设置器、管理设置器的 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); - } - } +> **@types** [IPublicApiSetters](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/api/setters.ts)
+> **@since** v1.0.0 - // 声明 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; +/** + * 获取指定 setter + * get setter by type + * @param type + * @returns + */ +getSetter(type: string): IPublicTypeRegisteredSetter | null; ``` +相关类型:[IPublicTypeRegisteredSetter](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/type/registerd-setter.ts) ### getSettersMap 获取已注册的所有 settersMap -**类型定义** ```typescript -function getSettersMap(): Map +/** + * 获取已注册的所有 settersMap + * get map of all registered setters + * @returns + */ +getSettersMap(): Map; ``` +相关类型:[IPublicTypeRegisteredSetter](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/type/registerd-setter.ts) + ### registerSetter 注册一个 setter -**类型定义** ```typescript -function registerSetter( - typeOrMaps: string | { [key: string]: CustomView | RegisteredSetter }, - setter?: CustomView | RegisteredSetter | undefined, +/** + * 注册一个 setter + * register a setter + * @param typeOrMaps + * @param setter + * @returns + */ +registerSetter( + typeOrMaps: string | { [key: string]: IPublicTypeCustomView | IPublicTypeRegisteredSetter }, + setter?: IPublicTypeCustomView | IPublicTypeRegisteredSetter | undefined ): void; ``` +相关类型: +- [IPublicTypeRegisteredSetter](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/type/registerd-setter.ts) +- [IPublicTypeCustomView](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/type/custom-view.ts) + ## 使用示例 ### 注册官方内置 Setter 到设计器中 ```typescript import { setters, skeleton } from '@alilc/lowcode-engine'; import { setterMap, pluginMap } from '@alilc/lowcode-engine-ext'; +import { IPublicModelPluginContext } from '@alilc/lowcode-types'; -const setterRegistry = (ctx: ILowCodePluginContext) => { +const SetterRegistry = (ctx: IPublicModelPluginContext) => { return { name: 'ext-setters-registry', async init() { @@ -238,8 +95,8 @@ const setterRegistry = (ctx: ILowCodePluginContext) => { }; } -setterRegistry.pluginName = 'setterRegistry'; -await plugins.register(setterRegistry); +SetterRegistry.pluginName = 'SetterRegistry'; +await plugins.register(SetterRegistry); ``` ### 开发自定义 Setter @@ -282,10 +139,13 @@ export default class AltStringSetter extends React.PureComponent **@types** [IPublicApiSimulatorHost](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/api/simulator-host.ts)
+> **@since** v1.0.0 + +## 模块简介 负责模拟器相关的 API,包括画布尺寸、语言等。 -# 方法(functions) -## set +## 方法 +### set +设置 host 配置值 +```typescript +/** + * 设置若干用于画布渲染的变量,比如画布大小、locale 等。 + * set config for simulator host, eg. device locale and so on. + * @param key + * @param value + */ +set(key: string, value: any): void; +``` +**示例** 设置若干用于画布渲染的变量,比如画布大小、locale 等。 以设置画布大小为例: @@ -21,11 +35,41 @@ project.simulatorHost.set('deviceClassName', 'my-canvas-class'); project.simulatorHost.set('deviceStyle', { canvas: { width: '300px', backgroundColor: 'red' }, viewport: { width: '280px' } }); ``` -## get +### get 获取模拟器中设置的变量,比如画布大小、locale 等。 + +```typescript +/** + * 获取模拟器中设置的变量,比如画布大小、locale 等。 + * set config value by key + * @param key + * @returns + */ +get(key: string): any; + +``` + +### rerender +触发组件构建,并刷新渲染画布 + ```typescript -project.simulatorHost.get('device'); +/** + * 触发组件构建,并刷新渲染画布 + * make simulator render again + */ +rerender(): void; ``` -## rerender -刷新渲染画布 +### scrollToNode +滚动到指定节点 + +```typescript +/** + * 滚动到指定节点 + * scroll to specific node + * @param node + * @since v1.1.0 + */ +scrollToNode(node: IPublicModelNode): void; +``` +**@since v1.1.0** diff --git a/docs/docs/api/skeleton.md b/docs/docs/api/skeleton.md index 1ae573e7ec..396fad9e9e 100644 --- a/docs/docs/api/skeleton.md +++ b/docs/docs/api/skeleton.md @@ -1,7 +1,11 @@ --- title: skeleton - 面板 API -sidebar_position: 1 +sidebar_position: 10 --- +> **@types** [IPublicApiSkeleton](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/api/skeleton.ts)
+> **@since** v1.0.0 + + ## 模块简介 面板 API 提供了面板扩展和管理的能力,如下图蓝色内容都是扩展出来的。 @@ -65,6 +69,7 @@ skeleton.add({ props: { align: "left", icon: "wenjian", + title: '标题', // 图标下方展示的标题 description: "JS 面板", }, panelProps: { @@ -86,7 +91,7 @@ Widget 形式是直接渲染在当前编辑器的对应位置上。如 demo 中 接入可以参考代码: ```javascript -import {skeleton} from "@alilc/lowcode-engine"; +import { skeleton } from "@alilc/lowcode-engine"; // 注册 logo 面板 skeleton.add({ area: "topArea", @@ -115,36 +120,36 @@ skeleton.add({ area: "leftArea", type: "Dock", name: "opener", - content: Opener, // Widget 组件实例 - contentProps: { // Widget 插件 props - xxx: "1", - }, props: { + icon: Icon, // Icon 组件实例 align: "bottom", - }, - onClick: function() { - // 打开外部链接 - window.open('https://lowcode-engine.cn'); - // 显示 widget - skeleton.showWidget('xxx'); + onClick: function () { + // 打开外部链接 + window.open('https://lowcode-engine.cn'); + // 显示 widget + skeleton.showWidget('xxx'); + } } }); ``` -## 变量(variables) +## 方法 -无 -## 方法签名(functions) +### add -### 1. add +往指定扩展区加入一块面板 -```tsx -add(config: IWidgetBaseConfig & { - area?: string; -}, extraConfig?: object): IWidget | Panel; +```typescript +/** + * 增加一个面板实例 + * add a new panel + * @param config + * @param extraConfig + * @returns + */ +add(config: IPublicTypeWidgetBaseConfig, extraConfig?: Record): any; ``` -往指定扩展区加入一块面板 IWidgetBaseConfig 定义如下: @@ -152,7 +157,7 @@ IWidgetBaseConfig 定义如下: | --- | --- | --- | | name | 面板名称 | | | area | 扩展区位置,可选值:'topArea' | 'leftArea' | 'rightArea' | 'toolbar' | 'bottomArea' | 'mainArea' | | -| type | 面板类型,可选值:'Widget' | 'PanelDock' | 'Panel' | 详见前文中对**展示类型**的描述 | +| type | 面板类型,可选值:'Widget' | 'PanelDock' | 'Panel' | Dock | 详见前文中对**展示类型**的描述 | | content | 面板的实现类/节点,类型是 ReactClass | ReactElement | | | props | 面板属性 | align: 'top' | 'bottom' | 'left' | 'center' | 'right'; // 指定面板 icon 位置区域
icon: string | ReactElement;  // icon 为字符串时,请确定当前 fusion 主题包中包含该 icon
description: string;
condition: Function; // 指定当前面板的显影状态 | | contentProps | 面板的实现类/节点的参数 | | @@ -160,74 +165,309 @@ IWidgetBaseConfig 定义如下: | index | 面板的位置,不传默认按插件注册顺序 | | -### 2. remove - -remove(config: IWidgetBaseConfig) +### remove 移除一个面板实例 -### 3. showPanel +```typescript +/** + * 移除一个面板实例 + * remove a panel + * @param config + * @returns + */ +remove(config: IPublicTypeWidgetBaseConfig): number | undefined; +``` -showPanel(name: string) +### getPanel -展示指定 Panel 实例 +获取面板实例 -### 4. hidePanel +```typescript +/** + * 获取面板实例 + * @param name 面板名称 + */ +getPanel(name: string): IPublicModelSkeletonItem | undefined; +``` -hidePanel(name: string) +相关类型:[IPublicModelSkeletonItem](https://github.com/alibaba/lowcode-engine/blob/main/packages/shell/src/model/skeleton-item.ts) -### 5. showWidget +@since v1.1.10 -showWidget(name: string) +### showPanel -展示指定 Widget 实例 +展示指定 Panel 实例 -### 6. hideWidget +```typescript +/** + * 展示指定 Panel 实例 + * show panel by name + * @param name + */ +showPanel(name: string): void; +``` -hideWidget(name: string) +### hidePanel +隐藏面板 -隐藏指定 widget 实例。 +```typescript +/** + * 隐藏面板 + * hide panel by name + * @param name + */ +hidePanel(name: string): void; +``` -### 7. enableWidget +### showWidget -enableWidget(name: string) +展示指定 Widget 实例 +```typescript +/** + * 展示指定 Widget 实例 + * show widget by name + * @param name + */ +showWidget(name: string): void; +``` + +### enableWidget 将 widget 启用。 +```typescript +/** + * 将 widget 启用 + * enable widget + * @param name + */ +enableWidget(name: string): void; +``` + +### hideWidget -注:该函数将会触发全局事件 'skeleton.widget.enable' +隐藏指定 widget 实例。 -### 8. disableWidget +```typescript +/** + * 隐藏指定 widget 实例 + * hide widget by name + * @param name + */ +hideWidget(name: string): void; +``` -disableWidget(name: string) +### disableWidget 将 widget 禁用掉,禁用后,所有鼠标事件都会被禁止掉。 适用场景:在该面板还在进行初始化构造时,可以先禁止掉,防止用户点击报错,待初始化完成,重新启用。 -## 事件(events) -### 1. onShowPanel +```typescript +/** + * 将 widget 禁用掉,禁用后,所有鼠标事件都会被禁止掉。 + * disable widget,and make it not responding any click event. + * @param name + */ +disableWidget(name: string): void; +``` + +### showArea +显示某个 Area + +```typescript +/** + * 显示某个 Area + * show area + * @param areaName name of area + */ +showArea(areaName: string): void; +``` + + +### hideArea +隐藏某个 Area + +```typescript +/** + * 隐藏某个 Area + * hide area + * @param areaName name of area + */ +hideArea(areaName: string): void; +``` + +### getAreaItems + +获取某个区域下的所有面板实例 + +```typescript +/** + * 获取某个区域下的所有面板实例 + * @param areaName IPublicTypeWidgetConfigArea + */ +getAreaItems(areaName: IPublicTypeWidgetConfigArea): IPublicModelSkeletonItem[] | undefined; +``` + +相关类型:[IPublicModelSkeletonItem](https://github.com/alibaba/lowcode-engine/blob/main/packages/shell/src/model/skeleton-item.ts) + + + +### registerConfigTransducer + +注册一个面板的配置转换器(transducer)。 + +```typescript +/** + * 注册一个面板的配置转换器(transducer)。 + * Registers a configuration transducer for a panel. + * @param {IPublicTypeConfigTransducer} transducer + * - 要注册的转换器函数。该函数接受一个配置对象(类型为 IPublicTypeSkeletonConfig)作为输入,并返回修改后的配置对象。 + * - The transducer function to be registered. This function takes a configuration object + * + * @param {number} level + * - 转换器的优先级。优先级较高的转换器会先执行。 + * - The priority level of the transducer. Transducers with higher priority levels are executed first. + * + * @param {string} [id] + * - (可选)转换器的唯一标识符。用于在需要时引用或操作特定的转换器。 + * - (Optional) A unique identifier for the transducer. Used for referencing or manipulating a specific transducer when needed. + */ +registerConfigTransducer(transducer: IPublicTypeConfigTransducer, level: number, id?: string): void; +``` + +使用示例 + +```typescript +import { IPublicModelPluginContext, IPublicTypeSkeletonConfig } from '@alilc/lowcode-types'; + +function updatePanelWidth(config: IPublicTypeSkeletonConfig) { + if (config.type === 'PanelDock') { + return { + ...config, + panelProps: { + ...(config.panelProps || {}), + width: 240, + }, + } + } + + return config; +} + +const controlPanelWidthPlugin = (ctx: IPublicModelPluginContext) => { + const { skeleton } = ctx; + (skeleton as any).registerConfigTransducer?.(updatePanelWidth, 1, 'update-panel-width'); + + return { + init() {}, + }; +}; + +controlPanelWidthPlugin.pluginName = 'controlPanelWidthPlugin'; +controlPanelWidthPlugin.meta = { + dependencies: [], + engines: { + lowcodeEngine: '^1.2.3', // 插件需要配合 ^1.0.0 的引擎才可运行 + }, +}; + +export default controlPanelWidthPlugin; +``` -onShowPanel(listener: (...args: unknown[]) => void) +## 事件 +### onShowPanel 监听 Panel 实例显示事件 -### 2. onHidePanel +```typescript +/** + * 监听 panel 显示事件 + * set callback for panel shown event + * @param listener + * @returns + */ +onShowPanel(listener: (paneName?: string, panel?: IPublicModelSkeletonItem) => void): IPublicTypeDisposable; +``` + +相关类型:[IPublicTypeDisposable](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/type/disposable.ts) -onHidePanel(listener: (...args: unknown[]) => void) +### onHidePanel 监听 Panel 实例隐藏事件 -### 3. onShowWidget +```typescript +/** + * 监听 Panel 实例隐藏事件 + * set callback for panel hidden event + * @param listener + * @returns + */ +onHidePanel(listener: (paneName?: string, panel?: IPublicModelSkeletonItem) => void): IPublicTypeDisposable; +``` + +相关类型:[IPublicTypeDisposable](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/type/disposable.ts) + +### onDisableWidget + +监听 Widget 实例 Disable 事件 + +```typescript +/** + * 监听 Widget 实例 Disable 事件 + * @param listener + */ +onDisableWidget(listener: (paneName?: string, panel?: IPublicModelSkeletonItem) => void): IPublicTypeDisposable; +``` + +相关类型:[IPublicTypeDisposable](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/type/disposable.ts) -onShowWidget(listener: (...args: unknown[]) => void) +### onEnableWidget + +监听 Widget 实例 Enable 事件 + +```typescript +/** + * 监听 Widget 实例 Enable 事件 + * @param listener + */ +onEnableWidget(listener: (paneName?: string, panel?: IPublicModelSkeletonItem) => void): IPublicTypeDisposable; +``` + +相关类型:[IPublicTypeDisposable](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/type/disposable.ts) + +### onShowWidget 监听 Widget 实例显示事件 -### 4. onHideWidget +```typescript +/** + * 监听 Widget 显示事件 + * set callback for widget shown event + * @param listener + * @returns + */ +onShowWidget(listener: (paneName?: string, panel?: IPublicModelSkeletonItem) => void): IPublicTypeDisposable; +``` + +相关类型:[IPublicTypeDisposable](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/type/disposable.ts) -onHideWidget(listener: (...args: unknown[]) => void) +### onHideWidget 监听 Widget 实例隐藏事件 + +```typescript +/** + * 监听 Widget 隐藏事件 + * set callback for widget hidden event + * @param listener + * @returns + */ +onHideWidget(listener: (paneName?: string, panel?: IPublicModelSkeletonItem) => void): IPublicTypeDisposable; +``` + +相关类型:[IPublicTypeDisposable](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/type/disposable.ts) + ## 使用示例 ```typescript @@ -299,7 +539,7 @@ skeleton.disableWidget('sourceEditor'); import { skeleton } from '@alilc/lowcode-engine'; skeleton.add({ - name: 'bottomAreaPanelName', + name: 'bottomAreaPanelName', area: 'bottomArea', type: 'Panel', content: () => 'demoText', diff --git a/docs/docs/api/workspace.md b/docs/docs/api/workspace.md new file mode 100644 index 0000000000..74f7d6950f --- /dev/null +++ b/docs/docs/api/workspace.md @@ -0,0 +1,172 @@ +--- +title: workspace - 应用级 API +sidebar_position: 10 +--- + +> **[@experimental](./#experimental)**
+> **@types** [IPublicApiWorkspace](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/api/workspace.ts)
+> **@since** v1.1.0 + +## 模块简介 + +通过该模块可以开发应用级低代码设计器。 + +## 变量 + +### isActive + +是否启用 workspace 模式 + +### window + +当前设计器窗口模型 + +```typescript +get window(): IPublicModelWindow +``` + +关联模型 [IPublicModelWindow](./model/window) + +### plugins + +应用级别的插件注册 + +```typescript +get plugins(): IPublicApiPlugins +``` + +关联模型 [IPublicApiPlugins](./plugins) + +### skeleton + +应用级别的面板管理 + +```typescript +get skeleton(): IPublicApiSkeleton +``` + +关联模型 [IPublicApiSkeleton](./skeleton) + +### windows + +当前设计器的编辑窗口 + +```typescript +get window(): IPublicModelWindow[] +``` + +关联模型 [IPublicModelWindow](./model/window) + +### resourceList + +当前设计器的资源列表数据 + +``` +get resourceList(): IPublicModelResource; +``` + +关联模型 [IPublicModelResource](./model/resource) + +## 方法 + +### registerResourceType +注册资源 + +```typescript +/** 注册资源 */ +registerResourceType(resourceTypeModel: IPublicTypeResourceType): void; +``` + +相关类型:[IPublicTypeResourceType](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/type/resource-type.ts) + +### setResourceList + +设置设计器资源列表数据 + +```typescript +setResourceList(resourceList: IPublicResourceList) {} +``` + +相关类型:[IPublicResourceData](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/type/resource-list.ts) + +### openEditorWindow + +打开视图窗口 + +```typescript +/** + * 打开视图窗口 + * @deprecated + */ +openEditorWindow(resourceName: string, id: string, extra: Object, viewName?: string, sleep?: boolean): Promise; + +/** 打开视图窗口 */ +openEditorWindow(resource: Resource, sleep?: boolean): Promise; +``` + +### openEditorWindowById + +通过视图 id 打开窗口 + +```typescript +openEditorWindowById(id: string): void; +``` + +### removeEditorWindow + +移除视图窗口 + +```typescript +/** + * 移除视图窗口 + * @deprecated + */ +removeEditorWindow(resourceName: string, id: string): void; + +/** + * 移除视图窗口 + */ +removeEditorWindow(resource: Resource): void; +``` + +### removeEditorWindowById + +通过视图 id 移除窗口 + +```typescript +removeEditorWindowById(id: string): void; +``` + +## 事件 + +### onChangeWindows + +窗口新增/删除的事件 + +```typescript +function onChangeWindows(fn: () => void): IPublicTypeDisposable; +``` + +相关类型:[IPublicTypeDisposable](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/type/disposable.ts) + +### onChangeActiveWindow + +active 窗口变更事件 + +```typescript +function onChangeActiveWindow(fn: () => void): IPublicTypeDisposable; +``` + +相关类型:[IPublicTypeDisposable](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/type/disposable.ts) + + +### onResourceListChange + +设计器资源列表数据变更事件 + +```typescript +onResourceListChange(fn: (resourceList: IPublicResourceList): void): (): IPublicTypeDisposable; +``` + +- 相关类型:[IPublicResourceOptions](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/type/resource-options.ts) +- 相关类型:[IPublicTypeDisposable](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/type/disposable.ts) diff --git a/docs/docs/article/index.md b/docs/docs/article/index.md index fd09a59a34..c223137b25 100644 --- a/docs/docs/article/index.md +++ b/docs/docs/article/index.md @@ -1,38 +1,15 @@ ---- -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 +# 官方文章 +- [2023/11/09 UIPaaS | 基于 LowCodeEngine 的低代码平台孵化器](https://mp.weixin.qq.com/s/mKuv3_Wvgt5T3AGErUGBQQ) +- [2023/04/04 什么?低代码引擎可以开发应用了](https://mp.weixin.qq.com/s/dwi40gJjGBHW9MVpag5Oxg) +- [2023/03/23 低代码引擎 LowCodeEngine 茁壮成长的一年](https://mp.weixin.qq.com/s/DDt4LQLFUBQ2-F5ehZGBKg) +- [2023/02/21 基于 LowCodeEngine 的低代码组件体系的建设和实践](https://mp.weixin.qq.com/s/rnvbGHImGt6oJuX2wCtaqw) +- [2022/12/21 低代码多分支协同开发的建设与实践](https://mp.weixin.qq.com/s/DmwxL67htHfTUP1U966N-Q) +- [2022/11/24 低代码引擎半岁啦,来跟大家唠唠嗑...](https://segmentfault.com/a/1190000042884409) +- [2022/10/27 低代码技术在研发团队的应用模式探讨](https://mp.weixin.qq.com/s/Ynk_wjJbmNw7fEG6UtGZbQ) +- [2022/08/23 基于 LowCodeEngine 的调试能力建设与实践](https://mp.weixin.qq.com/s/H8KvEOylmzLPgIuuBO0S9w) +- [2022/06/23 低代码渲染那些事](https://mp.weixin.qq.com/s/yqYey76qLGYPfDtpGkVFfA) +- [2022/06/16 关于 LowCode&ProCode 混合研发的思考](https://mp.weixin.qq.com/s/TY3VXjkSmsQoT47xma3wig) +- [2022/04/07 磁贴布局在钉钉宜搭报表设计引擎中的实现](https://mp.weixin.qq.com/s/PSTut5ahAB8nlJ9kBpBaxw) +- [2022/03/23 阿里低代码引擎 LowCodeEngine 正式开源!](https://mp.weixin.qq.com/s/T66LghtWLz2Oh048XqaniA) +- [2022/01/10 阿里低代码引擎和生态建设实战及思考](https://mp.weixin.qq.com/s/MI6MrUKKydtnSdO4xq6jwA) +- [2021/04/14 2B 领域下的低代码探索之路](https://mp.weixin.qq.com/s/HAxrMHLT43dPH488RiEIdw) diff --git a/docs/docs/demoUsage/appendix/loop.md b/docs/docs/demoUsage/appendix/loop.md index 8b364ecf4f..46f39398af 100644 --- a/docs/docs/demoUsage/appendix/loop.md +++ b/docs/docs/demoUsage/appendix/loop.md @@ -15,3 +15,14 @@ sidebar_position: 0 ![image.png](https://img.alicdn.com/imgextra/i4/O1CN01XQfnYL1P4wxn01oXv_!!6000000001788-2-tps-3840-1896.png) this.index 是当前循环的索引值。 + +3.在事件绑定函数中使用 + +在事件绑定函数中使用扩展参数设置 +![image](https://github.com/alibaba/lowcode-engine/assets/11935995/7274506e-decd-497a-b07f-c95941a706b4) + +绑定之后在函数中使用 +![image](https://github.com/alibaba/lowcode-engine/assets/11935995/9d52ee5c-9959-4991-91be-9391e639bb7e) + +按钮点击效果 +![image](https://github.com/alibaba/lowcode-engine/assets/11935995/6ca590c9-1f5f-4d48-94a5-439130a22e92) diff --git a/docs/docs/demoUsage/makeStuff/dialog.md b/docs/docs/demoUsage/makeStuff/dialog.md index 56303067cb..da78cc8e8c 100644 --- a/docs/docs/demoUsage/makeStuff/dialog.md +++ b/docs/docs/demoUsage/makeStuff/dialog.md @@ -2,6 +2,8 @@ title: 3. 如何通过按钮展示/隐藏弹窗 sidebar_position: 1 --- +> 说明:这个方式依赖低代码弹窗组件是否对外保留了相关的 API,不同的物料支持的方式不一样,这里只针对综合场景的弹窗物料。 + ## 1.拖拽一个按钮 ![image.png](https://img.alicdn.com/imgextra/i1/O1CN01kLaWA31D6WwTui9VW_!!6000000000167-2-tps-3584-1812.png) diff --git a/docs/docs/demoUsage/panels/code.md b/docs/docs/demoUsage/panels/code.md index 929c9bcb08..645fcc7af4 100644 --- a/docs/docs/demoUsage/panels/code.md +++ b/docs/docs/demoUsage/panels/code.md @@ -45,16 +45,13 @@ window.Next.Message.success('成功') - 读取:每次打开面板时,都会尝试读取 schema 中的 originCode 字段,如果没有,则从 schema 上的字段还原代码; - 写入:在关闭代码编辑面板(主动点击叉或者点击非代码编辑区块的被动关闭都算)时,将自动写入到 schema 中;您也可以在编辑过程中点击“保存”按钮手动保存; -| 源码面板中 | schema 中 | + +| 源码面板中 | Schema 中 | | --- | --- | -| 本地数据初始值设置: -![image.png](https://img.alicdn.com/imgextra/i4/O1CN01V6iaTY1gVNHi7gQfK_!!6000000004147-2-tps-370-146.png) | ![image.png](https://img.alicdn.com/imgextra/i2/O1CN010rhIPa268BEfGmzO6_!!6000000007616-2-tps-2098-826.png) | -| 生命周期方法: -![image.png](https://img.alicdn.com/imgextra/i4/O1CN010Y1TxV1QOvrVLRUjD_!!6000000001967-2-tps-478-260.png) | ![image.png](https://img.alicdn.com/imgextra/i3/O1CN01pbJzVQ1VSfAL7Lh8G_!!6000000002652-2-tps-2010-836.png) | -| 自定义函数: -![image.png](https://img.alicdn.com/imgextra/i4/O1CN01S2gjFk1CU3fm61eiD_!!6000000000083-2-tps-660-642.png) | ![image.png](https://img.alicdn.com/imgextra/i2/O1CN01X35YxU1GUkjj1YWVj_!!6000000000626-2-tps-1862-822.png) | -| 编译前全量代码: -![image.png](https://img.alicdn.com/imgextra/i2/O1CN01sbiK9N1kc1Uxp1OHY_!!6000000004703-2-tps-762-1122.png) | ![image.png](https://img.alicdn.com/imgextra/i3/O1CN01adKSg61QXAzRjQ4bm_!!6000000001985-2-tps-1906-796.png) | +| 本地数据初始值设置:![image.png](https://img.alicdn.com/imgextra/i4/O1CN01V6iaTY1gVNHi7gQfK_!!6000000004147-2-tps-370-146.png) | ![image.png](https://img.alicdn.com/imgextra/i2/O1CN010rhIPa268BEfGmzO6_!!6000000007616-2-tps-2098-826.png) | +| 生命周期方法:![image.png](https://img.alicdn.com/imgextra/i4/O1CN010Y1TxV1QOvrVLRUjD_!!6000000001967-2-tps-478-260.png) | ![image.png](https://img.alicdn.com/imgextra/i3/O1CN01pbJzVQ1VSfAL7Lh8G_!!6000000002652-2-tps-2010-836.png) | +| 自定义函数:![image.png](https://img.alicdn.com/imgextra/i4/O1CN01S2gjFk1CU3fm61eiD_!!6000000000083-2-tps-660-642.png) | ![image.png](https://img.alicdn.com/imgextra/i2/O1CN01X35YxU1GUkjj1YWVj_!!6000000000626-2-tps-1862-822.png) | +| 编译前全量代码:![image.png](https://img.alicdn.com/imgextra/i2/O1CN01sbiK9N1kc1Uxp1OHY_!!6000000004703-2-tps-762-1122.png) | ![image.png](https://img.alicdn.com/imgextra/i3/O1CN01adKSg61QXAzRjQ4bm_!!6000000001985-2-tps-1906-796.png) | - 异常处理:如果代码解析失败,它将无法被正常保存到 schema 中,此时编辑器会弹层提示: diff --git a/docs/docs/faq/faq009.md b/docs/docs/faq/faq009.md index f1247bfa41..4115384353 100644 --- a/docs/docs/faq/faq009.md +++ b/docs/docs/faq/faq009.md @@ -28,6 +28,28 @@ AliLowCodeEngine.project.simulator.renderer.components ``` 看看对应的物料是否存在,如果不存在,排查物料问题。 +如果不正常,查看资产包配置,其中资产包中的 `components` 和 `material.componentsMap` 生成有关系。 + +例如,物料配置信息在 @alilc/lowcode-materials 包里面,即需要在 components 中加上下面的代码 + +```javascript +"components": [{ + "exportName": "AlilcLowcodeMaterialsMeta", + "npm": { + "package": "@alilc/lowcode-materials" + }, + "url": "https://alifd.alicdn.com/npm/@alilc/lowcode-materials@1.0.7/build/lowcode/meta.js", + "urls": { + "default": "https://alifd.alicdn.com/npm/@alilc/lowcode-materials@1.0.7/build/lowcode/meta.js", + "design": "https://alifd.alicdn.com/npm/@alilc/lowcode-materials@1.0.7/build/lowcode/meta.design.js" + } +}] +``` + +`material.componentsMap` 不存在相关的组件信息,原因有两个: +- 没有添加对应的物料到 components 字段中 +- components 配置不正确,需要查看 url 是否正常加载,查看 exportName 是否配置正确,即 `window.${exportName}` 是否存在。 + 2.选中组件,在控制台中输入 ```json AliLowCodeEngine.project.currentDocument.selection.getNodes()[0].exportSchema('render') diff --git a/docs/docs/faq/faq011.md b/docs/docs/faq/faq011.md index 3c6bf1d2d2..f61d9830fc 100644 --- a/docs/docs/faq/faq011.md +++ b/docs/docs/faq/faq011.md @@ -5,6 +5,7 @@ tags: [FAQ] --- ## 简单场景 可以利用 props.__designMode + ![image.png](https://img.alicdn.com/imgextra/i3/O1CN01btr66024FOEldBOr2_!!6000000007361-2-tps-1616-440.png) 设计态中,__designMode 值为 "design" @@ -13,10 +14,12 @@ tags: [FAQ] ## 复杂场景 在资产包里定义 editUrls + ![image.png](https://img.alicdn.com/imgextra/i1/O1CN01odal6P27Rhjn8NoJ6_!!6000000007794-2-tps-1590-538.png) ### editUrls 在 lowcode/xx/ 下新建一个 view.tsx + ![image.png](https://img.alicdn.com/imgextra/i3/O1CN01q0Bbn91Lrig7d0alA_!!6000000001353-2-tps-598-154.png) 再执行 diff --git a/docs/docs/faq/faq013.md b/docs/docs/faq/faq013.md index bf073e7334..a8f86b2948 100644 --- a/docs/docs/faq/faq013.md +++ b/docs/docs/faq/faq013.md @@ -10,9 +10,28 @@ tags: [FAQ] ## 处理方式 ### 【推荐】升级到 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) + +通过新增 Save 态的 propsReducer,将 hidden props 去掉。可以参考下面的代码: + +```typescript +import { project } from '@alilc/lowcode-engine'; +import { IPublicEnumTransformStage } from '@alilc/lowcode-types'; + +export const deleteHiddenTransducer = (ctx: any) => { + return { + name: 'deleteHiddenTransducer', + async init() { + project.addPropsTransducer((props: any): any => { + delete props.hidden; + return props; + }, IPublicEnumTransformStage.Save); + }, + }; +} + +deleteHiddenTransducer.pluginName = 'deleteHiddenTransducer'; + +``` ### 导出 schema 使用 Save 态 ```typescript diff --git a/docs/docs/faq/faq015.md b/docs/docs/faq/faq015.md index 48e97bc22f..683e7df3aa 100644 --- a/docs/docs/faq/faq015.md +++ b/docs/docs/faq/faq015.md @@ -4,4 +4,4 @@ sidebar_position: 15 tags: [FAQ] --- 你可以通过在线工具「Parts 造物」生产物料描述协议,然后使用到你的项目中去。 -文档地址:[利用 Parts 造物快速使用 react 组件](/site/docs/guide/expand/editor/partsIntro) +文档地址:[利用 Parts 造物快速使用 react 组件](/site/docs/guide/expand/editor/parts/partsIntro) diff --git a/docs/docs/faq/faq023.md b/docs/docs/faq/faq023.md new file mode 100644 index 0000000000..e03f7118e0 --- /dev/null +++ b/docs/docs/faq/faq023.md @@ -0,0 +1,31 @@ +--- +title: Slot组件渲染报错问题 +sidebar_position: 23 +tags: [FAQ] +--- + +## 问题描述 +在低代码引擎的页面渲染过程中,可能会遇到一个关于Slot组件的报错,提示“Slot找不到”。实际上,在渲染态时不应使用Slot组件。 + +## 问题原因 +低代码引擎渲染分为两个状态:设计态和渲染态。 +- **设计态**:为了帮助插槽进行可视化设计,引入了Slot组件。 +- **渲染态**:在此状态下,不需要使用Slot组件。 + +这个问题通常是因为在渲染态错误地使用了设计态的schema。 + +## 解决方案 +1. **区分设计态和渲染态**:通过`project.exportSchema(TransformStage.Save)`的参数来区分。 + - `TransformStage.Save`代表渲染态的schema,其中不包含Slot组件。 + - 【默认值】`TransformStage.Render`代表设计态的schema,其中包含Slot组件。 +2. **使用正确的API和参数**:确保在渲染态使用正确的schema,避免引用设计态的Slot组件。 +3. **处理脏数据问题**:如果问题是由脏数据导致,清除数据并重新拖拽组件以恢复正常。 + +## 注意事项 +- 确保在代码和配置中正确区分设计态和渲染态。 +- 如果遇到持续的问题,检查是否有脏数据或配置错误,并进行相应的清理和调整。 + +## 相关链接 +- Issue链接:[Issue #1798](https://github.com/alibaba/lowcode-engine/issues/1798) + +--- diff --git a/docs/docs/faq/faq024.md b/docs/docs/faq/faq024.md new file mode 100644 index 0000000000..ab1b68f5d7 --- /dev/null +++ b/docs/docs/faq/faq024.md @@ -0,0 +1,133 @@ +--- +title: workspace 模式常见问题 +sidebar_position: 23 +tags: [FAQ] +--- + +#### 如何判断是否开启了IDE模式? + +- **通过官方API判断**:您可以通过访问 [workspace.isActive](/site/docs/api/workspace#isactive) 来判断当前是否处于IDE模式。这是阿里低代码引擎提供的一个官方API,专门用于确认是否处于集成开发环境。 + + + +#### 如何使用插件的ctx来做判断在哪个模式下? + +- **插件是否为应用级别**:可以通过 **ctx.isPluginRegisteredInWorkspace** 方法来判断一个插件是否是应用级别的插件。这有助于理解插件在阿里低代码引擎中的作用域和潜在的使用场景。 +- **插件的注册级别**:您可以使用 **ctx.registerLevel** 属性来判断插件处于哪个级别。插件级别的值包括: + - **Default**:默认级别。非 IDE 模式下的值 + - **Workspace**:应用级别。 + - **Resource**:资源级别。 + - **EditorView**:编辑视图级别。 这些级别代表了插件可能的作用域和使用场景,有助于在开发和管理低代码应用时对插件进行更精确的控制和配置。 + + + +#### 如何在IDE模式下设置资源列表? + +- **设置资源列表API**:在IDE模式下,可以通过访问 [workspace.setResourceList](/site/docs/api/workspace#setresourcelist) 来设置或更新IDE中的资源列表。这确保您在编辑器窗口中打开的资源是最新且可访问的。 + + + +#### 如何打开视图窗口? + +- **使用推荐的方法**:使用 `openEditorWindow(resource: Resource, sleep?: boolean): Promise;` 来打开视图窗口。这里的 **resource** 参数指的是您要打开的特定资源,可通过 [workspace.resourceList](/site/docs/api/workspace#resourcelist) 获取。 +- **不推荐使用的过时方法**:有一个过时的方法 `openEditorWindow(resourceName: string, id: string, extra: Object, viewName?: string, sleep?: boolean): Promise;` 也用于打开视图窗口。虽然仍然可用,但官方不推荐使用此方法,并计划在后续版本中废弃,因为它在维护和可扩展性方面存在限制。 + + + +#### 如何在全局插件中获取视图的上下文? + +- 在阿里低代码引擎的全局插件中获取视图的上下文,可以通过使用 **ProvideViewPluginContext** 函数实现。这个函数来自 **@alilc/lowcode-utils** 库,它使得您的 React 组件能够接收 **pluginContext** 作为 props,进而访问和操作当前视图的状态和属性。 + +**步骤** + +**引入依赖**:首先,确保您的插件文件中已经引入了 **ProvideViewPluginContext** 以及其他必要的依赖。 + +``` +import { ProvideViewPluginContext } from '@alilc/lowcode-utils'; +``` + +**定义 React 组件**:创建一个 React 组件,它将使用来自 **ProvideViewPluginContext** 的 **pluginContext**。 + +```typescript +const MyComponent = (props) => { + const { pluginContext } = props; + // 组件逻辑 + return
/* 组件内容 */
; +}; +``` + +**定义全局插件**:定义一个函数,这个函数会在插件被注册时调用。这个函数通常接受一个上下文对象 **ctx**,它提供了对引擎功能的访问。 + +```javascript +const globalPlugin = (ctx) => { + const { skeleton } = ctx; + + skeleton.add({ + type: 'PanelDock', + name: 'datapool', + content: ProvideViewPluginContext((props) => { + // 组件内容 + return ( + + ) + }), + // 其他配置 + contentProps: { + // 需要提供 pluginContext 作为参数 + pluginContext: ctx, + } + }); +}; +``` + +通过这些步骤,您的全局插件中的 React 组件就能够获取并使用视图的上下文了。这为您在插件中实现更复杂的功能和交互提供了基础。 + + + +**注意事项** + +- **组件重渲染**:正常情况下,**pluginsContext** 是视图的上下文。当视图切换时,组件会重新渲染。如果需要在组件中处理视图切换导致的重新渲染,可以利用 React 的 **key** 属性。 + +**示例代码** + +```typescript +ProvideViewPluginContext(props => { + return ( +