@ohos.xml (XML Parsing and Generation)

The XML module provides a series of APIs for converting XML text into JavaScript objects and generating and parsing XML files.

NOTE

The initial APIs of this module are supported since API version 8. Newly added APIs will be marked with a superscript to indicate their earliest API version.

Modules to Import

import { xml } from '@kit.ArkTS';

XmlSerializer

XmlSerializer provides APIs to generate an XML file.

constructor

constructor(buffer: ArrayBuffer|DataView, encoding?: string)

A constructor used to create an XmlSerializer instance.

NOTE

The buffer is used to temporarily store XML text generated. Its size can be customized. Ensure that the buffer is large enough to hold the generated text.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Utils.Lang

Parameters

Error codes

For details about the error codes, see Universal Error Codes.

Example

let arrayBuffer = new ArrayBuffer(2048);
let thatSer = new xml.XmlSerializer(arrayBuffer, "utf-8");

setAttributes

setAttributes(name: string, value: string): void

Sets an attribute.

NOTE

This API does not perform standard XML verification on the data added. Ensure that the data to add complies with the XML specifications. For example, as stipulated in the specifications, you are not allowed to add an attribute name starting with a digit or add multiple attribute names with the same name.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Utils.Lang

Parameters

Error codes

For details about the error codes, see Universal Error Codes.

Example

import { util } from '@kit.ArkTS';

let arrayBuffer = new ArrayBuffer(2048);
let thatSer = new xml.XmlSerializer(arrayBuffer);
thatSer.startElement("note");
thatSer.setAttributes("importance", "high");
thatSer.endElement();
let uint8 = new Uint8Array(arrayBuffer);
let result = util.TextDecoder.create().decodeToString(uint8);
console.log(result); // <note importance="high"/>

addEmptyElement

addEmptyElement(name: string): void

Adds an empty element.

NOTE

This API does not perform standard XML verification on the data added. Ensure that the data to add complies with the XML specifications. For example, as stipulated in the specifications, you are not allowed to add an attribute name starting with a digit.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Utils.Lang

Parameters

Error codes

For details about the error codes, see Universal Error Codes.

Example

import { util } from '@kit.ArkTS';

let arrayBuffer = new ArrayBuffer(2048);
let thatSer = new xml.XmlSerializer(arrayBuffer);
thatSer.addEmptyElement("d");
let uint8 = new Uint8Array(arrayBuffer);
let result = util.TextDecoder.create().decodeToString(uint8);
console.log(result); // <d/>

setDeclaration

setDeclaration(): void

Sets a file declaration with encoding.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Utils.Lang

Example

import { util } from '@kit.ArkTS';

let arrayBuffer = new ArrayBuffer(2048);
let thatSer = new xml.XmlSerializer(arrayBuffer);
thatSer.setDeclaration();
let uint8 = new Uint8Array(arrayBuffer);
let result = util.TextDecoder.create().decodeToString(uint8);
console.log(result);
// <?xml version="1.0" encoding="utf-8"?>

startElement

startElement(name: string): void

Writes the start tag based on the given element name.

NOTE

• After calling this API, you must call endElement to write the end flag to ensure that the node is closed correctly.

• This API does not perform standard XML verification on the data added. Ensure that the data to add complies with the XML specifications. For example, as stipulated in the specifications, you are not allowed to add an attribute name starting with a digit.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Utils.Lang

Parameters

Error codes

For details about the error codes, see Universal Error Codes.

Example

import { util } from '@kit.ArkTS';

let arrayBuffer = new ArrayBuffer(2048);
let thatSer = new xml.XmlSerializer(arrayBuffer);
thatSer.startElement("note");
thatSer.setText("Happy");
thatSer.endElement();
let uint8 = new Uint8Array(arrayBuffer);
let result = util.TextDecoder.create().decodeToString(uint8);
console.log(result);
// <note>Happy</note>

endElement

endElement(): void

Writes the end tag of the element.

NOTE

Before calling this API, you must call startElement to write the start flag.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Utils.Lang

Example

import { util } from '@kit.ArkTS';

let arrayBuffer = new ArrayBuffer(2048);
let thatSer = new xml.XmlSerializer(arrayBuffer);
thatSer.startElement("note");
thatSer.setText("Happy");
thatSer.endElement();
let uint8 = new Uint8Array(arrayBuffer);
let result = util.TextDecoder.create().decodeToString(uint8);
console.log(result);
// <note>Happy</note>

