drawui-core 0.3.4 → 0.3.5

package/dist/index.d.cts

@@ -176,6 +176,8 @@ interface LineShape extends BaseShape {
     type: 'line';
     points: Vec2[];
     connectionType?: ConnectionType;
+    /** 用户手工调节过的中间折点（世界坐标），见 ArrowShape.userPoints */
+    userPoints?: Vec2[];
 }
 type ConnectionType = 'straight' | 'polyline' | 'orthogonal' | 'curve';
 /** 生成点位创建上下文：from 为源点(生成点位)，to 为目标落点 */
@@ -242,6 +244,14 @@ interface ArrowShape extends BaseShape {
     connectionType?: ConnectionType;
     arrowHead?: ArrowHeadType;
     dashed?: boolean;
+    /**
+     * 用户手工调节过的中间折点（**世界坐标**，不含两端）。
+     *
+     * 飞书式「选中连线 → 拖动线段上的手柄调整走线位置」写的就是它：
+     * 存在时走线 = 起点 → userPoints… → 终点（每一段仍是正交的），
+     * 两端依旧跟随绑定（拖动图形后两端自动跟上，中间保持用户摆好的位置）。
+     */
+    userPoints?: Vec2[];
 }
 interface TextShape extends BaseShape {
     type: 'text';
@@ -816,6 +826,7 @@ declare class Editor {
     private connectingTargetId;
     private genPreview;
     private hoverAnchorShapeId;
+    private hoverConnectorId;
     private eraserPoint;
     private mindMapEditingShapeId;
     private mindMapSelectedNode;
@@ -878,6 +889,13 @@ declare class Editor {
     private setGenerationPreview;
     /** 设置悬停图形（画布为其绘制四边连接锚点） */
     private setHoverAnchorShape;
+    /** 设置悬停连线（画布为整条线描一层高亮） */
+    private setHoverConnector;
+    /**
+     * 某条连线当前的真实走线（世界坐标折点）。
+     * 交给工具层做线段手柄的命中与拖动 —— 用的是渲染器同一套计算，保证「看到哪就能拖哪」。
+     */
+    private getConnectorRoute;
     /**
      * 清掉所有「瞬态」的交互可视化状态：连线预览、目标高亮、对齐参考线、框选、悬停锚点。
      * 这些状态只在一次交互过程中有效 —— 只要交互结束（或事件丢失）就必须清空，
@@ -1130,6 +1148,69 @@ declare class Editor {
     dispose(): void;
 }
 
+/**
+ * 连线「手工调线段」的纯几何（飞书式交互的数学部分，不含任何画布/编辑器依赖）。
+ *
+ * 交互模型：选中一条连线 → 在每一段（够长的）线段的**中点**画一个小手柄 →
+ * 拖动它就把这一段沿垂直方向平移，相邻的垂直段自然伸缩，整条线始终横平竖直；
+ * 两端的停靠点/端点**永远不动**，必要时在端点旁补一个折点（这就是飞书里
+ * 「拖中间那段会让线在两端各拐一下」的效果）。
+ *
+ * 结果写回 `ArrowShape.userPoints` / `LineShape.userPoints`（世界坐标，不含两端）。
+ */
+/**
+ * 短于这个长度的线段不生成手柄（太短的段拖不动、手柄比线还长也没意义，飞书同样会略过）。
+ * 取 40：既排除「端点旁自动补出来的 24px 桩」，也放过那些只有几十像素、一拖就糊成一团的短段。
+ */
+declare const MIN_HANDLE_SEGMENT = 40;
+/**
+ * 台阶的最小高度（磁吸半径）。
+ *
+ * 拖动一段时，只要平移后的位置落进相邻水平线的这个范围内，就**直接吸回那条线**
+ * （＝把台阶抹平）。于是：
+ *  - 拖不出 1~19px 的浅台阶 —— 那种「两条平行线贴在一起」的观感就是用户说的「变成两条线段」；
+ *  - 已经存在的浅台阶，往基线方向一拖就自动抹平（不会出现「拖不动、回不去」）；
+ *  - 想真正折出台阶，明确拖过这个距离即可（超过就按实际位置走，不再吸附）。
+ */
+declare const MIN_JOG = 20;
+interface SegmentHandle {
+    /** 线段序号：route[index] → route[index + 1] */
+    index: number;
+    /** 手柄中心（世界坐标）= 线段中点 */
+    center: Vec2;
+    /** 线段轴向：'H' 水平（可上下拖）/ 'V' 垂直（可左右拖） */
+    axis: 'H' | 'V';
+    /** 线段长度 */
+    length: number;
+}
+/** 点到线段的最短距离（连线命中、手柄命中共用；SelectTool 也委托到这里） */
+declare function pointToSegmentDistance(point: Vec2, a: Vec2, b: Vec2): number;
+/** 一条走线（世界坐标折线）上所有可拖动的线段手柄 */
+declare function connectorSegmentHandles(route: Vec2[], minLength?: number): SegmentHandle[];
+/**
+ * 命中要拖动的线段：优先「手柄中心 handleRadius 内」；没直接命中就给一次宽容 ——
+ * 取离得最近的、够长可拖的那一段（点到该段距离 ≤ maxSegmentDist）。
+ *
+ * 这样「抓在选中连线的任意位置上」都能拖到最近的那段，也让「抓线段」优先于
+ * 拖整条线/从锚点拉新线 —— 避免在连线上按一下却拉出一条新线。
+ */
+declare function pickSegmentHandle(route: Vec2[], point: Vec2, handleRadius?: number, maxSegmentDist?: number): SegmentHandle | null;
+/**
+ * 把第 index 段沿其垂直方向平移 delta（水平段：>0 = 向下；垂直段：>0 = 向右），
+ * 返回平移后的**新走线**（首尾点保持不变）。
+ *
+ * 传入的 route 应当始终是「按下时的那条走线」，每次移动都从它重新算 —— 因为拖首/末段
+ * 会插入折点、段序号会变，从原始走线重算才能得到稳定（不漂移）的结果。
+ */
+declare function offsetConnectorSegment(route: Vec2[], index: number, delta: number): Vec2[];
+/**
+ * 去掉连续重复点与共线冗余点，精简冗余拐点。
+ * （唯一实现：Renderer.collapseLinePoints 与交互层写回前都调它 —— 别再各写一份）
+ */
+declare function collapseRoute(pts: Vec2[]): Vec2[];
+/** 走线 → 可写回 shape 的中间折点（去掉两端） */
+declare function routeToUserPoints(route: Vec2[]): Vec2[];
+
 interface SnapGuide {
     type: 'horizontal' | 'vertical';
     position: number;
@@ -1163,7 +1244,9 @@ declare class Renderer {
     /** 导出用：非 null 时先以该颜色铺满整块画布（白底等），默认不铺（透明） */
     background?: string | null, 
     /** 悬停的图形 id：为其绘制四边连接锚点（飞书式悬浮提示），已选中图形由选择手柄负责 */
-    hoverAnchorShapeId?: string | null): void;
+    hoverAnchorShapeId?: string | null, 
+    /** 悬停的连线 id：整条线描一层浅蓝高亮（提示「这条线可点、点开能调线段」） */
+    hoverConnectorId?: string | null): void;
     /** 橡皮擦：半透明主色圆 + 主色描边，半径与笔刷命中范围一致（屏幕像素恒定） */
     private drawEraserBrush;
     /** 连接进行中，高亮目标图形四边中点的可连锚点 */
@@ -1206,12 +1289,8 @@ declare class Renderer {
     private drawUmlInterface;
     /** 默认拐点圆角半径（页面坐标） */
     private static readonly DEFAULT_CORNER_RADIUS;
-    /** 连线与图形之间保留的最小避障间距，避免线条贴边/粘在图形上 */
-    private static readonly ROUTE_CLEARANCE;
     /** 连接点处的垂直出线桩长度：第一段垂直脱离图形边缘，避免贴角/贴边 */
     private static readonly CONNECTION_LEAD;
-    /** 连接的源/目标图形作为障碍时使用的避让间距（足够阻挡中段折回穿过，又允许紧邻节点直连） */
-    private static readonly CONNECTED_PAD;
     /**
      * 思维导图：先画连线（父右缘 → 子左缘的平滑曲线），再画节点
      * （白底圆角矩形 + 层级色描边 + 图标/文本/左上角属性说明/折叠标记）。
@@ -1221,6 +1300,29 @@ declare class Renderer {
     private drawMindMapNodes;
     /** 按像素宽度截断文本并加省略号 */
     private ellipsizeText;
+    /**
+     * 把连线两端解析成世界坐标折点 + 停靠法向（绑定落点、auto 重选、未绑定端点的轮廓吸附）。
+     * 绘制与 getConnectorRoute 共用这一份，避免两处规则漂移。
+     */
+    private resolveConnectorEnds;
+    /**
+     * 用户手工调过折点的连线：走线 = 起点 → 用户折点… → 终点（两端仍跟随绑定/端点）。
+     *
+     * ⚠️ 两端要先做和「两端点」时同样的近似对齐：用户是照着**对齐后**的那条线拖的手柄，
+     * 折点坐标是相对对齐后的轴线算出来的；若这里用未对齐的原始端点接上，就会在两端各
+     * 留下几像素的斜边（画布与导出还会各画各的）。对齐后手工折点与端点严格同轴。
+     */
+    private withUserPoints;
+    /**
+     * 连线当前的真实走线（**世界坐标**折点）。
+     * 手柄命中、手柄拖动都用它 —— 与绘制同一套计算，所以「看到手柄在哪，点它就一定命中」。
+     */
+    getConnectorRoute(shape: Shape, shapeMap: Map<string, Shape>): Vec2[];
+    /**
+     * 选中连线时：在每段（够长的）线段中点画一个可拖动的小手柄（飞书式「拖线段调位置」）。
+     * 拖动交互在 SelectTool 的 'dragging-segment' 状态里。
+     */
+    private drawSegmentHandles;
     private drawLine;
     private drawArrow;
     /** 选中连线 → 在线条上叠加一条高亮辅助线 */
@@ -1242,12 +1344,24 @@ declare class Renderer {
     private static readonly GEN_GHOST_ID;
     /** 与 Editor.lineStyle() 一致：预览线用最终连线的真实颜色/粗细 */
     private static readonly PREVIEW_LINE_STYLE;
+    /**
+     * 'straight' 连线的近似对齐：**只在「就是两端点」时**把近对齐拉成一条直线。
+     * 一旦用户手工折过点（>2 点），绝不能拉平 —— 否则用户拖出来的折弯会被
+     * 「两端 y 取平均」整条压回原来的直线，看起来就像「拖了没反应／原来的线还在」。
+     */
+    private straightAligned;
+    /**
+     * 实际用于绘制/命中的连线类型：**'straight' 但用户手工折过点 → 按 'polyline' 处理**。
+     * 直线型不参与正交路由，两端停靠点又常常不在同一轴上，原样画会出现几像素的斜边；
+     * 折线化后严格横平竖直（飞书拖过线段后同样变成折线型连接线）。
+     */
+    private effectiveConnType;
     /**
      * 判断连线两端是否水平或垂直对齐（在容差内）。
      * 若在容差内，强制将坐标对齐（避免 grid snapping 导致无法形成直线）。
      */
     private getAlignedPoints;
-    /** 生成路径点（对齐容差已在上游处理）。 */
+    /** 生成路径点。近似对齐（容差内）时先拉直，再交给对应连接类型路由。 */
     private buildPathPoints;
     /**
      * 使用 arcTo 绘制带圆角拐点的折线。
@@ -1261,48 +1375,25 @@ declare class Renderer {
     private drawSnapGuides;
     /** 折线：与orthogonal使用相同的H-V-H路由，差异仅在渲染（sharp vs rounded）。dock 法向在首/末段加一段垂直出线桩，垂直脱离图形边缘。 */
     private generatePolylinePoints;
-    /** 直角折线：与 polyline 使用相同的 H-V-H 正交路由，仅渲染方式（sharp）不同。 */
-    private generateOrthogonalPoints;
     /**
      * 把折线末段掰到期望轴向（'H' 水平收尾 / 'V' 垂直收尾）。
-     * 绕行分支（A 星网格 / 退避）给出的路径末段方向不受控，这里在末点前补一个拐点，
      * 保证箭头始终沿接入边法向插入（或沿出线方向收尾）。
      */
     private ensureFinalAxis;
-    /** 去除连续重合点与共线点，精简冗余拐点 */
+    /** 去除连续重合点与共线点，精简冗余拐点（唯一实现见 connectorEdit.collapseRoute） */
     private collapseLinePoints;
-    /** 计算单段直角路由：优先无碰撞、且符合总线轴方向的 H-V-H / V-H-V 折线，必要时绕开障碍 */
-    private computeOrthogonalRoute;
     /**
-     * 剔除「把某个端点压在身下」的障碍。
+     * 计算单段直角路由：最简单的正交折线（H-V-H / V-H-V / L 拐角）
+     * —— **刻意不做避障**，允许从其它图形上穿过去。
      *
-     * 这类障碍（典型：用户把图形拖到与另一张图形重叠）无法绕开 —— 端点的落点就在它里面，
-     * 与其避让只会让布线变成「绕着端点打转」的怪线，还会把 A* 的终点节点封死。
-     * 剔除后连线可以直穿重叠图形，观测上就是「叠在一起就随他叠」，
-     * 同时保证端点（点位）不会被自动挪走。
-     */
-    private dropObstaclesAtEndpoints;
-    /**
-     * 在停靠偏好对应的总线轴上，从源侧向外逐点平移总线位置，返回第一条「垂直方向和
-     * 末段水平分支都避开所有中间障碍」的总线折线；找不到则返回 null。
-     * 平移的起点越靠源侧越好，这样多条同一来源的连线会用同一条紧贴源点的主干总线。
-     */
-    private findClearBus;
-    /** 收集连线绕行所需的障碍包围盒（转为 shape 本地坐标）。
-     *  将本连线之外的所有图形（含其它连线/箭头/手绘）都作为障碍；
-     *  连接端点所在图形使用小间距（CONNECTED_PAD），其余图形使用大间距（ROUTE_CLEARANCE）。 */
-    private collectRoutingObstacles;
-    private pointInRect;
-    /** 整个折线路径是否与任一障碍相交 */
-    private routeHitsObstacles;
-    /** 轴对齐线段是否与任一障碍（向外扩其 pad）相交 */
-    private segmentHitsObstacle;
-    /**
-     * 正交避障路由器（类飞书）。
-     * 用「起终点坐标 + 每个障碍物扩展边界」构造一条布线网格，再用 A* 在网格上求
-     * 最短避障折线（半径外扩 pad 保证不贴边）。返回不含 from、含 to 的拐点序列。
+     * 为什么不做避障（2026-09-22 决定，对齐飞书）：绕行会让路径在拖动时反复改形
+     * （3 段 ↔ 6 段拐点来回跳），观感就是「绕来绕去」；而「挡路/重叠时直接穿过去、
+     * 端点不挪窝、永远横平竖直」更可预期也更好读。实测绕行只在约 6% 的布局下触发，
+     * 但它带来的「画布 ≠ 导出」与拖拽跳变是所有场景都在承受的。
+     *
+     * 规则与 export.dockRoutePoints 完全一致 → 画布所见即导出所得。
      */
-    private routeOrthogonalAvoidance;
+    private computeOrthogonalRoute;
     /**
      * 曲线：用三次贝塞尔拼接出平滑曲线（离散化采样）。
      * 端点若停靠在图形上（dock.fromN/toN），控制点沿法向伸出，使曲线垂直脱离 / 垂直接入
@@ -1433,6 +1524,10 @@ interface ToolContext {
     setGenerationPreview(preview: GenerationPreview | null): void;
     /** 悬停图形 → 画布为其绘制四边连接锚点（null 清除） */
     setHoverAnchorShape(id: string | null): void;
+    /** 悬停连线 → 画布为整条线描一层高亮（null 清除） */
+    setHoverConnector(id: string | null): void;
+    /** 某条连线当前的真实走线（世界坐标折点）：线段手柄的命中/拖动用它，与画布绘制同一套计算 */
+    getConnectorRoute(shapeId: string): Vec2[];
     /** 新建连线的线条样式（颜色/粗细），与最终创建的连线保持一致 */
     getLineStyle(): ShapeStyle;
     /** 拖动到空白处：创建一条浮动线条并弹出"选择新图形"菜单 */
@@ -1496,6 +1591,14 @@ declare class SelectTool extends Tool {
     private hoverGenPoint;
     /** 悬停（未按下）的图形 id：为其显示四边连接锚点，可直接从这里拖出连线 */
     private hoverShapeId;
+    /** 悬停（未按下）的连线 id：整条线描高亮 */
+    private hoverConnectorId;
+    /**
+     * 正在拖动某条连线的第 index 段（飞书式「拖线段调位置」）。
+     * route 是**按下那一刻**的走线：每次移动都从它重新算（拖动会插入折点、段序号会变，
+     * 从原始走线重算才不会累积漂移）。
+     */
+    private draggingSegment;
     private rotatingState;
     private draggingArrowId;
     private draggingTerminal;
@@ -1514,6 +1617,34 @@ declare class SelectTool extends Tool {
     onPointerDown(point: Vec2, event: PointerEvent): void;
     onPointerMove(point: Vec2, event: PointerEvent): void;
     onPointerUp(point: Vec2, _event: PointerEvent): void;
+    /**
+     * 点是否落在某条连线的**当前真实走线**上（容差 10px）。
+     * 画布上看到的那条线、悬停高亮、点击命中、手柄命中全部用这一份几何 ——
+     * 「看到哪就能点到哪」，不会出现悬停能亮、点击没反应。
+     */
+    private isPointOnConnector;
+    /**
+     * 悬停命中的连线 id（未选中才有高亮提示；选中的连线由线段手柄负责显示）。
+     * 与点击命中同一套判定（isPointOnConnector）。
+     */
+    private findHoverConnector;
+    /**
+     * 命中已选中连线上要拖动的线段（先手柄中心 10px，再退一步「离得最近的段」14px）。
+     * 这样在选中连线上任意位置按下都能拖到最近那一段，也就不会误触发「拖整条线 / 从锚点拉新线」。
+     */
+    private hitConnectorSegmentHandle;
+    /** 拖线段时的光标：水平段能上下拖 → 上下箭头；垂直段能左右拖 → 左右箭头 */
+    private segmentCursor;
+    /** 拖动线段：把这一段沿垂直方向平移（相邻段自然伸缩），两端端点永不移动 */
+    private handleDraggingSegment;
+    /**
+     * 把调整后的走线写回 shape：
+     * - 绑定连线（有 start/endBinding）只写中间折点 `userPoints`，两端继续跟随绑定；
+     * - 自由连线（无绑定）整条走线就是它自己的 `points`。
+     * 先把走线里的重复点/共线冗余点去掉：**如果去掉后就是一条直线（≤2 点），把 userPoints 清空**，
+     * 交还给自动路由 —— 这样「往基线拖、把浅台阶抹平」之后，连线是真的恢复原样，而不是留着一堆零高度折点。
+     */
+    private writeConnectorRoute;
     hasTransientState(): boolean;
     /**
      * 取消一切瞬态交互（拖拽/生成/框选/旋转/连线端点拖拽）并清掉画布上的瞬态预览。
@@ -1573,6 +1704,7 @@ declare class SelectTool extends Tool {
     private bindingPosition;
     private isPointInShape;
     private isPointInHexagon;
+    /** 点到线段最短距离（唯一实现见 connectorEdit.pointToSegmentDistance） */
     private pointToLineDistance;
     /**
      * 待新建图形与源图形重叠时，把它沿「源→目标」方向推到不重叠（留一个引线距离）。
@@ -1785,4 +1917,4 @@ declare function countMindMapNodes(root: MindMapNode): number;
  */
 declare function layoutMindMap(root: MindMapNode): MindMapLayoutResult;
 
-export { type ArrowBinding, type ArrowHeadType, type ArrowShape, type ArrowStyle, ArrowTool, Camera, type CameraState, type CircleShape, type ConnectionType, DEFAULT_HIGHLIGHTER_COLOR, type DiamondShape, type DrawShape, type DrawuiTheme, type DrawuiThemeSelection, Editor, type EditorData, type EditorOptions, type EditorState, type EllipseShape, type ExportFormat, type ExportOptions, type FreehandMode, FreehandTool, type GenerationContext, HandTool, type HexagonShape, type Language, type LineShape, LineTool, MINDMAP_COLORS, MINDMAP_FONT_SIZE, MINDMAP_MAX_WIDTH, MINDMAP_MIN_WIDTH, MINDMAP_NODE_HEIGHT, Mat2d, type MessageKey, type MindMapLayoutResult, type MindMapNode, type MindMapNodePos, type MindMapShape, type OctagonShape, type ParallelogramShape, type PentagonShape, type Rect, type RectangleShape, Renderer, type RoundedRectangleShape, SelectTool, type Shape, type ShapeStyle, ShapeTool, type ShapeType, type SnapGuide, type StarShape, THEME, type TextShape, type ToolType, type TrapezoidShape, type TriangleShape, UML_FONT_SIZE, UML_HEADER_HEIGHT, UML_LINE_HEIGHT, UML_MIN_WIDTH, UML_PADDING_X, UML_PADDING_Y, type UiEvent, type UmlAttribute, type UmlClassShape, type UmlInterfaceShape, type UmlMethod, type UmlVisibility, Vec, type Vec2 as Vec2Type, calcUmlClassSize, cloneMindMapNode, countMindMapNodes, downloadBlob, exportToBlob, findMindMapNode, getContentBounds, getLanguage, getMindMapNodeDepth, getMindMapParent, getTheme, hexToRgba, layoutMindMap, mindMapNodeColor, mindMapNodeSize, renderSVGString, renderToCanvas, setLanguage, setTheme, shadeColor, subscribeLanguage, subscribeTheme, t };
+export { type ArrowBinding, type ArrowHeadType, type ArrowShape, type ArrowStyle, ArrowTool, Camera, type CameraState, type CircleShape, type ConnectionType, DEFAULT_HIGHLIGHTER_COLOR, type DiamondShape, type DrawShape, type DrawuiTheme, type DrawuiThemeSelection, Editor, type EditorData, type EditorOptions, type EditorState, type EllipseShape, type ExportFormat, type ExportOptions, type FreehandMode, FreehandTool, type GenerationContext, HandTool, type HexagonShape, type Language, type LineShape, LineTool, MINDMAP_COLORS, MINDMAP_FONT_SIZE, MINDMAP_MAX_WIDTH, MINDMAP_MIN_WIDTH, MINDMAP_NODE_HEIGHT, MIN_HANDLE_SEGMENT, MIN_JOG, Mat2d, type MessageKey, type MindMapLayoutResult, type MindMapNode, type MindMapNodePos, type MindMapShape, type OctagonShape, type ParallelogramShape, type PentagonShape, type Rect, type RectangleShape, Renderer, type RoundedRectangleShape, type SegmentHandle, SelectTool, type Shape, type ShapeStyle, ShapeTool, type ShapeType, type SnapGuide, type StarShape, THEME, type TextShape, type ToolType, type TrapezoidShape, type TriangleShape, UML_FONT_SIZE, UML_HEADER_HEIGHT, UML_LINE_HEIGHT, UML_MIN_WIDTH, UML_PADDING_X, UML_PADDING_Y, type UiEvent, type UmlAttribute, type UmlClassShape, type UmlInterfaceShape, type UmlMethod, type UmlVisibility, Vec, type Vec2 as Vec2Type, calcUmlClassSize, cloneMindMapNode, collapseRoute, connectorSegmentHandles, countMindMapNodes, downloadBlob, exportToBlob, findMindMapNode, getContentBounds, getLanguage, getMindMapNodeDepth, getMindMapParent, getTheme, hexToRgba, layoutMindMap, mindMapNodeColor, mindMapNodeSize, offsetConnectorSegment, pickSegmentHandle, pointToSegmentDistance, renderSVGString, renderToCanvas, routeToUserPoints, setLanguage, setTheme, shadeColor, subscribeLanguage, subscribeTheme, t };