goatdee-canvas 0.0.1

package/dist/index.d.ts

@@ -0,0 +1,1250 @@
+import React from 'react';
+
+/**
+ * 画布支持的元素类型。
+ * @category 数据
+ */
+type CanvasElementType = 'textbox' | 'image' | 'circle' | 'rectangle' | 'triangle' | 'group' | 'frame' | 'slide' | 'path';
+/**
+ * 线性渐变配置。
+ * @category 样式
+ */
+interface CanvasLinearGradient {
+    /** 固定值 'linear' */
+    type: "linear";
+    /** 渐变起止坐标（相对元素宽高的 0–1 比例），x1/y1 为起点，x2/y2 为终点 */
+    coords: {
+        x1: number;
+        y1: number;
+        x2: number;
+        y2: number;
+    };
+    /** 色标数组，每项包含 offset（位置 0–1）和 color（颜色字符串如 'rgba(255,0,0,1)'） */
+    colorStops: {
+        offset: number;
+        color: string;
+    }[];
+}
+/**
+ * 填充值：纯色字符串（如 '#ff0000'、'rgba(0,0,0,0.5)'）或线性渐变对象；null 表示不填充。
+ * @category 样式
+ */
+type CanvasFill = string | CanvasLinearGradient | null;
+/**
+ * 描边值：与填充格式一致——纯色字符串或线性渐变对象；null 表示不描边。
+ * @category 样式
+ */
+type CanvasStroke = string | CanvasLinearGradient | null;
+/**
+ * 阴影配置。
+ * @category 样式
+ */
+interface CanvasShadow {
+    /** 模糊半径 */
+    blur: number;
+    /** 颜色字符串，如 'rgba(0,0,0,0.5)' */
+    color: string;
+    /** X 偏移 */
+    offsetX: number;
+    /** Y 偏移 */
+    offsetY: number;
+}
+/**
+ * 画布完整数据，用于 loadFromJSON / exportToJSON。
+ * @category 数据
+ */
+interface CanvasData {
+    /** 画布宽度 */
+    width: number;
+    /** 画布高度 */
+    height: number;
+    /** 缩略图 */
+    thumb?: string;
+    /** 对象列表 */
+    objects: CanvasObjectData[];
+}
+/**
+ * 粘贴操作的返回结果。
+ * @category 数据
+ */
+interface PasteResult {
+    /** 粘贴的元素数量，-1 表示使用了内部粘贴（无法确定具体数量） */
+    count: number;
+    /** 提示信息，例如不支持的文件类型 */
+    message?: string;
+}
+/**
+ * 文本对象。
+ * @category 对象类型
+ */
+interface CanvasTextboxObject {
+    /** 对象类型标识 */
+    type: "textbox";
+    /** 唯一 ID。默认 '' */
+    id: string;
+    /** 对象名称。默认 '' */
+    name?: string;
+    /** X 坐标。默认 0 */
+    left?: number;
+    /** Y 坐标。默认 0 */
+    top?: number;
+    /** 宽度。默认 0 */
+    width?: number;
+    /** 高度。默认 0 */
+    height?: number;
+    /** X 缩放。默认 1 */
+    scaleX?: number;
+    /** Y 缩放。默认 1 */
+    scaleY?: number;
+    /** 旋转角度（度）。默认 0 */
+    angle?: number;
+    /** 描边宽度。默认 0 */
+    strokeWidth?: number;
+    /** 不透明度 0–1。默认 1 */
+    opacity?: number;
+    /** 是否可见。默认 true */
+    visible?: boolean;
+    /** 是否锁定。默认 false */
+    locked?: boolean;
+    /** 锁定水平移动。默认 false */
+    lockMovementX?: boolean;
+    /** 锁定垂直移动。默认 false */
+    lockMovementY?: boolean;
+    /** 锁定旋转。默认 false */
+    lockRotation?: boolean;
+    /** 锁定水平缩放。默认 false */
+    lockScalingX?: boolean;
+    /** 锁定垂直缩放。默认 false */
+    lockScalingY?: boolean;
+    /** 锁定等比缩放。默认 true */
+    lockUniScaling?: boolean;
+    /** 是否可选中。默认 true */
+    selectable?: boolean;
+    /** 文本内容。默认 '输入文本' */
+    text?: string;
+    /** 字号。默认 32 */
+    fontSize?: number;
+    /** 行高，0 表示自动。默认 0 */
+    lineHeight?: number;
+    /** 字体名称。默认 'SourceHanSansCN-Normal' */
+    fontFamily?: string;
+    /** 填充（纯色字符串或渐变对象）。默认黑色 */
+    fill?: CanvasFill;
+    /** 描边（纯色字符串或渐变对象）。默认黑色 */
+    stroke?: CanvasStroke;
+    /** 阴影。默认 - */
+    shadow?: CanvasShadow;
+    /** 水平对齐：'left'、'center'、'right'。默认 'left' */
+    textAlign?: string;
+    /** 字符间距（千分之一 em）。默认 0 */
+    charSpacing?: number;
+    /** 下划线。默认 false */
+    underline?: boolean;
+    /** 删除线。默认 false */
+    linethrough?: boolean;
+    /** 粗体。默认 false */
+    bold?: boolean;
+    /** 斜体。默认 false */
+    italic?: boolean;
+    /** 富文本样式（按字符/段落的样式覆盖）。默认 - */
+    styles?: unknown;
+    /** 是否可编辑。默认 true */
+    editable?: boolean;
+}
+/**
+ * 图片对象。
+ * @category 对象类型
+ */
+interface CanvasImageObject {
+    /** 对象类型标识 */
+    type: "image";
+    /** 唯一 ID。默认 '' */
+    id: string;
+    /** 对象名称。默认 '' */
+    name?: string;
+    /** X 坐标。默认 0 */
+    left?: number;
+    /** Y 坐标。默认 0 */
+    top?: number;
+    /** 宽度。默认 0 */
+    width?: number;
+    /** 高度。默认 0 */
+    height?: number;
+    /** X 缩放。默认 1 */
+    scaleX?: number;
+    /** Y 缩放。默认 1 */
+    scaleY?: number;
+    /** 旋转角度（度）。默认 0 */
+    angle?: number;
+    /** 描边宽度。默认 0 */
+    strokeWidth?: number;
+    /** 不透明度 0–1。默认 1 */
+    opacity?: number;
+    /** 是否可见。默认 true */
+    visible?: boolean;
+    /** 是否锁定。默认 false */
+    locked?: boolean;
+    /** 锁定水平移动。默认 false */
+    lockMovementX?: boolean;
+    /** 锁定垂直移动。默认 false */
+    lockMovementY?: boolean;
+    /** 锁定旋转。默认 false */
+    lockRotation?: boolean;
+    /** 锁定水平缩放。默认 false */
+    lockScalingX?: boolean;
+    /** 锁定垂直缩放。默认 false */
+    lockScalingY?: boolean;
+    /** 锁定等比缩放。默认 true */
+    lockUniScaling?: boolean;
+    /** 是否可选中。默认 true */
+    selectable?: boolean;
+    /** 图片地址。默认 '' */
+    src?: string;
+    /** 适配方式：`fill`、`contain`、`cover`、`none`、`scale-down`。默认 'fill' */
+    objectFit?: string;
+    /** 裁切偏移 X。默认 0 */
+    cropX?: number;
+    /** 裁切偏移 Y。默认 0 */
+    cropY?: number;
+    /** 是否加载中。默认 false */
+    loading?: boolean;
+    /** 圆角 X。默认 0 */
+    rx?: number;
+    /** 圆角 Y。默认 0 */
+    ry?: number;
+    /** 背景色（纯色字符串或渐变对象）。默认 - */
+    backgroundColor?: CanvasFill;
+    /** 描边（纯色字符串或渐变对象）。默认 - */
+    stroke?: CanvasStroke;
+    /** 阴影。默认 - */
+    shadow?: CanvasShadow;
+}
+/**
+ * 圆形对象。
+ * @category 对象类型
+ */
+interface CanvasCircleObject {
+    /** 对象类型标识 */
+    type: "circle";
+    /** 唯一 ID。默认 '' */
+    id: string;
+    /** 对象名称。默认 '' */
+    name?: string;
+    /** X 坐标。默认 0 */
+    left?: number;
+    /** Y 坐标。默认 0 */
+    top?: number;
+    /** 宽度（等于 radius × 2）。默认 0 */
+    width?: number;
+    /** 高度（等于 radius × 2）。默认 0 */
+    height?: number;
+    /** X 缩放。默认 1 */
+    scaleX?: number;
+    /** Y 缩放。默认 1 */
+    scaleY?: number;
+    /** 旋转角度（度）。默认 0 */
+    angle?: number;
+    /** 描边宽度。默认 0 */
+    strokeWidth?: number;
+    /** 不透明度 0–1。默认 1 */
+    opacity?: number;
+    /** 是否可见。默认 true */
+    visible?: boolean;
+    /** 是否锁定。默认 false */
+    locked?: boolean;
+    /** 锁定水平移动。默认 false */
+    lockMovementX?: boolean;
+    /** 锁定垂直移动。默认 false */
+    lockMovementY?: boolean;
+    /** 锁定旋转。默认 false */
+    lockRotation?: boolean;
+    /** 锁定水平缩放。默认 false */
+    lockScalingX?: boolean;
+    /** 锁定垂直缩放。默认 false */
+    lockScalingY?: boolean;
+    /** 锁定等比缩放。默认 true */
+    lockUniScaling?: boolean;
+    /** 是否可选中。默认 true */
+    selectable?: boolean;
+    /** 填充（纯色字符串或渐变对象）。默认 - */
+    fill?: CanvasFill;
+    /** 描边（纯色字符串或渐变对象）。默认 - */
+    stroke?: CanvasStroke;
+    /** 阴影。默认 - */
+    shadow?: CanvasShadow;
+    /** 虚线长度数组，如 \[5, 3\]。默认 [] */
+    borderDashArray?: number[];
+    /** 半径。默认 50 */
+    radius?: number;
+}
+/**
+ * 矩形对象。
+ * @category 对象类型
+ */
+interface CanvasRectangleObject {
+    /** 对象类型标识 */
+    type: "rectangle";
+    /** 唯一 ID。默认 '' */
+    id: string;
+    /** 对象名称。默认 '' */
+    name?: string;
+    /** X 坐标。默认 0 */
+    left?: number;
+    /** Y 坐标。默认 0 */
+    top?: number;
+    /** 宽度。默认 0 */
+    width?: number;
+    /** 高度。默认 0 */
+    height?: number;
+    /** X 缩放。默认 1 */
+    scaleX?: number;
+    /** Y 缩放。默认 1 */
+    scaleY?: number;
+    /** 旋转角度（度）。默认 0 */
+    angle?: number;
+    /** 描边宽度。默认 0 */
+    strokeWidth?: number;
+    /** 不透明度 0–1。默认 1 */
+    opacity?: number;
+    /** 是否可见。默认 true */
+    visible?: boolean;
+    /** 是否锁定。默认 false */
+    locked?: boolean;
+    /** 锁定水平移动。默认 false */
+    lockMovementX?: boolean;
+    /** 锁定垂直移动。默认 false */
+    lockMovementY?: boolean;
+    /** 锁定旋转。默认 false */
+    lockRotation?: boolean;
+    /** 锁定水平缩放。默认 false */
+    lockScalingX?: boolean;
+    /** 锁定垂直缩放。默认 false */
+    lockScalingY?: boolean;
+    /** 锁定等比缩放。默认 false */
+    lockUniScaling?: boolean;
+    /** 是否可选中。默认 true */
+    selectable?: boolean;
+    /** 填充（纯色字符串或渐变对象）。默认 - */
+    fill?: CanvasFill;
+    /** 描边（纯色字符串或渐变对象）。默认 - */
+    stroke?: CanvasStroke;
+    /** 阴影。默认 - */
+    shadow?: CanvasShadow;
+    /** 虚线长度数组。默认 [] */
+    borderDashArray?: number[];
+    /** 圆角 X。默认 0 */
+    rx?: number;
+    /** 圆角 Y。默认 0 */
+    ry?: number;
+}
+/**
+ * 三角形对象。
+ * @category 对象类型
+ */
+interface CanvasTriangleObject {
+    /** 对象类型标识 */
+    type: "triangle";
+    /** 唯一 ID。默认 '' */
+    id: string;
+    /** 对象名称。默认 '' */
+    name?: string;
+    /** X 坐标。默认 0 */
+    left?: number;
+    /** Y 坐标。默认 0 */
+    top?: number;
+    /** 宽度。默认 0 */
+    width?: number;
+    /** 高度。默认 0 */
+    height?: number;
+    /** X 缩放。默认 1 */
+    scaleX?: number;
+    /** Y 缩放。默认 1 */
+    scaleY?: number;
+    /** 旋转角度（度）。默认 0 */
+    angle?: number;
+    /** 描边宽度。默认 0 */
+    strokeWidth?: number;
+    /** 不透明度 0–1。默认 1 */
+    opacity?: number;
+    /** 是否可见。默认 true */
+    visible?: boolean;
+    /** 是否锁定。默认 false */
+    locked?: boolean;
+    /** 锁定水平移动。默认 false */
+    lockMovementX?: boolean;
+    /** 锁定垂直移动。默认 false */
+    lockMovementY?: boolean;
+    /** 锁定旋转。默认 false */
+    lockRotation?: boolean;
+    /** 锁定水平缩放。默认 false */
+    lockScalingX?: boolean;
+    /** 锁定垂直缩放。默认 false */
+    lockScalingY?: boolean;
+    /** 锁定等比缩放。默认 false */
+    lockUniScaling?: boolean;
+    /** 是否可选中。默认 true */
+    selectable?: boolean;
+    /** 填充（纯色字符串或渐变对象）。默认 - */
+    fill?: CanvasFill;
+    /** 描边（纯色字符串或渐变对象）。默认 - */
+    stroke?: CanvasStroke;
+    /** 阴影。默认 - */
+    shadow?: CanvasShadow;
+    /** 虚线长度数组。默认 [] */
+    borderDashArray?: number[];
+}
+/**
+ * 组对象（多个对象成组）。
+ * @category 对象类型
+ */
+interface CanvasGroupObject {
+    /** 对象类型标识 */
+    type: "group";
+    /** 唯一 ID。默认 '' */
+    id: string;
+    /** 对象名称。默认 '' */
+    name?: string;
+    /** X 坐标。默认 0 */
+    left?: number;
+    /** Y 坐标。默认 0 */
+    top?: number;
+    /** 宽度。默认 0 */
+    width?: number;
+    /** 高度。默认 0 */
+    height?: number;
+    /** X 缩放。默认 1 */
+    scaleX?: number;
+    /** Y 缩放。默认 1 */
+    scaleY?: number;
+    /** 旋转角度（度）。默认 0 */
+    angle?: number;
+    /** 描边宽度。默认 0 */
+    strokeWidth?: number;
+    /** 不透明度 0–1。默认 1 */
+    opacity?: number;
+    /** 是否可见。默认 true */
+    visible?: boolean;
+    /** 是否锁定。默认 false */
+    locked?: boolean;
+    /** 锁定水平移动。默认 false */
+    lockMovementX?: boolean;
+    /** 锁定垂直移动。默认 false */
+    lockMovementY?: boolean;
+    /** 锁定旋转。默认 false */
+    lockRotation?: boolean;
+    /** 锁定水平缩放。默认 false */
+    lockScalingX?: boolean;
+    /** 锁定垂直缩放。默认 false */
+    lockScalingY?: boolean;
+    /** 锁定等比缩放。默认 true */
+    lockUniScaling?: boolean;
+    /** 是否可选中。默认 true */
+    selectable?: boolean;
+    /** 子对象列表 */
+    objects?: CanvasObjectData[];
+}
+/**
+ * 画框对象（可包含子元素、裁切内容）。
+ * @category 对象类型
+ */
+interface CanvasFrameObject {
+    /** 对象类型标识 */
+    type: "frame";
+    /** 唯一 ID。默认 '' */
+    id: string;
+    /** 对象名称。默认 '' */
+    name?: string;
+    /** X 坐标。默认 0 */
+    left?: number;
+    /** Y 坐标。默认 0 */
+    top?: number;
+    /** 宽度。默认 0 */
+    width?: number;
+    /** 高度。默认 0 */
+    height?: number;
+    /** X 缩放。默认 1 */
+    scaleX?: number;
+    /** Y 缩放。默认 1 */
+    scaleY?: number;
+    /** 旋转角度（度）。默认 0 */
+    angle?: number;
+    /** 描边宽度。默认 0 */
+    strokeWidth?: number;
+    /** 不透明度 0–1。默认 1 */
+    opacity?: number;
+    /** 是否可见。默认 true */
+    visible?: boolean;
+    /** 是否锁定。默认 false */
+    locked?: boolean;
+    /** 锁定水平移动。默认 false */
+    lockMovementX?: boolean;
+    /** 锁定垂直移动。默认 false */
+    lockMovementY?: boolean;
+    /** 锁定旋转。默认 true */
+    lockRotation?: boolean;
+    /** 锁定水平缩放。默认 false */
+    lockScalingX?: boolean;
+    /** 锁定垂直缩放。默认 false */
+    lockScalingY?: boolean;
+    /** 锁定等比缩放。默认 false */
+    lockUniScaling?: boolean;
+    /** 是否可选中。默认 true */
+    selectable?: boolean;
+    /** 背景色（纯色字符串或渐变对象）。默认白色 */
+    backgroundColor?: CanvasFill;
+    /** 描边（纯色字符串或渐变对象）。默认 - */
+    stroke?: CanvasStroke;
+    /** 背景是否跟随缩放。默认 true */
+    autoScaleBg?: boolean;
+    /** 是否允许跨层拖入。默认 true */
+    crossable?: boolean;
+    /** 是否裁切溢出内容。默认 true */
+    clipContent?: boolean;
+    /** 是否显示名称标签。默认 true */
+    showName?: boolean;
+    /** 是否显示尺寸标签。默认 true */
+    showSize?: boolean;
+    /** 子对象列表 */
+    objects?: CanvasObjectData[];
+}
+/**
+ * 幻灯片容器对象。
+ * @category 对象类型
+ */
+interface CanvasSlideObject {
+    /** 对象类型标识 */
+    type: "slide";
+    /** 唯一 ID。默认 '' */
+    id: string;
+    /** 对象名称。默认 '' */
+    name?: string;
+    /** X 坐标。默认 0 */
+    left?: number;
+    /** Y 坐标。默认 0 */
+    top?: number;
+    /** 宽度。默认 0 */
+    width?: number;
+    /** 高度。默认 0 */
+    height?: number;
+    /** X 缩放。默认 1 */
+    scaleX?: number;
+    /** Y 缩放。默认 1 */
+    scaleY?: number;
+    /** 旋转角度（度）。默认 0 */
+    angle?: number;
+    /** 描边宽度。默认 0 */
+    strokeWidth?: number;
+    /** 不透明度 0–1。默认 1 */
+    opacity?: number;
+    /** 是否可见。默认 true */
+    visible?: boolean;
+    /** 是否锁定。默认 false */
+    locked?: boolean;
+    /** 锁定水平移动。默认 false */
+    lockMovementX?: boolean;
+    /** 锁定垂直移动。默认 false */
+    lockMovementY?: boolean;
+    /** 锁定旋转。默认 true */
+    lockRotation?: boolean;
+    /** 锁定水平缩放。默认 true */
+    lockScalingX?: boolean;
+    /** 锁定垂直缩放。默认 true */
+    lockScalingY?: boolean;
+    /** 锁定等比缩放。默认 true */
+    lockUniScaling?: boolean;
+    /** 是否可选中。默认 true */
+    selectable?: boolean;
+    /** 背景色（纯色字符串或渐变对象）。默认白色 */
+    backgroundColor?: CanvasFill;
+    /** 描边（纯色字符串或渐变对象）。默认 - */
+    stroke?: CanvasStroke;
+    /** 内容区域背景色。默认白色 */
+    contentBackgroundColor?: CanvasFill;
+    /** 内容区域描边宽度。默认 0 */
+    contentStrokeWidth?: number;
+    /** 内容区域描边。默认 - */
+    contentStroke?: CanvasStroke;
+    /** 水平内边距。默认 0 */
+    paddingX?: number;
+    /** 垂直内边距。默认 0 */
+    paddingY?: number;
+    /** 圆角 X。默认 0 */
+    rx?: number;
+    /** 圆角 Y。默认 0 */
+    ry?: number;
+    /** 是否允许跨层拖入。默认 true */
+    crossable?: boolean;
+    /** 是否显示名称标签。默认 true */
+    showName?: boolean;
+    /** 是否显示尺寸标签。默认 true */
+    showSize?: boolean;
+    /** 子对象列表 */
+    objects?: CanvasObjectData[];
+}
+/**
+ * 占位对象（内部 overlay 等使用，不对外暴露）。
+ * @internal
+ */
+interface CanvasPlaceholderObject {
+    /** 对象类型标识 */
+    type: "placeholder";
+    /** 唯一 ID。默认 '' */
+    id: string;
+    /** 对象名称。默认 '' */
+    name?: string;
+    /** X 坐标。默认 0 */
+    left?: number;
+    /** Y 坐标。默认 0 */
+    top?: number;
+    /** 宽度。默认 0 */
+    width?: number;
+    /** 高度。默认 0 */
+    height?: number;
+    /** 是否参与导出。默认 false */
+    export?: boolean;
+    /** 是否锁定。默认 false */
+    locked?: boolean;
+    /** 锁定水平移动。默认 true */
+    lockMovementX?: boolean;
+    /** 锁定垂直移动。默认 true */
+    lockMovementY?: boolean;
+    /** 锁定旋转。默认 true */
+    lockRotation?: boolean;
+    /** 锁定水平缩放。默认 true */
+    lockScalingX?: boolean;
+    /** 锁定垂直缩放。默认 true */
+    lockScalingY?: boolean;
+    /** 锁定等比缩放。默认 true */
+    lockUniScaling?: boolean;
+    /** 是否可选中。默认 false */
+    selectable?: boolean;
+    /** 是否可见。默认 true */
+    visible?: boolean;
+}
+/**
+ * 路径（折线/曲线）对象。
+ * @category 对象类型
+ */
+interface CanvasPathObject {
+    /** 对象类型标识 */
+    type: "path";
+    /** 唯一 ID。默认 '' */
+    id: string;
+    /** 对象名称。默认 '' */
+    name?: string;
+    /** X 坐标。默认 0 */
+    left?: number;
+    /** Y 坐标。默认 0 */
+    top?: number;
+    /** 宽度。默认 0 */
+    width?: number;
+    /** 高度。默认 0 */
+    height?: number;
+    /** X 缩放。默认 1 */
+    scaleX?: number;
+    /** Y 缩放。默认 1 */
+    scaleY?: number;
+    /** 旋转角度（度）。默认 0 */
+    angle?: number;
+    /** 描边宽度。默认 0 */
+    strokeWidth?: number;
+    /** 不透明度 0–1。默认 1 */
+    opacity?: number;
+    /** 是否可见。默认 true */
+    visible?: boolean;
+    /** 是否锁定。默认 false */
+    locked?: boolean;
+    /** 锁定水平移动。默认 false */
+    lockMovementX?: boolean;
+    /** 锁定垂直移动。默认 false */
+    lockMovementY?: boolean;
+    /** 锁定旋转。默认 false */
+    lockRotation?: boolean;
+    /** 锁定水平缩放。默认 false */
+    lockScalingX?: boolean;
+    /** 锁定垂直缩放。默认 false */
+    lockScalingY?: boolean;
+    /** 锁定等比缩放。默认 true */
+    lockUniScaling?: boolean;
+    /** 是否可选中。默认 true */
+    selectable?: boolean;
+    /** 描边（纯色字符串或渐变对象）。默认黑色 */
+    stroke?: CanvasStroke;
+    /** 路径顶点 \[x, y\][] */
+    points?: [number, number][];
+}
+/**
+ * grid / line / grid-cell（暂不展开字段）。
+ * @internal
+ */
+interface CanvasGridLineCellLoose {
+    type: "grid" | "line" | "grid-cell";
+    id: string;
+    objects?: CanvasObjectData[];
+    src?: string;
+    [key: string]: unknown;
+}
+/**
+ * 画布中单个对象的数据（由 `type` 字段区分具体类型）。
+ * @category 数据
+ */
+type CanvasObjectData = CanvasTextboxObject | CanvasImageObject | CanvasCircleObject | CanvasRectangleObject | CanvasTriangleObject | CanvasGroupObject | CanvasFrameObject | CanvasSlideObject | CanvasPlaceholderObject | CanvasPathObject | CanvasGridLineCellLoose;
+/**
+ * 画布组件 props。
+ * @category 组件
+ */
+interface CanvasProps {
+    /**
+     * 画布内部事件回调。`action` / `data` 见 {@link CanvasOnActionEventMap}。
+     */
+    onAction?: (action: string, data?: unknown) => void;
+    /** 画布与 WASM 初始化完成回调 */
+    onLoad?: () => void;
+    /** 图片上传接口 URL */
+    uploadAction?: string;
+    /** 图片上传请求头 */
+    uploadHeader?: Record<string, string>;
+    /**
+     * 画布 overlay DOM 插槽（内部使用）。
+     * @internal
+     */
+    renderOverlay?: () => any;
+}
+/**
+ * **`onAction` 的 action 与 data 对照**。
+ *
+ * 下表为`action`和`data`的有效取值，无载荷时为 `null`。
+ *
+ * | action | data 说明 |
+ * |--------|-----------|
+ * | `afterrender` | 每帧绘制结束；无 `data` |
+ * | `loaded` | `loadFromJSON` 完成并清空剪贴板后；无 `data` |
+ * | `select` | 当前选中对象列表，与 `getActiveObjects()` 相同结构 |
+ * | `pan` | 画布偏移 `{ offsetX, offsetY }`（屏幕逻辑坐标） |
+ * | `scale` | 当前画布缩放系数 `number` |
+ * | `dblclick` | 双击目标对象（多为 textbox）的序列化数据，单对象 |
+ * | `add` | 绘制完成后的新建元素 JSON（已转为屏幕坐标） |
+ * | `remove` | 被删元素：单个为对象；多选批量删除为对象数组 |
+ * | `unmark` | 取消图片标注 `{ id, index }` |
+ * | `drop` | 拖拽放置结束；`null` |
+ * | `paste` | 粘贴后的对象 JSON 数组 |
+ * | `undo` | 是否仍可撤销 `boolean`（`history.canUndo()`） |
+ * | `redo` | 是否仍可重做 `boolean` |
+ * | `group` | 成组结果对象 JSON；失败时可能含 `message` |
+ * | `ungroup` | 取消成组后；一般无 `data` |
+ * | `move` | 键盘方向键移动：选中子元素数组；鼠标拖拽结束：当前选中解析后的列表 |
+ * | `scale element` | 缩放控制点拖拽过程中：当前选中对象列表 |
+ * | `editing` | 文本编辑时文本框图层 JSON（屏幕坐标） |
+ * | `mark` | 新增标注：`{ x, y, index, object }`；超限则 `index: -1` 且含 `message` |
+ * | `activate mark` / `deactivate mark` | `{ id, index }`（图片 id 与标注序号） |
+ * | `click` | 网格单元格点击（内部）；含点击相关字段 |
+ *
+ * @category 组件
+ */
+type CanvasOnActionEventMap = never;
+/**
+ * 画布 ref 暴露的方法，与包导出的函数一一对应。
+ * @internal
+ */
+interface CanvasRef {
+    pan: (deltaX: number, deltaY: number) => void;
+    scale: (scale: number, x: number, y: number) => void;
+    centerObjects: (ids: string[], duration?: number) => void;
+    fitToScreen: (screen?: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    }) => void;
+    worldToCanvas: (x: number, y: number) => {
+        x: number;
+        y: number;
+    } | null;
+    canvasToWorld: (x: number, y: number) => {
+        x: number;
+        y: number;
+    } | null;
+    getScale: () => number;
+    getActiveObjects: () => CanvasObjectData[] | null;
+    getObject: (id: string) => CanvasObjectData | null;
+    getBounds: () => {
+        left: number;
+        top: number;
+        width: number;
+        height: number;
+    } | null;
+    setObjectProperties: (id: string, properties: Record<string, any>) => Promise<void>;
+    registerFonts: (fonts: {
+        fontName: string;
+        url: string;
+    }[]) => Promise<void>;
+    switchToCreatingElement: (creating: boolean, type?: CanvasElementType | '', options?: Record<string, any>) => Promise<void>;
+    unmark: (id: string, index: number) => void;
+    add: (type: CanvasElementType, properties: Record<string, any>) => Promise<string | null>;
+    copy: () => Promise<void>;
+    paste: (x: number, y: number, clipboardEvent?: ClipboardEvent) => Promise<PasteResult>;
+    cut: () => Promise<void>;
+    remove: (id?: string) => void;
+    select: (ids: string[]) => void;
+    canUndo: () => boolean;
+    canRedo: () => boolean;
+    undo: () => void;
+    redo: () => void;
+    getParentLayer: (id: string) => string;
+    getIndex: (id: string) => number;
+    moveUp: (id: string) => void;
+    moveDown: (id: string) => void;
+    moveTo: (parentId: string, index: number) => void;
+    bringToFront: (id: string) => void;
+    sendToBack: (id: string) => void;
+    canGroup: (ids: string[]) => boolean;
+    group: (ids: string[]) => string | null;
+    ungroup: (id: string) => void;
+    align: (alignment: "left" | "right" | "top" | "bottom" | "center" | "middle") => void;
+    arrange: (arrangement: 'horizontal' | 'vertical' | 'auto') => void;
+    switchToPan: (isPan: boolean) => void;
+    loadFromJSON: (json: CanvasData) => Promise<void>;
+    addFabricJSON: (fabricJSON: Record<string, any>, x?: number, y?: number) => Promise<string | null>;
+    exportToJSON: () => CanvasData | null;
+    exportImage: (type?: string, multiple?: number, quality?: number) => string | string[] | null;
+    refreshOverlay?: () => void;
+}
+
+/**
+ * 画布 React 组件，通过 ref 调用画布方法。
+ * @internal 不纳入 API 文档，仅作为组件使用
+ */
+declare const GoatdeeCanvas: React.ForwardRefExoticComponent<CanvasProps & React.RefAttributes<CanvasRef>>;
+
+/**
+ * 平移画布。
+ * @category 画布操作
+ * @param deltaX - 水平偏移量（像素），正值向右
+ * @param deltaY - 垂直偏移量（像素），正值向下
+ */
+declare const pan: (deltaX: number, deltaY: number) => void;
+/**
+ * 缩放画布。
+ * @category 画布操作
+ * @param scale - 目标缩放倍数
+ * @param x - 缩放中心 X（画布坐标）
+ * @param y - 缩放中心 Y（画布坐标）
+ */
+declare const scale: (scale: number, x: number, y: number) => void;
+/**
+ * 将指定对象居中到视口。
+ * @category 画布操作
+ * @param ids - 需要居中的对象 ID 数组
+ * @param duration - 动画时长（毫秒），默认 0 表示无动画
+ */
+declare const centerObjects: (ids: string[], duration?: number) => void;
+/**
+ * 将画布内容自适应到视口。
+ * @category 画布操作
+ * @param screen - 可选，自定义视口区域 \{ x, y, width, height \}；不传则使用当前视口
+ */
+declare const fitToScreen: (screen?: {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}) => void;
+/**
+ * 世界坐标转画布（视口）坐标。
+ * @category 画布操作
+ * @param x - 世界坐标 X
+ * @param y - 世界坐标 Y
+ * @returns 画布坐标；失败时返回 null
+ */
+declare const worldToCanvas: (x: number, y: number) => {
+    x: number;
+    y: number;
+} | null;
+/**
+ * 画布（视口）坐标转世界坐标。
+ * @category 画布操作
+ * @param x - 画布坐标 X
+ * @param y - 画布坐标 Y
+ * @returns 世界坐标；失败时返回 null
+ */
+declare const canvasToWorld: (x: number, y: number) => {
+    x: number;
+    y: number;
+} | null;
+/**
+ * 获取当前画布缩放比例。
+ * @category 画布操作
+ * @returns 当前缩放值
+ */
+declare const getScale: () => number;
+/**
+ * 获取当前选中的对象列表。
+ * @category 对象操作
+ * @returns 选中对象数组；无选中时返回 null
+ */
+declare const getActiveObjects: () => CanvasObjectData[] | null;
+/**
+ * 根据 ID 获取单个对象的数据。
+ * @category 对象操作
+ * @param id - 对象 ID
+ * @returns 对象数据；未找到或 id 为空时返回 null
+ */
+declare const getObject: (id: string) => CanvasObjectData | null;
+/**
+ * 获取当前选中对象的外接矩形。
+ * @category 对象操作
+ * @returns 选中对象的包围盒；无选中时返回 null
+ */
+declare const getBounds: () => {
+    left: number;
+    top: number;
+    width: number;
+    height: number;
+} | null;
+/**
+ * 设置指定对象的属性。若包含图片 src，会自动预注册图片资源。
+ * @category 对象操作
+ * @param id - 对象 ID
+ * @param properties - 要设置的属性键值对，字段参考对应的对象类型定义（如 CanvasTextboxObject、CanvasImageObject 等）
+ */
+declare const setObjectProperties: (id: string, properties: Record<string, any>) => Promise<void>;
+/**
+ * 注册字体，供画布文本渲染使用。支持 TTF、OTF、WOFF2 格式，自动检测并解码 WOFF2。
+ * @category 字体
+ * @param fonts - 字体数组，每项包含 fontName（字体名）和 url（字体文件地址）
+ */
+declare const registerFonts: (fonts: {
+    fontName: string;
+    url: string;
+}[]) => Promise<void>;
+/**
+ * 切换「创建元素」模式，开启后点击画布可直接添加指定图形。
+ * @category 对象操作
+ * @param creating - 是否开启创建模式
+ * @param type - 元素类型
+ * @param options - 创建时的默认属性，字段参考对应的对象类型定义
+ */
+declare const switchToCreatingElement: (creating: boolean, type?: CanvasElementType | "", options?: Record<string, any>) => Promise<void>;
+/**
+ * 取消指定对象在指定索引处的标记。
+ * @category 对象操作
+ * @param id - 对象 ID
+ * @param index - 标记索引
+ */
+declare const unmark: (id: string, index: number) => void;
+/**
+ * 向画布添加对象。
+ * @category 对象操作
+ * @param type - 元素类型
+ * @param properties - 对象初始属性，字段参考对应的对象类型定义（如 CanvasTextboxObject、CanvasImageObject 等）
+ * @returns 新创建对象的 ID；失败时返回 null
+ */
+declare const add: (type: CanvasElementType, properties: Record<string, any>) => Promise<string | null>;
+/**
+ * 删除对象。不传 id 时删除当前选中的对象。
+ * @category 对象操作
+ * @param id - 对象 ID；默认为空字符串，表示删除当前选中
+ */
+declare const remove: (id?: string) => void;
+/**
+ * 选中指定 ID 的对象。
+ * @category 对象操作
+ * @param ids - 要选中的对象 ID 数组
+ */
+declare const select: (ids: string[]) => void;
+/**
+ * 将当前选中对象复制到剪贴板。
+ * @category 剪贴板
+ */
+declare const copy: () => Promise<void>;
+/**
+ * 在指定位置粘贴剪贴板内容。支持序列化数据、文本、图片等多种格式。
+ * @category 剪贴板
+ * @param x - 粘贴位置 X（世界坐标）
+ * @param y - 粘贴位置 Y（世界坐标）
+ * @param clipboardEvent - 可选，浏览器原始 ClipboardEvent，用于读取系统剪贴板
+ * @returns 粘贴结果
+ */
+declare const paste: (x: number, y: number, clipboardEvent?: ClipboardEvent) => Promise<PasteResult>;
+/**
+ * 剪切当前选中对象（先复制到剪贴板，再删除）。
+ * @category 剪贴板
+ */
+declare const cut: () => Promise<void>;
+/**
+ * 判断当前是否可撤销。
+ * @category 历史
+ * @returns true 表示可撤销
+ */
+declare const canUndo: () => boolean;
+/**
+ * 判断当前是否可重做。
+ * @category 历史
+ * @returns true 表示可重做
+ */
+declare const canRedo: () => boolean;
+/**
+ * 撤销上一步操作。
+ * @category 历史
+ */
+declare const undo: () => void;
+/**
+ * 重做上一步被撤销的操作。
+ * @category 历史
+ */
+declare const redo: () => void;
+/**
+ * 获取对象的父层 ID。
+ * @category 层级操作
+ * @param id - 对象 ID
+ * @returns 父层 ID；无父层时返回空字符串
+ */
+declare const getParentLayer: (id: string) => string;
+/**
+ * 获取对象在父层中的索引位置。
+ * @category 层级操作
+ * @param id - 对象 ID
+ * @returns 索引位置；未找到时返回 -1
+ */
+declare const getIndex: (id: string) => number;
+/**
+ * 将对象上移一层。
+ * @category 层级操作
+ * @param id - 对象 ID
+ */
+declare const moveUp: (id: string) => void;
+/**
+ * 将对象下移一层。
+ * @category 层级操作
+ * @param id - 对象 ID
+ */
+declare const moveDown: (id: string) => void;
+/**
+ * 将对象移动到指定父层的指定索引位置。
+ * @category 层级操作
+ * @param parentId - 目标父层 ID
+ * @param index - 目标索引，-1 表示移到末尾
+ */
+declare const moveTo: (parentId: string, index: number) => void;
+/**
+ * 将对象置于最顶层。
+ * @category 层级操作
+ * @param id - 对象 ID
+ */
+declare const bringToFront: (id: string) => void;
+/**
+ * 将对象置于最底层。
+ * @category 层级操作
+ * @param id - 对象 ID
+ */
+declare const sendToBack: (id: string) => void;
+/**
+ * 判断指定对象是否可以成组。
+ * @category 组合
+ * @param ids - 对象 ID 数组
+ * @returns true 表示可以成组
+ */
+declare const canGroup: (ids: string[]) => boolean;
+/**
+ * 将指定对象成组。
+ * @category 组合
+ * @param ids - 要成组的对象 ID 数组
+ * @returns 新组的 ID；失败时返回 null
+ */
+declare const group: (ids: string[]) => string | null;
+/**
+ * 解散组，将组内对象还原为独立对象。
+ * @category 组合
+ * @param id - 组对象 ID
+ */
+declare const ungroup: (id: string) => void;
+/**
+ * 对齐当前选中对象。
+ * @category 对齐与排列
+ * @param alignment - 对齐方式（相对当前选中范围）
+ */
+declare const align: (alignment: "left" | "right" | "top" | "bottom" | "center" | "middle") => void;
+/**
+ * 排列当前选中对象（如均匀分布）。
+ * @category 对齐与排列
+ * @param arrangement - 排列方式
+ */
+declare const arrange: (arrangement: "horizontal" | "vertical" | "auto") => void;
+/**
+ * 切换平移模式（拖拽画布而非选择对象）。
+ * @category 画布操作
+ * @param isPan - true 进入平移模式，false 退出
+ */
+declare const switchToPan: (isPan: boolean) => void;
+/**
+ * 从 JSON 加载画布内容（会覆盖当前画布）。自动预注册 JSON 中的图片资源。
+ * @category 数据
+ * @param json - 画布数据，格式为 \{ width, height, objects \}
+ */
+declare const loadFromJSON: (json: CanvasData) => Promise<void>;
+/**
+ * 将 Fabric.js 格式的 JSON 转为画布对象并添加到画布中。
+ * @category 数据
+ * @param fabricJSON - Fabric.js 导出的 JSON 数据
+ * @param x - 放置位置 X，默认 0
+ * @param y - 放置位置 Y，默认 0
+ * @returns 新建 frame 的 ID；失败时返回 null
+ */
+declare const addFabricJSON: (fabricJSON: Record<string, any>, x?: number, y?: number) => Promise<string | null>;
+/**
+ * 导出当前画布为 JSON 数据。
+ * @category 数据
+ * @returns 画布数据；失败时返回 null
+ */
+declare const exportToJSON: () => CanvasData | null;
+/**
+ * 导出图片。选中单图/多图时返回图片 URL 或 URL 数组；否则导出整画布为 base64 等。
+ * @category 数据
+ * @param type - MIME 类型，如 'image/png'
+ * @param multiple - 导出倍率（如 devicePixelRatio），默认 2
+ * @param quality - 质量 0–1，默认 1
+ * @returns 选中图片时返回原始 src；否则返回画布导出的 base64。失败返回 null
+ */
+declare const exportImage: (type?: string, multiple?: number, quality?: number) => string | string[] | null;
+/**
+ * 获取文本对象的选区范围。
+ * @category 对象操作
+ * @param id - 文本对象 ID
+ * @returns 文本选区；无选区时返回 null
+ */
+declare const getTextLayerSelection: (id: string) => {
+    start: number;
+    end: number;
+} | null;
+
+/**
+ * HTML to EditorJSON Converter - Type Definitions
+ */
+interface ColorStop {
+    offset: number;
+    color: string;
+}
+interface LinearGradient {
+    type: "linear";
+    coords: {
+        x1: number;
+        y1: number;
+        x2: number;
+        y2: number;
+    };
+    colorStops: ColorStop[];
+}
+interface Shadow {
+    blur?: number;
+    color?: string;
+    offsetX?: number;
+    offsetY?: number;
+}
+interface CharacterStyle {
+    fill?: string | LinearGradient;
+    fontSize?: number;
+    fontFamily?: string;
+    bold?: boolean;
+    italic?: boolean;
+    underline?: boolean;
+    linethrough?: boolean;
+    charSpacing?: number;
+    stroke?: string;
+    verticalAlign?: 'baseline' | 'super' | 'sub';
+}
+interface CommonLayerFields {
+    id: string;
+    name?: string;
+    left: number;
+    top: number;
+    width: number;
+    height: number;
+    scaleX?: number;
+    scaleY?: number;
+    angle?: number;
+    strokeWidth?: number;
+    opacity?: number;
+    visible?: boolean;
+    locked?: boolean;
+}
+interface TextLayer extends CommonLayerFields, CharacterStyle {
+    type: "textbox";
+    text: string;
+    lineHeight?: number;
+    shadow?: Shadow;
+    textAlign?: string;
+    styles?: {
+        [lineIndex: string]: {
+            [charIndex: string]: CharacterStyle;
+        };
+    };
+}
+interface ImageLayer extends CommonLayerFields {
+    type: "image";
+    src: string;
+    prompt?: string;
+    objectFit?: string;
+    rx?: number;
+    ry?: number;
+    backgroundColor?: string | LinearGradient;
+    stroke?: string;
+    shadow?: Shadow;
+}
+interface RectangleLayer extends CommonLayerFields {
+    type: "rectangle";
+    rx?: number;
+    ry?: number;
+    fill?: string | LinearGradient;
+    stroke?: string;
+    shadow?: Shadow;
+    borderDashArray?: number[];
+}
+interface CircleLayer extends CommonLayerFields {
+    type: "circle";
+    radius?: number;
+    fill?: string | LinearGradient;
+    stroke?: string;
+    shadow?: Shadow;
+    borderDashArray?: number[];
+}
+interface FrameLayer extends CommonLayerFields {
+    type: "frame";
+    backgroundColor?: string | LinearGradient;
+    objects: Layer[];
+}
+interface SlideLayer extends CommonLayerFields {
+    type: "slide";
+    paddingX?: number;
+    paddingY?: number;
+    backgroundColor?: string | LinearGradient;
+    stroke?: string;
+    contentBackgroundColor?: string | LinearGradient;
+    contentStrokeWidth?: number;
+    contentStroke?: string;
+    showName?: boolean;
+    showSize?: boolean;
+    objects: Layer[];
+}
+interface GroupLayer extends CommonLayerFields {
+    type: "group";
+    objects: Layer[];
+}
+type Layer = TextLayer | ImageLayer | RectangleLayer | CircleLayer | FrameLayer | SlideLayer | GroupLayer;
+
+/**
+ * HTML to EditorJSON Converter
+ */
+
+/**
+ * 将 HTML 字符串转换为 FrameLayer 或 SlideLayer（仅支持浏览器环境）。
+ *
+ * 在隐藏 iframe 中加载并执行 HTML（含脚本与动态样式），再按
+ * CSS 绘制顺序解析为 JSON。
+ *
+ * @param html          - HTML 字符串
+ * @param containerType - 输出容器类型，默认 "frame"
+ */
+declare function html2json(html: string, containerType?: "frame" | "slide"): Promise<FrameLayer | SlideLayer>;
+
+export { GoatdeeCanvas, add, addFabricJSON, align, arrange, bringToFront, canGroup, canRedo, canUndo, canvasToWorld, centerObjects, copy, cut, exportImage, exportToJSON, fitToScreen, getActiveObjects, getBounds, getIndex, getObject, getParentLayer, getScale, getTextLayerSelection, group, html2json, loadFromJSON, moveDown, moveTo, moveUp, pan, paste, redo, registerFonts, remove, scale, select, sendToBack, setObjectProperties, switchToCreatingElement, switchToPan, undo, ungroup, unmark, worldToCanvas };
+export type { CanvasCircleObject, CanvasData, CanvasElementType, CanvasFill, CanvasFrameObject, CanvasGroupObject, CanvasImageObject, CanvasLinearGradient, CanvasObjectData, CanvasOnActionEventMap, CanvasPathObject, CanvasProps, CanvasRectangleObject, CanvasRef, CanvasShadow, CanvasSlideObject, CanvasStroke, CanvasTextboxObject, CanvasTriangleObject, PasteResult };