From 33ed67ab577e8870b2f4131b10d1abd6d6e7e98a Mon Sep 17 00:00:00 2001 From: JackLian Date: Sun, 25 Dec 2022 13:49:05 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20api=E6=96=87=E6=A1=A3=E5=9F=BA=E7=A1=80?= =?UTF-8?q?=E4=BC=98=E5=8C=96?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/config/navbar.js | 22 +- docs/config/sidebars.js | 55 +- docs/docs/api/canvas.md | 86 ++ docs/docs/api/common.md | 130 ++- docs/docs/api/config.md | 109 +- docs/docs/api/event.md | 38 +- docs/docs/api/hotkey.md | 35 +- docs/docs/api/index.md | 6 +- docs/docs/api/init.md | 8 + docs/docs/api/logger.md | 93 +- docs/docs/api/material.md | 285 +++-- docs/docs/api/model/_category_.json | 6 + docs/docs/api/model/detecting.md | 47 + docs/docs/api/model/document-model.md | 150 +++ docs/docs/api/model/dragon.md | 129 ++ docs/docs/api/model/history.md | 58 + docs/docs/api/model/modal-nodes-manager.md | 48 + docs/docs/api/model/node-children.md | 123 ++ docs/docs/api/model/node.md | 250 ++++ docs/docs/api/model/prop.md | 53 + docs/docs/api/model/props.md | 58 + docs/docs/api/model/selection.md | 85 ++ docs/docs/api/plugins.md | 158 +-- docs/docs/api/project.md | 1038 ++++------------- docs/docs/api/setters.md | 228 +--- docs/docs/api/simulatorHost.md | 56 +- docs/docs/api/skeleton.md | 196 +++- docs/scripts/getDocsFromDir.js | 5 +- docs/scripts/sync-oss.js | 2 +- .../designer/src/plugin/plugin-manager.ts | 4 +- packages/designer/src/plugin/plugin-utils.ts | 4 +- packages/designer/src/project/project.ts | 1 - packages/editor-core/src/config.ts | 6 +- packages/editor-core/src/utils/preference.ts | 4 +- packages/shell/src/api/common.tsx | 32 +- packages/shell/src/api/material.ts | 6 +- packages/shell/src/api/plugins.ts | 4 +- packages/shell/src/api/project.ts | 9 +- packages/types/src/engine-config.ts | 17 - packages/types/src/shell/api/canvas.ts | 12 +- packages/types/src/shell/api/common.ts | 87 +- packages/types/src/shell/api/event.ts | 3 + packages/types/src/shell/api/hotkey.ts | 7 +- packages/types/src/shell/api/material.ts | 36 +- packages/types/src/shell/api/plugins.ts | 19 +- packages/types/src/shell/api/project.ts | 45 +- packages/types/src/shell/api/setters.ts | 3 + .../types/src/shell/api/simulator-host.ts | 14 +- packages/types/src/shell/api/skeleton.ts | 40 +- packages/types/src/shell/model/detecting.ts | 6 + packages/types/src/shell/model/dragon.ts | 12 +- .../types/src/shell/model/engine-config.ts | 17 +- packages/types/src/shell/model/index.ts | 1 + packages/types/src/shell/model/preference.ts | 17 + packages/types/src/shell/model/selection.ts | 6 + packages/types/src/shell/type/index.ts | 3 +- .../src/shell/type/plugin-register-options.ts | 13 + scripts/sync-oss.js | 2 +- 58 files changed, 2453 insertions(+), 1534 deletions(-) create mode 100644 docs/docs/api/canvas.md create mode 100644 docs/docs/api/model/_category_.json create mode 100644 docs/docs/api/model/detecting.md create mode 100644 docs/docs/api/model/document-model.md create mode 100644 docs/docs/api/model/dragon.md create mode 100644 docs/docs/api/model/history.md create mode 100644 docs/docs/api/model/modal-nodes-manager.md create mode 100644 docs/docs/api/model/node-children.md create mode 100644 docs/docs/api/model/node.md create mode 100644 docs/docs/api/model/prop.md create mode 100644 docs/docs/api/model/props.md create mode 100644 docs/docs/api/model/selection.md create mode 100644 packages/types/src/shell/model/preference.ts create mode 100644 packages/types/src/shell/type/plugin-register-options.ts diff --git a/docs/config/navbar.js b/docs/config/navbar.js index 0f0486398..20d5e5f90 100644 --- a/docs/config/navbar.js +++ b/docs/config/navbar.js @@ -33,12 +33,6 @@ module.exports = { position: 'left', label: 'FAQ', }, - { - type: 'doc', - docId: 'participate/index', - position: 'left', - label: '参与贡献', - }, { type: 'doc', docId: 'article/index', @@ -51,16 +45,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 +64,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 e2de2d49c..95a79962f 100644 --- a/docs/config/sidebars.js +++ b/docs/config/sidebars.js @@ -22,10 +22,56 @@ 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'), + }, + { + 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: 'link', + label: '技术白皮书', + href: 'https://developer.aliyun.com/ebook/7507', + }, + ], ], api: [ { @@ -57,5 +103,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 000000000..8340bd348 --- /dev/null +++ b/docs/docs/api/canvas.md @@ -0,0 +1,86 @@ +--- +title: cavas - 画布 API +sidebar_position: 12 +--- + +> **@types** [IPublicApiCanvas](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/api/canvas.ts)
+> **@since** v1.1.0 + + +## 模块简介 + +通过该模块可以触达对画布拖拽相关的一些能力。 + +## 变量 + +### dragon + +获取拖拽操作对象的实例 + +```typescript +/** + * 获取拖拽操作对象的实例 + * get dragon instance, you can use this to obtain draging related abilities and lifecycle hooks + * @since v1.1.0 + */ +get dragon(): IPublicModelDragon | null; +``` +关联模型 [IPublicModelDragon](./model/dragon) + +### activeTracker + +获取活动追踪器实例 + +```typescript +/** + * 获取活动追踪器实例 + * get activeTracker instance, which is a singleton running in engine. + * it tracks document`s current focusing node/node[], and notify it`s subscribers that when + * focusing node/node[] changed. + * @since v1.1.0 + */ +get activeTracker(): IPublicModelActiveTracker | null; +``` + +## 方法签名 + +### 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 (IPublicModelScrollable) 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: IPublicModelScrollable): 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; +``` \ No newline at end of file diff --git a/docs/docs/api/common.md b/docs/docs/api/common.md index 39ee609e8..a6b21974d 100644 --- a/docs/docs/api/common.md +++ b/docs/docs/api/common.md @@ -2,34 +2,87 @@ title: common - 通用 API sidebar_position: 11 --- -# 模块简介 -通用模块里包含除了 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 -从 schema 结构中查找指定 id 节点 +```typescript +/** + * 是否为表单事件类型 + * check if e is a form event + * @param {(KeyboardEvent | MouseEvent)} e + * @returns {boolean} + */ +isFormEvent(e: KeyboardEvent | MouseEvent): boolean; +``` -### executeTransaction +#### 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 批处理事务，用于优化特定场景的性能 -*引擎版本 >= 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 { IPublicEnumTransitionType } from '@alilc/lowcode-types'; @@ -42,9 +95,33 @@ common.utils.startTransaction(() => { }, IPublicEnumTransitionType.repaint); ``` -### createIntl +#### 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 +133,15 @@ 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 +### skeletonCabin +#### Workbench 编辑器框架 View -# 事件（events） -无 +```typescript +/** + * 编辑器框架 View + * get Workbench Component + */ +get Workbench(): Component; +``` \ No newline at end of file diff --git a/docs/docs/api/config.md b/docs/docs/api/config.md index 40d18eb3a..fee26d436 100644 --- a/docs/docs/api/config.md +++ b/docs/docs/api/config.md @@ -2,21 +2,29 @@ title: config - 配置 API sidebar_position: 8 --- + +> **@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,77 @@ 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** + +## 事件 + ### 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 +138,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 +159,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/event.md b/docs/docs/api/event.md index b24c91054..be3c768e0 100644 --- a/docs/docs/api/event.md +++ b/docs/docs/api/event.md @@ -2,41 +2,63 @@ title: event - 事件 API sidebar_position: 7 --- + +> **@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) ### 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; +/** + * 取消监听事件 + * cancel a monitor from a event + * @param event 事件名称 + * @param listener 事件回调 + */ +off(event: string, listener: (...args: any[]) => void): 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 cd0cf2944..a8c717342 100644 --- a/docs/docs/api/hotkey.md +++ b/docs/docs/api/hotkey.md @@ -2,29 +2,36 @@ title: hotkey - 快捷键 API sidebar_position: 5 --- + +> **@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 快捷键按下时需要执行的逻辑 -}); -``` ## 使用示例 ### 基础示例 diff --git a/docs/docs/api/index.md b/docs/docs/api/index.md index 212337a62..2bd735c84 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 文档 @@ -37,7 +37,7 @@ sidebar_position: 0 - history 操作历史 -### API 设计约定 +## API 设计约定 一些 API 设计约定： 1. 所有 API 命名空间都按照 variables / functions / events 来组织 diff --git a/docs/docs/api/init.md b/docs/docs/api/init.md index 93ad133d3..fd0d4fff3 100644 --- a/docs/docs/api/init.md +++ b/docs/docs/api/init.md @@ -2,6 +2,10 @@ title: init - 初始化 API sidebar_position: 10 --- + +> **@since** v1.0.0 + + ## 模块简介 提供 init 等方法 ## 方法签名 @@ -14,6 +18,7 @@ function init(container?: Element, options?: EngineOptions): void ``` **初始化引擎的参数** + ```typescript interface EngineOptions { /** @@ -102,6 +107,9 @@ interface EngineOptions { [key: string]: any; } ``` +> 源码详见 [EngineOptions](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/engine-config.ts) + + ## 使用示例 ```typescript import { init } from '@alilc/lowcode-engine'; diff --git a/docs/docs/api/logger.md b/docs/docs/api/logger.md index 211065410..68681438b 100644 --- a/docs/docs/api/logger.md +++ b/docs/docs/api/logger.md @@ -2,48 +2,79 @@ title: logger - 日志 API sidebar_position: 9 --- -## 模块简介 -引擎日志模块，可以按照 **日志级别 **和** 业务类型 **两个维度来定制日志，参考 [zen-logger](https://web.npm.alibaba-inc.com/package/zen-logger) 实现进行封装。 -> 注：日志级别可以通过 url query 动态调整，详见下方使用示例。 -## 变量（variables） -无 -## 方法签名（functions） -### log / warn / error / info / debug +> **@types** [IPublicApiLogger](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/api/logger.ts)
+> **@since** v1.0.0 + + +## 模块简介 +引擎日志模块，可以按照 **日志级别 **和** 业务类型 **两个维度来定制日志。 +> 注：日志级别可以通过 url query 动态调整，详见下方[查看示例](#查看示例)。
+> 参考 [zen-logger](https://web.npm.alibaba-inc.com/package/zen-logger) 实现进行封装 + +## 方法签名 + 日志记录方法 -**类型定义** ```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-utils'; -const logger = new Logger({ level: 'warn', bizName: 'designer:pluginManager' }); +const logger = new Logger({ level: 'warn', bizName: 'myPlugin:moduleA' }); logger.log('Awesome Low-Code Engine'); ``` -## 事件（events） -无 -## 使用示例 -```typescript -import { Logger } from '@alilc/lowcode-utils'; +## 查看示例 -const logger = new Logger({ level: 'warn', bizName: 'designer:pluginManager' }); +开启查看方式： -// 若在 url query 中增加 `__logConf__` 可改变打印日志级别和限定业务类型日志 -// 默认：__logConf__=warn:* -logger.log('log'); // 不输出 -logger.warn('warn'); // 输出 -logger.error('error'); // 输出 - -// 比如：__logConf__=log:designer:pluginManager -logger.log('log'); // 输出 -logger.warn('warn'); // 输出 -logger.error('error'); // 输出 +- 方式 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 + +https://lowcode-engine.cn/demo/demo-general/index.html?__logConf__=warn|* +// 同 __logConf__=warn + +https://lowcode-engine.cn/demo/demo-general/index.html?__logConf__=warn|bizName +// 开启 bizName 的 debug, log, info, warn 和 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 f1df43e6c..c060b9bef 100644 --- a/docs/docs/api/material.md +++ b/docs/docs/api/material.md @@ -2,24 +2,44 @@ title: material - 物料 API sidebar_position: 2 --- -# 模块简介 + +> **@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 包 ```javascript import { material } from '@alilc/lowcode-engine'; @@ -28,7 +48,7 @@ import assets from '@alilc/mc-assets-/assets.json'; material.setAssets(assets); ``` -通过物料中心接口动态引入资产包 +通过接口动态引入资产包 ```typescript import { material, plugins } from '@alilc/lowcode-engine'; import { IPublicModelPluginContext } from '@alilc/lowcode-types'; @@ -39,43 +59,54 @@ plugins.register((ctx: IPublicModelPluginContext) => { 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) -**示例** +##### 示例 ```typescript 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): void; ``` -说明：**该增量包会与原有的合并** +相关类型：[IPublicTypeAssetsJson](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/type/assets-json.ts) -**示例** +##### 示例 ```typescript import { material } from '@alilc/lowcode-engine'; import assets1 from '@alilc/mc-assets-/assets.json'; @@ -84,57 +115,23 @@ import assets2 from '@alilc/mc-assets-/assets.json'; material.setAssets(assets1); material.loadIncrementalAssets(assets2); ``` -## 设计器辅助层 -### addBuiltinComponentAction + +### 设计器辅助层 +#### addBuiltinComponentAction 在设计器辅助层增加一个扩展 action -**类型定义** + ```typescript -function addBuiltinComponentAction(action: IPublicTypeComponentAction): void; - -export interface IPublicTypeComponentAction { - /** - * behaviorName - */ - name: string; - /** - * 菜单名称 - */ - content: string | ReactNode | ActionContentObject; - /** - * 子集 - */ - items?: IPublicTypeComponentAction[]; - /** - * 显示与否 - * always: 无法禁用 - */ - condition?: boolean | ((currentNode: any) => boolean) | 'always'; - /** - * 显示在工具条上 - */ - important?: boolean; -} - -export interface ActionContentObject { - /** - * 图标 - */ - icon?: IconType; - /** - * 描述 - */ - title?: TipContent; - /** - * 执行动作 - */ - action?: (currentNode: any) => void; -} - -export type IconType = string | ReactElement | ComponentType | IconConfig; +/** + * 在设计器辅助层增加一个扩展 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) -**示例** +##### 示例 新增设计扩展位，并绑定事件 ```typescript import { material } from '@alilc/lowcode-engine'; @@ -154,14 +151,27 @@ 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'; @@ -169,16 +179,25 @@ material.removeBuiltinComponentAction('myIconName'); ``` -### modifyBuiltinComponentAction +#### modifyBuiltinComponentAction 修改已有的设计器辅助层的指定 action -**类型定义** + ```typescript -function modifyBuiltinComponentAction( - actionName: string, - handle: (action: IPublicTypeComponentAction) => 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：隐藏 @@ -188,7 +207,7 @@ function modifyBuiltinComponentAction( -**示例** +##### 示例 给原始的 remove 扩展时间添加执行前后的日志 ```typescript import { material } from '@alilc/lowcode-engine'; @@ -202,30 +221,43 @@ material.modifyBuiltinComponentAction('remove', (action) => { } }); ``` -### -## 物料元数据 -### getComponentMeta -获取指定名称的物料元数据 -**类型定义** -```typescript -function getComponentMeta(componentName: string): ComponentMeta; -``` -**示例** +### 物料元数据 +#### getComponentMeta +获取指定名称的物料元数据 + +```typescript +/** + * 获取指定名称的物料元数据 + * 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 import { material } from '@alilc/lowcode-engine'; material.getComponentMeta('Input'); ``` -### getComponentMetasMap +#### getComponentMetasMap 获取所有已注册的物料元数据 -**类型定义** -```typescript -function getComponentMetasMap(): new Map; -``` -**示例** +```typescript + /** + * 获取所有已注册的物料元数据 + * 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 import { material } from '@alilc/lowcode-engine'; @@ -233,19 +265,27 @@ material.getComponentMetasMap(); ``` -## 物料元数据管道函数 -### 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; ``` -**示例** +##### 示例 给每一个组件的配置添加高级配置面板，其中有一个是否渲染配置项 ```typescript import { material } from '@alilc/lowcode-engine' @@ -290,28 +330,37 @@ function addonCombine(metadata: TransformedComponentMetadata) { material.registerMetadataTransducer(addonCombine, 1, 'parse-func'); ``` -### getRegisteredMetadataTransducers +#### getRegisteredMetadataTransducers 获取所有物料元数据管道函数 -**类型定义** + ```typescript -function getRegisteredMetadataTransducers(): IPublicTypeMetadataTransducer[]; +/** + * 获取所有物料元数据管道函数 + * 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): void; ``` -**示例** +##### 示例 ```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 000000000..5b1f74b36 --- /dev/null +++ b/docs/docs/api/model/_category_.json @@ -0,0 +1,6 @@ +{ + "label": "模型定义 Models", + "position": 14, + "collapsed": false, + "collapsible": true +} diff --git a/docs/docs/api/model/detecting.md b/docs/docs/api/model/detecting.md new file mode 100644 index 000000000..2cc0ea18d --- /dev/null +++ b/docs/docs/api/model/detecting.md @@ -0,0 +1,47 @@ +--- +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 + +## 基本介绍 + +画布节点悬停模型 + +## 方法签名 +### capture + +capture(id: string) + +hover 指定节点 + +### release + +release(id: string) + +hover 离开指定节点 + +### leave + +leave() + +清空 hover 态 + +### current +当前 hover 的节点 + +**@since v1.0.16** + +### onDetectingChange +hover 节点变化事件 + +```typescript +/** + * hover 节点变化事件 + * set callback which will be called when hovering object changed. + * @since v1.1.0 + */ +onDetectingChange(fn: (node: IPublicModelNode) => void): () => void; +``` +**@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 000000000..68efe0575 --- /dev/null +++ b/docs/docs/api/model/document-model.md @@ -0,0 +1,150 @@ +--- +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 + +## 基本介绍 + +文档模型 + +## 变量 + +### selection + +画布节点选中区模型实例，具体方法参见 [画布节点选中区模型](./selection) + +### detecting + +画布节点 hover 区模型实例，具体方法参见 [画布节点悬停模型](./detecting) + +### history + +操作历史模型实例，具体方法参见 [操作历史模型](./history) +### canvas + +获取当前画布中的一些信息，比如拖拽时的 dropLocation + +### project + +获取当前文档模型所属的 project + +### root + +获取文档的根节点 + +### nodesMap + +获取文档下所有节点 + +### modalNodesManager + +参见 [模态节点管理](./modal-nodes-manager) + +## 方法签名 +### getNodeById + +getNodeById(nodeId: string) + +根据 nodeId 返回 [Node](./node) 实例 + +### importSchema + +importSchema(schema: RootSchema) + +导入 schema +### exportSchema + +exportSchema(stage: TransformStage = TransformStage.Render) + +导出 schema + +### insertNode + +insertNode( + parent: Node, + thing: Node, + at?: number | null | undefined, + copy?: boolean | undefined, + ) + +插入节点 +### createNode + +createNode(data: any) + +创建一个节点 +### removeNode + +removeNode(idOrNode: string | Node) + +移除指定节点/节点id + +### checkNesting +检查拖拽放置的目标节点是否可以放置该拖拽对象 + +**@since v1.0.16** + +```typescript +function checkNesting(dropTarget: Node, dragObject: DragNodeObject | DragNodeDataObject): boolean {} +``` + +## 事件 +### onAddNode + +onAddNode(fn: (node: Node) => void) + +当前 document 新增节点事件 + +```typescript +import { project } from '@alilc/lowcode-engine'; + +project.currentDocument.onAddNode((node) => { + console.log('node', node); +}) +``` + +### onRemoveNode + +onRemoveNode(fn: (node: Node) => void) + +当前 document 删除节点事件 + +### onChangeDetecting + +onChangeDetecting(fn: (node: Node) => void) + +当前 document 的 hover 变更事件 + +### onChangeSelection + +onChangeSelection(fn: (ids: string[]) => void) + +当前 document 的选中变更事件 + +### onChangeNodeVisible + +onChangeNodeVisible(fn: (node: Node, visible: boolean) => void) + +当前 document 的节点显隐状态变更事件 + +### onChangeNodeChildren + +onChangeNodeChildren(fn: (info?: IPublicOnChangeOptions) => void) + +当前 document 的节点 children 变更事件 + +### onChangeNodeProp +当前 document 节点属性修改事件 + +```typescript +onChangeNodeProp(fn: (info: IPublicTypePropChangeOptions) => void) +``` + +### onImportSchema +当前 document 导入新的 schema 事件 +版本 >= 1.0.15 +```typescript +onImportSchema(fn: (schema: any) => void) +``` \ 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 000000000..82884224b --- /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?: Node | 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/history.md b/docs/docs/api/model/history.md new file mode 100644 index 000000000..5864febea --- /dev/null +++ b/docs/docs/api/model/history.md @@ -0,0 +1,58 @@ +--- +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 + +go(cursor: number) + +历史记录跳转到指定位置 + +### back + +back() + +历史记录后退 + +### forward + +forward() + +历史记录前进 +### savePoint + +savePoint() + +保存当前状态 +### isSavePoint + +isSavePoint() + +当前是否是「保存点」，即是否有状态变更但未保存 + +### getState + +getState() + +获取 state，判断当前是否为「可回退」、「可前进」的状态 + +## 事件 +### onChangeState + +onChangeState(func: () => any) + +监听 state 变更事件 + +### onChangeCursor + +onChangeCursor(func: () => any) + +监听历史记录游标位置变更事件 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 000000000..ed89ce31b --- /dev/null +++ b/docs/docs/api/model/modal-nodes-manager.md @@ -0,0 +1,48 @@ +--- +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 + +setNodes() + +设置模态节点，触发内部事件 + +### getModalNodes + +getModalNodes() + +获取模态节点（们） + +### getVisibleModalNode + +getVisibleModalNode() + +获取当前可见的模态节点 + +### hideModalNodes + +hideModalNodes() + +隐藏模态节点（们） + +### setVisible + +setVisible(node: Node) + +设置指定节点为可见态 + +### setInvisible + +setInvisible(node: Node) + +设置指定节点为不可见态 diff --git a/docs/docs/api/model/node-children.md b/docs/docs/api/model/node-children.md new file mode 100644 index 000000000..4c1b76b61 --- /dev/null +++ b/docs/docs/api/model/node-children.md @@ -0,0 +1,123 @@ +--- +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 实例所属的节点实例 + +### size + +children 内的节点实例数 + +### isEmpty + +是否为空 + +## 方法签名 +### delete + +delete(node: Node) + +删除指定节点 + +### insert + +insert(node: Node, at?: number | null) + +插入一个节点 + +### indexOf + +indexOf(node: Node) + +返回指定节点的下标 + +### splice + +splice(start: number, deleteCount: number, node?: Node) + +类似数组 splice 操作 + +### get + +get(index: number) + +返回指定下标的节点 + +### has + +has(node: Node) + +是否包含指定节点 + +### forEach + +forEach(fn: (node: Node, index: number) => void) + +类似数组的 forEach + +### map + +map(fn: (node: Node, index: number) => T[]) + +类似数组的 map + +### every + +every(fn: (node: Node, index: number) => boolean) + +类似数组的 every + +### some + +some(fn: (node: Node, index: number) => boolean) + +类似数组的 some + +### filter + +filter(fn: (node: Node, index: number) => boolean) + +类似数组的 filter + +### find + +find(fn: (node: Node, index: number) => boolean) + +类似数组的 find + +### reduce + +reduce(fn: (acc: any, cur: Node) => any, initialValue: any) + +类似数组的 reduce + +### importSchema + +importSchema(data?: NodeData | NodeData[]) + +导入 schema + +### exportSchema + +exportSchema(stage: IPulicEnumTransformStage = IPulicEnumTransformStage.Render) + +导出 schema + +### mergeChildren + +mergeChildren( + remover: (node: Node, idx: number) => boolean, + adder: (children: Node[]) => any, + sorter: (firstNode: Node, secondNode: Node) => number, + ) + +执行新增、删除、排序等操作 \ No newline at end of file diff --git a/docs/docs/api/model/node.md b/docs/docs/api/model/node.md new file mode 100644 index 000000000..cc031d040 --- /dev/null +++ b/docs/docs/api/model/node.md @@ -0,0 +1,250 @@ +--- +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 + +### title + +节点标题 + +### isContainer + +是否为「容器型」节点 + +### isRoot + +是否为根节点 + +### isEmpty + +是否为空节点（无 children 或者 children 为空） + +### isPage + +是否为 Page 节点 + +### isComponent + +是否为 Component 节点 + +### isModal + +是否为「模态框」节点 + +### isSlot + +是否为插槽节点 + +### isParental + +是否为父类/分支节点 + +### isLeaf +是否为叶子节点 + +### isLocked +获取当前节点的锁定状态 + +**@since v1.0.16** + +### isRGLContainer +设置为磁贴布局节点，使用方式可参考：[磁贴布局在钉钉宜搭报表设计引擎中的实现](https://mp.weixin.qq.com/s/PSTut5ahAB8nlJ9kBpBaxw) + +**@since v1.0.16** + +### index + +下标 + +### icon + +图标 + +### zLevel + +节点所在树的层级深度，根节点深度为 0 + +### componentName + +节点 componentName + +### componentMeta + +节点的物料元数据，参见 物料元数据 + +### document + +获取节点所属的[文档模型](./document-model)对象 + +### prevSibling + +获取当前节点的前一个兄弟节点 + +### nextSibling + +获取当前节点的后一个兄弟节点 + +### parent + +获取当前节点的父亲节点 + +### children + +获取当前节点的孩子节点模型 + +### slots + +节点上挂载的插槽节点们 + +### slotFor + +当前节点为插槽节点时，返回节点对应的属性实例 + +### props + +返回节点的属性集 + +### propsData + +返回节点的属性集值 + +## 方法签名 +### 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: IPublicEnumTransformStage = IPublicEnumTransformStage.Render, options?: any) + +导出节点数据 + +### insertBefore + +insertBefore(node: Node, ref?: Node | undefined, useMutator?: boolean) + +在指定位置之前插入一个节点 + +### insertAfter + +insertAfter(node: Node, ref?: Node | undefined, useMutator?: boolean) + +在指定位置之后插入一个节点 + +### replaceChild + +replaceChild(node: Node, data: any) + +替换指定节点 + +### replaceWith + +replaceWith(schema: NodeSchema) + +将当前节点替换成指定节点描述 + +### select + +select() + +选中当前节点实例 + +### hover + +hover(flag = true) + +设置悬停态 + +### lock +设置节点锁定状态 + +```typescript +function lock(flag?: boolean){} +``` + +**@since v1.0.16** + +### remove + +remove() + +删除当前节点实例 \ No newline at end of file diff --git a/docs/docs/api/model/prop.md b/docs/docs/api/model/prop.md new file mode 100644 index 000000000..b7832ef9f --- /dev/null +++ b/docs/docs/api/model/prop.md @@ -0,0 +1,53 @@ +--- +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 + +### key + +key 值 + +### path + +返回当前 prop 的路径 + +### node + +返回所属的节点实例 + +## 方法签名 + +### setValue + +setValue(val: CompositeValue) + +设置值 + +### getValue + +getValue() + +获取值 + +### remove +移除值 + +**@since v1.0.16** + +### exportSchema + +exportSchema(stage: IPublicEnumTransformStage = IPublicEnumTransformStage.Render) + +导出值 \ 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 000000000..5956a14b7 --- /dev/null +++ b/docs/docs/api/model/props.md @@ -0,0 +1,58 @@ +--- +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 +### path + +返回当前 props 的路径 +### node + +返回当前属性集所属的节点实例 + +## 方法签名 +### 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 的属性模型实例值 \ 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 000000000..77b33fa60 --- /dev/null +++ b/docs/docs/api/model/selection.md @@ -0,0 +1,85 @@ +--- +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 + +## 方法签名 +### 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 不会返回 + +**@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): () => void; +``` + +**@since v1.1.0** \ No newline at end of file diff --git a/docs/docs/api/plugins.md b/docs/docs/api/plugins.md index bf683b365..06b558369 100644 --- a/docs/docs/api/plugins.md +++ b/docs/docs/api/plugins.md @@ -2,25 +2,27 @@ title: plugins - 插件 API sidebar_position: 4 --- +> **@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: IPublicModelPluginContext) => IPublicTypePluginConfig, - options?: ILowCodeRegisterOptions, + plugin: IPublicTypePlugin, + options?: IPublicTypePluginRegisterOptions, ): Promise ``` -pluginConfigCreator 是一个 IPublicTypePluginConfig 生成函数，IPublicTypePluginConfig 中包含了该插件的 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)进行创建 #### 简单示例 @@ -61,59 +63,59 @@ await plugins.register(builtinPluginRegistry); import { plugins } from '@alilc/lowcode-engine'; import { IPublicModelPluginContext } from '@alilc/lowcode-types'; -const pluginA = (ctx: IPublicModelPluginContext) => { +const PluginA = (ctx: IPublicModelPluginContext) => { return { async init() {}, exports() { return { x: 1, } }, }; } -pluginA.pluginName = 'pluginA'; +PluginA.pluginName = 'PluginA'; -const pluginB = (ctx: IPublicModelPluginContext) => { +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 的上下文，具体定义参见 [IPublicModelPluginContext](#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: IPublicModelPluginContext) => { +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: IPublicModelPluginContext, options: any) => { +const BuiltinPluginRegistry = (ctx: IPublicModelPluginContext, options: any) => { return { async init() { // 1.0.4 之后的传值方式，通过 register(xxx, options) @@ -124,8 +126,8 @@ const builtinPluginRegistry = (ctx: IPublicModelPluginContext, options: any) => }, }; } -builtinPluginRegistry.pluginName = 'builtinPluginRegistry'; -builtinPluginRegistry.meta = { +BuiltinPluginRegistry.pluginName = 'BuiltinPluginRegistry'; +BuiltinPluginRegistry.meta = { preferenceDeclaration: { title: 'pluginA 的参数定义', properties: [ @@ -154,101 +156,14 @@ 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 -``` -**调用示例** -```typescript -import { plugins } from '@alilc/lowcode-engine'; +- [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) -plugins.get(builtinPluginRegistry); -``` -### -### getAll -获取所有插件实例 - -**类型定义** -```typescript -function getAll(): ILowCodePlugin[] -``` -**调用示例** -```typescript -import { plugins } from '@alilc/lowcode-engine'; - -plugins.getAll(); -``` -### -### has -判断是否已经加载了指定插件 -**类型定义** -```typescript -function has(pluginName: string): boolean -``` -**调用示例** -```typescript -import { plugins } from '@alilc/lowcode-engine'; - -plugins.has('builtinPluginRegistry'); -``` -### delete -删除指定插件 -**类型定义** -```typescript -async function delete(pluginName: string): Promise -``` -**调用示例** -```typescript -import { plugins } from '@alilc/lowcode-engine'; - -plugins.delete('builtinPluginRegistry'); -``` -## -## 事件（events） -无 -## 相关模块 -### IPublicModelPluginContext -**类型定义** -```typescript -export interface IPublicModelPluginContext { - get skeleton(): IPublicApiSkeleton; - get hotkey(): IPublicApiHotkey; - get setters(): IPublicApiSetters; - get config(): IEngineConfig; - get material(): IPublicApiMaterial; - get event(): IPublicApiEvent; - get project(): IPublicApiProject; - get common(): IPublicApiCommon; - logger: IPublicApiLogger; - plugins: IPublicApiPlugins; - preference: IPluginPreferenceMananger; -} -``` -### IPublicTypePluginConfig -**类型定义** -```typescript -export interface IPublicTypePluginConfig { - init?(): void; - destroy?(): void; - exports?(): any; -} -``` ## 插件元数据工程转化示例 your-plugin/package.json ```json @@ -279,8 +194,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 64400cf2a..0a22cd920 100644 --- a/docs/docs/api/project.md +++ b/docs/docs/api/project.md @@ -2,880 +2,316 @@ title: project - 模型 API sidebar_position: 3 --- -# 模块简介 -引擎编排模块中包含多种模型，包括[项目模型（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） -## 变量（variables） +整个模型系统，以 project API 为入口，所有模型实例均需要通过 project 来获得，比如 project.currentDocument 来获取当前的文档模型，project.currentDocument.nodesMap 来获取当前文档模型里所有的节点列表。 + +下面来看看 project API 的具体介绍 + +## 变量 ### 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 +```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 -createDocument(data?: RootSchema): DocumentModel | null - 创建一个 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 +```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 -getDocumentByFileName(fileName: string): DocumentModel | null - 根据 fileName 获取 document +```typescript +/** + * 根据 fileName 获取 document + * get a document by filename + * @param fileName + * @returns + */ +getDocumentByFileName(fileName: string): IPublicModelDocumentModel | null; +``` + +相关类型：[IPublicApiSimulatorHost](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/api/simulator-host.ts) ### getDocumentById -getDocumentById(id: string): DocumentModel | null - 根据 id 获取 document +```typescript +/** + * 根据 id 获取 document + * get a document by id + * @param id + * @returns + */ +getDocumentById(id: string): IPublicModelDocumentModel | null; +``` + +相关类型：[IPublicApiSimulatorHost](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/api/simulator-host.ts) + ### exportSchema -exportSchema() +导出 project schema -导出 project +```typescript +/** + * 导出 project + * export project to schema + * @returns + */ +exportSchema(stage: IPublicEnumTransformStage): IPublicTypeProjectSchema; +``` + +相关类型： +- [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) ### importSchema -importSchema(schema?: ProjectSchema) - 导入 project +```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) + ### getCurrentDocument - -getCurrentDocument(): DocumentModel | null - 获取当前的 document +```typescript +/** + * 获取当前的 document + * get current document + * @returns + */ +getCurrentDocument(): IPublicModelDocumentModel | null; +``` +相关类型：[IPublicModelDocumentModel](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/model/document-model.ts) + ### addPropsTransducer - -addPropsTransducer(transducer: PropsTransducer, stage: TransformStage) - 增加一个属性的管道处理函数 -**示例 1：在保存的时候删除每一个组件的 props.hidden** +```typescript +/** + * 增加一个属性的管道处理函数 + * 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 { CompositeObject, TransformStage, IPublicModelPluginContext } from '@alilc/lowcode-types'; +import { IPublicTypeCompositeObject, IPublicEnumTransformStage, IPublicModelPluginContext } from '@alilc/lowcode-types'; -export const deleteHiddenTransducer = (ctx: IPublicModelPluginContext) => { +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'; ``` +### setI18n +设置多语言语料 + +```typescript +/** + * 设置多语言语料 + * 数据格式参考 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; +``` + +**@since v1.0.17** + + +## 事件 + ### onRemoveDocument 绑定删除文档事件 -```typescript -function onRemoveDocument(fn: (data: { docId: string}) => void) {} -``` -*引擎版本>=1.0.16 -### setI18n -设置多语言语料 -```typescript -function setI18n(value: object) {} -``` -*引擎版本>=1.0.17 -## 事件（events） -### onChangeDocument -onChangeDocument(fn: (doc: DocumentModel) => void) +```typescript +/** + * 绑定删除文档事件 + * 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) + +**@since v1.0.16** + +### onChangeDocument 当前 project 内的 document 变更事件 -### onSimulatorHostReady +```typescript +/** + * 当前 project 内的 document 变更事件 + * set callback for event onDocumentChanged + */ +onChangeDocument(fn: (doc: IPublicModelDocumentModel) => void): IPublicTypeDisposable; +``` -onSimulatorHostReady(fn: (host: SimulatorHost) => void) +相关类型： +- [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) + +### onSimulatorHostReady 当前 project 的模拟器 ready 事件 +```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 -onSimulatorRendererReady(fn: () => void) - 当前 project 的渲染器 ready 事件 -# -# 文档模型（DocumentModel） -## 变量（variables） -### selection - -画布节点选中区模型实例，具体方法参见 [画布节点选中区模型](#GtFkP) - -### detecting - -画布节点 hover 区模型实例，具体方法参见 [画布节点 hover 区模型](#Tjt05) - -### history - -操作历史模型实例，具体方法参见 [操作历史模型](#xvIKj) -### canvas - -获取当前画布中的一些信息，比如拖拽时的 dropLocation - -### project - -获取当前文档模型所属的 project - -### root - -获取文档的根节点 - -### nodesMap - -获取文档下所有节点 - -### modalNodesManager - -参见 [模态节点管理](#nNRF9) - -## 方法签名（functions） -### getNodeById - -getNodeById(nodeId: string) - -根据 nodeId 返回 [Node](#m0cJS) 实例 - -### importSchema - -importSchema(schema: RootSchema) - -导入 schema -### exportSchema - -exportSchema(stage: TransformStage = TransformStage.Render) - -导出 schema - -### insertNode - -insertNode( - parent: Node, - thing: Node, - at?: number | null | undefined, - copy?: boolean | undefined, - ) - -插入节点 -### createNode - -createNode(data: any) - -创建一个节点 -### removeNode - -removeNode(idOrNode: string | Node) - -移除指定节点/节点id - -### checkNesting -检查拖拽放置的目标节点是否可以放置该拖拽对象 -*引擎版本 > 1.0.16 -```typescript -function checkNesting(dropTarget: Node, dragObject: DragNodeObject | DragNodeDataObject): boolean {} -``` -## -## 事件（events） -### onAddNode - -onAddNode(fn: (node: Node) => void) - -当前 document 新增节点事件 ```typescript -import { project } from '@alilc/lowcode-engine'; - -project.currentDocument.onAddNode((node) => { - console.log('node', node); -}) +/** + * 当前 project 的渲染器 ready 事件 + * set callback for event onSimulatorRendererReady + */ +onSimulatorRendererReady(fn: () => void): IPublicTypeDisposable; ``` -### 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) -``` - -### onImportSchema -当前 document 导入新的 schema 事件 -版本 >= 1.0.15 -```typescript -onImportSchema(fn: (schema: any) => void) -``` - -# 画布节点选中模型（Selection） -## 变量（variables） -### selected - -返回选中的节点 id - -## 方法签名（functions） -### select - -select(id: string) - -选中指定节点（覆盖方式） - -### selectAll - -selectAll(ids: string[]) - -批量选中指定节点们 - -### remove - -remove(id: string) - -**取消选中**选中的指定节点，不会删除组件 - -### clear - -clear() - -**取消选中**所有选中节点，不会删除组件 - -### has - -has(id: string) - -判断是否选中了指定节点 - -### add - -add(id: string) - -选中指定节点（增量方式） - -### getNodes - -getNodes() - -获取选中的节点实例 - -### getTopNodes -获取选区的顶层节点 -例如选中的节点为： - -- DivA - - ChildrenA -- DivB - -getNodes 返回的是 [DivA、ChildrenA、DivB]，getTopNodes 返回的是 [DivA、DivB]，其中 ChildrenA 由于是二层节点，getTopNodes 不会返回 - -*引擎版本 >= 1.0.16 - - -# 画布节点悬停模型（Detecting） -## 方法签名（functions） -### capture - -capture(id: string) - -hover 指定节点 - -### release - -release(id: string) - -hover 离开指定节点 - -### leave - -leave() - -清空 hover 态 - -### current -当前 hover 的节点 -*引擎版本 >= 1.0.16 - -# 操作历史记录模型（History） -## 方法签名（functions） -### go - -go(cursor: number) - -历史记录跳转到指定位置 - -### back - -back() - -历史记录后退 - -### forward - -forward() - -历史记录前进 -### savePoint - -savePoint() - -保存当前状态 -### isSavePoint - -isSavePoint() - -当前是否是「保存点」，即是否有状态变更但未保存 - -### getState - -getState() - -获取 state，判断当前是否为「可回退」、「可前进」的状态 - -## 事件（events） -### onChangeState - -onChangeState(func: () => any) - -监听 state 变更事件 - -### onChangeCursor - -onChangeCursor(func: () => any) - -监听历史记录游标位置变更事件 - -# 节点模型（Node） -## 变量（variables） -### id - -节点 id - -### title - -节点标题 - -### isContainer - -是否为「容器型」节点 - -### isRoot - -是否为根节点 - -### isEmpty - -是否为空节点（无 children 或者 children 为空） - -### isPage - -是否为 Page 节点 - -### isComponent - -是否为 Component 节点 - -### isModal - -是否为「模态框」节点 - -### isSlot - -是否为插槽节点 - -### isParental - -是否为父类/分支节点 - -### isLeaf -是否为叶子节点 - -### isLocked -获取当前节点的锁定状态 -*引擎版本>=1.0.16 - -### isRGLContainer -设置为磁贴布局节点，使用方式可参考：[磁贴布局在钉钉宜搭报表设计引擎中的实现](https://mp.weixin.qq.com/s/PSTut5ahAB8nlJ9kBpBaxw) -*引擎版本>=1.0.16 - -### index - -下标 - -### icon - -图标 - -### zLevel - -节点所在树的层级深度，根节点深度为 0 - -### componentName - -节点 componentName - -### componentMeta - -节点的物料元数据，参见 物料元数据 - -### document - -获取节点所属的[文档模型](#lp7xO)对象 - -### prevSibling - -获取当前节点的前一个兄弟节点 - -### nextSibling - -获取当前节点的后一个兄弟节点 - -### parent - -获取当前节点的父亲节点 - -### children - -获取当前节点的孩子节点模型 - -### slots - -节点上挂载的插槽节点们 - -### slotFor - -当前节点为插槽节点时，返回节点对应的属性实例 - -### props - -返回节点的属性集 - -### propsData - -返回节点的属性集值 - -## 方法签名（functions） -### getDOMNode - -getDOMNode() - -获取节点实例对应的 dom 节点 - -### getRect - -getRect() - -返回节点的尺寸、位置信息 - -### hasSlots - -hasSlots() - -是否有挂载插槽节点 - -### hasCondition - -hasCondition() - -是否设定了渲染条件 - -### hasLoop - -hasLoop() - -是否设定了循环数据 - -### getProp - -getProp(path: string): Prop | null - -获取指定 path 的属性模型实例 - -### getPropValue - -getPropValue(path: string) - -获取指定 path 的属性模型实例值 - -### getExtraProp - -getExtraProp(path: string): Prop | null - -获取指定 path 的属性模型实例，注：导出时，不同于普通属性，该属性并不挂载在 props 之下，而是与 props 同级 - -### getExtraPropValue - -getExtraPropValue(path: string) - -获取指定 path 的属性模型实例，注：导出时，不同于普通属性，该属性并不挂载在 props 之下，而是与 props 同级 - -### setPropValue - -setPropValue(path: string, value: CompositeValue) - -设置指定 path 的属性模型实例值 - -### setExtraPropValue - -setExtraPropValue(path: string, value: CompositeValue) - -设置指定 path 的属性模型实例值 - -### importSchema - -importSchema(data: NodeSchema) - -导入节点数据 - -### exportSchema - -exportSchema(stage: TransformStage = TransformStage.Render, options?: any) - -导出节点数据 - -### insertBefore - -insertBefore(node: Node, ref?: Node | undefined, useMutator?: boolean) - -在指定位置之前插入一个节点 - -### insertAfter - -insertAfter(node: Node, ref?: Node | undefined, useMutator?: boolean) - -在指定位置之后插入一个节点 - -### replaceChild - -replaceChild(node: Node, data: any) - -替换指定节点 - -### replaceWith - -replaceWith(schema: NodeSchema) - -将当前节点替换成指定节点描述 - -### select - -select() - -选中当前节点实例 - -### hover - -hover(flag = true) - -设置悬停态 - -### lock -设置节点锁定状态 -```typescript -function lock(flag?: boolean){} -``` -*引擎版本>=1.0.16 - -### remove - -remove() - -删除当前节点实例 - -# 节点孩子模型（NodeChildren） -## 变量（variables） -### owner - -返回当前 children 实例所属的节点实例 - -### size - -children 内的节点实例数 - -### isEmpty - -是否为空 - -## 方法签名（functions） -### delete - -delete(node: Node) - -删除指定节点 - -### insert - -insert(node: Node, at?: number | null) - -插入一个节点 - -### indexOf - -indexOf(node: Node) - -返回指定节点的下标 - -### splice - -splice(start: number, deleteCount: number, node?: Node) - -类似数组 splice 操作 - -### get - -get(index: number) - -返回指定下标的节点 - -### has - -has(node: Node) - -是否包含指定节点 - -### forEach - -forEach(fn: (node: Node, index: number) => void) - -类似数组的 forEach - -### map - -map(fn: (node: Node, index: number) => T[]) - -类似数组的 map - -### every - -every(fn: (node: Node, index: number) => boolean) - -类似数组的 every - -### some - -some(fn: (node: Node, index: number) => boolean) - -类似数组的 some - -### filter - -filter(fn: (node: Node, index: number) => boolean) - -类似数组的 filter - -### find - -find(fn: (node: Node, index: number) => boolean) - -类似数组的 find - -### reduce - -reduce(fn: (acc: any, cur: Node) => any, initialValue: any) - -类似数组的 reduce - -### importSchema - -importSchema(data?: NodeData | NodeData[]) - -导入 schema - -### exportSchema - -exportSchema(stage: TransformStage = TransformStage.Render) - -导出 schema - -### mergeChildren - -mergeChildren( - remover: (node: Node, idx: number) => boolean, - adder: (children: Node[]) => any, - sorter: (firstNode: Node, secondNode: Node) => number, - ) - -执行新增、删除、排序等操作 - -# 属性集模型（Props） -## 变量（variables） -### id - -id -### path - -返回当前 props 的路径 -### node - -返回当前属性集所属的节点实例 - -## 方法签名（functions） -### getProp - -getProp(path: string): Prop | null - -获取指定 path 的属性模型实例 - -### getPropValue - -getPropValue(path: string) - -获取指定 path 的属性模型实例值 - -### getExtraProp - -getExtraProp(path: string): Prop | null - -获取指定 path 的属性模型实例，注：导出时，不同于普通属性，该属性并不挂载在 props 之下，而是与 props 同级 -### getExtraPropValue - -getExtraPropValue(path: string) - -获取指定 path 的属性模型实例值，注：导出时，不同于普通属性，该属性并不挂载在 props 之下，而是与 props 同级 -### - -### setPropValue - -setPropValue(path: string, value: CompositeValue) - -设置指定 path 的属性模型实例值 - -### setExtraPropValue - -setExtraPropValue(path: string, value: CompositeValue) - -设置指定 path 的属性模型实例值 - -# 属性模型（Prop） -## 变量（variables） -### id - -id - -### key - -key 值 - -### path - -返回当前 prop 的路径 - -### node - -返回所属的节点实例 - -## 方法签名（functions） -### setValue - -setValue(val: CompositeValue) - -设置值 - -### getValue - -getValue() - -获取值 - -### remove -移除值 -*引擎版本>=1.0.16 - -### exportSchema - -exportSchema(stage: TransformStage = TransformStage.Render) - -导出值 - -# 模态节点管理模型（ModalNodesManager） -## 方法签名（functions） -### getModalNodes - -getModalNodes() - -获取模态节点（们） - -### getVisibleModalNode - -getVisibleModalNode() - -获取当前可见的模态节点 - -### hideModalNodes - -hideModalNodes() - -隐藏模态节点（们） - -### setVisible - -setVisible(node: Node) - -设置指定节点为可见态 - -### setInvisible - -setInvisible(node: Node) - -设置指定节点为不可见态 - -### setNodes - -setNodes() - -设置模态节点，触发内部事件 +相关类型：[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 b36d7162d..3c5fd9f75 100644 --- a/docs/docs/api/setters.md +++ b/docs/docs/api/setters.md @@ -2,37 +2,64 @@ title: setters - 设置器 API sidebar_position: 6 --- +> **@types** [IPublicApiSetters](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/api/setters.ts)
+> **@since** v1.0.0 + ## 模块简介 负责注册设置器、管理设置器的 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 @@ -40,7 +67,7 @@ import { setters, skeleton } from '@alilc/lowcode-engine'; import { setterMap, pluginMap } from '@alilc/lowcode-engine-ext'; import { IPublicModelPluginContext } from '@alilc/lowcode-types'; -const setterRegistry = (ctx: IPublicModelPluginContext) => { +const SetterRegistry = (ctx: IPublicModelPluginContext) => { return { name: 'ext-setters-registry', async init() { @@ -68,8 +95,8 @@ const setterRegistry = (ctx: IPublicModelPluginContext) => { }; } -setterRegistry.pluginName = 'setterRegistry'; -await plugins.register(setterRegistry); +SetterRegistry.pluginName = 'SetterRegistry'; +await plugins.register(SetterRegistry); ``` ### 开发自定义 Setter @@ -112,182 +139,13 @@ export default class AltStringSetter extends React.PureComponent -``` - -### 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'; -import { IPublicModelPluginContext } from '@alilc/lowcode-types'; - -const setterRegistry = (ctx: IPublicModelPluginContext) => { - return { - name: 'ext-setters-registry', - async init() { - // 注册 setterMap - setters.registerSetter(setterMap); - // 注册插件 - // 注册事件绑定面板 - skeleton.add({ - area: 'centerArea', - type: 'Widget', - content: pluginMap.EventBindDialog, - name: 'eventBindDialog', - props: {}, - }); - - // 注册变量绑定面板 - skeleton.add({ - area: 'centerArea', - type: 'Widget', - content: pluginMap.VariableBindDialog, - name: 'variableBindDialog', - props: {}, - }); - }, - }; -} - -setterRegistry.pluginName = 'setterRegistry'; -await plugins.register(setterRegistry); -``` - -### 开发自定义 Setter -AltStringSetter 代码如下： -```typescript -import * as React from "react"; -import { Input } from "@alifd/next"; - -import "./index.scss"; -interface AltStringSetterProps { - // 当前值 - value: string; - // 默认值 - initialValue: string; - // setter 唯一输出 - onChange: (val: string) => void; - // AltStringSetter 特殊配置 - placeholder: string; -} -export default class AltStringSetter extends React.PureComponent { - componentDidMount() { - const { onChange, value, defaultValue } = this.props; - if (value == undefined && defaultValue) { - onChange(defaultValue); - } - } - - // 声明 Setter 的 title - static displayName = 'AltStringSetter'; - - render() { - const { onChange, value, placeholder } = this.props; - return ( - onChange(val)} - > - ); - } -} -``` -开发完毕之后，注册 AltStringSetter 到设计器中： -```typescript -import AltStringSetter from './AltStringSetter'; -const registerSetter = window.AliLowCodeEngine.setters.registerSetter; +import { setters } from '@alilc/lowcode-engine'; +const { registerSetter } = registerSetter; registerSetter('AltStringSetter', AltStringSetter); ``` 注册之后，我们就可以在物料中使用了，其中核心配置如下： diff --git a/docs/docs/api/simulatorHost.md b/docs/docs/api/simulatorHost.md index fc0009d3a..b30a61499 100644 --- a/docs/docs/api/simulatorHost.md +++ b/docs/docs/api/simulatorHost.md @@ -2,11 +2,25 @@ title: simulatorHost - 模拟器 API sidebar_position: 3 --- -# 模块简介 +> **@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 -project.simulatorHost.get('device'); +/** + * 获取模拟器中设置的变量，比如画布大小、locale 等。 + * set config value by key + * @param key + * @returns + */ +get(key: string): any; + ``` -## rerender +### rerender 刷新渲染画布 + +```typescript +/** + * 刷新渲染画布 + * make simulator render again + */ +rerender(): void; +``` + +### 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 1ae573e7e..5ad82accf 100644 --- a/docs/docs/api/skeleton.md +++ b/docs/docs/api/skeleton.md @@ -2,6 +2,10 @@ title: skeleton - 面板 API sidebar_position: 1 --- +> **@types** [IPublicApiSkeleton](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/api/skeleton.ts)
+> **@since** v1.0.0 + + ## 模块简介 面板 API 提供了面板扩展和管理的能力，如下图蓝色内容都是扩展出来的。 @@ -131,21 +135,24 @@ skeleton.add({ }); ``` -## 变量（variables） +## 方法签名 -无 -## 方法签名（functions） - -### 1. add - -```tsx -add(config: IWidgetBaseConfig & { - area?: string; -}, extraConfig?: object): IWidget | Panel; -``` +### add 往指定扩展区加入一块面板 +```typescript +/** + * 增加一个面板实例 + * add a new panel + * @param config + * @param extraConfig + * @returns + */ +add(config: IPublicTypeWidgetBaseConfig, extraConfig?: Record): any; +``` + + IWidgetBaseConfig 定义如下： | 属性名 | 含义 | 备注 | @@ -160,74 +167,181 @@ 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) + +### showPanel 展示指定 Panel 实例 -### 4. hidePanel +```typescript +/** + * 展示指定 Panel 实例 + * show panel by name + * @param name + */ +showPanel(name: string): void; +``` -hidePanel(name: string) +### hidePanel +隐藏面板 -### 5. showWidget +```typescript +/** + * 隐藏面板 + * hide panel by name + * @param name + */ +hidePanel(name: string): void; +``` -showWidget(name: string) +### showWidget 展示指定 Widget 实例 -### 6. hideWidget +```typescript +/** + * 展示指定 Widget 实例 + * show widget by name + * @param name + */ +showWidget(name: string): void; +``` -hideWidget(name: string) +### enableWidget +将 widget 启用。 +```typescript +/** + * 将 widget 启用 + * enable widget + * @param name + */ +enableWidget(name: string): void; +``` + +### hideWidget 隐藏指定 widget 实例。 -### 7. enableWidget +```typescript +/** + * 隐藏指定 widget 实例 + * hide widget by name + * @param name + */ +hideWidget(name: string): void; +``` -enableWidget(name: string) - -将 widget 启用。 - -注：该函数将会触发全局事件 'skeleton.widget.enable' - -### 8. disableWidget - -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; +``` -onShowPanel(listener: (...args: unknown[]) => 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; +``` +## 事件 +### onShowPanel 监听 Panel 实例显示事件 -### 2. onHidePanel +```typescript +/** + * 监听 panel 显示事件 + * set callback for panel shown event + * @param listener + * @returns + */ +onShowPanel(listener: (...args: any[]) => void): () => void; +``` -onHidePanel(listener: (...args: unknown[]) => void) +### onHidePanel 监听 Panel 实例隐藏事件 -### 3. onShowWidget +```typescript +/** + * 监听 Panel 实例隐藏事件 + * set callback for panel hidden event + * @param listener + * @returns + */ +onHidePanel(listener: (...args: any[]) => void): () => void; +``` -onShowWidget(listener: (...args: unknown[]) => void) + +### onShowWidget 监听 Widget 实例显示事件 -### 4. onHideWidget +```typescript +/** + * 监听 Widget 显示事件 + * set callback for widget shown event + * @param listener + * @returns + */ +onShowWidget(listener: (...args: any[]) => void): () => void; +``` -onHideWidget(listener: (...args: unknown[]) => void) + +### onHideWidget 监听 Widget 实例隐藏事件 + +```typescript +/** + * 监听 Widget 隐藏事件 + * set callback for widget hidden event + * @param listener + * @returns + */ +onHideWidget(listener: (...args: any[]) => void): () => void; +``` + ## 使用示例 ```typescript diff --git a/docs/scripts/getDocsFromDir.js b/docs/scripts/getDocsFromDir.js index 1d3236fe6..666d92c3c 100644 --- a/docs/scripts/getDocsFromDir.js +++ b/docs/scripts/getDocsFromDir.js @@ -9,7 +9,8 @@ module.exports = function getDocsFromDir(dir, cateList) { const docsDir = path.join(baseDir, dir); function getMarkdownOrder(filepath) { - return (matter(fs.readFileSync(filepath, 'utf-8')).data || {}).order || 100; + const data = matter(fs.readFileSync(filepath, 'utf-8')).data; + return (data || {}).sidebar_position || 100; } const docs = glob.sync('*.md?(x)', { @@ -26,7 +27,7 @@ module.exports = function getDocsFromDir(dir, cateList) { const orderA = getMarkdownOrder(a); const orderB = getMarkdownOrder(b); - return orderA - orderB; + return orderB - orderA; }) .map(filepath => { // /Users/xxx/site/docs/guide/basic/router.md => guide/basic/router diff --git a/docs/scripts/sync-oss.js b/docs/scripts/sync-oss.js index 407f113bd..8ab9402e8 100644 --- a/docs/scripts/sync-oss.js +++ b/docs/scripts/sync-oss.js @@ -5,7 +5,7 @@ const { version, name } = package; const options = { method: 'PUT', // 暂时使用 日常环境的 uipaas-node，上线后可切换成线上环境 https://uipaas-node.alibaba-inc.com - hostname: 'uipaas-node.alibaba.net', + hostname: 'uipaas-node.alibaba-inc.com', path: '/staticAssets/cdn/packages', headers: { 'Content-Type': 'application/json', diff --git a/packages/designer/src/plugin/plugin-manager.ts b/packages/designer/src/plugin/plugin-manager.ts index 456124397..449afebdf 100644 --- a/packages/designer/src/plugin/plugin-manager.ts +++ b/packages/designer/src/plugin/plugin-manager.ts @@ -15,7 +15,7 @@ import { invariant } from '../utils'; import sequencify from './sequencify'; import semverSatisfies from 'semver/functions/satisfies'; import { - ILowCodeRegisterOptions, + IPublicTypePluginRegisterOptions, IPublicTypePreferenceValueType, IPublicTypePlugin, } from '@alilc/lowcode-types'; @@ -65,7 +65,7 @@ export class LowCodePluginManager implements ILowCodePluginManager { async register( pluginModel: IPublicTypePlugin, options?: any, - registerOptions?: ILowCodeRegisterOptions, + registerOptions?: IPublicTypePluginRegisterOptions, ): Promise { // registerOptions maybe in the second place if (isLowCodeRegisterOptions(options)) { diff --git a/packages/designer/src/plugin/plugin-utils.ts b/packages/designer/src/plugin/plugin-utils.ts index 21e142ab7..7d8ab8db9 100644 --- a/packages/designer/src/plugin/plugin-utils.ts +++ b/packages/designer/src/plugin/plugin-utils.ts @@ -1,5 +1,5 @@ import { isPlainObject } from 'lodash'; -import { ILowCodeRegisterOptions, IPublicTypePluginDeclaration } from '@alilc/lowcode-types'; +import { IPublicTypePluginRegisterOptions, IPublicTypePluginDeclaration } from '@alilc/lowcode-types'; export function isValidPreferenceKey( key: string, @@ -13,7 +13,7 @@ export function isValidPreferenceKey( }); } -export function isLowCodeRegisterOptions(opts: any): opts is ILowCodeRegisterOptions { +export function isLowCodeRegisterOptions(opts: any): opts is IPublicTypePluginRegisterOptions { return opts && ('autoInit' in opts || 'override' in opts); } diff --git a/packages/designer/src/project/project.ts b/packages/designer/src/project/project.ts index a056c37bf..08b96d7c4 100644 --- a/packages/designer/src/project/project.ts +++ b/packages/designer/src/project/project.ts @@ -5,7 +5,6 @@ import { IPublicTypeProjectSchema, IPublicTypeRootSchema, IPublicTypeComponentsMap, - TransformStage, IPublicApiProject, IPublicModelDocumentModel, IPublicEnumTransformStage, diff --git a/packages/editor-core/src/config.ts b/packages/editor-core/src/config.ts index d8d5ff3c9..344529690 100644 --- a/packages/editor-core/src/config.ts +++ b/packages/editor-core/src/config.ts @@ -3,7 +3,7 @@ import { isPlainObject } from '@alilc/lowcode-utils'; import { EngineOptions, IPublicModelEngineConfig, - IPreference, + IPublicModelPreference, } from '@alilc/lowcode-types'; import { getLogger } from './utils/logger'; import Preference from './utils/preference'; @@ -193,7 +193,7 @@ export class EngineConfig implements IPublicModelEngineConfig, IEngineConfigPriv * used to store preferences * */ - readonly preference: IPreference; + readonly preference: IPublicModelPreference; constructor(config?: { [key: string]: any }) { this.config = config || {}; @@ -349,7 +349,7 @@ export class EngineConfig implements IPublicModelEngineConfig, IEngineConfigPriv } } - getPreference(): IPreference { + getPreference(): IPublicModelPreference { return this.preference; } } diff --git a/packages/editor-core/src/utils/preference.ts b/packages/editor-core/src/utils/preference.ts index b5693a514..0ee852bd7 100644 --- a/packages/editor-core/src/utils/preference.ts +++ b/packages/editor-core/src/utils/preference.ts @@ -1,6 +1,6 @@ import store from 'store'; import { getLogger } from './logger'; -import { IPreference } from '@alilc/lowcode-types'; +import { IPublicModelPreference } from '@alilc/lowcode-types'; const logger = getLogger({ level: 'log', bizName: 'Preference' }); const STORAGE_KEY_PREFIX = 'ale'; @@ -12,7 +12,7 @@ const STORAGE_KEY_PREFIX = 'ale'; * * @class PreferenceStore */ -export default class Preference implements IPreference { +export default class Preference implements IPublicModelPreference { getStorageKey(key: string, module?: string): string { const moduleKey = module || '__inner__'; return `${STORAGE_KEY_PREFIX}_${moduleKey}.${key}`; diff --git a/packages/shell/src/api/common.tsx b/packages/shell/src/api/common.tsx index d1bd7afa0..c77b80610 100644 --- a/packages/shell/src/api/common.tsx +++ b/packages/shell/src/api/common.tsx @@ -17,13 +17,13 @@ import { IPublicTypeNodeSchema, IPublicEnumTransitionType, IPublicEnumTransformStage as InnerTransitionStage, - IPublicCommonDesignerCabin, - IPublicCommonSkeletonCabin, - IPublicCommonUtils, + IPublicApiCommonDesignerCabin, + IPublicApiCommonSkeletonCabin, + IPublicApiCommonUtils, IPublicApiCommon, IPublicEnumDragObjectType as InnerDragObjectType, IPublicTypeLocationDetailType as InnerLocationDetailType, - IPublicCommonEditorCabin, + IPublicApiCommonEditorCabin, IPublicModelDragon, IDesigner, } from '@alilc/lowcode-types'; @@ -61,7 +61,7 @@ import { import { Dragon } from '../model'; import { ReactNode, Component } from 'react'; -class DesignerCabin implements IPublicCommonDesignerCabin { +class DesignerCabin implements IPublicApiCommonDesignerCabin { private readonly [editorSymbol]: Editor; /** * @deprecated @@ -150,10 +150,9 @@ class DesignerCabin implements IPublicCommonDesignerCabin { get dragon(): IPublicModelDragon | null { return Dragon.create(this[designerSymbol].dragon); } - } -class SkeletonCabin implements IPublicCommonSkeletonCabin { +class SkeletonCabin implements IPublicApiCommonSkeletonCabin { private readonly [skeletonSymbol]: InnerSkeleton; constructor(skeleton: InnerSkeleton) { @@ -187,7 +186,7 @@ class SkeletonCabin implements IPublicCommonSkeletonCabin { } } -class Utils implements IPublicCommonUtils { +class Utils implements IPublicApiCommonUtils { isNodeSchema(data: any): data is IPublicTypeNodeSchema { return innerIsNodeSchema(data); } @@ -196,11 +195,17 @@ class Utils implements IPublicCommonUtils { return innerIsFormEvent(e); } + /** + * @deprecated this is a legacy api, do not use this if not using is already + */ compatibleLegaoSchema(props: any): any { return innerCompatibleLegaoSchema(props); } - getNodeSchemaById(schema: IPublicTypeNodeSchema, nodeId: string): IPublicTypeNodeSchema | undefined { + getNodeSchemaById( + schema: IPublicTypeNodeSchema, + nodeId: string, + ): IPublicTypeNodeSchema | undefined { return innerGetNodeSchemaById(schema, nodeId); } @@ -212,7 +217,10 @@ class Utils implements IPublicCommonUtils { return innerGetOriginalExtraKey(key); } - executeTransaction(fn: () => void, type: IPublicEnumTransitionType = IPublicEnumTransitionType.REPAINT): void { + executeTransaction( + fn: () => void, + type: IPublicEnumTransitionType = IPublicEnumTransitionType.REPAINT, + ): void { transactionManager.executeTransaction(fn, type); } @@ -226,7 +234,7 @@ class Utils implements IPublicCommonUtils { } } -class EditorCabin implements IPublicCommonEditorCabin { +class EditorCabin implements IPublicApiCommonEditorCabin { private readonly [editorSymbol]: Editor; constructor(editor: Editor) { @@ -234,6 +242,7 @@ class EditorCabin implements IPublicCommonEditorCabin { } /** * Title 组件 + * @experimental unstable API, pay extra caution when trying to use this */ get Title(): Component { return InnerTitle; @@ -241,6 +250,7 @@ class EditorCabin implements IPublicCommonEditorCabin { /** * Tip 组件 + * @experimental unstable API, pay extra caution when trying to use this */ get Tip(): Component { return InnerTip; diff --git a/packages/shell/src/api/material.ts b/packages/shell/src/api/material.ts index 584cfa1e5..e824290a5 100644 --- a/packages/shell/src/api/material.ts +++ b/packages/shell/src/api/material.ts @@ -15,10 +15,12 @@ import { IPublicApiMaterial, IPublicTypeMetadataTransducer, IPublicModelComponentMeta, + IPublicTypeNpmInfo, } from '@alilc/lowcode-types'; import { Workspace } from '@alilc/lowcode-workspace'; import { editorSymbol, designerSymbol } from '../symbols'; import { ComponentMeta } from '../model/component-meta'; +import { ComponentType } from 'react'; const innerEditorSymbol = Symbol('editor'); export class Material implements IPublicApiMaterial { @@ -47,7 +49,7 @@ export class Material implements IPublicApiMaterial { /** * 获取组件 map 结构 */ - get componentsMap() { + get componentsMap(): { [key: string]: IPublicTypeNpmInfo | ComponentType | object } { return this[designerSymbol].componentsMap; } @@ -173,6 +175,6 @@ export class Material implements IPublicApiMaterial { // 设置 assets，经过 setAssets 赋值 this[editorSymbol].onGot('assets', fn); // 增量设置 assets，经过 loadIncrementalAssets 赋值 - this[editorSymbol].on('designer.incrementalAssetsReady', fn); + this[editorSymbol].eventBus.on('designer.incrementalAssetsReady', fn); } } diff --git a/packages/shell/src/api/plugins.ts b/packages/shell/src/api/plugins.ts index 60a66fb45..8a0a506e5 100644 --- a/packages/shell/src/api/plugins.ts +++ b/packages/shell/src/api/plugins.ts @@ -5,7 +5,7 @@ import { globalContext } from '@alilc/lowcode-editor-core'; import { IPublicApiPlugins, IPublicTypePlugin, - ILowCodeRegisterOptions, + IPublicTypePluginRegisterOptions, IPublicTypePreferenceValueType, } from '@alilc/lowcode-types'; import { pluginsSymbol } from '../symbols'; @@ -32,7 +32,7 @@ export class Plugins implements IPublicApiPlugins { async register( pluginModel: IPublicTypePlugin, options?: any, - registerOptions?: ILowCodeRegisterOptions, + registerOptions?: IPublicTypePluginRegisterOptions, ): Promise { await this[pluginsSymbol].register(pluginModel, options, registerOptions); } diff --git a/packages/shell/src/api/project.ts b/packages/shell/src/api/project.ts index f083bc7e8..31c3277d4 100644 --- a/packages/shell/src/api/project.ts +++ b/packages/shell/src/api/project.ts @@ -13,6 +13,7 @@ import { IPublicTypePropsTransducer, IPublicEnumEventNames, IPublicEnumTransformStage, + IPublicTypeDisposable, } from '@alilc/lowcode-types'; @@ -163,7 +164,7 @@ export class Project implements IPublicApiProject { * @param fn * @returns */ - onRemoveDocument(fn: (data: { id: string}) => void): any { + onRemoveDocument(fn: (data: { id: string}) => void): IPublicTypeDisposable { return this[editorSymbol].eventBus.on( IPublicEnumEventNames.DESIGNER_DOCUMENT_REMOVE, (data: { id: string }) => fn(data), @@ -173,7 +174,7 @@ export class Project implements IPublicApiProject { /** * 当前 project 内的 document 变更事件 */ - onChangeDocument(fn: (doc: IPublicModelDocumentModel) => void) { + onChangeDocument(fn: (doc: IPublicModelDocumentModel) => void): IPublicTypeDisposable { const offFn = this[projectSymbol].onCurrentDocumentChange((originalDoc) => { fn(DocumentModel.create(originalDoc)!); }); @@ -186,7 +187,7 @@ export class Project implements IPublicApiProject { /** * 当前 project 的模拟器 ready 事件 */ - onSimulatorHostReady(fn: (host: IPublicApiSimulatorHost) => void) { + onSimulatorHostReady(fn: (host: IPublicApiSimulatorHost) => void): IPublicTypeDisposable { const offFn = this[projectSymbol].onSimulatorReady((simulator: BuiltinSimulatorHost) => { this[simulatorHostSymbol] = simulator; fn(SimulatorHost.create(simulator)!); @@ -200,7 +201,7 @@ export class Project implements IPublicApiProject { /** * 当前 project 的渲染器 ready 事件 */ - onSimulatorRendererReady(fn: () => void) { + onSimulatorRendererReady(fn: () => void): IPublicTypeDisposable { const offFn = this[projectSymbol].onRendererReady((renderer: any) => { this[simulatorRendererSymbol] = renderer; fn(); diff --git a/packages/types/src/engine-config.ts b/packages/types/src/engine-config.ts index eed9e021d..4c97433fb 100644 --- a/packages/types/src/engine-config.ts +++ b/packages/types/src/engine-config.ts @@ -138,20 +138,3 @@ export interface EngineOptions { */ enableWorkspaceMode?: boolean; } - -export interface IPreference { - /** - * set value from local storage by module and key - */ - set(key: string, value: any, module?: string): void; - - /** - * get value from local storage by module and key - */ - get(key: string, module: string): any; - - /** - * check if local storage contain certain key - */ - contains(key: string, module: string): boolean; -} diff --git a/packages/types/src/shell/api/canvas.ts b/packages/types/src/shell/api/canvas.ts index 0d1e3e88d..147d554ec 100644 --- a/packages/types/src/shell/api/canvas.ts +++ b/packages/types/src/shell/api/canvas.ts @@ -5,34 +5,44 @@ export interface IPublicApiCanvas { /** + * 创一个滚动控制器 Scroller，赋予一个视图滚动的基本能力， * a Scroller is a controller that gives a view (IPublicModelScrollable) the ability scrolling * to some cordination by api scrollTo. * - * when initing aaa scroller, will need to pass is a scrollable, which has a scrollTarget. + * 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: IPublicModelScrollable): IPublicModelScroller; /** + * 创建一个 ScrollTarget，与 Scroller 一起发挥作用，详见 createScroller 中的描述 * this works with Scroller, refer to createScroller`s description + * @since v1.1.0 */ createScrollTarget(shell: HTMLDivElement): IPublicModelScrollTarget; /** + * 创建一个文档插入位置对象，该对象用来描述一个即将插入的节点在文档中的位置 * create a drop location for document, drop location describes a location in document + * @since v1.1.0 */ createLocation(locationData: IPublicTypeLocationData): IPublicModelDropLocation; /** + * 获取拖拽操作对象的实例 * get dragon instance, you can use this to obtain draging related abilities and lifecycle hooks + * @since v1.1.0 */ get dragon(): IPublicModelDragon | null; /** + * 获取活动追踪器实例 * get activeTracker instance, which is a singleton running in engine. * it tracks document`s current focusing node/node[], and notify it`s subscribers that when * focusing node/node[] changed. + * @since v1.1.0 */ get activeTracker(): IPublicModelActiveTracker | null; } diff --git a/packages/types/src/shell/api/common.ts b/packages/types/src/shell/api/common.ts index 8c1a7c4a0..ceb85067f 100644 --- a/packages/types/src/shell/api/common.ts +++ b/packages/types/src/shell/api/common.ts @@ -3,24 +3,65 @@ import { Component, ReactNode } from 'react'; import { IPublicTypeNodeSchema } from '../type'; import { IPublicEnumTransitionType } from '../enum'; -export interface IPublicCommonUtils { +export interface IPublicApiCommonUtils { + /** + * 是否为合法的 schema 结构 + * check if data is valid NodeSchema + * + * @param {*} data + * @returns {boolean} + */ isNodeSchema(data: any): boolean; + /** + * 是否为表单事件类型 + * check if e is a form event + * @param {(KeyboardEvent | MouseEvent)} e + * @returns {boolean} + */ isFormEvent(e: KeyboardEvent | MouseEvent): boolean; - compatibleLegaoSchema(props: any): any; - + /** + * 从 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; + // TODO: add comments getConvertedExtraKey(key: string): string; + // TODO: add comments getOriginalExtraKey(key: string): string; + /** + * 批处理事务，用于优化特定场景的性能 + * excute something in a transaction for performence + * + * @param {() => void} fn + * @param {IPublicEnumTransitionType} type + * @since v1.0.16 + */ executeTransaction(fn: () => void, type: IPublicEnumTransitionType): void; + /** + * 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; @@ -28,33 +69,43 @@ export interface IPublicCommonUtils { setLocale(locale: string): void; }; } -export interface IPublicCommonSkeletonCabin { +export interface IPublicApiCommonSkeletonCabin { + /** + * 编辑器框架 View + * get Workbench Component + */ get Workbench(): Component; } -export interface IPublicCommonEditorCabin { +export interface IPublicApiCommonEditorCabin { + /** + * Title 组件 + * @experimental unstable API, pay extra caution when trying to use this + */ get Tip(): Component; + /** + * Tip 组件 + * @experimental unstable API, pay extra caution when trying to use this + */ get Title(): Component; } -export interface IPublicCommonDesignerCabin { - /** - * 是否是 SettingField 实例 - * - * @param {*} obj - * @returns {obj is SettingField} - * @memberof DesignerCabin - */ - isSettingField(obj: any): boolean; +export interface IPublicApiCommonDesignerCabin { } export interface IPublicApiCommon { - get utils(): IPublicCommonUtils; + get utils(): IPublicApiCommonUtils; - get designerCabin(): IPublicCommonDesignerCabin; + /** + * @deprecated + */ + get designerCabin(): IPublicApiCommonDesignerCabin; - get editorCabin(): IPublicCommonEditorCabin; + /** + * @experimental unstable API, pay extra caution when trying to use this + */ + get editorCabin(): IPublicApiCommonEditorCabin; - get skeletonCabin(): IPublicCommonSkeletonCabin; + get skeletonCabin(): IPublicApiCommonSkeletonCabin; } diff --git a/packages/types/src/shell/api/event.ts b/packages/types/src/shell/api/event.ts index c54bac649..18e76febe 100644 --- a/packages/types/src/shell/api/event.ts +++ b/packages/types/src/shell/api/event.ts @@ -4,6 +4,7 @@ export interface IPublicApiEvent { /** * 监听事件 + * add monitor to a event * @param event 事件名称 * @param listener 事件回调 */ @@ -12,6 +13,7 @@ export interface IPublicApiEvent { /** * 取消监听事件 + * cancel a monitor from a event * @param event 事件名称 * @param listener 事件回调 */ @@ -19,6 +21,7 @@ export interface IPublicApiEvent { /** * 触发事件 + * emit a message fot a event * @param event 事件名称 * @param args 事件参数 * @returns diff --git a/packages/types/src/shell/api/hotkey.ts b/packages/types/src/shell/api/hotkey.ts index 335379e97..c8da780af 100644 --- a/packages/types/src/shell/api/hotkey.ts +++ b/packages/types/src/shell/api/hotkey.ts @@ -5,10 +5,15 @@ export interface IPublicApiHotkey { /** * 绑定快捷键 + * bind hotkey/hotkeys, * @param combos 快捷键，格式如：['command + s'] 、['ctrl + shift + s'] 等 * @param callback 回调函数 * @param action * @returns */ - bind(combos: string[] | string, callback: IPublicTypeHotkeyCallback, action?: string): IPublicTypeDisposable; + bind( + combos: string[] | string, + callback: IPublicTypeHotkeyCallback, + action?: string, + ): IPublicTypeDisposable; } diff --git a/packages/types/src/shell/api/material.ts b/packages/types/src/shell/api/material.ts index 34396ddfd..deec23d52 100644 --- a/packages/types/src/shell/api/material.ts +++ b/packages/types/src/shell/api/material.ts @@ -1,31 +1,41 @@ -import { IPublicTypeAssetsJson, IPublicTypeMetadataTransducer, IPublicTypeComponentAction } from '../type'; +import { IPublicTypeAssetsJson, IPublicTypeMetadataTransducer, IPublicTypeComponentAction, IPublicTypeNpmInfo } from '../type'; import { IPublicModelComponentMeta } from '../model'; - +import { ComponentType } from 'react'; export interface IPublicApiMaterial { + /** + * 获取组件 map 结构 + * get map of components + */ + get componentsMap(): { [key: string]: IPublicTypeNpmInfo | ComponentType | object } ; + /** * 设置「资产包」结构 - * @param assets - * @returns + * set data for Assets + * @returns void */ setAssets(assets: IPublicTypeAssetsJson): void; /** * 获取「资产包」结构 - * @returns + * get AssetsJson data + * @returns IPublicTypeAssetsJson */ - getAssets(): any; + getAssets(): IPublicTypeAssetsJson; /** * 加载增量的「资产包」结构，该增量包会与原有的合并 + * load Assets incrementally, and will merge this with exiting assets * @param incrementalAssets * @returns */ loadIncrementalAssets(incrementalAssets: IPublicTypeAssetsJson): void; /** - * 注册物料元数据管道函数 + * 注册物料元数据管道函数，在物料信息初始化时执行。 + * register transducer to process component meta, which will be + * excuted during component meta`s initialization * @param transducer * @param level * @param id @@ -38,12 +48,14 @@ export interface IPublicApiMaterial { /** * 获取所有物料元数据管道函数 - * @returns + * get all registered metadata transducers + * @returns {IPublicTypeMetadataTransducer[]} */ getRegisteredMetadataTransducers(): IPublicTypeMetadataTransducer[]; /** * 获取指定名称的物料元数据 + * get component meta by component name * @param componentName * @returns */ @@ -52,30 +64,33 @@ export interface IPublicApiMaterial { /** * test if the given object is a ComponentMeta instance or not * @param obj - * @returns + * @experiemental unstable API, pay extra caution when trying to use it */ isComponentMeta(obj: any): boolean; /** * 获取所有已注册的物料元数据 - * @returns + * get map of all component metas */ getComponentMetasMap(): Map; /** * 在设计器辅助层增加一个扩展 action + * add an action button in canvas context menu area * @param action */ addBuiltinComponentAction(action: IPublicTypeComponentAction): void; /** * 移除设计器辅助层的指定 action + * remove a builtin action button from canvas context menu area * @param name */ removeBuiltinComponentAction(name: string): void; /** * 修改已有的设计器辅助层的指定 action + * modify a builtin action button in canvas context menu area * @param actionName * @param handle */ @@ -86,6 +101,7 @@ export interface IPublicApiMaterial { /** * 监听 assets 变化的事件 + * add callback for assets changed event * @param fn */ onChangeAssets(fn: () => void): void; diff --git a/packages/types/src/shell/api/plugins.ts b/packages/types/src/shell/api/plugins.ts index b024a3699..2797ba071 100644 --- a/packages/types/src/shell/api/plugins.ts +++ b/packages/types/src/shell/api/plugins.ts @@ -1,5 +1,6 @@ import { IPublicTypePlugin } from '../model'; import { IPublicTypePreferenceValueType } from '../type'; +import { IPublicTypePluginRegisterOptions } from '../type/plugin-register-options'; export interface IPluginPreferenceMananger { // eslint-disable-next-line max-len @@ -9,28 +10,18 @@ export interface IPluginPreferenceMananger { ) => IPublicTypePreferenceValueType | undefined; } -export interface ILowCodeRegisterOptions { - /** - * Will enable plugin registered with auto-initialization immediately - * other than plugin-manager init all plugins at certain time. - * It is helpful when plugin register is later than plugin-manager initialization. - */ - autoInit?: boolean; - /** - * allow overriding existing plugin with same name when override === true - */ - override?: boolean; -} - export type PluginOptionsType = string | number | boolean | object; export interface IPublicApiPlugins { register( pluginModel: IPublicTypePlugin, options?: Record, - registerOptions?: ILowCodeRegisterOptions, + registerOptions?: IPublicTypePluginRegisterOptions, ): Promise; + /** + * @deprecated use options instead + */ getPluginPreference( pluginName: string, ): Record | null | undefined; diff --git a/packages/types/src/shell/api/project.ts b/packages/types/src/shell/api/project.ts index ad71f1fb8..823159e7b 100644 --- a/packages/types/src/shell/api/project.ts +++ b/packages/types/src/shell/api/project.ts @@ -7,30 +7,34 @@ import { IPublicModelDocumentModel } from '../model'; export interface IPublicApiProject { /** * 获取当前的 document - * @returns + * get current document */ get currentDocument(): IPublicModelDocumentModel | null; /** - * 获取当前 project 下所有 documents - * @returns - */ + * 获取当前 project 下所有 documents + * get all documents of this project + * @returns + */ get documents(): IPublicModelDocumentModel[]; /** * 获取模拟器的 host + * get simulator host */ get simulatorHost(): IPublicApiSimulatorHost | null; /** - * 打开一个 document - * @param doc - * @returns - */ + * 打开一个 document + * open a document + * @param doc + * @returns + */ openDocument(doc?: string | IPublicTypeRootSchema | undefined): IPublicModelDocumentModel | null; /** * 创建一个 document + * create a document * @param data * @returns */ @@ -39,12 +43,14 @@ export interface IPublicApiProject { /** * 删除一个 document + * remove a document * @param doc */ removeDocument(doc: IPublicModelDocumentModel): void; /** * 根据 fileName 获取 document + * get a document by filename * @param fileName * @returns */ @@ -52,6 +58,7 @@ export interface IPublicApiProject { /** * 根据 id 获取 document + * get a document by id * @param id * @returns */ @@ -59,24 +66,28 @@ export interface IPublicApiProject { /** * 导出 project + * export project to schema * @returns */ exportSchema(stage: IPublicEnumTransformStage): IPublicTypeProjectSchema; /** - * 导入 project - * @param schema 待导入的 project 数据 - */ + * 导入 project schema + * import schema to project + * @param schema 待导入的 project 数据 + */ importSchema(schema?: IPublicTypeProjectSchema): void; /** * 获取当前的 document + * get current document * @returns */ getCurrentDocument(): IPublicModelDocumentModel | null; /** * 增加一个属性的管道处理函数 + * add a transducer to process prop * @param transducer * @param stage */ @@ -87,31 +98,37 @@ export interface IPublicApiProject { /** * 绑定删除文档事件 + * set callback for event onDocumentRemoved * @param fn - * @returns + * @since v1.0.16 */ - onRemoveDocument(fn: (data: { id: string }) => void): any; + onRemoveDocument(fn: (data: { id: string }) => void): IPublicTypeDisposable; /** * 当前 project 内的 document 变更事件 + * set callback for event onDocumentChanged */ onChangeDocument(fn: (doc: IPublicModelDocumentModel) => void): IPublicTypeDisposable; /** * 当前 project 的模拟器 ready 事件 + * set callback for event onSimulatorHostReady */ onSimulatorHostReady(fn: (host: IPublicApiSimulatorHost) => void): IPublicTypeDisposable; /** * 当前 project 的渲染器 ready 事件 + * set callback for event onSimulatorRendererReady */ onSimulatorRendererReady(fn: () => void): IPublicTypeDisposable; /** * 设置多语言语料 * 数据格式参考 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 - * @returns + * @since v1.0.17 */ setI18n(value: object): void; } diff --git a/packages/types/src/shell/api/setters.ts b/packages/types/src/shell/api/setters.ts index 25b57fe48..9ff2e8eda 100644 --- a/packages/types/src/shell/api/setters.ts +++ b/packages/types/src/shell/api/setters.ts @@ -3,6 +3,7 @@ import { IPublicTypeRegisteredSetter, IPublicTypeCustomView } from '../type'; export interface IPublicApiSetters { /** * 获取指定 setter + * get setter by type * @param type * @returns */ @@ -10,6 +11,7 @@ export interface IPublicApiSetters { /** * 获取已注册的所有 settersMap + * get map of all registered setters * @returns */ getSettersMap(): Map): any; /** - * 移除一个面板实例 - * @param config - * @returns - */ + * 移除一个面板实例 + * remove a panel + * @param config + * @returns + */ remove(config: IPublicTypeWidgetBaseConfig): number | undefined; /** - * 显示面板 + * 展示指定 Panel 实例 + * show panel by name * @param name */ showPanel(name: string): void; /** * 隐藏面板 + * hide panel by name * @param name */ hidePanel(name: string): void; /** - * 显示 widget + * 展示指定 Widget 实例 + * show widget by name * @param name */ showWidget(name: string): void; /** - * enable widget + * 将 widget 启用 + * enable widget by name * @param name */ enableWidget(name: string): void; /** - * 隐藏 widget + * 隐藏指定 widget 实例 + * hide widget by name * @param name */ hideWidget(name: string): void; /** - * disable widget，不可点击 + * 将 widget 禁用掉，禁用后，所有鼠标事件都会被禁止掉。 + * disable widget，and make it not responding any click event. * @param name */ disableWidget(name: string): void; /** + * 显示某个 Area * show area * @param areaName name of area */ showArea(areaName: string): void; /** + * 隐藏某个 Area * hide area * @param areaName name of area */ hideArea(areaName: string): void; /** - * 监听 panel 显示事件 + * 监听 Panel 实例显示事件 + * set callback for panel shown event * @param listener * @returns */ onShowPanel(listener: (...args: any[]) => void): () => void; /** - * 监听 panel 隐藏事件 + * 监听 Panel 实例隐藏事件 + * set callback for panel hidden event * @param listener * @returns */ onHidePanel(listener: (...args: any[]) => void): () => void; /** - * 监听 widget 显示事件 + * 监听 Widget 显示事件 + * set callback for widget shown event * @param listener * @returns */ onShowWidget(listener: (...args: any[]) => void): () => void; /** - * 监听 widget 隐藏事件 + * 监听 Widget 隐藏事件 + * set callback for widget hidden event * @param listener * @returns */ diff --git a/packages/types/src/shell/model/detecting.ts b/packages/types/src/shell/model/detecting.ts index 9dc868d92..8e82f7449 100644 --- a/packages/types/src/shell/model/detecting.ts +++ b/packages/types/src/shell/model/detecting.ts @@ -9,6 +9,7 @@ export interface IPublicModelDetecting { /** * 当前 hover 的节点 + * @since v1.0.16 */ get current(): any; @@ -29,5 +30,10 @@ export interface IPublicModelDetecting { */ leave(): any; + /** + * hover 节点变化事件 + * set callback which will be called when hovering object changed. + * @since v1.1.0 + */ onDetectingChange(fn: (node: IPublicModelNode) => void): () => void; } diff --git a/packages/types/src/shell/model/dragon.ts b/packages/types/src/shell/model/dragon.ts index b9923b70b..6a6daf034 100644 --- a/packages/types/src/shell/model/dragon.ts +++ b/packages/types/src/shell/model/dragon.ts @@ -4,12 +4,14 @@ import { IPublicModelDragObject, IPublicModelLocateEvent, IPublicModelNode } fro export interface IPublicModelDragon { /** + * 是否正在拖动 * is dragging or not */ get dragging(): boolean; /** * 绑定 dragstart 事件 + * bind a callback function which will be called on dragging start * @param func * @returns */ @@ -17,6 +19,7 @@ export interface IPublicModelDragon { /** * 绑定 drag 事件 + * bind a callback function which will be called on dragging * @param func * @returns */ @@ -24,6 +27,7 @@ export interface IPublicModelDragon { /** * 绑定 dragend 事件 + * bind a callback function which will be called on dragging end * @param func * @returns */ @@ -32,13 +36,17 @@ export interface IPublicModelDragon { /** * 设置拖拽监听的区域 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 your dragObject for dragging(flying) 发射拖拽对象 + * 发射拖拽对象 + * boost your dragObject for dragging(flying) * * @param dragObject 拖拽对象 * @param boostEvent 拖拽初始时事件 @@ -47,11 +55,13 @@ export interface IPublicModelDragon { /** * 添加投放感应区 + * add sensor area */ addSensor(sensor: any): void; /** * 移除投放感应 + * remove sensor area */ removeSensor(sensor: any): void; } diff --git a/packages/types/src/shell/model/engine-config.ts b/packages/types/src/shell/model/engine-config.ts index 2a52203cf..99d3a9071 100644 --- a/packages/types/src/shell/model/engine-config.ts +++ b/packages/types/src/shell/model/engine-config.ts @@ -1,9 +1,10 @@ -import { IPreference } from '../../engine-config'; +import { IPublicModelPreference } from './'; export interface IPublicModelEngineConfig { /** * 判断指定 key 是否有值 + * check if config has certain key configed * @param key * @returns */ @@ -11,6 +12,7 @@ export interface IPublicModelEngineConfig { /** * 获取指定 key 的值 + * get value by key * @param key * @param defaultValue * @returns @@ -19,6 +21,7 @@ export interface IPublicModelEngineConfig { /** * 设置指定 key 的值 + * set value for certain key * @param key * @param value */ @@ -26,6 +29,7 @@ export interface IPublicModelEngineConfig { /** * 批量设值，set 的对象版本 + * set multiple config key-values * @param config */ setConfig(config: { [key: string]: any }): void; @@ -33,6 +37,8 @@ export interface IPublicModelEngineConfig { /** * 获取指定 key 的值，若此时还未赋值，则等待，若已有值，则直接返回值 * 注：此函数返回 Promise 实例，只会执行（fullfill）一次 + * wait until value of certain key is set, will only be + * triggered once. * @param key * @returns */ @@ -40,6 +46,8 @@ export interface IPublicModelEngineConfig { /** * 获取指定 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 @@ -48,7 +56,10 @@ export interface IPublicModelEngineConfig { /** * 获取全局 Preference, 用于管理全局浏览器侧用户 Preference，如 Panel 是否钉住 - * @returns IPreference + * 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(): IPreference; + getPreference(): IPublicModelPreference; } diff --git a/packages/types/src/shell/model/index.ts b/packages/types/src/shell/model/index.ts index a11c1b2d1..c9d8f3a98 100644 --- a/packages/types/src/shell/model/index.ts +++ b/packages/types/src/shell/model/index.ts @@ -25,3 +25,4 @@ export * from './plugin-context'; export * from './setting-target'; export * from './engine-config'; export * from './editor'; +export * from './preference'; diff --git a/packages/types/src/shell/model/preference.ts b/packages/types/src/shell/model/preference.ts new file mode 100644 index 000000000..a58b76573 --- /dev/null +++ b/packages/types/src/shell/model/preference.ts @@ -0,0 +1,17 @@ + +export interface IPublicModelPreference { + /** + * set value from local storage by module and key + */ + set(key: string, value: any, module?: string): void; + + /** + * get value from local storage by module and key + */ + get(key: string, module: string): any; + + /** + * check if local storage contain certain key + */ + contains(key: string, module: string): boolean; +} diff --git a/packages/types/src/shell/model/selection.ts b/packages/types/src/shell/model/selection.ts index 8d48be8f0..bfc0b75ce 100644 --- a/packages/types/src/shell/model/selection.ts +++ b/packages/types/src/shell/model/selection.ts @@ -59,9 +59,15 @@ export interface IPublicModelSelection { * for example: * getNodes() returns [A, subA, B], then * getTopNodes() will return [A, B], subA will be removed + * @since v1.0.16 * @returns */ getTopNodes(includeRoot?: boolean): IPublicModelNode[]; + /** + * 注册 selection 变化事件回调 + * set callback which will be called when selection is changed + * @since v1.1.0 + */ onSelectionChange(fn: (ids: string[]) => void): () => void; } diff --git a/packages/types/src/shell/type/index.ts b/packages/types/src/shell/type/index.ts index ef80a138c..a42e65e3e 100644 --- a/packages/types/src/shell/type/index.ts +++ b/packages/types/src/shell/type/index.ts @@ -71,4 +71,5 @@ export * from './dynamic-props'; export * from './setter-config'; export * from './tip-config'; export * from './widget-config-area'; -export * from './hotkey-callback'; \ No newline at end of file +export * from './hotkey-callback'; +export * from './plugin-register-options'; \ No newline at end of file diff --git a/packages/types/src/shell/type/plugin-register-options.ts b/packages/types/src/shell/type/plugin-register-options.ts new file mode 100644 index 000000000..7d2377bbe --- /dev/null +++ b/packages/types/src/shell/type/plugin-register-options.ts @@ -0,0 +1,13 @@ + +export interface IPublicTypePluginRegisterOptions { + /** + * Will enable plugin registered with auto-initialization immediately + * other than plugin-manager init all plugins at certain time. + * It is helpful when plugin register is later than plugin-manager initialization. + */ + autoInit?: boolean; + /** + * allow overriding existing plugin with same name when override === true + */ + override?: boolean; +} diff --git a/scripts/sync-oss.js b/scripts/sync-oss.js index 422f7162d..4b67bdca9 100644 --- a/scripts/sync-oss.js +++ b/scripts/sync-oss.js @@ -5,7 +5,7 @@ const { version, name } = package; const options = { method: 'PUT', // 暂时使用 日常环境的 uipaas-node，上线后可切换成线上环境 https://uipaas-node.alibaba-inc.com - hostname: 'uipaas-node.alibaba.net', + hostname: 'uipaas-node.alibaba-inc.com', path: '/staticAssets/cdn/packages', headers: { 'Content-Type': 'application/json',