深入解析如何自定义 SpreadJS 右键菜单

[powertoolsteam]

SpreadJS ( https://www.grapecity.com.cn/developer/spreadjs ) 本身支持丰富的右键菜单功能，包括单元格区域、行头区域、列头区域、角标区、表单标签区域等都可以用右键呼出对应的右键菜单，很厉害吧。但更惊喜的是，SpreadJS 还提供了自定义这些右键菜单的方法，让用户可以方便、自由地添加、删除、重新排序右键菜单，以及更改右键菜单原本的功能，甚至定义自己需要的右键菜单的样式！

注意：本博客适用 SpreadJS 版本是 V11 及以上版本。

了解 SpreadJS 右键菜单

SpreadJS 右键菜单，分布于以下几个区域，对应了各个区域所支持的操作：

1. Sheet 标签页区域（ sheetTab ）：

2. 角标区域（ corner ）：

3. 行头区域（ rowHeader ）：

4. 列头区域（ colHeader ）：

5. 数据编辑区域（ viewport ）：

6. 切片器区域（ slicer ）：

以上的所有右键菜单功能项，都是定义在一个数组对象 menuData 中，下列代码展示了如何获取这个数组：

var spread = new GC.Spread.Sheets.Workbook(document.getElementById("ss"), {
sheetCount : 1 });

var menuData = spread.contextMenu.menuData;

每个元素都是以 json 对象的方式被定义的，其中包括几类元素：

1. 不含子菜单，单击即执行的菜单项（代表项是“复制”）：

   包含属性：

   • command：代表了点击此菜单项后只需的命令操作
   • iconClass：代表了此菜单项左侧 icon 的样式
   • name：菜单项的名称（不可重复）
   • text：菜单项显示的文字
   • workArea：工作区域，“复制”操作的可用区域为 viewport + colHeader + rowHeader + slicer + corner。

2. 含有子菜单，点击子菜单项执行的菜单项（代表项是“排序”）：

   与不含子菜单的项，区别在于没有 command 属性，而多了一个 subMenu 属性，subMenu 是一个数组元素，每一个都代表了一项可执行命令：

   这个子菜单是可以继续扩展二级子菜单甚至多级子菜单的，只需要给子菜单继续添加 subMenu 属性即可。

3. 组菜单头，表示一个组菜单的头部（代表项是“粘贴选项”）：

   组菜单头依然不是可执行的项，但是它代表了一组菜单项的头部，以 type:“ groupHeader ”来定义

4. 组菜单元素，表示组菜单的元素项（代表项是“全部粘贴”）：

   组菜单元素是隶属于组菜单头元素的元素项，它们在 menuData 中是独立的元素，但是它们包含 group 属性，这个 group 属性与组菜单头元素的 name 相同，指定了其所属的组。

5. 组菜单元素

6. 分隔符，表示右键菜单中的横线（ separator ）：

   只有一个属性的元素，指定了它就是作为视觉分隔符而定义的

自定义右键菜单示例解析

OK，经过以上的分析，相信大家对 SpreadJS 右键菜单组件已经有了充分的了解，下面我用一个 Demo 展示一下具体该如何对右键菜单实现自定义。

点击下载 Demo 文件 zip 包 ( http://www.grapecity.com.cn/downloads/demo/%E6%B7%B1%E5%85%A5%E8%A7%A3%E6%9E%90%E5%A6%82%E4%BD%95%E8%87%AA%E5%AE%9A%E4%B9%89SpreadJS%E5%8F%B3%E9%94%AE%E8%8F%9C%E5%8D%95.zip )

本例中展示了三个操作，分别是为右键菜单添加项、删除右键菜单的两个指定项、自定义右键菜单的“粘贴”项。以下分别解析这三个案例的代码：

1. 为右键菜单添加一个项：

   /*
   *  定义一个命令，作为右键菜单项的执行逻辑
   * */
   spread.commandManager().register("insertRowsBehind",
       {
           canUndo: true,
           execute: function (context, options, isUndo) {
               var Commands = GC.Spread.Sheets.Commands;
               // 在此加 cmd
               options.cmd = "insertRowsBehind";
               if (isUndo) {
                   Commands.undoTransaction(context, options);
                   return true;
               } else {
                   Commands.startTransaction(context, options);
                   var sheet = spread.getActiveSheet();
                   var sels = sheet.getSelections();
                   if(sels && sels.length > 0){
                       for(var i=0; i<sels.length; i++ ){
                           var sel = sels[i];
                           var row = sel.row;
                           var rowCount = sel.rowCount;
                           sheet.addRows(row+1, rowCount);
                       }
                   }
                   Commands.endTransaction(context, options);
                   return true;
               }
           }
       });
   
   // 获取右键菜单数组
   var menuData = spread.contextMenu.menuData;
   
   console.log(menuData);
   
   // 定义一个在行头区域执行的右键菜单项
   var insertRowsBehind = {
       command: "insertRowsBehind",
       text: "向后插入行",
       // name 只要不重复即可
       name: "insertRowsBehind",
       // 把自己定义好的 icon class 加在这里
       iconClass:"gc-spread-custom-icon",
       workArea: "rowHeader"
   };
   
   // 将自定义的项，加入到“插入行”（ insertRows ）之后
   menuData.forEach(function (item, index) {
       if(item && item.name === "gc.spread.insertRows"){
           menuData.splice(index+1, 0, insertRowsBehind);
       }
   });
   
   

以上代码展示了如何实现为右键菜单添加一个自定义命令项

如果对命令不熟悉，可以参考我们的API：

1. 删除右键菜单的两个指定项：

   var menuData = spread.contextMenu.menuData;
   
   var newMenuData = [];
   
   /*
   *  注意：这里没有直接删除原数组，而是创建一个新数组，
   *  原因是在遍历数组时不能同时删除数组项，这样会导致程序运算结果错误。
   * */
   menuData.forEach(function (item) {
       if(item){
           if(item.name === "gc.spread.insertSheet" ||
               item.name === "gc.spread.deleteSheet"){
               return;
           }
           newMenuData.push(item);
       }
   });
   
   // 将新数组赋予 spread 的右键菜单属性
   spread.contextMenu.menuData = newMenuData;
   

以上代码演示了如何删除掉 sheet 标签右键菜单中的“插入”和“删除”项

1. 自定义右键菜单的“粘贴”项：

   var paste = {
       iconClass : "gc-spread-pasteAll",
       name : "gc.spread.pasteOptions",
       text : "粘贴",
       command : "gc.spread.contextMenu.pasteAll",
       workArea : "viewportcolHeaderrowHeadercorner"
   };
   
   var menuData = spread.contextMenu.menuData;
   var newMenuData = [];
   menuData.forEach(function (item) {
       if(item){
           if(item.name === "gc.spread.pasteOptions" ||
               item.group === "gc.spread.pasteOptions"){
               return;
           }
           newMenuData.push(item);
       }
   });
   newMenuData.unshift(paste);
   spread.contextMenu.menuData = newMenuData;
   
   

最后一段代码，展示了如何将“粘贴选项”组改为“粘贴”项

经过以上的解释和 Demo 分析，相信大家都掌握了基本的自定义右键菜单的方法。但是右键菜单还有更加强大的功能，它还允许用户自定义右键菜单的样式！

关于这部分内容，我将在后续文章中，结合一个实用的 Demo 做出解答。

SpreadJS | 下载试用

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