setNamespace

setNamespace(prefix: string, namespace: string): void

Sets the namespace for an element tag.

NOTE

This API does not perform standard XML verification on the data added. Ensure that the data to add complies with the XML specifications. For example, as stipulated in the specifications, you are not allowed to add a namespace starting with a digit or set multiple namespaces for the same element.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Utils.Lang

Parameters

Error codes

For details about the error codes, see Universal Error Codes.

Example

import { util } from '@kit.ArkTS';

let arrayBuffer = new ArrayBuffer(2048);
let thatSer = new xml.XmlSerializer(arrayBuffer);
thatSer.setNamespace("h", "http://www.w3.org/TR/html4/");
thatSer.startElement("note");
thatSer.endElement();
let uint8 = new Uint8Array(arrayBuffer);
let result = util.TextDecoder.create().decodeToString(uint8);
console.log(result);
// <h:note xmlns:h="http://www.w3.org/TR/html4/"/>

setComment

setComment(text: string): void

Sets a comment.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Utils.Lang

Parameters

Error codes

For details about the error codes, see Universal Error Codes.

Example

import { util } from '@kit.ArkTS';

let arrayBuffer = new ArrayBuffer(2048);
let thatSer = new xml.XmlSerializer(arrayBuffer);
thatSer.setComment("Hello, World!");
let uint8 = new Uint8Array(arrayBuffer);
let result = util.TextDecoder.create().decodeToString(uint8);
console.log(result); // <!--Hello, World!-->

setCDATA

setCDATA(text: string): void

Adds data to the CDATA tag. The structure of the generated CDATA tag is “<! <![CDATA[”+ Data added + “]]>”.

NOTE

This API does not perform standard XML verification on the data added. Ensure that the data to add complies with the XML specifications. For example, as stipulated in the specifications, you are not allowed to add data that contains the string ]]> to the CDATA tag.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Utils.Lang

Parameters

Error codes

For details about the error codes, see Universal Error Codes.

Example

import { util } from '@kit.ArkTS';

let arrayBuffer = new ArrayBuffer(2048);
let thatSer = new xml.XmlSerializer(arrayBuffer);
thatSer.setCDATA('root SYSTEM')
let uint8 = new Uint8Array(arrayBuffer);
let result = util.TextDecoder.create().decodeToString(uint8);
console.log(result); // <![CDATA[root SYSTEM]]>

setText

setText(text: string): void

Sets a tag value.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Utils.Lang

Parameters

Error codes

For details about the error codes, see Universal Error Codes.

Example

import { util } from '@kit.ArkTS';

let arrayBuffer = new ArrayBuffer(2048);
let thatSer = new xml.XmlSerializer(arrayBuffer);
thatSer.startElement("note");
thatSer.setAttributes("importance", "high");
thatSer.setText("Happy");
thatSer.endElement();
let uint8 = new Uint8Array(arrayBuffer);
let result = util.TextDecoder.create().decodeToString(uint8);
console.log(result); // <note importance="high">Happy</note>

setDocType

setDocType(text: string): void

Sets a document type.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Utils.Lang

Parameters

Error codes

For details about the error codes, see Universal Error Codes.

Example

import { util } from '@kit.ArkTS';

let arrayBuffer = new ArrayBuffer(2048);
let thatSer = new xml.XmlSerializer(arrayBuffer);
thatSer.setDocType('root SYSTEM "http://www.test.org/test.dtd"');
let uint8 = new Uint8Array(arrayBuffer);
let result = util.TextDecoder.create().decodeToString(uint8);
console.log(result); // <!DOCTYPE root SYSTEM "http://www.test.org/test.dtd">

XmlPullParser

Implements XML file parsing.

constructor

constructor(buffer: ArrayBuffer|DataView, encoding?: string)

Creates and returns an XmlPullParser object.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Utils.Lang

Parameters

Error codes

For details about the error codes, see Universal Error Codes.

Example

import { util } from '@kit.ArkTS';

let strXml = '<title>Happy</title>'
let textEncoder = new util.TextEncoder();
let uint8Array = textEncoder.encodeInto(strXml);
let that = new xml.XmlPullParser(uint8Array.buffer as object as ArrayBuffer, 'UTF-8');

parseXml¹⁴⁺

parseXml(option: ParseOptions): void

Parses XML information.

Atomic service API: This API can be used in atomic services since API version 14.

System capability: SystemCapability.Utils.Lang

