imgAreaSelect 是一個 jQuery 外掛,讓使用者能以滑鼠拖曳在圖片上框選出一塊矩形區域。這個選取結果可以進一步延伸應用,例如自圖片上裁切縮圖、標記重點區域、互動式圖片編輯等。
<script type="text/javascript">
$(document).ready(function () {
$('img#photo').imgAreaSelect({
handles: true,
onSelectEnd: someFunction
});
});
</script>
若 jQuery 物件中包有多個 img,外掛會逐一套用。實際上它並不限於 img,任何區塊級元素(例如帶背景圖的 div)都能使用。初始化時機與其他外掛相同,可放在 $(document).ready() 或 $(window).load() 中。
| 選項 | 說明 | 預設值 |
|---|---|---|
| aspectRatio | 固定長寬比,例如 "4:3",拖曳時比例不會改變。 | 無 |
| autoHide | 為 true 時選取完成後自動隱藏選區。 | false |
| classPrefix | 外掛產生元素的 class 前綴。 | imgareaselect |
| disable / enable | 暫時停用或重新啟用外掛(圖片本身仍舊可見)。 | — |
| fadeSpeed | 設定大於零的毫秒數即可套用淡入淡出效果。 | 0 |
| handles | 為 true 時在選區四角/四边顯示縮放控制點。 | false |
| hide / show | 控制選區初始是否隱藏或顯示。 | false |
| imageHeight / imageWidth | 圖片的真實高度與寬度,用於圖片曾被 CSS 縮放過的情況。 | 無 |
| instance | 為 true 時 imgAreaSelect() 會回傳 API 物件,可進一步程式化操作。 | false |
| keys | 啟用鍵盤操作選區。 | false |
| maxHeight / maxWidth / minHeight / minWidth | 以像素限制選區的最大與最小尺寸。 | 無 |
| movable | 是否允許移動選區。 | true |
| parent | 外掛元素掛載的父元素。 | body |
| persistent | 為 true 時點擊選區外不會重開新選取,使用者只能移動或縮放現有選區。 | false |
| remove | 為 true 時完全移除外掛。 | false |
| resizable | 是否允許調整選區大小。 | true |
| resizeMargin | 距邊緣多少像素內才進入縮放模式。 | 無 |
| x1 / y1 / x2 / y2 | 初始化時選區的左上與右下座標。 | 無 |
| zIndex | 外掛元素的 z-index;一般會自動計算,極少數情況才需手動指定。 | 自動 |
| onInit / onSelectStart / onSelectChange / onSelectEnd | 初始化、開始選取、選取中、選取結束時的回呼。 | 無 |
隨外掛提供三份 CSS,只需在頁面 head 引入其中一份:
CSS 資料夾內另有四張 GIF 用以繪製邊框。
外掛以數個 div 組成選區,各自帶有固定 class,因此可用 CSS 或 jQuery 選擇器自由改造外觀:
| 類別名稱 | 對應元素 |
|---|---|
| imgareaselect-selection | 選取區域本身 |
| imgareaselect-border1 ~ border4 | 選區的四條邊框,各由一個 div 組成 |
| imgareaselect-handle | 縮放控制點,四或八個 div(未啟用 handles 時不顯示) |
| imgareaselect-outer | 未被選取的外圍區域,由四個 div 組成 |

