@next-bricks/diagram 0.68.8 → 0.68.10

package/dist-types/diagram/index.d.ts

@@ -39,27 +39,74 @@ export interface EoDiagramEventsMapping {
     onNodesConnect: "nodes.connect";
 }
 /**
- * 构件 `eo-diagram`
+ * @description 图表构件，支持 dagre（有向无环图）和 force（力导向图）两种布局，可渲染节点和连线，支持缩放、平移、拖拽节点、连线交互等功能。
+ * @category diagram
  */
 export declare class EoDiagram extends ReactNextElement implements EoDiagramProps {
     #private;
     /**
+     * @description 图表布局类型，支持 `dagre`（层次有向图）和 `force`（力导向图）。
      * @required
      */
     accessor layout: "dagre" | "force" | undefined;
+    /**
+     * @description 节点数据列表，每个节点需包含唯一 `id` 字段。
+     */
     accessor nodes: DiagramNode[] | undefined;
+    /**
+     * @description 边（连线）数据列表，每条边需包含 `source` 和 `target` 字段，指向节点 id。
+     */
     accessor edges: DiagramEdge[] | undefined;
+    /**
+     * @description 节点砖块配置，指定渲染节点使用的自定义构件，可按节点类型匹配不同配置。
+     */
     accessor nodeBricks: NodeBrickConf[] | undefined;
+    /**
+     * @description 连线样式配置，支持箭头、颜色、标签、交互等多种选项。
+     */
     accessor lines: LineConf[] | undefined;
+    /**
+     * @description 布局算法选项，dagre 布局支持 rankdir、ranksep、nodesep 等，force 布局支持 dummyNodesOnEdges、collide 等。
+     */
     accessor layoutOptions: LayoutOptions | undefined;
+    /**
+     * @description 当前激活目标，可以是节点（`{ type: "node", nodeId }`) 或边（`{ type: "edge", edge }`），为 null 表示无激活目标。
+     */
     accessor activeTarget: ActiveTarget | null | undefined;
+    /**
+     * @description 是否禁用键盘操作（删除节点/边、切换激活节点），当有标签正在编辑时可临时禁用以避免冲突。
+     */
     accessor disableKeyboardAction: boolean | undefined;
+    /**
+     * @description 连线交互配置，启用后支持从节点拖拽出新的连线，可配置连线样式和源节点过滤条件。
+     */
     accessor connectNodes: ConnectNodesOptions | undefined;
+    /**
+     * @description 拖拽节点配置，启用后支持手动拖拽节点调整位置，可配置是否保存用户视图。
+     */
     accessor dragNodes: DragNodesOptions | undefined;
+    /**
+     * @description 是否允许通过鼠标滚轮或触控板捏合手势缩放图表，默认为 true。
+     */
     accessor zoomable: boolean | undefined;
+    /**
+     * @description 是否允许通过滚轮平移图表（非捏合手势），默认为 true。
+     */
     accessor scrollable: boolean | undefined;
+    /**
+     * @description 是否允许通过鼠标拖拽平移图表，默认为 true。
+     */
     accessor pannable: boolean | undefined;
+    /**
+     * @description 缩放比例范围，格式为 `[min, max]`，默认范围由内部常量决定。
+     */
     accessor scaleRange: RangeTuple | undefined;
+    /**
+     * @description 调用指定 id 的连线标签构件上的方法，常用于触发标签编辑（如 `callOnLineLabel(id, "enableEditing")`）。
+     * @param id 连线标签的 id（格式通常为 `${lineId}-${placement}`）
+     * @param method 要调用的方法名
+     * @param args 传递给方法的参数列表
+     */
     callOnLineLabel(id: string, method: string, ...args: unknown[]): void;
     render(): React.JSX.Element;
 }

package/dist-types/diagram/interfaces.d.ts

@@ -1,5 +1,5 @@
 import type { CSSProperties } from "react";
