萬盛學電腦網

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

jQuery jCrop + FileAPI 實現圖片上傳、裁剪、預覽全流程(無需伺服器端處理)

專案亮點

  • **純前端裁剪**:利用 `FileAPI` (Mail.ru) 在瀏覽器端完成裁剪,不上傳原圖至伺服器,節省頻寬、保護隱私。
  • **跨瀏覽器相容**:現代瀏覽器用 `Canvas` 裁剪;IE6~IE9 自動降級用 Flash 代理。
  • **jCrop 整合**:專業裁剪 UI(選區拖拽、比例鎖定、預覽區即時同步)。
  • **SeaJS 模組化載入**:按需載入 CSS/JS,依賴管理清晰。

核心實現邏輯

var el = $('input').get(0); // 

seajs.use(['gallery/jcrop/0.9.12/jcrop.css', 'gallery/jcrop/0.9.12/jcrop.js'], function() {
    FileAPI.event.on(el, 'change', function(evt) {
        // 1. 取得檔案列表
        var files = FileAPI.getFiles(evt);

        // 2. 過濾:只允許圖片、限制大小
        FileAPI.filterFiles(files, function(file, info) {
            if (!/^image/.test(file.type)) { alert('請選擇圖片'); return false; }
            if (file.size > 20 * FileAPI.MB) { alert('圖片不可超過 20MB'); return false; }
            return true;
        }, function(files, rejected) {
            if (!files.length) return;

            var file = files[0];
            // 3. 建立兩個 Image 實例:一個供 jCrop 選區,一個供最終裁剪輸出
            var imgForCrop = FileAPI.Image(file);
            var imgForOutput = FileAPI.Image(file);
            var ratio = 1; // 原圖與顯示圖的縮放比

            // 4. 取得原圖尺寸計算縮放比 (限制顯示寬/高 500px)
            FileAPI.getInfo(file, function(err, info) {
                if (!err && info.width && info.height) {
                    ratio = Math.max(info.width, info.height) / 500;
                }
            });

            // 5. 縮放圖片供 jCrop 顯示 (最大 500x500)
            imgForCrop.resize(500, 500, 'max').get(function(err, imgEl) {
                $('#img2').empty().append($(imgEl)); // 載入裁剪預覽區

                // 6. 初始化 jCrop
                $('#img2').children().Jcrop({
                    aspectRatio: 1,           // 正方形裁剪框
                    bgColor: 'rgba(0,0,0,0.4)', // 遮罩顏色
                    onSelect: function(c) {    // 選區變更回調
                        // 將選區座標映射回原圖座標系
                        imgForOutput.matrix.sx = c.x * ratio;
                        imgForOutput.matrix.sy = c.y * ratio;
                        imgForOutput.matrix.sw = c.w * ratio;
                        imgForOutput.matrix.sh = c.h * ratio;
                        imgForOutput.matrix.dw = 500; // 輸出寬
                        imgForOutput.matrix.dh = 500; // 輸出高

                        // 即時生成裁剪預覽
                        imgForOutput.get(function(err, outImg) {
                            $('#img3').html($(outImg)); // 顯示裁剪結果
                        });
                    }
                });
            });

            // 7. 確認上傳按鈕
            $('#btn').on('click', function() {
                FileAPI.upload({
                    // url: '/api/upload', // 實際上傳端點
                    files: { images: imgForOutput }, // 直接上傳裁剪後的 Image 實例
                    progress: function(evt) { /* 進度條 */ },
                    complete: function(err, xhr) {
                        console.log('上傳完成', xhr.responseText);
                    }
                });
            });
        });
    });
});

HTML 結構

<input type="file" accept="image/*" />
<div id="img2"><!-- jCrop 裁剪區 --></div>
<div id="img3"><!-- 裁剪結果預覽 --></div>
<button id="btn">確認上傳</button>

FileAPI 關鍵矩陣屬性說明

`FileAPI.Image` 實例的 `matrix` 物件控制輸出變換:

屬性含義
`sx`, `sy`源圖裁剪起始座標 (左上角)
`sw`, `sh`源圖裁剪寬高
`dx`, `dy`目標畫布繪製起始座標
`dw`, `dh`目標畫布繪製寬高 (最終輸出尺寸)
`rotate`旋轉角度 (度)
`flip`翻轉模式

裁剪邏輯核心:`onSelect` 回調中,將 jCrop 給出的**顯示層座標** `c.x, c.y, c.w, c.h` 乘以 `ratio` 映射為**原圖座標**,賦值給 `imgForOutput.matrix`,再呼叫 `.get()` 生成裁剪後圖片。

優缺點與現代替代

維度jCrop + FileAPI現代方案 (Cropper.js + Canvas API)
依賴jQuery, jCrop, FileAPI, SeaJS無依賴 / 輕量 ES Module
IE 支援IE6+ (Flash 降級)IE10+ (Canvas)
維護狀態FileAPI 2016 年停更Cropper.js 活躍維護
功能豐富度基礎裁剪、旋轉、縮放觸控、縮放手勢、向量裁剪、EXIF 方向修正
包體積~150KB (含 jQuery)~30KB (Cropper.js gzip)

遷移建議

新專案請直接使用 **Cropper.js** 或 **React/Vue 組件庫** (如 `vue-cropperjs`、`react-image-crop`),僅在必須支援 IE8 以下的老舊專案維護此方案。

copyright © 萬盛學電腦網 all rights reserved