docs(detecting): optimize api doc for model/detecting, and fix related lint issues

JackLian · liujuping · commit f6771fefac2a · 2023-01-10T15:16:27.000+08:00
diff --git a/docs/docs/api/model/detecting.md b/docs/docs/api/model/detecting.md
@@ -9,29 +9,63 @@ sidebar_position: 6
 
 画布节点悬停模型
 
+## 变量
+
+### current
+
+当前 hover 的节点
+
+`@type {IPublicModelNode | null}`
+
+相关类型：[IPublicModelNode](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/model/node.ts)
+
+**@since v1.0.16**
+
+### enable
+
+是否启用
+
+`@type {boolean}`
+
+
 ## 方法签名
 ### capture
 
-capture(id: string)
-
 hover 指定节点
 
-### release
+```typescript
+/**
+ * hover 指定节点
+ * capture node with nodeId
+ * @param id 节点 id
+ */
+capture(id: string): void;
+```
 
-release(id: string)
+### release
 
 hover 离开指定节点
 
-### leave
+```typescript
+/**
+ * hover 离开指定节点
+ * release node with nodeId
+ * @param id 节点 id
+ */
+release(id: string): void;
+```
 
-leave()
+### leave
 
 清空 hover 态
 
-### current
-当前 hover 的节点
-
-**@since v1.0.16**
+```typescript
+/**
+ * 清空 hover 态
+ * clear all hover state
+ */
+leave(): void;
+```
 
 ### onDetectingChange
 hover 节点变化事件
@@ -42,6 +76,11 @@ hover 节点变化事件
  * set callback which will be called when hovering object changed.
  * @since v1.1.0
  */
