更新记录

1.0.0（2026-10-11） 下载此版本

• 首个版本发布（uni-app x / uvue + UTS）
• 支持正方形 / 任意矩形 / 圆形三种裁剪模式
• 支持通过属性控制矩形、圆形模式切换开关
• 支持图片拖动、双指缩放、90° 旋转
• 裁剪框支持拖动位置与手柄缩放
• 裁剪框外半透明遮罩，透明度可配置
• 支持重置、重选
• 新增 resizable 属性，可控制是否允许拖动 / 缩放裁剪框
• Web 平台支持鼠标操作：左键拖拽
• 图片变换覆盖约束：拖动 / 缩放 / 旋转 / 调整裁剪框时始终填满裁剪框，不露白
• 拖动 / 缩放图片时框外遮罩自动变亮，突出裁剪区域
• 裁剪结果以 base64 dataURL 返回（区别于 Vue2 版的临时文件路径）
• 提供完整示例页面 example/example.uvue

平台兼容性

uni-app x(5.07)

hy-avatar-cropper-x 图片裁剪器

hy-avatar-cropper-x 是一个基于 uni-app x（uvue + UTS） 的图片 / 头像裁剪组件。

与 Vue2 版 hy-avatar-cropper 的主要差异：本组件以 base64 dataURL 形式返回裁剪结果（而非临时文件路径）， 且脚本采用 <script setup lang="uts"> 写法。

功能特性

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

安装

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

需使用 uni-app x 项目（HBuilderX 编译到 App-Android / App-iOS / App-HarmonyOS / Web / 微信小程序）。

基本用法

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

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

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

    const showCropper = ref(false)
    const src = ref('')
    const avatar = ref('')

    type ConfirmResult = {
        dataURL : string,
        width : number,
        height : number,
        mode : string
    }

    const chooseImage = () => {
        uni.chooseImage({
            count: 1,
            success: (res) => {
                const paths = res.tempFilePaths
                if (paths.length == 0) return
                src.value = paths[0]
                showCropper.value = true
            }
        })
    }

    const onConfirm = (e : ConfirmResult) => {
        // 裁剪结果以 base64 dataURL 返回，可直接用于 image 的 src
        avatar.value = e.dataURL
        showCropper.value = false
    }

    const onCancel = () => {
        showCropper.value = false
    }
</script>

完整可运行示例见插件目录 example/example.uvue：将其拷入 uni-app x 工程并在 pages.json 中注册后即可预览。

属性 Props

事件 Events

交互说明

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

电脑鼠标操作（Web）

Web 平台基于 @mousedown / @mousemove / @mouseup 支持鼠标操作：

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

鼠标事件仅为 Web 平台能力，App 与小程序平台请使用触摸操作。

平台支持

注意事项

1. 导出结果为 base64 dataURL：confirm 事件返回的 dataURL 为完整 data:image/png;base64,... 字符串，可直接赋给 image 的 src。若需要临时文件路径，请自行将 base64 写入本地文件（如 App 端 uni.getFileSystemManager().writeFile）。
2. 图片变换带有覆盖约束：无论拖动、缩放、旋转还是调整裁剪框，裁剪框内都会被图片填满，不会出现空白（透明边）。
3. 圆形模式导出为带透明通道的 dataURL，保存到不支持透明通道的格式（如 JPG）时会自动填充底色。
4. 像素倍率 pixelRatio 过高时，部分平台存在 canvas 尺寸上限，请按需调整。