-import type { UseSingleBrickConf } from "@next-core/react-runtime";
+import type { UseSingleBrickConfOrRenderFunction } from "@next-core/react-runtime";
 export interface DiagramNode {
     id: DiagramNodeId;
     type?: string;
@@ -96,7 +96,7 @@ export interface LineMarker {
 export type DiagramNodeId = string;
 export type RefRepository = Map<DiagramNodeId, HTMLElement>;
 export interface NodeBrickConf {
-    useBrick: UseSingleBrickConf;
+    useBrick: UseSingleBrickConfOrRenderFunction;
     nodeType?: string | string[];
     if?: string | boolean | null;
 }
@@ -134,7 +134,7 @@ export interface LineConfOverridable {
 }
 export interface LineLabelConf extends LabelOrTextBaseOptions {
     if?: string | boolean | null;
-    useBrick: UseSingleBrickConf;
+    useBrick: UseSingleBrickConfOrRenderFunction;
 }
 export interface TextOptions extends LabelOrTextBaseOptions {
     content: string;

package/dist-types/display-canvas/index.d.ts

@@ -36,18 +36,34 @@ export interface EoDisplayCanvasEventsMapping {
     onCellClick: "cell.click";
 }
 /**
- * 用于展示查看的画布。
+ * @description 用于展示查看的画布构件，支持 manual、force、dagre 多种布局，可展示节点、边和装饰器，支持缩放、平移、激活目标高亮、淡化无关元素等功能。
+ * @category diagram
  */
 export declare class EoDisplayCanvas extends ReactNextElement implements EoDisplayCanvasProps {
     #private;
     /**
-     * 用于查看的画布可以更新 `cells` 属性。
+     * @description 画布中的单元格数据，包含节点（node）、边（edge）和装饰器（decorator）。
      */
     accessor cells: InitialCell[] | undefined;
+    /**
+     * @description 画布布局类型，支持 `manual`（手动定位）、`force`（力导向）、`dagre`（层次有向图）。
+     */
     accessor layout: LayoutType;
+    /**
+     * @description 布局算法选项，根据 layout 类型不同，支持不同参数（如 dagre 的 ranksep/nodesep，force 的碰撞参数等）。
+     */
     accessor layoutOptions: LayoutOptions | undefined;
+    /**
+     * @description 是否自动计算节点尺寸，启用后画布会根据节点内容自动调整节点大小。
+     */
     accessor autoSize: AutoSize | undefined;
+    /**
+     * @description 节点默认尺寸，格式为 `[width, height]`，在节点未指定尺寸时使用。
+     */
     accessor defaultNodeSize: SizeTuple;
+    /**
+     * @description 节点默认砖块配置，指定渲染节点的自定义构件，可按节点类型匹配不同配置。
+     */
     accessor defaultNodeBricks: NodeBrickConf[] | undefined;
     /**
      * 当节点数量达到或超过 `degradedThreshold` 时，节点将被降级展示。
@@ -71,14 +87,29 @@ export declare class EoDisplayCanvas extends ReactNextElement implements EoDispl
      * ```
      */
     accessor defaultEdgeLines: EdgeLineConf[] | undefined;
+    /**
+     * @description 当前激活目标，可以是节点（`{ type: "node", id }`）或边（`{ type: "edge", id }`）等，为 null 表示无激活目标。
+     */
     accessor activeTarget: ActiveTarget | null | undefined;
     /**
-     * 当鼠标悬浮到某节点上时，隐藏其他跟该节点无关的元素。
+     * @description 当鼠标悬浮到某节点上时，隐藏其他跟该节点无关的元素，高亮相关节点和边。
      */
     accessor fadeUnrelatedCells: boolean | undefined;
+    /**
+     * @description 是否允许通过鼠标滚轮或触控板捏合手势缩放画布，默认为 true。
+     */
     accessor zoomable: boolean | undefined;
+    /**
+     * @description 是否允许通过滚轮平移画布（非捏合手势），默认为 true。
+     */
     accessor scrollable: boolean | undefined;
+    /**
+     * @description 是否允许通过鼠标拖拽平移画布，默认为 true。
+     */
     accessor pannable: boolean | undefined;
+    /**
+     * @description 缩放比例范围，格式为 `[min, max]`，默认范围由内部常量决定。
+     */
     accessor scaleRange: RangeTuple | undefined;
     /**
      * 隐藏右下角放大缩小的控制栏
@@ -97,6 +128,9 @@ export declare class EoDisplayCanvas extends ReactNextElement implements EoDispl
      */
     accessor doNotResetActiveTargetOutsideCanvas: boolean | undefined;
     accessor extraStyleTexts: string[] | undefined;
+    /**
+     * @description 将画布视图重置并居中，使所有单元格重新显示在视口中央。
+     */
     center(): void;
     render(): React.JSX.Element;
 }

package/dist-types/draw-canvas/index.d.ts

@@ -1,6 +1,6 @@
 import React from "react";
 import { ReactNextElement } from "@next-core/react-element";
-import type { UseSingleBrickConf } from "@next-core/react-runtime";
+import type { UseSingleBrickConfOrRenderFunction } from "@next-core/react-runtime";
 import "@next-core/theme";
 import type { NodePosition, PositionTuple, RangeTuple, SizeTuple, TransformLiteral } from "../diagram/interfaces";
 import type { ActiveTarget, Cell, EdgeCell, InitialCell, NodeBrickConf, NodeCell, NodeId, DecoratorCell, DecoratorType, CellContextMenuDetail, ConnectNodesDetail, EdgeLineConf, DecoratorTextChangeDetail, LayoutType, LayoutOptions, LineConnecterConf, Direction, LineSettings, DecoratorView, DecoratorLineView } from "./interfaces";
@@ -55,7 +55,7 @@ export interface DropDecoratorInfo {
 }
 export interface AddNodeInfo {
     id: NodeId;
-    useBrick?: UseSingleBrickConf;
+    useBrick?: UseSingleBrickConfOrRenderFunction;
     data?: unknown;
     size?: SizeTuple;
     containerId?: NodeId;
@@ -132,22 +132,32 @@ export interface EoDrawCanvasEventsMapping {
     onCanvasUngroup: "canvas.ungroup";
 }
 /**
- * 用于手工绘图的画布。
- *
- * 注意：将配套另外一个用于展示的画布构件。
+ * @description 用于手工绘图的画布构件，支持节点拖放、连线绘制、元素移动/缩放/删除等交互操作，配合展示画布（eo-display-canvas）使用。
+ * @category diagram
  */
 export declare class EoDrawCanvas extends ReactNextElement implements EoDrawCanvasProps {
     #private;
     /**
-     * 仅当初始化时使用，渲染后重新设置 `cells` 将无效。
+     * @description 初始化画布单元格数据，包含节点（node）、边（edge）和装饰器（decorator）。仅当初始化时使用，渲染后重新设置 `cells` 将无效，请使用 `updateCells` 方法代替。
      */
     accessor cells: InitialCell[] | undefined;
+    /**
+     * @description 画布布局类型，支持 `manual`（手动定位）、`force`（力导向）、`dagre`（层次有向图）。
+     */
     accessor layout: LayoutType;
+    /**
+     * @description 布局算法选项，根据 layout 类型不同，支持不同参数（如 dagre 的 ranksep/nodesep 等）。
+     */
     accessor layoutOptions: LayoutOptions | undefined;
     /**
+     * @description 节点默认尺寸，格式为 `[width, height]`，在节点未指定尺寸时使用。
+     *
      * @default [100,20]
      */
     accessor defaultNodeSize: SizeTuple;
+    /**
+     * @description 节点默认砖块配置，指定渲染节点的自定义构件，可按节点类型匹配不同配置。
+     */
     accessor defaultNodeBricks: NodeBrickConf[] | undefined;
     /**
      * 当节点数量达到或超过 `degradedThreshold` 时，节点将被降级展示。
@@ -171,14 +181,29 @@ export declare class EoDrawCanvas extends ReactNextElement implements EoDrawCanv
      * ```
      */
     accessor defaultEdgeLines: EdgeLineConf[] | undefined;
+    /**
+     * @description 当前激活目标，可以是节点、边或装饰器，为 null 表示无激活目标。
+     */
     accessor activeTarget: ActiveTarget | null | undefined;
     /**
-     * 当 `activeTarget` 不为 `null` 时，隐藏其他跟该 `activeTarget` 无关的元素。
+     * @description 当 `activeTarget` 不为 `null` 时，隐藏其他跟该 `activeTarget` 无关的元素，高亮相关节点和边。
      */
     accessor fadeUnrelatedCells: boolean | undefined;
+    /**
+     * @description 是否允许通过鼠标滚轮或触控板捏合手势缩放画布，默认为 true。
+     */
     accessor zoomable: boolean | undefined;
+    /**
+     * @description 是否允许通过滚轮平移画布（非捏合手势），默认为 true。
+     */
     accessor scrollable: boolean | undefined;
+    /**
+     * @description 是否允许通过鼠标拖拽平移画布，默认为 true。
+     */
     accessor pannable: boolean | undefined;
+    /**
+     * @description 是否允许将边连接到区域（area）装饰器，默认为 false。
+     */
     accessor allowEdgeToArea: boolean | undefined;
     /**
      * 按住鼠标拖动时的行为：
@@ -197,8 +222,17 @@ export declare class EoDrawCanvas extends ReactNextElement implements EoDrawCanv
      * @default "none"
      */
     accessor ctrlDragBehavior: CtrlDragBehavior | undefined;
+    /**
+     * @description 缩放比例范围，格式为 `[min, max]`，默认范围由内部常量决定。
+     */
     accessor scaleRange: RangeTuple | undefined;
+    /**
+     * @description 连线设置，包含连线类型、箭头等属性，用于新建连线时的默认样式。
+     */
     accessor lineSettings: LineSettings | undefined;
+    /**
+     * @description 连线连接器配置，设置为 `true` 或配置对象以启用智能连线功能，允许从节点边缘拖出连线。
+     */
     accessor lineConnector: LineConnecterConf | boolean | undefined;
     /**
      * 选择器，点击该选择器对应的元素时不重置 `activeTarget`。
@@ -208,14 +242,48 @@ export declare class EoDrawCanvas extends ReactNextElement implements EoDrawCanv
      * 在画布外点击时不重置 `activeTarget`。
      */
     accessor doNotResetActiveTargetOutsideCanvas: boolean | undefined;
+    /**
+     * @description 将一个节点拖放到画布中指定位置。如果放置位置不在画布内，则返回 null。
+     * @param info 拖放节点信息，包含节点 id、拖放位置（clientX/clientY）、尺寸和数据
+     * @returns 成功时返回创建的 NodeCell，否则返回 null
+     */
     dropNode({ id, position, size, data, useBrick, }: DropNodeInfo): Promise<NodeCell | null>;
+    /**
+     * @description 将一个装饰器（area、container、text、line 等）拖放到画布中指定位置。如果放置位置不在画布内，则返回 null。
+     * @param info 拖放装饰器信息，包含装饰器类型、拖放位置、文本和方向等
+     * @returns 成功时返回创建的 DecoratorCell，否则返回 null
+     */
     dropDecorator({ position, decorator, text, direction, source, target, view, }: DropDecoratorInfo): Promise<DecoratorCell | null>;
+    /**
+     * @description 批量添加节点到画布，节点位置由布局算法自动计算。
+     * @param nodes 要添加的节点信息列表，每项包含 id、数据、尺寸等
+     * @returns 创建的 NodeCell 列表
+     */
     addNodes(nodes: AddNodeInfo[]): Promise<NodeCell[]>;
+    /**
+     * @description 以编程方式添加一条边（连线）到画布。注意：此方法不会触发 `edge.add` 事件。
+     * @param info 边信息，包含 source（起始节点 id）、target（目标节点 id）和可选的 data
+     * @returns 创建的 EdgeCell 对象
+     */
     addEdge({ source, target, data }: AddEdgeInfo): Promise<EdgeCell>;
+    /**
+     * @description 以编程方式启动从指定源节点到目标节点的手动连线流程，等待用户在画布上点击目标节点后返回连线详情。
+     * @param source 起始节点的 id
+     * @returns Promise，解析为 ConnectNodesDetail 包含 source 和 target 节点信息
+     */
     manuallyConnectNodes(source: NodeId): Promise<ConnectNodesDetail>;
+    /**
+     * @description 更新画布中的单元格数据，支持增量更新（新增、修改），已渲染的画布使用此方法代替直接设置 `cells` 属性。
+     * @param cells 新的单元格数据列表
+     * @param ctx 可选的更新上下文，用于指定更新原因和位置参考节点
+     * @returns 返回实际被更新的单元格列表
+     */
     updateCells(cells: InitialCell[], ctx?: UpdateCellsContext): Promise<{
         updated: Cell[];
     }>;
+    /**
+     * @description 将画布视图重置并居中，使所有单元格重新显示在视口中央。
+     */
     reCenter(): Promise<void>;
     /**
      * 切换锁定状态。

package/dist-types/draw-canvas/interfaces.d.ts

@@ -1,4 +1,4 @@
-import type { UseSingleBrickConf } from "@next-core/react-runtime";
+import type { UseSingleBrickConfOrRenderFunction } from "@next-core/react-runtime";
 import type { SimulationLinkDatum, SimulationNodeDatum } from "d3-force";
 import type { CSSProperties, FunctionComponent } from "react";
 import type { ResizeCellPayload } from "./reducers/interfaces";
@@ -21,7 +21,7 @@ export type NodeComponent = FunctionComponent<{
 }>;
 export type NodeId = string;
 export interface BaseBrickCell extends BaseCell {
-    useBrick?: UseSingleBrickConf;
+    useBrick?: UseSingleBrickConfOrRenderFunction;
 }
 export interface BaseNodeCell extends BaseCell {
     type: "node";
@@ -96,7 +96,7 @@ export type InitialNodeCell = Omit<NodeCell, "view"> & {
 };
 export type InitialCell = InitialNodeCell | EdgeCell | DecoratorCell;
 export interface NodeBrickConf {
-    useBrick?: UseSingleBrickConf;
+    useBrick?: UseSingleBrickConfOrRenderFunction;
     component?: NodeComponent;
     if?: string | boolean | null;
 }

package/dist-types/editable-label/index.d.ts

@@ -20,13 +20,26 @@ export interface EditableLabelEventsMapping {
     onLabelChange: "label.change";
 }
 /**
- * 构件 `diagram.editable-label`
+ * @description 可编辑标签构件，用于在图表连线或节点上展示可双击编辑的文本标签，支持只读模式，常配合 `eo-draw-canvas` 和 `eo-diagram` 使用。
+ * @category diagram
  */
 export declare class EditableLabel extends ReactNextElement implements EditableLabelProps {
     #private;
+    /**
+     * @description 标签文本内容。
+     */
     accessor label: string | undefined;
+    /**
+     * @description 标签类型，`line` 用于连线标签样式，`default` 为默认节点标签样式，影响外观渲染（使用 `render: false` 仅更新属性不触发重渲染）。
+     */
     accessor type: LabelType | undefined;
+    /**
+     * @description 是否为只读模式，启用后双击不会进入编辑状态，`enableEditing` 方法调用也不会生效。
+     */
     accessor readOnly: boolean | undefined;
+    /**
+     * @description 以编程方式启用标签的编辑状态（相当于用户双击），只读模式下不生效。
+     */
     enableEditing(): void;
     render(): React.JSX.Element;
 }

package/dist-types/experimental-node/index.d.ts

@@ -20,12 +20,22 @@ export interface ExperimentalNodeEventsMapping {
     onDragEnd: "drag.end";
 }
 /**
- * 构件 `diagram.experimental-node`
+ * @description 实验性图表节点构件，支持从素材库拖拽到画布（`usage: "library"`）和画布内节点渲染（`usage: "default"`），支持高亮、淡化等状态样式，常配合 `eo-draw-canvas` 和 `eo-display-canvas` 使用。
+ * @category diagram
  */
 export declare class ExperimentalNode extends ReactNextElement implements ExperimentalNodeProps {
     #private;
+    /**
+     * @description 节点使用场景：`library` 表示素材库中的拖拽源，`dragging` 表示正在拖拽中的幽灵节点，`default` 表示画布内正常渲染的节点。
+     */
     accessor usage: ExperimentalUsage | undefined;
+    /**
+     * @description 节点状态，影响外观样式：`highlighted` 高亮、`faded` 淡化、`default` 默认（使用 `render: false` 仅更新属性不触发重渲染）。
+     */
     accessor status: NodeStatus | undefined;
+    /**
+     * @description 装饰器类型，用于渲染不同类型的装饰器外观（area、container、text 等），与 `usage: "dragging"` 配合使用。
+     */
     accessor decorator: DecoratorType | undefined;
     render(): React.JSX.Element;
 }

package/docs/editable-label.md

@@ -1,9 +1,42 @@
-构件 `diagram.editable-label`
+---
+tagName: diagram.editable-label
+displayName: WrappedDiagramEditableLabel
+description: 可编辑标签构件，用于在图表连线或节点上展示可双击编辑的文本标签，支持只读模式，常配合 `eo-draw-canvas` 和 `eo-diagram` 使用。
+category: diagram
+source: "@next-bricks/diagram"
+---
+
+# diagram.editable-label
+
+> 可编辑标签构件，用于在图表连线或节点上展示可双击编辑的文本标签，支持只读模式，常配合 `eo-draw-canvas` 和 `eo-diagram` 使用。
+
+## Props
+
+| 属性     | 类型                     | 必填 | 默认值 | 说明                                                                                                                           |
+| -------- | ------------------------ | ---- | ------ | ------------------------------------------------------------------------------------------------------------------------------ |
+| label    | `string \| undefined`    | -    | -      | 标签文本内容。                                                                                                                 |
+| type     | `LabelType \| undefined` | -    | -      | 标签类型，`line` 用于连线标签样式，`default` 为默认节点标签样式，影响外观渲染（使用 `render: false` 仅更新属性不触发重渲染）。 |
+| readOnly | `boolean \| undefined`   | -    | -      | 是否为只读模式，启用后双击不会进入编辑状态，`enableEditing` 方法调用也不会生效。                                               |
+
+## Events
+
+| 事件                 | detail                                                                  | 说明                                                                                                    |
+| -------------------- | ----------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
+| label.editing.change | `boolean` — 当前是否处于编辑状态，true 表示正在编辑，false 表示结束编辑 | 标签编辑状态变化时触发，当用户开始编辑（双击或调用 `enableEditing`）或结束编辑（失焦/按 Enter）时触发。 |
+| label.change         | `string` — 编辑完成后的新标签文本                                       | 标签编辑完成后触发（用户失焦或按 Enter 键），即使内容未变化也会触发，需自行判断是否发生实际变更。       |
+
+## Methods
+
+| 方法          | 参数         | 返回值 | 说明                                                               |
+| ------------- | ------------ | ------ | ------------------------------------------------------------------ |
+| enableEditing | `() => void` | `void` | 以编程方式启用标签的编辑状态（相当于用户双击），只读模式下不生效。 |
 
 ## Examples
 
 ### Basic
 
+展示可编辑标签的基本用法，双击标签可进入编辑模式，失焦或按 Enter 键确认修改。
+
 ```yaml preview
 brick: diagram.editable-label
 properties:
@@ -15,3 +48,40 @@ events:
     args:
       - "<% `Label changed to: ${EVENT.detail}` %>"
 ```
+
+### Read Only
+
+展示只读模式下的标签，双击不会进入编辑状态。
+
+```yaml preview
+brick: diagram.editable-label
+properties:
+  type: line
+  label: Read Only Label
+  readOnly: true
+events:
+  label.change:
+    action: message.success
+    args:
+      - "<% `Label changed to: ${EVENT.detail}` %>"
+```
+
+### Editing State Change
+
+展示监听编辑状态变化事件，在用户开始/结束编辑时响应。
+
+```yaml preview
+brick: diagram.editable-label
+properties:
+  type: default
+  label: Click to edit
+events:
+  label.editing.change:
+    action: message.info
+    args:
+      - "<% EVENT.detail ? 'Editing started' : 'Editing ended' %>"
+  label.change:
+    action: message.success
+    args:
+      - "<% `New label: ${EVENT.detail}` %>"
+```

package/docs/editable-label.react.md

@@ -0,0 +1,100 @@
+---
+tagName: diagram.editable-label
+displayName: WrappedDiagramEditableLabel
+description: 可编辑标签构件，用于在图表连线或节点上展示可双击编辑的文本标签，支持只读模式，常配合 `eo-draw-canvas` 和 `eo-diagram` 使用。
+category: diagram
+source: "@next-bricks/diagram"
+---
+
+# WrappedDiagramEditableLabel
+
+> 可编辑标签构件，用于在图表连线或节点上展示可双击编辑的文本标签，支持只读模式，常配合 `eo-draw-canvas` 和 `eo-diagram` 使用。
+
+## 导入
+
+```tsx
+import { WrappedDiagramEditableLabel } from "@easyops/wrapped-components";
+```
+
+## Props
+
+| 属性                 | 类型                                | 必填 | 默认值 | 说明                                                                                                                           |
+| -------------------- | ----------------------------------- | ---- | ------ | ------------------------------------------------------------------------------------------------------------------------------ |
+| label                | `string \| undefined`               | -    | -      | 标签文本内容。                                                                                                                 |
+| type                 | `LabelType \| undefined`            | -    | -      | 标签类型，`line` 用于连线标签样式，`default` 为默认节点标签样式，影响外观渲染（使用 `render: false` 仅更新属性不触发重渲染）。 |
+| readOnly             | `boolean \| undefined`              | -    | -      | 是否为只读模式，启用后双击不会进入编辑状态，`enableEditing` 方法调用也不会生效。                                               |
+| onLabelEditingChange | `(e: CustomEvent<boolean>) => void` | -    | -      | 标签编辑状态变化时触发。                                                                                                       |
+| onLabelChange        | `(e: CustomEvent<string>) => void`  | -    | -      | 标签编辑完成后触发。                                                                                                           |
+
+## Events
+
+| 事件                 | detail                                                                  | 说明                                                                                                    |
+| -------------------- | ----------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
+| onLabelEditingChange | `boolean` — 当前是否处于编辑状态，true 表示正在编辑，false 表示结束编辑 | 标签编辑状态变化时触发，当用户开始编辑（双击或调用 `enableEditing`）或结束编辑（失焦/按 Enter）时触发。 |
+| onLabelChange        | `string` — 编辑完成后的新标签文本                                       | 标签编辑完成后触发（用户失焦或按 Enter 键），即使内容未变化也会触发，需自行判断是否发生实际变更。       |
+
+## Methods
+
+| 方法          | 参数         | 返回值 | 说明                                                               |
+| ------------- | ------------ | ------ | ------------------------------------------------------------------ |
+| enableEditing | `() => void` | `void` | 以编程方式启用标签的编辑状态（相当于用户双击），只读模式下不生效。 |
+
+## Examples
+
+### Basic
+
+展示可编辑标签的基本用法，双击标签可进入编辑模式，失焦或按 Enter 键确认修改。
+
+```tsx
+import { WrappedDiagramEditableLabel } from "@easyops/wrapped-components";
+
+function BasicEditableLabel() {
+  return (
+    <WrappedDiagramEditableLabel
+      type="line"
+      label="Relation"
+      onLabelChange={(e) => alert(`Label changed to: ${e.detail}`)}
+    />
+  );
+}
+```
+
+### Read Only
+
+展示只读模式下的标签，双击不会进入编辑状态。
+
+```tsx
+import { WrappedDiagramEditableLabel } from "@easyops/wrapped-components";
+
+function ReadOnlyLabel() {
+  return (
+    <WrappedDiagramEditableLabel
+      type="line"
+      label="Read Only Label"
+      readOnly={true}
+      onLabelChange={(e) => alert(`Label changed to: ${e.detail}`)}
+    />
+  );
+}
+```
+
+### Editing State Change
+
+展示监听编辑状态变化事件，在用户开始/结束编辑时响应。
+
+```tsx
+import { WrappedDiagramEditableLabel } from "@easyops/wrapped-components";
+
+function EditingStateLabel() {
+  return (
+    <WrappedDiagramEditableLabel
+      type="default"
+      label="Click to edit"
+      onLabelEditingChange={(e) =>
+        console.log(e.detail ? "Editing started" : "Editing ended")
+      }
+      onLabelChange={(e) => console.log(`New label: ${e.detail}`)}
+    />
+  );
+}
+```