前言 | 问题背景

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示例,点击这里下载


SpreadJS | 下载试用

纯前端表格控件SpreadJS,是市面上布局与功能都与 Excel 高度类似的一款表格控件,全中文操作界面,适用于.NET、Java、移动端等多个平台的类 Excel 数据开发,备受华为、中通、民航飞行学院等国内知名企业客户青睐。

您对SpreadJS产品的任何技术问题,都有技术支持工程师提供1对1专业解答,点击此处即可发帖提问>>技术支持论坛