Parameters

Error codes

For details about the error codes, see Universal Error Codes.

Example

import { xml, util } from '@kit.ArkTS';

let strxml =
  '<?xml version="1.0" encoding="utf-8"?>' +
    '<note importance="high" logged="true">' +
    '    <title><![CDATA[Test\nTest]]></title>' +
    '</note>';
let textEncoder = new util.TextEncoder();
let uint8 = textEncoder.encodeInto(strxml);

function func(key: xml.EventType, value: xml.ParseInfo) {
  if (key == xml.EventType.CDSECT) {
    console.log(JSON.stringify(value.getText()));
  }
  return true;
}
let options: xml.ParseOptions = {supportDoctype:true, ignoreNameSpace:true, tokenValueCallbackFunction:func}
let pullParser = new xml.XmlPullParser(uint8.buffer as object as ArrayBuffer);
pullParser.parseXml(options);
// "Test\nTest"

parse^(deprecated)

parse(option: ParseOptions): void

Parses XML information.

NOTE

This API is supported since API version 8 and deprecated since API version 14. You are advised to use parseXml¹⁴⁺ instead.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Utils.Lang

Parameters

Error codes

For details about the error codes, see Universal Error Codes.

Example

import { util } from '@kit.ArkTS';

let strXml =
  '<?xml version="1.0" encoding="utf-8"?>' +
  '<note importance="high" logged="true">' +
    '<company>John &amp; Hans</company>' +
    '<title>Happy</title>' +
  '</note>';
let textEncoder = new util.TextEncoder();
let arrbuffer = textEncoder.encodeInto(strXml);
let that = new xml.XmlPullParser(arrbuffer.buffer as object as ArrayBuffer, 'UTF-8');
let str = '';
function func(name: string, value: string) {
  str = name + value;
  console.log(str);
  return true;
}
let options: xml.ParseOptions = {supportDoctype:true, ignoreNameSpace:true, tagValueCallbackFunction:func}
that.parse(options);
// note
// company
// John & Hans
// company
// title
// Happy
// title
// note

ParseOptions

Defines the XML parsing options.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Utils.Lang

ParseInfo

Provides APIs to manage the parsed XML information.

getColumnNumber

getColumnNumber(): number

Obtains the current column number, starting from 1.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Utils.Lang

Return value

Example

import { util } from '@kit.ArkTS';

let strXml = '<?xml version="1.0" encoding="utf-8"?><note>Happy</note>';
let textEncoder = new util.TextEncoder();
let arrbuffer = textEncoder.encodeInto(strXml);
let that = new xml.XmlPullParser(arrbuffer.buffer as object as ArrayBuffer);
let str = "";
function func(key: xml.EventType, value: xml.ParseInfo) {
  str += 'key:' + key + ' value:' + value.getColumnNumber() + ' ';
  return true; // Determines whether to continually parse, which is used to continue or terminate parsing.
}
let options: xml.ParseOptions = {supportDoctype:true, ignoreNameSpace:true, tokenValueCallbackFunction:func}
that.parse(options);
console.log(str);
// key:0 value:1 key:2 value:45 key:4 value:50 key:3 value:57 key:1 value:57

getDepth

getDepth(): number

Obtains the depth of this element.

NOTE

The depth of the whitespace character event in the tag is the same as the depth of the tag.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Utils.Lang

Return value

Example

import { util } from '@kit.ArkTS';

let strXml =
  '<?xml version="1.0" encoding="utf-8"?>' +
  '<note importance="high">' +
    '<title>Happy</title>' +
  '</note>';
let textEncoder = new util.TextEncoder();
let arrbuffer = textEncoder.encodeInto(strXml);
let that = new xml.XmlPullParser(arrbuffer.buffer as object as ArrayBuffer);
let str = "";
function func(key: xml.EventType, value: xml.ParseInfo) {
  str += 'key:' + key + ' value:' + value.getDepth() + ' ';
  return true; // Determines whether to continually parse, which is used to continue or terminate parsing.
}
let options: xml.ParseOptions = {supportDoctype:true, ignoreNameSpace:true, tokenValueCallbackFunction:func}
that.parse(options);
console.log(str);
// key:0 value:0 key:2 value:1 key:2 value:2 key:4 value:2 key:3 value:2 key:3 value:1 key:1 value:0

getLineNumber

getLineNumber(): number

Obtains the current line number, starting from 1.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Utils.Lang

Return value

Example

