From e0ed17a16a91a9ae8d232ab27877d8cf343a3ff6 Mon Sep 17 00:00:00 2001 From: liujuping Date: Thu, 30 Mar 2023 10:51:17 +0800 Subject: [PATCH] docs: update SettingField and SettingTopEntry docs --- docs/docs/api/index.md | 7 +- docs/docs/api/init.md | 2 +- docs/docs/api/model/config.md | 113 ------------------ docs/docs/api/model/setting-field.md | 74 ++++++------ docs/docs/api/model/setting-top-entry.md | 16 +-- packages/shell/src/api/canvas.ts | 5 +- packages/shell/src/api/common.tsx | 6 +- packages/shell/src/{model => api}/config.ts | 0 packages/shell/src/api/index.ts | 3 +- packages/shell/src/api/workspace.ts | 2 +- packages/shell/src/index.ts | 2 +- packages/shell/src/model/document-model.ts | 2 +- packages/shell/src/model/drag-object.ts | 8 +- packages/shell/src/model/index.ts | 1 - packages/shell/src/model/node-children.ts | 4 +- packages/shell/src/model/node.ts | 8 +- packages/types/src/shell/api/common.ts | 8 +- packages/types/src/shell/model/drag-object.ts | 12 +- 18 files changed, 92 insertions(+), 181 deletions(-) delete mode 100644 docs/docs/api/model/config.md rename packages/shell/src/{model => api}/config.ts (100%) diff --git a/docs/docs/api/index.md b/docs/docs/api/index.md index 993c39e88..383b2952c 100644 --- a/docs/docs/api/index.md +++ b/docs/docs/api/index.md @@ -29,12 +29,17 @@ sidebar_position: 0 - node-children 节点孩子 - props 属性集 - prop 属性 -- setting-prop-entry 设置属性 +- setting-field 设置属性 - setting-top-entry 设置属性集 - component-meta 物料元数据 - selection 画布选中 - detecting 画布 hover - history 操作历史 +- window 低代码设计器窗口模型 +- detecting 画布节点悬停模型 +- modal-nodes-manager 模态节点管理器模型 +- plugin-instance 插件实例 +- drop-location 拖拽放置位置模型 ## API 设计约定 diff --git a/docs/docs/api/init.md b/docs/docs/api/init.md index f8bf2cdbe..9917d1f72 100644 --- a/docs/docs/api/init.md +++ b/docs/docs/api/init.md @@ -9,7 +9,7 @@ sidebar_position: 10 ## 模块简介 提供 init 等方法 ## 方法 -#### 1. init +#### init 初始化引擎 **方法定义** diff --git a/docs/docs/api/model/config.md b/docs/docs/api/model/config.md deleted file mode 100644 index 854aa1a04..000000000 --- a/docs/docs/api/model/config.md +++ /dev/null @@ -1,113 +0,0 @@ ---- -title: Config -sidebar_position: 16 ---- -> **@types** [IPublicModelEngineConfig](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/model/engine-config.ts)
-> **@since** v1.1.3 - -## 方法 -### has - -判断指定 key 是否有值 - -```typescript -/** - * 判断指定 key 是否有值 - * check if config has certain key configed - * @param key - * @returns - */ -has(key: string): boolean; -``` - -### get - -获取指定 key 的值 - -```typescript -/** - * 获取指定 key 的值 - * get value by key - * @param key - * @param defaultValue - * @returns - */ -get(key: string, defaultValue?: any): any; -``` - -### set - -设置指定 key 的值 - -```typescript -/** - * 设置指定 key 的值 - * set value for certain key - * @param key - * @param value - */ -set(key: string, value: any): void; -``` - -### setConfig -批量设值，set 的对象版本 - -```typescript -/** - * 批量设值，set 的对象版本 - * set multiple config key-values - * @param config - */ -setConfig(config: { [key: string]: any }): void; -``` - -### 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) - -## 事件 - -### onGot -获取指定 key 的值，函数回调模式，若多次被赋值，回调会被多次调用 - -```typescript -/** - * 获取指定 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): IPublicTypeDisposable; -``` - -相关类型：[IPublicTypeDisposable](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/type/disposable.ts) - -### onceGot -获取指定 key 的值，若此时还未赋值，则等待，若已有值，则直接返回值 -> 注：此函数返回 Promise 实例，只会执行（fullfill）一次 - -```typescript -/** - * 获取指定 key 的值，若此时还未赋值，则等待，若已有值，则直接返回值 - * 注：此函数返回 Promise 实例，只会执行（fullfill）一次 - * wait until value of certain key is set, will only be - * triggered once. - * @param key - * @returns - */ -onceGot(key: string): Promise; -``` diff --git a/docs/docs/api/model/setting-field.md b/docs/docs/api/model/setting-field.md index abf99db37..226a0c7e5 100644 --- a/docs/docs/api/model/setting-field.md +++ b/docs/docs/api/model/setting-field.md @@ -4,68 +4,68 @@ sidebar_position: 6 --- > **@types** [IPublicModelSettingField](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/model/setting-field.ts)
-# 基本介绍 +## 基本介绍 setter 设置器操作对象 -# 属性 +## 属性 -## isGroup +#### isGroup 获取设置属性的 isGroup `@type {boolean}` -## id +#### id 获取设置属性的 id `@type {string}` -## name +#### name 获取设置属性的 name `@type {string | number | undefined}` -## key +#### key 获取设置属性的 key `@type {string | number | undefined}` -## path +#### path 获取设置属性的 path `@type {(string | number)[]}` -## title +#### title 获取设置属性的 title `@type {string}` -## setter +#### setter 获取设置属性的 setter `@type {IPublicTypeSetterType | null}` -## expanded +#### expanded 获取设置属性的 expanded `@type {boolean}` -## extraProps +#### extraProps 获取设置属性的 extraProps `@type {IPublicTypeFieldExtraProps}` -## props +#### props `@type {IPublicModelSettingTopEntry}` @@ -73,14 +73,14 @@ setter 设置器操作对象 相关类型：[IPublicModelSettingTopEntry](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/model/setting-top-entry.ts) -## node +#### node 获取设置属性对应的节点实例 `@type {IPublicModelNode | null}` -## parent +#### parent 获取设置属性的父设置属性 @@ -90,7 +90,7 @@ setter 设置器操作对象 相关类型：[IPublicModelSettingTopEntry](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/model/setting-top-entry.ts) -## top +#### top 获取顶级设置属性 @@ -100,19 +100,19 @@ setter 设置器操作对象 相关类型：[IPublicModelSettingTopEntry](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/model/setting-top-entry.ts) -## isSettingField +#### isSettingField 是否是 SettingField 实例 `@type {boolean}` -## componentMeta +#### componentMeta `@type {IPublicModelComponentMeta}` 相关类型：[IPublicModelComponentMeta](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/model/component-meta.ts) -## items +#### items 获取设置属性的 items @@ -120,9 +120,9 @@ setter 设置器操作对象 相关类型：[IPublicTypeCustomView](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/type/custom-view.ts) -# 方法 +## 方法 -## setKey +#### setKey 设置 key 值 @@ -134,7 +134,7 @@ setter 设置器操作对象 setKey(key: string | number): void; ``` -## setValue +#### setValue 设置值 @@ -150,7 +150,7 @@ setValue(val: IPublicTypeCompositeValue, extraOptions?: IPublicTypeSetValueOptio - [IPublicTypeCompositeValue](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/type/composite-value.ts) - [IPublicTypeSetValueOptions](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/type/set-value-options.ts) -## setPropValue +#### setPropValue 设置子级属性值 @@ -163,7 +163,7 @@ setValue(val: IPublicTypeCompositeValue, extraOptions?: IPublicTypeSetValueOptio setPropValue(propName: string | number, value: any): void; ``` -## clearPropValue +#### clearPropValue 清空指定属性值 @@ -175,7 +175,7 @@ setPropValue(propName: string | number, value: any): void; clearPropValue(propName: string | number): void; ``` -## getDefaultValue +#### getDefaultValue 获取配置的默认值 @@ -187,7 +187,7 @@ clearPropValue(propName: string | number): void; getDefaultValue(): any; ``` -## getValue +#### getValue 获取值 @@ -199,7 +199,7 @@ getDefaultValue(): any; getValue(): any; ``` -## getPropValue +#### getPropValue 获取子级属性值 @@ -212,7 +212,7 @@ getValue(): any; getPropValue(propName: string | number): any; ``` -## getExtraPropValue +#### getExtraPropValue 获取顶层附属属性值 @@ -223,7 +223,7 @@ getPropValue(propName: string | number): any; getExtraPropValue(propName: string): any; ``` -## setExtraPropValue +#### setExtraPropValue 设置顶层附属属性值 @@ -234,7 +234,7 @@ getExtraPropValue(propName: string): any; setExtraPropValue(propName: string, value: any): void; ``` -## getProps +#### getProps 获取设置属性集 @@ -250,7 +250,7 @@ getProps(): IPublicModelSettingTopEntry; 相关类型：[IPublicModelSettingTopEntry](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/model/setting-top-entry.ts) -## isUseVariable +#### isUseVariable 是否绑定了变量 @@ -262,7 +262,7 @@ getProps(): IPublicModelSettingTopEntry; isUseVariable(): boolean; ``` -## setUseVariable +#### setUseVariable 设置绑定变量 @@ -274,7 +274,7 @@ isUseVariable(): boolean; setUseVariable(flag: boolean): void; ``` -## createField +#### createField 创建一个设置 field 实例 @@ -289,7 +289,7 @@ createField(config: IPublicTypeFieldConfig): IPublicModelSettingField; 相关类型：[IPublicTypeFieldConfig](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/type/field-config.ts) -## getMockOrValue +#### getMockOrValue 获取值，当为变量时，返回 mock @@ -302,7 +302,7 @@ getMockOrValue(): any; ``` -## purge +#### purge 销毁当前 field 实例 @@ -313,7 +313,7 @@ getMockOrValue(): any; purge(): void; ``` -## remove +#### remove 移除当前 field 实例 @@ -324,7 +324,9 @@ purge(): void; remove(): void; ``` -## onEffect +## 事件 + +#### onEffect 设置 autorun diff --git a/docs/docs/api/model/setting-top-entry.md b/docs/docs/api/model/setting-top-entry.md index 0a925c3a9..2e2cad52b 100644 --- a/docs/docs/api/model/setting-top-entry.md +++ b/docs/docs/api/model/setting-top-entry.md @@ -4,21 +4,21 @@ sidebar_position: 6 --- > **@types** [IPublicModelSettingTopEntry](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/model/setting-top-entry.ts)
-# 基本介绍 +## 基本介绍 setter 设置器顶层操作对象 -# 属性 +## 属性 -## node +#### node 返回所属的节点实例 `@type {IPublicModelNode | null}` -# 方法 +## 方法 -## get +#### get 获取子级属性对象 @@ -35,7 +35,7 @@ get(propName: string | number): IPublicModelSettingField | null; 相关类型：[IPublicModelSettingField](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/model/setting-field.ts) -## getPropValue +#### getPropValue 获取指定 propName 的值 @@ -48,7 +48,7 @@ get(propName: string | number): IPublicModelSettingField | null; getPropValue(propName: string | number): any; ``` -## setPropValue +#### setPropValue 设置指定 propName 的值 @@ -61,7 +61,7 @@ getPropValue(propName: string | number): any; setPropValue(propName: string | number, value: any): void; ``` -## clearPropValue +#### clearPropValue 清除指定 propName 的值 diff --git a/packages/shell/src/api/canvas.ts b/packages/shell/src/api/canvas.ts index d20ebd9d9..48acbc487 100644 --- a/packages/shell/src/api/canvas.ts +++ b/packages/shell/src/api/canvas.ts @@ -20,6 +20,7 @@ import { DropLocation as ShellDropLocation, ActiveTracker as ShellActiveTracker, Clipboard as ShellClipboard, + DropLocation, } from '../model'; const clipboardInstanceSymbol = Symbol('clipboardInstace'); @@ -66,10 +67,10 @@ export class Canvas implements IPublicApiCanvas { * 创建插入位置，考虑放到 dragon 中 */ createLocation(locationData: IPublicTypeLocationData): IPublicModelDropLocation { - return this[designerSymbol].createLocation({ + return new DropLocation(this[designerSymbol].createLocation({ ...locationData, target: (locationData.target as any)[nodeSymbol], - }); + })); } /** diff --git a/packages/shell/src/api/common.tsx b/packages/shell/src/api/common.tsx index 9954fdfe6..6a44dc82e 100644 --- a/packages/shell/src/api/common.tsx +++ b/packages/shell/src/api/common.tsx @@ -59,7 +59,7 @@ import { observer as innerObserver, } from '@alilc/lowcode-editor-core'; import { Dragon as ShellDragon } from '../model'; -import { ReactNode, Component } from 'react'; +import { ReactNode } from 'react'; class DesignerCabin implements IPublicApiCommonDesignerCabin { private readonly [editorSymbol]: Editor; @@ -246,7 +246,7 @@ class EditorCabin implements IPublicApiCommonEditorCabin { * Title 组件 * @experimental unstable API, pay extra caution when trying to use this */ - get Title(): Component { + get Title() { return InnerTitle; } @@ -254,7 +254,7 @@ class EditorCabin implements IPublicApiCommonEditorCabin { * Tip 组件 * @experimental unstable API, pay extra caution when trying to use this */ - get Tip(): Component { + get Tip() { return InnerTip; } diff --git a/packages/shell/src/model/config.ts b/packages/shell/src/api/config.ts similarity index 100% rename from packages/shell/src/model/config.ts rename to packages/shell/src/api/config.ts diff --git a/packages/shell/src/api/index.ts b/packages/shell/src/api/index.ts index 9274571c5..4114926e1 100644 --- a/packages/shell/src/api/index.ts +++ b/packages/shell/src/api/index.ts @@ -9,4 +9,5 @@ export * from './setters'; export * from './simulator-host'; export * from './skeleton'; export * from './canvas'; -export * from './workspace'; \ No newline at end of file +export * from './workspace'; +export * from './config'; \ No newline at end of file diff --git a/packages/shell/src/api/workspace.ts b/packages/shell/src/api/workspace.ts index ae4bc65aa..21015431f 100644 --- a/packages/shell/src/api/workspace.ts +++ b/packages/shell/src/api/workspace.ts @@ -1,8 +1,8 @@ import { IPublicApiWorkspace, IPublicResourceList, IPublicTypeDisposable, IPublicTypeResourceType } from '@alilc/lowcode-types'; import { IWorkspace } from '@alilc/lowcode-workspace'; -import { Plugins } from '@alilc/lowcode-shell'; import { workspaceSymbol } from '../symbols'; import { Resource as ShellResource, Window as ShellWindow } from '../model'; +import { Plugins } from './plugins'; export class Workspace implements IPublicApiWorkspace { readonly [workspaceSymbol]: IWorkspace; diff --git a/packages/shell/src/index.ts b/packages/shell/src/index.ts index 30eb32ada..7017ca289 100644 --- a/packages/shell/src/index.ts +++ b/packages/shell/src/index.ts @@ -9,7 +9,6 @@ import { Dragon, SettingTopEntry, Clipboard, - Config, SettingField, } from './model'; import { @@ -26,6 +25,7 @@ import { Canvas, Workspace, SimulatorHost, + Config, } from './api'; export * from './symbols'; diff --git a/packages/shell/src/model/document-model.ts b/packages/shell/src/model/document-model.ts index b8698ebf7..68252e3a5 100644 --- a/packages/shell/src/model/document-model.ts +++ b/packages/shell/src/model/document-model.ts @@ -196,7 +196,7 @@ export class DocumentModel implements IPublicModelDocumentModel { * @param data * @returns */ - createNode(data: IPublicTypeNodeSchema): IPublicModelNode | null { + createNode(data: IPublicTypeNodeSchema): IPublicModelNode | null { return ShellNode.create(this[documentSymbol].createNode(data)); } diff --git a/packages/shell/src/model/drag-object.ts b/packages/shell/src/model/drag-object.ts index dc4157bd2..064680fde 100644 --- a/packages/shell/src/model/drag-object.ts +++ b/packages/shell/src/model/drag-object.ts @@ -1,5 +1,5 @@ import { dragObjectSymbol } from '../symbols'; -import { IPublicModelDragObject, IPublicModelDragObject as InnerDragObject, IPublicTypeDragNodeDataObject } from '@alilc/lowcode-types'; +import { IPublicModelDragObject, IPublicModelDragObject as InnerDragObject, IPublicTypeDragNodeDataObject, IPublicTypeNodeSchema } from '@alilc/lowcode-types'; import { Node } from './node'; export class DragObject implements IPublicModelDragObject { @@ -16,11 +16,11 @@ export class DragObject implements IPublicModelDragObject { return new DragObject(dragObject); } - get type(): any { + get type() { return this[dragObjectSymbol].type; } - get nodes(): any { + get nodes() { const { nodes } = this[dragObjectSymbol]; if (!nodes) { return null; @@ -28,7 +28,7 @@ export class DragObject implements IPublicModelDragObject { return nodes.map(Node.create); } - get data(): any { + get data(): IPublicTypeNodeSchema | IPublicTypeNodeSchema[] { return (this[dragObjectSymbol] as IPublicTypeDragNodeDataObject).data; } } \ No newline at end of file diff --git a/packages/shell/src/model/index.ts b/packages/shell/src/model/index.ts index e747021b7..cd481643e 100644 --- a/packages/shell/src/model/index.ts +++ b/packages/shell/src/model/index.ts @@ -19,4 +19,3 @@ export * from './active-tracker'; export * from './plugin-instance'; export * from './window'; export * from './clipboard'; -export * from './config'; diff --git a/packages/shell/src/model/node-children.ts b/packages/shell/src/model/node-children.ts index 4d1cc0a22..b6d52e86f 100644 --- a/packages/shell/src/model/node-children.ts +++ b/packages/shell/src/model/node-children.ts @@ -142,8 +142,8 @@ export class NodeChildren implements IPublicModelNodeChildren { * 类似数组的 map * @param fn */ - map(fn: (node: IPublicModelNode, index: number) => T[]): any[] | null { - return this[nodeChildrenSymbol].map((item: InnerNode, index: number) => { + map(fn: (node: IPublicModelNode, index: number) => T): T[] | null { + return this[nodeChildrenSymbol].map((item: InnerNode, index: number): T => { return fn(ShellNode.create(item)!, index); }); } diff --git a/packages/shell/src/model/node.ts b/packages/shell/src/model/node.ts index 249e87f46..f2cddd1ab 100644 --- a/packages/shell/src/model/node.ts +++ b/packages/shell/src/model/node.ts @@ -31,6 +31,10 @@ import { ConditionGroup } from './condition-group'; const shellNodeSymbol = Symbol('shellNodeSymbol'); +function isShellNode(node: any): node is IPublicModelNode { + return node[shellNodeSymbol]; +} + export class Node implements IPublicModelNode { private readonly [documentSymbol]: InnerDocumentModel | null; private readonly [nodeSymbol]: InnerNode; @@ -326,12 +330,12 @@ export class Node implements IPublicModelNode { this._id = this[nodeSymbol].id; } - static create(node: InnerNode | null | undefined): IPublicModelNode | null { + static create(node: InnerNode | IPublicModelNode | null | undefined): IPublicModelNode | null { if (!node) { return null; } // @ts-ignore 直接返回已挂载的 shell node 实例 - if (node[shellNodeSymbol]) { + if (isShellNode(node)) { return (node as any)[shellNodeSymbol]; } const shellNode = new Node(node); diff --git a/packages/types/src/shell/api/common.ts b/packages/types/src/shell/api/common.ts index d00a2468b..60fac1606 100644 --- a/packages/types/src/shell/api/common.ts +++ b/packages/types/src/shell/api/common.ts @@ -4,6 +4,7 @@ import { IPublicTypeNodeSchema, IPublicTypeTitleContent } from '../type'; import { IPublicEnumTransitionType } from '../enum'; export interface IPublicApiCommonUtils { + /** * 是否为合法的 schema 结构 * check if data is valid NodeSchema @@ -70,6 +71,7 @@ export interface IPublicApiCommonUtils { }; } export interface IPublicApiCommonSkeletonCabin { + /** * 编辑器框架 View * get Workbench Component @@ -78,16 +80,18 @@ export interface IPublicApiCommonSkeletonCabin { } export interface IPublicApiCommonEditorCabin { + /** * Title 组件 * @experimental unstable API, pay extra caution when trying to use this */ - get Tip(): React.FC<{}>; + get Tip(): React.ComponentClass<{}>; + /** * Tip 组件 * @experimental unstable API, pay extra caution when trying to use this */ - get Title(): React.FC<{ + get Title(): React.ComponentClass<{ title: IPublicTypeTitleContent | undefined; match?: boolean; keywords?: string | null; diff --git a/packages/types/src/shell/model/drag-object.ts b/packages/types/src/shell/model/drag-object.ts index af404a2f0..92d92eca3 100644 --- a/packages/types/src/shell/model/drag-object.ts +++ b/packages/types/src/shell/model/drag-object.ts @@ -1,3 +1,11 @@ -import { IPublicTypeDragNodeDataObject, IPublicTypeDragNodeObject } from '../type'; +import { IPublicEnumDragObjectType } from '../enum'; +import { IPublicTypeNodeSchema } from '../type'; +import { IPublicModelNode } from './node'; -export type IPublicModelDragObject = Readonly | Readonly; +export class IPublicModelDragObject { + type: IPublicEnumDragObjectType.Node | IPublicEnumDragObjectType.NodeData; + + data: IPublicTypeNodeSchema | IPublicTypeNodeSchema[] | null; + + nodes: (IPublicModelNode | null)[] | null; +}