leafer-connector 1.4.1 → 1.5.1

package/README.md

@@ -50,6 +50,98 @@ const edge = new Connector(app, { from: a, to: b });
 app.tree.add([a, b, edge]);
 ```
 
+## 纯坐标连线（Point 模式）
+
+如果你不想传节点（`IUI`），只想用 **两个点坐标** 画一条连线，可以用 point 模式：
+
+- 只传点时，Connector **不会监听节点拖拽/渲染事件**（默认 `updateMode="manual"`）
+- **点击连线**会显示起点/终点两个圆点（handle），拖动圆点会更新端点坐标
+
+Point 模式新增参数：
+
+- **`fromPoint` / `toPoint`**：`IPointData`（world 坐标），与 `from/to` 二选一
+- **`pointsEditable`**：`boolean`，是否允许点击进入编辑态（显示/拖拽端点圆点），默认 `true`
+- **`pointHandles`**：端点圆点样式（见下表）
+- **`onPointsChange`**：端点坐标变化回调（拖拽端点 / `setPoints` 时触发）
+
+```ts
+import { App } from "leafer-editor";
+import { Connector } from "leafer-connector";
+
+const app = new App({ view: container, editor: {} });
+
+const edge = new Connector(app, {
+  fromPoint: { x: 120, y: 160 },
+  toPoint: { x: 520, y: 320 },
+  routeType: "bezier",
+  pointsEditable: true, // 默认 true（仅 point 模式生效）
+  onPointsChange: ({ from, to }) => {
+    console.log("points changed:", from, to);
+  },
+});
+
+app.tree.add(edge);
+edge.update(); // point 模式下你也可以手动触发刷新
+```
+![Preview](https://github.com/rideWind97/leafer-connector/blob/master/playground/assets/point-mode.gif)
+
+
+### 模式切换（Point → Node）
+
+Connector 支持在运行时从 **Point 模式切回 Node 模式**（比如你先用点画线，后续拿到真实节点再绑定）：
+
+- **会自动清理 point-mode 的编辑态/拖拽态**（隐藏 handles）
+- **会解绑旧的交互监听并重新绑定**，避免残留 point-mode 的 click/drag 行为
+- 默认会把 `updateMode` 切回 `"event"`（因为 point-mode 默认 `updateMode="manual"`）
+
+API：
+
+```ts
+// 从 point-mode 切换到 node-mode
+edge.switchToNodeMode(a, b);
+
+// 或者显式指定 updateMode（例如协同场景）
+edge.switchToNodeMode(a, b, { updateMode: "render" });
+```
+
+参数说明：
+
+- **`from`**：`IUI`，起点节点
+- **`to`**：`IUI`，终点节点
+- **`opts`**（可选）：
+  - **`opts.autoUpdateMode`**：`boolean`，默认 `true`。为 `true` 时（且未传 `opts.updateMode`），会将 `updateMode` 设为 `"event"`
+  - **`opts.updateMode`**：`"event" | "render" | "manual"`，强制设置切换后的更新模式
+
+### 模式切换（Node → Point）
+
+当你希望“先连节点”，后续又想把它变成“纯点坐标线”（不再依赖节点）时，可以用：
+
+```ts
+// 从 node-mode 切换到 point-mode
+edge.switchToPointMode({ x: 120, y: 160 }, { x: 520, y: 320 });
+
+// 或者显式指定 updateMode
+edge.switchToPointMode(
+  { x: 120, y: 160 },
+  { x: 520, y: 320 },
+  { updateMode: "manual" }
+);
+```
+
+行为说明：
+
+- 会解绑旧的交互监听并按 point-mode 重新绑定
+- 会清理 node 引用与拖拽态
+- 默认会把 `updateMode` 切到 `"manual"`（因为 point-mode 通常由业务侧手动刷新/控制）
+
+参数说明：
+
+- **`fromPoint`**：`IPointData`，起点坐标（world）
+- **`toPoint`**：`IPointData`，终点坐标（world）
+- **`opts`**（可选）：
+  - **`opts.autoUpdateMode`**：`boolean`，默认 `true`。为 `true` 时（且未传 `opts.updateMode`），会将 `updateMode` 设为 `"manual"`
+  - **`opts.updateMode`**：`"event" | "render" | "manual"`，强制设置切换后的更新模式
+
 ## 路由示例
 
 ### 正交（orthogonal）
@@ -159,6 +251,8 @@ const edge = new Connector(app, {
 | --- | --- | --- | --- | --- |
 | `from` | `IUI` | 是 | - | 起点节点 |
 | `to` | `IUI` | 是 | - | 终点节点 |
+| `fromPoint` | `IPointData` | 否 | - | **Point 模式**起点坐标（world）；与 `from/to` 互斥 |
+| `toPoint` | `IPointData` | 否 | - | **Point 模式**终点坐标（world）；与 `from/to` 互斥 |
 | `routeType` | `"orthogonal" \| "bezier" \| "straight" \| "custom"` | 否 | `"orthogonal"` | 路由类型 |
 | `padding` | `number` | 否 | `20` | 出线段长度（从 linkPoint 沿法线外扩） |
 | `margin` | `number` | 否 | `0` | 连接点与节点边界间距（让线不贴边） |
@@ -177,7 +271,8 @@ const edge = new Connector(app, {
 | `updateMode` | `"event" \| "render" \| "manual"` | 否 | `"event"` | 自动更新模式（协同场景建议用 render） |
 | `renderThrottleMs` | `number` | 否 | `16` | render 模式节流（ms） |
 | `getNodeId` | `(node: IUI) => string` | 否 | - | 协同序列化：node -> id（用于 getState/onChange） |
-| `onChange` | `({ reason, prev, next, diff, changedKeys }) => void` | 否 | - | 统一变更回调（reason: `"label" \| "setState"`） |
+| `onChange` | `({ reason, prev, next, diff, changedKeys }) => void` | 否 | - | 统一变更回调（reason: `"label" \| "setState" \| "points"`） |
+| `onPointsChange` | `({ from, to }) => void` | 否 | - | **Point 模式**端点坐标变化回调 |
 | `onLabelChange` | `({ oldText, newText }) => void` | 否 | - | label 文本变化回调 |
 | `stroke` | `string` | 否 | `"#ffffff"` | 线条颜色 |
 | `strokeWidth` | `number` | 否 | `2` | 线宽 |
@@ -191,6 +286,14 @@ const edge = new Connector(app, {
 | `label.editable` | `boolean` | 否 | - | 是否允许编辑（打开 inner editor） |
 | `label.style` | `Partial<ITextInputData>` | 否 | - | 文案样式（fill/fontSize/boxStyle/padding 等） |
 | `labelOnDoubleClick` | `boolean` | 否 | `true` | 是否允许双击连线打开/创建 label |
+| `pointsEditable` | `boolean` | 否 | `true` | **Point 模式**是否允许点击进入编辑态（显示/拖拽端点圆点） |
+| `pointHandles` | `{ ... }` | 否 | - | **Point 模式**端点圆点样式 |
+| `pointHandles.size` | `number` | 否 | `10` | 端点圆点直径 |
+| `pointHandles.fill` | `string` | 否 | `"#ffffff"` | 填充色 |
+| `pointHandles.stroke` | `string` | 否 | `"#000000"` | 描边色 |
+| `pointHandles.strokeWidth` | `number` | 否 | `1` | 描边宽度 |
+| `pointHandles.opacity` | `number` | 否 | `1` | 透明度 |
+| `pointHandles.hitStrokeWidth` | `number` | 否 | `12` | 命中范围（越大越好点） |
 
 ### `TargetOption`（用于 `opt1/opt2`）表格
 
@@ -367,6 +470,13 @@ const edge = new Connector(app, {
 
 - 导出：`Connector` 以及相关类型（见 `src/types.ts`）
 
+### Connector 实例方法（补充）
+
+| 方法 | 说明 |
+| --- | --- |
+| `switchToNodeMode(from, to, opts?)` | 从 point-mode 切换到 node-mode，并重新绑定交互监听（详见上方“模式切换”小节） |
+| `switchToPointMode(fromPoint, toPoint, opts?)` | 从 node-mode 切换到 point-mode，并重新绑定交互监听（详见上方“模式切换”小节） |
+
 ## 构建与发布
 
 本包默认输出 **双产物**：
@@ -374,6 +484,19 @@ const edge = new Connector(app, {
 - ESM：`dist/esm`
 - CJS：`dist/cjs`（`.cjs` 后缀）
 
+## Vue 3 + Vite Playground（本仓库内运行示例）
+
+本仓库内置了一个 Vue 3 的 Vite 示例项目（用于本地调试/演示）：
+
+```bash
+pnpm install
+pnpm run dev
+```
+
+- 默认会启动在 `http://localhost:5173`
+- playground 代码在 `playground-vue/`
+- 开发时会通过 Vite alias 直接引用本仓库源码：`leafer-connector → ../src/index.ts`
+
 可选：Rollup 生产 bundle（更适合做体积检查/发布前 smoke test）：
 
 ```bash