import { util } from '@kit.ArkTS';

let strXml = '<?xml version="1.0" encoding="utf-8"?><note>Work</note>';
let textEncoder = new util.TextEncoder();
let arrbuffer = textEncoder.encodeInto(strXml);
let that = new xml.XmlPullParser(arrbuffer.buffer as object as ArrayBuffer);
let str = "";
function func(key: xml.EventType, value: xml.ParseInfo) {
  str += 'key:' + key + ' value:' + value.getLineNumber() + ' ';
  return true; // Determines whether to continually parse, which is used to continue or terminate parsing.
}
let options: xml.ParseOptions = {supportDoctype:true, ignoreNameSpace:true, tokenValueCallbackFunction:func}
that.parse(options);
console.log(str);
// key:0 value:1 key:2 value:1 key:4 value:1 key:3 value:1 key:1 value:1

getName

getName(): string

Obtains the name of this element.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Utils.Lang

Return value

Example

import { util } from '@kit.ArkTS';

let strXml = '<?xml version="1.0" encoding="utf-8"?><note>Happy</note>';
let textEncoder = new util.TextEncoder();
let arrbuffer = textEncoder.encodeInto(strXml);
let that = new xml.XmlPullParser(arrbuffer.buffer as object as ArrayBuffer);
let str = "";
function func(key: xml.EventType, value: xml.ParseInfo) {
  str += 'key:' + key + ' value:' + value.getName() + ' ';
  return true; // Determines whether to continually parse, which is used to continue or terminate parsing.
}
let options: xml.ParseOptions = {supportDoctype:true, ignoreNameSpace:true, tokenValueCallbackFunction:func}
that.parse(options);
console.log(str);
// key:0 value: key:2 value:note key:4 value: key:3 value:note key:1 value:

getNamespace

getNamespace(): string

Obtains the namespace of this element.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Utils.Lang

Return value

Example

import { util } from '@kit.ArkTS';

let strXml =
  '<?xml version="1.0" encoding="utf-8"?>' +
  '<note xmlns:h="http://www.w3.org">' +
    '<h:title>Happy</h:title>' +
  '</note>';
let textEncoder = new util.TextEncoder();
let arrbuffer = textEncoder.encodeInto(strXml);
let that = new xml.XmlPullParser(arrbuffer.buffer as object as ArrayBuffer);
let str = "";
function func(key: xml.EventType, value: xml.ParseInfo) {
  str += 'key:' + key + ' value:' + value.getNamespace() + ' ';
  return true; // Determines whether to continually parse, which is used to continue or terminate parsing.
}
let options: xml.ParseOptions = {supportDoctype:true, ignoreNameSpace:false, tokenValueCallbackFunction:func}
that.parse(options);
console.log(str);
// key:0 value: key:2 value: key:2 value:http://www.w3.org key:4 value: key:3 value:http://www.w3.org key:3 value: key:1 value:

getPrefix

getPrefix(): string

Obtains the prefix of this element.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Utils.Lang

Return value

Example

import { util } from '@kit.ArkTS';

let strXml =
  '<?xml version="1.0" encoding="utf-8"?>' +
  '<note xmlns:h="http://www.w3.org/TR/html4">' +
    '<h:title>Happy</h:title>' +
  '</note>';
let textEncoder = new util.TextEncoder();
let arrbuffer = textEncoder.encodeInto(strXml);
let that = new xml.XmlPullParser(arrbuffer.buffer as object as ArrayBuffer);
let str = "";
function func(key: xml.EventType, value: xml.ParseInfo) {
  str += 'key:' + key + ' value:' + value.getPrefix() + ' ';
  return true; // Determines whether to continually parse, which is used to continue or terminate parsing.
}
let options: xml.ParseOptions = {supportDoctype:true, ignoreNameSpace:false, tokenValueCallbackFunction:func}
that.parse(options);
console.log(str);
// key:0 value: key:2 value: key:2 value:h key:4 value: key:3 value:h key:3 value: key:1 value:

getText

getText(): string

Obtains the text of the current event.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Utils.Lang

Return value

Example

import { util } from '@kit.ArkTS';

