Jcrop 是 jQuery 經典圖片裁切外掛,支援選區拖曳、縮放、比例限制、動畫、觸控等功能。本文整理初始化參數、API 方法、事件回調完整速查表,並提供最小可用範例。
<!-- 1. 引入 CSS/JS -->
<link rel="stylesheet" href="css/jquery.Jcrop.css">
<script src="js/jquery.js"></script>
<script src="js/jquery.Jcrop.js"></script>
<!-- 2. 目標圖片 -->
<img id="cropbox" src="photo.jpg">
<!-- 3. 初始化 -->
<script>
$('#cropbox').Jcrop({
aspectRatio: 1, // 正方形裁切
setSelect: [0, 0, 200, 200], // 初始選區
onSelect: updateCoords // 選區變更回調
}, function() {
// this 即為 Jcrop API 物件
window.jcrop_api = this;
});
function updateCoords(c) {
$('#x').val(c.x);
$('#y').val(c.y);
$('#w').val(c.w);
$('#h').val(c.h);
}
</script>
<!-- 4. 表單隱藏欄位送至後端 -->
<form action="/upload" method="post">
<input type="hidden" name="x" id="x">
<input type="hidden" name="y" id="y">
<input type="hidden" name="w" id="w">
<input type="hidden" name="h" id="h">
<button type="submit">上傳裁切</button>
</form>
| 參數 | 預設值 | 說明 |
|---|---|---|
| allowSelect | true | 允許建立新選區 |
| allowMove | true | 允許移動選區 |
| allowResize | true | 允許縮放選區 |
| aspectRatio | 0 | 寬高比 (0=自由)。width/height,如 4/3=1.333 |
| minSize | [0,0] | 最小選區 [w,h],小於此自動取消 |
| maxSize | [0,0] | 最大選區 [w,h] |
| setSelect | null | 初始選區 [x, y, x2, y2] |
| boxWidth | 0 | 畫布最大寬度(圖片縮放上限) |
| boxHeight | 0 | 畫布最大高度 |
| boundary | 2 | 邊界間距,允許從邊緣開始拖曳 |
| bgColor | 'black' | 遮罩背景色 |
| bgOpacity | 0.6 | 遮罩透明度 0-1 |
| bgFade | false | 遮罩淡入動畫 |
| borderOpacity | 0.4 | 選區邊框透明度 |
| handleOpacity | 0.5 | 控制點透明度 |
| handleSize | 9 | 控制點大小 (px) |
| handleOffset | 5 | 控制點超出邊框距離 |
| keySupport | true | 鍵盤控制(方向鍵移動、Esc 取消、Tab 離開) |
| cornerHandles | true | 顯示四角控制點 |
| sideHandles | true | 顯示四邊控制點 |
| drawBorders | true | 繪製選區邊框 |
| dragEdges | true | 允許拖曳邊框移動 |
| addClass | null | 額外 CSS 類別前綴 |
| baseClass | 'jcrop' | 基礎 CSS 類別前綴 |
| onChange | function(){} | 選區改變時觸發 (拖曳中持續觸發) |
| onSelect | function(){} | 選區確定時觸發 (滑鼠釋放) |
| onRelease | function(){} | 取消選區時觸發 |
| fadeTime | 400 | 淡入動畫毫秒數 |
| animationDelay | 20 | 動畫延遲 |
| swingSpeed | 3 | 動畫速度 |
| touchSupport | null | 觸控支援 (auto/true/false) |
jcrop_api 呼叫)| 方法 | 參數 | 說明 |
|---|---|---|
| setImage | url | 切換圖片 (保留選區比例) |
| setOptions | object | 動態修改參數 |
| setSelect | [x,y,x2,y2] | 程式化建立選區 |
| animateTo | [x,y,x2,y2] | 動畫建立選區 |
| release | - | 取消選區 |
| disable | - | 禁用 Jcrop (選區保留) |
| enable | - | 啟用 Jcrop |
| destroy | - | 完全移除 Jcrop、恢復原圖 |
| tellSelect | - | 取得選區實際座標 [x,y,x2,y2] |
| tellScaled | - | 取得選區顯示座標 (縮放後) |
| getBounds | - | 取得圖片實際尺寸 [w,h] |
| getWidgetSize | - | 取得顯示尺寸 [w,h] |
| getScaleFactor | - | 取得縮放比例 [scaleX, scaleY] |
$('#avatar').Jcrop({
aspectRatio: 1,
minSize: [80, 80],
maxSize: [300, 300],
setSelect: [50, 50, 250, 250],
boxWidth: 500,
bgOpacity: 0.5,
bgColor: 'white'
});
function previewNewImage(url) {
jcrop_api.setImage(url);
// 圖片載入後可選擇性重置選區
jcrop_api.setSelect([0, 0, 200, 200]);
}
function submitCrop() {
const coords = jcrop_api.tellSelect(); // 實際像素座標
const scale = jcrop_api.getScaleFactor(); // [scaleX, scaleY]
// 若圖片被縮放顯示,tellSelect 已回傳實際座標,通常無需再換算
// 但若後端需要原圖座標,確認 tellSelect 是否為原圖座標 (官方文檔: 實際尺寸)
$.post('/api/crop', {
x: coords[0], y: coords[1],
w: coords[2] - coords[0],
h: coords[3] - coords[1]
});
}
$('#cropbox').Jcrop({
touchSupport: true, // 啟用觸控
handleSize: 16, // 加大控制點
handleOffset: 8,
borderOpacity: 0.6,
bgOpacity: 0.4
});
new Cropper(image, options)、cropper.getData()、cropper.setData()。Jcrop 參數豐富,核心在於 aspectRatio、minSize/maxSize、onSelect 回調。掌握 tellSelect() 取得實際座標與 getScaleFactor() 處理縮放修正是後端對接關鍵。新專案優先評估 Cropper.js。