SlickGrid的自定義cell編輯器對象接口

一個功能強大的基於jQuery的grid控件SlickGrid的自定義單元格編輯器對象接口的詳細定義：(翻譯自http://wiki.github.com/mleibman/SlickGrid/writing-custom-cell-editors)

基本接口

 

function IEditor(args) {
    // 參數args有以下成員:
    //     container: 待編輯的cell容器
   //     item: 待編輯的row數據項
   // 執行一些代碼來初始化UI

    
    this.destroy = function() {
        // 刪除constructor(就是IEditor自己)建立的任何數據、事件、DOM元素
   };

    this.focus = function() {
        // 若是可能，將焦點移動到主編輯控件上
   };

    this.isValueChanged = function() {
        // 若是編輯控件改變了內容則return true不然返回false
    };

    this.serializeValue = function() {
       // 返回編輯內容的序列化形式能夠
     // 是任何對象但必須是簡單對象，就是說即便本對象被銷燬後依然能夠被傳遞出去
   };
    
    this.loadValue = function(item) {
        // 向編輯控件裝入值並更新UI
        // 本方法可能在編輯器初始化後當即調用
     // 還可能在經過grid.updateRow/updateCell改變正在編輯的row/cell時調用
    };

    this.applyValue = function(item,state) {
    // 將存在state中的序列化形式的內容反序列化到item中
     // 本方法可能在編輯器對象(IEditor)被銷燬後調用因此這個必須是一個相似Java/C#/C++的static方法
     // 也就是說本方法執行時不能訪問任何實例變量
    };

    this.validate = function() {
        // 驗證用戶的輸入, 若是驗證經過則返回{valid:true,msg:null}, 不然
     return { valid: false, msg: "驗證出錯信息" };        
    };


    
    this.hide = function() {
     // 若是實現了本方法，當正被編輯的cell被卷滾出view時將會被調用
     // 若是你的UI不是在cell中或者你須要打開其它輔助控件(好比日曆或者日期選擇控件)時你可能須要實現這個
    };

    this.show = function() {
        // 和hide正好相反的做用
    };

    this.position = function(cellBox) {
        // 若是實現了本方法, 當cell容器滾動或者正在編輯的cell的絕對位置發生變化時會被調用
     // 若是你的UI做爲document BODY的一部分被構造，可能你須要實現這個方法以便當cell位置變化時更新你的UI
        // 參數cellBox: { top, left, bottom, right, width, height, visible }
    };
}

 

複合編輯器

在絕大多數狀況下，Cell(單元格)和數據項的字段應該是1:1的關係。但有時候，爲了提升可用性，你可能須要將多個字段放到一個單元格中編輯。能夠定製一個formatter將多個字段的內容組合到一個單元格中顯示。SlickGrid經過調用定製編輯器對象接口的loadValue(從字段到編輯控件)、serializeValue(從編輯控件到序列化形式)以及applyValue(從序列化形式到字段)方法的方式很容易實現多個字段在一個單元格中編輯的UI。儘管這裏有三個方法比getValue/SetValue這樣僅需兩個方法要稍微複雜點，可是後者沒法實現前述的多字段複合編輯器。

例子參見http://mleibman.github.com/SlickGrid/examples/example3a-compound-editors.html

介入單元格編輯過程

你能夠輕易地鉤住onCellChange事件以便當單元格被編輯改變後運行一些代碼。你還能夠經過grid.options的editCommandHander選項來設定一個定製的處理器來介入單元格編輯過程，而後你就能夠徹底控制如何以及什麼時候提交編輯的內容。因爲applyValue()和serializeValue()互不相關，你甚至能在提交修改後撤消這些修改。這個特性當你編輯遠程數據時尤爲有用：你能夠經過一個ajax調用來應用這些修改並在其錯誤處理代碼中撤消這些修改，這樣當服務器端沒法保存修改時仍然保持數據的同步。你還能夠將這些編輯命令存在一個隊列中，而後用不多的一點代碼實現undo/redo。

當編輯器的destropy()調用後將調用editCommandHandler，傳遞的參數有數據項、單元格的列定義以及編輯命令：

function editCommandHandler(item,column,editCommand) {}

 

編輯命令對象有以下屬性和方法：

• row: 被編輯的單元格行號
• cell: 被編輯的單元格列號
• editor: 對編輯器接口對象的引用
• serializedValue: 編輯結果的序列化形式，就是當destroy編輯器對象後對editor.serializeValue()的調用結果
• prevSerializedValue: 用戶修改之前調用editor.serializeValue()獲得的序列化形式
• execute(): 調用本方法會在editor對象上調用editor.applyValue(item,serializedValue)保存修改到數據項
• undo(): 調用本方法會調用editor.applyValue(item,prevSerializedValue)恢復數據項到未修改前

 

實現了undo的例子參見：http://mleibman.github.com/SlickGrid/examples/example3b-editing-with-undo.html