市场平台
作者 NativeScript.org
nativescript-xml2js
由 spike1292 创建 | v0.5.2
简单的 XML 到 JavaScript 对象转换器。
npm i --save nativescript-xml2js

nativescript-xml2js (基于 node-xml2js)

你是否有过解析 XML 的冲动？并且想以某种合理、简单的方式访问数据？不想编译 C 解析器？那么 xml2js 就是你要找的！

描述

简单的 XML 到 JavaScript 对象转换器。支持双向转换。使用 sax-js 和 xmlbuilder-js。

注意：如果你在寻找一个完整的 DOM 解析器，你可能需要 JSDom。

安装

安装 nativescript-xml2js 最简单的方法是使用 npm，只需 npm install --save nativescript-xml2js，这将下载 xml2js 及所有依赖项。

使用

无需复杂的教程，因为你是一位聪明的开发者！解析 XML 的任务应该是简单的，让我们让它变得如此！以下是一些示例。

一次性使用

你想尽可能简单、容易地解析 XML？单独去很危险，带上这个

var parseString = require('nativescript-xml2js').parseString;
var xml = "<root>Hello xml2js!</root>"
parseString(xml, function (err, result) {
    console.dir(result);
});

这还不够简单吗？这从 nativescript-xml2js 0.2.3 开始工作。使用 CoffeeScript 则看起来像这样

{parseString} = require 'xml2js'
xml = "<root>Hello xml2js!</root>"
parseString xml, (err, result) ->
    console.dir result

如果你需要一些特殊选项，不必担心，nativescript-xml2js 支持许多选项（见下文），你可以将这些选项作为第二个参数指定

parseString(xml, {trim: true}, function (err, result) {
});

像蛋糕一样简单使用

没错，如果你一直在使用 xml-simple 或自定义包装器，这正是在 0.1.11 中为你添加的

var fs = require('fs'),
    xml2js = require('nativescript-xml2js');

var parser = new xml2js.Parser();
fs.readFile(__dirname + '/foo.xml', function(err, data) {
    parser.parseString(data, function (err, result) {
        console.dir(result);
        console.log('Done');
    });
});

看，没有事件监听器！

你还可以使用 nativescript-xml2js 从 CoffeeScript，进一步减少混乱

fs = require 'fs',
xml2js = require 'nativescript-xml2js'

parser = new xml2js.Parser()
fs.readFile __dirname + '/foo.xml', (err, data) ->
  parser.parseString data, (err, result) ->
    console.dir result
    console.log 'Done.'

但如果你忘了创建新的 Parser 时的 new 关键字？在深夜编码会议中，它可能会丢失。别担心，我们为你考虑到了！从 0.2.8 开始，你也可以省略它，在这种情况下，nativescript-xml2js 会友好地为你添加它，不会出现任何坏惊喜和不可解释的错误！

解析多个文件

如果你想解析多个文件，你有多种选择

  • 你可以为每个文件创建一个 xml2js.Parser。这是推荐的方法，并保证始终 正常工作。
  • 你可以在解析器对象上调用 reset()。
  • 你可以寄希望于一切顺利。这种行为并不保证总是工作，如果曾经工作过。如果可能，请使用选项 #1。谢谢！

那么你想要一些 JSON 吗？

只需将 result 对象包裹在 JSON.stringify 调用中，如下所示 JSON.stringify(result)。你将获得一个包含解析对象 JSON 表示的字符串，你可以将其提供给渴望 JSON 的消费者。

显示结果

你可能想知道为什么使用 console.dir 或 console.log 时，在某些级别上的输出仅为 [Object]。别担心，这不是因为 xml2js 懒惰。这是因为在 Node 中，使用 util.inspect 将对象转换为字符串，该函数在 depth=2 时停止，这对于大多数 XML 来说有点低。

要显示整个结果，你可以使用 console.log(util.inspect(result, false, null))，这将显示整个结果。

关于这一点就讲到这里，但如果您使用eyes来获得美观的彩色输出，并且它使用…截断输出怎么办？别担心，也有针对这个问题的解决方案，您只需要通过创建自定义检查器来增加maxLength限制：var inspect = require('eyes').inspector({maxLength: false})，然后您可以轻松地执行inspect(result)。

XML构建器使用方法

从0.4.0版本开始，也可以使用对象来构建XML

var fs = require('fs'),
    xml2js = require('nativescript-xml2js');

var obj = {name: "Super", Surname: "Man", age: 23};

var builder = new xml2js.Builder();
var xml = builder.buildObject(obj);

目前，默认配置下保证了一对一的双向转换，除了您可以根据个人喜好重新定义的attrkey、charkey和explicitArray选项外。通过设置cdata选项为true支持写入CDATA。

