如何使用SpreadJS的内置命令（Command）以及自定义命令

前言 | 问题背景

SpreadJS 本身内置提供了一个很强大的功能，那就是命令（Command）。命令实际上就是把前端用户的操作封装成接口，让技术人员在代码中也可以完美模拟终端用户来执行一些操作。同时命令还支持事务，包括多步骤的撤销、重做等。在一些情况下，我们还需要调用命令来触发一些事件。

用过SpreadJS设计器和在线表格编辑器的伙伴现在应该想到了，实际上设计器几乎所有的功能，都是用命令来封装实现的！因此当我们在操作设计器时，就和我们在使用Excel的感觉几乎是一样的。知道了命令的强大，我们一起来了解一下应该怎么驾驭它。

本文基于SpreadJS V12版本，下载请点击。

用一个简单示例来演示命令的使用

下面我用一段简单的代码来演示命令调用的方法：

// 获取ID为”ss”的div上初始化的Workbook实例
var spread = GC.Spread.Sheets.findControl("ss");
// 获取该实例的CommandManager实例
var commandManager = spread.commandManager();
// 设置当前Workbook允许撤销命令
spread.options.allowUndo = true;
// 定义操作的列集合
var columns = [ { col: 3 } ];
// 命令调用：
commandManager().execute({cmd: "autoFitColumn", sheetName: "Sheet1", columns: columns, isRowHeader: false, autoFitType: GC.Spread.Sheets.AutoFitType.cell});

以上代码示例实现了为Workbook的Sheet1表，表单第3列实现自适应列宽（autoFitColumn）的操作。其中execute方法的参数含义如下：

• cmd : 命令名称，表示此次执行的命令；（必需）
• sheetName: 表格名称，也就是Worksheet名称，表示此命令作用的具体表格；（必需）
• columns: 列集合，表示命令作用的列；
• isRowHeader: 是否行头；
• autoFitType: 自适应的类型，参考API。

与命令相关的API

这一部分我会针对SpreadJS 中与命令相关的API进行讲解，以便于想使用命令的小伙伴能够全面地掌握它的用法。

1、GC.Spread.Commands

GC.Spread.Commands是命令的命名空间，点击此处查看API。

其中包括了CommandManager和UndoManager两个类型，以及一个枚举类Key。先解释枚举类型，Key代表了常用的一些键盘编码，推荐使用Key中枚举的按键编码来替代hard code的方式，这样能够确保您程序的健壮性。

2、GC.Spread.Commands.CommandManager

定义了执行命令（execute）、注册命令（register）和设置快捷键（setShortcutKey）三个方法。我们可以采用execute来执行SpreadJS的内置命令，也可以执行我们注册的自定义命令；register是用来注册自定义命令的函数，而setShortcutKey方法则是为命令（内置或自定义）设置快捷键。点击此处查看API。

3、GC.Spread.Commands.UndoManager

定义了命令撤销、重做、清空操作栈等操作。命令之所以能被撤销，就是因为SpreadJS内部维护了一个命令的操作栈，它记录了每一步命令的执行、撤销情况，当您执行一个命令后，栈的顶部就会记录这个命令的信息，执行与撤销的顺序也是按照栈的元素顺序进行的。清空操作栈函数则可以清空命令执行的历史记录。点击此处查看API。

4、GC.Spread.Sheets.Commands

这个类中定义了SpreadJS目前支持的所有命令。点击此处查看API。

5、CommandManager Method

用来获取当前Workbook实例的command manager对象。点击此处查看API。

6、UndoManager Method

用来获取当前Workbook实例的undo command对象。点击此处查看API。

示例

上一节说了那么多API，我们该如何使用它们？下面我会用一个实例来演示如何把命令应用到具体开发中，为SpreadJS终端用户添加一个“填充当前时间”的功能。

1、一些初始设置（包括HTML和JS代码）

<div class="sample-turtorial">
    <button id="btn1">执行</button>
    <button id="btn2">回滚</button>
    <button id="btn3">重新执行</button>
    <div id="ss" style="width:70%; height:400px;border: 1px solid gray;"></div>
</div>

var spread = new GC.Spread.Sheets.Workbook(document.getElementById('ss'), { sheetCount: 1 });
var sheet = spread.getActiveSheet();
// 挂起表格绘制
sheet.suspendPaint();
// 锁定表格
sheet.options.isProtected = true;
// 设置默认列宽
sheet.defaults.colWidth = 150;
// 设置单元格默认样式为解锁状态
var ds = sheet.getDefaultStyle();
ds.locked = false;
sheet.setDefaultStyle(ds);
// 设置锁定行、列
sheet.getRange(-1, 1).backColor("red").locked(true);
sheet.getRange(1, -1).backColor("red").locked(true);
// 设置单元格格式为日期格式
sheet.setFormatter(-1, -1, "yyyy年m月d日");
// 恢复表格绘制
sheet.resumePaint();

2、设置允许Undo命令

// 设置允许撤销操作
spread.options.allowUndo = true;

3、注册自定义命令fillNow

// 注册命令的调用方法
/*
* 其中第一个参数fillNow是命令的名称
* 第二个参数
* */
spread.commandManager().register("fillNow",
{
    canUndo: true,
    execute: function (context, options, isUndo) {
        var Commands = GC.Spread.Sheets.Commands;
        // 在此加cmd名称
        options.cmd = "fillNow";
        if (isUndo) {
            // isUndo 为true时，调用undoTransaction
            Commands.undoTransaction(context, options);
            return true;
        } else {
            // 开始事务
            Commands.startTransaction(context, options);
            var sheet = spread.getActiveSheet();
            var ranges = sheet.getSelections();
            if (ranges.length > 0) {
                var range = ranges[0];
                var cell = sheet.getCell(range.row, range.col);
                if (!cell.locked()) {
                    sheet.setValue(range.row, range.col, new Date());
                }
            }
            // 结束事务
            Commands.endTransaction(context, options);
            return true;
        }
}
});

4、为自定义命令注册快捷键Ctrl + ; (分号)

// 设置快捷键：Ctrl + ;
// 参数含义：commandName, key, isCtrl, isShift, isAlt, isMeta
spread.commandManager().setShortcutKey(
        "fillNow", 186, true, false, false, false
);

5、注册按钮事件（执行命令）

$("#btn1").click(function () {
    var sheet = spread.getActiveSheet();
    // 调用命令执行
    spread.commandManager().execute({
        cmd: "fillNow",
        sheetName: sheet.name()
    });
});

6、注册按钮事件（撤销命令）

$("#btn2").click(function () {
    // 调用代码撤销
    var undoManager = spread.undoManager();
    undoManager.undo();
});

7、注册按钮事件（回滚命令）

$("#btn3").click(function () {
    // 重做
    var undoManager = spread.undoManager();
    undoManager.redo();
});

关于命令的分享就先告一段落，有遇到任何问题的朋友，欢迎访问我们GCDN论坛的SpreadJS求助中心发帖交流哦！

完整Demo示例，点击这里下载。