# @builttocreate/hot-formula-parser 中文文档

规范地址：https://npmcn.com/package/%40builttocreate/hot-formula-parser/

版本：5\.0\.2
npm 元数据更新时间：2026-10-16T17:49:55.227Z
中文译文更新时间：2026-11-08T19:24:02.777Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40builttocreate/hot-formula-parser
原文对照：https://npmcn.com/package/%40builttocreate/hot-formula-parser/?lang=original
项目主页：https://github.com/handsontable/formula-parser
源码仓库：https://github.com/handsontable/formula-parser

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：622 kB，12 个文件
- 模块格式：CommonJS
- TypeScript 类型：未声明
- 运行依赖：2 个
- 首次发布：2021-02-15T15:19:05.372Z
- 最新版本发布：2022-11-11T13:36:03.908Z
- 近 30 天下载量：80960（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：9（近 12 个月 0 个）

## 中文简介

公式解析器

## 安装

```sh
npm install @builttocreate/hot-formula-parser
```

也可以使用：`pnpm add @builttocreate/hot-formula-parser`、`yarn add @builttocreate/hot-formula-parser`、`bun add @builttocreate/hot-formula-parser`

## README

# 公式解析器 [![Build Status](https://travis-ci.org/handsontable/formula-parser.png?branch=master)](https://travis-ci.org/handsontable/formula-parser) [![Test Coverage](https://codeclimate.com/github/handsontable/formula-parser/badges/coverage.svg)](https://codeclimate.com/github/handsontable/formula-parser/coverage) [![hot-formula-parser](https://img.shields.io/npm/v/hot-formula-parser.svg)](https://www.npmjs.com/package/hot-formula-parser)

图书馆提供a `Parser` 类,用于评价优异的数学公式.

* * *

## 安装

