创建中文版 README

cat > README.zh-CN.md << 'EOL'

React 图片标注组件

简介

一个轻量级的 React 图片标注组件，支持矩形框标注、拖拽调整、大小更改等功能。适用于图片标注、目标检测标注、图片裁剪等场景。

特点

• 🎯 支持矩形框标注
  • 点击拖拽绘制矩形框
  • 自动计算坐标和尺寸
  • 实时绘制预览
• 🖱️ 拖拽移动标注位置
  • 平滑的拖拽体验
  • 自动吸附到图片边界
  • 保持相对位置不变
• 📏 八个方向调整大小
  • 四个角点调整
  • 四个边调整
  • 保持宽高比例（可选）
• 🗑️ 一键删除标注
  • 悬浮显示删除按钮
  • 点击即可删除
  • 支持撤销/重做（开发中）
• 🔒 自动限制标注在图片范围内
  • 绘制时限制范围
  • 拖拽时限制范围
  • 调整大小时限制范围
• 🎨 自定义样式支持
  • 自定义边框样式
  • 自定义控制点样式
  • 自定义删除按钮样式

安装

npm install react-image-annotation
# 或
yarn add react-image-annotation

使用示例

import { ImageAnnotation } from 'react-image-annotation';

function Demo() {
  const [annotations, setAnnotations] = useState([]);

  return (
    <ImageAnnotation
      src="/path/to/image.png"
      width={800}
      coordinates={annotations}
      onDraw={(coordinate, index, coordinates) => {
        setAnnotations(coordinates);
      }}
      onDelete={(coordinate, index, coordinates) => {
        setAnnotations(coordinates);
      }}
    />
  );
}

API 文档

属性

| 属性 | 说明 | 类型 | 默认值 | |------|------|------|--------| | src | 图片地址 | string | - | | coordinates | 标注数据 | Coordinate[] | [] | | width | 图片宽度 | number | - | | height | 图片高度 | number | - |

事件

| 事件名 | 说明 | 参数 | |--------|------|------| | onDraw | 绘制标注时触发 | (coordinate, index, coordinates) | | onDrag | 拖拽标注时触发 | (coordinate, index, coordinates) | | onResize | 调整大小时触发 | (coordinate, index, coordinates) | | onDelete | 删除标注时触发 | (coordinate, index, coordinates) | | onLoad | 图片加载完成时触发 | (event) |

数据结构

interface Coordinate {
  id: string;     // 唯一标识
  x: number;      // 横坐标（相对于图片左上角）
  y: number;      // 纵坐标（相对于图片左上角）
  width: number;  // 宽度（像素）
  height: number; // 高度（像素）
}

交互说明

绘制标注

1. 在图片上按下鼠标左键
2. 拖动鼠标绘制矩形
3. 松开鼠标完成绘制

移动标注

1. 鼠标移动到已有标注上
2. 按住标注中心区域
3. 拖动到目标位置
4. 松开鼠标完成移动

调整大小

1. 鼠标移动到标注边框或角点
2. 出现调整手柄
3. 拖动手柄调整大小
4. 松开鼠标完成调整

删除标注

1. 鼠标悬浮在标注上
2. 点击右上角的删除按钮
3. 标注被立即删除

注意事项

1. 所有坐标值均为相对于图片左上角的像素值
2. 标注框不能超出图片边界
3. 建议设置合适的图片尺寸以获得最佳体验
4. 组件会自动处理图片加载和错误状态
5. 支持触摸设备，但体验可能不如鼠标操作

本地开发

# 安装依赖
npm install

# 启动 Storybook
npm run storybook

# 运行测试
npm test

# 构建
npm run build

浏览器兼容性

• Chrome >= 61
• Firefox >= 60
• Safari >= 11
• Edge >= 16

贡献指南

欢迎提交 Issue 和 Pull Request。在提交 PR 之前，请确保：

1. 添加/更新测试用例
2. 更新相关文档
3. 遵循代码规范

许可证

MIT EOL