UviewUltra 4.0

Appearance

Cropper 图片裁剪 4.4.0 ​

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

平台差异说明 ​

|App（vue）|App（uvue/uni-app-x）|App（nvue）|H5|小程序| |:-😐:-😐:-😐:-😐:-😐:-😐 |√|√|√|√|

基本使用 ​

通过ref获取组件实例，调用chooseImage方法选择图片进行裁剪。

头像裁剪模式 ​

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

vue
<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>
js
<script setup>
import { ref } from 'vue';

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

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

可变裁剪区域 ​

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

vue
<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>
js
<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>

裁剪已有图片 ​

有些业务会自行拍照或选图（例如先调用 uni.chooseImage、相机、或从服务端下载），拿到路径后才需要裁剪。 此时给 chooseImage 的第二个参数传入 imageSrc，组件会直接裁剪该路径，不再打开系统选图。

vue
<template>
  <view>
    <view class="image-wrapper" @click="cropExistingImage">
      <up-image :src="existingImage" height="160px"></up-image>
    </view>
    <up-cropper
      ref="existingCropperRef"
      @confirm="onExistingConfirm"
    />
  </view>
</template>
js
<script setup>
import { ref } from 'vue';

const existingImage = ref('');
const existingCropperRef = ref(null);

const cropExistingImage = () => {
  // 业务侧自行选图/拍照，拿到路径后再交给裁剪器
  uni.chooseImage({
    count: 1,
    success: (res) => {
      existingCropperRef.value.chooseImage(0, {
        imageSrc: res.tempFilePaths[0],
        areaWidth: '300rpx',
        areaHeight: '300rpx',
        exportWidth: '260rpx',
        exportHeight: '260rpx'
      });
    }
  });
};

const onExistingConfirm = (rsp) => {
  existingImage.value = rsp.path;
};
</script>

Props ​

参数说明类型默认值可选值
canChangeSize是否允许调整裁剪区域大小booleanfalsetrue/false
areaWidth裁剪区域宽度string300rpx-
areaHeight裁剪区域高度string300rpx-
exportWidth导出图片宽度string260rpx-
exportHeight导出图片高度string260rpx-
minScale最小缩放比例number0.3-
maxScale最大缩放比例number4-
canScale是否允许缩放booleantruetrue/false
canRotate是否允许旋转booleantruetrue/false
inner是否限制裁剪框始终在图片内（开启后不可旋转）booleanfalsetrue/false
quality图片质量number0.90-1
noTab是否隐藏底部操作栏booleantruetrue/false

Events ​

事件名说明回调参数
confirm裁剪完成时触发
avtinit组件初始化完成时触发-

Slots ​

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

方法 ​

方法名说明参数
chooseImage打开图片选择器并开始裁剪；传入 params.imageSrc 时直接裁剪该路径(index, params, data)
index: 索引标识
params: 配置参数对象
data: 自定义数据
close关闭裁剪界面-
rotate旋转图片-
preview预览裁剪结果-

注意事项 ​

  1. 使用[chooseImage]方法时，可以通过第二个参数传入配置项来临时改变裁剪区域大小等属性
  2. 裁剪完成后会返回临时文件路径，可用于上传或展示
  3. 支持手势操作：单指拖动图片，双指缩放图片
  4. 可通过canChangeSize属性控制是否允许调整裁剪区域大小
  5. 在H5平台可能需要处理跨域图片问题
  6. 设置 inner 为 true 时，裁剪框始终保持在图片范围内，适合头像等禁止留白场景；该模式下旋转会被禁用
  7. chooseImage 的第二个参数也可传 inner: true 临时开启
  8. 4.5.31 chooseImage 的第二个参数支持 imageSrc：传入非空字符串路径时直接裁剪该图片并跳过系统选图；不传、空字符串或非字符串仍打开系统选图。路径需为当前平台可被 uni.getImageInfo 读取的地址（本地临时路径、相册路径或同源网络图片）
  9. 通过 imageSrc 进入裁剪后，点击「重选」仍会打开系统选图，不会重复加载传入的路径