From 76f612b29c18c8a8338f437555d3d6810548147d Mon Sep 17 00:00:00 2001 From: JackLian Date: Fri, 6 Jan 2023 16:31:24 +0800 Subject: [PATCH] docs(prop): optimize api doc for model/prop, and fix related lint issues --- docs/docs/api/model/document-model.md | 2 +- docs/docs/api/model/prop.md | 67 +++++++++++++++++-- docs/docs/guide/design/editor.md | 2 +- .../designer/src/document/document-model.ts | 2 + packages/designer/src/document/node/node.ts | 23 +++++-- .../designer/src/document/node/props/prop.ts | 32 +++++---- .../designer/src/document/node/props/props.ts | 4 +- packages/shell/src/model/prop.ts | 11 +-- packages/shell/src/model/props.ts | 2 +- packages/types/src/shell/model/node.ts | 1 + packages/types/src/shell/model/prop.ts | 21 ++++-- packages/types/src/shell/type/value-type.ts | 17 +++++ 12 files changed, 147 insertions(+), 37 deletions(-) diff --git a/docs/docs/api/model/document-model.md b/docs/docs/api/model/document-model.md index c7b35c4d6..9e5064371 100644 --- a/docs/docs/api/model/document-model.md +++ b/docs/docs/api/model/document-model.md @@ -334,7 +334,7 @@ onChangeNodeVisible(fn: (node: IPublicModelNode, visible: boolean) => void): voi ### onChangeNodeChildren -onChangeNodeChildren(fn: (info?: IPublicOnChangeOptions) => void) +onChangeNodeChildren(fn: (info?: IPublicTypeOnChangeOptions) => void) 当前 document 的节点 children 变更事件 diff --git a/docs/docs/api/model/prop.md b/docs/docs/api/model/prop.md index b7832ef9f..e619cdc33 100644 --- a/docs/docs/api/model/prop.md +++ b/docs/docs/api/model/prop.md @@ -15,39 +15,94 @@ sidebar_position: 3 id +`@type {string}` + ### key key 值 +`@type {string | number | undefined}` + ### path 返回当前 prop 的路径 +`@type {string[]}` + ### node 返回所属的节点实例 +`@type {IPublicModelNode | null}` + +相关类型：[IPublicModelNode](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/model/node.ts) + +### slotNode + +当本 prop 代表一个 Slot 时，返回对应的 slotNode + +`@type {IPublicModelNode | undefined | null}` + +相关类型：[IPublicModelNode](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/model/node.ts) + + ## 方法签名 ### setValue -setValue(val: CompositeValue) - 设置值 +```typescript +/** + * 设置值 + * set value for this prop + * @param val + */ +setValue(val: IPublicTypeCompositeValue): void; +``` + +相关类型：[IPublicTypeCompositeValue](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/type/composite-value.ts) + ### getValue -getValue() - 获取值 +```typescript +/** + * 获取值 + * get value of this prop + */ +getValue(): any; +``` + ### remove + 移除值 +```typescript +/** + * 移除值 + * remove value of this prop + * @since v1.0.16 + */ +remove(): void; +``` + **@since v1.0.16** ### exportSchema -exportSchema(stage: IPublicEnumTransformStage = IPublicEnumTransformStage.Render) +导出值 -导出值 \ No newline at end of file +```typescript +/** + * 导出值 + * export schema + * @param stage + */ +exportSchema(stage: IPublicEnumTransformStage): IPublicTypeCompositeValue; +``` + +相关类型： +- [IPublicEnumTransformStage](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/enum/transform-stage.ts) +- [IPublicTypeCompositeValue](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/type/composite-value.ts) \ No newline at end of file diff --git a/docs/docs/guide/design/editor.md b/docs/docs/guide/design/editor.md index b04cb4eb6..fcead2922 100644 --- a/docs/docs/guide/design/editor.md +++ b/docs/docs/guide/design/editor.md @@ -313,7 +313,7 @@ simulator-renderer 通过调用 host 的方法，将 schema、components 等参 - 被拖拽对象 - `DragObject` - 拖拽到的目标位置 - `DropLocation` -- 拖拽感应区 - `ISensor` +- 拖拽感应区 - `IPublicModelSensor` - 定位事件 - `LocateEvent` ##### Sensor diff --git a/packages/designer/src/document/document-model.ts b/packages/designer/src/document/document-model.ts index 6fd30394b..9d5b05175 100644 --- a/packages/designer/src/document/document-model.ts +++ b/packages/designer/src/document/document-model.ts @@ -37,6 +37,8 @@ export type GetDataType = T extends undefined : T; export interface IDocumentModel extends IPublicModelDocumentModel { + readonly designer: Designer; + } export class DocumentModel implements IDocumentModel { diff --git a/packages/designer/src/document/node/node.ts b/packages/designer/src/document/node/node.ts index 96ac3b073..ef837a329 100644 --- a/packages/designer/src/document/node/node.ts +++ b/packages/designer/src/document/node/node.ts @@ -19,7 +19,7 @@ import { import { compatStage, isDOMText, isJSExpression } from '@alilc/lowcode-utils'; import { SettingTopEntry } from '@alilc/lowcode-designer'; import { Props, getConvertedExtraKey } from './props/props'; -import { DocumentModel } from '../document-model'; +import { DocumentModel, IDocumentModel } from '../document-model'; import { NodeChildren, INodeChildren } from './node-children'; import { Prop } from './props/prop'; import { ComponentMeta } from '../../component-meta'; @@ -55,6 +55,21 @@ export interface INode extends IPublicModelNode { unlinkSlot(slotNode: Node): void; didDropOut(dragment: Node): void; + + /** + * 导出 schema + */ + export(stage: IPublicEnumTransformStage, options?: any): IPublicTypeNodeSchema; + + get document(): IDocumentModel; + + emitPropChange(val: IPublicTypePropChangeOptions): void; + + import(data: IPublicTypeNodeSchema, checkId?: boolean): void; + + internalSetSlotFor(slotFor: Prop | null | undefined): void; + + addSlot(slotNode: INode): void; } /** @@ -189,7 +204,7 @@ export class Node isInited = false; - constructor(readonly document: DocumentModel, nodeSchema: Schema, options: any = {}) { + constructor(readonly document: IDocumentModel, nodeSchema: Schema, options: any = {}) { makeObservable(this); const { componentName, id, children, props, ...extras } = nodeSchema; this.id = document.nextId(id); @@ -521,7 +536,7 @@ export class Node return this.props.export(IPublicEnumTransformStage.Serilize).props || null; } - @obx.shallow _slots: Node[] = []; + @obx.shallow _slots: INode[] = []; hasSlots() { return this._slots.length > 0; @@ -885,7 +900,7 @@ export class Node return false; } - addSlot(slotNode: Node) { + addSlot(slotNode: INode) { const slotName = slotNode?.getExtraProp('name')?.getAsString(); // 一个组件下的所有 slot，相同 slotName 的 slot 应该是唯一的 if (includeSlot(this, slotName)) { diff --git a/packages/designer/src/document/node/props/prop.ts b/packages/designer/src/document/node/props/prop.ts index 41aee7dea..76354bc97 100644 --- a/packages/designer/src/document/node/props/prop.ts +++ b/packages/designer/src/document/node/props/prop.ts @@ -1,9 +1,9 @@ import { untracked, computed, obx, engineConfig, action, makeObservable, mobx, runInAction } from '@alilc/lowcode-editor-core'; -import { IPublicTypeCompositeValue, GlobalEvent, IPublicTypeJSSlot, IPublicTypeSlotSchema, IPublicEnumTransformStage } from '@alilc/lowcode-types'; +import { IPublicTypeCompositeValue, GlobalEvent, IPublicTypeJSSlot, IPublicTypeSlotSchema, IPublicEnumTransformStage, IPublicModelProp } from '@alilc/lowcode-types'; import { uniqueId, isPlainObject, hasOwnProperty, compatStage, isJSExpression, isJSSlot } from '@alilc/lowcode-utils'; import { valueToSource } from './value-to-source'; import { Props } from './props'; -import { SlotNode, Node } from '../node'; +import { SlotNode, INode } from '../node'; // import { TransformStage } from '../transform-stage'; const { set: mobxSet, isObservableArray } = mobx; @@ -11,19 +11,25 @@ export const UNSET = Symbol.for('unset'); // eslint-disable-next-line no-redeclare export type UNSET = typeof UNSET; -export interface IPropParent { +export interface IProp extends Omit { + delete(prop: Prop): void; + readonly props: Props; - readonly owner: Node; - readonly path: string[]; + + readonly owner: INode; + + export(stage: IPublicEnumTransformStage): IPublicTypeCompositeValue; + + getNode(): INode; } export type ValueTypes = 'unset' | 'literal' | 'map' | 'list' | 'expression' | 'slot'; -export class Prop implements IPropParent { +export class Prop implements IProp { readonly isProp = true; - readonly owner: Node; + readonly owner: INode; /** * 键值 @@ -40,7 +46,7 @@ export class Prop implements IPropParent { readonly options: any; constructor( - public parent: IPropParent, + public parent: IProp, value: IPublicTypeCompositeValue | UNSET = UNSET, key?: string | number, spread = false, @@ -305,9 +311,9 @@ export class Prop implements IPropParent { } } - private _slotNode?: SlotNode; + private _slotNode?: INode; - get slotNode() { + get slotNode(): INode | undefined | null { return this._slotNode; } @@ -342,8 +348,10 @@ export class Prop implements IPropParent { } else { const { owner } = this.props; this._slotNode = owner.document.createNode(slotSchema); - owner.addSlot(this._slotNode); - this._slotNode.internalSetSlotFor(this); + if (this._slotNode) { + owner.addSlot(this._slotNode); + this._slotNode.internalSetSlotFor(this); + } } } diff --git a/packages/designer/src/document/node/props/props.ts b/packages/designer/src/document/node/props/props.ts index 897b54f17..95f29f79a 100644 --- a/packages/designer/src/document/node/props/props.ts +++ b/packages/designer/src/document/node/props/props.ts @@ -1,7 +1,7 @@ import { computed, makeObservable, obx, action } from '@alilc/lowcode-editor-core'; import { IPublicTypePropsMap, IPublicTypePropsList, IPublicTypeCompositeValue, IPublicEnumTransformStage } from '@alilc/lowcode-types'; import { uniqueId, compatStage } from '@alilc/lowcode-utils'; -import { Prop, IPropParent, UNSET } from './prop'; +import { Prop, IProp, UNSET } from './prop'; import { Node } from '../node'; // import { TransformStage } from '../transform-stage'; @@ -23,7 +23,7 @@ export function getConvertedExtraKey(key: string): string { export function getOriginalExtraKey(key: string): string { return key.replace(new RegExp(`${EXTRA_KEY_PREFIX}`, 'g'), ''); } -export class Props implements IPropParent { +export class Props implements IProp { readonly id = uniqueId('props'); @obx.shallow private items: Prop[] = []; diff --git a/packages/shell/src/model/prop.ts b/packages/shell/src/model/prop.ts index 3630ced94..8d4ca7842 100644 --- a/packages/shell/src/model/prop.ts +++ b/packages/shell/src/model/prop.ts @@ -1,7 +1,7 @@ -import { IPropParent as InnerProp } from '@alilc/lowcode-designer'; +import { IProp as InnerProp } from '@alilc/lowcode-designer'; import { IPublicTypeCompositeValue, IPublicEnumTransformStage, IPublicModelProp, IPublicModelNode } from '@alilc/lowcode-types'; import { propSymbol } from '../symbols'; -import { Node } from './node'; +import { Node as ShellNode } from './node'; export class Prop implements IPublicModelProp { private readonly [propSymbol]: InnerProp; @@ -26,6 +26,7 @@ export class Prop implements IPublicModelProp { /** * key 值 + * get key of prop */ get key(): string | number | undefined { return this[propSymbol].key; @@ -34,7 +35,7 @@ export class Prop implements IPublicModelProp { /** * 返回当前 prop 的路径 */ - get path(): any[] { + get path(): string[] { return this[propSymbol].path; } @@ -42,14 +43,14 @@ export class Prop implements IPublicModelProp { * 返回所属的节点实例 */ get node(): IPublicModelNode | null { - return Node.create(this[propSymbol].getNode()); + return ShellNode.create(this[propSymbol].getNode()); } /** * return the slot node (only if the current prop represents a slot) */ get slotNode(): IPublicModelNode | null { - return Node.create(this[propSymbol].slotNode); + return ShellNode.create(this[propSymbol].slotNode); } /** diff --git a/packages/shell/src/model/props.ts b/packages/shell/src/model/props.ts index 5261ac69a..801ee39bd 100644 --- a/packages/shell/src/model/props.ts +++ b/packages/shell/src/model/props.ts @@ -1,4 +1,4 @@ -import { IPropParent as InnerProps, getConvertedExtraKey } from '@alilc/lowcode-designer'; +import { IProp as InnerProps, getConvertedExtraKey } from '@alilc/lowcode-designer'; import { IPublicTypeCompositeValue, IPublicModelProps, IPublicModelNode, IPublicModelProp } from '@alilc/lowcode-types'; import { propsSymbol } from '../symbols'; import { Node } from './node'; diff --git a/packages/types/src/shell/model/node.ts b/packages/types/src/shell/model/node.ts index 2350b5291..70c92016b 100644 --- a/packages/types/src/shell/model/node.ts +++ b/packages/types/src/shell/model/node.ts @@ -4,6 +4,7 @@ import { IPublicEnumTransformStage } from '../enum'; import { IPublicModelNodeChildren, IPublicModelComponentMeta, IPublicModelProp, IPublicModelProps, IPublicModelSettingTopEntry, IPublicModelDocumentModel, IPublicModelExclusiveGroup } from './'; export interface IPublicModelNode { + /** * 节点 id * node id diff --git a/packages/types/src/shell/model/prop.ts b/packages/types/src/shell/model/prop.ts index 7cec09b22..7ac906762 100644 --- a/packages/types/src/shell/model/prop.ts +++ b/packages/types/src/shell/model/prop.ts @@ -3,6 +3,7 @@ import { IPublicTypeCompositeValue } from '../type'; import { IPublicModelNode } from './'; export interface IPublicModelProp { + /** * id */ @@ -10,50 +11,60 @@ export interface IPublicModelProp { /** * key 值 + * get key of prop */ get key(): string | number | undefined; /** * 返回当前 prop 的路径 + * get path of current prop */ - get path(): any[]; + get path(): string[]; /** * 返回所属的节点实例 + * get node instance, which this prop belongs to */ get node(): IPublicModelNode | null; /** + * 当本 prop 代表一个 Slot 时，返回对应的 slotNode * return the slot node (only if the current prop represents a slot) + * @since v1.1.0 */ - get slotNode(): IPublicModelNode | null; + get slotNode(): IPublicModelNode | undefined | null; /** - * judge if it is a prop or not + * 是否是 Prop , 固定返回 true + * check if it is a prop or not, and of course always return true + * @experimental */ get isProp(): boolean; /** * 设置值 + * set value for this prop * @param val */ setValue(val: IPublicTypeCompositeValue): void; /** * 获取值 - * @returns + * get value of this prop */ getValue(): any; /** * 移除值 + * remove value of this prop + * @since v1.0.16 */ remove(): void; /** * 导出值 + * export schema * @param stage - * @returns */ exportSchema(stage: IPublicEnumTransformStage): IPublicTypeCompositeValue; } diff --git a/packages/types/src/shell/type/value-type.ts b/packages/types/src/shell/type/value-type.ts index 2be3cccb8..c0c012544 100644 --- a/packages/types/src/shell/type/value-type.ts +++ b/packages/types/src/shell/type/value-type.ts @@ -7,16 +7,19 @@ import { IPublicTypeNodeData, IPublicTypeCompositeValue, IPublicTypeNodeSchema } */ export interface IPublicTypeJSExpression { type: 'JSExpression'; + /** * 表达式字符串 */ value: string; + /** * 模拟值 * * @todo 待标准描述 */ mock?: any; + /** * 源码 * @@ -33,6 +36,7 @@ export interface IPublicTypeJSExpression { */ export interface IPublicTypeJSFunction { type: 'JSFunction'; + /** * 函数定义，或直接函数表达式 */ @@ -66,21 +70,34 @@ export interface IPublicTypeJSFunction { * 通常用于描述组件的某一个属性为 ReactNode 或 Function return ReactNode 的场景。 */ export interface IPublicTypeJSSlot { + + /** + * type + */ type: 'JSSlot'; + /** * @todo 待标准描述 */ title?: string; + + /** + * @todo 待标准描述 + */ + id?: string; + /** * 组件的某一个属性为 Function return ReactNode 时，函数的入参 * * 其子节点可以通过 this[参数名] 来获取对应的参数。 */ params?: string[]; + /** * 具体的值。 */ value?: IPublicTypeNodeData[] | IPublicTypeNodeData; + /** * @todo 待标准描述 */