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

SpreadJS 本身内置提供了一个很强大的功能，那就是命令（Command）。命令实际上就是把前端用户的操作封装成接口，让技术人员在代码中也可以完美模拟终端用户来执行一些操作。

下载SpreadJS最新试用版

前言 | 问题背景

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

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

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

// 获取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

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

1、GC.Spread.Commands

GC.Spread.Commands是命令的命名空间

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

2、GC.Spread.Commands.CommandManager

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

3、GC.Spread.Commands.UndoManager

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

4、GC.Spread.Sheets.Commands

这个类中定义了SpreadJS目前支持的所有命令。

5、CommandManager Method

用来获取当前Workbook实例的command manager对象。

6、UndoManager Method

用来获取当前Workbook实例的undo command对象。

示例

上一节说了那么多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, isMetaspread.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();});

购买SpreadJS正版授权，请点击“咨询在线客服”哟！

标签：表格控件Spread