Document

When using XML as a data carrier, it is necessary to parse relevant elements in practice. This typically includes three types of operations: parsing XML tags and their values, parsing XML attributes and their values, and parsing XML event types and element information. For example, in web services, XML is the foundation of the Simple Object Access Protocol (SOAP). SOAP messages, which are usually encapsulated in XML format and contain request and response parameters, are parsed by web services to process client requests and generate corresponding responses.

The XML module provides the XmlPullParser class to parse XML text. The input is an ArrayBuffer or DataView that contains XML data, and the output is a structured parsing result.

Table 1 XML parsing options (see ParseOptions for detailed descriptions)

Expand

Name	Type	Mandatory	Description
supportDoctype	boolean	No	Whether to parse the document type. The value true means to parse the document type, and false means the opposite. The default value is false.
ignoreNameSpace	boolean	No	Whether to ignore the namespace. If the namespace is ignored, it will not be parsed. The value true means to ignore the namespace, and false means the opposite. The default value is false.
tagValueCallbackFunction	(name: string, value: string) => boolean	No	Callback used to return tagValue, which consists of XML tags and tag values. The default value is undefined, indicating that XML tags and their values are not parsed.
attributeValueCallbackFunction	(name: string, value: string) => boolean	No	Callback used to return attributeValue, which consists of an attribute and its value. The default value is undefined, indicating that XML attributes and their values are not parsed.
tokenValueCallbackFunction	(eventType: EventType, value: ParseInfo) => boolean	No	Callback used to return tokenValue, which consists of the XML event type and the attributes of parseInfo. The default value is undefined, indicating that the XML event type is not parsed.

Precautions

The input XML data must be in the standard format.
Parsing a specified node is not supported.

Parsing XML Tags and Values

Import the module.

Collapse
Word wrap
Dark theme
Copy code
import { xml, util } from '@kit.ArkTS'; // Use the API provided by the util module to encode text.
ParsingTagsAndValues.ets

Create an XmlPullParser object.

You can create an XmlPullParser object based on ArrayBuffer or DataView. Both methods yield the same results.

Collapse
Word wrap
Dark theme
Copy code
let strXml: string =
  '<?xml version="1.0" encoding="utf-8"?>' +
    '<note importance="high" logged="true">' +
    '<title>Play</title>' +
    '<lens>Work</lens>' +
    '</note>';
let textEncoder: util.TextEncoder = new util.TextEncoder();
let arrBuffer: Uint8Array = textEncoder.encodeInto(strXml); // Encode data to prevent garbled Chinese characters.
// Method 1: Create an XmlPullParser object based on ArrayBuffer.
let xmlParser: xml.XmlPullParser = new xml.XmlPullParser(arrBuffer.buffer as object as ArrayBuffer, 'UTF-8');
ParsingTagsAndValues.ets

Collapse
Word wrap
Dark theme
Copy code
// Method 2: Create an XmlPullParser object based on DataView.
let dataView: DataView = new DataView(arrBuffer.buffer as object as ArrayBuffer);
let xmlParser: xml.XmlPullParser = new xml.XmlPullParser(dataView, 'UTF-8');
ParsingTagsAndValues.ets

Customize a callback function. In this example, the callback function directly prints the tags and their values.

Collapse
Word wrap
Dark theme
Copy code
function func(name: string, value: string): boolean {
  if (name == 'note') {
    console.info(name);
  }
  if (value == 'Play' || value == 'Work') {
    console.info('    ' + value);
    // ...
  }
  if (name == 'title' || name == 'lens') {
    console.info('  ' + name);
  }
  return true; // The value true means to continue parsing, and false means to stop parsing.
}
ParsingTagsAndValues.ets

Set parsing options and call the parseXml function.

Collapse
Word wrap
Dark theme
Copy code
let options: xml.ParseOptions = {supportDoctype:true, ignoreNameSpace:true, tagValueCallbackFunction:func};
xmlParser.parseXml(options);
ParsingTagsAndValues.ets

The output is as follows:

Collapse
Word wrap
Dark theme
Copy code
note
  title
    Play
  title
  lens
    Work
  lens
note

Parsing XML Attributes and Values

Import the module.
Collapse
Word wrap
Dark theme
Copy code
```
import { xml, util } from '@kit.ArkTS'; // Use the util module to encode text.
```
ParsingAttributesAndValues.ets

Create an XmlPullParser object.

Collapse
Word wrap
Dark theme
Copy code
let strXml: string =
  '<?xml version="1.0" encoding="utf-8"?>' +
    '<note importance="high" logged="true">' +
    '    <title>Play</title>' +
    '    <title>Happy</title>' +
    '    <lens>Work</lens>' +
    '</note>';
let textEncoder: util.TextEncoder = new util.TextEncoder();
let arrBuffer: Uint8Array = textEncoder.encodeInto(strXml); // Encode data to prevent garbled Chinese characters.
let xmlParser: xml.XmlPullParser = new xml.XmlPullParser(arrBuffer.buffer as object as ArrayBuffer, 'UTF-8');
ParsingAttributesAndValues.ets

Customize a callback function. In this example, the callback function directly prints the attributes and their values.

Collapse
Word wrap
Dark theme
Copy code
let str: string = '';
function func(name: string, value: string): boolean {
  str += name + ' ' + value + ' ';
  return true; // The value true means to continue parsing, and false means to stop parsing.
}
ParsingAttributesAndValues.ets

