vue3【组件封装】头像裁剪 S-avatar.vue

已于 2025-07-28 15:34:55 修改
阅读量723 收藏 11
点赞数 22
CC 4.0 BY-SA版权
分类专栏： Vue3 文章标签： vue3 头像裁剪
于 2025-07-28 14:56:17 首次发布
版权声明：本文为博主原创文章，遵循 CC 4.0 BY-SA 版权协议，转载请附上原文出处链接和本声明。
本文链接：https://blog.csdn.net/weixin_41192489/article/details/149716009

最终效果

在这里插入图片描述
在这里插入图片描述

在这里插入图片描述
在这里插入图片描述

技术要点

图片裁剪

安装依赖 vue-cropper

npm install vue-cropper@next

专用于vue3 项目的图片裁剪，详细使用参考官方文档

页面使用

import "vue-cropper/dist/index.css";
import { VueCropper } from "vue-cropper";

<vue-cropper
  ref="cropper"
  v-bind="option"
  @realTime="realTime"
></vue-cropper>

const cropper = ref();

const option = ref({
  autoCrop: true, // 是否默认生成截图框
  autoCropHeight: "240px", // 默认生成截图框宽度(默认值：容器的 80%, 可选值：0 ~ max), 真正裁剪出来的图片的宽度为 autoCropHeight * 1.25
  autoCropWidth: "240px", // 默认生成截图框宽度(默认值：容器的 80%, 可选值：0 ~ max), 真正裁剪出来的图片的宽度为 autoWidth * 1.25
  canMove: true, // 上传图片是否可以移动
  canScale: true, // 图片是否允许滚轮缩放
  centerBox: true, // 截图框是否被限制在图片里面
  fixed: true, // 是否固定截图框的宽高比例
  fixedBox: true, // 是否固定截图框大小
  fixedNumber: [1, 1], // 截图框的宽高比例([ 宽度 , 高度 ])
  img: "", // 裁剪图片的地址(可选值：url 地址, base64, blob)
  info: true, // 是否显示裁剪框的宽高信息
  infoTrue: true, // infoTrue为 true 时裁剪框显示的是预览图片的宽高信息,infoTrue为 false 时裁剪框显示的是裁剪框的宽高信息
  mode: "contain", // 截图框可拖动时的方向(可选值：contain , cover, 100px, 100% auto)
  origin: false, // 上传的图片是否按照原始比例渲染
  outputSize: 1, // 裁剪生成图片的质量(可选值：0.1 ~ 1)
  outputType: "png", // 裁剪生成图片的格式(可选值：png, jpeg, webp)
  full: true,
});

const previews = ref<any>({
  url: "",
  file: null,
});

// 实时预览
const realTime = () => {
  cropper.value.getCropBlob((blob: Blob) => {
    previews.value.url = window.URL.createObjectURL(blob);
    previews.value.file = blobToFile(blob, imageName.value);
  });
};

裁剪效果预览

        <div class="preview">
          <img :src="previews.url" />
        </div>

.preview {
  width: 150px;
  height: 150px;
  margin: 0px auto 20px auto;
  border-radius: 50%;
  border: 1px solid #ccc;
  background-color: #ccc;
  overflow: hidden;
}

阻止点击冒泡

@click.stop

组件封装 S-avatar.vue

components/SUI/S-avatar.vue

