feat: 梳理 api 中 model 相关文档, 优化相关 api 实现

docs/docs/api/model/document-model.md

@@ -11,39 +11,86 @@ sidebar_position: 0
 
 ## 变量
 
+### id
+
+唯一 ID
+
+`@type {string}`
+
 ### selection
 
-画布节点选中区模型实例，具体方法参见 [画布节点选中区模型](./selection)
+画布节点选中区模型实例
+
+`@type {IPublicModelSelection}`
+
+相关章节：[节点选中区模型](./selection)
+
+相关类型：[IPublicModelSelection](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/model/selection.ts)
 
 ### detecting
 
-画布节点 hover 区模型实例，具体方法参见 [画布节点悬停模型](./detecting)
+画布节点 hover 区模型实例
+
+`@type {IPublicModelDetecting}`
+
+相关章节：[画布节点悬停模型](./detecting)
+
+相关类型：[IPublicModelDetecting](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/model/detecting.ts)
 
 ### history
 
-操作历史模型实例，具体方法参见 [操作历史模型](./history)
+操作历史模型实例
-### canvas
 
-获取当前画布中的一些信息，比如拖拽时的 dropLocation
+`@type {IPublicModelHistory}`
+
+相关章节：[操作历史模型](./history)
+
+相关类型：[IPublicModelHistory](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/model/history.ts)
 
 ### project
 
 获取当前文档模型所属的 project
 
+`@type {IPublicApiProject}`
+
+相关类型：[IPublicApiProject](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/api/project.ts)
+
 ### root
 
 获取文档的根节点
 
+`@type {IPublicModelNode | null}`
+
+相关类型：[IPublicModelNode](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/model/node.ts)
+
 ### nodesMap
 
-获取文档下所有节点
+获取文档下所有节点 Map, key 为 nodeId
+
+`@type {Map<string, IPublicModelNode>} `
+
+
+相关章节：[节点模型](./node)
+
+相关类型：[IPublicModelNode](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/model/node.ts)
 
 ### modalNodesManager
 
-参见 [模态节点管理](./modal-nodes-manager)
+模态节点管理器
+
+`@type {IPublicModelModalNodesManager | null}`
+
+相关章节：[模态节点管理](./modal-nodes-manager)
+
+相关类型：[IPublicModelModalNodesManager](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/model/modal-nodes-manager.ts)
 
 ### dropLocation
+
 文档的 dropLocation
+
+`@type {IPublicModelDropLocation | null}`
+
+
 相关类型：[IPublicModelDropLocation](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/model/drop-location.ts)
 
 **@since v1.1.0**
@@ -51,51 +98,127 @@ sidebar_position: 0
 ## 方法签名
 ### getNodeById
 
-getNodeById(nodeId: string)
-
 根据 nodeId 返回 [Node](./node) 实例
 
+```typescript
+/**
+ * 根据 nodeId 返回 Node 实例
+ * get node by nodeId
+ * @param nodeId
+ * @returns
+ */
+getNodeById(nodeId: string): IPublicModelNode | null;
+```
+
+相关类型：[IPublicModelNode](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/model/node.ts)
+
+
 ### importSchema
 
-importSchema(schema: RootSchema)
-
 导入 schema
+
+```typescript
+/**
+ * 导入 schema
+ * import schema data
+ * @param schema
+ */
+importSchema(schema: IPublicTypeRootSchema): void;
+```
+
+相关类型：[IPublicTypeRootSchema](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/type/root-schema.ts)
+
+
 ### exportSchema
-
-exportSchema(stage: TransformStage = TransformStage.Render)
-
 导出 schema
 
+```typescript
+/**
+ * 导出 schema
+ * export schema
+ * @param stage
+ * @returns
+ */
+exportSchema(stage: IPublicEnumTransformStage): any;
+```
+
+相关类型：[IPublicEnumTransformStage](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/enum/transform-stage.ts)
+
 ### insertNode
 
-insertNode(
-    parent: Node,
-    thing: Node,
-    at?: number | null | undefined,
-    copy?: boolean | undefined,
-  )
-
 插入节点
+
+```typescript
+/**
+ * 插入节点
+ * insert a node
+ */
+insertNode(
+  parent: IPublicModelNode,
+  thing: IPublicModelNode,
+  at?: number | null | undefined,
+  copy?: boolean | undefined
+): IPublicModelNode | null;
+```
+
+相关类型：[IPublicModelNode](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/model/node.ts)
+
 ### createNode
 
-createNode(data: any)
-
 创建一个节点
+
+```typescript
+/**
+ * 创建一个节点
+ * create a node
+ * @param data
+ * @returns
+ */
+createNode(data: any): IPublicModelNode | null;
+```
+
+相关类型：[IPublicModelNode](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/model/node.ts)
+
 ### removeNode
 
-removeNode(idOrNode: string | Node)
-
 移除指定节点/节点id
 
+```typescript
+/**
+ * 移除指定节点/节点id
+ * remove a node by node instance or nodeId
+ * @param idOrNode
+ */
+removeNode(idOrNode: string | IPublicModelNode): void;
+```
+
+相关类型：[IPublicModelNode](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/model/node.ts)
+
 ### checkNesting
 检查拖拽放置的目标节点是否可以放置该拖拽对象
 
-**@since v1.0.16**
-
 ```typescript
-function checkNesting(dropTarget: Node, dragObject: DragNodeObject | DragNodeDataObject): boolean {}
+/**
+ * 检查拖拽放置的目标节点是否可以放置该拖拽对象
+ * check if dragOjbect can be put in this dragTarget
+ * @param dropTarget 拖拽放置的目标节点
+ * @param dragObject 拖拽的对象
+ * @returns boolean 是否可以放置
+ * @since v1.0.16
+ */
+checkNesting(
+  dropTarget: IPublicModelNode,
+  dragObject: IPublicTypeDragNodeObject | IPublicTypeDragNodeDataObject
+): boolean;
 ```
 
+相关类型：
+- [IPublicModelNode](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/model/node.ts)
+- [IPublicTypeDragNodeObject](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/type/drag-node-object.ts)
+- [IPublicTypeDragNodeDataObject](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/type/drag-node-object-data.ts)
+
+**@since v1.0.16**
+
 ### isDetectingNode
 检查拖拽放置的目标节点是否可以放置该拖拽对象
 
@@ -117,48 +240,107 @@ isDetectingNode(node: IPublicModelNode): boolean;
 ## 事件
 ### onAddNode
 
-onAddNode(fn: (node: Node) => void)
-
 当前 document 新增节点事件
 
 ```typescript
-import { project } from '@alilc/lowcode-engine';
+/**
-
+ * 当前 document 新增节点事件
-project.currentDocument.onAddNode((node) => {
+ * set callback for event on node is created for a document
-  console.log('node', node);
+ */
-})
+onAddNode(fn: (node: IPublicModelNode) => void): IPublicTypeDisposable;
 ```
 
+相关类型：
+- [IPublicModelNode](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/model/node.ts)
+- [IPublicTypeDisposable](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/type/disposable.ts)
+
+### onMountNode
+
+当前 document 新增节点事件，此时节点已经挂载到 document 上
+
+```typescript
+/**
+ * 当前 document 新增节点事件，此时节点已经挂载到 document 上
+ * set callback for event on node is mounted to canvas
+ */
+onMountNode(fn: (payload: { node: IPublicModelNode }) => void): IPublicTypeDisposable;
+```
+
+相关类型：
+- [IPublicModelNode](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/model/node.ts)
+- [IPublicTypeDisposable](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/type/disposable.ts)
+
 ### onRemoveNode
