下載SpreadJS最新試用版

前言 | 問題背景

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

這一部分我會針對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, 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();
});

購買SpreadJS正版授權，請點擊“”喲！