@8btc/whiteboard 0.0.17 → 0.0.19-beta.0

package/dist/maze.d.ts

@@ -0,0 +1,507 @@
+import { default as default_2 } from 'konva';
+
+/**
+ * 计算内容左下角的插入位置
+ * @param api Canvas API 实例
+ * @returns 插入位置 { x, y }
+ */
+export declare function calculateBottomLeftOfCanvasContent(api: CanvasApi | null | undefined): {
+    x: number;
+    y: number;
+};
+
+/**
+ * CanvasApi 是面向外部使用的公开 API 类
+ * 继承自 CanvasCore，只暴露必要的公开方法
+ */
+declare class CanvasApi extends CanvasCore {
+    /**
+     * 获取所有可用的工具类型
+     */
+    getAvailableTools(): ToolType[];
+    /**
+     * 设置当前工具类型
+     */
+    setToolType(type: ToolType): void;
+    /**
+     * 手动创建多个节点
+     * 如果你不知道自己在干什么，请使用更高层的封装方法，如 createImageNode
+     */
+    createNodes(nodes: INode[], addToHistory: boolean): void;
+    /**
+     * 根据 ID 获取节点
+     */
+    getNodeById<T extends INode = INode>(id: string): T | null;
+    /**
+     * 更新视口位置
+     */
+    updateViewport(viewport: Partial<ICoreState["viewport"]>, addToHistory?: boolean): void;
+    /**
+     * 创建图片节点
+     */
+    createImageNode(imageUrl: string, position?: {
+        x: number;
+        y: number;
+    }): void;
+    /**
+     * 导出全部图形为图片
+     * @param options - 导出配置
+     * @returns DataURL 格式的图片数据
+     */
+    exportAsImage(options?: {
+        pixelRatio?: number;
+        mimeType?: string;
+        quality?: number;
+    }): string;
+    /**
+     * 导出当前选区为图片
+     * @param options - 导出配置
+     * @returns DataURL 格式的图片数据，如果没有选区则返回 null
+     */
+    exportSelectionAsImage(options?: {
+        pixelRatio?: number;
+        mimeType?: string;
+        quality?: number;
+        padding?: number;
+    }): string | null;
+    /**
+     * 导出带有标注的图片节点为图片
+     * @param id - 图片节点 ID
+     * @returns DataURL 格式的图片数据，如果节点或者 marker 不存在则返回 null
+     */
+    exportImageWithMarker(id: string, options?: {
+        pixelRatio?: number;
+        mimeType?: string;
+        quality?: number;
+    }): string | null;
+    /**
+     * 删除当前选中的节点
+     * 如果删除的是 image 节点，会同步删除所有关联的 image-marker
+     */
+    deleteSelectedNodes(): void;
+    /**
+     * 删除指定的节点
+     * 如果删除的是 image 节点，会同步删除所有关联的 image-marker
+     * @param nodeIds - 要删除的节点 ID 数组
+     * @returns 被删除的节点数据数组
+     */
+    deleteNodes(nodeIds: string[]): INode[];
+    /**
+     * 将节点移动到最上层
+     */
+    moveNodesToTop(nodeIds: string[]): void;
+    /**
+     * 将节点移动到最下层
+     */
+    moveNodesToBottom(nodeIds: string[]): void;
+    /**
+     * 滚动到内容区域
+     * - 如果提供了 nodeIds，将指定的节点居中显示
+     * - 如果没有提供 nodeIds 但有选中的节点，将选中节点居中显示
+     * - 如果没有选中节点，将所有内容居中显示
+     * @param options - 配置选项
+     * @param options.padding - 内容周围的留白，默认 50px
+     * @param options.scale - 是否自动调整缩放以适应内容，默认 false
+     * @param options.nodeIds - 要滚动到的节点 ID 数组
+     */
+    scrollToContent(options?: {
+        padding?: number;
+        scale?: boolean;
+        nodeIds?: string[];
+    }): void;
+    /**
+     * 导出当前状态
+     */
+    save(): ICoreState;
+    /**
+     * 从状态中恢复画布
+     */
+    restore(state: ICoreState): void;
+}
+
+declare class CanvasCore extends CanvasState_2 {
+    #private;
+    constructor(el: HTMLDivElement, state?: ICoreState);
+    /**
+     * 获取 CanvasStage 实例
+     */
+    getCanvasStage(): CanvasStage;
+    /**
+     * 获取 CanvasTransformer 实例
+     */
+    getCanvasTransformer(): CanvasTransformer;
+    /**
+     * 获取 Konva.Stage 实例
+     */
+    getStage(): default_2.Stage;
+    /**
+     * 获取 Stage 容器元素
+     */
+    getContainer(): HTMLDivElement;
+    /**
+     * 获取主图层
+     */
+    getMainLayer(): default_2.Layer;
+    /**
+     * 获取当前工具类型
+     */
+    getToolType(): ToolType;
+    /**
+     * 设置当前工具类型（内部使用）
+     */
+    setToolType(type: ToolType): void;
+    /**
+     * 根据 ID 获取 Canvas 节点实例
+     */
+    getCanvasNodeById(id: string): ICanvasNode | null;
+    /**
+     * 设置是否可拖拽（内部使用）
+     */
+    protected setDraggable(draggable: boolean): void;
+    /* Excluded from this release type: _setCursor */
+    /* Excluded from this release type: _resetCursor */
+    /**
+     * 获取当前 Stage 缩放比例
+     */
+    getStageScale(): number;
+    /* Excluded from this release type: _updateViewport */
+    protected createNodes(nodes: INode[], addToHistory: boolean): void;
+    /**
+     * 创建图片标注节点（内部使用）
+     */
+    protected createImageMarkerNode(parentImageId: string, startPosition: {
+        x: number;
+        y: number;
+    }, endPosition: {
+        x: number;
+        y: number;
+    }, imageBounds: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    }): void;
+    /* Excluded from this release type: _findImageAtPosition */
+    /* Excluded from this release type: _setDrawingPosition */
+    /* Excluded from this release type: _updateDrawingPosition */
+    /* Excluded from this release type: _createDraftNode */
+    /* Excluded from this release type: _updateDraftNode */
+    /* Excluded from this release type: _finalizeDraftNode */
+    /* Excluded from this release type: _createSelectRect */
+    _updateSelectRect(): void;
+    /* Excluded from this release type: _finalizeSelectRect */
+    /* Excluded from this release type: _selectNodes */
+    /* Excluded from this release type: deleteNodes */
+    /* Excluded from this release type: deleteSelectedNodes */
+    /**
+     * 销毁 canvas
+     */
+    dispose(): void;
+    /* Excluded from this release type: _rebuildStateAfterNodeChange */
+    /**
+     * 实现父类的状态同步方法
+     * 当 undo/redo 时被调用
+     */
+    protected _renderCanvas(state: ICoreState): void;
+}
+
+/**
+ * CanvasStage 封装了 Konva.Stage 的核心功能
+ * 提供视口管理、事件处理、拖拽和缩放等能力
+ */
+declare class CanvasStage {
+    #private;
+    constructor(core: CanvasCore, config: StageConfig);
+    /**
+     * 获取原生 Konva.Stage 实例
+     */
+    getStage(): default_2.Stage;
+    /**
+     * 获取当前视口状态
+     */
+    getViewport(): ViewportState;
+    /**
+     * 设置视口（包括位置、缩放和尺寸）
+     */
+    setViewport(viewport: Partial<ViewportState>): void;
+    /**
+     * 设置是否可拖拽
+     */
+    setDraggable(draggable: boolean): void;
+    /**
+     * 设置光标样式
+     */
+    setCursor(cursor: string): void;
+    /**
+     * 重置光标样式
+     */
+    resetCursor(): void;
+    /**
+     * 销毁 Stage
+     */
+    destroy(): void;
+}
+
+/**
+ * CanvasState 类负责管理画布的状态
+ * 包括历史记录（past/present/future）和状态监听
+ */
+declare abstract class CanvasState_2 {
+    #private;
+    constructor(initialState: ICoreState);
+    /**
+     * 获取当前状态
+     */
+    getState(): ICoreState;
+    /**
+     * 获取完整历史状态
+     */
+    getHistory(): HistoryState<ICoreState>;
+    /**
+     * 是否可以撤销
+     */
+    canUndo(): boolean;
+    /**
+     * 是否可以重做
+     */
+    canRedo(): boolean;
+    /**
+     * 订阅状态事件
+     */
+    on<K extends keyof StateEvents>(event: K, handler: (data: StateEvents[K]) => void): void;
+    /**
+     * 取消订阅状态事件
+     */
+    off<K extends keyof StateEvents>(event: K, handler: (data: StateEvents[K]) => void): void;
+    /* Excluded from this release type: _emit */
+    /**
+     * 撤销操作
+     */
+    undo(): void;
+    /**
+     * 重做操作
+     */
+    redo(): void;
+    /**
+     * 重置历史记录
+     */
+    resetHistory(): void;
+    /**
+     * 更新状态
+     * @param partial - 部分状态更新
+     * @param addToHistory - 是否添加到历史记录
+     */
+    protected _updateState(partial: Partial<ICoreState>, addToHistory: boolean): void;
+    /**
+     * 同步状态到 canvas 系统（由子类实现）
+     * @param _state - 要同步的状态
+     */
+    protected abstract _renderCanvas(_state: ICoreState): void;
+    /**
+     * 清理资源
+     */
+    protected _dispose(): void;
+}
+
+/**
+ * CanvasTransformer 封装了 Konva.Transformer 的核心功能
+ * 提供变换器管理、位置计算、事件处理等能力
+ */
+declare class CanvasTransformer {
+    #private;
+    constructor(core: CanvasCore, config?: TransformerConfig);
+    /**
+     * 获取原生 Konva.Transformer 实例
+     */
+    getTransformer(): default_2.Transformer;
+    /**
+     * 获取 Transformer 的位置信息
+     */
+    getPosition(): TransformerPosition | null;
+    /**
+     * 设置要变换的节点
+     */
+    setNodes(nodes: default_2.Node[]): void;
+    /**
+     * 获取当前变换的节点
+     */
+    getNodes(): default_2.Node[];
+    /**
+     * 清除所有节点
+     */
+    clearNodes(): void;
+    /**
+     * emit Transformer 位置
+     */
+    emitPositionChange(): void;
+    /**
+     * 销毁 Transformer
+     */
+    destroy(): void;
+}
+
+declare interface CommonNodeConfig<T = NodeType> {
+    $_type: T;
+    $_line?: "solid" | "dashed" | "dotted";
+    $_size?: "small" | "medium" | "large" | "extra-large";
+    $_fill?: "none" | "semi" | "solid";
+    $_animated?: boolean;
+    $_arrowStartHead?: "none" | "arrow";
+    $_arrowEndHead?: "none" | "arrow";
+    $_parentId?: string;
+}
+
+/**
+ * 根据图片标注裁剪图片并返回 base64 字符串
+ * @param api Canvas API 实例
+ * @param imageMarkerNodeId 图片标注节点 ID
+ * @returns Promise<string | null> 裁剪后的图片 base64 字符串，失败返回 null
+ */
+export declare function cropImageBaseOnImageMarker(api: CanvasApi | null | undefined, imageMarkerNodeId: string): Promise<string | null>;
+
+declare type HistoryState<T> = {
+    past: T[];
+    present: T;
+    future: T[];
+};
+
+declare interface ICanvasNode {
+    getID(): string;
+    getElement(): default_2.Shape | default_2.Group;
+    getConfig(): INode;
+    updateNode(node: Partial<INode>): void;
+    destroy(): void;
+}
+
+declare interface ICoreState {
+    viewport: IViewport;
+    toolType: ToolType;
+    selectedNodeIds?: string[];
+    nodes?: INode[];
+}
+
+declare interface INode<T = NodeType> extends default_2.ShapeConfig, CommonNodeConfig<T> {
+    id: string;
+    x: number;
+    y: number;
+    $_imageUrl?: string;
+    $_markerNumber?: number;
+    $_bounds?: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+    $_relativeBox?: {
+        start: {
+            ratioX: number;
+            ratioY: number;
+        };
+        end: {
+            ratioX: number;
+            ratioY: number;
+        };
+    };
+}
+
+/**
+ * 在当前 canvas 内容左下角插入图片节点
+ * @param api Canvas API 实例
+ * @param imageUrl 图片 URL 或 URL 数组
+ * @returns Promise<string[] | undefined> 返回插入的图片节点 ID 数组
+ */
+export declare function insertImageBesideContent(api: CanvasApi | null | undefined, imageUrl: string | string[]): Promise<string[] | undefined>;
+
+/**
+ * 在指定位置插入图片节点
+ * @param api Canvas API 实例
+ * @param imageUrls 图片 URL 或 URL 数组
+ * @param position 插入位置 { x, y }
+ * @param options 可选配置
+ * @returns Promise<string[] | undefined> 返回插入的图片节点 ID 数组
+ */
+export declare function insertImagesAtPosition(api: CanvasApi | null | undefined, imageUrls: string | string[], position: {
+    x: number;
+    y: number;
+}, options?: {
+    spacing?: number;
+    scrollToView?: boolean;
+    direction?: "horizontal" | "vertical";
+}): Promise<string[] | undefined>;
+
+/**
+ * 在当前选中节点右侧插入 loading 图片节点
+ * @param api Canvas API 实例
+ * @param imageUrl 图片 URL
+ * @returns string | undefined 返回插入的 loading 图片节点 ID，如果未插入则返回 undefined
+ */
+export declare function insertLoadingImageBesideSelection(api: CanvasApi | null | undefined, imageUrl: string): string | undefined;
+
+declare interface IViewport {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    scale: number;
+}
+
+declare type NodeType = "rectangle" | "image" | "image-marker";
+
+export declare function replaceLoadingImageNode(api: CanvasApi | null | undefined, loadingNodeId: string, imageUrls: string | string[]): void;
+
+declare type StageConfig = {
+    container: HTMLDivElement;
+    width: number;
+    height: number;
+    draggable?: boolean;
+    className?: string;
+};
+
+/**
+ * 状态事件类型定义
+ */
+declare type StateEvents = {
+    "state:change": ICoreState;
+    "state:undo": ICoreState;
+    "state:redo": ICoreState;
+    "state:reset": ICoreState;
+    "viewport:change": ICoreState["viewport"];
+    "viewport:scale:change": number;
+    "transformer:positionChange": TransformerPosition | null;
+    "toolType:change": ICoreState["toolType"];
+    "nodes:created": INode[];
+    "nodes:deleted": INode[];
+    "nodes:selected": string[];
+};
+
+declare type ToolType = "select" | "hand" | "rectangle" | "image-marker";
+
+declare type TransformerConfig = {
+    rotateEnabled?: boolean;
+    ignoreStroke?: boolean;
+    anchorSize?: number;
+    borderDash?: number[];
+    anchorCornerRadius?: number;
+    padding?: number;
+};
+
+/**
+ * 变换器（Transformer）位置信息
+ */
+declare interface TransformerPosition {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    rotation?: number;
+}
+
+declare type ViewportState = {
+    x: number;
+    y: number;
+    scale: number;
+    width?: number;
+    height?: number;
+};
+
+export { }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@8btc/whiteboard",
   "private": false,
-  "version": "0.0.17",
+  "version": "0.0.19-beta.0",
   "type": "module",
   "main": "./dist/index.umd.js",
   "module": "./dist/index.js",
@@ -9,8 +9,11 @@
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
-      "import": "./dist/index.js",
-      "require": "./dist/index.umd.js"
+      "import": "./dist/index.js"
+    },
+    "./adapter/maze": {
+      "types": "./dist/maze.d.ts",
+      "import": "./dist/adapter/maze.js"
     }
   },
   "files": [
@@ -25,7 +28,8 @@
     "lint": "eslint .",
     "preview": "vite preview",
     "prepublishOnly": "pnpm build",
-    "release": "pnpm build && npm publish --access public"
+    "release": "pnpm build && npm publish --access public",
+    "release:beta": "pnpm build && npm publish --access public --tag beta"
   },
   "peerDependencies": {
     "react": "^18.0.0 || ^19.0.0",