<template>
  <el-upload
    class="avatar-uploader"
    action="#"
    :show-file-list="false"
    :on-success="handleAvatarSuccess"
    :before-upload="beforeAvatarUpload"
    :accept="imgType"
    :drag="drag"
    :disabled="disabled"
  >
    <S-msgWin :msg="callbackMessage" :duration="500" />
    <div v-if="imageUrl" @click.stop class="avatar-container relative group">
      <el-image
        class="avatar"
        :src="imageUrl"
        fit="cover"
        :preview-src-list="[imageUrl]"
      />
      <div
        v-if="!disabled"
        class="absolute inset-0 bg-black/30 opacity-0 group-hover:opacity-100 transition-opacity flex items-center justify-center"
      >
        <el-icon
          :size="30"
          color="white"
          class="edit-icon text-white mr-8 cursor-pointer"
          @click.stop="handleEditAvatar"
        >
          <Edit />
        </el-icon>

        <el-popconfirm title="确定删除吗?" @confirm="handleDeleteAvatar">
          <template #reference>
            <el-icon
              @click.stop
              :size="30"
              color="white"
              class="delete-icon text-white cursor-pointer"
            >
              <Delete />
            </el-icon>
          </template>
        </el-popconfirm>
      </div>
    </div>
    <el-icon v-else class="avatar-uploader-icon">
      <Plus />
    </el-icon>
  </el-upload>

  <el-dialog title="修改头像" v-model="editAvatarDialog" width="600">
    <el-row type="flex" justify="center" class="nowarp">
      <div class="cropper">
        <vue-cropper
          ref="cropper"
          v-bind="option"
          @realTime="realTime"
        ></vue-cropper>
      </div>
      <div class="previewBox">
        <div class="preview">
          <img :src="previews.url" />
        </div>

        <el-row type="flex" justify="center">
          <el-upload
            action="#"
            :show-file-list="false"
            :on-success="handleAvatarSuccess"
            :before-upload="beforeAvatarUpload"
          >
            <el-button size="small" type="primary"> 更换头像 </el-button>
          </el-upload>
        </el-row>
        <br />
        <el-row>
          <el-button
            :icon="ZoomIn"
            circle
            size="small"
            @click="changeScale(1)"
          ></el-button>
          <el-button
            :icon="ZoomOut"
            circle
            size="small"
            @click="changeScale(-1)"
          ></el-button>
          <el-button
            :icon="Download"
            circle
            size="small"
            @click="downloadPreView"
          ></el-button>
          <el-button
            :icon="RefreshLeft"
            circle
            size="small"
            @click="rotateLeft"
          ></el-button>
          <el-button
            :icon="RefreshRight"
            circle
            size="small"
            @click="rotateRight"
          ></el-button>
        </el-row>
      </div>
    </el-row>

    <template #footer>
      <div class="dialog-footer">
        <el-button @click="editAvatarDialog = false">取 消</el-button>
        <el-button type="primary" @click="editAvatarConfirm">确 定</el-button>
      </div>
    </template>
  </el-dialog>
</template>

<script setup lang="ts">
import "vue-cropper/dist/index.css";
import { VueCropper } from "vue-cropper";
import {
  ZoomIn,
  ZoomOut,
  Download,
  RefreshLeft,
  RefreshRight,
} from "@element-plus/icons-vue";
import { ref } from "vue";
import { Plus, Edit, Delete } from "@element-plus/icons-vue";
import type { UploadProps } from "element-plus";

const { imgType, drag, disabled, maxImgSize } = defineProps({
  imgType: {
    type: String,
    default: "image/*",
  },
  drag: {
    type: Boolean,
    default: false,
  },
  disabled: {
    type: Boolean,
    default: false,
  },
  maxImgSize: {
    type: Number,
    default: 2,
  },
});

const imageUrl = defineModel<string>();

const { uploadImage } = useImageUpload();
const editAvatarDialog = ref(false);
const imageName = ref("");

const previews = ref<any>({
  url: "",
  file: null,
});
// 响应式变量
const callbackMessage = useCallbackMessage();
const cropper = ref();

const option = ref({
  autoCrop: true, // 是否默认生成截图框
  autoCropHeight: "240px", // 默认生成截图框宽度(默认值：容器的 80%, 可选值：0 ~ max), 真正裁剪出来的图片的宽度为 autoCropHeight * 1.25
  autoCropWidth: "240px", // 默认生成截图框宽度(默认值：容器的 80%, 可选值：0 ~ max), 真正裁剪出来的图片的宽度为 autoWidth * 1.25
  canMove: true, // 上传图片是否可以移动
  canScale: true, // 图片是否允许滚轮缩放
  centerBox: true, // 截图框是否被限制在图片里面
  fixed: true, // 是否固定截图框的宽高比例
  fixedBox: true, // 是否固定截图框大小
  fixedNumber: [1, 1], // 截图框的宽高比例([ 宽度 , 高度 ])
  img: "", // 裁剪图片的地址(可选值：url 地址, base64, blob)
  info: true, // 是否显示裁剪框的宽高信息
  infoTrue: true, // infoTrue为 true 时裁剪框显示的是预览图片的宽高信息,infoTrue为 false 时裁剪框显示的是裁剪框的宽高信息
  mode: "contain", // 截图框可拖动时的方向(可选值：contain , cover, 100px, 100% auto)
  origin: false, // 上传的图片是否按照原始比例渲染
  outputSize: 1, // 裁剪生成图片的质量(可选值：0.1 ~ 1)
  outputType: "png", // 裁剪生成图片的格式(可选值：png, jpeg, webp)
  full: true,
});

