@machete-jhun/canvas-studio 0.0.1 → 0.0.6

package/README.md

@@ -1,140 +1,201 @@
 # CanvasStudio 🎨
 
-基于 React + Konva 的轻量级 Canvas 画布编辑器组件
+基于 React + Konva 的专业级 Canvas 画布编辑器组件库，支持丰富的图形编辑能力。
 
 ## 特性
 
-- 🎨 支持多种图形：矩形、椭圆、文本、图片、SVG、二维码、条形码
-- 🖱️ 拖拽、缩放、旋转图形
-- ⌨️ 键盘快捷键支持
-- 📐 辅助线与对齐吸附
-- 🔲 棋盘格/点阵背景
-- 📏 标尺显示
-- 💪 完整的 TypeScript 类型支持
-- ⚡ 轻量级打包 (~33KB gzip: ~11KB)
+- 🎨 **丰富的图形支持**：矩形、圆形、文本、图片、SVG、二维码、条形码、视频、Rive 动画、屏幕背景
+- 🖱️ **完整的编辑能力**：拖拽、缩放、旋转、多选、组选等
+- ⌨️ **键盘快捷键**：支持常用快捷键（复制、粘贴、删除、撤销等）
+- 📐 **智能对齐**：辅助线与吸附功能，支持网格对齐
+- 🔲 **灵活的背景**：棋盘格、点阵、纯色背景可选
+- 📏 **标尺与刻度**：像素/毫米刻度可配置
+- 💪 **完整的 TypeScript 支持**：完善的类型定义
+- 📦 **轻量级**：仅 ~53KB（gzip ~17KB）
 
 ## 安装
 
-```bash
-npm install canvas-studio
-# 或
-pnpm add canvas-studio
-```
+### 使用 npm/pnpm/yarn
 
-### Peer Dependencies
+```bash
+# 使用 pnpm（推荐）
+pnpm add @machete-jhun/canvas-studio
 
-需要同时安装以下依赖：
+# 或使用 npm
+npm install @machete-jhun/canvas-studio
 
-```bash
-npm install react react-dom konva react-konva react-konva-utils nanoid lodash-es js-base64 qrcode jsbarcode
+# 或使用 yarn
+yarn add @machete-jhun/canvas-studio
 ```
 
-## 基础使用
+
+## 快速开始
 
 ```tsx
-import { CanvasStudio, type CanvasStudioRef } from 'canvas-studio'
+import { CanvasStudio, type CanvasStudioRef } from '@machete-jhun/canvas-studio'
 import { useRef } from 'react'
 
-function App() {
+export function App() {
   const canvasRef = useRef<CanvasStudioRef>(null)
 
   return (
     <CanvasStudio
       ref={canvasRef}
-      width={800}
-      height={600}
+      width={1200}
+      height={800}
       backgroundType="grid"
     />
   )
 }
 ```
 
-## Props
+## 组件 Props
 
 | 属性 | 类型 | 默认值 | 说明 |
 |------|------|--------|------|
-| `width` | `number` | `800` | 画布宽度 |
-| `height` | `number` | `600` | 画布高度 |
-| `shapeList` | `MyShapeConfig[]` | `[]` | 图形列表 |
-| `bgShapeList` | `MyShapeConfig[]` | `[]` | 背景图形列表（锁定） |
+| `width` | `number` | `800` | 画布宽度（像素） |
+| `height` | `number` | `600` | 画布高度（像素） |
+| `shapeList` | `MyShapeConfig[]` | `[]` | 编辑图形列表 |
+| `bgShapeList` | `MyShapeConfig[]` | `[]` | 背景图形列表（锁定，不可编辑） |
 | `backgroundType` | `'grid' \| 'point' \| 'none'` | `'grid'` | 背景类型 |
 | `hideRuler` | `boolean` | `false` | 是否隐藏标尺 |
-| `ppmm` | `number` | `1` | 每毫米像素数 |
-| `className` | `string` | `''` | 自定义类名 |
-| `onShapeListChange` | `(shapes: MyShapeConfig[]) => void` | - | 图形变化回调 |
-| `onSelectedShapeIdsChange` | `(ids: string[]) => void` | - | 选中变化回调 |
+| `ppmm` | `number` | `1` | 每毫米像素数（用于精确尺寸设置） |
+| `className` | `string` | `''` | 自定义容器类名 |
+| `onShapeListChange` | `(shapes: MyShapeConfig[]) => void` | - | 图形列表变化回调 |
+| `onSelectedShapeIdsChange` | `(ids: string[]) => void` | - | 选中图形变化回调 |
+| `onBgShapeListChange` | `(shapes: MyShapeConfig[]) => void` | - | 背景图形变化回调 |
+
+## Ref API
 
-## Ref 方法
+通过 `useRef` 访问画布的命令式 API：
 
 ```tsx
 const canvasRef = useRef<CanvasStudioRef>(null)
 
-// 获取 Konva Stage 实例
-canvasRef.current?.getStage()
+// 获取原生 Konva Stage 实例
+const stage = canvasRef.current?.getStage()
 
-// 获取/设置选中图形
-canvasRef.current?.getSelectedShapeIds()
-canvasRef.current?.setSelectedShapeIds(['id1', 'id2'])
+// 管理选中的图形
+canvasRef.current?.getSelectedShapeIds()           // 获取选中图形 ID
+canvasRef.current?.setSelectedShapeIds(['id1'])   // 设置选中图形
 
-// 增删改图形
-canvasRef.current?.addShapes([...shapes])
-canvasRef.current?.removeShapes(['id1'])
-canvasRef.current?.updateShape(shape)
-canvasRef.current?.getShapeList()
+// 管理图形
+canvasRef.current?.addShapes([shape1, shape2])    // 添加图形
+canvasRef.current?.removeShapes(['id1', 'id2'])   // 删除图形
+canvasRef.current?.updateShape(shape)              // 更新单个图形
+canvasRef.current?.getShapeList()                  // 获取所有图形列表
 
-// 适配内容
-canvasRef.current?.fitToContent()
+// 视图操作
+canvasRef.current?.fitToContent()                 // 自适应缩放显示所有内容
 ```
 
-## 创建图形
+## 创建和操作图形
+
+导入工具函数快速创建各类图形：
 
 ```tsx
 import {
   createRect,
-  createEllipse,
   createText,
   createImage,
   createSvg,
   createQrCode,
   createBarCode,
+  createRive,
+  createVideo,
+  createBackScreen,
   copyShape,
-} from 'canvas-studio'
+  type MyShapeConfig,
+} from '@machete-jhun/canvas-studio/utils'
 
 // 创建矩形
