萬盛學電腦網

您现在的位置: 萬盛學電腦網 >> 程式設計 >  >> 腳本程式專題 >> JavaScript

Jcrop 圖片裁切外掛完整參數與 API 速查表

前言

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>

完整 Options 參數表

參數預設值說明
allowSelecttrue允許建立新選區
allowMovetrue允許移動選區
allowResizetrue允許縮放選區
aspectRatio0寬高比 (0=自由)。width/height,如 4/3=1.333
minSize[0,0]最小選區 [w,h],小於此自動取消
maxSize[0,0]最大選區 [w,h]
setSelectnull初始選區 [x, y, x2, y2]
boxWidth0畫布最大寬度(圖片縮放上限)
boxHeight0畫布最大高度
boundary2邊界間距,允許從邊緣開始拖曳
bgColor'black'遮罩背景色
bgOpacity0.6遮罩透明度 0-1
bgFadefalse遮罩淡入動畫
borderOpacity0.4選區邊框透明度
handleOpacity0.5控制點透明度
handleSize9控制點大小 (px)
handleOffset5控制點超出邊框距離
keySupporttrue鍵盤控制(方向鍵移動、Esc 取消、Tab 離開)
cornerHandlestrue顯示四角控制點
sideHandlestrue顯示四邊控制點
drawBorderstrue繪製選區邊框
dragEdgestrue允許拖曳邊框移動
addClassnull額外 CSS 類別前綴
baseClass'jcrop'基礎 CSS 類別前綴
onChangefunction(){}選區改變時觸發 (拖曳中持續觸發)
onSelectfunction(){}選區確定時觸發 (滑鼠釋放)
onReleasefunction(){}取消選區時觸發
fadeTime400淡入動畫毫秒數
animationDelay20動畫延遲
swingSpeed3動畫速度
touchSupportnull觸控支援 (auto/true/false)

API 方法表 (透過 jcrop_api 呼叫)

方法參數說明
setImageurl切換圖片 (保留選區比例)
setOptionsobject動態修改參數
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]

常見進階用法

1. 固定比例 + 最小尺寸 (頭像裁切)

$('#avatar').Jcrop({
    aspectRatio: 1,
    minSize: [80, 80],
    maxSize: [300, 300],
    setSelect: [50, 50, 250, 250],
    boxWidth: 500,
    bgOpacity: 0.5,
    bgColor: 'white'
});

2. 動態切換圖片 (AJAX 上傳預覽)

function previewNewImage(url) {
    jcrop_api.setImage(url);
    // 圖片載入後可選擇性重置選區
    jcrop_api.setSelect([0, 0, 200, 200]);
}

3. 取得實際裁切座標送後端 (含縮放修正)

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]
    });
}

4. 觸控裝置優化

$('#cropbox').Jcrop({
    touchSupport: true,     // 啟用觸控
    handleSize: 16,         // 加大控制點
    handleOffset: 8,
    borderOpacity: 0.6,
    bgOpacity: 0.4
});

後端裁切參考 (PHP + GD)

遷移提醒:Jcrop 3 / Cropper.js

  • Jcrop 2.x 依賴 jQuery,維護模式。
  • 新專案建議使用 Cropper.js (無依賴、ES6 模組、支援 Vue/React、功能更豐富)。
  • API 概念相似:new Cropper(image, options)、cropper.getData()、cropper.setData()。

總結

Jcrop 參數豐富,核心在於 aspectRatio、minSize/maxSize、onSelect 回調。掌握 tellSelect() 取得實際座標與 getScaleFactor() 處理縮放修正是後端對接關鍵。新專案優先評估 Cropper.js。

copyright © 萬盛學電腦網 all rights reserved