SpreadJS 自定义函数实战指南：从入门到避坑

在企业级表格应用开发中，内置函数往往难以满足复杂的业务逻辑需求。SpreadJS 作为一款功能强大的类 Excel 表格控件，提供了灵活的自定义函数（Custom Function） 能力，让开发者可以像使用 SUM、VLOOKUP 那样，在单元格公式中直接调用自己编写的逻辑。本文将围绕"什么是自定义函数"、"如何实现"、"异步场景处理"以及"新手避坑指南"四个维度，带你全面掌握 SpreadJS 自定义函数的开发技巧。

一、为什么需要自定义函数？

函数的本质是"封装好的代码片段"。用户通过简单调用（如 =SUM(A1:A10)），即可完成复杂操作，无需重复编写逻辑。SpreadJS 的内置函数虽覆盖数学、逻辑、查找等常见场景，但在面对以下情况时仍显不足：

业务规则特殊：如固定资产折旧计算、行业特定指标；
依赖外部数据：如实时汇率、商品库存、用户信息；
多人协作需统一逻辑：避免因手动计算导致结果不一致。

自定义函数的价值在于：

✅ 提升效率：一键完成复杂计算；
✅ 动态响应：数据变化自动更新结果；
✅ 标准化逻辑：确保团队内计算规则统一。

二、从零实现一个自定义函数

在 SpreadJS 中，创建自定义函数只需三步：定义逻辑 → 注册函数 → 应用调用。

1.定义函数逻辑

你需要创建一个函数类，继承自 GC.Spread.CalcEngine.Functions.Function，并实现 evaluate 方法。该方法负责接收参数、执行计算并返回结果。

JavaScript 复制代码

function FactorialFunction() {
  this.name = "FACTORIAL";
  this.maxArgs = 1;
  this.minArgs = 1;
}
FactorialFunction.prototype = new GC.Spread.CalcEngine.Functions.Function();
FactorialFunction.prototype.evaluate = function (arg) {
  let result = 1;
  if (arguments.length === 1 && !isNaN(parseInt(arg))) {
    for (let i = 1; i <= arg; i++) {
      result = i * result;
    }
    return result;
  }
  return "#VALUE!";
};
FactorialFunction.prototype.description = function () {
  return {
    name: "FACTORIAL",
    description:
      "这是一个计算从 1 开始的阶乘并在单元格中显示的函数",
    parameters: [{ name: "number" }],
  };
};

常见的实战案例包括：

阶乘函数：处理单个数值的递归计算；
阶乘数组函数：支持对区域（如 A1:A5）批量计算；
固定资产折旧函数：根据年限、残值率等参数计算月折旧额。

2.注册函数

通过 workbook.addCustomFunction() 将函数注册到工作簿（或工作表、全局），使其可在公式中被识别。

JavaScript 复制代码

let factorial = new FactorialFunction();
// 工作簿级别注册
spread.addCustomFunction(factorial);
// 工作表级别注册
sheet.addCustomFunction(factorial);

3.在单元格中使用

注册成功后，即可像内置函数一样使用，例如：=FACTORIAL(5) 或 =DEPRECIATION(B2, C2, D2)。

三、异步函数：处理外部数据依赖

普通自定义函数是同步执行 的，一旦涉及网络请求（如调用 API 获取汇率）、数据库查询或耗时计算，就会阻塞 UI 线程，导致表格卡顿。此时，应使用 异步自定义函数。

异步函数的核心特点：

不立即返回结果，而是发起异步操作；
表格暂时显示默认值（如 "Loading..."）；
异步完成后，通过 context.setAsyncResult(result) 自动更新单元格。

典型应用场景：

根据商品 ID 实时获取价格；
查询用户历史订单并统计；
调用第三方服务（如天气、汇率）。

JavaScript 复制代码

function AsyncRateFunction() {
  this.name = "ASYNC_GET_RATE";
  this.minArgs = 1;
  this.maxArgs = 1;
}
AsyncRateFunction.prototype =
  new GC.Spread.CalcEngine.Functions.AsyncFunction("ASYNC_GET_RATE");
AsyncRateFunction.prototype.defaultValue = function () {
  return "加载中...";
};
AsyncRateFunction.prototype.evaluate = function (context) {
  let currency = arguments[1]?.toUpperCase();

  if (!["USD", "EUR"].includes(currency)) {
    return "#INVALID! 仅支持USD/EUR";
  }

  fetch(
    `https://api.apilayer.com/exchangerates_data/latest?base=${currency}&symbols=CNY`,
    {
      headers: { apikey: "your_api_key" },
    }
  )
    .then((res) => res.json())
    .then((data) => {
      let rate = data.rates?.CNY;
      rate
        ? context.setAsyncResult(parseFloat(rate.toFixed(4)))
        : context.setAsyncResult("#NO_DATA! 未获取到汇率");
    })
    .catch((err) => {
      context.setAsyncResult(`#API_ERROR: ${err.message}`);
    });
};
AsyncRateFunction.prototype.evaluateMode = function () {
  return 1;
};
AsyncRateFunction.prototype.description = function () {
  return {
    name: "ASYNC_GET_RATE",
    description: "异步获取指定货币的汇率",
    parameters: [{ name: "currency", description: "货币类型（USD/EUR）" }],
  };
};

💡 注意：异步函数必须在 evaluate 中调用 context.setAsyncResult()，而不能使用 return。

同步 vs 异步对比

维度	同步函数	异步函数
执行方式	立即执行，阻塞表格	异步执行，不阻塞
适用场景	本地计算（阶乘、加减）	外部数据依赖（API/DB）
返回方式	return result	context.setAsyncResult(result)
未完成状态	无	显示 defaultValue

四、新手开发避坑指南

在实际开发中，以下问题高频出现，务必提前规避：

1.导入文件后出现 `#NAME?`

原因：自定义函数在导入模板之后才注册，导致公式无法识别。 ✅ 解决方案：先导入文件 → 再注册函数 → 最后调用 workbook.calcEngine().calculate("rebuild")。

2.函数作用域混乱

函数可注册到 workbook、worksheet 或全局 GC 对象。

一般推荐注册到 workbook；
若需跨多个工作簿复用，可注册到 GC.Spread.CalcEngine.Functions.

3.返回值类型错误

同步函数：return value
数组函数：返回 CalcArray 对象
异步函数：必须用 context.setAsyncResult()

4.需访问 `workbook` 对象？

若函数需读取选区、样式等上下文信息（如实现 =SELECTION()），需设置 isContextSensitive: true。

5.参数合法性校验缺失

用户可能传入字符串、空值、错误范围。务必在 evaluate 中做类型判断与容错处理。

6.忽略单元格数据类型

看似数字的单元格可能是文本格式（如从 CSV 导入）。建议使用 parseFloat 或类型转换确保计算正确。

7.与内置函数重名

避免命名如 SUM、AVERAGE 等，否则会覆盖原生函数。

8.大数据量性能问题

遍历大范围单元格时，使用 getArray() 替代多次 getValue()，并配合 suspendPaint() 提升性能。

9.数组公式未开启动态数组

使用数组公式（如返回多单元格结果）时，需设置 workbook.options.allowDynamicArray = true。

开发建议

先易后难：从阶乘、求和等简单函数入手，再挑战异步或数组场景；
多打日志 ：在 evaluate 中 console.log 参数与中间结果，快速定位问题；
勤查文档 ：SpreadJS 官方 API 文档是最佳参考。

SpreadJS 自定义函数实战指南：从入门到避坑