jQuery.cropper中文API詳解

cropper提供了大量的參數、方法和事件供圖片的剪裁操做。 
 

安裝

能夠經過Bower或NPM來安裝該插件。 
bower install cropper
npm install cropper

 

使用方法

使用該圖片剪裁插件首先要引入必要的js和css文件。
<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>           

 

HTML結構

能夠將圖片或canvas直接包裹到一個塊級元素中。 
<!-- Wrap the image or canvas with a block element -->
<div class="container">
<img src="picture.jpg">
</div>

 

調用插件

可使用$.fn.cropper方法來初始化該圖片剪裁插件。 
$('.container > img').cropper({
aspectRatio: 16 / 9,
crop: function(data) {
// Output the result data for cropping image.
}
});   

 

注意事項：
注意：剪裁區域的尺寸繼承自圖片的父容器（包裹容器），因此要確保包裹圖片的是一個可見的塊級元素。
輸出的剪裁數據基於原始的圖片尺寸，你可使用這些數據直接剪裁圖片。
若是你要使用跨源圖片來做爲剪裁圖片，請確保你的瀏覽器支持HTML5 CORS settings attributes，而且你的圖片服務器支持Access-Control-Allow-Origin屬性。

配置參數

你能夠經過$().cropper(options)方法來設置參數。若是你想改變全局默認參數，可使用$.fn.cropper.setDefaults(options)方法。
aspectRatio：類型：Number，默認值NaN。設置剪裁容器的比例。
crop：類型：Function，默認值null。當改變剪裁容器或圖片時的事件函數。
preview：類型：String(jQuery選擇器)，默認值''。添加額外的元素（容器）的預覽。
 

注意：

1. 1.最大寬度是剪裁容器的初始化寬度
2. 最大高度是剪裁容器的初始化高度
3. 若是你設置了aspectRatio參數，確保預覽容器具備相同的比例
   {{{strict：類型：Boolean，默認值true。在strict模式中，canvas不能小於容器，剪裁容器不能再canvas以外。
   responsive：類型：Boolean，默認值true。是否在窗口尺寸改變的時候重置cropper。
   checkImageOrigin：類型：Boolean，默認值true。默認狀況下，插件會檢測圖片的源，若是是跨域圖片，圖片元素會被添加crossOrigin class，並會爲圖片的url添加一個時間戳來使getCroppedCanvas變爲可用。添加時間戳會使圖片從新加載，以使跨域圖片可以使用getCroppedCanvas。在圖片上添加crossOrigin class會阻止在圖片url上添加時間戳，及圖片的從新加載。
   background：類型：Boolean，默認值true。是否在容器上顯示網格背景。
   modal：類型：Boolean，默認值true。是否在剪裁框上顯示黑色的模態窗口。
   guides：類型：Boolean，默認值true。是否在剪裁框上顯示虛線。
   highlight：類型：Boolean，默認值true。是否在剪裁框上顯示白色的模態窗口。
   autoCrop：類型：Boolean，默認值true。是否在初始化時容許自動剪裁圖片。
   autoCropArea：類型：Number，默認值0.8（圖片的80%）。0-1之間的數值，定義自動剪裁區域的大小。
   dragCrop：類型：Boolean，默認值true。是否容許移除當前的剪裁框，並經過拖動來新建一個剪裁框區域。
   movable：類型：Boolean，默認值true。是否容許移動剪裁框。
   resizable：類型：Boolean，默認值true。是否容許改變剪裁框的大小。
   zoomable：類型：Boolean，默認值true。是否容許放大縮小圖片。
   mouseWheelZoom：類型：Boolean，默認值true。是否容許經過鼠標滾輪來縮放圖片。
   touchDragZoom：類型：Boolean，默認值true。是否容許經過觸摸移動來縮放圖片。
   rotatable：類型：Boolean，默認值true。是否容許旋轉圖片。
   minContainerWidth：類型：Number，默認值200。容器的最小寬度。
   minContainerHeight：類型：Number，默認值100。容器的最小高度。
   minCanvasWidth：類型：Number，默認值0。canvas 的最小寬度（image wrapper）。
   minCanvasHeight：類型：Number，默認值0。canvas 的最小高度（image wrapper）。
   build：類型：Function，默認值null。build.cropper事件的簡寫方式。
   built：類型：Function，默認值null。built.cropper事件的簡寫方式。
   dragstart：類型：Function，默認值null。dragstart.cropper事件的簡寫方式。
   dragmove：類型：Function，默認值null。dragmove.cropper事件的簡寫方式。
   dragend：類型：Function，默認值null。dragend.cropper事件的簡寫方式。
   zoomin：類型：Function，默認值null。zoomin.cropper事件的簡寫方式。
   zoomout：類型：Function，默認值null。zoomout.cropper事件的簡寫方式。
   }}}

方法

