EasyUI 是建在 jQuery 之上的一系列 UI 元件庫,透過在 HTML 標籤上加 class,或用 JavaScript 呼叫對應方法,就能把平凡的 div、table、input 變成視窗、面板、資料格、樹選單等完整元件。由於元件數量多、參數琳瑯滿目,這篇把常用元件做一份分類速查。
modal:是否為模態視窗,true/false。
shadow:是否顯示視窗陰影,true/false。
title:顯示於面板頭部的標題文字。
iconCls:以 CSS class 指定一個 16×16 的標題圖示。
width / height:面板尺寸,預設 auto。
left / top:面板的左邊距與頂部位置。
cls / headerCls / bodyCls:分別為整個面板、頭部、內容加上自訂 class。
style:直接指定行內樣式。
fit:為 true 時自動適配父容器尺寸,預設 false。
border:是否顯示邊框,預設 true。
doSize:為 true 時面板會重繪並重建佈局,預設 true。
collapsible / minimizable / maximizable / closable:分別控制摺疊、最小化、最大化、關閉按鈕是否顯示,預設皆為 false。
tools:自訂工具列,每個工具包含 iconCls 與 handler 兩個屬性。
collapsed / minimized / maximized / closed:面板初始化時的狀態,預設皆為 false。
href:指定一個 URL,遠端載入資料並顯示於面板中。
loadingMessage:遠端資料載入時顯示的提示文字,預設 Loading…。
面板事件:onLoad(遠端資料載入完成)、onBeforeOpen/onOpen(打開前/後)、onBeforeClose/onClose(關閉前/後)、onBeforeDestroy/onDestroy(銷毀前/後)、onBeforeCollapse/onCollapse(摺疊前/後)、onBeforeExpand/onExpand(展開前/後)、onResize(重繪後,參數為新的 width/height)、onMove(移動後,參數為新的 left/top)、onMaximize、onRestore、onMinimize。
面板方法:options(取得設定物件)、panel(取得面板物件)、header/body(取得頭部/主體)、setTitle(設定標題)、open(開啟,傳 forceOpen=true 可跳過 onBeforeOpen)、close、destroy(同樣可用 force 參數跳過對應回呼)、refresh(設定 href 後重新載入遠端資料)、resize({width, height, left, top})、move({left, top})。
disabled:為 true 時停用按鈕,預設 false。
plain:為 true 時顯示為樸素樣式,預設 false。
required:是否必填,預設 false。
validType:驗證規則,可為 length[a,b](長度介於 a 到 b)、email、url。
missingMessage:值為空時顯示的提示(有英文預設值,可自訂覆蓋)。
invalidMessage:值格式錯誤時顯示的提示。
url:取得遠端樹資料的位址。
animate:展開/摺疊節點時是否使用動畫,預設 false。
節點屬性:text(顯示文字)、id(節點識別碼,遠端載入時很重要)、state(open 或 closed,預設 open;設為 closed 表示該節點含子節點但初始收合)、attributes(自訂屬性)、children(以陣列定義子節點)。
事件:onClick(點擊節點,參數含 id、text、attributes、target 即被點擊的 DOM)、onLoadSuccess(等同 jQuery.ajax 的 success)、onLoadError(等同 error)。
方法:reload(重新載入)、getSelected(取得選中節點,未選回傳 null)、collapse(target)/expand(target)(摺疊/展開指定節點)、append({parent, data})(在父節點下追加子節點)、remove(target)(刪除節點及其子節點)。
title / iconCls / border:標題文字、標題圖示 class、是否顯示邊框。
width / height:面板尺寸。
columns:欄位設定陣列;frozenColumns:固定在左側的欄位。
striped:是否顯示斑馬線,預設 false。
method:請求遠端資料的方法,預設 post。
nowrap:資料是否強制單行顯示,預設 true。
idField:指定哪個欄位作為識別鍵。
url:遠端資料來源。
loadMsg:載入提示文字,預設 Processing, please wait …。
pagination:是否顯示分頁工具列,預設 false。
rownumbers:是否顯示序號欄,預設 false。
singleSelect:是否只允許單選一列,預設 false。
fit:是否適配父容器,預設 false。
pageNumber:初始頁碼,預設 1。
pageSize:初始每頁筆數,預設 10。
pageList:每頁筆數可選清單,預設 [10,20,30,40,50]。
queryParams:請求時額外附帶的參數。
sortName / sortOrder:預設排序欄位與方向(asc/desc)。
欄位(Column)屬性:title(標題)、field(對應的資料欄位名)、width(寬度)、rowspan/colspan(合併儲存格)、align(left/right/center)、sortable(是否可排序)、checkbox(該欄是否顯示勾選框)。
事件:onLoadSuccess、onLoadError、onClickRow/onDblClickRow(參數為 rowIndex 從 0 起算與 rowData)、onSortColumn(參數為排序欄位與方向)、onSelect/onUnselect(選取與取消選取某列)。
方法:options、resize、reload、fixColumnSize、loadData(載入本地資料,舊列會被清除)、getSelected(第一個選中列,未選回傳 null)、getSelections(所有選中列,無選取回傳空陣列)、clearSelections、selectRow(index)、selectRecord(idValue)、unselectRow(index)。
width / height:容器尺寸。
idSeed:衍生分頁 DOM id 的根值,預設 0。
plain:為 true 時不使用容器背景圖,預設 false。
fit:是否適配父容器,預設 false。
border:是否顯示邊框。
scrollIncrement / scrollDuration:分頁過多時的捲動幅度與動畫時間。
事件:onLoad(AJAX 分頁載入遠端資料時觸發)、onSelect、onClose。
方法:resize、add(選項物件)、close(標題)、select(標題)、exists(標題)(判斷分頁是否存在)。
分頁屬性:id、text(標題)、content(內容)、href(遠端內容 URL)、cache(是否快取,設定 href 時有效,預設 true)、icon(標題圖示 class)、closable(是否顯示關閉按鈕,預設 false)、selected(是否為初始選中頁,預設 false)、width/height。
div menu-sep:選單分隔線。
a easyui-splitbutton:附帶下拉選單的按鈕。
div easyui-accordion:手風琴式伸縮面板,繼承自 panel。
width:容器寬度。
listWidth / listHeight:下拉清單的寬與高。
valueField:綁定到 value 的資料欄位。
textField:綁定到顯示文字的資料欄位。
editable:是否可直接輸入文字,預設 true。
url:遠端載入清單資料。
事件:onLoadSuccess、onLoadError、onSelect、onChange。
方法:select(值)(選取清單中的項目)、setValue(param)(設定值,可傳字串或含 valueField/textField 的物件)、getValue()、reload()。
width:容器寬度。
treeWidth / treeHeight:樹狀清單的寬與高。
url:遠端載入樹資料。
事件:onSelect、onChange。
方法:setValue(param)(可傳節點 id 或含 id/text 的物件)、getValue()、reload()。
title:面板標題。
region:面板位置,可為 north、south、east、west、center。
border:是否顯示邊框,預設 true。
split:是否顯示分隔條讓使用者拖曳調整尺寸,預設 false。
icon:標題圖示 class。
href:遠端載入資料的 URL。
zIndex:選單的堆疊層級。
left / top:選單的起始位置,預設皆為 0。
href:點擊選項時要開啟的網址。
事件:onShow、onHide。
方法:show({left, top})(在指定位置顯示)、hide()。
disabled:是否停用,預設 false。
plain:是否顯示為樸素樣式,預設 false。
menu:用於建立對應選單的選擇器名稱。
duration:滑鼠懸停時選單持續顯示的時間(毫秒)。
min:允許的最小值,輸入小於此值時會顯示最小值。
max:允許的最大值,輸入大於此值時會顯示最大值。
precision:小數點後可精確的位數。
呼叫方式 $('#w').window({...}),參數與 easyui-window 的 CSS 類別相同。
呼叫方式 $('#t').tree({...}),參數與方法同前。
呼叫方式 $('#g').datagrid({...})。
呼叫方式 $('#c').combobox({...})/$('#ct').combotree({...})。
title:標題文字,預設 New Dialog。
collapsible / minimizable / maximizable / resizable:是否顯示摺疊、最小化、最大化按鈕,以及是否可調整大小,預設皆為 false。
toolbar:置於對話框頂部的工具列,每項可含 text、iconCls、disabled、handler。
buttons:置於底部的按鈕區,每項可含 text、iconCls、handler。
handle:指定 #id 作為拖曳把手。
disabled:是否停止拖曳,預設 false。
edge:開始拖曳的觸發寬度,預設 0。
axis:限制移動軸,v 為垂直、h 為水平,超出範圍時設為 null。
事件:onStartDrag(開始拖曳)、onDrag(拖曳中,回傳 false 可取消實際移動)、onStopDrag(停止拖曳)。
ok / cancel:自訂確定與取消按鈕的文字。
show():在螢幕右下角彈出提示。參數包含 showType(null/slide/fade/show,預設 slide)、showSpeed(顯示動畫時間,預設 600 毫秒)、width(預設 250)、height(預設 100)、msg(內容)、title(標題)、timeout(自動關閉時間,設為 0 則不自動關閉,需使用者手動關閉)。
alert():顯示含單一確定鈕的提示框。參數:title、msg、icon(error/question/info/warning)、fn(關閉後的回呼)。
confirm():顯示含確定與取消鈕的確認框。參數:title、msg、fn(b)——點擊確定時 b 為 true,其餘為 false。
prompt():顯示含輸入欄與確定/取消鈕的對話框。參數:title、msg、fn(val)——回呼會收到使用者輸入的值。
total:總筆數,預設 1。
pageSize:每頁筆數,預設 10。
pageNumber:目前頁碼,預設 1。
pageList:每頁筆數可選項,預設 [10,20,30,50]。
loading:是否處於載入中狀態,預設 false。
buttons:自訂按鈕,每項含 iconCls 與 handler。
beforePageText / afterPageText:頁碼輸入框前後的說明文字。
displayMsg:顯示的頁碼資訊文字。
事件:onSelectPage(pageNumber, pageSize)——使用者切換頁面時觸發,回呼收到新頁碼與新的每頁筆數。
EasyUI 的元件幾乎都遵循同一套模式:用 class 宣告 → 用屬性設定外觀與行為 → 用事件回呼 → 用方法查詢與操作。因此真正需要背誦的東西很少,記住這條脈絡後,查文件時只要確認參數名稱即可上手。
不過也要留意兩點:一是 EasyUI 大量依賴行內樣式與固定尺寸,與現代 CSS 佈局(Flexbox、Grid)搭配時容易互相打架,樣式客製成本不低;二是它對行動裝置的支援相對弱。若是全新專案且需要響應式設計,值得先評估其他方案;若維護的是既有後台系統,EasyUI 的高開發效率仍然很有競爭力。