uview-plus

# Cropper 图片裁剪 3.4.85

打开

图片裁剪组件，支持手势操作、旋转、缩放、裁剪等功能，适用于头像裁剪等场景。

# 平台差异说明

App（vue） App（nvue） H5 小程序
√ √ √ √

# 基本使用

通过 ref 获取组件实例，调用 chooseImage 方法选择图片进行裁剪；如果业务已经通过拍照、选图等方式取得临时图片路径，可在第二个参数中传入 imageSrc 直接开始裁剪。

# 头像裁剪模式

设置固定裁剪区域大小，适用于头像裁剪等场景。

<template>
  <view>
    <up-cropper 
      ref="avatarCropperRef"
      :canChangeSize="false"
      areaWidth="300rpx" 
      areaHeight="300rpx" 
      exportWidth="260rpx" 
      exportHeight="260rpx"
      @confirm="onAvatarConfirm"
    >
      <view class="avatar-wrapper">
        <up-avatar :src="avatarImage" size="120px"></up-avatar>
      </view>
    </up-cropper>
  </view>
</template>

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

const avatarImage = ref('');
const avatarCropperRef = ref(null);

const onAvatarConfirm = (rsp) => {
  avatarImage.value = rsp.path;
};
</script>

<script>
export default {
  data() {
    return {
      avatarImage: ''
    }
  },
  methods: {
    onAvatarConfirm(rsp) {
      this.avatarImage = rsp.path;
    }
  }
}
</script>

# 裁剪已有临时图片

业务可以先自行拍照或选图，再把得到的临时图片路径传给 Cropper。传入有效 imageSrc 时，组件不会再次打开系统图片选择器。

<template>
  <view>
    <button @click="takePhotoAndCrop">拍照或选图后裁剪</button>
    <up-cropper ref="externalCropperRef" @confirm="onExternalConfirm" />
  </view>
</template>

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

const externalCropperRef = ref(null);
const croppedImage = ref('');

const takePhotoAndCrop = () => {
  uni.chooseImage({
    count: 1,
    success: (res) => {
      externalCropperRef.value.chooseImage(0, {
        imageSrc: res.tempFilePaths[0],
        areaWidth: '300rpx',
        areaHeight: '300rpx'
      });
    }
  });
};

const onExternalConfirm = (rsp) => {
  croppedImage.value = rsp.path;
};
</script>

<script>
export default {
  data() {
    return {
      croppedImage: ''
    }
  },
  methods: {
    takePhotoAndCrop() {
      uni.chooseImage({
        count: 1,
        success: (res) => {
          this.$refs.externalCropperRef.chooseImage(0, {
            imageSrc: res.tempFilePaths[0],
            areaWidth: '300rpx',
            areaHeight: '300rpx'
          });
        }
      });
    },
    onExternalConfirm(rsp) {
      this.croppedImage = rsp.path;
    }
  }
}
</script>
```

# 可变裁剪区域

允许用户调整裁剪区域大小，适用于需要自定义裁剪区域的场景。

<template>
  <view>
    <view class="image-wrapper" @click="chooseCustomImage">
      <up-image :src="customImage" height="160px"></up-image>
    </view>
    <up-cropper 
      ref="customCropperRef"
      @confirm="onCustomConfirm"
    />
  </view>
</template>

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

const customImage = ref('');
const customCropperRef = ref(null);

const chooseCustomImage = () => {
  customCropperRef.value.chooseImage(0, {
    canChangeSize: true,
    areaWidth: "300rpx", 
    areaHeight: "180rpx",
    exportWidth: '260rpx', 
    exportHeight: '160rpx'
  });
};

const onCustomConfirm = (rsp) => {
  customImage.value = rsp.path;
};
</script>

<script>
export default {
  data() {
    return {
      customImage: ''
    }
  },
  methods: {
    chooseCustomImage() {
      this.$refs.customCropperRef.chooseImage(0, {
        canChangeSize: true,
        areaWidth: "300rpx", 
        areaHeight: "180rpx",
        exportWidth: '260rpx', 
        exportHeight: '160rpx'
      });
    },
    onCustomConfirm(rsp) {
      this.customImage = rsp.path;
    }
  }
}
</script>
```

# Props

参数 说明 类型 默认值 可选值
canChangeSize 是否允许调整裁剪区域大小 boolean false true/false
areaWidth 裁剪区域宽度 string 300rpx -
areaHeight 裁剪区域高度 string 300rpx -
exportWidth 导出图片宽度 string 260rpx -
exportHeight 导出图片高度 string 260rpx -
minScale 最小缩放比例 number 0.3 -
maxScale 最大缩放比例 number 4 -
canScale 是否允许缩放 boolean true true/false
canRotate 是否允许旋转 boolean true true/false
inner 是否限制裁剪框始终在图片内（开启后不可旋转） boolean false true/false
quality 图片质量 number 0.9 0-1
noTab 是否隐藏底部操作栏 boolean true true/false

# Events

事件名 说明 回调参数
confirm 裁剪完成时触发 { avatar, path, index, data }
avtinit 组件初始化完成时触发 -

# Slots

名称 说明
default 触发裁剪的元素，点击该插槽内容时会打开裁剪界面

# 方法

方法名 说明 参数
chooseImage 选择图片或加载已有路径并开始裁剪 (index, params, data)
index: 索引标识
params: 配置参数对象；imageSrc 为非空字符串时直接加载该路径并跳过系统选图
data: 自定义数据
close 关闭裁剪界面 -
rotate 旋转图片 -
preview 预览裁剪结果 -

# 注意事项

  1. 使用[chooseImage]方法时，可以通过第二个参数传入配置项来临时改变裁剪区域大小等属性
  2. 裁剪完成后会返回临时文件路径，可用于上传或展示
  3. 支持手势操作：单指拖动图片，双指缩放图片
  4. 可通过canChangeSize属性控制是否允许调整裁剪区域大小
  5. 在H5平台可能需要处理跨域图片问题
  6. 设置 inner 为 true 时，裁剪框始终保持在图片范围内，适合头像等禁止留白场景；该模式下旋转会被禁用
  7. chooseImage 的第二个参数也可传 inner: true 临时开启
  8. params.imageSrc 仅在值为非空字符串时生效；未传、空字符串或非字符串仍会打开系统图片选择器
  9. imageSrc 必须能被当前平台的 uni.getImageInfo 和画布读取；远程地址在 H5 仍受跨域配置限制，组件不会自动下载或转换地址
  10. 使用外部路径进入裁剪后，底部“重选”按钮仍会打开系统图片选择器

← Signature 签名 →