-
-onRemoveNode(fn: (node: Node) => void)
-
 当前 document 删除节点事件
 
+```typescript
+/**
+ * 当前 document 删除节点事件
+ * set callback for event on node is removed
+ */
+onRemoveNode(fn: (node: IPublicModelNode) => void): IPublicTypeDisposable;
+```
+
+相关类型：
+- [IPublicModelNode](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/model/node.ts)
+- [IPublicTypeDisposable](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/type/disposable.ts)
+
+
 ### onChangeDetecting
 
-onChangeDetecting(fn: (node: Node) => void)
-
 当前 document 的 hover 变更事件
 
+```typescript
+/**
+ * 当前 document 的 hover 变更事件
+ *
+ * set callback for event on detecting changed
+ */
+onChangeDetecting(fn: (node: IPublicModelNode) => void): IPublicTypeDisposable;
+```
+
+相关类型：
+- [IPublicModelNode](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/model/node.ts)
+- [IPublicTypeDisposable](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/type/disposable.ts)
+
 ### onChangeSelection
 
-onChangeSelection(fn: (ids: string[]) => void)
-
 当前 document 的选中变更事件
 
+```typescript
+/**
+ * 当前 document 的选中变更事件
+ * set callback for event on selection changed
+ */
+onChangeSelection(fn: (ids: string[]) => void): IPublicTypeDisposable;
+```
+
+相关类型：[IPublicTypeDisposable](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/type/disposable.ts)
+
 ### onChangeNodeVisible
 
-onChangeNodeVisible(fn: (node: Node, visible: boolean) => void)
-
 当前 document 的节点显隐状态变更事件
 
+```typescript
+/**
+ * 当前 document 的节点显隐状态变更事件
+ * set callback for event on visibility changed for certain node
+ * @param fn
+ */
+onChangeNodeVisible(fn: (node: IPublicModelNode, visible: boolean) => void): void;
+```
+
+相关类型：[IPublicModelNode](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/model/node.ts)
+
 ### onChangeNodeChildren
 
 onChangeNodeChildren(fn: (info?: IPublicOnChangeOptions) => void)
 
 当前 document 的节点 children 变更事件
 
+```typescript
+```
+
 ### onChangeNodeProp
 当前 document 节点属性修改事件
 

docs/docs/api/model/node.md

@@ -14,237 +14,634 @@ sidebar_position: 1
 
 节点 id
 
+`@type {string}`
+
 ### title
 
 节点标题
 
-### isContainer
+`@type {string | IPublicTypeI18nData | ReactElement}`
+
+相关类型：[IPublicTypeI18nData](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/type/i18n-data.ts)
+
+### isContainerNode
 
 是否为「容器型」节点
 
-### isRoot
+`@type {boolean}`
+
+**@since v1.1.0**
+> v1.1.0 之前请使用 `isContainer`
+
+### isRootNode
 
 是否为根节点
 
-### isEmpty
+`@type {boolean}`
+
+**@since v1.1.0**
+
+> v1.1.0 之前请使用 `isRoot`
+
+### isEmptyNode
 
 是否为空节点（无 children 或者 children 为空）
 
-### isPage
+`@type {boolean}`
+
+**@since v1.1.0**
+
+> v1.1.0 之前请使用 `isEmpty`
+
+### isPageNode
 
 是否为 Page 节点
 
-### isComponent
+`@type {boolean}`
+
+**@since v1.1.0**
+
+> v1.1.0 之前请使用 `isPage`
+
+### isComponentNode
 
 是否为 Component 节点
 
-### isModal
+`@type {boolean}`
+
+**@since v1.1.0**
+
+> v1.1.0 之前请使用 `isComponent`
+
+### isModalNode
 
 是否为「模态框」节点
 
-### isSlot
+`@type {boolean}`
+
+**@since v1.1.0**
+
+> v1.1.0 之前请使用 `isModal`
+
+### isSlotNode
 
 是否为插槽节点
 
-### isParental
+`@type {boolean}`
+
+**@since v1.1.0**
+
+> v1.1.0 之前请使用 `isSlot`
+
+### isParentalNode
 
 是否为父类/分支节点
 
-### isLeaf
+`@type {boolean}`
+
+**@since v1.1.0**
+
+> v1.1.0 之前请使用 `isParental`
+
+### isLeafNode
+
 是否为叶子节点
 
+`@type {boolean}`
+
+**@since v1.1.0**
+
+> v1.1.0 之前请使用 `isLeaf`
+
 ### isLocked
+
 获取当前节点的锁定状态
 
 **@since v1.0.16**
 
