74 lines
4.4 KiB
Markdown
74 lines
4.4 KiB
Markdown
|
# fast-xml-builder
|
||
|
|
Build XML from JSON
|
||
|
|
|
||
|
|
|
||
|
|
XML Builder was part of [fast-xml-parser](https://github.com/NaturalIntelligence/fast-xml-parser) for years. But considering that any bug in the parser may false-alarm users who are only using the builder, we have decided to split it into a separate package.
|
||
|
|
|
||
|
|
## Installation
|
||
|
|
|
||
|
|
```bash
|
||
|
|
npm install fast-xml-builder
|
||
|
|
```
|
||
|
|
|
||
|
|
## Usage
|
||
|
|
|
||
|
|
```javascript
|
||
|
|
import XMLBuilder from 'fast-xml-builder';
|
||
|
|
|
||
|
|
const builder = new XMLBuilder();
|
||
|
|
const xml = builder.build({ name: 'value' });
|
||
|
|
```
|
||
|
|
|
||
|
|
fast-xml-builder fully supports the response generated by fast-xml-parser. You can use options like `preserveOrder`, `ignoreAttributes`, `attributeNamePrefix`, `textNodeName`, `cdataPropName`, `commentPropName`, `format`, `indentBy`, `suppressEmptyNode`, `suppressUnpairedNode`, `stopNodes`, `oneListGroup`, `maxNestedTags`, and many more.
|
||
|
|
|
||
|
|
## Default Options
|
||
|
|
|
||
|
|
```js
|
||
|
|
{
|
||
|
|
attributeNamePrefix: '@_',
|
||
|
|
attributesGroupName: false,
|
||
|
|
textNodeName: '#text',
|
||
|
|
ignoreAttributes: true,
|
||
|
|
cdataPropName: false,
|
||
|
|
commentPropName: false,
|
||
|
|
format: false,
|
||
|
|
indentBy: ' ',
|
||
|
|
suppressEmptyNode: false,
|
||
|
|
suppressUnpairedNode: true,
|
||
|
|
suppressBooleanAttributes: true,
|
||
|
|
preserveOrder: false,
|
||
|
|
processEntities: true,
|
||
|
|
unpairedTags: [],
|
||
|
|
stopNodes: [],
|
||
|
|
oneListGroup: false,
|
||
|
|
maxNestedTags: 100,
|
||
|
|
jPath: true,
|
||
|
|
tagValueProcessor: (key, val) => val,
|
||
|
|
attributeValueProcessor: (attrName, val) => val,
|
||
|
|
}
|
||
|
|
```
|
||
|
|
|
||
|
|
## Options Reference
|
||
|
|
|
||
|
|
Check [Options reference](docs/Builder_v1.md) for more detail and examples.
|
||
|
|
|
||
|
|
- **arrayNodeName**: When building XML from an array, set `arrayNodeName` to wrap each element in a tag name.
|
||
|
|
- **attributeNamePrefix**: Prefix used to identify attribute properties in the JS object. Default: `'@_'`.
|
||
|
|
- **attributesGroupName**: Group name for attributes in the JS object. When set, all attributes are expected to be nested under this key. Not supported with `preserveOrder: true`.
|
||
|
|
- **attributeValueProcessor**: Customize how attribute values are serialized. Receives the attribute name and value.
|
||
|
|
- **cdataPropName**: Property name that identifies CDATA content. Values under this key are wrapped in `<![CDATA[...]]>`.
|
||
|
|
- **commentPropName**: Property name that identifies comment content. Values under this key are rendered as `<!-- ... -->`.
|
||
|
|
- **format**: By default, output is a single-line XML string. Set `format: true` for human-readable, indented output.
|
||
|
|
- **ignoreAttributes**: By default (`true`), attributes are skipped. Set to `false` to include them. Also supports selective ignoring via an array of strings, array of regular expressions, or a callback function.
|
||
|
|
- **indentBy**: String used for each level of indentation. Default: `' '` (two spaces). Only applies when `format: true`.
|
||
|
|
- **maxNestedTags**: Limits the maximum depth of nested tags. An error is thrown if this depth is exceeded. Default: `100`.
|
||
|
|
- **oneListGroup**: Groups all repeated child tags under a single parent tag.
|
||
|
|
- **preserveOrder**: When a JS object was produced by XMLParser with `preserveOrder: true`, pass the same option to XMLBuilder to reconstruct the original XML correctly.
|
||
|
|
- **processEntities**: When `true` (default), special characters in text and attribute values are replaced with XML entities (`&`, `<`, etc.). Set to `false` for a performance boost when you know your content has no entities. Note: quotes in attribute values are always escaped regardless of this setting.
|
||
|
|
- **stopNodes**: Tags listed here are treated as raw content containers — their text content is written as-is without entity encoding. Accepts an array of tag name strings or `Expression` instances from `path-expression-matcher`. The old `*.tagName` wildcard syntax is still accepted and automatically converted to the equivalent `..tagName` deep-wildcard syntax.
|
||
|
|
- **suppressBooleanAttributes**: When `true` (default), attributes with the value `true` are rendered without the value (e.g. `<tag attr>` instead of `<tag attr="true">`).
|
||
|
|
- **suppressEmptyNode**: When `true`, tags with no text value are rendered as self-closing (`<tag/>`).
|
||
|
|
- **suppressUnpairedNode**: When `true` (default), unpaired tags are rendered without a closing slash (`<br>`). When `false`, they are rendered as `<br/>`.
|
||
|
|
- **tagValueProcessor**: Customize how tag text values are serialized. Receives the tag name and value.
|
||
|
|
- **textNodeName**: Property name representing the text content of a tag in the JS object. Default: `'#text'`.
|
||
|
|
- **unpairedTags**: List of tag names that have no matching closing tag (e.g. `<br>` in HTML).
|