更新记录

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

1.0.0

• 首个版本发布
• 支持双指缩放、单指拖动图片
• 支持拖拽裁剪框、拖拽四角手柄调整裁剪框大小（保持宽高比）
• 支持 90° 旋转
• 支持自定义输出尺寸、裁剪比例与强调色
• 零第三方依赖

平台兼容性

uni-app(4.87)

snow-image-cropper 图片裁剪组件

基于 canvas 实现的 uni-app 图片裁剪组件。零第三方依赖，单文件引入，适用于头像上传、封面裁剪、图文配图等需要按固定比例裁剪图片的场景。

特性

• 双指缩放 / 单指拖动，图片始终覆盖裁剪框，不会出现空白
• 拖拽裁剪框整体移动，拖拽四角 L 形手柄调整裁剪框大小（自动保持传入的宽高比，对角固定）
• 90° 旋转（每次 90°）
• 自定义导出尺寸（outputWidth / outputHeight）与裁剪比例（ratio）
• 自定义强调色（accentColor）
• 裁剪框内三分辅助线，便于构图
• 组件内部自动测量画布尺寸并居中，无需外部计算布局

平台支持

基于 canvas-id + uni.createCanvasContext 的老式canvas 方案实现，仅在 App 端（vue 页面，非 nvue）验证通过。

安装

// 从插件市场搜索「图片裁剪组件」导入，或手动将本目录放到项目的 uni_modules 下

组件符合 easycom 规范，导入到 uni_modules/snow-image-cropper/ 后无需注册即可使用：

<!-- 标签名即插件名：snow-image-cropper -->
<snow-image-cropper ref="cropper" :visible="visible" :src="src" />

使用示例

<template>
    <view class="page">
        <image v-if="croppedPath" :src="croppedPath" mode="aspectFill"
            style="width: 200rpx; height: 200rpx; border-radius: 12rpx;"></image>

        <button @click="chooseImage">选择图片</button>

        <!-- 裁剪组件：visible 控制显示，src 传图片路径 -->
        <snow-image-cropper
            :visible="visible"
            :src="src"
            :ratio="1"
            :output-width="500"
            :output-height="500"
            :accent-color="'#0E8D6E'"
            @confirm="onConfirm"
            @cancel="onCancel"
        />
    </view>
</template>

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

属性说明

事件说明

常见问题

Q：组件是全覆盖遮罩，会不会挡住页面其他元素？ 会。visible 为 true 时会渲染一个 position: fixed、z-index: 999999 的全屏遮罩，请在 @cancel / @confirm 中及时把 visible 置回 false。

Q：为什么小程序不支持？ 小程序原生 canvas 属于原生组件，层级最高，会盖住上层的 footer 按钮，导致「确定」「取消」无法点击。

Q：H5 端返回的值和 App 端不一样吗？ 不一样。H5 上 uni.canvasToTempFilePath 返回的是 base64 数据字符串，不是本地临时路径。若要在 H5 使用，@confirm 回调里拿到的值需自行判断是路径还是 base64 再处理。本插件未在 H5 上做过完整验证。

Q：nvue 为什么不支持？ nvue 不支持 canvas-id 的 uni.createCanvasContext 方案，需要改用 subNVue 或 uvue 重写。

许可证

MIT