-const rect = createRect(100, 100, 200, 150, '#ff0000')
+const rect = createRect(100, 100, 200, 150, '#3498db')
 
 // 创建文本
-const text = createText('Hello', 24, 'Arial', 'font-id', 'font-url', 100, 100)
+const text = createText(
+  'Hello Canvas',      // 文本内容
+  24,                  // 字体大小
+  'Arial',             // 字体族
+  'font-id',           // 字体 ID
+  'https://...',       // 字体 URL
+  50,                  // x 坐标
+  50                   // y 坐标
+)
 
 // 创建图片
-const image = createImage('https://...', 'image.png', '图片', 100, 100, 200, 200)
+const image = createImage(
+  'https://example.com/image.png',  // 图片 URL
+  'image.png',                       // 图片名
+  '图片描述',                        // 显示名
+  '',                                // ID（可选）
+  100,                               // x 坐标
+  100,                               // y 坐标
+  200,                               // 宽度
+  200                                // 高度
+)
 
 // 创建二维码
-const qrcode = createQrCode('https://example.com', 100, 100, 150)
+const qrcode = createQrCode(
+  'https://example.com',  // 二维码内容
+  100,                    // x 坐标
+  100,                    // y 坐标
+  150                     // 边长
+)
 
 // 创建条形码
-const barcode = createBarCode('123456789', 100, 100, 200, 80)
-
-// 复制图形
-const copiedShape = copyShape(rect)
+const barcode = createBarCode(
+  '1234567890',    // 条形码内容
+  100,             // x 坐标
+  100,             // y 坐标
+  200,             // 宽度
+  100              // 高度
+)
+
+// 创建 Rive 动画
+const rive = createRive(
+  'https://example.com/animation.riv',  // Rive 文件 URL
+  'animation',                           // 名称
+  '动画描述',                            // 显示名
+  100,                                   // x 坐标
+  100,                                   // y 坐标
+  400,                                   // 宽度
+  300,                                   // 高度
+  'rive-id',                             // ID
+  []                                     // 状态机输入配置
+)
+
+// 创建视频
+const video = createVideo(
+  'https://example.com/video.mp4',  // 视频 URL
+  '我的视频',                        // 显示名
+  100,                               // x 坐标
+  100,                               // y 坐标
+  1920,                              // 宽度
+  1080,                              // 高度
+  1.0,                               // 播放速度
+  true                               // 是否循环
+)
+
+// 创建屏幕背景（展示用）
+const screen = createBackScreen(
+  'SCREEN_001',     // 屏幕 ID
+  '#ffffff',        // 背景色
+  100,              // x 坐标
+  100,              // y 坐标
+  400,              // 宽度
+  600               // 高度
+)
+
+// 复制图形（会生成新 ID）
+const copiedRect = copyShape(rect)
 
 // 添加到画布