const beforeAvatarUpload: UploadProps["beforeUpload"] = (rawFile) => {
  if (rawFile.size / 1024 / 1024 > maxImgSize) {
    callbackMessage.value = {
      show: true,
      valid: false,
      content: `图片大小不能超过${maxImgSize}MB!`,
    };
    return false;
  }
  return true;
};

const handleAvatarSuccess: UploadProps["onSuccess"] = (
  response,
  uploadFile
) => {
  // ! 为 TS 的非空断言
  option.value.img = URL.createObjectURL(uploadFile.raw!);
  editAvatarDialog.value = true;
  imageName.value = uploadFile.name;
};

// 实时预览
const realTime = () => {
  cropper.value.getCropBlob((blob: Blob) => {
    previews.value.url = window.URL.createObjectURL(blob);
    previews.value.file = blobToFile(blob, imageName.value);
  });
};

const editAvatarConfirm = async () => {
  editAvatarDialog.value = false;

  const res = await uploadImage(previews.value.file);
  if (Array.isArray(res?.data) && res.data.length) {
    imageUrl.value = res.data[0].url;
    imageName.value = res.data[0].filename;
    callbackMessage.value = {
      show: true,
      valid: true,
      content: `上传成功`,
    };
  } else {
    callbackMessage.value = {
      show: true,
      valid: false,
      content: `上传失败`,
    };
  }
};

const downloadPreView = () => {
  let aLink = document.createElement("a");
  aLink.download = "头像裁剪后的效果图.png";

  cropper.value.getCropBlob((blob: Blob) => {
    aLink.href = window.URL.createObjectURL(blob);
    aLink.click();
  });
};

const rotateLeft = () => {
  cropper.value.rotateLeft();
};

const rotateRight = () => {
  cropper.value.rotateRight();
};

const changeScale = (scaleSize: number) => {
  cropper.value.changeScale(scaleSize);
};

const handleDeleteAvatar = () => {
  if (!imageName.value) {
    imageName.value = imageUrl.value?.split("/").pop() || "";
  }
  $fetch(`/api/upload/delete`, {
    body: { filename: imageName.value },
    method: "POST",
  }).then((res) => {
    callbackMessage.value = {
      show: true,
      valid: true,
      content: `删除成功`,
    };
    imageUrl.value = "";
  });
};

const handleEditAvatar = () => {
  if (imageUrl.value) {
    imageName.value = imageUrl.value.split("/").pop() || "";
  }
  option.value.img = imageUrl.value || "";
  editAvatarDialog.value = true;
};
</script>

<style scoped>
.previewBox {
  text-align: center;
  margin-left: 60px;
}

.preview {
  width: 150px;
  height: 150px;
  margin: 0px auto 20px auto;
  border-radius: 50%;
  border: 1px solid #ccc;
  background-color: #ccc;
  overflow: hidden;
}

.cropper {
  width: 260px;
  height: 260px;
}

.avatar-uploader .avatar {
  width: 178px;
  height: 178px;
  display: block;
}

.avatar-container {
  position: relative;
}

.avatar:hover + .avatar-actions,
.avatar-actions:hover {
  display: flex;
}
</style>

<style>
.avatar-uploader .el-upload {
  border: 1px dashed var(--el-border-color);
  border-radius: 50% !important;
  cursor: pointer;
  position: relative;
  overflow: hidden;
  transition: var(--el-transition-duration-fast);
}

.avatar-uploader .el-upload:hover {
  border-color: var(--el-color-primary);
}

.el-icon.avatar-uploader-icon {
  font-size: 28px;
  color: #8c939d;
  width: 178px;
  height: 178px;
  text-align: center;
}
</style>

