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