vue3-image-annotation

vue3-image-annotation

A Vue 3 image annotation component based on fabric.js — draw rect / circle / polygon annotations on images, with zoom & pan, undo/redo, data echo and PNG export.

基于 fabric.js 的 Vue3 在线图片标注组件。

提供 <ImageCaption /> 组件：缩略图区域 + 主标注区域 + 工具区域，支持矩形、圆形、多边形标注，支持选中拖动、删除、撤销/反撤销、标签管理、标注数据回显与获取。

特性

• 矩形 / 圆形拖拽绘制，多边形逐点点击绘制（双击或回车结束，ESC 取消）
• 已标注区域点击选中、按住拖动调整位置（自动限制在图片范围内，松开后重新计算标注坐标）
• 删除标注（工具栏按钮或 Delete / Backspace 键）
• 撤销 / 反撤销（Ctrl+Z / Ctrl+Shift+Z / Ctrl+Y，按图片独立记录）
• 每个标注可关联标签名称，支持自由输入或从预设标签列表选择
• 鼠标滚轮缩放（以鼠标位置为中心）、左键拖动空白平移、fit 视野
• 标注坐标基于图片原始像素存储，任何缩放/平移状态下坐标不会错位
• 屏幕尺寸变化自适应
• 支持已有标注数据回显、继续编辑
• 提供 TypeScript 类型声明，同时兼容非 TS 项目
• 零 UI 框架依赖（按钮/下拉/提示均为自绘实现，不引入 element-plus 等组件库，与宿主项目任何 UI 框架无冲突）

示例截图

环境要求

• Vue ^3.2.0
• Node >= 18（仅本地开发/构建需要）

fabric 为组件库唯一运行时依赖（dependencies），安装本组件时会自动安装，无需手动处理。

安装

pnpm add vue3-image-annotation
# 或
npm install vue3-image-annotation
# 或
yarn add vue3-image-annotation

使用方式

方式一：全局注册（推荐，vue.use 方式）

// main.ts
import { createApp } from 'vue'
import ImageCaption from 'vue3-image-annotation'
import 'vue3-image-annotation/style.css'
import App from './App.vue'

const app = createApp(App)
app.use(ImageCaption) // 全局注册 <ImageCaption /> 组件
app.mount('#app')

<!-- 任意组件中直接使用 -->
<template>
  <ImageCaption
    :images="images"
    :labels="['行人', '车辆', '建筑']"
    style="height: 640px"
  >
    <!-- 可选：自定义操作区（工具栏右侧），如保存按钮 -->
    <template #actions>
      <button class="ic-btn ic-btn--primary" @click="handleSave">保存</button>
    </template>
  </ImageCaption>
</template>

方式二：按需引入

<script setup lang="ts">
import { ImageCaption } from 'vue3-image-annotation'
import 'vue3-image-annotation/style.css'
</script>

<template>
  <ImageCaption :images="images" />
</template>

非 TypeScript 项目中按普通组件使用即可（组件已编译为 JS，类型声明可选）。

组件 API

Props

Events

插槽

保存数据最佳实践

组件不内置保存按钮（数据何时、如何持久化由宿主决定），提供两种常用模式：

模式一：实时保存 —— 监听 change 事件，标注每次变化自动提交：

<script setup lang="ts">
import { ref } from 'vue'
import type { AnnotationData } from 'vue3-image-annotation'

const images = ref([
  { id: 'img-1', url: 'https://example.com/a.jpg' },
])

async function handleChange(imageId: string, annotations: AnnotationData[]) {
  await fetch(`/api/annotations/${imageId}`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(annotations),
  })
}
</script>

<template>
  <ImageCaption :images="images" @change="handleChange" style="height: 640px" />
</template>

模式二：手动保存 —— 通过 actions 插槽放自己的按钮，点击时从 ref 获取数据（可携带页面其他表单字段一起提交）：

<script setup lang="ts">
import { ref } from 'vue'

const captionRef = ref()

async function handleSave() {
  const imageId = captionRef.value.currentImageId
  const annotations = captionRef.value.getAnnotations()
  await fetch(`/api/annotations/${imageId}`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(annotations),
  })
}
</script>

<template>
  <ImageCaption ref="captionRef" :images="images" style="height: 640px">
    <template #actions>
      <button class="ic-btn ic-btn--primary" @click="handleSave">保存</button>
    </template>
  </ImageCaption>
</template>

组件方法（通过 ref 调用）

import { ref } from 'vue'

const captionRef = ref()

// 获取当前图片标注数据
captionRef.value.getAnnotations()
// 获取指定图片标注数据
captionRef.value.getAnnotations('img-1')
// 获取全部图片标注数据 { [imageId]: AnnotationData[] }
captionRef.value.getAllAnnotations()
// 撤销 / 反撤销
captionRef.value.undo()
captionRef.value.redo()
// 删除当前选中标注
captionRef.value.deleteSelected()
// 清空当前图片标注
captionRef.value.clearCurrent()
// 视图控制
captionRef.value.zoomIn()
captionRef.value.zoomOut()
captionRef.value.fitView()
// 导出当前图片（含标注）的 PNG dataURL（图片原始像素尺寸，可用于自定义上传等场景）
const dataUrl = captionRef.value.exportImage()
// 当前图片 id（手动保存时配合 getAnnotations 使用）
const imageId = captionRef.value.currentImageId
// 切换图片
captionRef.value.switchImage('img-2')

数据类型

type AnnotationType = 'rect' | 'circle' | 'polygon'

interface Point {
  x: number
  y: number
}

interface AnnotationData {
  id: string
  type: AnnotationType
  label: string
  /** rect / circle：外接框左上角坐标与宽高 */
  x?: number
  y?: number
  width?: number
  height?: number
  /** polygon：顶点列表 */
  points?: Point[]
}

interface ImageItem {
  id: string
  url: string
  name?: string
  /** 已有标注，加载后回显 */
  annotations?: AnnotationData[]
}

所有坐标均为图片原始像素坐标（与画布缩放无关），可直接用于业务存储与换算。

交互说明

标注对象不支持控制柄缩放（避免坐标换算误差），画错可删除重画或撤销。

本地开发

本项目统一使用 pnpm 作为包管理工具。

# 安装依赖
pnpm install

# 启动 demo 演示页（examples/）
pnpm dev

# 库构建（产物输出至 dist/）
pnpm build

# 类型检查
pnpm typecheck

License

MIT