+
+一个基于 Fabric.js 构建的现代化 React Canvas 绘图组件库，提供强大的 2D 图形绘制、交互和动画功能。
+
+
+
+## ✨ 核心特性
+
+### 🎯 丰富的图形组件
+
+- **基础图形**: 矩形、圆形、椭圆、线条、多边形、路径
+- **文本组件**: 文本、可编辑文本、文本框
+- **图像组件**: 背景图片、普通图片
+- **组合组件**: 分组、对象集合
+- **自定义控件**: 可拖拽控制点、工具栏
+
+### 🖱️ 强大的交互功能
+
+- **自动缩放**: 支持鼠标滚轮缩放，自动适应容器大小
+- **平移操作**: 支持拖拽平移画布视图
+- **触摸支持**: 完整的触摸设备支持，包括双指缩放和拖拽
+- **选择系统**: 多选、框选、键盘快捷键支持
+- **拖拽操作**: 对象拖拽、批量操作
+
+### 📦 响应式设计
+
+- **自动适配**: 画布自动撑满父容器，响应式调整
+- **触摸优化**: 专为移动设备优化的触摸交互
+- **跨平台**: 支持桌面端和移动端浏览器
+
+### 💻 开发者友好
+
+- **TypeScript**: 完整的 TypeScript 类型支持
+- **React 风格**: 声明式 API，符合 React 开发习惯
+- **事件系统**: 完整的事件回调，支持所有 Fabric.js 事件
+- **状态管理**: 内置状态管理，支持受控和非受控模式
-
+## ✨ 快速开始
-## 安装
+### 安装
```bash
npm install @cs-open/react-fabric
@@ -14,124 +61,814 @@ yarn add @cs-open/react-fabric
pnpm add @cs-open/react-fabric
```
-### 可选依赖
+### 基础用法
+
+```tsx
+import React from 'react'
+import { ReactFabric, Rect, Text, Circle } from '@cs-open/react-fabric'
+
+function App() {
+ return (
+
+
+
+
+
+
+
+ )
+}
+
+export default App
+```
+
+## 🎯 核心功能
+
+### 自动缩放与平移
+
+```tsx
+import { ReactFabric, useReactFabric } from '@cs-open/react-fabric'
+
+function CanvasWithControls() {
+ const { zoomIn, zoomOut, resetViewport, zoom } = useReactFabric()
+
+ return (
+
+
+
+
+
+ 缩放: {Math.round(zoom * 100)}%
+
+
+
+ {/* 你的画布内容 */}
+
+
+ )
+}
+```
+
+### 触摸设备支持
+
+```tsx
+import { ReactFabric, PluginPinch } from '@cs-open/react-fabric'
+import { PluginPinch } from '@cs-open/react-fabric/plugins'
+
+function TouchCanvas() {
+ return (
+
+ {/* 你的画布内容 */}
+
+
+ )
+}
+```
+
+### 背景图片
+
+```tsx
+import { ReactFabric, BackgroundImage } from '@cs-open/react-fabric'
+
+function CanvasWithBackground() {
+ return (
+
+
+ {/* 其他图形元素 */}
+
+ )
+}
+```
+
+## 🔌 插件系统
+
+### 内置插件
+
+| 插件 | 功能 | 描述 |
+| ---------------- | -------- | ---------------------- |
+| `PluginPinch` | 触摸缩放 | 支持双指缩放和拖拽操作 |
+| `PluginFreeDraw` | 自由绘制 | 手绘路径和涂鸦功能 |
+| `PluginFreeRect` | 矩形绘制 | 交互式矩形绘制工具 |
+| `PluginFreeText` | 文本工具 | 点击添加可编辑文本 |
+| `PluginGridLine` | 网格辅助 | 显示网格线辅助对齐 |
+| `PluginMask` | 遮罩效果 | 创建遮罩和裁剪效果 |
+
+### 使用插件
+
+```tsx
+import { ReactFabric } from '@cs-open/react-fabric'
+import { PluginPinch, PluginFreeDraw, PluginFreeRect, PluginGridLine } from '@cs-open/react-fabric/plugins'
+
+function AdvancedCanvas() {
+ return (
+
+ {/* 触摸支持 */}
+
+
+ {/* 自由绘制 */}
+ {
+ console.log('绘制完成:', path)
+ }}
+ />
+
+ {/* 矩形绘制工具 */}
+ {
+ console.log('矩形绘制完成:', rect)
+ }}
+ />
+
+ {/* 网格线 */}
+
+
+ )
+}
+```
+
+## 📦 组件 API
+
+### ReactFabric 组件
+
+主要的画布容器组件，支持以下属性：
+
+```tsx
+interface ReactFabricProps {
+ // 基础属性
+ width?: number
+ height?: number
+ className?: string
+ style?: CSSProperties
+
+ // 交互控制
+ zoomable?: boolean // 是否可缩放
+ panAble?: boolean // 是否可平移
+ selection?: boolean // 是否可选择
+ defaultSelection?: boolean // 默认选择状态
+ defaultDraggable?: boolean // 默认拖拽状态
+
+ // 缩放控制
+ manualZoom?: number // 手动缩放倍数
+ minManualZoom?: number // 最小缩放倍数
+ maxManualZoom?: number // 最大缩放倍数
+ defaultCentered?: boolean // 背景图是否居中
+
+ // 事件回调
+ onMouseDown?: (e: FabricPublicEvent) => void
+ onMouseMove?: (e: FabricPublicEvent) => void
+ onMouseUp?: (e: FabricPublicEvent) => void
+ onMouseWheel?: (e: FabricPublicEvent) => void
+}
+```
+
+### 图形组件
+
+所有图形组件都支持对应的 Fabric.js 对象的所有属性和事件：
+
+```tsx
+// 矩形
+
console.log('矩形被修改', e.target)}
+/>
+
+// 圆形
+ console.log('圆形被选中')}
+/>
+
+// 文本
+
+
+// 图片
+
+```
+
+## 🎮 状态管理
+
+### useReactFabric Hook
+
+```tsx
+import { useReactFabric } from '@cs-open/react-fabric'
+
+function Toolbar() {
+ const {
+ // 状态
+ canvas,
+ zoom,
+ manualZoom,
+ isDragging,
+ selection,
+
+ // 方法
+ zoomIn,
+ zoomOut,
+ resetViewport,
+ setZoomable,
+ setSelection,
+ setDraggable,
+ } = useReactFabric()
+
+ return (
+
+
+
+
+ 缩放: {Math.round(zoom * 100)}%
+
+ )
+}
+```
+
+### 跨组件状态访问
+
+ReactFabricProvider 是一个上下文提供程序，允许您从组件树中的任何位置访问流的内部状态，例如子组件，甚至在 ReactFabric 之外 元件。它通常用于应用程序的顶层。
+在这种情况下，您可能需要使用 ReactFabricProvider 组件
+
+```tsx
+import { ReactFabricProvider, useReactFabric } from '@cs-open/react-fabric'
+
+function App() {
+ return (
+
+
+ {/* 画布内容 */}
+
+ )
+}
+
+function Toolbar() {
+ const { zoomIn, zoomOut, resetViewport } = useReactFabric()
+ // 可以在 ReactFabric 外部访问状态
+}
+```
+
+## 🎨 高级用法
+
+### 受控模式
+
+```tsx
+import { useState } from 'react'
+import { ReactFabric, Rect } from '@cs-open/react-fabric'
+
+function ControlledCanvas() {
+ const [rect, setRect] = useState({
+ left: 100,
+ top: 100,
+ width: 200,
+ height: 100,
+ fill: 'red',
+ })
+
+ return (
+
+ setRect(e.target)} />
+
+ )
+}
+```
+
+### 非受控模式
+
+```tsx
+import { ReactFabric, Rect, Group } from '@cs-open/react-fabric'
+
+function UncontrolledCanvas() {
+ return (
+
+
+
+
+
+ )
+}
+```
+
+### DOM 集成
+
+```tsx
+import { ReactFabric, Rect } from '@cs-open/react-fabric'
+
+function CanvasWithDOM() {
+ return (
+
+
+ 这是一个提示框
+
+
+ )
+}
+```
+
+## 📋 依赖要求
+
+### 必需依赖
+
+```json
+{
+ "react": ">=17.0.0",
+ "react-dom": ">=17.0.0",
+ "fabric": "^6.6.1",
+ "zustand": "^4.0.0 || ^5.0.0"
+}
+```
-某些插件需要额外的依赖才能正常工作：
+### 可选依赖
-#### Pinch 插件（触摸手势支持）
+某些插件需要额外的依赖：
```bash
+# 触摸手势支持
npm install hammerjs
-# 如果使用 TypeScript，还需要安装类型定义
-npm install @types/hammerjs
+npm install @types/hammerjs # TypeScript 用户
+
+# 浮动 UI 支持（用于 DOM 集成）
+npm install @floating-ui/react
```
-**注意**：如果没有安装 `hammerjs`，Pinch 插件会自动禁用，不会影响其他功能。
+## 🤝 贡献
+
+欢迎提交 Issue 和 Pull Request！
+
+1. Fork 本仓库
+2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)
+3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
+4. 推送到分支 (`git push origin feature/AmazingFeature`)
+5. 开启 Pull Request
+
+## 📄 许可证
+
+本项目基于 [MIT](LICENSE) 许可证开源。
+
+## 🔗 相关链接
+
+- [Fabric.js 官方文档](http://fabricjs.com/)
+- [React 官方文档](https://reactjs.org/)
+- [项目主页](https://cs-open.github.io/react-fabric/)
+- [GitHub 仓库](https://github.com/cs-open/react-fabric)
+
+---
+
+**Made with ❤️ by the CS-Open team**
+
+
+
+**[⬆ Back to Top](#-cs-openreact-fabric) | [English](#english)**
+
+
+
+
+
+A modern React Canvas drawing component library built on Fabric.js, providing powerful 2D graphics rendering, interaction, and animation capabilities.
+
+## ✨ Core Features
+
+### 🎯 Rich Graphic Components
+
+- **Basic Shapes**: Rectangle, Circle, Ellipse, Line, Polygon, Path
+- **Text Components**: Text, Editable Text, Textbox
+- **Image Components**: Background Image, Regular Image
+- **Group Components**: Group, Object Collection
+- **Custom Controls**: Draggable Control Points, Toolbar
+
+### 🖱️ Powerful Interaction Features
+
+- **Auto Zoom**: Supports mouse wheel zooming, automatically adapts to container size
+- **Pan Operation**: Supports drag to pan canvas view
+- **Touch Support**: Full touch device support, including pinch zoom and drag
+- **Selection System**: Multi-select, box selection, keyboard shortcut support
+- **Drag Operation**: Object dragging, batch operations
+
+### 📦 Responsive Design
+
+- **Auto Adapt**: Canvas automatically fills parent container, responsive adjustment
+- **Touch Optimization**: Touch interactions optimized for mobile devices
+- **Cross-platform**: Supports desktop and mobile browsers
+
+### 💻 Developer Friendly
+
+- **TypeScript**: Full TypeScript type support
+- **React Style**: Declarative API, conforms to React development practices
+- **Event System**: Complete event callbacks, supports all Fabric.js events
+- **State Management**: Built-in state management, supports controlled and uncontrolled modes
+
+## ✨ Quick Start
+
+### Installation
+
+```bash
+npm install @cs-open/react-fabric
+# or
+yarn add @cs-open/react-fabric
+# or
+pnpm add @cs-open/react-fabric
+```
+
+### Basic Usage
```tsx
import React from 'react'
-import { Canvas, Rect, Text } from '@cs-open/react-fabric'
+import { ReactFabric, Rect, Text, Circle } from '@cs-open/react-fabric'
function App() {
return (
-
+
+
+
+
+
+
+
)
}
export default App
```
-## 插件系统
+## 🎯 Core Features
-### 内置插件
+### Auto Zoom and Pan
-- **Pinch**: 触摸设备双指缩放支持
-- **FreeDraw**: 自由绘制工具
-- **FreeRect**: 自由矩形绘制工具
-- **FreeText**: 自由文本工具
-- **GridLine**: 网格线辅助工具
-- **Mask**: 遮罩效果
-- **Pinch**: 触摸手势支持
+```tsx
+import { ReactFabric, useReactFabric } from '@cs-open/react-fabric'
-### 使用插件
+function CanvasWithControls() {
+ const { zoomIn, zoomOut, resetViewport, zoom } = useReactFabric()
+
+ return (
+
+
+
+
+
+ Zoom: {Math.round(zoom * 100)}%
+
+
+
+ {/* Your canvas content */}
+
+
+ )
+}
+```
+
+### Touch Device Support
+
+```tsx
+import { ReactFabric, PluginPinch } from '@cs-open/react-fabric'
+import { PluginPinch } from '@cs-open/react-fabric/plugins'
+
+function TouchCanvas() {
+ return (
+
+ {/* Your canvas content */}
+
+
+ )
+}
+```
+
+### Background Image
+
+```tsx
+import { ReactFabric, BackgroundImage } from '@cs-open/react-fabric'
+
+function CanvasWithBackground() {
+ return (
+
+
+ {/* Other graphic elements */}
+
+ )
+}
+```
+
+## 🔌 Plugin System
+
+### Built-in Plugins
+
+| Plugin | Function | Description |
+| ---------------- | -------------- | ------------------------------------------- |
+| `PluginPinch` | Touch Zoom | Supports pinch zoom and drag operations |
+| `PluginFreeDraw` | Free Draw | Hand-drawn paths and doodle features |
+| `PluginFreeRect` | Rectangle Draw | Interactive rectangle drawing tool |
+| `PluginFreeText` | Text Tool | Click to add editable text |
+| `PluginGridLine` | Grid Guide | Display grid lines for alignment assistance |
+| `PluginMask` | Mask Effect | Create mask and crop effects |
+
+### Using Plugins
+
+```tsx
+import { ReactFabric } from '@cs-open/react-fabric'
+import { PluginPinch, PluginFreeDraw, PluginFreeRect, PluginGridLine } from '@cs-open/react-fabric/plugins'
+
+function AdvancedCanvas() {
+ return (
+
+ {/* Touch support */}
+
+
+ {/* Free draw */}
+ {
+ console.log('Drawing completed:', path)
+ }}
+ />
+
+ {/* Rectangle drawing tool */}
+ {
+ console.log('Rectangle drawing completed:', rect)
+ }}
+ />
+
+ {/* Grid lines */}
+
+
+ )
+}
+```
+
+## 📦 Component API
+
+### ReactFabric Component
+
+The main canvas container component, supports the following properties:
```tsx
-import { Canvas } from '@cs-open/react-fabric'
-import { Pinch, FreeDraw } from '@cs-open/react-fabric/plugins'
+interface ReactFabricProps {
+ // Basic Properties
+ width?: number
+ height?: number
+ className?: string
+ style?: CSSProperties
+
+ // Interaction Control
+ zoomable?: boolean // Whether zoomable
+ panAble?: boolean // Whether panable
+ selection?: boolean // Whether selectable
+ defaultSelection?: boolean // Default selection state
+ defaultDraggable?: boolean // Default draggable state
+
+ // Zoom Control
+ manualZoom?: number // Manual zoom level
+ minManualZoom?: number // Minimum zoom level
+ maxManualZoom?: number // Maximum zoom level
+ defaultCentered?: boolean // Whether background image is centered
+
+ // Event Callbacks
+ onMouseDown?: (e: FabricPublicEvent) => void
+ onMouseMove?: (e: FabricPublicEvent) => void
+ onMouseUp?: (e: FabricPublicEvent) => void
+ onMouseWheel?: (e: FabricPublicEvent) => void
+}
+```
+
+### Graphic Components
+
+All graphic components support all properties and events of the corresponding Fabric.js objects:
+
+```tsx
+// Rectangle
+
console.log('Rectangle modified', e.target)}
+/>
+
+// Circle
+ console.log('Circle selected')}
+/>
+
+// Text
+
+
+// Image
+
+```
+
+## 🎮 State Management
+
+### useReactFabric Hook
+
+```tsx
+import { useReactFabric } from '@cs-open/react-fabric'
+
+function Toolbar() {
+ const {
+ // State
+ canvas,
+ zoom,
+ manualZoom,
+ isDragging,
+ selection,
+
+ // Methods
+ zoomIn,
+ zoomOut,
+ resetViewport,
+ setZoomable,
+ setSelection,
+ setDraggable,
+ } = useReactFabric()
+
+ return (
+
+
+
+
+ Zoom: {Math.round(zoom * 100)}%
+
+ )
+}
+```
+
+### Cross-component State Access
+
+ReactFabricProvider is a context provider that allows you to access the internal state of the flow from anywhere in the component tree, such as child components, or even outside the ReactFabric component. It is typically used at the top level of the application.
+In this case, you may need to use the ReactFabricProvider component
+
+```tsx
+import { ReactFabricProvider, useReactFabric } from '@cs-open/react-fabric'
function App() {
return (
-
+
+
+ {/* Canvas content */}
+
)
}
+
+function Toolbar() {
+ const { zoomIn, zoomOut, resetViewport } = useReactFabric()
+ // Can access state outside ReactFabric
+}
```
-## 故障排除
+## 🎨 Advanced Usage
-### Pinch 插件不工作
+### Controlled Mode
-如果触摸手势功能不工作，请确保：
+```tsx
+import { useState } from 'react'
+import { ReactFabric, Rect } from '@cs-open/react-fabric'
+
+function ControlledCanvas() {
+ const [rect, setRect] = useState({
+ left: 100,
+ top: 100,
+ width: 200,
+ height: 100,
+ fill: 'red',
+ })
-1. 已安装 `hammerjs`：
+ return (
+
+ setRect(e.target)} />
+
+ )
+}
+```
- ```bash
- npm install hammerjs
- ```
+### Uncontrolled Mode
-2. 检查控制台是否有相关警告信息
+```tsx
+import { ReactFabric, Rect, Group } from '@cs-open/react-fabric'
+
+function UncontrolledCanvas() {
+ return (
+
+
+
+
+
+ )
+}
+```
-3. 确保在触摸设备上测试
+### DOM Integration
-### 其他问题
+```tsx
+import { ReactFabric, Rect } from '@cs-open/react-fabric'
-如果遇到其他问题，请检查：
+function CanvasWithDOM() {
+ return (
+
+
+ This is a tooltip
+
+
+ )
+}
+```
-1. 所有必需依赖是否正确安装
-2. 浏览器控制台是否有错误信息
-3. 确保使用兼容的浏览器版本
+## 📋 Dependency Requirements
-DOM control
+### Required Dependencies
-```jsx
-
-
-
-
-
+```json
+{
+ "react": ">=17.0.0",
+ "react-dom": ">=17.0.0",
+ "fabric": "^6.6.1",
+ "zustand": "^4.0.0 || ^5.0.0"
+}
```
-## 许可证
+### Optional Dependencies
-MIT
+Some plugins require additional dependencies:
-```jsx
-pnpm run changeset // 修改 changeset.md
-全选 changed & unchanged enter
-不选 enter major
-不选 enter minor
-Summary 随便写
-desired changeset ? true
-pnpm run version-packages // 修改 package.json 的 version
-pnpm install // 修改 lock 文件
-git add .
-git commit -m 'chore(core): version bump'
-git push
-提交pr到main
-通过 github action 自动发布到 npm
+```bash
+# Touch gesture support
+npm install hammerjs
+npm install @types/hammerjs # TypeScript users
+
+# Floating UI support (for DOM integration)
+npm install @floating-ui/react
```
+
+## 🤝 Contributing
+
+Welcome to submit Issues and Pull Requests!
+
+1. Fork this repository
+2. Create feature branch (`git checkout -b feature/AmazingFeature`)
+3. Commit changes (`git commit -m 'Add some AmazingFeature'`)
+4. Push to branch (`git push origin feature/AmazingFeature`)
+5. Open Pull Request
+
+## 📄 License
+
+This project is open source under the [MIT](LICENSE) license.
+
+## 🔗 Related Links
+
+- [Fabric.js Official Documentation](http://fabricjs.com/)
+- [React Official Documentation](https://reactjs.org/)
+- [Project Homepage](https://cs-open.github.io/react-fabric/)
+- [GitHub Repository](https://github.com/cs-open/react-fabric)
+
+---
+
+**Made with ❤️ by the CS-Open team**
+
+