@haoxin-web/excalidraw 1.0.21 → 1.0.22

package/dist/prod/subset-shared.chunk.js

@@ -1 +1 @@
-import{a,b,c,d}from"./chunk-LS7FJGPW.js";import"./chunk-UB3N3ODO.js";import"./chunk-SRAX5OIU.js";export{a as Commands,b as subsetToBase64,c as subsetToBinary,d as toBase64};
+import{a,b,c,d}from"./chunk-LS7FJGPW.js";import"./chunk-H7BFYYZW.js";import"./chunk-SRAX5OIU.js";export{a as Commands,b as subsetToBase64,c as subsetToBinary,d as toBase64};

package/dist/prod/subset-worker.chunk.js

@@ -1 +1 @@
-import{a as r,c as t}from"./chunk-LS7FJGPW.js";import"./chunk-UB3N3ODO.js";import"./chunk-SRAX5OIU.js";var s=import.meta.url?new URL(import.meta.url):void 0;typeof window>"u"&&typeof self<"u"&&(self.onmessage=async e=>{switch(e.data.command){case r.Subset:let a=await t(e.data.arrayBuffer,e.data.codePoints);self.postMessage(a,{transfer:[a]});break}});export{s as WorkerUrl};
+import{a as r,c as t}from"./chunk-LS7FJGPW.js";import"./chunk-H7BFYYZW.js";import"./chunk-SRAX5OIU.js";var s=import.meta.url?new URL(import.meta.url):void 0;typeof window>"u"&&typeof self<"u"&&(self.onmessage=async e=>{switch(e.data.command){case r.Subset:let a=await t(e.data.arrayBuffer,e.data.codePoints);self.postMessage(a,{transfer:[a]});break}});export{s as WorkerUrl};

package/dist/types/excalidraw/components/ExternalLeftToolbar.d.ts

@@ -0,0 +1,8 @@
+import React from "react";
+import type { ExcalidrawImperativeAPI } from "../types";
+export type ExternalLeftToolbarProps = {
+    excalidrawAPI: ExcalidrawImperativeAPI | null;
+    className?: string;
+    style?: React.CSSProperties;
+};
+export declare const ExternalLeftToolbar: ({ excalidrawAPI, className, style, }: ExternalLeftToolbarProps) => import("react/jsx-runtime").JSX.Element;

package/dist/types/excalidraw/index.d.ts

@@ -3,6 +3,7 @@ import Footer from "./components/footer/FooterCenter";
 import LiveCollaborationTrigger from "./components/live-collaboration/LiveCollaborationTrigger";
 import MainMenu from "./components/main-menu/MainMenu";
 import WelcomeScreen from "./components/welcome-screen/WelcomeScreen";
+import { UserList } from "./components/UserList";
 import "./css/app.scss";
 import "./css/styles.scss";
 import "./fonts/fonts.css";
@@ -32,7 +33,10 @@ export { MainMenu };
 export { Ellipsify } from "./components/Ellipsify";
 export { useDevice } from "./components/App";
 export { WelcomeScreen };
+export { UserList };
 export { LiveCollaborationTrigger };
+export { ExternalLeftToolbar } from "./components/ExternalLeftToolbar";
+export type { ExternalLeftToolbarProps } from "./components/ExternalLeftToolbar";
 export { Stats } from "./components/Stats";
 export { DefaultSidebar } from "./components/DefaultSidebar";
 export { TTDDialog } from "./components/TTDDialog/TTDDialog";
@@ -45,3 +49,4 @@ export { DiagramToCodePlugin } from "./components/DiagramToCodePlugin/DiagramToC
 export { getDataURL } from "./data/blob";
 export { isElementLink } from "@excalidraw/element";
 export { setCustomTextMetricsProvider } from "@excalidraw/element";
+export type { LeftToolbarCommand, LeftToolbarFreedrawVariant, LeftToolbarLineVariant, LeftToolbarShapeTool, LeftToolbarStylePatch, } from "./types";

package/dist/types/excalidraw/types.d.ts

@@ -628,6 +628,52 @@ export type PointerDownState = Readonly<{
     };
 }>;
 export type UnsubscribeCallback = () => void;