let strXml = '<?xml version="1.0" encoding="utf-8"?><note>Happy</note>';
let textEncoder = new util.TextEncoder();
let arrbuffer = textEncoder.encodeInto(strXml);
let that = new xml.XmlPullParser(arrbuffer.buffer as object as ArrayBuffer);
let str = "";
function func(key: xml.EventType, value: xml.ParseInfo) {
  str += 'key:' + key + ' value:' + value.getText() + ' ';
  return true; // Determines whether to continually parse, which is used to continue or terminate parsing.
}
let options: xml.ParseOptions = {supportDoctype:true, ignoreNameSpace:true, tokenValueCallbackFunction:func}
that.parse(options);
console.log(str);
// key:0 value: key:2 value: key:4 value:Happy key:3 value: key:1 value:

isEmptyElementTag

isEmptyElementTag(): boolean

Checks whether the current element is empty.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Utils.Lang

Return value

Example

import { util } from '@kit.ArkTS';

let strXml =
  '<?xml version="1.0" encoding="utf-8"?>' +
  '<note importance="high" logged="true">' +
    '<title/>' +
  '</note>';
let textEncoder = new util.TextEncoder();
let arrbuffer = textEncoder.encodeInto(strXml);
let that = new xml.XmlPullParser(arrbuffer.buffer as object as ArrayBuffer);
let str = "";
function func(key: xml.EventType, value: xml.ParseInfo) {
  str += 'key:' + key + ' value:' + value.isEmptyElementTag() + ' ';
  return true; // Determines whether to continually parse, which is used to continue or terminate parsing.
}
let options: xml.ParseOptions = {supportDoctype:true, ignoreNameSpace:true, tokenValueCallbackFunction:func}
that.parse(options);
console.log(str);
// key:0 value:false key:2 value:false key:2 value:true key:3 value:false key:3 value:false key:1 value:false

isWhitespace

isWhitespace(): boolean

Checks whether the current event contains only whitespace characters.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Utils.Lang

Return value

Example

import { util } from '@kit.ArkTS';

let strXml =
  '<?xml version="1.0" encoding="utf-8"?>' +
  '<note importance="high" logged="true">' +
    '<title> </title>' +
  '</note>';
let textEncoder = new util.TextEncoder();
let arrbuffer = textEncoder.encodeInto(strXml);
let that = new xml.XmlPullParser(arrbuffer.buffer as object as ArrayBuffer);
let str = "";
function func(key: xml.EventType, value: xml.ParseInfo) {
  str += 'key:' + key + ' value:' + value.isWhitespace() + ' ';
  return true; // Determines whether to continually parse, which is used to continue or terminate parsing.
}
let options: xml.ParseOptions = {supportDoctype:true, ignoreNameSpace:true, tokenValueCallbackFunction:func}
that.parse(options);
console.log(str);
// key:0 value:true key:2 value:false key:2 value:true key:10 value:true key:3 value:true key:3 value:true key:1 value:true

getAttributeCount

getAttributeCount(): number

Obtains the number of attributes for the current start tag.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Utils.Lang

Return value |Type|Description | |——|———————-| |number|Number of attributes obtained.|

Example

import { util } from '@kit.ArkTS';

let strXml = '<?xml version="1.0" encoding="utf-8"?><note importance="high" logged="true"/>';
let textEncoder = new util.TextEncoder();
let arrbuffer = textEncoder.encodeInto(strXml);
let that = new xml.XmlPullParser(arrbuffer.buffer as object as ArrayBuffer);
let str = "";
function func(key: xml.EventType, value: xml.ParseInfo) {
  str += 'key:' + key + ' value:' + value.getAttributeCount() + ' ';
  return true; // Determines whether to continually parse, which is used to continue or terminate parsing.
}
let options: xml.ParseOptions = {supportDoctype:true, ignoreNameSpace:true, tokenValueCallbackFunction:func}
that.parse(options);
console.log(str);
// key:0 value:0 key:2 value:2 key:3 value:2 key:1 value:0

EventType

Enumerates the event types.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Utils.Lang

你可能感兴趣的鸿蒙文章

harmony 鸿蒙ArkTS

harmony 鸿蒙Compilation Toolchain Error Codes

harmony 鸿蒙TypeScript Compiler Error Codes

harmony 鸿蒙Utils Error Codes

harmony 鸿蒙js-apis-arkts-collections

harmony 鸿蒙@arkts.math.Decimal (High-Precision Math Library Decimal)

harmony 鸿蒙@arkts.lang (ArkTS Base Capability)

harmony 鸿蒙@arkts.utils (ArkTS Utils)

harmony 鸿蒙@ohos.util.ArrayList (Linear Container ArrayList)

harmony 鸿蒙@ohos.buffer (Buffer)