当前位置：首页>行业动态> 正文

cropper.js中文文档

Cropper.js 中文文档

Cropper.js是一个流行的 JavaScript 图像裁剪库，它提供了简单易用的 API，允许开发者在网页上实现图片裁剪功能，以下是关于 Cropper.js 的详细中文文档。

一、引入 Cropper.js

在使用 Cropper.js 之前，首先需要将其引入到项目中，可以通过以下几种方式引入：

（一）通过 CDN 引入

<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/cropperjs/dist/cropper.min.css">
<script src="https://cdn.jsdelivr.net/npm/cropperjs/dist/cropper.min.js"></script>

（二）通过 npm 安装

在项目目录下执行以下命令安装 Cropper.js：

npm install cropperjs

然后在项目中引入：

import Cropper from 'cropperjs';

二、基本用法

（一）初始化 Cropper.js

1、HTML 结构

需要在 HTML 中创建一个<img> 元素，用于显示要裁剪的图片：

cropper.js中文文档 第1张

<img id="image" src="path/to/your/image.jpg" alt="Example">

2、JavaScript 初始化

在 JavaScript 中，获取图片元素并初始化 Cropper.js：

const image = document.getElementById('image');
const cropper = new Cropper(image, {
    aspectRatio: 16 / 9, // 设置裁剪框的宽高比，可省略
    viewMode: 1, // 裁剪模式，0 为默认模式，1 为固定大小模式，2 为固定宽高比模式
    dragMode: 'crop', // 拖拽模式，'crop' 为裁剪模式，'move' 为移动模式
});

（二）生成裁剪后的图片

当用户完成裁剪操作后，可以通过以下代码生成裁剪后的图片：

document.getElementById('getData')?.addEventListener('click', () => {
    const croppedCanvas = cropper.getData()[0].getData()[0];
    const croppedImage = document.createElement('img');
    croppedImage.src = croppedCanvas.toDataURL();
    document.body.appendChild(croppedImage);
});

上述代码中，点击id 为getData 的按钮时，会生成裁剪后的 canvas 数据，并将其转换为图片添加到页面中。

三、常用配置选项

选项类型默认值描述
aspectRationumber0裁剪框的宽高比，设置为 0 表示不限制宽高比。
viewModenumber0裁剪模式，0 为默认模式，1 为固定大小模式，2 为固定宽高比模式。
dragModestring‘crop’拖拽模式。’crop’ 为裁剪模式，’move’ 为移动模式。
autoCropAreanumber0.8自动调整裁剪区域的面积比例，取值范围为 0 1。
minContainerWidthnumber200裁剪容器的最小宽度。
minContainerHeightnumber100裁剪容器的最小高度。
backgroundbooleantrue是否显示背景。
highlightbooleantrue是否显示高亮区域。
movablebooleantrue是否允许移动图片。
rotatablebooleantrue是否允许旋转图片。
scalablebooleantrue是否允许缩放图片。
zoomablebooleantrue是否允许缩放图片。
zoomOnWheelbooleanfalse是否允许通过鼠标滚轮缩放图片。
zoomOnScrollbooleanfalse是否允许通过滚动缩放图片。
modalbooleanfalse是否显示遮罩层。
guidesbooleanfalse是否显示参考线。
centerbooleanfalse是否将图片居中显示。
responsivebooleantrue是否响应窗口大小变化。
checkOrientationbooleantrue是否检查图片方向。
checkCrossOriginbooleantrue是否检查跨域图片。
restorebooleanfalse是否在初始化时恢复上次的裁剪数据。
willChangeHeightbooleantrue是否根据图片高度变化自动调整容器高度。

四、方法

（一）getData()

获取当前裁剪区域的数据，返回一个包含裁剪信息的对象。

const data = cropper.getData();
console.log(data);

输出结果可能如下：

{
    "x": 100,
    "y": 50,
    "width": 300,
    "height": 150,
    "rotate": 0,
    "scaleX": 1,
    "scaleY": 1
}

（二）setData()

设置裁剪区域的数据。

const data = { x: 200, y: 100, width: 400, height: 200 };
cropper.setData(data);

（三）generate(options)

生成裁剪后的图片或 canvas。options 参数是一个对象，可用于指定生成的图片格式、质量等。

const options = {
    width: 800, // 生成图片的宽度
    height: 400, // 生成图片的高度
    type: 'png' // 生成图片的格式，可选 'jpeg'、'png' 等
};
const croppedCanvas = cropper.getCroppedCanvas(options);
const croppedImage = document.createElement('img');
croppedImage.src = croppedCanvas.toDataURL();
document.body.appendChild(croppedImage);

五、事件

Cropper.js 提供了丰富的事件，方便开发者在用户操作过程中执行相应的逻辑，以下是一些常用的事件：

事件名称触发时机回调函数参数
cropstart开始裁剪时触发(event)
cropmove裁剪过程中触发(event)
cropend结束裁剪时触发(event)
crop每次裁剪操作完成后触发，包括开始和结束(event)
dblclick双击图片时触发(event)
readyCropper.js 初始化完成且图片准备好时触发(event)
zoom缩放图片时触发(event)

监听cropend 事件：

cropper.on('cropend', (event) => {
    console.log('裁剪结束');
});

六、FAQs

（一）如何动态更新图片源？

如果需要动态更新图片源，可以先销毁当前的 Cropper.js 实例，然后重新初始化。

// 假设有一个按钮，点击时更新图片源
document.getElementById('updateImage')?.addEventListener('click', () => {
    if (cropper) {
        cropper.destroy(); // 销毁当前实例
    }
    const newImage = document.createElement('img');
    newImage.src = 'new/image/path.jpg'; // 新的图片路径
    newImage.alt = 'New Image';
    document.getElementById('image-container').replaceChild(newImage, image); // 替换旧的图片元素
    image = newImage; // 更新图片元素引用
    cropper = new Cropper(image, { aspectRatio: 16 / 9 }); // 重新初始化 Cropper.js
});

（二）如何设置初始裁剪区域？

可以使用setData() 方法设置初始裁剪区域。

const initialData = { x: 50, y: 50, width: 200, height: 200 };
cropper.setData(initialData);

这样，在初始化 Cropper.js 时就会按照指定的裁剪区域进行显示。

小编有话说

Cropper.js 是一个非常强大的图像裁剪库，它不仅提供了丰富的功能和灵活的配置选项，还具有良好的兼容性和易用性，无论是在网页设计中添加图片裁剪功能，还是在开发各种图像处理应用时，Cropper.js 都能发挥重要作用，希望本文的介绍能帮助开发者更好地理解和使用 Cropper.js，快速实现所需的图片裁剪效果。

Cropper.js中文文档图片裁剪
0

相关文章