Set parsing options and call the parseXml function.

Collapse
Word wrap
Dark theme
Copy code
let options: xml.ParseOptions = {supportDoctype:true, ignoreNameSpace:true, attributeValueCallbackFunction:func};
xmlParser.parseXml(options);
console.info(str); // Print all attributes and their values.
ParsingAttributesAndValues.ets

The output is as follows:

Collapse
Word wrap
Dark theme
Copy code
importance high logged true // Attributes and values of the note node

Parsing XML Event Types and Element Information

Import the module.
Collapse
Word wrap
Dark theme
Copy code
```
import { xml, util } from '@kit.ArkTS'; // Use the util module to encode text.
```
ParsingEventTypesAndElementInformation.ets

Create an XmlPullParser object.

Collapse
Word wrap
Dark theme
Copy code
let strXml: string =
  '<?xml version="1.0" encoding="utf-8"?>' +
    '<note importance="high" logged="true">' +
    '<title>Play</title>' +
    '</note>';
let textEncoder: util.TextEncoder = new util.TextEncoder();
let arrBuffer: Uint8Array = textEncoder.encodeInto(strXml); // Encode data to prevent garbled Chinese characters.
let xmlParser: xml.XmlPullParser = new xml.XmlPullParser(arrBuffer.buffer as object as ArrayBuffer, 'UTF-8');
ParsingEventTypesAndElementInformation.ets

Customize a callback function. In this example, the callback function directly prints the event types and element depths.

Collapse
Word wrap
Dark theme
Copy code
let str: string = '';
function func(name: xml.EventType, value: xml.ParseInfo): boolean {
  str = name + ' ' + value.getDepth(); // Obtain the current depth of an element in the XML document.
  console.info(str);
  // ...
  return true; // The value true means to continue parsing, and false means to stop parsing.
}
ParsingEventTypesAndElementInformation.ets

Set parsing options and call the parseXml function.

Collapse
Word wrap
Dark theme
Copy code
let options: xml.ParseOptions = {supportDoctype:true, ignoreNameSpace:true, tokenValueCallbackFunction:func};
xmlParser.parseXml(options);
ParsingEventTypesAndElementInformation.ets

The output is as follows:

Collapse
Word wrap
Dark theme
Copy code
0 0 // First digit 0: <?xml version="1.0" encoding="utf-8"?> corresponds to event type START_DOCUMENT, which value is 0; second digit 0: The depth is 0.
2 1 // First digit 2: <note importance="high" logged="true"> corresponds to event type START_TAG, which value is 2; second digit 1: The depth is 1.
2 2 // First digit 2: <title> corresponds to event type START_TAG, which value is 2; second digit 2: The depth is 2.
4 2 // First digit 4: "Play" corresponds to event type TEXT, which value is 4; second digit 2: The depth is 2.
3 2 // First digit 3: </title> corresponds to event type END_TAG, which value is 3; second digit 2: The depth is 2.
3 1 // First digit 3: </note> corresponds to event type END_TAG, which value is 3; second digit 1: The depth is 1.
1 0 // First digit 1: corresponds to event type END_DOCUMENT, which value is 1; second digit 0: The depth is 0.

Example Scenario

This example demonstrates how to use all parsing options to parse XML tags, attributes, and event types.

Collapse
Word wrap
Dark theme
Copy code
import { xml, util } from '@kit.ArkTS';
// ...
let strXml: string =
  '<?xml version="1.0" encoding="UTF-8"?>' +
    '<book category="COOKING">' +
    '<title lang="en">Everyday</title>' +
    '<author>Giana</author>' +
    '</book>';
let textEncoder: util.TextEncoder = new util.TextEncoder();
let arrBuffer: Uint8Array = textEncoder.encodeInto(strXml);
let xmlParser: xml.XmlPullParser = new xml.XmlPullParser(arrBuffer.buffer as object as ArrayBuffer, 'UTF-8');
let str: string = '';

function tagFunc(name: string, value: string): boolean {
  str = name + value;
  console.info('tag-' + str);
  return true;
}

function attFunc(name: string, value: string): boolean {
  str = name + ' ' + value;
  console.info('attri-' + str);
  return true;
}

function tokenFunc(name: xml.EventType, value: xml.ParseInfo): boolean {
  str = name + ' ' + value.getDepth();
  console.info('token-' + str);
  // ...
  return true;
}
// ...
  let options: xml.ParseOptions = {
    supportDoctype: true,
    ignoreNameSpace: true,
    tagValueCallbackFunction: tagFunc,
    attributeValueCallbackFunction: attFunc,
    tokenValueCallbackFunction: tokenFunc
  };
  xmlParser.parseXml(options);
ExampleScenario.ets

The output is as follows:

Collapse
Word wrap
Dark theme
Copy code
tag-
token-0 0
tag-book
token-2 1
attri-category COOKING
tag-title
token-2 2
attri-lang en
tag-Everyday
token-4 2
tag-title
token-3 2
tag-author
token-2 2
tag-Giana
token-4 2
tag-author
token-3 2
tag-book
token-3 1
tag-
token-1 0

XML Parsing

Precautions

Parsing XML Tags and Values

Parsing XML Attributes and Values

Parsing XML Event Types and Element Information

Example Scenario