更新记录

1.0.0（2026-10-11）

• 首个版本发布
• 支持正方形 / 任意矩形 / 圆形三种裁剪模式
• 支持通过属性控制矩形、圆形模式切换开关
• 支持图片拖动、双指缩放、90° 旋转
• 裁剪框支持拖动位置与手柄缩放
• 裁剪框外半透明遮罩，透明度可配置
• 支持重置、重选
• 新增 resizable 属性，可控制是否允许拖动 / 缩放裁剪框
• 支持电脑鼠标操作：左键拖拽、滚轮缩放
• 图片变换覆盖约束：拖动 / 缩放 / 旋转 / 调整裁剪框时始终填满裁剪框，不露白
• 拖动 / 缩放图片时框外遮罩自动变亮，突出裁剪区域
• 修复圆形裁剪导出位置偏移：改为整块舞台画布绘制后按裁剪区域截取
• 导出高清 PNG，圆形模式导出透明背景圆形图

平台兼容性

uni-app(5.0)

其他

hy-avatar-cropper 头像裁剪

hy-avatar-cropper 是一个功能完整、开箱即用的头像 / 图片裁剪组件，基于 uni-app 编写，兼容 Vue2 / Vue3。

功能特性

• 默认正方形裁剪，一键切换任意矩形或圆形裁剪
• 可通过属性开关控制是否允许切换矩形 / 圆形
• 裁剪框可自由拖动位置（拖边框移动，拖手柄缩放）
• 图片支持拖动、双指缩放、90° 旋转
• 裁剪框外自动添加半透明遮罩，突出裁剪区域（透明度可调）
• 内置重置（还原图片变换与裁剪框）、重选（重新选择图片）操作
• 导出高清 PNG，圆形模式导出为透明背景圆形图

安装

将 hy-avatar-cropper 目录放入项目的 uni_modules 目录即可，组件已支持 easycom，无需手动 import。

基本用法

<template>
    <view>
        <image :src="avatar" mode="aspectFill" />
        <button @tap="chooseImage">选择图片</button>

        <hy-avatar-cropper
            :show.sync="showCropper"
            :src="src"
            title="裁剪头像"
            mode="square"
            :allow-rect="true"
            :allow-circle="true"
            :allow-rotate="true"
            @confirm="onConfirm"
            @cancel="onCancel"
        />
    </view>
</template>

<script>
export default {
    data() {
        return {
            showCropper: false,
            src: '',
            avatar: ''
        }
    },
    methods: {
        chooseImage() {
            uni.chooseImage({
                count: 1,
                success: (res) => {
                    this.src = res.tempFilePaths[0]
                    this.showCropper = true
                }
            })
        },
        onConfirm(e) {
            this.avatar = e.tempFilePath
            this.showCropper = false
        },
        onCancel() {
            this.showCropper = false
        }
    }
}
</script>

Vue3 项目请将 :show.sync="showCropper" 改为 v-model:show="showCropper"。

属性 Props

事件 Events

交互说明

• 拖动图片：单指按住裁剪框以外的区域拖动，拖动过程中框外遮罩自动变亮，进一步突出裁剪区域；图片会被自动约束，裁剪框内始终填满、不会露白
• 缩放图片：双指捏合，缩放过程中框外遮罩同步变亮，松手恢复；最小缩放会被限制为「刚好覆盖裁剪框」，无法缩到出现空白
• 旋转图片：点击底部「旋转」（每次 90°），旋转后自动重新约束，保证不露白
• 移动裁剪框：按住裁剪框边框拖动（正方形 / 矩形模式），移动后图片会自动吸附保证覆盖；resizable 为 false 时不可移动
• 缩放裁剪框：拖动四角手柄（正方形等比，矩形可自由拉伸），矩形模式还支持拖动四边中点调整单边；resizable 为 false 时手柄隐藏、不可缩放，框放大后图片会自动放大以覆盖
• 重置：还原图片变换与裁剪框到初始状态
• 重选：重新选择一张图片

电脑鼠标操作（H5 / PC）

组件同时支持鼠标操作，无需额外配置：

• 拖动图片 / 裁剪框：鼠标左键按住拖动
• 缩放图片：鼠标滚轮，以光标位置为中心缩放
• 缩放裁剪框：拖动四角 / 四边手柄
• 切换模式、旋转、重置、重选：点击对应按钮

平台支持

• App（vue 页面）：y
• H5（移动端 / PC）：y，PC 支持鼠标拖拽与滚轮缩放
• 各主流小程序：y
• nvue 页面：暂不支持

注意事项

1. 图片变换带有覆盖约束：无论拖动、缩放、旋转还是调整裁剪框，裁剪框内都会被图片填满，不会出现空白（透明边）。当裁剪框被拉得大于图片时，图片会自动放大以覆盖。
2. 圆形模式导出为带透明通道的 PNG，保存到不支持透明通道的格式（如 JPG）时会自动填充底色。
3. 像素倍率 pixelRatio 过高时，部分小程序平台存在 canvas 尺寸上限（如 4096px），请按需调整。