由於圖片是異步加載的，因此你須要在built以後才能調用下面的方法，setAspectRatio、replace和destroy方法例外。
$().cropper({
built: function () {
$().cropper('method', argument1, , argument2, ..., argumentN)
}
}

 

move(offsetX, offsetY)：
1.offsetX：類型：Number，水平方向上移動的大小，單位像素。
2. offsetY：類型：Number，垂直方向上移動的大小，單位像素。

移動一幅圖片：
$().cropper('move', 1, 0)
$().cropper('move', 0, -1)

 

zoom(ratio)：
ratio：
類型：Number
Zoom in：須要一個正數（ratio > 0）
Zoom out：須要一個負數（ratio < 0）

縮放一幅圖片：
$().cropper('zoom', 0.1)
$().cropper('zoom', -0.1)

 

rotate(degree)：
ratio：
類型：Number
Rotate right：須要一個正數（degree > 0）
Rotate left：須要一個負數（degree < 0）

旋轉一幅圖片，須要CSS3 Transforms3d的支持（IE10+）：

$().cropper('rotate', 90)
$().cropper('rotate', -90)

 

enable()：使cropper可用。
disable()：凍結cropper。
reset()：重置剪裁區域的圖片到初始狀態。
clear()：清空剪裁區域。

replace(url)：
url：
類型：String
一個新的圖片URL
替換圖片的URL重建cropper。

getData()：

返回值：
類型：Object
屬性：
<1>x：剪裁區域左側的偏移。
<2>y：剪裁區域距上部的偏移。
<3>width：剪裁區域的寬度。
<4>height：剪裁區域的高度。
<5>rotate：圖片的旋轉角度。
下圖演示從原始圖片中返回的剪裁區域數據。 

 

getContainerData()：

返回值： 類型：Object 屬性： width：容器的當前寬度。 height：容器的當前高度。  輸出容器尺寸數據。 getImageData()： 返回值： 類型：Object 屬性： left：圖片的左側偏移。 top：圖片的上部偏移。 width：圖片的寬度。 height：圖片的高度。 輸出圖片的位置和尺寸大小。  getCanvasData()： 返回值： 類型：Object 屬性： left：canvas的左側偏移。 top：canvas的上部偏移。 width：canvas的寬度。 height：canvas的高度。 輸出canvas（圖片容器）的位置和尺寸大小。  etCanvasData(data)： 返回值： 類型：Object 屬性： left：canvas的距離左側新的偏移。 top：canvas的距離上部新的偏移。 width：canvas新的寬度。 height：canvas新的高度。 改變canvas（圖片容器）的位置和尺寸大小。 getCropBoxData()： 返回值： 類型：Object 屬性： left：剪裁區域距離左側的偏移。 top：剪裁區域距離上部的偏移。 width：剪裁區域的寬度。 height：剪裁區域的高度。  輸出剪裁區域的位置和尺寸大小。 setCropBoxData(data)： 返回值： 類型：Object 屬性： left：剪裁區域距離左側新的偏移。 top：剪裁區域距離上部新的偏移。 width：剪裁區域新的寬度。 height：剪裁區域新的高度。 改變剪裁區域的位置和尺寸大小。  getCroppedCanvas([options])： 參數（默認值）： 類型：Object 屬性： width：輸出的canvas目標寬度。 height：輸出的canvas目標高度。 fillColor：canvas中填充的顏色。 返回值： 類型：HTMLCanvasElement 一個畫有剪裁圖片的canvas。 瀏覽器支持： 基本圖像：須要Canvas的支持（IE9+） 旋轉圖像：須要CSS3 animations Transforms3d的支持（IE10+） 跨域圖像：須要HTML5 CORS settings attributes的支持（IE11+） 獲取canvas繪製的剪裁圖像。 在這以後，你能夠直接將canvas做爲圖片顯示，或使用canvas.toDataURL方法獲取圖像的數據連接，或者使用canvas.toBlob方法獲取一個blob，並經過FormData方法將它更新到服務器上（若是瀏覽器支持這些API）。 $().cropper('getCroppedCanvas') $().cropper('getCroppedCanvas', { width: 160, height: 90 }); 複製代碼 setAspectRatio(aspectRatio)： aspectRatio： 類型：Number 須要一個正整數。 改變剪裁區域的比例。 setDragMode([mode])： mode（可選項）： 類型：String 默認值：'' 選項：'crop'或'move' 改變拖拽模式。提示：你能夠經過雙擊來改變"crop" 和 "move"模式。 事件  build.cropper：當cropper對象開始加載圖片的時候觸發該事件。 built.cropper：當cropper對象構建完成時觸發該事件。 dragstart.cropper：  event.dragType： "crop"：建立一個新的剪裁區域。 "move"：移動canvas。 "zoom"：經過觸摸移動來縮放canvas。 "e"：調整剪裁區域東邊的尺寸大小。 "w"：調整剪裁區域西邊的尺寸大小。 "s"：調整剪裁區域南邊的尺寸大小。 "n"：調整剪裁區域北邊的尺寸大小。 "se"：調整剪裁區域東南邊的尺寸大小。 "sw"：調整剪裁區域西南邊的尺寸大小。 "ne"：調整剪裁區域東北邊的尺寸大小。 "nw"：調整剪裁區域西北邊的尺寸大小。 "all"：移動剪裁區域。 該事件在剪裁區域發生改變時觸發。 相關的原始事件：mousedown、touchstart。  $('img').on('dragstart.cropper', function (e) { console.log(e.type); // dragstart console.log(e.namespace); // cropper console.log(e.dragType); // ... }); 複製代碼 dragmove.cropper： event.dragType：和dragstart.cropper相同。 當剪裁區域發生改變時觸發。 相關的原始事件：mousemove、touchmove。 dragend.cropper： event.dragType：和dragstart.cropper相同。 當剪裁區域改變結束時觸發。 相關的原始事件：mouseup、mouseleave、touchend、touchleave和touchcancel。  zoomin.cropper：當cropper對象開始放大canvas時觸發。 zoomout.cropper：當cropper對象開始縮小canvas時觸發。  No conflict：若是你使用了相同名稱空間的其它插件，能夠經過$.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 38+ Firefox 33+ Internet Explorer 8+ Opera 25+ Safari 5.1+