相关组件

components/SUI/S-msgWin.vue

<script lang="ts" setup>
const props = defineProps({
  msg: {
    type: Object,
    required: true,
  },
  top: {
    type: String,
    default: "50%",
  },
  duration: {
    type: Number,
    default: 3000,
  },
});
watch(
  () => props.msg,
  (newVal, oldVal) => {
    if (newVal.show) {
      setTimeout(() => {
        props.msg.show = false;
      }, props.duration);
    }
  }
);
</script>
<template>
  <transition name="fade">
    <div
      v-show="msg.show"
      class="msgBox"
      :class="{
        'border-#fde2e2 bg-red-50 text-#f56c6c': !msg.valid,
        'border-green-800 bg-green-50 text-green-500': msg.valid,
      }"
    >
      <S-icon :icon="msg.valid ? 'ep:success-filled' : 'ix:error-filled'" />
      <div class="whitespace-nowrap">{{ msg.content }}</div>
      <S-icon
        v-if="msg.closeable"
        class="c-#a8abb2 cursor-pointer"
        icon="material-symbols:close-rounded"
        @click="msg.show = false"
      />
    </div>
  </transition>
</template>
<style scoped>
.msgBox {
  font-size: 14px;
  position: absolute;
  display: flex;
  flex-wrap: nowrap;
  align-items: center;
  gap: 6px;
  padding: 8px 10px;
  top: v-bind(props.top);
  left: 50%;
  transform: translate(-50%, -50%);
  z-index: 9999;
  border-radius: 4px;
}

.fade-leave-from,
.fade-enter-to {
  opacity: 1;
}
.fade-leave-to,
.fade-enter-from {
  opacity: 0;
}
/* 定义过渡的持续时间和动画效果 */
.fade-enter-active,
.fade-leave-active {
  transition: opacity 0.3s ease;
}
</style>

相关组合式函数

composables/useCallbackMessage.ts

export const useCallbackMessage = () => {
  const callbackMessage = ref({
    show: false,
    valid: true,
    content: "",
  });

  return callbackMessage;
};

composables/useImageUpload.ts

export const useImageUpload = () => {
  const isLoading = ref(false);
  const error = ref<string | null>(null);

  const uploadImage = async (file: File) => {
    isLoading.value = true;
    error.value = null;

    try {
      const formData = new FormData();
      formData.append("image", file);

      const response = await $fetch("/api/upload/image", {
        method: "POST",
        body: formData,
        headers: {
          Accept: "application/json",
        },
      });

      return response;
    } catch (err: any) {
      error.value = err.message || "上传失败，请重试";
      throw err;
    } finally {
      isLoading.value = false;
    }
  };

  return {
    uploadImage,
    isLoading,
    error,
  };
};

页面使用

      <S-avatar
        :disabled="action === 'detail'"
        v-model="formData.avatar"
      />

Nuxt 中使用

因 vue-cropper 不支持服务端渲染，所以必须限定其仅在客户端渲染

import { ref, onMounted } from "vue";
import { defineAsyncComponent } from "vue";

// 标记客户端环境
const isClient = ref(false);

// 动态导入组件，禁用SSR
const AvatarCropper = defineAsyncComponent({
  loader: () => import("~/components/SUI/S-avatar.vue"),
  suspensible: false, // 关键：禁止在服务端渲染该组件，使用 suspensible 替代 ssr
});

onMounted(() => {
  isClient.value = true; // 确保在客户端挂载后才显示组件
});

      <AvatarCropper
        :disabled="action === 'detail'"
        v-if="isClient"
        v-model="formData.avatar"
      />