+export type LeftToolbarShapeTool = Extract<ToolType, "rectangle" | "diamond" | "ellipse" | "triangle" | "pentagon" | "callout" | "hollow_arrow" | "hollow_double_arrow">;
+export type LeftToolbarLineVariant = "line" | "arrow" | "doubleArrow" | "outlineArrow" | "outlineDoubleArrow";
+export type LeftToolbarFreedrawVariant = "pen" | "highlighter";
+export type LeftToolbarStylePatch = Partial<Pick<AppState, "currentItemStrokeColor" | "currentItemBackgroundColor" | "currentItemFillStyle" | "currentItemStrokeWidth" | "currentItemOpacity" | "currentItemStartArrowhead" | "currentItemEndArrowhead" | "currentItemFontSize" | "currentItemTextAlign" | "currentTextBold" | "currentTextItalic" | "currentTextUnderline" | "currentTextStrikethrough">>;
+export type LeftToolbarCommand = {
+    type: "selectSelection";
+} | {
+    type: "selectFreedraw";
+    payload?: {
+        variant?: LeftToolbarFreedrawVariant;
+        strokeWidth?: number;
+        strokeColor?: string;
+    };
+} | {
+    type: "selectLine";
+    payload?: {
+        variant?: LeftToolbarLineVariant;
+        strokeWidth?: number;
+        strokeColor?: string;
+    };
+} | {
+    type: "selectShape";
+    payload?: {
+        shape?: LeftToolbarShapeTool;
+        strokeWidth?: number;
+        strokeColor?: string;
+        backgroundColor?: string;
+        fillStyle?: AppState["currentItemFillStyle"];
+    };
+} | {
+    type: "selectText";
+    payload?: {
+        fontSize?: number;
+        textAlign?: AppState["currentItemTextAlign"];
+        strokeColor?: string;
+        bold?: boolean;
+        italic?: boolean;
+        underline?: boolean;
+        strikethrough?: boolean;
+    };
+} | {
+    type: "selectEraser";
+} | {
+    type: "updateStyle";
+    payload: LeftToolbarStylePatch;
+};
 export interface ExcalidrawImperativeAPI {
     updateScene: InstanceType<typeof App>["updateScene"];
     /**
@@ -658,6 +704,61 @@ export interface ExcalidrawImperativeAPI {
     addFiles: (data: BinaryFileData[]) => void;
     id: string;
     setActiveTool: InstanceType<typeof App>["setActiveTool"];
+    leftToolbar: {
+        /**
+         * Left toolbar: selection tool.
+         */
+        selectSelection: () => void;
+        /**
+         * Left toolbar: freedraw tool.
+         */
+        selectFreedraw: (opts?: {
+            variant?: LeftToolbarFreedrawVariant;
+            strokeWidth?: number;
+            strokeColor?: string;
+        }) => void;
+        /**
+         * Left toolbar: line/arrow group.
+         */
+        selectLine: (opts?: {
+            variant?: LeftToolbarLineVariant;
+            strokeWidth?: number;
+            strokeColor?: string;
+        }) => void;
+        /**
+         * Left toolbar: shapes group.
+         */
+        selectShape: (shape?: LeftToolbarShapeTool, opts?: {
+            strokeWidth?: number;
+            strokeColor?: string;
+            backgroundColor?: string;
+            fillStyle?: AppState["currentItemFillStyle"];
+        }) => void;
+        /**
+         * Left toolbar: text tool.
+         */
+        selectText: (opts?: {
+            fontSize?: number;
+            textAlign?: AppState["currentItemTextAlign"];
+            strokeColor?: string;
+            bold?: boolean;
+            italic?: boolean;
+            underline?: boolean;
+            strikethrough?: boolean;
+        }) => void;
+        /**
+         * Left toolbar: eraser tool.
+         */
+        selectEraser: () => void;
+        /**
+         * Generic style update used by external custom toolbar.
+         */
+        updateStyle: (patch: LeftToolbarStylePatch) => void;
+        /**
+         * Executes a serializable command. Designed for cross-end communication.
+         */
+        dispatch: (command: LeftToolbarCommand) => void;
+    };
     setCursor: InstanceType<typeof App>["setCursor"];
     resetCursor: InstanceType<typeof App>["resetCursor"];
     toggleSidebar: InstanceType<typeof App>["toggleSidebar"];

