goatdee-canvas 0.0.1

package/README.md

@@ -0,0 +1,536 @@
+# Goatdee Canvas
+
+一个功能强大的无限画布组件，支持文本、图像、形状的添加、编辑和操作，提供完整的画布交互体验。
+
+## 特性
+
+- 🎨 **多种内容类型**: 支持文本、图像、圆形、矩形、三角形等形状
+- 🖱️ **交互操作**: 平移、缩放、选择、拖拽等画布操作
+- 📝 **历史记录**: 完整的撤销/重做功能
+- 🎯 **对象管理**: 对象属性设置、层级调整、删除等操作
+- 📤 **数据导出**: 支持导出为 JSON、图片（PNG/JPEG/WEBP）格式
+- 🔧 **类型安全**: 完整的 TypeScript 支持
+
+## 安装
+
+```bash
+npm install goatdee-canvas
+# 或
+yarn add goatdee-canvas
+# 或
+pnpm add goatdee-canvas
+```
+
+## 快速开始
+
+```tsx
+import React from 'react';
+import { GoatdeeCanvas } from 'goatdee-canvas';
+
+function App() {
+  return (
+    <div style={{ width: '100vw', height: '100vh' }}>
+      <GoatdeeCanvas />
+    </div>
+  );
+}
+```
+
+## API 参考
+
+### 画布操作
+
+#### 平移 (Pan)
+```tsx
+import { pan } from 'goatdee-canvas';
+
+// 平移画布
+pan(deltaX: number, deltaY: number);
+```
+
+#### 缩放 (Scale)
+```tsx
+import { scale, getScale } from 'goatdee-canvas';
+
+// 获取当前缩放比例
+const currentScale = getScale();
+
+// 缩放画布 (scaleValue: 缩放倍数, centerX: 中心点X, centerY: 中心点Y)
+scale(scaleValue: number, centerX: number, centerY: number);
+```
+
+#### 自适应屏幕 (Fit To Screen)
+```tsx
+import { fitToScreen } from 'goatdee-canvas';
+
+// 将画布内容自适应到屏幕大小
+fitToScreen();
+```
+
+#### 切换平移模式 (Switch To Pan)
+```tsx
+import { switchToPan } from 'goatdee-canvas';
+
+// 开启/关闭平移模式
+switchToPan(true);  // 开启
+switchToPan(false); // 关闭
+```
+
+### 对象操作
+
+#### 添加对象
+
+**添加文本**
+```tsx
+import { add } from 'goatdee-canvas';
+
+const textData = {
+  text: "测试文案",           // 必需：文本内容
+  left: 100,                // 必需：左侧位置
+  top: 100,                 // 必需：顶部位置
+  fontSize: 24,             // 可选：字体大小
+  fontFamily: "SourceHanSansCN-Normal", // 可选：字体族
+  fill: "#ff0000"           // 可选：填充颜色
+};
+
+add("text", textData);
+```
+
+**添加图像**
+```tsx
+const imageData = {
+  src: "https://example.com/image.png", // 必需：图片URL
+  left: 400,                           // 必需：左侧位置
+  top: 100                             // 必需：顶部位置
+};
+
+add("image", imageData);
+```
+
+**添加形状**
+```tsx
+// 圆形
+const circleData = {
+  type: "circle",      // 必需：形状类型
+  left: 100,                // 必需：左侧位置
+  top: 100,                 // 必需：顶部位置
+  radius: 50,               // 可选：半径
+  fill: "#00ff00",     // 可选：填充颜色
+  stroke: "#000000",   // 可选：描边颜色
+  strokeWidth: 2            // 可选：描边宽度
+};
+
+add("shape", circleData);
+
+// 矩形
+const rectangleData = {
+  type: "rectangle",   // 必需：形状类型
+  left: 200,                // 必需：左侧位置
+  top: 200,                 // 必需：顶部位置
+  width: 100,               // 可选：宽度
+  height: 100,              // 可选：高度
+  fill: "#0000ff",     // 可选：填充颜色
+  stroke: "#000000",   // 可选：描边颜色
+  strokeWidth: 2            // 可选：描边宽度
+};
+
+add("shape", rectangleData);
+
+// 三角形
+const triangleData = {
+  type: "triangle",    // 必需：形状类型
+  left: 300,                // 必需：左侧位置
+  top: 300,                 // 必需：顶部位置
+  width: 100,               // 可选：宽度
+  height: 100,              // 可选：高度
+  fill: "#00ff00",     // 可选：填充颜色
+  stroke: "#000000",   // 可选：描边颜色
+  strokeWidth: 2            // 可选：描边宽度
+};
+
+add("shape", triangleData);
+```
+
+#### 选中对象 (Select)
+```tsx
+import { select } from 'goatdee-canvas';
+
+// 通过对象ID选中对象
+select(objectId: string);
+```
+
+#### 获取活动对象
+```tsx
+import { getActiveObjects } from 'goatdee-canvas';
+
+const activeObject = getActiveObjects();
+// 返回 JSON 字符串，需要解析
+const obj = JSON.parse(activeObject);
+```
+
+#### 获取对象外接矩形
+```tsx
+import { getBounds } from 'goatdee-canvas';
+
+// 获取指定对象的外接矩形信息
+// 如果不传参数，则获取所有对象的外接矩形
+const bounds = getBounds(); // 获取所有对象
+const bounds = getBounds(['id1', 'id2']); // 获取指定对象
+```
+
+#### 设置对象属性
+```tsx
+import { setObjectProperties } from 'goatdee-canvas';
+
+const properties = {
+  fill: "#ff0000",
+  fontSize: 12,
+  left: 100,
+  text: "修改文案成功！",
+  top: 400
+};
+
+setObjectProperties(objectId: string, properties);
+```
+
+#### 删除对象
+```tsx
+import { remove } from 'goatdee-canvas';
+
+remove(objectId: string);
+```
+
+### 字体管理
+
+#### 注册字体
+```tsx
+import { registerFonts } from 'goatdee-canvas';
+
+// 注册自定义字体
+const fonts = [
+  {
+    fontName: "baotuxiaobaiti",
+    url: "https://example.com/font.ttf"
+  }
+];
+
+await registerFonts(fonts);
+```
+
+### 数据导入导出
+
+#### 从JSON导入
+```tsx
+import { loadFromJSON } from 'goatdee-canvas';
+
+// 从JSON数据加载画布内容
+const jsonData = {
+  width: 2608,
+  height: 1708,
+  objects: [...]
+};
+
+loadFromJSON(jsonData);
+```
+
+#### 导出为JSON
+```tsx
+import { exportToJSON } from 'goatdee-canvas';
+
+const jsonData = exportToJSON();
+if (jsonData) {
+  const jsonString = JSON.stringify(jsonData, null, 2);
+  console.log("导出的数据:", jsonData);
+  
+  // 复制到剪贴板
+  navigator.clipboard.writeText(jsonString);
+}
+```
+
+#### 导出图片 (Export Image)
+```tsx
+import { exportImage } from 'goatdee-canvas';
+
+// 导出为图片，返回 Data URL 字符串
+// 支持的类型：'image/png' | 'image/jpeg' | 'image/webp'
+const type = 'image/png';
+const dataUrl = await exportImage(type);
+if (dataUrl) {
+  // 触发下载
+  const link = document.createElement('a');
+  link.href = dataUrl;
+  link.download = type === 'image/png' ? 'canvas.png' : type === 'image/jpeg' ? 'canvas.jpg' : 'canvas.webp';
+  link.click();
+}
+```
+
+### 层级操作
+
+```tsx
+import { moveUp, moveDown, bringToFront, sendToBack } from 'goatdee-canvas';
+
+// 上移一层
+moveUp(objectId: string);
+
+// 下移一层
+moveDown(objectId: string);
+
+// 置顶
+bringToFront(objectId: string);
+
+// 置底
+sendToBack(objectId: string);
+```
+
+### 对齐 (Align)
+
+```tsx
+import { align } from 'goatdee-canvas';
+
+// 对齐选中对象
+// alignment 可选值：'left' | 'right' | 'top' | 'bottom' | 'center' | 'middle'
+align(alignment: string);
+```
+
+### 历史记录
+
+```tsx
+import { canUndo, canRedo, undo, redo } from 'goatdee-canvas';
+
+// 检查是否可以撤销
+const canUndoState = canUndo();
+
+// 检查是否可以重做
+const canRedoState = canRedo();
+
+// 撤销
+undo();
+
+// 重做
+redo();
+```
+
+### 剪贴板操作
+
+```tsx
+import { copy, paste, cut } from 'goatdee-canvas';
+
+// 复制：会将当前选中对象复制到剪贴板（文本格式），并返回该对象数据
+const copied = copy();
+console.log('copied object:', copied);
+
+// 粘贴：从剪贴板读取对象数据并在指定位置创建
+paste(100, 200); // x, y
+
+// 剪切：复制后删除当前选中对象
+cut();
+```
+
+### 组件属性（CanvasProps）
+
+```tsx
+import { GoatdeeCanvas } from 'goatdee-canvas';
+
+export default function App() {
+  return (
+    <GoatdeeCanvas
+      onLoad={() => {
+        // 画布和 WASM 初始化完成
+        console.log('Canvas ready');
+      }}
+      onAction={(action: string, data?: unknown) => {
+        // 画布内部产生的动作回调（如选择、拖拽、键盘操作等）
+        console.log('Canvas action:', action, data);
+      }}
+    />
+  );
+}
+```
+
+## 完整示例
+
+```tsx
+import React, { useState, useEffect } from "react";
+import {
+  pan,
+  scale,
+  getScale,
+  getActiveObjects,
+  setObjectProperties,
+  add,
+  remove,
+  canUndo,
+  canRedo,
+  undo,
+  redo,
+  moveUp,
+  moveDown,
+  bringToFront,
+  sendToBack,
+  exportToJSON,
+  fitToScreen,
+  getBounds,
+  registerFonts,
+  loadFromJSON,
+} from "goatdee-canvas";
+
+function CanvasEditor() {
+  const [currentScale, setCurrentScale] = useState(1);
+  const [canUndoState, setCanUndoState] = useState(false);
+  const [canRedoState, setCanRedoState] = useState(false);
+
+  // 更新状态
+  const updateStates = () => {
+    setCanUndoState(canUndo());
+    setCanRedoState(canRedo());
+    setCurrentScale(getScale());
+  };
+
+  // 定期更新状态
+  useEffect(() => {
+    const interval = setInterval(updateStates, 100);
+    return () => clearInterval(interval);
+  }, []);
+
+  // 添加文本
+  const addText = () => {
+    const textData = {
+      text: "Hello World",
+      left: 100,
+      top: 100,
+      fontSize: 24,
+      fill: "#ff0000"
+    };
+    add("textbox", textData);
+    updateStates();
+  };
+
+  // 添加圆形
+  const addCircle = () => {
+    const circleData = {
+      type: "circle",
+      left: 200,
+      top: 200,
+      radius: 50,
+      fill: "#00ff00"
+    };
+    add("shape", circleData);
+    updateStates();
+  };
+
+  // 缩放
+  const zoomIn = () => {
+    const step = 0.05;
+    const scale = getScale();
+    const newScale = scale + step;
+    const canvas = document.querySelector("canvas");
+    if (canvas) {
+      const rect = canvas.getBoundingClientRect();
+      const centerX = rect.width / 2;
+      const centerY = rect.height / 2;
+      scale(newScale / scale, centerX, centerY);
+      updateStates();
+    }
+  };
+
+  // 自适应屏幕
+  const fitScreen = () => {
+    fitToScreen();
+    updateStates();
+  };
+
+  // 获取对象边界
+  const getObjectBounds = () => {
+    const bounds = getBounds();
+    console.log("所有对象边界:", bounds);
+  };
+
+  return (
+    <div>
+      <div style={{ marginBottom: "20px" }}>
+        <button onClick={addText}>添加文本</button>
+        <button onClick={addCircle}>添加圆形</button>
+        <button onClick={zoomIn}>放大</button>
+        <button onClick={fitScreen}>自适应屏幕</button>
+        <button onClick={getObjectBounds}>获取边界</button>
+        <button onClick={undo} disabled={!canUndoState}>撤销</button>
+        <button onClick={redo} disabled={!canRedoState}>重做</button>
+        <span>当前缩放: {(currentScale * 100).toFixed(0)}%</span>
+      </div>
+      
+      <GoatdeeCanvas />
+    </div>
+  );
+}
+```
+
+## 类型定义
+
+```tsx
+// 文本数据
+interface TextData {
+  text: string;           // 必需：文本内容
+  left: number;           // 必需：左侧位置
+  top: number;            // 必需：顶部位置
+  fontSize?: number;      // 可选：字体大小
+  fontFamily?: string;    // 可选：字体族
+  fill?: string;          // 可选：填充颜色
+}
+
+// 图像数据
+interface ImageData {
+  src: string;            // 必需：图片URL
+  left: number;           // 必需：左侧位置
+  top: number;            // 必需：顶部位置
+  width?: number;         // 可选：宽度
+  height?: number;        // 可选：高度
+  scaleX?: number;        // 可选：横向比例
+  scaleY?: number;        // 可选：纵向比例
+}
+
+// 形状数据
+interface ShapeData {
+  type: "circle" | "rectangle" | "triangle"; // 必需：形状类型
+  left: number;           // 必需：左侧位置
+  top: number;            // 必需：顶部位置
+  radius?: number;        // 可选：半径（圆形）
+  width?: number;         // 可选：宽度（矩形/三角形）
+  height?: number;        // 可选：高度（矩形/三角形）
+  fill?: string;     // 可选：填充颜色
+  stroke?: string;   // 可选：描边颜色
+  strokeWidth?: number;   // 可选：描边宽度
+  cornerRadius?: number;  // 可选：圆角半径（矩形）
+}
+
+// 字体数据
+interface FontData {
+  fontName: string;       // 字体名称
+  url: string;            // 字体文件URL
+}
+
+// 对齐枚举
+type Alignment = 'left' | 'right' | 'top' | 'bottom' | 'center' | 'middle';
+
+// 画布数据
+interface CanvasData {
+  width: number;          // 画布宽度
+  height: number;         // 画布高度
+  objects: any[];         // 对象数组
+  thumb?: string;         // 缩略图（可选）
+}
+```
+
+## 注意事项
+
+1. **对象ID**: 每个对象都有唯一的ID，用于后续的属性设置、删除等操作
+2. **坐标系统**: 使用左上角为原点的坐标系统
+3. **缩放中心**: 缩放操作需要指定中心点坐标
+4. **状态更新**: 建议定期调用状态更新函数以保持UI同步
+5. **错误处理**: 在解析JSON数据时建议使用try-catch进行错误处理
+6. **字体注册**: 字体注册是异步操作，需要等待完成
+7. **图片替换**: 只能替换类型为"image"的对象
+8. **数据导入**: 导入JSON数据会覆盖当前画布内容
+
+## 许可证
+
+MIT License