创建自定义名称

自定义用户定义名称是表示工作表中信息的标识符。自定义名称可以引用单元格范围或公式。

您可以定义一个自定义名称，然后在公式中使用该名称。当公式被计算时，将引用并评估自定义名称的值。使用 addCustomName 方法创建自定义名称。

以下代码示例创建了一个自定义名称。

activeSheet.setValue(0, 0, 1);
activeSheet.setValue(0, 1, 2);
activeSheet.setValue(0, 2, 3);

// 通过将 isReadOnly 参数设置为 true 添加自定义名称
activeSheet.addCustomName("customName1","=12", 0, 0, 'readonly', true);

activeSheet.addCustomName("customName2","Average(20,45)", 0, 0);
activeSheet.addCustomName("customName3", "=$B$1:$C$1", 0, 0);

activeSheet.setFormula(1, 0, "customName1");
activeSheet.setFormula(1, 1, "customName2");
activeSheet.setFormula(1, 2, "sum(customName3)");

SpreadJS 不允许您在 SpreadJS Designer 的名称管理器对话框中更改或删除只读自定义名称。如果选择了只读自定义名称，编辑和删除按钮将被禁用，双击只读自定义名称将没有响应。只读自定义名称的状态只能使用 API 设置或更改。

更新自定义名称

您可以使用 NameInfo 类的 set 方法更新公式或任何其他信息，例如更改名称或现有自定义名称的注释。

以下代码示例使您能够更新自定义名称信息：

// 重命名自定义名称时，所有引用的公式将被重新计算
activeSheet.getCustomName("customName2").set("updatedName");

没有工作表名称的自定义名称公式在没有工作表中的自定义名称时会更新为使用 spread 实例的自定义名称。

以下代码示例使您能够使用 spread 的自定义名称：

spread.sheets[0].setFormula(0, 0, "=customName1+1");
spread.sheets[0].setFormula(1, 0, "=Sheet1!customName1+1");
spread.addCustomName("customName1", "111"); // A1 显示 111，A2 保持 #NAME!
spread.getCustomName("customName1").set("customUpdateName1"); // A1:=bbb+1 A2:=Sheet1!customName1+1

但是，如果更新的自定义名称已经存在，则会抛出“无效的自定义名称”错误。例如：

activeSheet.addCustomName("updatedName", "222");
activeSheet.getCustomName("customName2").set("updatedName");

SpreadJS 支持更新自定义名称信息的各种其他场景如下：

当旧名称未在公式中使用并且新名称在公式中被引用时，设置名称后引用新名称的单元格公式将被重新计算。例如：

activeSheet.setFormula(2, 0, "updatedName+1"); // 公式结果为 #NAME!
activeSheet.getCustomName("customName1").set("updatedName"); // 公式结果为 13

当公式中同时引用新名称和旧名称时。例如：

// 抛出异常 'Both the current name and new name are referenced in cell formulas'
activeSheet.setFormula(1, 0, "customName1");
activeSheet.setFormula(1, 1, "updatedName");
activeSheet.getCustomName("customName1").set("updatedName");

更新公式并重命名自定义名称。例如：

activeSheet.getCustomName("customName2").set("updatedName","SUM(20,45)");

使用基准行和基准列更新自定义名称公式并更新注释。例如：

activeSheet.getCustomName("customName2").set(null,"=A1", 0,1, "the cell adjacent to the upper left corner");

更新自定义名称注释。例如：

activeSheet.addCustomName("customName4", "=$A$1");
activeSheet.getCustomName("customName4").set(null, null, null, null, "the A1 cell in current sheet");

更新在另一个自定义名称中使用的自定义名称。例如：

activeSheet.addCustomName("customName4", "=$A$1");
activeSheet.addCustomName("customName5", "=customName4+1");
activeSheet.getCustomName("customName4").set("customName6", "=$C$2", null, null); // 自定义名称 customName5 将变为 "=customName6+1"

更新在另一个自定义名称中使用的自定义名称，其中旧名称未使用但新名称在使用。例如：

activeSheet.addCustomName("customName4", "=$A$1");
activeSheet.addCustomName("customName5", "=customName6+1");
activeSheet.getCustomName("customName4").set("customName6", "=$D$2", null, null); //customName4 将更改为 customName6

type=warning
注意：SpreadJS 不会根据工作簿的自定义名称修改公式。