package/docs/left-toolbar-commands.mdx

@@ -0,0 +1,380 @@
+# Left Toolbar Remote Commands
+
+本文档说明如何在“工具条端与白板端隔离”的场景下，通过命令控制白板左侧工具能力。
+
+## 适用场景
+
+- 工具条和白板不在同一个组件中
+- 通过 `WebSocket` / `postMessage` / 其他消息通道传 JSON
+- 白板端收到命令后执行，不直接暴露 UI
+
+## 白板端执行入口
+
+白板端拿到 `excalidrawAPI` 后，统一调用：
+
+```ts
+excalidrawAPI.leftToolbar.dispatch(command);
+```
+
+其中 `command` 的类型是 `LeftToolbarCommand`。
+
+## Command 总览
+
+| `type` | 作用 | `payload` |
+| --- | --- | --- |
+| `selectSelection` | 切换到“选择”工具 | 无 |
+| `selectFreedraw` | 切换到“自由书写”工具 | 可选 |
+| `selectLine` | 切换到“线条/箭头”工具组 | 可选 |
+| `selectShape` | 切换到“形状”工具组 | 可选 |
+| `selectText` | 切换到“文字”工具 | 可选 |
+| `selectEraser` | 切换到“橡皮”工具 | 无 |
+| `updateStyle` | 仅更新样式，不切换工具 | 必填 |
+
+---
+
+## 1) `selectSelection`
+
+切换到选择工具。
+
+```json
+{ "type": "selectSelection" }
+```
+
+---
+
+## 2) `selectFreedraw`
+
+切换到自由书写工具（普通画笔/荧光笔）。
+
+### payload 字段
+
+| 字段 | 类型 | 必填 | 含义 |
+| --- | --- | --- | --- |
+| `variant` | `"pen" \| "highlighter"` | 否 | 画笔类型。`pen` 普通笔，`highlighter` 荧光笔（半透明） |
+| `strokeWidth` | `number` | 否 | 线宽 |
+| `strokeColor` | `string` | 否 | 笔颜色（如 `#1677ff`） |
+
+### `variant` 取值对照（freedraw）
+
+| 值 | 含义 |
+| --- | --- |
+| `pen` | 普通画笔（不透明） |
+| `highlighter` | 荧光笔（半透明，适合标注） |
+
+### 示例
+
+```json
+{
+  "type": "selectFreedraw",
+  "payload": {
+    "variant": "highlighter",
+    "strokeWidth": 6,
+    "strokeColor": "#ffcc00"
+  }
+}
+```
+
+---
+
+## 3) `selectLine`
+
+切换到线条/箭头工具组，并可指定箭头类型。
+
+### payload 字段
+
+| 字段 | 类型 | 必填 | 含义 |
+| --- | --- | --- | --- |
+| `variant` | `"line" \| "arrow" \| "doubleArrow" \| "outlineArrow" \| "outlineDoubleArrow"` | 否 | 线条变体：直线、单箭头、双箭头、空心单箭头、空心双箭头 |
+| `strokeWidth` | `number` | 否 | 线宽 |
+| `strokeColor` | `string` | 否 | 线条颜色 |
+
+### `variant` 取值对照（line）
+
+| 值 | 含义 |
+| --- | --- |
+| `line` | 直线 |
+| `arrow` | 实心单箭头 |
+| `doubleArrow` | 实心双箭头 |
+| `outlineArrow` | 空心单箭头 |
+| `outlineDoubleArrow` | 空心双箭头 |
+
+### 示例
+
+```json
+{
+  "type": "selectLine",
+  "payload": {
+    "variant": "outlineDoubleArrow",
+    "strokeWidth": 2,
+    "strokeColor": "#1677ff"
+  }
+}
+```
+
+---
+
+## 4) `selectShape`
+
+切换到形状工具组，并可指定具体形状。
+
+### payload 字段
+
+| 字段 | 类型 | 必填 | 含义 |
+| --- | --- | --- | --- |
+| `shape` | `"rectangle" \| "diamond" \| "ellipse" \| "triangle" \| "pentagon" \| "callout" \| "hollow_arrow" \| "hollow_double_arrow"` | 否 | 具体形状。不传时默认矩形 |
+| `strokeWidth` | `number` | 否 | 描边宽度 |
+| `strokeColor` | `string` | 否 | 描边颜色 |
+| `backgroundColor` | `string` | 否 | 填充背景色 |
+| `fillStyle` | `AppState["currentItemFillStyle"]` | 否 | 填充样式（如 `solid` / `hachure` / `cross-hatch`） |
+
+### `shape` 取值对照
+
+| 值 | 对应图形 |
+| --- | --- |
+| `rectangle` | 矩形 |
+| `diamond` | 菱形 |
+| `ellipse` | 椭圆 |
+| `triangle` | 三角形 |
+| `pentagon` | 五边形 |
+| `callout` | 标注框（气泡） |
+| `hollow_arrow` | 空心单箭头形状 |
+| `hollow_double_arrow` | 空心双箭头形状 |
+
+### `fillStyle` 常见值对照
+
+| 值 | 含义 |
+| --- | --- |
+| `hachure` | 斜线填充 |
+| `cross-hatch` | 交叉线填充 |
+| `solid` | 实心填充 |
+
+### 示例
+
+```json
+{
+  "type": "selectShape",
+  "payload": {
+    "shape": "ellipse",
+    "strokeWidth": 3,
+    "strokeColor": "#1f1f1f",
+    "backgroundColor": "#E6F4FF",
+    "fillStyle": "solid"
+  }
+}
+```
+
+---
+
+## 5) `selectText`
+
+切换到文字工具，并可设置文字默认样式。
+
+### payload 字段
+
+| 字段 | 类型 | 必填 | 含义 |
+| --- | --- | --- | --- |
+| `fontSize` | `number` | 否 | 字号 |
+| `textAlign` | `"left" \| "center" \| "right"` | 否 | 对齐方式 |
+| `strokeColor` | `string` | 否 | 文字颜色 |
+| `bold` | `boolean` | 否 | 是否粗体 |
+| `italic` | `boolean` | 否 | 是否斜体 |
+| `underline` | `boolean` | 否 | 是否下划线 |
+| `strikethrough` | `boolean` | 否 | 是否删除线 |
+
+### `textAlign` 取值对照
+
+| 值 | 含义 |
+| --- | --- |
+| `left` | 左对齐 |
+| `center` | 居中对齐 |
+| `right` | 右对齐 |
+
+### 示例
+
+```json
+{
+  "type": "selectText",
+  "payload": {
+    "fontSize": 24,
+    "textAlign": "center",
+    "strokeColor": "#222222",
+    "bold": true
+  }
+}
+```
+
+---
+
+## 6) `selectEraser`
+
+切换到橡皮工具。
+
+```json
+{ "type": "selectEraser" }
+```
+
+---
+
+## 7) `updateStyle`
+
+只更新样式，不切换当前工具。
+
+### payload 字段（可选子集）
+
+可以传递以下字段中的任意组合：
+
+- `currentItemStrokeColor`
+- `currentItemBackgroundColor`
+- `currentItemFillStyle`
+- `currentItemStrokeWidth`
+- `currentItemOpacity`
+- `currentItemStartArrowhead`
+- `currentItemEndArrowhead`
+- `currentItemFontSize`
+- `currentItemTextAlign`
+- `currentTextBold`
+- `currentTextItalic`
+- `currentTextUnderline`
+- `currentTextStrikethrough`
+
+### `updateStyle` 字段含义对照
+
+| 字段 | 含义 |
+| --- | --- |
+| `currentItemStrokeColor` | 当前工具的描边颜色 |
+| `currentItemBackgroundColor` | 当前工具的填充背景色 |
+| `currentItemFillStyle` | 当前工具的填充样式 |
+| `currentItemStrokeWidth` | 当前工具线宽 |
+| `currentItemOpacity` | 当前工具透明度（0-100） |
+| `currentItemStartArrowhead` | 箭头起点箭头样式 |
+| `currentItemEndArrowhead` | 箭头终点箭头样式 |
+| `currentItemFontSize` | 文字默认字号 |
+| `currentItemTextAlign` | 文字默认对齐方式 |
+| `currentTextBold` | 文字是否粗体 |
+| `currentTextItalic` | 文字是否斜体 |
+| `currentTextUnderline` | 文字是否下划线 |
+| `currentTextStrikethrough` | 文字是否删除线 |
+
+### 示例
+
+```json
+{
+  "type": "updateStyle",
+  "payload": {
+    "currentItemStrokeWidth": 4,
+    "currentItemStrokeColor": "#ff4d4f"
+  }
+}
+```
+
+---
+
+## 接入示例（白板端）
+
+```ts
+socket.on("toolbar-command", (command) => {
+  excalidrawAPI?.leftToolbar.dispatch(command);
+});
+```
+
+## 完整命令 JSON 示例集合
+
+以下示例可直接用于联调（通过 socket 发送）：
+
+### 1) 选择工具
+
+```json
+{ "type": "selectSelection" }
+```
+
+### 2) 自由书写（普通画笔）
+
+```json
+{
+  "type": "selectFreedraw",
+  "payload": {
+    "variant": "pen",
+    "strokeWidth": 2,
+    "strokeColor": "#1677ff"
+  }
+}
+```
+
+### 3) 自由书写（荧光笔）
+
+```json
+{
+  "type": "selectFreedraw",
+  "payload": {
+    "variant": "highlighter",
+    "strokeWidth": 6,
+    "strokeColor": "#ffcc00"
+  }
+}
+```
+
+### 4) 线条（空心双箭头）
+
+```json
+{
+  "type": "selectLine",
+  "payload": {
+    "variant": "outlineDoubleArrow",
+    "strokeWidth": 2,
+    "strokeColor": "#1f1f1f"
+  }
+}
+```
+
+### 5) 形状（椭圆 + 实心填充）
+
+```json
+{
+  "type": "selectShape",
+  "payload": {
+    "shape": "ellipse",
+    "strokeWidth": 3,
+    "strokeColor": "#1f1f1f",
+    "backgroundColor": "#E6F4FF",
+    "fillStyle": "solid"
+  }
+}
+```
+
+### 6) 文字（24号，居中，加粗）
+
+```json
+{
+  "type": "selectText",
+  "payload": {
+    "fontSize": 24,
+    "textAlign": "center",
+    "strokeColor": "#222222",
+    "bold": true
+  }
+}
+```
+
+### 7) 橡皮
+
+```json
+{ "type": "selectEraser" }
+```
+
+### 8) 仅更新样式（不切工具）
+
+```json
+{
+  "type": "updateStyle",
+  "payload": {
+    "currentItemStrokeWidth": 4,
+    "currentItemStrokeColor": "#ff4d4f"
+  }
+}
+```
+
+## 注意事项
+
+- 命令建议使用 JSON 格式，便于跨端传输和记录日志
+- 白板端建议做一次类型校验后再 `dispatch`
+- 建议在“进入注释模式”时再接收命令，退出时解绑监听

