Vue Image Annotator

一个基于 Vue 3 的图片标注工具组件，支持在图片上进行绘画、标注、添加文字等操作，并可导出标注后的图片。

特性

• 🎨 多种标注工具：画笔、矩形、圆形、箭头、直线、文字、马赛克、橡皮擦
• 📷 多种上传方式：支持拖拽、点击、粘贴上传图片
• ↩️ 撤销/重做：支持操作历史管理
• 🖼️ 图片导出：支持导出为 PNG/JPEG 格式
• 🌓 主题支持：支持亮色/暗色主题
• 📱 触摸支持：支持移动端触摸操作
• 🎯 TypeScript 友好：完整的类型提示

安装

npm install vue-image-annotator
# 或
yarn add vue-image-annotator
# 或
pnpm add vue-image-annotator

使用

基础使用

<template>
  <ImageAnnotator
    :image="imageUrl"
    @change="handleChange"
    @export="handleExport"
  />
</template>

<script setup>
import { ref } from 'vue'
import ImageAnnotator from 'vue-image-annotator'
import 'vue-image-annotator/style.css'

const imageUrl = ref('/path/to/image.jpg')

const handleChange = (annotations) => {
  console.log('标注数据:', annotations)
}

const handleExport = (blob) => {
  // 下载导出的图片
  const url = URL.createObjectURL(blob)
  const a = document.createElement('a')
  a.href = url
  a.download = 'annotated-image.png'
  a.click()
  URL.revokeObjectURL(url)
}
</script>

自定义工具

<template>
  <ImageAnnotator
    :image="imageUrl"
    :tools="['pen', 'arrow', 'rect', 'text']"
    :default-color="'#00ff00'"
    :default-stroke-width="3"
  />
</template>

编程式控制

<template>
  <div>
    <ImageAnnotator ref="annotatorRef" :image="imageUrl" />
    <button @click="handleExport">导出</button>
    <button @click="handleUndo">撤销</button>
    <button @click="handleRedo">重做</button>
    <button @click="handleClear">清空</button>
  </div>
</template>

<script setup>
import { ref } from 'vue'
import ImageAnnotator from 'vue-image-annotator'
import 'vue-image-annotator/style.css'

const annotatorRef = ref(null)
const imageUrl = ref('/path/to/image.jpg')

const handleExport = () => {
  annotatorRef.value?.exportImage('png')
}

const handleUndo = () => {
  annotatorRef.value?.undo()
}

const handleRedo = () => {
  annotatorRef.value?.redo()
}

const handleClear = () => {
  annotatorRef.value?.clear()
}
</script>

Props

| 属性 | 类型 | 默认值 | 说明 | |------|------|--------|------| | image | String \| File \| Blob | null | 图片源（URL、File、Blob） | | initialAnnotations | Array | [] | 初始标注数据 | | tools | Array | ['pen', 'arrow', 'rect', 'circle', 'line', 'text', 'mosaic', 'eraser'] | 启用的工具列表 | | defaultColor | String | '#ff0000' | 默认画笔颜色 | | defaultStrokeWidth | Number | 2 | 默认线条粗细 | | defaultFontSize | Number | 16 | 默认字体大小 | | showToolbar | Boolean | true | 是否显示工具栏 | | showSidebar | Boolean | true | 是否显示侧边栏 | | enableUpload | Boolean | true | 是否允许上传 | | width | String \| Number | '100%' | 容器宽度 | | height | String \| Number | 'auto' | 容器高度 | | maxHistory | Number | 50 | 最大历史记录数 | | dark | Boolean | false | 是否使用暗色主题 |

Events

| 事件 | 参数 | 说明 | |------|------|------| | ready | - | 组件初始化完成 | | change | annotations: Array | 标注数据变化 | | tool-change | tool: String | 工具切换 | | export | blob: Blob | 导出图片 | | error | error: String | 错误发生 |

Methods

通过 ref 调用组件方法：

| 方法 | 参数 | 说明 | |------|------|------| | exportImage | (format: 'png' \| 'jpeg', quality: number) | 导出图片 | | undo | - | 撤销 | | redo | - | 重做 | | clear | - | 清空所有标注 | | setTool | (tool: string) | 设置当前工具 | | setColor | (color: string) | 设置颜色 | | setStrokeWidth | (width: number) | 设置线条粗细 | | setFontSize | (size: number) | 设置字体大小 | | getAnnotations | - | 获取所有标注数据 | | setAnnotations | (annotations: Array) | 设置标注数据 | | loadImage | (source: String \| File \| Blob) | 加载图片 | | getCanvasElement | - | 获取 Canvas 元素 |

标注数据结构

// 画笔标注
{
  id: 'ann_xxx',
  type: 'pen',
  color: '#ff0000',
  strokeWidth: 2,
  data: {
    points: [{ x: 10, y: 10 }, { x: 20, y: 20 }, ...]
  },
  timestamp: 1234567890
}

// 矩形标注
{
  id: 'ann_xxx',
  type: 'rect',
  color: '#ff0000',
  strokeWidth: 2,
  data: {
    x: 10,
    y: 10,
    width: 100,
    height: 50
  },
  timestamp: 1234567890
}

// 圆形标注
{
  id: 'ann_xxx',
  type: 'circle',
  color: '#ff0000',
  strokeWidth: 2,
  data: {
    cx: 100,
    cy: 100,
    radius: 50
  },
  timestamp: 1234567890
}

// 箭头标注
{
  id: 'ann_xxx',
  type: 'arrow',
  color: '#ff0000',
  strokeWidth: 2,
  data: {
    startX: 10,
    startY: 10,
    endX: 100,
    endY: 100
  },
  timestamp: 1234567890
}

// 直线标注
{
  id: 'ann_xxx',
  type: 'line',
  color: '#ff0000',
  strokeWidth: 2,
  data: {
    startX: 10,
    startY: 10,
    endX: 100,
    endY: 100
  },
  timestamp: 1234567890
}

// 文字标注
{
  id: 'ann_xxx',
  type: 'text',
  color: '#ff0000',
  strokeWidth: 1,
  data: {
    x: 10,
    y: 10,
    text: '标注文字',
    fontSize: 16,
    fontFamily: 'Arial, sans-serif'
  },
  timestamp: 1234567890
}

// 马赛克标注
{
  id: 'ann_xxx',
  type: 'mosaic',
  color: '#000000',
  strokeWidth: 1,
  data: {
    x: 10,
    y: 10,
    width: 100,
    height: 50,
    blockSize: 10
  },
  timestamp: 1234567890
}

工具类型

| 工具 | 名称 | 说明 | |------|------|------| | pen | 画笔 | 自由绘制 | | rect | 矩形 | 绘制矩形框 | | circle | 圆形 | 绘制圆形 | | arrow | 箭头 | 绘制箭头 | | line | 直线 | 绘制直线 | | text | 文字 | 添加文字标注 | | mosaic | 马赛克 | 添加马赛克遮罩 | | eraser | 橡皮擦 | 删除标注 |

本地开发

# 安装依赖
npm install

# 启动开发服务器
npm run dev

# 构建库
npm run build

# 预览构建结果
npm run preview

浏览器支持

• Chrome >= 60
• Firefox >= 55
• Safari >= 12
• Edge >= 79

License

MIT