-### isRGLContainer
+### isRGLContainerNode
 设置为磁贴布局节点，使用方式可参考：[磁贴布局在钉钉宜搭报表设计引擎中的实现](https://mp.weixin.qq.com/s/PSTut5ahAB8nlJ9kBpBaxw)
 
-**@since v1.0.16**
+`@type {boolean}`
+
+**@since v1.1.0**
+
+> v1.0.16 - v1.1.0 请使用 `isRGLContainer`
 
 ### index
 
 下标
 
+`@type {number}`
+
 ### icon
 
 图标
 
+`@type {IPublicTypeIconType}`
+
+相关类型：[IPublicTypeIconType](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/type/icon-type.ts)
+
 ### zLevel
 
 节点所在树的层级深度，根节点深度为 0
 
+`@type {number}`
+
 ### componentName
 
 节点 componentName
 
+`@type {string}`
+
 ### componentMeta
 
-节点的物料元数据，参见 物料元数据
+节点的物料元数据
+
+`@type {IPublicModelComponentMeta | null}`
+
+相关类型：[IPublicTypeIconType](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/model/component-meta.ts)
+
 
 ### document
 
 获取节点所属的[文档模型](./document-model)对象
 
+`@type {IPublicModelDocumentModel | null}`
+
+相关类型：[IPublicModelDocumentModel](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/model/document-model.ts)
+
 ### prevSibling
 
 获取当前节点的前一个兄弟节点
 
+`@type {IPublicModelNode | null}`
+
 ### nextSibling
 
 获取当前节点的后一个兄弟节点
 
+`@type {IPublicModelNode | null}`
+
 ### parent
 
 获取当前节点的父亲节点
 
+`@type {IPublicModelNode | null}`
+
 ### children
 
 获取当前节点的孩子节点模型
 
+`@type {IPublicModelNodeChildren | null}`
+
+相关类型：[IPublicModelNodeChildren](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/model/node-children.ts)
+
 ### slots
 
 节点上挂载的插槽节点们
 
+`@type {IPublicModelNode[]}`
+
 ### slotFor
 
 当前节点为插槽节点时，返回节点对应的属性实例
 
+`@type {IPublicModelProp | null}`
+
+相关类型：[IPublicModelProp](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/model/prop.ts)
+
 ### props
 
 返回节点的属性集
 
+`@type {IPublicModelProps | null}`
+
+相关类型：[IPublicModelProps](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/model/props.ts)
+
+
 ### propsData
 
 返回节点的属性集值
 
+`@type {IPublicTypePropsMap | IPublicTypePropsList | null}`
+
+相关类型：
+- [IPublicTypePropsMap](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/type/props-map.ts)
+- [IPublicTypePropsList](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/type/props-list.ts)
+
+### conditionGroup
+
+获取条件组
+
+`@type {IPublicModelExclusiveGroup | null}`
+
+相关类型：[IPublicModelExclusiveGroup](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/model/exclusive-group.ts)
+
+**@since v1.1.0**
+
+### schema
+
+获取符合搭建协议 - 节点 schema 结构
+
+`@type {IPublicTypeNodeSchema | null}`
+
+相关类型：[IPublicTypeNodeSchema](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/type/node-schema.ts)
+
+### settingEntry
+
+获取对应的 setting entry
+
+`@type {IPublicModelSettingTopEntry}`
+
+相关类型：[IPublicModelSettingTopEntry](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/model/setting-top-entry.ts)
+
+### visible
+当前节点是否可见
+
+`@type {boolean}`
+
+**@since v1.1.0**
+
 ## 方法签名
-### getDOMNode
-
-getDOMNode()
-
-获取节点实例对应的 dom 节点
 
 ### getRect
 
-getRect()
-
 返回节点的尺寸、位置信息
 
+```typescript
+/**
+ * 返回节点的尺寸、位置信息
+ * get rect information for this node
+ */
+getRect(): DOMRect | null;
+```
+
 ### hasSlots
 
-hasSlots()
-
 是否有挂载插槽节点
 
+```typescript
+/**
+ * 是否有挂载插槽节点
+ * check if current node has slots
+ */
+hasSlots(): boolean;
+```
+
 ### hasCondition
 
-hasCondition()
-
 是否设定了渲染条件
 
+```typescript
+/**
+ * 是否设定了渲染条件
+ * check if current node has condition value set
+ */
+hasCondition(): boolean;
+```
+
 ### hasLoop
 
-hasLoop()
-
 是否设定了循环数据
 
+```typescript
+/**
+ * 是否设定了循环数据
+ * check if loop is set for this node
+ */
+hasLoop(): boolean;
+```
+
 ### getProp
 
-getProp(path: string): Prop | null
-
 获取指定 path 的属性模型实例
 
+```typescript
+/**
+ * 获取指定 path 的属性模型实例
+ * get prop by path
+ * @param path 属性路径，支持 a / a.b / a.0 等格式
+ */
+getProp(path: string, createIfNone: boolean): IPublicModelProp | null;
+```
+
+相关类型：[IPublicModelProp](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/model/prop.ts)
+
 ### getPropValue
 
-getPropValue(path: string)
-
 获取指定 path 的属性模型实例值
 
+```typescript
+/**
+ * 获取指定 path 的属性模型实例值
+ * get prop value by path
+ * @param path 属性路径，支持 a / a.b / a.0 等格式
+ */
+getPropValue(path: string): any;
+```
+
 ### getExtraProp
 
-getExtraProp(path: string): Prop | null
-
 获取指定 path 的属性模型实例，注：导出时，不同于普通属性，该属性并不挂载在 props 之下，而是与 props 同级
 
+```typescript
+/**
+ * 获取指定 path 的属性模型实例，
+ *  注：导出时，不同于普通属性，该属性并不挂载在 props 之下，而是与 props 同级
+ *
+ * get extra prop by path, an extra prop means a prop not exists in the `props`
+ * but as siblint of the `props`
+ * @param path 属性路径，支持 a / a.b / a.0 等格式
+ * @param createIfNone 当没有属性的时候，是否创建一个属性
+ */
+getExtraProp(path: string, createIfNone?: boolean): IPublicModelProp | null;
+```
+
+相关类型：[IPublicModelProp](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/model/prop.ts)
+
 ### getExtraPropValue
 
-getExtraPropValue(path: string)
-
 获取指定 path 的属性模型实例，注：导出时，不同于普通属性，该属性并不挂载在 props 之下，而是与 props 同级
 
+```typescript
+/**
+ * 获取指定 path 的属性模型实例，
+ *  注：导出时，不同于普通属性，该属性并不挂载在 props 之下，而是与 props 同级
+ *
+ * get extra prop value by path, an extra prop means a prop not exists in the `props`
+ * but as siblint of the `props`
+ * @param path 属性路径，支持 a / a.b / a.0 等格式
+ * @returns
+ */
+getExtraPropValue(path: string): any;
+```
+
 ### setPropValue
 
 setPropValue(path: string, value: CompositeValue)
 
 设置指定 path 的属性模型实例值
 
-### setExtraPropValue
+```typescript
+/**
+ * 设置指定 path 的属性模型实例值
+ * set value for prop with path
+ * @param path 属性路径，支持 a / a.b / a.0 等格式
+ * @param value 值
+ */
+setPropValue(path: string, value: IPublicTypeCompositeValue): void;
+```
 
-setExtraPropValue(path: string, value: CompositeValue)
+相关类型：[IPublicTypeCompositeValue](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/type/composite-value.ts)
+
+
+### setExtraPropValue
 
 设置指定 path 的属性模型实例值
 
-### importSchema
+```typescript
+/**
+ * 设置指定 path 的属性模型实例值
+ * set value for extra prop with path
+ * @param path 属性路径，支持 a / a.b / a.0 等格式
+ * @param value 值
+ */
+setExtraPropValue(path: string, value: IPublicTypeCompositeValue): void;
+```
 
-importSchema(data: NodeSchema)
+相关类型：[IPublicTypeCompositeValue](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/type/composite-value.ts)
+
+### importSchema
 
 导入节点数据
 
-### exportSchema
+```typescript
+/**
+ * 导入节点数据
+ * import node schema
+ * @param data
+ */
+importSchema(data: IPublicTypeNodeSchema): void;
+```
 
-exportSchema(stage: IPublicEnumTransformStage = IPublicEnumTransformStage.Render, options?: any)
+相关类型：[IPublicTypeNodeSchema](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/type/node-schema.ts)
+
+### exportSchema
 
 导出节点数据
 
-### insertBefore
+```typescript
+/**
+ * 导出节点数据
+ * export schema from this node
+ * @param stage
+ * @param options
+ */
+exportSchema(stage: IPublicEnumTransformStage, options?: any): IPublicTypeNodeSchema;
+```
 
-insertBefore(node: Node, ref?: Node | undefined, useMutator?: boolean)
+相关类型：
+- [IPublicEnumTransformStage](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/enum/transform-stage.ts)
+- [IPublicTypeNodeSchema](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/type/node-schema.ts)
+
+### insertBefore
 
 在指定位置之前插入一个节点
 
-### insertAfter
+```typescript
+/**
+ * 在指定位置之前插入一个节点
+ * insert a node befor current node
+ * @param node
+ * @param ref
+ * @param useMutator
+ */
+insertBefore(
+    node: IPublicModelNode,
+    ref?: IPublicModelNode | undefined,
+    useMutator?: boolean,
+  ): void;
+```
 
-insertAfter(node: Node, ref?: Node | undefined, useMutator?: boolean)
+### insertAfter
 
 在指定位置之后插入一个节点
 
+```typescript
+/**
+ * 在指定位置之后插入一个节点
+ * insert a node after this node
+ * @param node
+ * @param ref
+ * @param useMutator
+ */
+insertAfter(
+    node: IPublicModelNode,
+    ref?: IPublicModelNode | undefined,
+    useMutator?: boolean,
+  ): void;
+```
+
 ### replaceChild
 
-replaceChild(node: Node, data: any)
+替换指定子节点
 
-替换指定节点
+```typescript
+/**
+ * 替换指定子节点
+ * replace a child node with data provided
+ * @param node 待替换的子节点
+ * @param data 用作替换的节点对象或者节点描述
+ * @returns
+ */
+replaceChild(node: IPublicModelNode, data: any): IPublicModelNode | null;
+```
 
 ### replaceWith
 
-replaceWith(schema: NodeSchema)
-
 将当前节点替换成指定节点描述
 
+```typescript
+/**
+ * 将当前节点替换成指定节点描述
+ * replace current node with a new node schema
+ * @param schema
+ */
+replaceWith(schema: IPublicTypeNodeSchema): any;
+```
+
+相关类型：[IPublicTypeNodeSchema](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/type/node-schema.ts)
+
 ### select
 
-select()
-
 选中当前节点实例
 
+```typescript
+/**
+ * 选中当前节点实例
+ * select current node
+ */
+select(): void;
+```
+
 ### hover
 
-hover(flag = true)
-
 设置悬停态
 
+```typescript
+/**
+ * 设置悬停态
+ * set hover value for current node
+ * @param flag
+ */
+hover(flag: boolean): void;
+```
+
 ### lock
 设置节点锁定状态
 
 ```typescript
-function lock(flag?: boolean){}
+/**
+ * 设置节点锁定状态
+ * set lock value for current node
+ * @param flag
+ * @since v1.0.16
+ */
+lock(flag?: boolean): void;
 ```
 
 **@since v1.0.16**
 
 ### remove
 
-remove()
+删除当前节点实例
 
-删除当前节点实例
+```typescript
+/**
+ * 删除当前节点实例
+ * remove current node
+ */
+remove(): void;
+```
+
+### mergeChildren
+
+执行新增、删除、排序等操作
+
+```typescript
+/**
+ * 执行新增、删除、排序等操作
+ * excute remove/add/sort operations on node`s children
+ *
+ * @since v1.1.0
+ */
+mergeChildren(
+  remover: (node: IPublicModelNode, idx: number) => boolean,
+  adder: (children: IPublicModelNode[]) => any,
+  sorter: (firstNode: IPublicModelNode, secondNode: IPublicModelNode) => number
+): any;
+```
+
+**@since v1.1.0**
+
+### contains
+
+当前节点是否包含某子节点
+
+```typescript
+/**
+ * 当前节点是否包含某子节点
+ * check if current node contains another node as a child
+ * @param node
+ * @since v1.1.0
+ */
+contains(node: IPublicModelNode): boolean;
+```
+
+**@since v1.1.0**
+
+### canPerformAction
+
+是否可执行某 action
+
+```typescript
+/**
+ * 是否可执行某 action
+ * check if current node can perform certain aciton with actionName
+ * @param actionName action 名字
+ * @since v1.1.0
+ */
+canPerformAction(actionName: string): boolean;
+```
+
+**@since v1.1.0**
+
+### isConditionalVisible
+
+获取该节点的 ConditionalVisible 值
+
+```typescript
+/**
+ * 获取该节点的 ConditionalVisible 值
+ * check if current node ConditionalVisible
+ * @since v1.1.0
+ */
+isConditionalVisible(): boolean | undefined;
+```
+
+**@since v1.1.0**
+
+### setConditionalVisible
+设置该节点的 ConditionalVisible 为 true
+
+```typescript
+/**
+ * 设置该节点的 ConditionalVisible 为 true
+ * make this node as conditionalVisible === true
+ * @since v1.1.0
+ */
+setConditionalVisible(): void;
+```
+
+**@since v1.1.0**

docs/docs/specs/assets-spec.md

@@ -2,8 +2,6 @@
 title: 《低代码引擎资产包协议规范》
 sidebar_position: 2
 ---
-# 《低代码引擎资产包协议规范》
-
 ## 1 介绍
 
 ### 1.1 本协议规范涉及的问题域

docs/docs/specs/lowcode-spec.md

@@ -2,8 +2,6 @@
 title: 《低代码引擎搭建协议规范》
 sidebar_position: 0
 ---
-# 《低代码引擎搭建协议规范》
-
 
 ## 1 介绍
 

docs/docs/specs/material-spec.md

@@ -2,7 +2,6 @@
 title: 《低代码引擎物料协议规范》
 sidebar_position: 1
 ---
-# 《低代码引擎物料协议规范》
 
 ## 1 介绍
 

packages/designer/src/document/node/node.ts

@@ -32,6 +32,9 @@ import { NodeRemoveOptions } from '../../types';
 
 export interface INode extends IPublicModelNode {
 
+  setVisible(flag: boolean): void;
+
+  getVisible(): boolean;
 }
 
 /**
@@ -261,27 +264,59 @@ export class Node<Schema extends IPublicTypeNodeSchema = IPublicTypeNodeSchema>
     return !!this._isRGLContainer;
   }
 
+  set isRGLContainerNode(status: boolean) {
+    this._isRGLContainer = status;
+  }
+
+  get isRGLContainerNode(): boolean {
+    return !!this._isRGLContainer;
+  }
+
   isContainer(): boolean {
-    return this.isParental() && this.componentMeta.isContainer;
+    return this.isContainerNode;
+  }
+
+  get isContainerNode(): boolean {
+    return this.isParentalNode && this.componentMeta.isContainer;
   }
 
   isModal(): boolean {
+    return this.isModalNode;
+  }
+
+  get isModalNode(): boolean {
     return this.componentMeta.isModal;
   }
 
   isRoot(): boolean {
+    return this.isRootNode;
+  }
+
+  get isRootNode(): boolean {
     return this.document.rootNode === (this as any);
   }
 
   isPage(): boolean {
-    return this.isRoot() && this.componentName === 'Page';
+    return this.isPageNode;
+  }
+
+  get isPageNode(): boolean {
+    return this.isRootNode && this.componentName === 'Page';
   }
 
   isComponent(): boolean {
-    return this.isRoot() && this.componentName === 'Component';
+    return this.isComponentNode;
+  }
+
+  get isComponentNode(): boolean {
+    return this.isRootNode && this.componentName === 'Component';
   }
 
   isSlot(): boolean {
+    return this.isSlotNode;
+  }
+
+  get isSlotNode(): boolean {
     return this._slotFor != null && this.componentName === 'Slot';
   }
 
@@ -289,13 +324,20 @@ export class Node<Schema extends IPublicTypeNodeSchema = IPublicTypeNodeSchema>
    * 是否一个父亲类节点
    */
   isParental(): boolean {
-    return !this.isLeaf();
+    return this.isParentalNode;
+  }
+
+  get isParentalNode(): boolean {
+    return !this.isLeafNode;
   }
 
   /**
    * 终端节点，内容一般为 文字 或者 表达式
    */
-  isLeaf(): this is LeafNode {
+  isLeaf(): boolean {
+    return this.isLeafNode;
+  }
+  get isLeafNode(): boolean {
     return this.componentName === 'Leaf';
   }
 

packages/plugin-outline-pane/src/controllers/tree-node.ts

@@ -110,7 +110,7 @@ export default class TreeNode {
   get hidden(): boolean {
     const cv = this.node.isConditionalVisible();
     if (cv == null) {
-      return !this.node.getVisible();
+      return !this.node.visible;
     }
     return !cv;
   }
@@ -119,7 +119,7 @@ export default class TreeNode {
     if (this.node.conditionGroup) {
       return;
     }
-    this.node.setVisible(!flag);
+    this.node.visible = !flag;
     this.onHiddenChanged && this.onHiddenChanged(flag);
   }
 

packages/plugin-outline-pane/src/views/tree-title.tsx

@@ -122,7 +122,7 @@ export default class TreeTitle extends Component<{
         data-id={treeNode.id}
         onClick={() => {
           if (isModal) {
-            if (node.getVisible()) {
+            if (node.visible) {
               node.document?.modalNodesManager?.setInvisible(node);
             } else {
               node.document?.modalNodesManager?.setVisible(node);
@@ -134,7 +134,7 @@ export default class TreeTitle extends Component<{
           }
         }}
       >
-        {isModal && node.getVisible() && (
+        {isModal && node.visible && (
           <div onClick={() => {
             node.document?.modalNodesManager?.setInvisible(node);
           }}
@@ -142,7 +142,7 @@ export default class TreeTitle extends Component<{
             <IconRadioActive className="tree-node-modal-radio-active" />
           </div>
         )}
-        {isModal && !node.getVisible() && (
+        {isModal && !node.visible && (
           <div onClick={() => {
             node.document?.modalNodesManager?.setVisible(node);
           }}

packages/shell/src/model/document-model.ts

@@ -29,6 +29,7 @@ import { Node } from './node';
 import { Selection } from './selection';
 import { Detecting } from './detecting';
 import { History } from './history';
+import { DropLocation } from './drop-location';
 import { Project } from '../api/project';
 import { Prop } from './prop';
 import { ModalNodesManager } from './modal-nodes-manager';
@@ -45,7 +46,7 @@ export class DocumentModel implements IPublicModelDocumentModel {
   detecting: IPublicModelDetecting;
   history: IPublicModelHistory;
   /**
-   * @deprecated
+   * @deprecated use canvas API instead
    */
   canvas: IPublicApiCanvas;
 
@@ -89,12 +90,13 @@ export class DocumentModel implements IPublicModelDocumentModel {
    * 获取当前文档所属的 project
    * @returns
    */
-  get project(): IPublicApiProject | null {
+  get project(): IPublicApiProject {
     return Project.create(this[documentSymbol].project);
   }
 
   /**
    * 获取文档的根节点
+   * root node of this documentModel
    * @returns
    */
   get root(): IPublicModelNode | null {
@@ -114,10 +116,10 @@ export class DocumentModel implements IPublicModelDocumentModel {
   }
 
   /**
-   * 获取文档下所有节点
+   * 获取文档下所有节点 Map, key 为 nodeId
-   * @returns
+   * get map of all nodes , using node.id as key
    */
-  get nodesMap(): any {
+  get nodesMap(): Map<string, IPublicModelNode> {
     const map = new Map<string, IPublicModelNode>();
     for (let id of this[documentSymbol].nodesMap.keys()) {
       map.set(id, this.getNodeById(id)!);
@@ -132,11 +134,8 @@ export class DocumentModel implements IPublicModelDocumentModel {
     return ModalNodesManager.create(this[documentSymbol].modalNodesManager);
   }
 
-  /**
+  get dropLocation(): IPublicModelDropLocation | null {
-   * @TODO: 能不能直接暴露
+    return DropLocation.create(this[documentSymbol].dropLocation);
-   */
-  get dropLocation(): IPublicModelDropLocation {
-    return this[documentSymbol].dropLocation;
   }
 
   set dropLocation(loc: IPublicModelDropLocation | null) {
@@ -144,8 +143,8 @@ export class DocumentModel implements IPublicModelDocumentModel {
   }
   /**
    * 根据 nodeId 返回 Node 实例
-   * @param nodeId
+   * get node instance by nodeId
-   * @returns
+   * @param {string} nodeId
    */
   getNodeById(nodeId: string): IPublicModelNode | null {
     return Node.create(this[documentSymbol].getNode(nodeId));

packages/shell/src/model/drop-location.ts

@@ -3,7 +3,7 @@ import {
 } from '@alilc/lowcode-designer';
 import { dropLocationSymbol } from '../symbols';
 import { Node } from './node';
-import { IPublicModelDropLocation } from '@alilc/lowcode-types';
+import { IPublicModelDropLocation, IPublicTypeLocationDetail, IPublicModelLocateEvent } from '@alilc/lowcode-types';
 
 export class DropLocation implements IPublicModelDropLocation {
   private readonly [dropLocationSymbol]: InnerDropLocation;
@@ -12,7 +12,7 @@ export class DropLocation implements IPublicModelDropLocation {
     this[dropLocationSymbol] = dropLocation;
   }
 
-  static create(dropLocation: InnerDropLocation | null): DropLocation | null {
+  static create(dropLocation: InnerDropLocation | null): IPublicModelDropLocation | null {
     if (!dropLocation) {
       return null;
     }
@@ -22,4 +22,12 @@ export class DropLocation implements IPublicModelDropLocation {
   get target() {
     return Node.create(this[dropLocationSymbol].target);
   }
+
+  get detail(): IPublicTypeLocationDetail {
+    return this[dropLocationSymbol].detail;
+  }
+
+  clone(event: IPublicModelLocateEvent): IPublicModelDropLocation {
+    return new DropLocation(this[dropLocationSymbol].clone(event));
+  }
 }

packages/shell/src/model/node.ts

@@ -1,5 +1,6 @@
 import {
-  DocumentModel as InnerDocumentModel,
+  IDocumentModel as InnerDocumentModel,
+  INode as InnerNode,
 } from '@alilc/lowcode-designer';
 import {
   IPublicTypeCompositeValue,
@@ -16,6 +17,7 @@ import {
   IPublicTypePropsMap,
   IPublicTypePropsList,
   IPublicModelSettingTopEntry,
+  IPublicModelExclusiveGroup,
 } from '@alilc/lowcode-types';
 import { Prop } from './prop';
 import { Props } from './props';
@@ -29,8 +31,8 @@ import { ReactElement } from 'react';
 const shellNodeSymbol = Symbol('shellNodeSymbol');
 
 export class Node implements IPublicModelNode {
-  private readonly [documentSymbol]: InnerDocumentModel;
+  private readonly [documentSymbol]: InnerDocumentModel | null;
-  private readonly [nodeSymbol]: IPublicModelNode;
+  private readonly [nodeSymbol]: InnerNode;
 
   private _id: string;
 
@@ -81,14 +83,14 @@ export class Node implements IPublicModelNode {
    * 是否为「容器型」节点
    */
   get isContainer(): boolean {
-    return this[nodeSymbol].isContainer();
+    return this[nodeSymbol].isContainerNode;
   }
 
   /**
    * 是否为「容器型」节点
    */
   get isContainerNode(): boolean {
-    return this[nodeSymbol].isContainer();
+    return this[nodeSymbol].isContainerNode;
   }
 
   /**
@@ -96,14 +98,14 @@ export class Node implements IPublicModelNode {
    * 是否为根节点
    */
   get isRoot(): boolean {
-    return this[nodeSymbol].isRoot();
+    return this[nodeSymbol].isRootNode;
   }
 
   /**
    * 是否为根节点
    */
   get isRootNode(): boolean {
-    return this[nodeSymbol].isRoot();
+    return this[nodeSymbol].isRootNode;
   }
 
   /**
@@ -111,14 +113,14 @@ export class Node implements IPublicModelNode {
    * 是否为空节点（无 children 或者 children 为空）
    */
   get isEmpty(): boolean {
-    return this[nodeSymbol].isEmpty();
+    return this[nodeSymbol].isEmptyNode;
   }
 
   /**
    * 是否为空节点（无 children 或者 children 为空）
    */
   get isEmptyNode(): boolean {
-    return this[nodeSymbol].isEmpty();
+    return this[nodeSymbol].isEmptyNode;
   }
 
   /**
@@ -126,14 +128,14 @@ export class Node implements IPublicModelNode {
    * 是否为 Page 节点
    */
   get isPage(): boolean {
-    return this[nodeSymbol].isPage();
+    return this[nodeSymbol].isPageNode;
   }
 
   /**
    * 是否为 Page 节点
    */
   get isPageNode(): boolean {
-    return this[nodeSymbol].isPage();
+    return this[nodeSymbol].isPageNode;
   }
 
   /**
@@ -141,14 +143,14 @@ export class Node implements IPublicModelNode {
    * 是否为 Component 节点
    */
   get isComponent(): boolean {
-    return this[nodeSymbol].isComponent();
+    return this[nodeSymbol].isComponentNode;
   }
 
   /**
    * 是否为 Component 节点
    */
   get isComponentNode(): boolean {
-    return this[nodeSymbol].isComponent();
+    return this[nodeSymbol].isComponentNode;
   }
 
   /**
@@ -156,14 +158,14 @@ export class Node implements IPublicModelNode {
    * 是否为「模态框」节点
    */
   get isModal(): boolean {
-    return this[nodeSymbol].isModal();
+    return this[nodeSymbol].isModalNode;
   }
 
   /**
    * 是否为「模态框」节点
    */
   get isModalNode(): boolean {
-    return this[nodeSymbol].isModal();
+    return this[nodeSymbol].isModalNode;
   }
 
   /**
@@ -171,14 +173,14 @@ export class Node implements IPublicModelNode {
    * 是否为插槽节点
    */
   get isSlot(): boolean {
-    return this[nodeSymbol].isSlot();
+    return this[nodeSymbol].isSlotNode;
   }
 
   /**
    * 是否为插槽节点
    */
   get isSlotNode(): boolean {
-    return this[nodeSymbol].isSlot();
+    return this[nodeSymbol].isSlotNode;
   }
 
   /**
@@ -186,14 +188,14 @@ export class Node implements IPublicModelNode {
    * 是否为父类/分支节点
    */
   get isParental(): boolean {
-    return this[nodeSymbol].isParental();
+    return this[nodeSymbol].isParentalNode;
   }
 
   /**
    * 是否为父类/分支节点
    */
   get isParentalNode(): boolean {
-    return this[nodeSymbol].isParental();
+    return this[nodeSymbol].isParentalNode;
   }
 
   /**
@@ -201,14 +203,14 @@ export class Node implements IPublicModelNode {
    * 是否为叶子节点
    */
   get isLeaf(): boolean {
-    return this[nodeSymbol].isLeaf();
+    return this[nodeSymbol].isLeafNode;
   }
 
   /**
    * 是否为叶子节点
    */
   get isLeafNode(): boolean {
-    return this[nodeSymbol].isLeaf();
+    return this[nodeSymbol].isLeafNode;
   }
 
   /**
@@ -398,6 +400,14 @@ export class Node implements IPublicModelNode {
     return this[nodeSymbol].hasLoop();
   }
 
+  get visible(): boolean {
+    return this[nodeSymbol].getVisible();
+  }
+
+  set visible(value: boolean) {
+    this[nodeSymbol].setVisible(value);
+  }
+
   getVisible(): boolean {
     return this[nodeSymbol].getVisible();
   }
@@ -620,4 +630,20 @@ export class Node implements IPublicModelNode {
   canPerformAction(actionName: string): boolean {
     return this[nodeSymbol].canPerformAction(actionName);
   }
+
+  /**
+   * get conditionGroup
+   * @since v1.1.0
+   */
+  get conditionGroup(): IPublicModelExclusiveGroup | null {
+    return this[nodeSymbol].conditionGroup;
+  }
+
+  /**
+   * set value for conditionalVisible
+   * @since v1.1.0
+   */
+  setConditionalVisible(): void {
+    this[nodeSymbol].setConditionalVisible();
+  }
 }

packages/types/src/shell/model/document-model.ts

@@ -12,20 +12,34 @@ export interface IPublicModelDocumentModel {
 
   set id(id);
 
+  /**
+   * 节点选中区模型实例
+   * instance of selection
+   */
   selection: IPublicModelSelection;
 
+  /**
+   * 画布节点 hover 区模型实例
+   * instance of detecting
+   */
   detecting: IPublicModelDetecting;
 
+  /**
+   * 操作历史模型实例
+   * instance of history
+   */
   history: IPublicModelHistory;
 
   /**
    * 获取当前文档所属的 project
+   * get project which this documentModel belongs to
    * @returns
    */
-  get project(): IPublicApiProject | null;
+  get project(): IPublicApiProject;
 
   /**
    * 获取文档的根节点
+   * root node of this documentModel
    * @returns
    */
   get root(): IPublicModelNode | null;
@@ -38,15 +52,17 @@ export interface IPublicModelDocumentModel {
    * 获取文档下所有节点
    * @returns
    */
-  get nodesMap(): any;
+  get nodesMap(): Map<string, IPublicModelNode>;
 
   /**
    * 模态节点管理
+   * get instance of modalNodesManager
    */
   get modalNodesManager(): IPublicModelModalNodesManager | null;
 
   /**
    * 根据 nodeId 返回 Node 实例
+   * get node by nodeId
    * @param nodeId
    * @returns
    */
@@ -54,12 +70,14 @@ export interface IPublicModelDocumentModel {
 
   /**
    * 导入 schema
+   * import schema data
    * @param schema
    */
   importSchema(schema: IPublicTypeRootSchema): void;
 
   /**
    * 导出 schema
+   * export schema
    * @param stage
    * @returns
    */
@@ -67,11 +85,7 @@ export interface IPublicModelDocumentModel {
 
   /**
    * 插入节点
-   * @param parent
+   * insert a node
-   * @param thing
-   * @param at
-   * @param copy
-   * @returns
    */
   insertNode(
     parent: IPublicModelNode,
@@ -82,6 +96,7 @@ export interface IPublicModelDocumentModel {
 
   /**
    * 创建一个节点
+   * create a node
    * @param data
    * @returns
    */
@@ -89,6 +104,7 @@ export interface IPublicModelDocumentModel {
 
   /**
    * 移除指定节点/节点id
+   * remove a node by node instance or nodeId
    * @param idOrNode
    */
   removeNode(idOrNode: string | IPublicModelNode): void;
@@ -102,9 +118,11 @@ export interface IPublicModelDocumentModel {
 
   /**
    * 检查拖拽放置的目标节点是否可以放置该拖拽对象
+   * check if dragOjbect can be put in this dragTarget
    * @param dropTarget 拖拽放置的目标节点
    * @param dragObject 拖拽的对象
    * @returns boolean 是否可以放置
+   * @since v1.0.16
    */
   checkNesting(
     dropTarget: IPublicModelNode,
@@ -113,31 +131,38 @@ export interface IPublicModelDocumentModel {
 
   /**
    * 当前 document 新增节点事件
+   * set callback for event on node is created for a document
    */
   onAddNode(fn: (node: IPublicModelNode) => void): IPublicTypeDisposable;
 
   /**
    * 当前 document 新增节点事件，此时节点已经挂载到 document 上
+   * set callback for event on node is mounted to canvas
    */
   onMountNode(fn: (payload: { node: IPublicModelNode }) => void): IPublicTypeDisposable;
 
   /**
    * 当前 document 删除节点事件
+   * set callback for event on node is removed
    */
   onRemoveNode(fn: (node: IPublicModelNode) => void): IPublicTypeDisposable;
 
   /**
    * 当前 document 的 hover 变更事件
+   *
+   * set callback for event on detecting changed
    */
   onChangeDetecting(fn: (node: IPublicModelNode) => void): IPublicTypeDisposable;
 
   /**
    * 当前 document 的选中变更事件
+   * set callback for event on selection changed
    */
   onChangeSelection(fn: (ids: string[]) => void): IPublicTypeDisposable;
 
   /**
    * 当前 document 的节点显隐状态变更事件
+   * set callback for event on visibility changed for certain node
    * @param fn
    */
   onChangeNodeVisible(fn: (node: IPublicModelNode, visible: boolean) => void): void;
@@ -169,7 +194,7 @@ export interface IPublicModelDocumentModel {
    * get current drop location
    * @since v1.1.0
    */
-  get dropLocation(): IPublicModelDropLocation;
+  get dropLocation(): IPublicModelDropLocation | null;
 
   /**
    * 设置当前的 DropLocation 信息

packages/types/src/shell/model/node.ts

@@ -6,43 +6,49 @@ import { IPublicModelNodeChildren, IPublicModelComponentMeta, IPublicModelProp,
 export interface IPublicModelNode {
   /**
    * 节点 id
+   * node id
    */
   id: string;
+
   /**
    * 节点标题
+   * title of node
    */
   get title(): string | IPublicTypeI18nData | ReactElement;
 
   /**
    * @deprecated please use isContainerNode
-   * 是否为「容器型」节点
    */
   get isContainer(): boolean;
 
   /**
    * 是否为「容器型」节点
+   * check if node is a container type node
+   * @since v1.1.0
    */
   get isContainerNode(): boolean;
 
   /**
    * @deprecated please use isRootNode
-   * 是否为根节点
    */
   get isRoot(): boolean;
 
   /**
    * 是否为根节点
+   * check if node is root in the tree
+   * @since v1.1.0
    */
   get isRootNode(): boolean;
 
   /**
    * @deprecated please use isEmptyNode
-   * 是否为空节点（无 children 或者 children 为空）
    */
   get isEmpty(): boolean;
 
   /**
    * 是否为空节点（无 children 或者 children 为空）
+   * check if current node is empty, which means no children or children is empty
+   * @since v1.1.0
    */
   get isEmptyNode(): boolean;
 
@@ -54,220 +60,260 @@ export interface IPublicModelNode {
 
   /**
    * 是否为 Page 节点
+   * check if node is Page
+   * @since v1.1.0
    */
   get isPageNode(): boolean;
 
   /**
    * @deprecated please use isComponentNode
-   * 是否为 Component 节点
    */
   get isComponent(): boolean;
 
   /**
    * 是否为 Component 节点
+   * check if node is Component
+   * @since v1.1.0
    */
   get isComponentNode(): boolean;
 
   /**
    * @deprecated please use isModalNode
-   * 是否为「模态框」节点
    */
   get isModal(): boolean;
 
   /**
    * 是否为「模态框」节点
+   * check if node is Modal
+   * @since v1.1.0
    */
   get isModalNode(): boolean;
 
   /**
    * @deprecated please use isSlotNode
-   * 是否为插槽节点
    */
   get isSlot(): boolean;
 
   /**
    * 是否为插槽节点
+   * check if node is a Slot
+   * @since v1.1.0
    */
   get isSlotNode(): boolean;
 
   /**
    * @deprecated please use isParentalNode
-   * 是否为父类/分支节点
    */
   get isParental(): boolean;
 
   /**
    * 是否为父类/分支节点
+   * check if node a parental node
+   * @since v1.1.0
    */
   get isParentalNode(): boolean;
 
   /**
    * @deprecated please use isLeafNode
-   * 是否为叶子节点
    */
   get isLeaf(): boolean;
 
   /**
    * 是否为叶子节点
+   * check if node is a leaf node in tree
+   * @since v1.1.0
    */
   get isLeafNode(): boolean;
 
   /**
    * 获取当前节点的锁定状态
+   * check if current node is locked
+   * @since v1.0.16
    */
   get isLocked(): boolean;
 
+  /**
+   * @deprecated please use isRGLContainerNode
+   */
+  set isRGLContainer(flag: boolean);
+
+  /**
+   * @deprecated please use isRGLContainerNode
+   * @returns Boolean
+   */
+  get isRGLContainer();
+
+  /**
+   * 设置为磁贴布局节点
+   * @since v1.1.0
+   */
+  set isRGLContainerNode(flag: boolean);
+
+  /**
+   * 获取磁贴布局节点设置状态
+   * @returns Boolean
+   * @since v1.1.0
+   */
+  get isRGLContainerNode();
+
   /**
    * 下标
+   * index
    */
   get index(): number;
 
   /**
    * 图标
+   * get icon of this node
    */
   get icon(): IPublicTypeIconType;
 
   /**
    * 节点所在树的层级深度，根节点深度为 0
+   * depth level of this node, value of root node is 0
    */
   get zLevel(): number;
 
   /**
    * 节点 componentName
+   * componentName
    */
   get componentName(): string;
 
   /**
    * 节点的物料元数据
+   * get component meta of this node
    */
   get componentMeta(): IPublicModelComponentMeta | null;
 
   /**
    * 获取节点所属的文档模型对象
-   * @returns
+   * get documentModel of this node
    */
   get document(): IPublicModelDocumentModel | null;
 
   /**
    * 获取当前节点的前一个兄弟节点
-   * @returns
+   * get previous sibling of this node
    */
   get prevSibling(): IPublicModelNode | null;
 
   /**
    * 获取当前节点的后一个兄弟节点
-   * @returns
+   * get next sibling of this node
    */
   get nextSibling(): IPublicModelNode | null;
 
   /**
    * 获取当前节点的父亲节点
-   * @returns
+   * get parent of this node
    */
   get parent(): IPublicModelNode | null;
 
   /**
    * 获取当前节点的孩子节点模型
-   * @returns
+   * get children of this node
    */
   get children(): IPublicModelNodeChildren | null;
 
   /**
    * 节点上挂载的插槽节点们
+   * get slots of this node
    */
   get slots(): IPublicModelNode[];
 
   /**
    * 当前节点为插槽节点时，返回节点对应的属性实例
+   * return coresponding prop when this node is a slot node
    */
   get slotFor(): IPublicModelProp | null;
 
   /**
    * 返回节点的属性集
+   * get props
    */
   get props(): IPublicModelProps | null;
 
   /**
    * 返回节点的属性集
+   * get props data
    */
   get propsData(): IPublicTypePropsMap | IPublicTypePropsList | null;
 
+  /**
+   * get conditionGroup
+   */
+  get conditionGroup(): IPublicModelExclusiveGroup | null;
+
   /**
    * 获取符合搭建协议 - 节点 schema 结构
+   * get schema of this node
+   * @since v1.1.0
    */
   get schema(): IPublicTypeNodeSchema;
 
+  /**
+   * 获取对应的 setting entry
+   * get setting entry of this node
+   * @since v1.1.0
+   */
   get settingEntry(): IPublicModelSettingTopEntry;
 
-  /**
-   * 执行新增、删除、排序等操作
-   * @param remover
-   * @param adder
-   * @param sorter
-   */
-  mergeChildren(
-    remover: (node: IPublicModelNode, idx: number) => boolean,
-    adder: (children: IPublicModelNode[]) => any,
-    sorter: (firstNode: IPublicModelNode, secondNode: IPublicModelNode) => number
-  ): any;
-
   /**
    * 返回节点的尺寸、位置信息
-   * @returns
+   * get rect information for this node
    */
   getRect(): DOMRect | null;
 
   /**
    * 是否有挂载插槽节点
-   * @returns
+   * check if current node has slots
    */
   hasSlots(): boolean;
 
   /**
    * 是否设定了渲染条件
-   * @returns
+   * check if current node has condition value set
    */
   hasCondition(): boolean;
 
   /**
    * 是否设定了循环数据
-   * @returns
+   * check if loop is set for this node
    */
   hasLoop(): boolean;
 
-  getVisible(): boolean;
-
-  setVisible(flag: boolean): void;
-
-  isConditionalVisible(): boolean | undefined;
-
-  /**
-   * 设置节点锁定状态
-   * @param flag
-   */
-  lock(flag?: boolean): void;
-
-  contains(node: IPublicModelNode): boolean;
-
   /**
    * 获取指定 path 的属性模型实例
+   * get prop by path
    * @param path 属性路径，支持 a / a.b / a.0 等格式
-   * @returns
    */
   getProp(path: string, createIfNone: boolean): IPublicModelProp | null;
 
+  /**
+   * 获取指定 path 的属性模型实例值
+   * get prop value by path
+   * @param path 属性路径，支持 a / a.b / a.0 等格式
+   */
+  getPropValue(path: string): any;
+
   /**
    * 获取指定 path 的属性模型实例，
    *  注：导出时，不同于普通属性，该属性并不挂载在 props 之下，而是与 props 同级
+   *
+   * get extra prop by path, an extra prop means a prop not exists in the `props`
+   * but as siblint of the `props`
    * @param path 属性路径，支持 a / a.b / a.0 等格式
    * @param createIfNone 当没有属性的时候，是否创建一个属性
-   * @returns
    */
   getExtraProp(path: string, createIfNone?: boolean): IPublicModelProp | null;
 
   /**
    * 获取指定 path 的属性模型实例，
    *  注：导出时，不同于普通属性，该属性并不挂载在 props 之下，而是与 props 同级
+   *
+   * get extra prop value by path, an extra prop means a prop not exists in the `props`
+   * but as siblint of the `props`
    * @param path 属性路径，支持 a / a.b / a.0 等格式
    * @returns
    */
@@ -275,52 +321,64 @@ export interface IPublicModelNode {
 
   /**
    * 设置指定 path 的属性模型实例值
+   * set value for prop with path
    * @param path 属性路径，支持 a / a.b / a.0 等格式
    * @param value 值
-   * @returns
    */
   setPropValue(path: string, value: IPublicTypeCompositeValue): void;
 
   /**
    * 设置指定 path 的属性模型实例值
+   * set value for extra prop with path
    * @param path 属性路径，支持 a / a.b / a.0 等格式
    * @param value 值
-   * @returns
    */
   setExtraPropValue(path: string, value: IPublicTypeCompositeValue): void;
 
   /**
    * 导入节点数据
+   * import node schema
    * @param data
    */
   importSchema(data: IPublicTypeNodeSchema): void;
 
   /**
    * 导出节点数据
+   * export schema from this node
    * @param stage
    * @param options
-   * @returns
    */
   exportSchema(stage: IPublicEnumTransformStage, options?: any): IPublicTypeNodeSchema;
 
   /**
    * 在指定位置之前插入一个节点
+   * insert a node befor current node
    * @param node
    * @param ref
    * @param useMutator
    */
-  insertBefore(node: IPublicModelNode, ref?: IPublicModelNode | undefined, useMutator?: boolean): void;
+  insertBefore(
+      node: IPublicModelNode,
+      ref?: IPublicModelNode | undefined,
+      useMutator?: boolean,
+    ): void;
 
   /**
    * 在指定位置之后插入一个节点
+   * insert a node after this node
    * @param node
    * @param ref
    * @param useMutator
    */
-  insertAfter(node: IPublicModelNode, ref?: IPublicModelNode | undefined, useMutator?: boolean): void;
+  insertAfter(
+      node: IPublicModelNode,
+      ref?: IPublicModelNode | undefined,
+      useMutator?: boolean,
+    ): void;
 
   /**
    * 替换指定节点
+   * replace a child node with data provided
    * @param node 待替换的子节点
    * @param data 用作替换的节点对象或者节点描述
    * @returns
@@ -329,58 +387,91 @@ export interface IPublicModelNode {
 
   /**
    * 将当前节点替换成指定节点描述
+   * replace current node with a new node schema
    * @param schema
    */
   replaceWith(schema: IPublicTypeNodeSchema): any;
 
   /**
    * 选中当前节点实例
+   * select current node
    */
   select(): void;
 
   /**
    * 设置悬停态
+   * set hover value for current node
    * @param flag
    */
   hover(flag: boolean): void;
 
+  /**
+   * 设置节点锁定状态
+   * set lock value for current node
+   * @param flag
+   * @since v1.0.16
+   */
+  lock(flag?: boolean): void;
+
   /**
    * 删除当前节点实例
+   * remove current node
    */
   remove(): void;
 
   /**
-   * @deprecated please use isRGLContainerNode
+   * 执行新增、删除、排序等操作
-   * 设置为磁贴布局节点
+   * excute remove/add/sort operations on node`s children
+   *
+   * @since v1.1.0
    */
-  set isRGLContainer(flag: boolean);
+  mergeChildren(
+    remover: (node: IPublicModelNode, idx: number) => boolean,
+    adder: (children: IPublicModelNode[]) => any,
+    sorter: (firstNode: IPublicModelNode, secondNode: IPublicModelNode) => number
+  ): any;
 
   /**
-   * @deprecated please use isRGLContainerNode
+   * 当前节点是否包含某子节点
-   * 获取磁贴布局节点设置状态
+   * check if current node contains another node as a child
-   * @returns Boolean
+   * @param node
+   * @since v1.1.0
    */
-  get isRGLContainer();
+  contains(node: IPublicModelNode): boolean;
-
-  /**
-   * 设置为磁贴布局节点
-   */
-  set isRGLContainerNode(flag: boolean);
-
-  /**
-   * 获取磁贴布局节点设置状态
-   * @returns Boolean
-   */
-  get isRGLContainerNode();
 
   /**
    * 是否可执行某 action
+   * check if current node can perform certain aciton with actionName
    * @param actionName action 名字
-   * @returns boolean
+   * @since v1.1.0
    */
   canPerformAction(actionName: string): boolean;
 
-  get conditionGroup(): IPublicModelExclusiveGroup | null;
+  /**
+   * 当前节点是否可见
+   * check if current node is visible
+   * @since v1.1.0
+   */
+  get visible(): boolean;
 
+  /**
+   * 设置当前节点是否可见
+   * set visible value for current node
+   * @since v1.1.0
+   */
+  set visible(value: boolean);
+
+  /**
+   * 获取该节点的 ConditionalVisible 值
+   * check if current node ConditionalVisible
+   * @since v1.1.0
+   */
+  isConditionalVisible(): boolean | undefined;
+
+  /**
+   * 设置该节点的 ConditionalVisible 为 true
+   * make this node as conditionalVisible === true
+   * @since v1.1.0
+   */
   setConditionalVisible(): void;
 }