「上傳完圖片後在頁面上生成縮略圖預覽」是後台表單裡的高頻需求。這個功能看似簡單,但如果把上傳、渲染、表單值同步三件事揉進一個函數,後續擴展到視頻、音頻、附件上傳時就會非常痛苦。本文記錄把它抽象成組件的完整過程,重點在於職責分離與表現行為分離這兩條設計線索。

說明:演示代碼是純靜態的,文件上傳環節用 setTimeout 模擬,但調用方式與真實項目中使用的上傳組件完全一致,因此這份實現符合真實的功能需求。
從演示效果可以直接看出四條:
憑經驗還能補出兩條隱含需求:頁面處於編輯態(從數據庫讀出已有數據)時,初始就要渲染這些圖片,並依據列表長度決定上傳按鈕是否顯示;頁面處於只讀態時,初始就要把上傳按鈕和刪除按鈕全部移除。
表單頁面的圖片最終要提交給後台,所以靜態結構裡必須預留一個隱藏文本域,上傳成功和刪除成功後都要同步它的值。結構大致如下:
<div class="appForm-group-img-upload clearfix">
<label>法人身份證電子版</label>
<div>
<input id="legalPersonIDPic-input" name="legalPersonIDPic" type="hidden">
<ul id="legalPersonIDPic-view" class="image-upload-view clearfix">
<li class="view-item-add">
<a class="view-act-add" href="javascript:;" title="點擊上傳">+</a>
</li>
</ul>
<p class="img-upload-msg">請確保圖片清晰,文字可辨</p>
</div>
</div>
整個預覽區就是一個 ul,第一個 li 充當上傳按鈕。按職責拆開,至少需要三個部分:一個負責文件上傳,一個負責預覽列表的增刪渲染,一個負責文本域值的管理。千萬不要把它們两两或全部封在一起,否則耦合過重,可擴展性和可重用性都很差。三者之間需要協作時,通過回調函數或發布訂閱定義對外接口即可。
文本域管理邏輯很輕,函數級封裝就夠了;文件上傳可以直接引入成熟開源方案(如 webuploader)或在其上做二次封裝;預覽管理是本文重點,封裝為 ImageUploadView。從需求看,它有語義的實例方法就三個:render 負責初始化渲染,append 負責追加,delItem 負責刪除。
再結合需求補上配置項:readonly 控制頁面是否可編輯,sizeLimit 控制數量上限。事件方面參照 bootstrap 插件的慣例,每個方法配一對事件,例如 render.before 在主邏輯執行前觸發,若外部監聽器調用了 preventDefault(),主邏輯就不再執行;render.after 則在主邏輯完成後觸發。這種成對定義既開放了擴展點,也讓默認行為可被攔截。
最後一點是抽象:上傳圖片、視頻、音頻、普通文檔這幾類需求裡有大量相似邏輯,應該抽一個基類,讓通用部分完全與 HTML 結構解耦。基類只做 option 定義、行為定義、事件綁定與觸發,把具體渲染留給子類。基類不碰任何 HTML 和 CSS,適用範圍自然比受結構約束的子類更大。
最終的繼承鏈是:ImageUploadView → FileUploadBaseView → EventBase。基類的默認配置如下:
var DEFAULTS = {
data: [], // 展示數據,元素須為對象,如 [{url:'xxx.png'}]
sizeLimit: 0, // 元素個數上限,0 表示不限
readonly: false, // 是否允許增刪
onBeforeRender: $.noop, // render.before
onRender: $.noop, // render.after
onBeforeAppend: $.noop, // append.before
onAppend: $.noop, // append.after
onBeforeDelItem: $.noop, // delItem.before
onDelItem: $.noop // delItem.after
};
基類把每個行為拆成「模板方法 + 待實現方法」兩層,以此統一處理事件派發:
render: function () {
var e;
this.trigger(e = $.Event('render.before'));
if (e.isDefaultPrevented()) return;
this._render(); // 交給子類
this.trigger($.Event('render.after'));
},
_render: function () {},
append: function (item) {
var e;
if (!item) return;
item = resolveDataItem(item);
this.trigger(e = $.Event('append.before'), item);
if (e.isDefaultPrevented()) return;
this.data.push(item);
this._append(item);
this.trigger($.Event('append.after'), item);
},
_append: function (data) {},
delItem: function (uuid) {
var e, item = this.getDataItem(uuid);
if (!item) return;
this.trigger(e = $.Event('delItem.before'), item);
if (e.isDefaultPrevented()) return;
this.data.splice(this.getDataItemIndex(uuid), 1);
this._delItem(item);
this.trigger($.Event('delItem.after'), item);
},
_delItem: function (data) {}
子類只重寫帶下劃線的方法,不要覆蓋 render、append、delItem,否則就得自己處理事件觸發。此外基類在初始化時會給每條數據打上 _uuid 標記,方便後續按標識查找與刪除。

