搜索intelogie / cropper
This package is auto-updated.
Last update: 2024-08-29 03:10:43 UTC
README
一个简单的 jQuery 图片裁剪插件。
目录
功能
- 支持 39 个 选项
- 支持 27 个 方法
- 支持 7 个 事件
- 支持触摸（移动设备）
- 支持缩放
- 支持旋转
- 支持缩放（翻转）
- 支持多个裁剪器
- 支持在画布上裁剪
- 支持在浏览器端通过画布裁剪图像
- 支持翻译 Exif Orientation 信息
- 跨浏览器支持
主要
dist/
├── cropper.css ( 5 KB)
├── cropper.min.css ( 4 KB)
├── cropper.js (78 KB)
└── cropper.min.js (28 KB)
入门
快速开始
有四个快速开始选项可用
- 下载最新版本.
- 克隆仓库：
git clone https://github.com/fengyuanchen/cropper.git。 - 使用 NPM 安装：
npm install cropper。 - 使用 Bower 安装：
bower install cropper。
安装
包含文件
<script src="/path/to/jquery.js"></script><!-- jQuery is required --> <link href="/path/to/cropper.css" rel="stylesheet"> <script src="/path/to/cropper.js"></script>
cdnjs 为 Cropper 的 CSS 和 JavaScript 提供了 CDN 支持。您可以在 这里 找到链接。
使用方法
使用 $.fn.cropper 方法初始化。
<!-- Wrap the image or canvas element with a block element (container) --> <div> <img id="image" src="picture.jpg"> </div>
/* Limit image width to avoid overflow the container */ img { max-width: 100%; /* This rule is very important, please do not ignore this! */ }
$('#image').cropper({ aspectRatio: 16 / 9, crop: function(e) { // Output the result data for cropping image. console.log(e.x); console.log(e.y); console.log(e.width); console.log(e.height); console.log(e.rotate); console.log(e.scaleX); console.log(e.scaleY); } });
常见问题解答
如何放大或缩小后裁剪新区域？
只需双击鼠标即可进入裁剪模式。
如何裁剪后移动图像？
只需双击鼠标即可进入移动模式。
如何在自由比例模式下固定宽高比？
在调整裁剪框大小时按住
shift键。
如何在自由比例模式下裁剪正方形区域？
在裁剪图像时按住
shift键。
注意事项
-
裁剪器的大小继承自图像父元素（包装器）的大小，因此请确保用 可见的块级元素 包裹图像。
如果您在模态框中使用裁剪器，应在模态框完全显示后初始化裁剪器。否则，您将无法获得正确的裁剪器。
-
输出的裁剪数据基于原始图像大小，因此您可以直接使用它们来裁剪图像。
-
如果您尝试在跨源图像上启动裁剪器，请确保您的浏览器支持 HTML5 CORS 设置属性，并且您的图像服务器支持
Access-Control-Allow-Origin选项（请参阅 HTTP 访问控制（CORS））。
已知问题
-
已知 iOS 资源限制：由于 iOS 设备限制内存，当您裁剪大图像（iPhone 相机分辨率）时，浏览器可能会崩溃。为了避免这种情况，您可以在启动裁剪器之前先调整图像大小（小于 1024px）。
-
已知图像尺寸增加：当使用
HTMLCanvasElement.toDataURL方法在浏览器端导出裁剪后的图像时，导出图像的大小可能大于原始图像。这是因为导出图像的类型与原始图像不同。因此，只需将原始图像的类型作为第一个参数传递给toDataURL即可修复此问题。例如，如果原始类型是 JPEG，则使用$().cropper('getCroppedCanvas').toDataURL('image/jpeg')来导出图像。
选项
您可以使用 $().cropper(options) 设置裁剪器选项。如果您想更改全局默认选项，可以使用 $.fn.cropper.setDefaults(options)。
viewMode
- 类型：
Number - 默认：
0 - 选项
0：裁剪框仅在容器内1：裁剪框应在画布内2：画布不应在容器内3：容器应在画布内
定义裁剪器的视图模式。
dragMode
- 类型：
String - 默认：
'crop' - 选项
'crop'：创建新的裁剪框'move'：移动画布'none'：不执行任何操作
定义裁剪器的拖动模式。
aspectRatio
- 类型：
Number - 默认：
NaN
设置裁剪框的宽高比。默认情况下，裁剪框是自由比例。
data
- 类型：
Object - 默认：
null
如果之前已存储裁剪数据，它将自动传递给 setData 方法。
preview
- 类型：
String(jQuery选择器) - 默认：
''
添加额外元素（容器）用于预览。
注意事项
- 最大宽度是预览容器的初始宽度。
- 最大高度是预览容器的初始高度。
- 如果您设置了
aspectRatio选项，请确保设置预览容器具有相同的宽高比。 - 如果预览没有正确显示，将
overflow:hidden设置为预览容器。
responsive
- 类型：
Boolean - 默认：
true
当调整窗口大小时重新渲染裁剪器。
restore
- 类型：
Boolean - 默认：
true
调整窗口大小时恢复裁剪区域。
checkCrossOrigin
- 类型：
Boolean - 默认：
true
检查当前图像是否是跨域图像。
如果是，当克隆图像时，将在克隆的图像元素上添加 crossOrigin 属性，并在 src 属性中添加时间戳以重新加载源图像，避免浏览器缓存错误。
通过向图像添加 crossOrigin 属性，将停止向图像 URL 添加时间戳，并停止重新加载图像。
checkOrientation
- 类型：
Boolean - 默认：
true
检查当前图像的 Exif 方向信息。
更确切地说，读取方向值以旋转或翻转图像，然后用 1（默认值）覆盖方向值，以避免在 iOS 设备上的一些问题（#120，#509）。
需要同时将 rotatable 和 scalable 选项设置为 true。
注意：不要总是相信这个，因为一些 JPG 图像具有不正确（非标准）的方向值。
需要支持 Typed Arrays（IE 10+）。
modal
- 类型：
Boolean - 默认：
true
在图像和裁剪框上方显示黑色模态框。
guides
- 类型：
Boolean - 默认：
true
在裁剪框上方显示虚线线。
center
- 类型：
Boolean - 默认：
true
在裁剪框上方显示中心指示器。
highlight
- 类型：
Boolean - 默认：
true
在裁剪框上方显示白色模态框（突出显示裁剪框）。
background
- 类型：
Boolean - 默认：
true
显示容器的网格背景。
autoCrop
- 类型：
Boolean - 默认：
true
初始化时自动裁剪图片。
autoCropArea
- 类型：
Number - 默认值:
0.8(图像的80%)
介于0和1之间的数字。定义自动裁剪区域的大小（百分比）。
movable
- 类型：
Boolean - 默认：
true
启用移动图片。
rotatable
- 类型：
Boolean - 默认：
true
启用旋转图片。
scalable
- 类型：
Boolean - 默认：
true
启用缩放图片。
zoomable
- 类型：
Boolean - 默认：
true
启用缩放图片。
zoomOnTouch
- 类型：
Boolean - 默认：
true
启用通过拖动触摸缩放图片。
zoomOnWheel
- 类型：
Boolean - 默认：
true
启用通过鼠标滚轮缩放图片。
wheelZoomRatio
- 类型：
Number - 默认值:
0.1
定义通过鼠标滚轮缩放图片时的缩放比例。
cropBoxMovable
- 类型：
Boolean - 默认：
true
启用通过拖动移动裁剪框。
cropBoxResizable
- 类型：
Boolean - 默认：
true
启用通过拖动调整裁剪框大小。
toggleDragModeOnDblclick
- 类型：
Boolean - 默认：
true
启用在裁剪器上双击时在“裁剪”和“移动”模式之间切换。
minContainerWidth
- 类型：
Number - 默认值:
200
容器的最小宽度。
minContainerHeight
- 类型：
Number - 默认值:
100
容器的最小高度。
minCanvasWidth
- 类型：
Number - 默认：
0
画布（图像包装器）的最小宽度。
minCanvasHeight
- 类型：
Number - 默认：
0
画布（图像包装器）的最小高度。
minCropBoxWidth
- 类型：
Number - 默认：
0
裁剪框的最小宽度。
注意： 此大小相对于页面，而不是图像。
minCropBoxHeight
- 类型：
Number - 默认：
0
裁剪框的最小高度。
注意： 此大小相对于页面，而不是图像。
build
- 类型:
Function - 默认：
null
"build.cropper"事件的快捷方式。
built
- 类型:
Function - 默认：
null
"built.cropper"事件的快捷方式。
cropstart
- 类型:
Function - 默认：
null
"cropstart.cropper"事件的快捷方式。
cropmove
- 类型:
Function - 默认：
null
"cropmove.cropper"事件的快捷方式。
cropend
- 类型:
Function - 默认：
null
"cropend.cropper"事件的快捷方式。
crop
- 类型:
Function - 默认：
null
"crop.cropper"事件的快捷方式。
zoom
- 类型:
Function - 默认：
null
"zoom.cropper"事件的快捷方式。
方法
由于加载图像时存在异步过程，因此你应在"built"之后调用大多数方法，除了"setAspectRatio"、"replace"和"destroy"。
$().cropper({ built: function () { $().cropper('method', argument1, , argument2, ..., argumentN); } });
crop()
手动显示裁剪框。
$().cropper({ autoCrop: false, built: function () { // Do something here // ... // And then $(this).cropper('crop'); } });
reset()
将图片和裁剪框重置到初始状态。
clear()
清除裁剪框。
replace(url[, onlyColorChanged])
-
url:
- 类型：
String - 新的图片URL。
- 类型：
-
onlyColorChanged (可选)
- 类型：
Boolean - 如果只改变颜色，不改变大小，则裁剪器只需更改所有相关图像的src，无需重新构建裁剪器。这可以用于应用过滤器。
- 如果不存在，其默认值为
false。
- 类型：
替换图像的src并重新构建裁剪器。
enable()
启用（解冻）裁剪器。
disable()
禁用（冻结）裁剪器。
destroy()
销毁裁剪器并将实例从图像中移除。
move(offsetX[, offsetY])
-
offsetX:
- 类型：
Number - 水平方向上的移动大小（像素）。
- 类型：
-
offsetY (可选)
- 类型：
Number - 垂直方向上的移动大小（像素）。
- 如果不存在，其默认值是
offsetX。
- 类型：
使用相对偏移量移动画布（图像包装器）。
$().cropper('move', 1); $().cropper('move', 1, 0); $().cropper('move', 0, -1);
moveTo(x[, y])
-
x:
- 类型：
Number - 画布的
left值
- 类型：
-
y (可选)
- 类型：
Number - 画布的
top值 - 如果不存在，其默认值是
x。
- 类型：
将画布（图像包装器）移动到绝对点。
zoom(ratio)
- ratio:
- 类型：
Number - 放大：需要一个正数（ratio > 0）
- 缩小：需要一个负数（ratio < 0）
- 类型：
使用相对比例缩放画布（图像包装器）。
$().cropper('zoom', 0.1); $().cropper('zoom', -0.1);
zoomTo(ratio)
- ratio:
- 类型：
Number
- 类型：
使用绝对比例缩放画布（图像包装器）。
$().cropper('zoomTo', 1); // 1:1 (canvasData.width === canvasData.naturalWidth)
rotate(degree)
- degree:
- 类型：
Number - 顺时针旋转：需要正数（degree > 0）
- 逆时针旋转：需要负数（degree < 0）
- 类型：
使用相对角度旋转图像。
需要支持CSS3 2D 变换（IE 9+）。
$().cropper('rotate', 90); $().cropper('rotate', -90);
rotateTo(degree)
- degree:
- 类型：
Number
- 类型：
将图像旋转到绝对角度。
scale(scaleX[, scaleY])
-
scaleX:
- 类型：
Number - 默认值：
1 - 应用于图像横轴的缩放因子。
- 当等于
1时，不执行任何操作。
- 类型：
-
scaleY（可选）
- 类型：
Number - 应用于图像纵轴的缩放因子。
- 如果未提供，则默认值为
scaleX。
- 类型：
缩放图像。
需要支持CSS3 2D 变换（IE 9+）。
$().cropper('scale', -1); // Flip both horizontal and vertical $().cropper('scale', -1, 1); // Flip horizontal $().cropper('scale', 1, -1); // Flip vertical
scaleX(scaleX)
- scaleX:
- 类型：
Number - 默认值：
1 - 应用于图像横轴的缩放因子。
- 当等于
1时，不执行任何操作。
- 类型：
缩放图像的横轴。
scaleY(scaleY)
- scaleY:
- 类型：
Number - 默认值：
1 - 应用于图像纵轴的缩放因子。
- 当等于
1时，不执行任何操作。
- 类型：
缩放图像的纵轴。
getData([rounded])
-
rounded（可选）
- 类型：
Boolean - 默认值：
false - 设置为
true以获取四舍五入的值。
- 类型：
-
（返回值）
- 类型：
Object - 属性
x：裁剪区域的左偏移量y：裁剪区域的上偏移量width：裁剪区域的宽度height：裁剪区域的高度rotate：图像的旋转角度scaleX：应用于图像横轴的缩放因子scaleY：应用于图像纵轴的缩放因子
- 类型：
输出最终裁剪区域的位置和尺寸数据（基于原始图像的自然尺寸）。
可以将数据发送到服务器端以直接裁剪图像。
setData(data)
- data:
- 类型：
Object - 属性：请参阅
getData方法。
- 类型：
使用新数据更改裁剪区域的位置和大小（基于原始图像）。
注意：此方法仅在
viewMode选项大于或等于1时可用。
getContainerData()
- （返回值）
- 类型：
Object - 属性
width：容器当前宽度height：容器当前高度
- 类型：
输出容器尺寸数据。
getImageData()
- （返回值）
- 类型：
Object - 属性
left：图像的左偏移量top：图像的上偏移量width：图像的宽度height：图像的高度naturalWidth：图像的自然宽度naturalHeight：图像的自然高度aspectRatio：图像的宽高比rotate：如果已旋转，则图像的旋转角度scaleX：如果已缩放，则应用于图像横轴的缩放因子scaleY：如果已缩放，则应用于图像纵轴的缩放因子
- 类型：
输出图像位置、尺寸和其他相关数据。
getCanvasData()
- （返回值）
- 类型：
Object - 属性
left：画布的左偏移量top：画布的上偏移量width：画布的宽度height：画布的高度naturalWidth：画布的自然宽度（只读）naturalHeight：画布的自然高度（只读）
- 类型：
输出画布（图像包装器）的位置和尺寸数据。
var imageData = $().cropper('getImageData'); var canvasData = $().cropper('getCanvasData'); if (imageData.rotate % 180 === 0) { console.log(canvasData.naturalWidth === imageData.naturalWidth); // true }
setCanvasData(data)
- data:
- 类型：
Object - 属性
left：画布的新左偏移量top：画布的新上偏移量width：画布的新宽度height：画布的新高度
- 类型：
使用新数据更改画布（图像包装器）的位置和大小。
getCropBoxData()
- （返回值）
- 类型：
Object - 属性
left：裁剪框的左偏移量top：裁剪框的顶部偏移量width：裁剪框的宽度height：裁剪框的高度
- 类型：
输出裁剪框的位置和尺寸数据。
setCropBoxData(data)
- data:
- 类型：
Object - 属性
left：裁剪框的新左偏移量top：裁剪框的新顶部偏移量width：裁剪框的新宽度height：裁剪框的新高度
- 类型：
使用新数据更改裁剪框的位置和尺寸。
getCroppedCanvas([options])
-
options（可选）
- 类型：
Object - 属性
width：输出画布的目标宽度height：输出画布的目标高度fillColor：用于填充输出画布中任何alpha值的颜色
- 注意：输出画布的宽高比将自动适应裁剪框的宽高比。
- 类型：
-
（返回值）
- 类型：
HTMLCanvasElement - 绘制裁剪图像的画布。
- 类型：
-
浏览器支持
- 基本图像：需要Canvas支持（IE 9+）。
- 旋转图像：需要CSS3 2D Transforms支持（IE 9+）。
- 跨源图像：需要HTML5 CORS设置属性支持（IE 11+）。
获取绘制裁剪图像的画布。如果没有裁剪，则返回整个画布。
然后，您可以直接显示画布作为图像，或者使用HTMLCanvasElement.toDataURL获取Data URL，或者使用HTMLCanvasElement.toBlob获取blob，并通过FormData上传到服务器，如果浏览器支持这些API。
$().cropper('getCroppedCanvas'); $().cropper('getCroppedCanvas', { width: 160, height: 90 }); // Upload cropped image to server if the browser supports `HTMLCanvasElement.toBlob` $().cropper('getCroppedCanvas').toBlob(function (blob) { var formData = new FormData(); formData.append('croppedImage', blob); $.ajax('/path/to/upload', { method: "POST", data: formData, processData: false, contentType: false, success: function () { console.log('Upload success'); }, error: function () { console.log('Upload error'); } }); });
setAspectRatio(aspectRatio)
- aspectRatio:
- 类型：
Number - 需要正数。
- 类型：
更改裁剪框的宽高比。
setDragMode([mode])
- mode（可选）
- 类型：
String - 默认：
'none' - 选项：
'none'、'crop'、'move'
- 类型：
更改拖动模式。
提示：您可以通过在裁剪器上双击来切换“裁剪”和“移动”模式。
事件
build.cropper
此事件在裁剪器实例开始加载图像时触发。
built.cropper
此事件在裁剪器实例完全构建后触发。
cropstart.cropper
-
event.originalEvent:
- 类型：
Event - 选项：
mousedown、touchstart和pointerdown
- 类型：
-
event.action:
- 类型：
String - 选项
'crop'：创建新的裁剪框'move'：移动画布（图像包装器）'zoom'：通过触摸放大/缩小画布（图像包装器）'e'：调整裁剪框的东侧'w'：调整裁剪框的西侧's'：调整裁剪框的南侧'n'：调整裁剪框的北侧'se'：调整裁剪框的东南侧'sw'：调整裁剪框的西南侧'ne'：调整裁剪框的东北侧'nw'：调整裁剪框的西北侧'all'：移动裁剪框（所有方向）
- 类型：
此事件在画布（图像包装器）或裁剪框开始变化时触发。
$().on('cropstart.cropper', function (e) { console.log(e.type); // cropstart console.log(e.namespace); // cropper console.log(e.action); // ... console.log(e.originalEvent.pageX); // Prevent to start cropping, moving, etc if necessary if (e.action === 'crop') { e.preventDefault(); } });
cropmove.cropper
-
event.originalEvent:
- 类型：
Event - 选项：
mousemove、touchmove和pointermove。
- 类型：
-
event.action：与“cropstart.cropper”相同。
此事件在画布（图像包装器）或裁剪框正在变化时触发。
cropend.cropper
-
event.originalEvent:
- 类型：
Event - 选项：
mouseup、touchend、touchcancel、pointerup和pointercancel。
- 类型：
-
event.action：与“cropstart.cropper”相同。
当画布（图像包装器）或裁剪框停止变化时，此事件触发。
crop.cropper
- event.x
- event.y
- event.width
- event.height
- event.rotate
- event.scaleX
- event.scaleY
关于这些属性，请参阅
getData方法。
当画布（图像包装器）或裁剪框发生变化时，此事件触发。
zoom.cropper
-
event.originalEvent:
- 类型：
Event - 选项：
wheel、touchmove。
- 类型：
-
event.oldRatio:
- 类型：
Number - 画布的旧（当前）比例
- 类型：
-
event.ratio:
- 类型：
Number - 画布的新（下一个）比例（
canvasData.width / canvasData.naturalWidth）
- 类型：
当裁剪实例开始放大或缩小其画布（图像包装器）时，此事件触发。
$().on('zoom.cropper', function (e) { // Zoom in if (e.ratio > e.oldRatio) { // Prevent zoom in e.preventDefault(); } // Zoom out // ... });
无冲突
如果您必须使用具有相同命名空间的另一个插件，只需调用 $.fn.cropper.noConflict 方法即可恢复。
<script src="other-plugin.js"></script> <script src="cropper.js"></script> <script> $.fn.cropper.noConflict(); // Code that uses other plugin's "$().cropper" can follow here. </script>
浏览器支持
- Chrome（最新版）
- Firefox（最新版）
- Safari（最新版）
- Opera（最新版）
- Edge（最新版）
- Internet Explorer 8+
作为jQuery插件，您还需要查看 jQuery浏览器支持。
贡献
请阅读我们的 贡献指南。
版本控制
遵循 语义化版本规范 维护。
许可
相关项目
- ember-cli-image-cropper by @mhretab
- Image Widget Crop - Drupal 8中的主要裁剪解决方案
- meteor-cropper by @jonblum
- ngCropper by @koorgoo
- redux-cropper by @lapanoid