更新记录

1.0.0（2026-08-12）

• 初始发布：涂鸦/文字/箭头/图形/标记/裁剪/旋转/翻转/撤销重做/合成导出

平台兼容性

uni-app(5.23)

wc-image-annotator 图片标注组件

一个功能完整、高性能的 uni-app 图片标注/编辑器 组件，支持涂鸦、文字、箭头、图形、标记、裁剪、旋转、翻转，并把底图与标注合成导出为图片文件。

兼容：微信小程序（完整）/ H5（尽力）/ App（尽力）。零第三方依赖（仅依赖 Vue3 + uni-app 原生 API），可直接作为 uni-app 插件市场插件发布。

功能特性

• 涂鸦 / 手写笔迹（可调粗细、颜色）
• 文字标注（可调字号、颜色、字重）
• 箭头、圆圈、方框、三角（拖拽画出）
• 多种元素标记（点击放置）
• 裁剪（多比例预设 + 自由裁剪 + 旋转 + 水平/垂直翻转）
• 整体旋转（90° 步进、带缓动动画）
• ↩ ↪ 撤销 / 重做（历史栈上限 50）
• 保存：合成底图与标注，高清导出（微信小程序通过 canvas 2d 导出）

安装

将 wc-image-annotator.vue、enums.ts、index.ts 拷贝到你的项目（推荐放在 components/wc-image-annotator/ 下）。

easycom 方式（推荐）：在 pages.json 的 easycom 配置中声明：

{
  "easycom": {
    "autoscan": true,
    "custom": {
      "^wc-image-annotator$": "@/components/wc-image-annotator/wc-image-annotator.vue"
    }
  }
}

手动引入方式：

import WcImageAnnotator from '@/components/wc-image-annotator/wc-image-annotator.vue';

基本用法

<template>
    <view class="page">
        <wc-image-annotator
            :image-url="imageUrl"
            @cancel="onCancel"
            @save="onSave"
            @change="onChange"
        />
    </view>
</template>

<script setup lang="ts">
import { ref } from 'vue';
import WcImageAnnotator from '@/components/wc-image-annotator/wc-image-annotator.vue';
import type { AnnotationItem } from '@/components/wc-image-annotator';

const annotatorRef = ref<InstanceType<typeof wc-image-annotator> | null>(null);
const imageUrl = ref('https://example.com/a.jpg');

const onCancel = () => console.log('取消');
const onSave = (tempFilePath: string, annotations: AnnotationItem[]) => {
    console.log('导出文件：', tempFilePath, '标注：', annotations);
};
const onChange = (annotations: AnnotationItem[]) => console.log('标注变化', annotations);
</script>

<style scoped>
.page { height: 100vh; }
</style>

Props

Events

组件方法（通过 ref 调用）

const annotatorRef = ref<InstanceType<typeof wc-image-annotator> | null>(null);

// 主动导出
const tempFilePath = await annotatorRef.value?.export();
// 回显标注
annotatorRef.value?.setAnnotations(savedAnnotations);

类型定义

组件相关的枚举、接口、常量统一从 @/components/wc-image-annotator（index.ts）导出：

import type { AnnotationItem, TextItem, ArrowItem } from '@/components/wc-image-annotator';
import { AnnotateTool, MarkerKind, ShapeKind } from '@/components/wc-image-annotator';

标注坐标说明

所有标注的坐标均为 图片本地坐标（相对图片原始左上角，单位像素）。如需在其它画布 / 场景回放，请配合原图尺寸 imageInfo 使用。

平台注意事项

• 微信小程序：完整功能，导出使用 canvas type="2d"。
• 「系统编辑」工具：仅微信小程序支持（调用微信原生图片编辑器），其他端点击会提示。
• H5 / App：canvas API 实现有差异，旋转/裁剪/导出建议真机验证；导出文件在 H5 走下载、App 走临时文件。
• 组件内部使用原生 uni.showToast / uni.showModal 提示，不依赖任何第三方 UI 库。

Changelog

v1.0.0

• 初始发布：涂鸦/文字/箭头/图形/标记/裁剪/旋转/翻转/撤销重做/合成导出
• 解耦外部依赖，内置轻提示，支持直接作为独立插件使用
• 新增可配置 props 与 ref 方法（export/getAnnotations/setAnnotations/reset/save）
• 新增 index.ts 类型/常量统一出口