更新记录

1.1.0（2026-07-13） 下载此版本

图片裁剪支持旋转

1.0（2026-06-17） 下载此版本

零依赖：自带弹窗，无需 uView 等 UI 库 跨端兼容：H5 + APP（含 Android 10 WebView）均已验证 精准裁剪：帧-图交叉区域算法，预览/生成图片与裁剪框视觉内容完全一致 垂直居中：任意尺寸图片（横版/竖版/正方形）在裁剪框中始终居中 手势交互：单指拖拽 + 双指缩放（最小宽度 = 裁剪框宽度） 可配置：裁剪框尺寸、输出尺寸、主题色、输出形状等均可自定义

平台兼容性

uni-app(3.8.0)

头像裁剪插件示例工程

基于 uni-app 的头像裁剪组件演示项目，展示如何快速集成和使用 avatar-cropper 插件。

项目简介

本项目是 avatar-cropper 图片裁剪插件的示例工程，演示如何在 uni-app 项目中集成和使用该组件。

功能特性

• ✅ 头像裁剪（圆形/方形）
• ✅ 单指拖拽移动图片
• ✅ 双指缩放调整大小
• ✅ 图片旋转（每次顺时针旋转 90°）
• ✅ 裁剪预览
• ✅ 零依赖开箱即用
• ✅ 支持 H5 和 APP（含 Android 10）

技术栈

• 框架：uni-app (Vue 3)
• 组件：avatar-cropper（自定义图片裁剪组件）
• 构建工具：HBuilderX

快速开始

环境要求

• HBuilderX 3.0+
• Node.js（HBuilderX 内置）

运行步骤

1. 克隆项目

git clone https://github.com/xyytwz/img-avatar-cropper.git
cd img-avatar-cropper-demo

2. 打开项目

使用 HBuilderX 打开项目根目录

3. 运行项目

• 菜单栏 → 运行 → 运行到浏览器 → 选择浏览器
• 或运行到手机/模拟器

项目结构

img-avatar-cropper/
├── img-cropper/                   # 插件发布目录（可独立发布到 dcloud 插件市场）
│   ├── components/
│   │   └── img-cropper/
│   │       └── img-cropper.vue    # 组件源码
│   ├── pages/
│   │   └── demo/
│   │       └── demo.vue           # 插件演示页
│   ├── package.json               # 插件元信息
│   └── readme.md                  # 插件文档
├── pages/
│   └── index/
│       └── index.vue              # 示例页面（头像裁剪演示）
├── uni_modules/
│   └── img-cropper/               # 裁剪组件插件（easycom 自动注册）
│       └── components/
│           └── img-cropper/
│               └── img-cropper.vue
├── static/                        # 静态资源
├── App.vue                        # 应用入口
├── main.js                        # 主入口文件
├── pages.json                     # 页面配置
├── manifest.json                  # 应用配置
└── README.md                      # 示例工程文档

核心代码示例

1. 页面中使用组件

<template>
  <view class="demo-page">
    <!-- 头像展示 -->
    <view class="avatar-box">
      <image
        v-if="avatarUrl"
        :src="avatarUrl"
        class="avatar"
        mode="aspectFill"
      />
      <view v-else class="avatar avatar-placeholder">
        <text class="placeholder-text">点击选择图片</text>
      </view>
    </view>

    <!-- 选择图片按钮 -->
    <button class="choose-btn" @click="chooseImage">选择图片并裁剪</button>

    <!-- 图片裁剪组件 -->
    <img-cropper
      ref="cropperRef"
      :output-width="800"
      :output-height="800"
      :frame-size="560"
      output-shape="circle"
      theme-color="#07c160"
      title="裁剪头像"
      @complete="onCropComplete"
      @cancel="onCropCancel"
      @error="onCropError"
    />
  </view>
</template>

<script setup>
import { ref } from 'vue';

const cropperRef = ref(null);
const avatarUrl = ref('');

const chooseImage = () => {
  uni.chooseImage({
    count: 1,
    sizeType: ['original'],
    sourceType: ['album', 'camera'],
    success: (res) => {
      const tempFilePath = res.tempFilePaths[0];
      cropperRef.value?.open(tempFilePath);
    },
  });
};

const onCropComplete = (tempFilePath) => {
  avatarUrl.value = tempFilePath;
  uni.showToast({ title: '裁剪完成', icon: 'success' });
  // 这里可以调用上传接口
  // uni.uploadFile({ url: '...', filePath: tempFilePath, ... })
};

const onCropCancel = () => {
  console.log('用户取消裁剪');
};

const onCropError = (error) => {
  console.error('裁剪出错:', error);
};
</script>

2. easycom 自动注册

在 pages.json 中配置 easycom：

{
  "easycom": {
    "autoscan": true,
    "custom": {}
  }
}

组件目录结构必须为：

uni_modules/
└── img-cropper/
    └── components/
        └── img-cropper/
            └── img-cropper.vue

组件 API

Props

Events

Methods

支持平台

常见问题

1. 图片不显示

问题：打开裁剪弹窗后图片不可见

原因：cropAreaHeight 在异步回调中赋值，导致 computed 计算出负数偏移

解决：已在 open() 中立即设置初始值

2. TypeScript 报错

问题：提示找不到 uni 或 vue 模块

原因：项目未配置 TypeScript 类型声明

解决：不影响运行，可忽略。如需类型支持，安装 @dcloudio/types

3. 裁剪结果与预览不一致

组件使用帧-图交叉区域算法，确保预览与生成图片完全一致。如遇问题，请检查：

• 图片路径是否正确
• 输出尺寸是否合理

插件文档

完整插件文档请查看：img-cropper/readme.md

仓库地址

• GitHub：https://github.com/xyytwz/img-avatar-cropper.git
• 作者：xyytwz

许可证

MIT

更新日志

v1.1.0 (2026-07-13)

• ✨ 新增图片旋转功能，点击「旋转」按钮每次顺时针旋转 90°
• ✨ 增大裁剪区域上下留白，操作空间更大
• ✅ 旋转后裁剪输出与预览完全一致（canvas 旋转变换）

v1.0.0 (2026-06-17)

• ✨ 初始版本发布
• ✅ 支持 H5 和 APP 端
• ✅ 帧-图交叉区域算法
• ✅ 单指拖拽 + 双指缩放
• ✅ 圆形/方形裁剪