ImageUploadView 的 DEFAULTS 要擴展而非覆蓋父類配置,這樣既保留了通用選項,又能新增自己的:
var DEFAULTS = $.extend({}, FileUploadBaseView.DEFAULTS, {
onAppendClick: $.noop // 點擊上傳按鈕的回調,外部可在此調起上傳組件
});
init 中先調用父類 init 完成配置解析與通用事件綁定,再綁定上傳與刪除的監聽,最後手動調一次 render,這樣實例化完成就能立刻看到效果。渲染時的判斷很關鍵:
_render: function () {
var html = [], that = this;
// 非只讀,且未達上限,才顯示上傳按鈕
if (!(this.readOnly || (this.sizeLimit && this.sizeLimit <= this.data.length))) {
this._setItemAddHtml();
}
this.data.forEach(function (item) {
html.push(that._getItemRenderHtml(item));
});
this.$element.append($(html.join('')));
},
_dealWithSizeLimit: function () {
if (!this.sizeLimit) return;
var $itemAddLi = this.$element.find('li.view-item-add');
if (this.sizeLimit <= this.data.length && $itemAddLi.length) {
$itemAddLi.remove(); // 達上限,移除上傳按鈕
} else if (!$itemAddLi.length) {
this._setItemAddHtml(); // 未達上限且按鈕不在,補回來
}
},
_append: function (data) {
this.$element.append($(this._getItemRenderHtml(data)));
this._dealWithSizeLimit();
},
_delItem: function (data) {
$('#' + data._uuid).remove();
this._dealWithSizeLimit();
}

上傳組件用異步任務模擬,只暴露一個 onSuccess 回調和一個 openChooseFileWin 方法:
define(function (require, exports, module) {
return function () {
var imgList = ['../img/1.jpg', '../img/2.jpg', '../img/3.jpg', '../img/4.jpg'], i = 0;
var that = this;
that.onSuccess = function (uploadValue) {};
this.openChooseFileWin = function () {
setTimeout(function () {
that.onSuccess(imgList[i++]);
if (i == imgList.length) i = 0;
}, 1000);
};
};
});
頁面邏輯把三者串起來:上傳成功後既調 append 追加預覽,也把數據寫進隱藏文本域;刪除時通過 onDelItem 把文本域中對應記錄清掉。
var $input = $('#legalPersonIDPic-input');
var data = JSON.parse($input.val() || '[]');
var appendImageInputValue = function ($input, item) {
var value = JSON.parse($input.val() || '[]');
value.push(item);
$input.val(JSON.stringify(value));
};
var removeImageInputValue = function ($input, uuid) {
var value = JSON.parse($input.val() || '[]'), index;
value.forEach(function (item, i) { if (item._uuid === uuid) index = i; });
value.splice(index, 1);
$input.val(JSON.stringify(value));
};
var fileUploader = new FileUploader();
fileUploader.onSuccess = function (uploadValue) {
var item = { url: uploadValue };
legalPersonIDPicView.append(item);
appendImageInputValue($input, item);
};
var legalPersonIDPicView = new ImageUploadView('#legalPersonIDPic-view', {
data: data,
sizeLimit: 4,
onAppendClick: function () { fileUploader.openChooseFileWin(); },
onDelItem: function (d) { removeImageInputValue($input, d._uuid); }
});
這個組件寫起來並不難,真正的時間成本花在抽象上——反覆權衡哪些邏輯屬於通用層、哪些屬於業務層。抽象是主觀的,每個人的思考路徑不同,結論也會不同,所以這篇更傾向於分享思路而非宣稱唯一正解。如果你在職責分離、表現與行為分離這兩個方向上有自己的實踐心得,也歡迎對照參考。