处理属性、标签名和值

从0.4.1版本开始，您可以可选地提供解析器属性名和标签名处理器以及元素值处理器（从0.4.14版本开始，您也可以可选地提供解析器属性值处理器）


function nameToUpperCase(name){
    return name.toUpperCase();
}

//transform all attribute and tag names and values to uppercase
parseString(xml, {
  tagNameProcessors: [nameToUpperCase],
  attrNameProcessors: [nameToUpperCase],
  valueProcessors: [nameToUpperCase],
  attrValueProcessors: [nameToUpperCase]},
  function (err, result) {
    // processed data
});

tagNameProcessors和attrNameProcessors选项接受一个具有以下签名的函数数组

function (name){
  //do something with `name`
  return name
}

attrValueProcessors和valueProcessors选项接受一个具有以下签名的函数数组

function (value, name) {
  //`name` will be the node name or attribute name
  //do something with `value`, (optionally) dependent on the node/attr name
  return value
}

一些处理器是默认提供的，可以在lib/processors.js中找到

  • normalize：将名称转换为小写。（当options.normalize设置为true时自动使用）

  • firstCharLowerCase：将第一个字符转换为小写。例如，'MyTagName'变为'myTagName'

  • stripPrefix：删除xml命名空间前缀。例如<foo:Bar/>将变为'Bar'。（注意：不会删除xmlns前缀。）

  • parseNumbers：将类似于整数的字符串解析为整数，将类似于浮点数的字符串解析为浮点数。例如，"0"变为0，"15.56"变为15.56

  • parseBooleans：将类似于布尔值的字符串解析为布尔值。例如，"true"变为true，"False"变为false

选项

除了默认设置之外，还有许多可以为解析器指定的选项。通过new Parser({optionName: value})指定选项。可能的选项包括

  • attrkey（默认：$）：用于访问属性的限定符。0.1版本的默认值为@。
  • charkey（默认：_）：用于访问字符内容的限定符。0.1版本的默认值为#。
  • explicitCharkey（默认：false）
  • trim（默认：false）：从文本节点的开始和结束处删除空白。
  • normalizeTags（默认：false）：将所有标签名转换为小写。
  • normalize（默认：false）：删除文本节点内的空白。
  • explicitRoot（默认：true）：如果您想获取结果对象中的根节点，则设置此选项。
  • emptyTag（默认：''）：空节点的值是什么。
  • explicitArray（默认：true）：如果为true，则始终将子节点放在数组中；否则，只有当有多个子节点时才创建数组。
  • ignoreAttrs（默认：false）：忽略所有XML属性，仅创建文本节点。
  • mergeAttrs（默认：false）：将属性和子元素作为父元素的属性合并，而不是将属性键从子属性对象中键入。如果ignoreAttrs为false，则忽略此选项。
  • validator（默认null）：您可以指定一个可调用的函数，该函数以您想要的方式验证结果结构。请参阅单元测试示例。
  • xmlns（默认 false）：给每个元素添加一个通常称为'$ns'（第一个字符与attrkey相同）的字段，其中包含其本地名称和命名空间URI。
  • explicitChildren（默认 false）：将子元素放入单独的属性中。如果mergeAttrs = true，则不起作用。如果元素没有子元素，则不会创建"children"。在0.2.5版本中添加。
  • childkey (默认 $$): 如果 explicitChildren 设置为 true，则用于访问子元素的命名前缀。自 0.2.5 版本添加。
  • preserveChildrenOrder (默认 false): 修改 explicitChildren 的行为，使 "children" 属性的值成为一个有序数组。当此值为 true 时，每个节点也将获得一个 #name 字段，其值将对应于 XML 的 nodeName，这样您就可以遍历 "children" 数组，同时还能确定节点名称。在配置中，命名属性（可能是不有序的）也以与有序的 "children" 数组相同级别保留。自 0.4.9 版本添加。
  • charsAsChildren (默认 false): 确定 chars 是否应被视为子元素，如果 explicitChildren 已开启。自 0.2.5 版本添加。
  • includeWhiteChars (默认 false): 确定是否包含仅包含空白字符的文本节点。自 0.4.17 版本添加。
  • async (默认 false)：回调函数是否为异步？如果您的代码依赖于回调函数的同步执行，则这可能会导致不兼容的改变。未来版本的 xml2js 可能会更改此默认值，因此建议不要依赖于同步执行。自 0.2.6 版本添加。
  • strict (默认 true)：将 sax-js 设置为严格或非严格解析模式。默认值为 true，强烈推荐，因为解析非规范化的 XML 可能会产生任何东西。自 0.2.7 版本添加。
  • attrNameProcessors (默认：null)：允许添加属性名称处理函数。接受具有以下签名的函数数组
    function (name){
        //do something with `name`
        return name
    }
    自 0.4.14 版本添加
  • attrValueProcessors (默认：null)：允许添加属性值处理函数。接受具有以下签名的函数数组
    function (name){
      //do something with `name`
      return name
    }
    自 0.4.1 版本添加
  • tagNameProcessors (默认：null)：允许添加标签名称处理函数。接受具有以下签名的函数数组
    function (name){
      //do something with `name`
      return name
    }
    自 0.4.1 版本添加
  • valueProcessors (默认：null)：允许添加元素值处理函数。接受具有以下签名的函数数组
    function (name){
      //do something with `name`
      return name
    }
    自 0.4.6 版本添加