前綴 imgareaselect 為預設值,可透過 classPrefix 選項更改。當頁面上有多個選取框需要各自套用不同樣式時,這個選項特別有用。
onInit、onSelectStart、onSelectChange、onSelectEnd 都會收到兩個參數:第一個是外掛所作用圖片的參照,第二個是描述目前選區的物件,包含 x1、y1(左上角座標)、x2、y2(右下角座標)、width、height(寬高)共六個屬性。
$('img#photo').imgAreaSelect({
onSelectEnd: function (img, selection) {
alert('width: ' + selection.width + '; height: ' + selection.height);
}
});
把 keys 設為 true 後,可用鍵盤移動與縮放選區,預設行為如下:
| 按鍵 | 動作 |
|---|---|
| 方向鍵 | 每次以 10 像素為單位移動選區 |
| Shift + 方向鍵 | 每次以 1 像素為單位移動選區 |
| Ctrl + 方向鍵 | 每次以 10 像素為單位縮放選區 |
| Ctrl + Shift + 方向鍵 | 每次以 1 像素為單位縮放選區 |
也可自行覆寫,keys 可設定 arrows、shift、ctrl、alt 四個屬性,值為像素數(不小於 1)或字串 "resize":
$('img#example').imgAreaSelect({
keys: { arrows: 15, ctrl: 5, shift: 'resize' }
});
此例的意義是:方向鍵移動 15 像素、按住 Ctrl 移動 5 像素、按住 Shift 則切換為縮放模式。若頁面上有多張圖片,自訂按鍵設定會套用於目前「啟用」(被點擊)的那一張。
要使用 API,先取得外掛物件:
var ias = $('#photo').imgAreaSelect({ instance: true });
ias.setSelection(50, 50, 150, 200, true);
ias.setOptions({ show: true });
ias.update();
| 方法 | 說明 |
|---|---|
| getOptions() | 回傳目前的選項設定物件。 |
| setOptions(newOptions) | 以新的設定物件更新選項。 |
| getSelection([noScale]) | 取得目前選區;noScale 為真時不做縮放換算。 |
| setSelection(x1, y1, x2, y2, [noScale]) | 設定選區座標。注意此方法只更新內部狀態,畫面不會立即變化,必須接著呼叫 update() 且 show 選項為 true 才會顯示。 |
| cancelSelection() | 取消選取並隱藏選區,不需再呼叫 update()。 |
| update([resetKeyPress]) | 套用設定變更;resetKeyPress 設為 false 時可保留按鍵設定。 |
$('#ladybug_ant').imgAreaSelect({ maxWidth: 200, maxHeight: 150, handles: true });
$('#bee').imgAreaSelect({ aspectRatio: '4:3', handles: true });
$('#duck').imgAreaSelect({ x1: 120, y1: 90, x2: 280, y2: 210 });
下面的片段在 onSelectChange 中依選區比例縮放預覽圖,做出「局部放大鏡」的效果:
function preview(img, selection) {
var scaleX = 100 / (selection.width || 1);
var scaleY = 100 / (selection.height || 1);
$('#ferret + div > img').css({
width: Math.round(scaleX * 400) + 'px',
height: Math.round(scaleY * 300) + 'px',
marginLeft: '-' + Math.round(scaleX * selection.x1) + 'px',
marginTop: '-' + Math.round(scaleY * selection.y1) + 'px'
});
}
$(document).ready(function () {
$('<div><img src="ferret.jpg" style="position: relative;" /></div>')
.css({
float: 'left', position: 'relative',
overflow: 'hidden', width: '100px', height: '100px'
})
.insertAfter($('#ferret'));
$('#ferret').imgAreaSelect({ aspectRatio: '1:1', onSelectChange: preview });
});

選取範圍大於 100px 時,預覽圖會縮小

選取範圍小於 100px 時,預覽圖會放大
這裡用到一個關鍵技巧:等比率縮放。實際上只有一張圖,第二個區塊是同一張圖的複製品,透過 overflow: hidden 裁掉超出 100×100 的部分,再用負的 margin 把選區移到視線內,最後以 scale 因子調整整體縮放。因此程式中的 400、300 必須填「原圖的真實寬高」,一旦填錯就會出現選取偏移。
真正的裁切需要後端支援(PHP、ASP.NET、JSP 等)。前端選取只是第一步,要把結果送到伺服器,做法是放四個隱藏欄位,並在 onSelectEnd 中寫入座標:
<form action="crop.php" method="post">
<input type="hidden" name="x1" value="" />
<input type="hidden" name="y1" value="" />
<input type="hidden" name="x2" value="" />
<input type="hidden" name="y2" value="" />
<input type="submit" name="submit" value="Submit" />
</form>
<script>
$(document).ready(function () {
$('#ladybug').imgAreaSelect({
onSelectEnd: function (img, selection) {
$('input[name="x1"]').val(selection.x1);
$('input[name="y1"]').val(selection.y1);
$('input[name="x2"]').val(selection.x2);
$('input[name="y2"]').val(selection.y2);
}
});
});
</script>
送出後,後端就能取得這四個座標並進行實際裁切。若使用 PHP,以 $_POST['x1'] 等即可讀取。