docs: impove behavior comments and add api interactive demos (#5715)

* docs: add reference page title

* docs: refine behavior api interactive demos

Author: yvonneyx

packages/g6/src/behaviors/brush-select.ts

@@ -137,6 +137,11 @@ export class BrushSelect extends BaseBehavior<BrushSelectOptions> {
     this.bindEvents();
   }
 
+  /**
+   * Triggered when the pointer is pressed
+   * @param event - Pointer event
+   * @internal
+   */
   protected onPointerDown(event: IPointerEvent) {
     if (!this.validate(event) || !this.isKeydown() || this.startPoint) return;
     const { canvas } = this.context;
@@ -147,6 +152,11 @@ export class BrushSelect extends BaseBehavior<BrushSelectOptions> {
     this.startPoint = [event.canvas.x, event.canvas.y];
   }
 
+  /**
+   * Triggered when the pointer is moved
+   * @param event - Pointer event
+   * @internal
+   */
   protected onPointerMove(event: IPointerEvent) {
     if (!this.startPoint) return;
     const { immediately, mode } = this.options;
@@ -163,6 +173,11 @@ export class BrushSelect extends BaseBehavior<BrushSelectOptions> {
     if (immediately && mode === 'default') this.updateElementsStates(getBoundingPoints(this.startPoint, this.endPoint));
   }
 
+  /**
+   * Triggered when the pointer is released
+   * @param event - Pointer event
+   * @internal
+   */
   protected onPointerUp(event: IPointerEvent) {
     if (!this.startPoint) return;
     if (!this.endPoint) {

packages/g6/src/behaviors/click-element.ts

@@ -28,6 +28,14 @@ export interface ClickElementOptions extends BaseBehaviorOptions {
    *
    * <en/> Whether to enable the function of clicking the element
    * @defaultValue true
+   * @remarks
+   * <zh/> 可以通过函数的方式动态控制是否启用，例如只有节点被选中时才启用。
+   *
+   * <en/> Whether to enable can be dynamically controlled by functions, such as only when nodes are selected.
+   *
+   * ```json
+   * { enable: event => event.targetType === 'node'}
+   * ```
    */
   enable?: boolean | ((event: IPointerEvent) => boolean);
   /**
@@ -64,19 +72,13 @@ export interface ClickElementOptions extends BaseBehaviorOptions {
    * <en/> The degree to determine the scope of influence
    * @defaultValue 0
    * @remarks
-   * <zh/> 对于节点来说，
-   * - 0 表示只选中当前节点
-   * - 1 表示选中当前节点及其直接相邻的节点和边，以此类推
-   * 对于边来说，
-   * - 0 表示只选中当前边
-   * - 1 表示选中当前边及其直接相邻的节点，以此类推
+   * <zh/> 对于节点来说，`0` 表示只选中当前节点，`1` 表示选中当前节点及其直接相邻的节点和边，以此类推。
    *
-   * <en/> For nodes,
-   * - 0 means only the current node is selected
-   * - 1 means the current node and its directly adjacent nodes and edges are selected, etc
-   * For edges,
-   * - 0 means only the current edge is selected
-   * - 1 means the current edge and its directly adjacent nodes are selected, etc
+   * <zh/> 对于边来说，`0` 表示只选中当前边，`1` 表示选中当前边及其直接相邻的节点，以此类推。
+   *
+   * <en/> For nodes, `0` means only the current node is selected, `1` means the current node and its directly adjacent nodes and edges are selected, etc.
+   *
+   * <en/> For edges, `0 `means only the current edge is selected,`1` means the current edge and its directly adjacent nodes are selected, etc.
    */
   degree?: number;
 }
@@ -86,11 +88,9 @@ export interface ClickElementOptions extends BaseBehaviorOptions {
  *
  * <en/> Click Element
  * @remarks
- * ```typescript
- * const graph = new Graph({
- *  behaviors: ['click-element'],
- * });
- * ```
+ * <zh/> 当鼠标点击元素时，可以激活元素的状态，例如选中节点或边。当 degree 设置为 `1` 时，点击节点会高亮当前节点及其直接相邻的节点和边。
+ *
+ * <en/> When the mouse clicks on an element, you can activate the state of the element, such as selecting nodes or edges. When the degree is 1, clicking on a node will highlight the current node and its directly adjacent nodes and edges.
  */
 export class ClickElement extends BaseBehavior<ClickElementOptions> {
   private selectedElementIds: ID[] = [];

packages/g6/src/behaviors/collapse-expand.ts

@@ -6,14 +6,19 @@ import { isElement } from '../utils/element';
 import type { BaseBehaviorOptions } from './base-behavior';
 import { BaseBehavior } from './base-behavior';
 
+/**
+ * <zh/> 展开/收起组合元素交互配置项
+ *
+ * <en/> Collapse/Expand combo behavior options
+ */
 export interface CollapseExpandOptions extends BaseBehaviorOptions {
   /**
    * <zh/> 是否启用动画
    *
    * <en/> Whether to enable animation
    * @defaultValue true
    */
-  animation: boolean;
+  animation?: boolean;
   /**
    * <zh/> 是否启用展开/收起功能
    *
@@ -34,10 +39,15 @@ export interface CollapseExpandOptions extends BaseBehaviorOptions {
    */
   onExpand?: (id: ID) => void;
 }
+
 /**
- * <zh/> 展开/收起
+ * <zh/> 展开/收起组合元素交互
+ *
+ * <en/> Collapse/Expand Combo behavior
+ * @remarks
+ * <zh/> 通过双击 Combo 进行展开或收起 Combo。
  *
- * <en/> Collapse/Expand
+ * <en/> Expand or collapse a Combo by double-clicking on it.
  */
 export class CollapseExpand extends BaseBehavior<CollapseExpandOptions> {
   static defaultOptions: Partial<CollapseExpandOptions> = {

packages/g6/src/behaviors/create-edge.ts

@@ -3,25 +3,30 @@ import { CommonEvent } from '../constants';
 import type { RuntimeContext } from '../runtime/types';
 import type { EdgeData } from '../spec';
 import type { EdgeStyle } from '../spec/element/edge';
-import type { Element, ID, IPointerEvent } from '../types';
+import type { ID, IElementEvent, IPointerEvent } from '../types';
 import type { BaseBehaviorOptions } from './base-behavior';
 import { BaseBehavior } from './base-behavior';
 
 const ASSIST_EDGE_ID = 'g6-create-edge-assist-edge-id';
 const ASSIST_NODE_ID = 'g6-create-edge-assist-node-id';
 
+/**
+ * <zh/> 创建边交互配置项
+ *
+ * <en/> Create edge behavior options
+ */
 export interface CreateEdgeOptions extends BaseBehaviorOptions {
   /**
-   * <zh/> 是否启用悬浮元素的功能
+   * <zh/> 是否启用创建边的功能
    *
-   * <en/> Whether to enable hover element function
+   * <en/> Whether to enable the function of creating edges
    * @defaultValue true
    */
   enable?: boolean | ((event: IPointerEvent) => boolean);
   /**
-   * <zh/> 边配置
+   * <zh/> 新建边的样式配置
    *
-   * <en/> edge config
+   * <en/> Style configs of the new edge
    */
   style?: EdgeStyle;
   /**
@@ -45,6 +50,15 @@ export interface CreateEdgeOptions extends BaseBehaviorOptions {
   onCreate?: (edge: EdgeData) => EdgeData;
 }
 
+/**
+ * <zh/> 创建边交互
+ *
+ * <en/> Create edge behavior
+ * @remarks
+ * <zh/> 通过拖拽或点击节点创建边，支持自定义边样式。
+ *
+ * <en/> Create edges by dragging or clicking nodes, and support custom edge styles.
+ */
 export class CreateEdge extends BaseBehavior<CreateEdgeOptions> {
   static defaultOptions: Partial<CreateEdgeOptions> = {
     animation: true,
@@ -62,6 +76,11 @@ export class CreateEdge extends BaseBehavior<CreateEdgeOptions> {
     this.bindEvents();
   }
 
+  /**
+   * Update options
+   * @param options - The options to update
+   * @internal
+   */
   public update(options: Partial<CreateEdgeOptions>): void {
     super.update(options);
     this.bindEvents();
@@ -203,5 +222,3 @@ export class CreateEdge extends BaseBehavior<CreateEdgeOptions> {
     super.destroy();
   }
 }
-
-type IElementEvent = IPointerEvent<Element>;

packages/g6/src/behaviors/drag-canvas.ts

@@ -33,7 +33,12 @@ export interface DragCanvasOptions extends BaseBehaviorOptions {
    *
    * <en/> The way to trigger dragging, default to dragging with the pointer pressed
    */
-  trigger?: CombinationKey;
+  trigger?: {
+    up: ShortcutKey;
+    down: ShortcutKey;
+    left: ShortcutKey;
+    right: ShortcutKey;
+  };
   /**
    * <zh/> 触发一次按键移动的距离
    *
@@ -49,13 +54,11 @@ export interface DragCanvasOptions extends BaseBehaviorOptions {
   onFinish?: () => void;
 }
 
-type CombinationKey = {
-  up: ShortcutKey;
-  down: ShortcutKey;
-  left: ShortcutKey;
-  right: ShortcutKey;
-};
-
+/**
+ * <zh/> 拖拽画布交互
+ *
+ * <en/> Drag canvas behavior
+ */
 export class DragCanvas extends BaseBehavior<DragCanvasOptions> {
   static defaultOptions: Partial<DragCanvasOptions> = {
     enable: true,
@@ -76,6 +79,18 @@ export class DragCanvas extends BaseBehavior<DragCanvasOptions> {
     context.canvas.setCursor('grab');
   }
 
+  /**
+   * <zh/> 更新配置
+   *
+   * <en/> Update options
+   * @param options - <zh/> 配置项 | <en/> Options
+   * @internal
+   */
+  public update(options: Partial<DragCanvasOptions>): void {
+    super.update(options);
+    this.bindEvents();
+  }
+
   private bindEvents() {
     const { trigger } = this.options;
     this.shortcut.unbindAll();
@@ -110,6 +125,14 @@ export class DragCanvas extends BaseBehavior<DragCanvasOptions> {
     this.options.onFinish?.();
   }
 
+  /**
+   * <zh/> 平移画布
+   *
+   * <en/> Translate canvas
+   * @param offset - <zh/> 平移距离 | <en/> Translation distance
+   * @param animation - <zh/> 动画配置 | <en/> Animation configuration
+   * @internal
+   */
   protected async translate(offset: Vector2, animation?: ViewportAnimationEffectTiming) {
     await this.context.graph.translateBy(offset, animation);
   }

packages/g6/src/behaviors/drag-element-force.ts

@@ -1,18 +1,38 @@
-import type { Element, ID, IDragEvent, Point } from '../types';
+import type { ID, IElementDragEvent, Point } from '../types';
 import { idOf } from '../utils/id';
 import { getLayoutProperty, invokeLayoutMethod } from '../utils/layout';
 import { add } from '../utils/vector';
 import type { DragElementOptions } from './drag-element';
 import { DragElement } from './drag-element';
 
+/**
+ * <zh/> 调用力导布局拖拽元素交互配置项
+ *
+ * <en/> Call d3-force layout to drag element behavior options
+ */
 export interface DragElementForceOptions extends Omit<DragElementOptions, 'animation' | 'dropEffect' | 'shadow'> {}
 
+/**
+ * <zh/> 调用力导布局拖拽元素的交互
+ *
+ * <en/> Call d3-force layout to drag element behavior
+ * @remarks
+ * <zh/> 只能在使用 d3-force 布局时使用该交互，在拖拽过程中会实时重新计算布局。
+ *
+ * <en/> This behavior can only be used with d3-force layout. The layout will be recalculated in real time during dragging.
+ */
 export class DragElementForce extends DragElement {
   private get forceLayoutInstance() {
     return this.context.layout!.getLayoutInstance().find((layout) => ['d3-force', 'd3-force-3d'].includes(layout?.id));
   }
 
-  protected validate(event: IDragEvent<Element>): boolean {
+  /**
+   * Whether the behavior is enabled
+   * @param event - The event object
+   * @returns Is the behavior enabled
+   * @internal
+   */
+  protected validate(event: IElementDragEvent): boolean {
     if (!this.context.layout) return false;
 
     // 未使用力导布局 / The force layout is not used
@@ -24,6 +44,12 @@ export class DragElementForce extends DragElement {
     return super.validate(event);
   }
 
+  /**
+   * Move selected elements by offset
+   * @param ids - The selected element IDs
+   * @param offset - The offset to move
+   * @internal
+   */
   protected async moveElement(ids: ID[], offset: Point) {
     const layout = this.forceLayoutInstance;
     this.context.graph.getNodeData(ids).forEach((element, index) => {
@@ -32,7 +58,12 @@ export class DragElementForce extends DragElement {
     });
   }
 
-  protected onDragStart(event: IDragEvent<Element>) {
+  /**
+   * Triggered when the drag starts
+   * @param event - The event object
+   * @internal
+   */
+  protected onDragStart(event: IElementDragEvent) {
     this.enable = this.validate(event);
     if (!this.enable) return;
 
@@ -49,13 +80,22 @@ export class DragElementForce extends DragElement {
     });
   }
 
-  protected onDrag(event: IDragEvent<Element>) {
+  /**
+   * Triggered when dragging
+   * @param event - The event object
+   * @internal
+   */
+  protected onDrag(event: IElementDragEvent) {
     if (!this.enable) return;
 
     const delta = this.getDelta(event);
     this.moveElement(this.target, delta);
   }
 
+  /**
+   * Triggered when the drag ends
+   * @internal
+   */
   protected onDragEnd() {
     const layout = this.forceLayoutInstance;
     if (layout) getLayoutProperty(layout, 'simulation').alphaTarget(0);