Fast XML Parser v6 配置选项详解：解析器与输出构建器配置指南

前言

Fast XML Parser 是一个高性能的 XML 解析库，其 v6 版本提供了丰富的配置选项，允许开发者根据需求灵活调整解析行为。本文将深入解析该库的两大类配置选项：解析器配置和输出构建器配置，帮助开发者充分利用这个强大的工具。

解析器配置详解

解析器配置主要控制 XML 解析的核心行为，以下是关键配置项及其作用：

命名空间处理

• removeNSPrefix：布尔值，控制是否移除标签名或属性名中的命名空间前缀。当设置为 true 时，会将 ns:tag 转换为 tag。

特殊节点处理

• stopNodes：数组，指定哪些嵌套标签即使出现错误也不进行解析。这对于处理已知问题节点非常有用。
• htmlEntities：布尔值，决定是否处理 HTML 实体（如 & 转换为 &）。

标签处理配置

tags: {
  unpaired: [], // 指定自闭合标签列表
  nameFor: {
    cdata: false, // CDATA 节点在输出中的名称
    comment: false, // 注释节点在输出中的名称
    text: '#text'  // 文本节点的名称
  },
  separateTextProperty: false // 是否将文本内容分离为独立属性
}

属性处理配置

attributes: {
  ignore: false, // 是否忽略所有属性
  booleanType: true, // 是否自动将"true"/"false"字符串转为布尔值
  entities: true // 是否解析属性值中的实体
}

选择性解析

• only：数组，指定仅解析哪些标签，其余标签将被跳过，结果将呈现为扁平数组
• skip：数组，指定要跳过的标签，解析时会触发 on('skip') 事件
• select：数组，当匹配到指定标签时会触发 on('select') 事件
• stop：数组，指定不解析的标签路径，其内部 XML 将作为字符串值保留

输出构建器配置详解

输出构建器配置决定了解析结果的格式和组织方式：

输出结构控制

• preserveOrder：布尔值，当设置为 true 时，将使用 'join' 值解析器处理标签值，保持原始顺序

节点命名配置

nameFor: {
  text: "#text", // 文本节点的名称
  comment: "",   // 注释节点的名称
  cdata: ""      // CDATA 节点的名称
}

XML 特殊标记处理

• piTag：布尔值，是否处理处理指令标签
• declaration：布尔值或字符串，控制 XML 声明处理（如 <?xml version="1.0"?>）

标签值解析器

tags: {
  valueParsers: [
    // "trim",    // 修剪空白
    // "boolean", // 转为布尔值
    // "number",  // 转为数字
    // "currency",// 货币格式处理
    // "date"     // 日期格式处理
  ]
}

属性处理配置

attributes: {
  prefix: "@_", // 属性名前缀
  suffix: "",   // 属性名后缀
  groupBy: "",  // 属性分组依据
  valueParsers: [
    // 与标签值解析器相同的选项
  ]
}

实践示例

以下是一个完整的配置示例，展示了如何组合使用这些选项：

const XMLParser = require("fast-xml-parse/src/v6/XMLParser");
const JsObjOutputBuilder = require("fast-xml-parse/src/v6/OutputBuilders/JsObjBuilder");

const xmlData = fs.readFileSync("sample.xml").toString();

// 输出构建器配置
const outputBuilderOptions = {
  preserveOrder: true,
  attributes: {
    prefix: "attr_",
    valueParsers: ["trim", "number"]
  }
};

// 解析器配置
const parserOptions = {
  removeNSPrefix: true,
  attributes: {
    ignore: false,
    booleanType: true
  },
  tags: {
    separateTextProperty: true
  },
  OutputBuilder: new JsObjOutputBuilder(outputBuilderOptions)
};

const parser = new XMLParser(parserOptions);
let result = parser.parse(xmlData);

console.log(JSON.stringify(result, null, 2));

最佳实践建议

1. 性能考量：对于大型 XML 文件，建议启用 only 或 skip 选项来减少不必要的解析工作

2. 数据一致性：使用 valueParsers 确保数值、日期等类型数据的一致性

3. 调试技巧：利用 onAttribute 和 on('select') 等回调函数进行调试和日志记录

4. 特殊字符处理：根据 XML 内容特点合理配置 htmlEntities 和 entities 选项

5. 输出格式：根据应用需求选择合适的输出构建器（JsObjBuilder、JsArrBuilder 或 JsMinArrBuilder）

通过合理配置这些选项，开发者可以精确控制 Fast XML Parser 的行为，使其适应各种复杂的 XML 处理场景。