-onDetectingChange(fn: (node: IPublicModelNode) => void): () => void;
+onDetectingChange(fn: (node: IPublicModelNode) => void): IPublicTypeDisposable;
 ```
+
+相关类型：
+- [IPublicModelNode](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/model/node.ts)
+- [IPublicModelNode](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/type/disposable.ts)
+
 **@since v1.1.0**
diff --git a/packages/designer/src/designer/detecting.ts b/packages/designer/src/designer/detecting.ts
@@ -2,8 +2,13 @@ import { makeObservable, obx, IEventBus, createModuleEventBus } from '@alilc/low
 import { IPublicModelDetecting, IPublicModelNode, IPublicModelDocumentModel } from '@alilc/lowcode-types';
 
 const DETECTING_CHANGE_EVENT = 'detectingChange';
-export interface IDetecting extends IPublicModelDetecting {
+export interface IDetecting extends Omit< IPublicModelDetecting, 'capture' | 'release' | 'leave' > {
 
+  capture(node: IPublicModelNode | null): void;
+
+  release(node: IPublicModelNode | null): void;
+
+  leave(document: IPublicModelDocumentModel | undefined): void;
 }
 
 export class Detecting implements IDetecting {
diff --git a/packages/designer/src/document/document-model.ts b/packages/designer/src/document/document-model.ts
@@ -39,6 +39,10 @@ export interface IDocumentModel extends IPublicModelDocumentModel {
 
   readonly designer: Designer;
 
+  /**
+   * 根据 id 获取节点
+   */
+  getNode(id: string): INode | null;
 }
 
 export class DocumentModel implements IDocumentModel {
@@ -118,16 +122,85 @@ export class DocumentModel implements IDocumentModel {
 
   @obx.ref private _drillDownNode: Node | null = null;
 
-  drillDown(node: Node | null) {
-    this._drillDownNode = node;
-  }
-
   private _modalNode?: INode;
 
   private _blank?: boolean;
 
   private inited = false;
 
+  @obx.shallow private willPurgeSpace: Node[] = [];
+
+  get modalNode() {
+    return this._modalNode;
+  }
+
+  get currentRoot() {
+    return this.modalNode || this.focusNode;
+  }
+
+  @obx.shallow private activeNodes?: Node[];
+
+  @obx.ref private _dropLocation: IDropLocation | null = null;
+
+  set dropLocation(loc: IPublicModelDropLocation | null) {
+    this._dropLocation = loc;
+    // pub event
+    this.designer.editor.eventBus.emit(
+      'document.dropLocation.changed',
+      { document: this, location: loc },
+    );
+  }
+
+  /**
+   * 投放插入位置标记
+   */
+  get dropLocation() {
+    return this._dropLocation;
+  }
+
+  /**
+   * 导出 schema 数据
+   */
+  get schema(): IPublicTypeRootSchema {
+    return this.rootNode?.schema as any;
+  }
+
+  @obx.ref private _opened = false;
+
+  @obx.ref private _suspensed = false;
+
+  /**
+   * 是否为非激活状态
+   */
+  get suspensed(): boolean {
+    return this._suspensed || !this._opened;
+  }
+
+  /**
+   * 与 suspensed 相反，是否为激活状态，这个函数可能用的更多一点
+   */
+  get active(): boolean {
+    return !this._suspensed;
+  }
+
+  /**
+   * @deprecated 兼容
+   */
+  get actived(): boolean {
+    return this.active;
+  }
+
+  /**
+   * 是否打开
+   */
+  get opened() {
+    return this._opened;
+  }
+
+  get root() {
+    return this.rootNode;
+  }
+
   constructor(project: Project, schema?: IPublicTypeRootSchema) {
     makeObservable(this);
     this.project = project;
@@ -162,6 +235,10 @@ export class DocumentModel implements IDocumentModel {
     this.inited = true;
   }
 
+  drillDown(node: Node | null) {
+    this._drillDownNode = node;
+  }
+
   onChangeNodeVisible(fn: (node: IPublicModelNode, visible: boolean) => void): () => void {
     this.designer.editor?.eventBus.on(EDITOR_EVENT.NODE_CHILDREN_CHANGE, fn);
 
@@ -178,16 +255,6 @@ export class DocumentModel implements IDocumentModel {
     };
   }
 
-  @obx.shallow private willPurgeSpace: Node[] = [];
-
-  get modalNode() {
-    return this._modalNode;
-  }
-
-  get currentRoot() {
-    return this.modalNode || this.focusNode;
-  }
-
   addWillPurge(node: Node) {
     this.willPurgeSpace.push(node);
   }
@@ -204,7 +271,7 @@ export class DocumentModel implements IDocumentModel {
   }
 
   /**
-   * 生成唯一id
+   * 生成唯一 id
    */
   nextId(possibleId: string | undefined) {
     let id = possibleId;
@@ -218,7 +285,7 @@ export class DocumentModel implements IDocumentModel {
   /**
    * 根据 id 获取节点
    */
-  getNode(id: string): Node | null {
+  getNode(id: string): INode | null {
     return this._nodesMap.get(id) || null;
   }
 
@@ -237,8 +304,6 @@ export class DocumentModel implements IDocumentModel {
     return node ? !node.isPurged : false;
   }
 
-  @obx.shallow private activeNodes?: Node[];
-
   /**
    * 根据 schema 创建一个节点
    */
@@ -338,24 +403,6 @@ export class DocumentModel implements IDocumentModel {
     this._nodesMap.delete(node.id);
   }
 
-  @obx.ref private _dropLocation: IDropLocation | null = null;
-
-  set dropLocation(loc: IPublicModelDropLocation | null) {
-    this._dropLocation = loc;
-    // pub event
-    this.designer.editor.eventBus.emit(
-      'document.dropLocation.changed',
-      { document: this, location: loc },
-    );
-  }
-
-  /**
-   * 投放插入位置标记
-   */
-  get dropLocation() {
-    return this._dropLocation;
-  }
-
   /**
    * 包裹当前选区中的节点
    */
@@ -378,13 +425,6 @@ export class DocumentModel implements IDocumentModel {
     return null;
   }
 
-  /**
-   * 导出 schema 数据
-   */
-  get schema(): IPublicTypeRootSchema {
-    return this.rootNode?.schema as any;
-  }
-
   @action
   import(schema: IPublicTypeRootSchema, checkId = false) {
     const drillDownNodeId = this._drillDownNode?.id;
@@ -449,37 +489,6 @@ export class DocumentModel implements IDocumentModel {
     );
   }
 
-  @obx.ref private _opened = false;
-
-  @obx.ref private _suspensed = false;
-
-  /**
-   * 是否为非激活状态
-   */
-  get suspensed(): boolean {
-    return this._suspensed || !this._opened;
-  }
-
-  /**
-   * 与 suspensed 相反，是否为激活状态，这个函数可能用的更多一点
-   */
-  get active(): boolean {
-    return !this._suspensed;
-  }
-
-  /**
-   * @deprecated 兼容
-   */
-  get actived(): boolean {
-    return this.active;
-  }
-
-  /**
-   * 是否打开
-   */
-  get opened() {
-    return this._opened;
-  }
 
   /**
    * 切换激活，只有打开的才能激活
@@ -617,10 +626,6 @@ export class DocumentModel implements IDocumentModel {
     return this.history;
   }
 
-  get root() {
-    return this.rootNode;
-  }
-
   /**
    * @deprecated
    */
diff --git a/packages/shell/src/model/detecting.ts b/packages/shell/src/model/detecting.ts
@@ -1,10 +1,10 @@
-import { Node } from './node';
+import { Node as ShellNode } from './node';
 import {
   Detecting as InnerDetecting,
-  DocumentModel as InnerDocumentModel,
+  IDocumentModel as InnerDocumentModel,
 } from '@alilc/lowcode-designer';
 import { documentSymbol, detectingSymbol } from '../symbols';
-import { IPublicModelDetecting, IPublicModelNode } from '@alilc/lowcode-types';
+import { IPublicModelDetecting, IPublicModelNode, IPublicTypeDisposable } from '@alilc/lowcode-types';
 
 export class Detecting implements IPublicModelDetecting {
   private readonly [documentSymbol]: InnerDocumentModel;
@@ -26,7 +26,7 @@ export class Detecting implements IPublicModelDetecting {
    * 当前 hover 的节点
    */
   get current() {
-    return Node.create(this[detectingSymbol].current);
+    return ShellNode.create(this[detectingSymbol].current);
   }
 
   /**
@@ -52,7 +52,7 @@ export class Detecting implements IPublicModelDetecting {
     this[detectingSymbol].leave(this[documentSymbol]);
   }
 
-  onDetectingChange(fn: (node: IPublicModelNode) => void): () => void {
+  onDetectingChange(fn: (node: IPublicModelNode) => void): IPublicTypeDisposable {
     return this[detectingSymbol].onDetectingChange(fn);
   }
 }
diff --git a/packages/types/src/shell/model/detecting.ts b/packages/types/src/shell/model/detecting.ts