Builder 类的选项

这些选项通过 new Builder({optionName: value}) 指定。可能选项有

  • rootName (默认 root 或根键名)：在 explicitRoot 为 false 或要覆盖根元素名称的情况下使用的根元素名称。
  • renderOpts (默认 { 'pretty': true, 'indent': ' ', 'newline': '\n' })：xmlbuilder-js 的渲染选项。
    • pretty：美化生成的 XML
    • indent：缩进使用的空白（仅在 pretty 时有效）
    • newline：换行符（仅在 pretty 时有效）
  • xmldec (默认 { 'version': '1.0', 'encoding': 'UTF-8', 'standalone': true })：XML 声明属性。
    • xmldec.version 版本号字符串，例如 1.0
    • xmldec.encoding 编码声明，例如 UTF-8
    • xmldec.standalone 独立文档声明：true 或 false
  • doctype (默认 null)：可选 DTD。例如 {'ext': 'hello.dtd'}
  • headless (默认: false)：省略 XML 头部。自 0.4.3 版本添加。
  • allowSurrogateChars (默认: false)：允许使用 Unicode 置替块中的字符。
  • cdata (默认: false)：在必要时将文本节点用 <![CDATA[ ... ]]> 包装而不是转义。如果不必要，则不会添加 <![CDATA[ ... ]]>。自 0.4.5 版本添加。

renderOpts、xmldec、doctype 和 headless 通过 xmlbuilder-js 传递。

更新到新版本

版本 0.2 修改了默认解析设置，但版本 0.1.14 引入了版本 0.2 的默认设置，因此可以在迁移之前尝试这些设置。

var xml2js = require('nativescript-xml2js');
var parser = new xml2js.Parser(xml2js.defaults["0.2"]);

要获取0.2版本中的0.1默认值，您只需在同一位置使用xml2js.defaults["0.1"]即可。这为您提供了足够的时间迁移到nativescript-xml2js 0.2中更合理、更简单的解析方式。我们尽量使迁移过程简单、温和，但某些破坏是不可避免的。

那么，具体发生了什么变化？为什么？在0.2版本中，我们更改了一些默认设置，以便以更通用、更合理的方式解析XML。因此，我们禁用了normalize和trim，这样xml2js就不会裁剪任何文本内容。当然，您可以根据需要重新启用此功能。一个更重要的变化是通过explicitRoot设置，在生成的JavaScript结构中返回根标签，因此您需要访问第一个元素。这对于想知道根节点是什么以及保留更多信息的人来说很有用。最后一个重大变化是启用explicitArray，因此，每当可能将多个子标签嵌入到一个标签中时，xml2js >= 0.2即使在数组只包含一个元素的情况下，也会返回一个数组。这对于处理返回可变数量子标签的API很有用。

运行测试，开发

Build Status Coverage Status Dependency Status

开发需求由npm处理，您只需安装它们即可。我们还有许多单元测试，可以直接从项目根目录使用npm test运行。这会运行zap以发现所有测试并执行它们。

如果您想贡献，请注意nativescript-xml2js是用CoffeeScript编写的，因此请不要在提交到仓库以方便起见的所有JavaScript文件上进行开发。此外，请编写一些单元测试来检查您的行为，如果是面向用户的功能，请添加一些文档到这个README中，这样人们就会知道它的存在。提前感谢！

获取支持

请，如果您对这个库有问题，首先确保您已经阅读了这份README。如果您已经读到这里，谢谢，您做得很好。然后，请确保您的问题确实是nativescript-xml2js的问题。是吗？好的，我会看看。给我发邮件，我们可以谈谈。请不要打开问题，因为我认为这不是支持问题的正确论坛。有些问题可能是nativescript-xml2js中的真正错误，如果是这样，我会让您知道打开问题的替代方案：）

但如果您确信您真的找到了一个错误，请随时打开一个问题。