建议安装公式解析器的方法已经通过 [国家预防机制](https://www.npmjs.com/) 使用下列命令:

```sh
$ npm install hot-formula-parser --save
```

节点.js:

```js
var FormulaParser = require('hot-formula-parser').Parser;
var parser = new FormulaParser();

parser.parse('SUM(1, 6, 7)'); // It returns `Object {error: null, result: 14}`
```

浏览器 :

```html
<script src="/node_modules/hot-formula-parser/dist/formula-parser.min.js"></script>
<script>
var parser = new formulaParser.Parser();

parser.parse('SUM(1, 6, 7)'); // It returns `Object {error: null, result: 14}`
</script>
```

## 特征

它支持:

-   任何数值,负数和正数为浮动或整数;
-   算术操作类 `+`, (中文(简体) ), `-`, (中文(简体) ), `/`, (中文(简体) ), `*`, (中文(简体) ), `%`, (中文(简体) ), `^`· ;
-   逻辑操作类 `AND()`, (中文(简体) ), `OR()`, (中文(简体) ), `NOT()`, (中文(简体) ), `XOR()`· ;
-   比较诸如 `=`, (中文(简体) ), `>`, (中文(简体) ), `>=`, (中文(简体) ), `<`, (中文(简体) ), `<=`, (中文(简体) ), `<>`· ;
-   所有 JavaScript 数学常数都喜欢 `PI()`, (中文(简体) ), `E()`, (中文(简体) ), `LN10()`, (中文(简体) ), `LN2()`, (中文(简体) ), `LOG10E()`, (中文(简体) ), `LOG2E()`, (中文(简体) ), `SQRT1_2()`, (中文(简体) ), `SQRT2()`· ;
-   字符串操作像 `&` (协和eq. `parser.parse('-(2&5)');` 将返回 `-25`(三);
-   定义的所有优秀公式 [公式.js (简体中文)](https://github.com/handsontable/formula.js)· ;
-   相对和绝对的单元格坐标 `A1`, (中文(简体) ), `$A1`, (中文(简体) ), `A$1`, (中文(简体) ), `$A$1`· ;
-   内置变量如 `TRUE`, (中文(简体) ), `FALSE`, (中文(简体) ), `NULL`
-   自定义变量;
-   自定义函数/公式;
-   节点和浏览器环境.

## API( 方法)

```js
var parser = new formulaParser.Parser();
```

### .parse( 表达式)

提供解析和评价表达式。 它总是以 `result` 财务报告和审定财务报表 `error` 属性. `result` 属性 总是保持评价值。 如果发生错误 `error` 属性将被设定为:

-   `#ERROR!` 一般错误;
-   `#DIV/0!` 除以零出错;
-   `#NAME?` 未识别函数名称或可变名称;
-   `#N/A` 表示公式没有数值;
-   `#NUM!` 公式遇到无效数字时的情况;
-   `#VALUE!` 当公式参数之一为错误类型时会发生.

```js
parser.parse('(1 + 5 + (5 * 10)) / 10'); // returns `Object {error: null, result: 5.6}`
parser.parse('SUM(MY_VAR)'); // returns `Object {error: "#NAME?", result: null}`
parser.parse('1;;1'); // returns `Object {error: "#ERROR!", result: null}`
```

### .set可变(名称,值)

设定在解析公式表达式时可以可见的预定义可变名称.

```js
parser.setVariable('MY_VARIABLE', 5);
parser.setVariable('fooBar', 10);

parser.parse('(1 + MY_VARIABLE + (5 * fooBar)) / fooBar'); // returns `5.6`
```

### .getVariable(名称)

获取可变名称 .

```js
parser.setVariable('fooBar', 10);

parser.getVariable('fooBar'); // returns `10`
```

### .setFunt 函数(名称, fn)

设置在解析公式表达式时可见的自定义函数.

```js
parser.setFunction('ADD_5', function(params) {
  return params[0] + 5;
});
parser.setFunction('GET_LETTER', function(params) {
  var string = params[0];
  var index = params[1] - 1;

  return string.charAt(index);
});

parser.parse('SUM(4, ADD_5(1))'); // returns `10`
parser.parse('GET_LETTER("Some string", 3)'); // returns `m`
```

### 功能( 名称)

获取自定义函数 .

```js
parser.setFunction('ADD_5', function(params) {
  return params[0] + 5;
});

parser.getFunction('ADD_5')([1]); // returns `6`
```

### . 被推广 福尔摩斯

列出所有支持的公式函数.

```js
require('hot-formula-parser').SUPPORTED_FORMULAS; // An array of formula names
```

## API (呼声)

### 调用可变( 名称, 已完成)

获取变量时已开火 。 如果前面使用 `setVariable` 你可以用这个钩子覆盖它.

```js
parser.on('callVariable', function(name, done) {
  if (name === 'foo') {
    done(Math.PI / 2);
  }
});

parser.parse('SUM(SIN(foo), COS(foo))'); // returns `1`
```

### 调用功能( 名称、 参数、 完成)

调用函数时已开火 。 如果先前使用 `setFunction` 你可以覆盖它的结果 通过这个钩. 您也可以使用它来覆盖内建公式的结果 .

```js
parser.on('callFunction', function(name, params, done) {
  if (name === 'ADD_5') {
    done(params[0] + 5);
  }
});

parser.parse('ADD_5(3)'); // returns `8`
```

### 呼叫CellValue(CellCoord,已完成)

使用其标签获取单元格值时被解除( eq : `B3`, (中文(简体) ), `B$3`, (中文(简体) ), `B$3`, (中文(简体) ), `$B$3`) (中文(简体) ).

```js
parser.on('callCellValue', function(cellCoord, done) {
  // using label
  if (cellCoord.label === 'B$6') {
    done('hello');
  }
  // or using indexes
  if (cellCoord.row.index === 5 && cellCoord.row.isAbsolute && cellCoord.column.index === 1 && !cellCoord.column.isAbsolute) {
    done('hello');
  }

  if (cellCoord.label === 'C6') {
    done(0.75);
  }
});

parser.parse('B$6'); // returns `"hello"`
parser.parse('B$6&" world"'); // returns `"hello world"`
parser.parse('FISHER(C6)'); // returns `0.9729550745276566`
```

### 呼叫RangeValue( 启动CellCoord, 端CellCoord, 完成)

获取单元格范围值时已开火( eq : `A1:B3`, (中文(简体) ), `$A1:B$3`, (中文(简体) ), `A$1:B$3`, (中文(简体) ), `$A$1:$B$3`) (中文(简体) ).

```js
parser.on('callRangeValue', function(startCellCoord, endCellCoord, done) {
  var data = [
    [1, 2, 3, 4, 5],
    [6, 7, 8, 9, 10],
    [11, 12, 13, 14, 15],
    [16, 17, 18, 19, 20],
  ];
  var fragment = [];

  for (var row = startCellCoord.row.index; row <= endCellCoord.row.index; row++) {
    var rowData = data[row];
    var colFragment = [];

    for (var col = startCellCoord.column.index; col <= endCellCoord.column.index; col++) {
      colFragment.push(rowData[col]);
    }
    fragment.push(colFragment);
  }

  if (fragment) {
    done(fragment);
  }
});

parser.parse('JOIN(A1:E2)'); // returns `"1,2,3,4,5,6,7,8,9,10"`
parser.parse('COLUMNS(A1:E2)'); // returns `5`
parser.parse('ROWS(A1:E2)'); // returns `2`
parser.parse('COUNT(A1:E2)'); // returns `10`
parser.parse('COUNTIF(A1:E2, ">5")'); // returns `5`
```

### 想帮忙吗?

请看 [捐款额](https://npmcn.com/package/%40builttocreate/hot-formula-parser/CONTRIBUTING.md)。 。 。 .

### 更改日志

要查看最近更改的清单,见 [发布部分](https://github.com/handsontable/formula-parser/releases)。 。 。 .

### 许可证

麻省理工学院许可证(见 [自由主义](https://github.com/handsontable/formula-parser/blob/master/LICENSE) file for the full text)). 页面存档备份,存于互联网档案馆.

### 联系人

你可以联系我们 [你好@handsontable.com](mailto:hello@handsontable.com)。 。 。 .

## 常见问题

### @builttocreate/hot-formula-parser 是什么？

公式解析器

### 如何安装 @builttocreate/hot-formula-parser？

在项目目录运行 npm install @builttocreate/hot-formula-parser，或使用 pnpm add / yarn add / bun add。

### @builttocreate/hot-formula-parser 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/builttocreate\_\_hot-formula-parser 是否存在。

### @builttocreate/hot-formula-parser 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @builttocreate/hot-formula-parser 可以商用吗？

@builttocreate/hot-formula-parser 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @builttocreate/hot-formula-parser 的下载量有多少？

根据 npm 官方下载统计，@builttocreate/hot-formula-parser 在 2026/10/09 – 2026/11/07 这 30 天内被下载 80,960 次，日均约 2,699 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @builttocreate/hot-formula-parser 还在维护吗？

最新版本 5\.0\.2 发布于 2022/11/11（3 年前）；至今共发布 9 个版本，其中过去 12 个月发布了 0 个；首次发布于 2021/02/15。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。