vue3 - 超详细头像裁剪并上传到服务器，支持按照自定义比例裁切图片效果组件插件（详细示例源码教程，一键复制运行开箱即用）
高级前端工程师
05-05 4929
vue3头像裁剪，vue3上传头像并裁剪，vue3裁剪头像及上传服务器，vue3头像的裁剪功能示例源码，vue3最好用的头像裁剪组件，vue3如何实现头像上传后按比例进行裁剪，vue3+ts实现图片裁剪上传(像素裁剪,比例裁剪)，vue3上传图像进行裁剪，vue3将图片进行裁切的示例功能，vue3 element plus 组件库upload上传组件怎么接入裁剪插件，vue3图片图像头像的裁剪裁切插件组件，Vue3中实现选取头像并裁剪，element plus 组件库upload上传组件怎么能先裁剪再上传，
vue3 - 超详细 cropper.js 实现图片（头像）裁剪效果功能，在vue3中上传图像后按比例进行图片的裁剪及实时预览，Element / Ant Desi（详细示例源码，一键复制开箱即用！）
高级前端工程师
06-13 4293
vue3图片裁剪及实时预览，vue3 vue-cropper，vue3头像裁剪，vue3 el-upload+vue-cropper 图像图片头像裁剪上传，vue3怎么进行图片的裁剪，vue3使用vue-cropper图片裁剪，vue3项目如何实现头像图片裁剪上传功能，vue3网站pc怎么将上传的图片按比例进行裁剪，vue3+element plus实现图片上传按尺寸大小裁剪，vue3中图片上传使用cropperjs 头像裁剪，vue3中图片上传使用cropperjs 头像裁剪，vue3好用的图片裁剪插件组
Vue3 + Cropper.js 实现高质量图片裁剪组件：从原理到实战
最新发布
weixin_43699654的博客
08-28 1646
Props：接收父组件传递的图片地址（imgSrc）、弹窗显示状态（）、裁剪比例（）与裁剪区域高度（Emit：向父组件传递裁剪后的图片 URL（newImgUrl）、更新弹窗显示状态（）与错误信息（error内部状态：管理 Cropper 实例（CROPPER）、图片加载状态（imgLoaded）、错误信息（）、初始化锁（）与裁剪器就绪状态（// 父组件传参aspectRatio: { type: Number, default: NaN }, // NaN表示自由比例});
在vue3中使用vue-cropper完成头像裁剪上传图片功能
rolling_kitten的博客
05-31 1684
最终效果如下： vue3项目，使用了element-plus组件库，和vue-cropper头像上传插件，实现了一个头像组件 插件文档：https://www.npmjs.com/package/vue-cropper/v/0.6.2?activeTab=readme 同时参考了文章：https://blog.csdn.net/m0_62317155/article/details/131691932 vue-cropper一个奇怪的bug是，使用此插件就不能导入vue的h函数，否则无法正常工作。另外，v
Vue3中实现选取头像并裁剪
胡海龙
09-23 2351
在一个项目中，尤其是个人中心功能中，免不了要有设置头像的功能，设置时为了最后展示的时候美观好看，一般我们会采取提前截取用户想要的部分，截取时支持放大，缩小，旋转等操作，本文将描述如何在Vue3中实现点击选取图片并裁剪出想要的头像
vue3:十六、个人中心-个人信息-头像裁剪、功能
weixin_46001736的博客
06-26 985
vue3:十六、个人中心-个人信息-头像裁剪、功能
在vue3项目中使用在线图片裁剪功能
zihan0321的博客
02-06 1484
如何在前后端分离项目中使用在线的图片裁剪功能， 今天我来给大家讲一下。
vue3使用vue-cropper裁剪头像
weixin_44165996的博客
05-15 618
定义一个组件ImgCropper文件夹，新建一个index.vue，代码如下。在其它地方引入组件，即可实现。
Vue3 + cropper 实现裁剪头像的功能（裁剪效果可实时预览、预览图可下载、预览图可上传到SpringBoot后端、附完整的示例代码和源代码）
聂可以的博客
08-02 2514
Vue3 + cropper 实现裁剪头像的功能（裁剪效果可实时预览、预览图可下载、预览图可上传到SpringBoot后端、附完整的示例代码和源代码）
uniapp-avatar-master.zip
07-01
"uniapp-avatar-master.zip" 是一个包含完整且全面的头像裁剪工具的压缩包，主要面向使用 Uni-App 开发的小程序和 H5 应用。Uni-App 是一个基于 Vue.js 的多端开发框架，它允许开发者使用一套代码在微信小程序、...
vue-cli结合Element-ui基于cropper.js封装vue实现图片裁剪组件功能
11-26
总结起来，通过 Vue-cli 结合 Element-UI 和 cropper.js，我们可以轻松地封装一个功能丰富的图片裁剪组件，提供用户友好的图片上传和裁剪功能。这个组件不仅能够满足基本的图片裁剪需求，还可以通过自定义扩展，实现...
Vue-Cropper头像裁剪插件使用
昵称为啥重复呐的博客
02-26 1741
官网地址：[
Vue3+Ts+vue-cropper:实现头像图片裁剪
qq_67718812的博客
09-27 3185
本文主要介绍如何基于VUE+TS，通过vue-cropper实现头像图片剪裁的基本功能，包含拖拽效果、放大、缩小、旋转、更换图片。上传部分请根据自身要求进行代码编写。
vue3+elementPlus+vueCropper实现头像(图片)裁剪（非常全，可直接cv！！！！！）
qq_52850749的博客
02-01 1358
最后一步就是确认裁剪操作了,这一步一定要用asyncawait,不然数据获取的会有问题，会显示promisepending，调上传接口的时候也要把headers带上，点击确认裁剪的时候我加了一个elemnetplus的loading动画，防止没上传完弹出就被用户x掉了。总结：首先使用el-upload拿到图片地址，将图片url转换成base64，使用头像裁剪，最后调用upload上传接口，成功后调用保存图片即可。完结，撒花，以上代码有任何问题请私信踢我，或者评论区留言！引入vueCropper插件。
vue3 - 最新详细实现头像上传并裁剪功能，用户上传头像裁剪圆形并上传到服务器教程，可搭配element plus或ant design vue组件库，支持头像预览、完美对接服务端接口
weixin_41513488的博客
09-02 1494
安装依赖：首先，你需要安装一些依赖。你可以选择使用 Element Plus 或 Ant Design Vue 组件库，具体选择哪个取决于你的需求。你还需要安装其他一些依赖，如 axios（用于发送请求到服务器）和 vue-cropper（用于裁剪头像）。创建上传组件：创建一个头像上传组件，其中包含一个上传按钮和一个预览区域。根据你选择的组件库，可以使用。（Ant Design Vue）组件来实现上传功能。添加裁剪功能：为了实现头像裁剪功能，你可以使用。需要替换为你的上传接口地址。
vue3 裁剪图片、头像组件封装 elementPlus上传组件+cropper
2301_76513773的博客
05-08 2106
如果原先就有图片，则点击修改时直接出现原图片，用户可点击【选择】重新上传再裁剪，也可直接裁剪原图片提交。用户上传的头像、封面等图片需要符合一定的比例，网站需要帮助用户进行预处理，确保图片显示时不会变形。点击上传按钮选择文件后，出现裁剪弹窗。
vue3图片剪裁:vue-img-cutter
Gunba1的博客
01-29 2053
vue-img-cutter实现当前已有的图片剪裁
在Vue3中使用 `vue-cropperjs` 实现图片裁剪、预览与上传功能
wandongle的博客
03-03 2625
通过属性可以设置裁剪框的宽高比。例如，设置为1 / 1可以实现正方形裁剪框，常用于头像等，或设置16 / 9用于背景图片等。是一个功能强大且易于使用的图片裁剪组件，适合在 Vue 项目中实现图片裁剪与上传功能。通过本文的介绍，希望你可以快速掌握其基本用法。本文只是简单介绍了在Vue3中使用实现图片裁剪与上传两个主要功能，如果有需要更多高级用法，可以在下方的参考文档中查看官方文档。如果你有更多问题或需要进一步的帮助，欢迎在评论区留言！参考文档cropperjs 官方文档。
评论
添加红包

请填写红包祝福语或标题

个

红包个数最小为10个

元

红包金额最低5元

当前余额3.43元 前往充值 >
需支付：10.00元
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包

打赏作者

朝阳39

你的鼓励将是我创作的最大动力

¥1 ¥2 ¥4 ¥6 ¥10 ¥20
扫码支付：¥1
获取中
扫码支付

您的余额不足，请更换扫码支付或充值

打赏作者

实付元
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明：

1.余额是钱包充值的虚拟货币，按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载，可以购买VIP、付费专栏及课程。

余额充值