-canvasRef.current?.addShapes([rect, text, image])
+canvasRef.current?.addShapes([rect, text, image, qrcode])
 ```
 
-## 导出的常量
-
-```tsx
-import {
-  STAGE_CONTAINER_ID,
-  CUSTOMER_SHAPE_NAME,
-  BACKGROUND_SHAPE_NAME,
-  SHAPE_LAYER_NAME,
-  // ...
-} from 'canvas-studio'
-```
+## 工具函数
 
-## 导出的工具函数
+导入并使用各种工具函数：
 
 ```tsx
 import {
@@ -143,15 +204,115 @@ import {
   getPointerPosition,
   getStageCenter,
   getStageViewPortCenter,
-} from 'canvas-studio'
+  assertNever,
+} from '@machete-jhun/canvas-studio/utils'
+
+// 检查是否 macOS
+if (isMac()) {
+  // 使用 Cmd 键
+}
+
+// 获取互补色
+const complementColor = complementaryHexColor('#ff0000')  // '#00ffff'
+
+// 获取鼠标在 Stage 中的位置
+const position = getPointerPosition(konvaEvent)
+
+// 获取 Stage 中心坐标
+const center = getStageCenter(stage)
+
+// 获取视口中心坐标
+const vpCenter = getStageViewPortCenter({ stage, offsetWidth: 0 })
 ```
 
-### 扣绿幕
-ffmpeg -i dragon_green_screen.mp4 -vf "chromakey=0x00FF00:0.15:0.1" -c:v libvpx-vp9 -pix_fmt yuva420p -b:v 5M output_transparent.webm
-### mov 转webm
-ffmpeg -i 你的文件名.mov -c:v libvpx-vp9 -pix_fmt yuva420p output.webm
-## License
+## 导出的常量
+
+```tsx
+import { SHAPE_TYPES, THEME_COLOR } from '@machete-jhun/canvas-studio'
+
+// 图形类型
+console.log(SHAPE_TYPES.TEXT)       // 'text'
+console.log(SHAPE_TYPES.RECT)       // 'rect'
+console.log(SHAPE_TYPES.IMAGE)      // 'image'
+console.log(SHAPE_TYPES.SVG)        // 'svg'
+console.log(SHAPE_TYPES.QR_CODE)    // 'qr_code'
+console.log(SHAPE_TYPES.BAR_CODE)   // 'bar_code'
+console.log(SHAPE_TYPES.RIVE)       // 'rive'
+console.log(SHAPE_TYPES.VIDEO)      // 'video'
+console.log(SHAPE_TYPES.BACK_SCREEN) // 'back_screen'
+
+// 主题色
+console.log(THEME_COLOR.active)     // '#1677ff'
+console.log(THEME_COLOR.disable)    // '#666'
+console.log(THEME_COLOR.default)    // '#ccc'
+```
+
+## 导出路径
+
+本库支持两种导出方式：
+
+```tsx
+// 方式 1：导入主组件和类型
+import { 
+  CanvasStudio, 
+  type CanvasStudioProps, 
+  type CanvasStudioRef,
+  SHAPE_TYPES,
+} from '@machete-jhun/canvas-studio'
+
+// 方式 2：导入工具函数（推荐单独导入）
+import {
+  createRect,
+  createText,
+  createImage,
+  // ...其他工具
+} from '@machete-jhun/canvas-studio/utils'
+```
+
+## 高级用法
+
+### 自定义背景图层
+
+```tsx
+<CanvasStudio
+  shapeList={editableShapes}
+  bgShapeList={backgroundShapes}
+  onShapeListChange={handleEditableChange}
+  onBgShapeListChange={handleBgChange}
+/>
+```
+
+### 精确尺寸控制
+
+使用 `ppmm`（每毫米像素数）实现精确的物理尺寸：
+
+```tsx
+<CanvasStudio
+  width={210}    // 210mm 宽（A4 纸）
+  height={297}   // 297mm 高（A4 纸）
+  ppmm={3.78}    // 1mm = 3.78px (96DPI)
+/>
+```
+
+## 常见问题
+
+### 如何处理视频透明背景？
+
+可以使用 FFmpeg 将视频转换为支持透明通道的格式：
+
+```bash
+# 扣绿幕效果
+ffmpeg -i input.mp4 -vf "chromakey=0x00FF00:0.15:0.1" \
+  -c:v libvpx-vp9 -pix_fmt yuva420p -b:v 5M output.webm
+
+# MOV 转 WebM（支持透明）
+ffmpeg -i input.mov -c:v libvpx-vp9 -pix_fmt yuva420p output.webm
+```
+
+## 许可证
 
 MIT
 
+## 贡献
+
 

package/dist/constants-CHIlz4uF.js

@@ -0,0 +1 @@
+const c="c0",a="c1",s="c2",e="c3",E="c4",t="c5",d="c6",r="c7",_="c8",i="c9",o="ca",C="cb",R="cc",b="cd",f="ce",v={IMAGE:"image",RECT:"rect",TEXT:"text",SVG:"svg",QR_CODE:"qr_code",BAR_CODE:"bar_code",RIVE:"rive",VIDEO:"video",BACK_SCREEN:"back_screen"},g={active:"#1677ff",disable:"#666",default:"#ccc"};export{g as _,s as a,E as c,b as d,d as f,c as g,R as h,r as i,C as l,v as m,o as n,a as o,t as p,i as r,_ as s,e as t,f as u};

package/dist/index.d.ts

@@ -2,5 +2,3 @@ export { CanvasStudio, type CanvasStudioProps, type CanvasStudioRef } from './Ca
 export { default } from './CanvasStudio';
 export * from './types';
 export * from './constants';
-export * from './utils/shapeTools';
-export { isMac, complementaryHexColor, getPointerPosition, getStageCenter, getStageViewPortCenter, } from './utils';