package/docs/remote-annotation-integration.mdx

@@ -0,0 +1,170 @@
+# Remote Annotation Integration Guide
+
+本文档用于说明“白板端”和“控制端”完全隔离时，如何通过命令实现远程注释控制。
+
+## 目标
+
+- 白板端只负责渲染 `Excalidraw` 并执行命令
+- 控制端只负责发送工具命令（不直接操作白板实例）
+- 两端通过 `socket`（或其他消息通道）通信
+
+---
+
+## 一、白板端如何接入
+
+白板端核心职责：
+
+1. 挂载 `Excalidraw`，拿到 `excalidrawAPI`
+2. 监听远端命令消息
+3. 收到命令后执行 `excalidrawAPI.leftToolbar.dispatch(command)`
+
+### 示例（React + socket）
+
+```tsx
+import { useEffect, useState } from "react";
+import Excalidraw from "@excalidraw/excalidraw";
+import type {
+  ExcalidrawImperativeAPI,
+  LeftToolbarCommand,
+} from "@excalidraw/excalidraw";
+
+type SocketLike = {
+  on: (event: string, cb: (data: unknown) => void) => void;
+  off: (event: string, cb: (data: unknown) => void) => void;
+};
+
+const isLeftToolbarCommand = (v: unknown): v is LeftToolbarCommand => {
+  if (!v || typeof v !== "object") return false;
+  const type = (v as { type?: unknown }).type;
+  return (
+    typeof type === "string" &&
+    [
+      "selectSelection",
+      "selectFreedraw",
+      "selectLine",
+      "selectShape",
+      "selectText",
+      "selectEraser",
+      "updateStyle",
+    ].includes(type)
+  );
+};
+
+export default function WhiteboardPage({ socket }: { socket: SocketLike }) {
+  const [api, setApi] = useState<ExcalidrawImperativeAPI | null>(null);
+
+  useEffect(() => {
+    const handler = (data: unknown) => {
+      if (!isLeftToolbarCommand(data)) return;
+      api?.leftToolbar.dispatch(data);
+    };
+
+    socket.on("toolbar-command", handler);
+    return () => socket.off("toolbar-command", handler);
+  }, [socket, api]);
+
+  return (
+    <Excalidraw
+      excalidrawAPI={setApi}
+      showToolBar={false}
+      // 透明叠加在 PPT 场景可按需开启：
+      // viewModeEnabled={false}
+    />
+  );
+}
+```
+
+### 白板端注意事项
+
+- 建议对命令先做类型校验再执行
+- 退出注释模式时及时解绑 socket 监听
+- 若需“只读观看模式”，可以结合 `viewModeEnabled`
+
+---
+
+## 二、控制端如何调用命令
+
+控制端核心职责：
+
+1. 监听本地工具条交互（按钮、颜色、线宽、形状等）
+2. 将操作转换成 `LeftToolbarCommand`
+3. 通过 socket 发给白板端
+
+### 示例（发送命令）
+
+```ts
+import type { LeftToolbarCommand } from "@excalidraw/excalidraw";
+
+type SocketLike = {
+  emit: (event: string, data: unknown) => void;
+};
+
+const sendToolbarCommand = (
+  socket: SocketLike,
+  command: LeftToolbarCommand,
+) => {
+  socket.emit("toolbar-command", command);
+};
+
+// 切换到荧光笔
+sendToolbarCommand(socket, {
+  type: "selectFreedraw",
+  payload: { variant: "highlighter", strokeWidth: 6, strokeColor: "#ffcc00" },
+});
+
+// 切换到线条：空心双箭头
+sendToolbarCommand(socket, {
+  type: "selectLine",
+  payload: { variant: "outlineDoubleArrow", strokeWidth: 2, strokeColor: "#1677ff" },
+});
+
+// 切换到形状：椭圆
+sendToolbarCommand(socket, {
+  type: "selectShape",
+  payload: { shape: "ellipse", strokeWidth: 3, strokeColor: "#1f1f1f" },
+});
+
+// 仅更新样式（不切工具）
+sendToolbarCommand(socket, {
+  type: "updateStyle",
+  payload: { currentItemStrokeWidth: 4, currentItemStrokeColor: "#ff4d4f" },
+});
+```
+
+---
+
+## 三、推荐事件约定
+
+建议统一使用一个事件名：
+
+- `toolbar-command`
+
+消息体直接使用 `LeftToolbarCommand` JSON。
+
+这样控制端和白板端都容易调试，也便于后续扩展（录制/回放命令流）。
+
+---
+
+## 四、常见问题
+
+### 1) 为什么控制端不能直接调用白板方法？
+
+因为是跨端隔离部署，控制端拿不到白板实例。必须通过消息通道转发命令。
+
+### 2) 一定要用 socket 吗？
+
+不是。只要能传 JSON 的通道都可以：`WebSocket`、`postMessage`、Electron IPC 等。
+
+### 3) 如何保证命令安全？
+
+- 白板端做类型校验
+- 只允许白名单命令类型
+- 必要时增加鉴权和房间隔离
+
+---
+
+## 五、下一步建议
+
+- 接入日志：记录每次命令时间戳，方便排查问题
+- 接入回放：按命令时间线回放注释过程
+- 接入权限：区分“可控白板”的角色与“只读观众”角色