# saxes 中文文档

规范地址：https://npmcn.com/package/saxes/

版本：6\.0\.0
npm 元数据更新时间：2022-05-17T04:15:01.302Z
中文译文更新时间：2026-11-05T14:44:11.733Z
软件包许可：ISC

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

原始 npm 页面：https://www.npmjs.com/package/saxes
原文对照：https://npmcn.com/package/saxes/?lang=original
项目主页：https://github.com/lddubeau/saxes#readme
源码仓库：https://github.com/lddubeau/saxes

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

- 包体积（解压后）：164 kB，5 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=v12\.22\.7
- 运行依赖：1 个
- 首次发布：2018-07-23T15:19:39.440Z
- 最新版本发布：2021-11-07T19:06:31.264Z
- 近 30 天下载量：464603073（2026-10-05 至 2026-11-03，npm 官方下载统计）
- 已发布版本数：30（近 12 个月 0 个）

## 中文简介

JavaScript 中一个事件流化的 XML 解析器

## 安装

```sh
npm install saxes
```

也可以使用：`pnpm add saxes`、`yarn add saxes`、`bun add saxes`

## README

# 萨克斯

XML 的 sax 风格的非验证分解器 .

萨克斯是叉子 [萨克斯](https://github.com/isaacs/sax-js) 1.2.4. 均提及 项目文件中的sax是指sax 1.2.4.

设计与 [节点](http://nodejs.org/) 记住,但应该做得很好 浏览器或其他常见JS执行.

Saxes不支持年龄大于10的节点版本.

## 与萨克斯的显著区别.

-   在XML方面,萨克斯要比萨克斯严格得多 形而上学 萨克斯即使在所谓的"严格模式"中也不严格. 这个 默默地接受不完善的XML结构. 需要的项目 更好地遵守良好结构的限制,不能使用萨克斯作为现实.
    
    因此,萨克斯不支持HTML,或伪XML,或坏XML. 撒克逊 在所有这些案件中,都会报告成型良好的错误,但不会试图 从错误的文档中提取数据,就像sax所做的那样.
    
-   撒克萨斯比撒克萨斯快得多,这主要是因为大幅重新设计 内部解析逻辑。 速度的提高不仅仅是因为 删除 Sax 支持的特性。 有点帮助,但萨克斯 增加一些昂贵的检查,以便符合XML 规格。 重新设计解析逻辑是大多数 业绩改进.
    
-   Saxes并非旨在支持过时的平台. 我们不会污染 源或默认构建,支持已过时的平台。 如果你想的话 支持 IE 11,欢迎您制作一个增加 _新建筑_ 转至ES5.
    
-   Saxes处理错误与Sax不同: 它提供了默认的偏差 处理者投出。 你可以用你自己的处理器来代替它 若为 你的操作员什么都不做,没有 `resume` 调用方法.
    
-   没有 `Stream` API (英语). 稍后可能会推出经过修改的API. (还是) 一个一般意义上的"流派解析器",即写字符流到 ) (中文(简体)
    
-   撒克逊没有限制数据块的大小的设施 事件处理器。 详见FAQ条目.
    

## 遵约

萨克斯支持:

-   [XML 1.0 第5版](https://www.w3.org/TR/2008/REC-xml-20081126/)
-   [XML 1.1 第二版](https://www.w3.org/TR/2006/REC-xml11-20060816/)
-   [XML 1.0 中的命名空间( 第三版)](https://www.w3.org/TR/2009/REC-xml-names-20091208/)。 。 。 .
-   [XML 1. 1 中的命名空间( 第二版)](https://www.w3.org/TR/2006/REC-xml-names11-20060816/)。 。 。 .

## 限制

这是一个不验证的解析器,所以它只验证文档是否 身材不错 我们确实想引起所有错误的构造 遇到。 然而,这个解析器并没有对以下内容进行解析: (原始内容存档于2018-10-21). DTDs. 所以大多数错误都是错误造成的 **数字化** 无法是 报告.

## 关于 `<!DOCTYPE` 财务报告和审定财务报表 `<!ENTITY`

解析器将在文本节点和属性中处理基本的 XML 实体 值 : `&amp; &lt; &gt; &apos; &quot;`。可以定义额外的 在 XML 中,将它们放入 DTD 。 这个解剖师什么也不做 那个 如果你想听的话 `doctype` 事件,然后获取 文档类型,并读取实体并添加到 `parser.ENTITIES`成为我的 来宾.

## 文档

源代码包含JSDOC的评论. 使用它们。 下面是简报 现有资料摘要。 最后权威是源代码.

**注意什么是公众和什么是私人.**

向TypeScript的移动使得现在一切正式成为私有, 保护,或公开.

如果你用什么非公开的, 那会危及你自己.

如果文件有错误,就提出问题. 如果你只是假设, 你可能猜错了.

## 使用信息摘要

### 示例

```javascript
var saxes = require("./lib/saxes"),
  parser = new saxes.SaxesParser();

parser.on("error", function (e) {
  // an error happened.
});
parser.on("text", function (t) {
  // got some text.  t is the string of text.
});
parser.on("opentag", function (node) {
  // opened a tag.  node has "name" and "attributes"
});
parser.on("end", function () {
  // parser stream is done, and ready to have more stuff written to it.
});

parser.write('<xml>Hello, <who name="world">world</who>!</xml>').close();
```

### 构造参数

支持设置 :

-   `xmlns` -布尔 若为 `true`,然后支持命名空间。 默认 实值 `false`。 。 。 .
    
-   `position` -布尔 若为 `false`,然后不要跟踪行/行/位置。 未设定为 被视为 `true`默认值未设置。 目前,设定为 `false` 仅限 导致表面变化:报告的错误不包含位置 资料。 sax-js会从字面上关闭位置计算逻辑,如果 此旗被设定为假. 概念是,它将优化 执行。 至少是在萨克斯岛 不断测试这面旗帜 导致成本抵消了关闭这一逻辑的好处.
    
-   `fileName` - 弦乐。 设置错误报告的文件名 。 这只有用 当跟踪位置。 你可以让它不固定.
    
-   `fragment` -布尔 若为 `true`,将 XML 分析为 XML 片段。 默认是 `false`。 。 。 .
    
-   `additionalNamespaces` - 一个普通对象,其密钥,值对定义 解析 XML 文件前已知的命名空间 。 不可以通过 命名空间绑定 `"xml"` 或者说 `"xmlns"`。 。 。 .
    
-   `defaultXMLVersion` - XML 规格的默认版本,如果 该文档中没有 XML 声明。 如果文档确实包含 XML 声明,然后忽略此设置。 一定是这样 `"1.0"` 或者说 `"1.1"`编辑 默认为 `"1.0"`。 。 。 .
    
-   `forceXMLVersion` -布尔 显示是否强制 XML 的旗帜 用于解析到 `defaultXMLVersion`当此旗帜 实值 `true`, (中文(简体) ), `defaultXMLVersion` 必须指明。 未说明的 此旗帜的默认值是 `false`。 。 。 .
    
    示例:假设您正在解析一个具有 XML 声明的文档 指定 XML 版本 1.1.
    
    如果你准备好了 `defaultXMLVersion` 改为 `"1.0"` 不设置 `forceXMLVersion` 然后, XML 声明将覆盖 `defaultXMLVersion` ,文档将按 XML 1.1 进行解析.
    
    如果你准备好了 `defaultXMLVersion` 改为 `"1.0"` 设置 `forceXMLVersion` 改为 `true`,则XML声明将被忽略,文档将被忽略 根据XML 1.0. 解析.
    

### 方法

`write` - 把字节写到溪上 你不必通过整份文件 在一个 `write` 电话 您可以逐个读取源代码并拨打 `write` 每个块.

`close` - 关闭溪流。 关闭后,将不再写入数据 处理缓冲器完成,缓冲器由 `end` 活动.

### 属性

剖析器有以下属性:

`line`, (中文(简体) ), `column`, (中文(简体) ), `columnIndex`, (中文(简体) ), `position` - 表明在俄罗斯联邦境内的立场 XML 文档, 解析器正在查找 。 这个 `columnIndex` 属性 计数列,如索引为 JavaScript 字符串,而 `column` 属性计算 Unicode 字符.

`closed` - 布尔表示解析器是否可以写入 。 若为 这是 `true`,然后等待时间 `ready` 再次写入的事件.

`opt` - 任何选择权传入建筑师.

`xmlDecl` - 本文的XML声明。 里面有田园 `version`, (中文(简体) ), `encoding` 财务报告和审定财务报表 `standalone`他们都是 `undefined` 在此之前 遇到 XML 声明 。 如果在 XML 之后未定义 声明,声明没有设定相应的值。 没有 与 XML 声明相关的事件。 在成型良好的文档中, XML 在声明之前只能有一个可选的BOM。 所以,到时候任何事件 通过解析器生成的,如果存在,则声明已被处理 一点也不 否则,你有一个错误的文件, 如上所述,你 无法依赖解析器数据 !

### 处理错误

即使遇到错误 解析器也继续分析 并尽力 继续报告错误。 你应该注意所有报告的错误。 之后 但是,Saxes可能会错误地解释文档。 比如说 `<foo a=bc="d"/>` 是无效的 XML 。 你是故意的吗 `<foo a="bc=d"/>` 或者说 `<foo a="b" c="d"/>` 还是别的变异? 为了继续 提供出错, saxes 将继续解析文档,但结构 报告可能不正确。 只有在文档中更正错误后 萨克斯可以对文件提供可靠的解释.

这让你有两种拇指规则 当使用萨克斯:

-   注意萨克斯报告的错误. 默认 `onerror` 处理器 扔出,所以默认情况下,不能漏出错误.
    
-   **一旦发生错误,停止 复用其他手 超过 `onerror`。 。 。 .** 如上所解释,当萨克斯 进入一个良好的形状 问题,它是一个猜测 为了继续报告更多的错误。 这个猜想 也许错了.
    

### 活动

为了听一个事件, 取消 `on<eventname>`。支持的活动清单 也在导出中 `EVENTS` 阵列.

关于每个被支持者的描述,请参看源代码中的 JSDOC 注释 活动.

### 解析 XML 碎片

XML 规格没有定义用于解析 XML 的任何方法 碎片 不过,有些使用假想方案是可取的 碎片 为了允许这一点,萨克斯提供了三个初始化选项.

如果你通过选项 `fragment: true` 到解析器构建器, 解析器 将会等待 XML 碎片 。 基本上从解析状态开始 相当于它将会在其中,如果 `parser.write("<foo">)` 被调用 初始化后立即开始 换句话说,它期望的内容是 在元素内可接受。 也关闭了造型良好的检查 当解析出碎片时不合适.

选项 `additionalNamespaces` 允许您定义额外的前缀到 URI 解析开始前已知的约束。 你会用这个 `resolvePrefix` 若为 您已经准备好一系列的命名空间 绑定使用.

选项 `resolvePrefix` 如果 它无法自行解决命名空间前缀。 你会用这个 `additionalNamespaces` 在获得完整定义清单的情况下 名称空间很繁琐.

注意,您可以使用 `additionalNamespaces` 财务报告和审定财务报表 `resolvePrefix` 一起来,如果你 想要吗. `additionalNamespaces` 适用前 `resolvePrefix`。 。 。 .

二. 备选方案 `additionalNamespaces` 财务报告和审定财务报表 `resolvePrefix` 本来是 用于解析碎片。 然而,萨克斯不会阻止你使用它们 与 `fragment: false`。请注意,如果你这样做,文档可能会解析 没有出错,但因文档可以引用命名空间而变形 未定义的 _内_ 文档.

当然, `additionalNamespaces` 财务报告和审定财务报表 `resolvePrefix` 仅当 `xmlns` 实值 `true`。如果你正在解析一个不使用命名空间的片段,那么 设置这些选项没有意义.

### 性能提示

-   saxes在使用新行的文件上工作得更快(`\u000A`)作为行尾 与使用行标其它端的文件相比的标记(如 `\r` 或者说 `\r\n`) (中文(简体) ). XML 规格要求符合要求的应用程序行为 仿佛所有要当作行尾字符的字符都是 转换为 `\u000A` 在解析之前。 萨克斯的最佳代码路径是 所有行尾字符已经存在的文件 `\u000A`。 。 。 .
    
-   不要将Unicode字符串分割给替身的萨克斯. 当你 在 JavaScript 中天真地拆分一个字符串, 您冒着拆分 Unicode 的风险 字符为两个代词。 譬如说. 在以下例子中: `a` 财务报告和审定财务报表 `b` 每一个都包含一个单一 Unicode 字符的一半 : `const a = "\u{1F4A9}"[0]; const b = "\u{1F4A9}"[1]` 如果将这种分拆的代词输入版本 4点前的萨克斯,你会出错的 Saxes 第4版及以上可以 检测某一块数据以代孕结束并结转代孕 到下一个块。 然而,这一行动需要切开和装饰 字符串。 如果你能以不分裂代孕的方式提供数据, 你应该这样做。 (显然,一次用单笔输入所有数据) 速度最快。)
    
-   不要设置你不需要的事件处理器。 撒克逊人总是要避免 但未来的改进希望做到这一点 更激烈。 萨克斯知道是否需要一些数据的方法之一是 通过检查是否为特定事件设置了处理器.
    

## 财务问题

Q. 为什么Saxes放弃了对限制数据块大小的支持 事件处理者?

A. 用萨克斯可以设置 `MAX_BUFFER_LENGTH` 来限制 传输给事件处理者的数据块大小 。 所以,如果你碰到一个字段 超过限额, 多次 `text` 发射数据块较小的事件 而不是一个大块的单一事件.

但是,这一功能有一些有问题的特点。 它有一个 任意默认值。 它是一个全库,所以所有解析器 从一个 单例 `sax` 图书馆共享。 这有可能导致 在同一 VM 中运行但使用 sax 处理不同的库之间的冲突 目标.

这些问题本来可以很容易地解决,但还有更大的问题。 这个 缓冲限制任意适用于某些事件,而不适用于其他事件。 它会分裂 `text`, (中文(简体) ), `cdata` 财务报告和审定财务报表 `script` 事件。 但是,如果 `comment`, (中文(简体) ), `doctype`, (中文(简体) ), `attribute` 或者说 `processing instruction` 不仅仅是 限制, 解析器会生成一个错误, 而您被留到 块.

这不是直觉使用。 你觉得把限制定在1K就可以阻止 大于 1K 块将传递给事件处理者 。 但这不是 案例。 源代码中的评论告诉你,如果 您将大块传递到 `write`所以,如果你想要1K的限制, 不要通过64K 块到 `write`相当公平 你知道你想要什么限制,所以你可以 控制您传递到的数据大小 `write`。所以您将块限制在 `write` 一次到1K 一次到1K 一次到1K 即使你这样做,你的事件处理者也会得到数据 大小为 2K 的块 。 假设之前 `write` 解析器有 刚刚处理完一个打开的标签, 所以它已准备好文本 。  `write` 超过1K文本。 您还没有超过极限, 所以没有生成事件 还没有。 下一个 `write` 再通过一K文本。 碰巧是萨克斯检查 每起缓冲限制一次 `write`,则在数据块已 已处理。 现在你到了极限,你得到一个 `text` 2K 时的事件 数据。 所以,即使你限制你的 `write` 呼叫你设定的缓冲限制, 您可能仍然得到 块以两倍的缓冲大小限制的事件 页:1.

我们可考虑恢复同等功能,条件是 解决上述问题,不会给 用例假想不需要它.

## 常见问题

### saxes 是什么？

JavaScript 中一个事件流化的 XML 解析器

### 如何安装 saxes？

在项目目录运行 npm install saxes，或使用 pnpm add / yarn add / bun add。

### saxes 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### saxes 支持 ESM 还是 CommonJS？

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

### saxes 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=v12\.22\.7。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### saxes 可以商用吗？

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

### saxes 的下载量有多少？

根据 npm 官方下载统计，saxes 在 2026/10/05 – 2026/11/03 这 30 天内被下载 464,603,073 次，日均约 15,486,769 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### saxes 还在维护吗？

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