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> 元素，用于显示要裁剪的图片：

<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 数据，并将其转换为图片添加到页面中。

三、常用配置选项

选项	类型	默认值	描述
aspectRatio	number	0	裁剪框的宽高比，设置为 0 表示不限制宽高比。
viewMode	number	0	裁剪模式，0 为默认模式，1 为固定大小模式，2 为固定宽高比模式。
dragMode	string	‘crop’	拖拽模式。’crop’ 为裁剪模式，’move’ 为移动模式。
autoCropArea	number	0.8	自动调整裁剪区域的面积比例，取值范围为 0 1。
minContainerWidth	number	200	裁剪容器的最小宽度。
minContainerHeight	number	100	裁剪容器的最小高度。
background	boolean	true	是否显示背景。
highlight	boolean	true	是否显示高亮区域。
movable	boolean	true	是否允许移动图片。
rotatable	boolean	true	是否允许旋转图片。
scalable	boolean	true	是否允许缩放图片。
zoomable	boolean	true	是否允许缩放图片。
zoomOnWheel	boolean	false	是否允许通过鼠标滚轮缩放图片。
zoomOnScroll	boolean	false	是否允许通过滚动缩放图片。
modal	boolean	false	是否显示遮罩层。
guides	boolean	false	是否显示参考线。
center	boolean	false	是否将图片居中显示。
responsive	boolean	true	是否响应窗口大小变化。
checkOrientation	boolean	true	是否检查图片方向。
checkCrossOrigin	boolean	true	是否检查跨域图片。
restore	boolean	false	是否在初始化时恢复上次的裁剪数据。
willChangeHeight	boolean	true	是否根据图片高度变化自动调整容器高度。

四、方法

（一）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)
ready	Cropper.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，快速实现所需的图片裁剪效果。