1# @ohos.xml (XML Parsing and Generation)
2
3The **XML** module provides a series of APIs for converting XML text into JavaScript objects and generating and parsing XML files.
4
5> **NOTE**
6>
7> 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.
8
9
10## Modules to Import
11
12```
13import { xml } from '@kit.ArkTS';
14```
15
16## XmlSerializer
17
18**XmlSerializer** provides APIs to generate an XML file.
19
20### constructor
21
22constructor(buffer: ArrayBuffer | DataView, encoding?: string)
23
24A constructor used to create an **XmlSerializer** instance.
25
26> **NOTE**
27>
28> 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.
29
30**Atomic service API**: This API can be used in atomic services since API version 11.
31
32**System capability**: SystemCapability.Utils.Lang
33
34**Parameters**
35
36| Name  | Type                             | Mandatory| Description                                            |
37| -------- | --------------------------------- | ---- | ------------------------------------------------ |
38| buffer   | ArrayBuffer \| DataView | Yes  | **ArrayBuffer** or **DataView** for storing the XML information to set.|
39| encoding | string                            | No  | Encoding format. The default value is **'utf-8'** (the only format currently supported).              |
40
41**Error codes**
42
43For details about the error codes, see [Universal Error Codes](../errorcode-universal.md).
44
45| ID| Error Message|
46| -------- | -------- |
47| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. |
48
49**Example**
50
51```ts
52let arrayBuffer = new ArrayBuffer(2048);
53let thatSer = new xml.XmlSerializer(arrayBuffer, "utf-8");
54```
55
56### setAttributes
57
58setAttributes(name: string, value: string): void
59
60Sets an attribute.
61
62> **NOTE**
63>
64> 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.
65
66**Atomic service API**: This API can be used in atomic services since API version 11.
67
68**System capability**: SystemCapability.Utils.Lang
69
70**Parameters**
71
72| Name| Type  | Mandatory| Description           |
73| ------ | ------ | ---- | --------------- |
74| name   | string | Yes  | Key of the attribute.  |
75| value  | string | Yes  | Value of the attribute.|
76
77**Error codes**
78
79For details about the error codes, see [Universal Error Codes](../errorcode-universal.md).
80
81| ID| Error Message|
82| -------- | -------- |
83| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. |
84
85**Example**
86
87```ts
88import { util } from '@kit.ArkTS';
89
90let arrayBuffer = new ArrayBuffer(2048);
91let thatSer = new xml.XmlSerializer(arrayBuffer);
92thatSer.startElement("note");
93thatSer.setAttributes("importance", "high");
94thatSer.endElement();
95let uint8 = new Uint8Array(arrayBuffer);
96let result = util.TextDecoder.create().decodeToString(uint8);
97console.log(result); // <note importance="high"/>
98```
99
100### addEmptyElement
101
102addEmptyElement(name: string): void
103
104Adds an empty element.
105
106> **NOTE**
107>
108> 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.
109
110**Atomic service API**: This API can be used in atomic services since API version 11.
111
112**System capability**: SystemCapability.Utils.Lang
113
114**Parameters**
115
116| Name| Type  | Mandatory| Description              |
117| ------ | ------ | ---- | ------------------ |
118| name   | string | Yes  | Name of the empty element to add.|
119
120**Error codes**
121
122For details about the error codes, see [Universal Error Codes](../errorcode-universal.md).
123
124| ID| Error Message|
125| -------- | -------- |
126| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. |
127
128**Example**
129
130```ts
131import { util } from '@kit.ArkTS';
132
133let arrayBuffer = new ArrayBuffer(2048);
134let thatSer = new xml.XmlSerializer(arrayBuffer);
135thatSer.addEmptyElement("d");
136let uint8 = new Uint8Array(arrayBuffer);
137let result = util.TextDecoder.create().decodeToString(uint8);
138console.log(result); // <d/>
139```
140
141### setDeclaration
142
143setDeclaration(): void
144
145Sets a file declaration with encoding.
146
147**Atomic service API**: This API can be used in atomic services since API version 11.
148
149**System capability**: SystemCapability.Utils.Lang
150
151**Example**
152
153```ts
154import { util } from '@kit.ArkTS';
155
156let arrayBuffer = new ArrayBuffer(2048);
157let thatSer = new xml.XmlSerializer(arrayBuffer);
158thatSer.setDeclaration();
159let uint8 = new Uint8Array(arrayBuffer);
160let result = util.TextDecoder.create().decodeToString(uint8);
161console.log(result);
162// <?xml version="1.0" encoding="utf-8"?>
163```
164
165### startElement
166
167startElement(name: string): void
168
169Writes the start tag based on the given element name.
170
171> **NOTE**
172>
173>- After calling this API, you must call [endElement](#endelement) to write the end flag to ensure that the node is closed correctly.
174>
175>- 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.
176
177**Atomic service API**: This API can be used in atomic services since API version 11.
178
179**System capability**: SystemCapability.Utils.Lang
180
181**Parameters**
182
183| Name| Type  | Mandatory| Description              |
184| ------ | ------ | ---- | ------------------ |
185| name   | string | Yes  | Name of the element.|
186
187**Error codes**
188
189For details about the error codes, see [Universal Error Codes](../errorcode-universal.md).
190
191| ID| Error Message|
192| -------- | -------- |
193| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. |
194
195**Example**
196
197```ts
198import { util } from '@kit.ArkTS';
199
200let arrayBuffer = new ArrayBuffer(2048);
201let thatSer = new xml.XmlSerializer(arrayBuffer);
202thatSer.startElement("note");
203thatSer.setText("Happy");
204thatSer.endElement();
205let uint8 = new Uint8Array(arrayBuffer);
206let result = util.TextDecoder.create().decodeToString(uint8);
207console.log(result);
208// <note>Happy</note>
209```
210
211### endElement
212
213endElement(): void
214
215Writes the end tag of the element.
216
217> **NOTE**
218>
219> Before calling this API, you must call [startElement](#startelement) to write the start flag.
220
221**Atomic service API**: This API can be used in atomic services since API version 11.
222
223**System capability**: SystemCapability.Utils.Lang
224
225**Example**
226
227```ts
228import { util } from '@kit.ArkTS';
229
230let arrayBuffer = new ArrayBuffer(2048);
231let thatSer = new xml.XmlSerializer(arrayBuffer);
232thatSer.startElement("note");
233thatSer.setText("Happy");
234thatSer.endElement();
235let uint8 = new Uint8Array(arrayBuffer);
236let result = util.TextDecoder.create().decodeToString(uint8);
237console.log(result);
238// <note>Happy</note>
239```
240
241### setNamespace
242
243setNamespace(prefix: string, namespace: string): void
244
245Sets the namespace for an element tag.
246
247> **NOTE**
248>
249> 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.
250
251**Atomic service API**: This API can be used in atomic services since API version 11.
252
253**System capability**: SystemCapability.Utils.Lang
254
255**Parameters**
256
257| Name   | Type  | Mandatory| Description                          |
258| --------- | ------ | ---- | ------------------------------ |
259| prefix    | string | Yes  | Prefix of the element and its child elements.    |
260| namespace | string | Yes  | Namespace to set.|
261
262**Error codes**
263
264For details about the error codes, see [Universal Error Codes](../errorcode-universal.md).
265
266| ID| Error Message|
267| -------- | -------- |
268| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. |
269
270**Example**
271
272```ts
273import { util } from '@kit.ArkTS';
274
275let arrayBuffer = new ArrayBuffer(2048);
276let thatSer = new xml.XmlSerializer(arrayBuffer);
277thatSer.setNamespace("h", "http://www.w3.org/TR/html4/");
278thatSer.startElement("note");
279thatSer.endElement();
280let uint8 = new Uint8Array(arrayBuffer);
281let result = util.TextDecoder.create().decodeToString(uint8);
282console.log(result);
283// <h:note xmlns:h="http://www.w3.org/TR/html4/"/>
284```
285
286### setComment
287
288setComment(text: string): void
289
290Sets a comment.
291
292**Atomic service API**: This API can be used in atomic services since API version 11.
293
294**System capability**: SystemCapability.Utils.Lang
295
296**Parameters**
297
298| Name| Type  | Mandatory| Description                |
299| ------ | ------ | ---- | -------------------- |
300| text   | string | Yes  | Comment to set.|
301
302**Error codes**
303
304For details about the error codes, see [Universal Error Codes](../errorcode-universal.md).
305
306| ID| Error Message|
307| -------- | -------- |
308| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. |
309
310**Example**
311
312```ts
313import { util } from '@kit.ArkTS';
314
315let arrayBuffer = new ArrayBuffer(2048);
316let thatSer = new xml.XmlSerializer(arrayBuffer);
317thatSer.setComment("Hello, World!");
318let uint8 = new Uint8Array(arrayBuffer);
319let result = util.TextDecoder.create().decodeToString(uint8);
320console.log(result); // <!--Hello, World!-->
321```
322
323### setCDATA
324
325setCDATA(text: string): void
326
327Adds data to the CDATA tag. The structure of the generated CDATA tag is "\<! <![CDATA\["+ Data added + "\]\]\>".
328
329> **NOTE**
330>
331> 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.
332
333**Atomic service API**: This API can be used in atomic services since API version 11.
334
335**System capability**: SystemCapability.Utils.Lang
336
337**Parameters**
338
339| Name| Type  | Mandatory| Description             |
340| ------ | ------ | ---- | ----------------- |
341| text   | string | Yes  | CDATA data to set.|
342
343**Error codes**
344
345For details about the error codes, see [Universal Error Codes](../errorcode-universal.md).
346
347| ID| Error Message|
348| -------- | -------- |
349| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. |
350
351**Example**
352
353```ts
354import { util } from '@kit.ArkTS';
355
356let arrayBuffer = new ArrayBuffer(2048);
357let thatSer = new xml.XmlSerializer(arrayBuffer);
358thatSer.setCDATA('root SYSTEM')
359let uint8 = new Uint8Array(arrayBuffer);
360let result = util.TextDecoder.create().decodeToString(uint8);
361console.log(result); // <![CDATA[root SYSTEM]]>
362```
363
364### setText
365
366setText(text: string): void
367
368Sets a tag value.
369
370**Atomic service API**: This API can be used in atomic services since API version 11.
371
372**System capability**: SystemCapability.Utils.Lang
373
374**Parameters**
375
376| Name| Type  | Mandatory| Description            |
377| ------ | ------ | ---- | ---------------- |
378| text   | string | Yes  | Tag value to set, which is the content of the **text** attribute.|
379
380**Error codes**
381
382For details about the error codes, see [Universal Error Codes](../errorcode-universal.md).
383
384| ID| Error Message|
385| -------- | -------- |
386| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. |
387
388**Example**
389
390```ts
391import { util } from '@kit.ArkTS';
392
393let arrayBuffer = new ArrayBuffer(2048);
394let thatSer = new xml.XmlSerializer(arrayBuffer);
395thatSer.startElement("note");
396thatSer.setAttributes("importance", "high");
397thatSer.setText("Happy");
398thatSer.endElement();
399let uint8 = new Uint8Array(arrayBuffer);
400let result = util.TextDecoder.create().decodeToString(uint8);
401console.log(result); // <note importance="high">Happy</note>
402```
403
404### setDocType
405
406setDocType(text: string): void
407
408Sets a document type.
409
410**Atomic service API**: This API can be used in atomic services since API version 11.
411
412**System capability**: SystemCapability.Utils.Lang
413
414**Parameters**
415
416| Name| Type  | Mandatory| Description               |
417| ------ | ------ | ---- | ------------------- |
418| text   | string | Yes  | Content of **DocType** to set.|
419
420**Error codes**
421
422For details about the error codes, see [Universal Error Codes](../errorcode-universal.md).
423
424| ID| Error Message|
425| -------- | -------- |
426| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. |
427
428**Example**
429
430```ts
431import { util } from '@kit.ArkTS';
432
433let arrayBuffer = new ArrayBuffer(2048);
434let thatSer = new xml.XmlSerializer(arrayBuffer);
435thatSer.setDocType('root SYSTEM "http://www.test.org/test.dtd"');
436let uint8 = new Uint8Array(arrayBuffer);
437let result = util.TextDecoder.create().decodeToString(uint8);
438console.log(result); // <!DOCTYPE root SYSTEM "http://www.test.org/test.dtd">
439```
440
441## XmlPullParser
442
443Implements XML file parsing.
444
445### constructor
446
447constructor(buffer: ArrayBuffer | DataView, encoding?: string)
448
449Creates and returns an **XmlPullParser** object.
450
451**Atomic service API**: This API can be used in atomic services since API version 11.
452
453**System capability**: SystemCapability.Utils.Lang
454
455**Parameters**
456
457| Name  | Type                             | Mandatory| Description                                      |
458| -------- | --------------------------------- | ---- | ------------------------------------------ |
459| buffer   | ArrayBuffer \| DataView | Yes  | XML text information to be parsed.|
460| encoding | string                            | No  | Encoding format. The default value is **'utf-8'** (the only format currently supported).        |
461
462**Error codes**
463
464For details about the error codes, see [Universal Error Codes](../errorcode-universal.md).
465
466| ID| Error Message|
467| -------- | -------- |
468| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. |
469
470**Example**
471
472```ts
473import { util } from '@kit.ArkTS';
474
475let strXml = '<title>Happy</title>'
476let textEncoder = new util.TextEncoder();
477let uint8Array = textEncoder.encodeInto(strXml);
478let that = new xml.XmlPullParser(uint8Array.buffer as object as ArrayBuffer, 'UTF-8');
479```
480
481### parseXml<sup>14+</sup>
482
483parseXml(option: ParseOptions): void
484
485Parses XML information.
486
487**Atomic service API**: This API can be used in atomic services since API version 14.
488
489**System capability**: SystemCapability.Utils.Lang
490
491**Parameters**
492
493| Name| Type                         | Mandatory| Description         |
494| ------ | ----------------------------- | ---- | ------------- |
495| option | [ParseOptions](#parseoptions) | Yes  | XML parsing options.|
496
497**Error codes**
498
499For details about the error codes, see [Universal Error Codes](../errorcode-universal.md).
500
501| ID| Error Message|
502| -------- | -------- |
503| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. |
504
505**Example**
506
507```ts
508import { xml, util } from '@kit.ArkTS';
509
510let strxml =
511  '<?xml version="1.0" encoding="utf-8"?>' +
512    '<note importance="high" logged="true">' +
513    '    <title><![CDATA[Test\nTest]]></title>' +
514    '</note>';
515let textEncoder = new util.TextEncoder();
516let uint8 = textEncoder.encodeInto(strxml);
517
518function func(key: xml.EventType, value: xml.ParseInfo) {
519  if (key == xml.EventType.CDSECT) {
520    console.log(JSON.stringify(value.getText()));
521  }
522  return true;
523}
524let options: xml.ParseOptions = {supportDoctype:true, ignoreNameSpace:true, tokenValueCallbackFunction:func}
525let pullParser = new xml.XmlPullParser(uint8.buffer as object as ArrayBuffer);
526pullParser.parseXml(options);
527// "Test\nTest"
528```
529
530### parse<sup>(deprecated)</sup>
531
532parse(option: ParseOptions): void
533
534Parses XML information.
535
536> **NOTE**
537>
538> This API is supported since API version 8 and deprecated since API version 14. You are advised to use [parseXml<sup>14+</sup>](#parsexml14) instead.
539
540**Atomic service API**: This API can be used in atomic services since API version 11.
541
542**System capability**: SystemCapability.Utils.Lang
543
544**Parameters**
545
546| Name| Type                         | Mandatory| Description                            |
547| ------ | ----------------------------- | ---- | -------------------------------- |
548| option | [ParseOptions](#parseoptions) | Yes  | Options for controlling and obtaining the parsed information.|
549
550**Error codes**
551
552For details about the error codes, see [Universal Error Codes](../errorcode-universal.md).
553
554| ID| Error Message|
555| -------- | -------- |
556| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. |
557
558**Example**
559
560```ts
561import { util } from '@kit.ArkTS';
562
563let strXml =
564  '<?xml version="1.0" encoding="utf-8"?>' +
565  '<note importance="high" logged="true">' +
566    '<company>John &amp; Hans</company>' +
567    '<title>Happy</title>' +
568  '</note>';
569let textEncoder = new util.TextEncoder();
570let arrbuffer = textEncoder.encodeInto(strXml);
571let that = new xml.XmlPullParser(arrbuffer.buffer as object as ArrayBuffer, 'UTF-8');
572let str = '';
573function func(name: string, value: string) {
574  str = name + value;
575  console.log(str);
576  return true;
577}
578let options: xml.ParseOptions = {supportDoctype:true, ignoreNameSpace:true, tagValueCallbackFunction:func}
579that.parse(options);
580// note
581// company
582// John & Hans
583// company
584// title
585// Happy
586// title
587// note
588```
589
590## ParseOptions
591
592Defines the XML parsing options.
593
594**Atomic service API**: This API can be used in atomic services since API version 11.
595
596**System capability**: SystemCapability.Utils.Lang
597
598
599| Name                          | Type                                                        | Mandatory| Description                                   |
600| ------------------------------ | ------------------------------------------------------------ | ---- | --------------------------------------- |
601| supportDoctype                 | boolean                                                      | No  | Whether to ignore the document type. The default value is **false**, indicating that the document type is not parsed.|
602| ignoreNameSpace                | boolean                                                      | No  | Whether to ignore the namespace. The default value is **false**, indicating that the namespace is not ignored.|
603| tagValueCallbackFunction       | (name: string, value: string) =&gt; boolean | No  | Start tag, tag value, and end tag of parsing. The default value is **undefined**, indicating no parsing.|
604| attributeValueCallbackFunction | (name: string, value: string) =&gt; boolean | No  | Parsing attribute and attribute value. The default value is **undefined**, indicating no parsing.|
605| tokenValueCallbackFunction     | (eventType: [EventType](#eventtype), value: [ParseInfo](#parseinfo)) =&gt; boolean | No  | Parsing element's [EventType](#eventtype) and [ParseInfo](#parseinfo). The default value is **undefined**, indicating no parsing.|
606
607## ParseInfo
608
609Provides APIs to manage the parsed XML information.
610
611
612### getColumnNumber
613
614getColumnNumber(): number
615
616Obtains the column line number, starting from 1.
617
618**Atomic service API**: This API can be used in atomic services since API version 11.
619
620**System capability**: SystemCapability.Utils.Lang
621
622**Return value**
623
624| Type  | Description          |
625| ------ | -------------- |
626| number | Column number obtained.|
627
628**Example**
629
630```ts
631import { util } from '@kit.ArkTS';
632
633let strXml = '<?xml version="1.0" encoding="utf-8"?><note>Happy</note>';
634let textEncoder = new util.TextEncoder();
635let arrbuffer = textEncoder.encodeInto(strXml);
636let that = new xml.XmlPullParser(arrbuffer.buffer as object as ArrayBuffer);
637let str = "";
638function func(key: xml.EventType, value: xml.ParseInfo) {
639  str += 'key:' + key + ' value:' + value.getColumnNumber() + ' ';
640  return true; // Determines whether to continually parse, which is used to continue or terminate parsing.
641}
642let options: xml.ParseOptions = {supportDoctype:true, ignoreNameSpace:true, tokenValueCallbackFunction:func}
643that.parse(options);
644console.log(str);
645// key:0 value:1 key:2 value:45 key:4 value:50 key:3 value:57 key:1 value:57
646```
647
648### getDepth
649
650getDepth(): number
651
652Obtains the depth of this element.
653
654> **NOTE**
655>
656> The depth of the whitespace character event in the tag is the same as the depth of the tag.
657
658**Atomic service API**: This API can be used in atomic services since API version 11.
659
660**System capability**: SystemCapability.Utils.Lang
661
662**Return value**
663
664| Type  | Description                |
665| ------ | -------------------- |
666| number | Depth obtained.|
667
668**Example**
669
670```ts
671import { util } from '@kit.ArkTS';
672
673let strXml =
674  '<?xml version="1.0" encoding="utf-8"?>' +
675  '<note importance="high">' +
676    '<title>Happy</title>' +
677  '</note>';
678let textEncoder = new util.TextEncoder();
679let arrbuffer = textEncoder.encodeInto(strXml);
680let that = new xml.XmlPullParser(arrbuffer.buffer as object as ArrayBuffer);
681let str = "";
682function func(key: xml.EventType, value: xml.ParseInfo) {
683  str += 'key:' + key + ' value:' + value.getDepth() + ' ';
684  return true; // Determines whether to continually parse, which is used to continue or terminate parsing.
685}
686let options: xml.ParseOptions = {supportDoctype:true, ignoreNameSpace:true, tokenValueCallbackFunction:func}
687that.parse(options);
688console.log(str);
689// 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
690```
691
692### getLineNumber
693
694getLineNumber(): number
695
696Obtains the current line number, starting from 1.
697
698**Atomic service API**: This API can be used in atomic services since API version 11.
699
700**System capability**: SystemCapability.Utils.Lang
701
702**Return value**
703
704| Type  | Description          |
705| ------ | -------------- |
706| number | Line number obtained.|
707
708**Example**
709
710```ts
711import { util } from '@kit.ArkTS';
712
713let strXml = '<?xml version="1.0" encoding="utf-8"?><note>Work</note>';
714let textEncoder = new util.TextEncoder();
715let arrbuffer = textEncoder.encodeInto(strXml);
716let that = new xml.XmlPullParser(arrbuffer.buffer as object as ArrayBuffer);
717let str = "";
718function func(key: xml.EventType, value: xml.ParseInfo) {
719  str += 'key:' + key + ' value:' + value.getLineNumber() + ' ';
720  return true; // Determines whether to continually parse, which is used to continue or terminate parsing.
721}
722let options: xml.ParseOptions = {supportDoctype:true, ignoreNameSpace:true, tokenValueCallbackFunction:func}
723that.parse(options);
724console.log(str);
725// key:0 value:1 key:2 value:1 key:4 value:1 key:3 value:1 key:1 value:1
726```
727
728### getName
729
730getName(): string
731
732Obtains the name of this element.
733
734**Atomic service API**: This API can be used in atomic services since API version 11.
735
736**System capability**: SystemCapability.Utils.Lang
737
738**Return value**
739
740| Type  | Description              |
741| ------ | ------------------ |
742| string | Element name obtained.|
743
744**Example**
745
746```ts
747import { util } from '@kit.ArkTS';
748
749let strXml = '<?xml version="1.0" encoding="utf-8"?><note>Happy</note>';
750let textEncoder = new util.TextEncoder();
751let arrbuffer = textEncoder.encodeInto(strXml);
752let that = new xml.XmlPullParser(arrbuffer.buffer as object as ArrayBuffer);
753let str = "";
754function func(key: xml.EventType, value: xml.ParseInfo) {
755  str += 'key:' + key + ' value:' + value.getName() + ' ';
756  return true; // Determines whether to continually parse, which is used to continue or terminate parsing.
757}
758let options: xml.ParseOptions = {supportDoctype:true, ignoreNameSpace:true, tokenValueCallbackFunction:func}
759that.parse(options);
760console.log(str);
761// key:0 value: key:2 value:note key:4 value: key:3 value:note key:1 value:
762```
763### getNamespace
764
765getNamespace(): string
766
767Obtains the namespace of this element.
768
769**Atomic service API**: This API can be used in atomic services since API version 11.
770
771**System capability**: SystemCapability.Utils.Lang
772
773**Return value**
774
775| Type  | Description                    |
776| ------ | ------------------------ |
777| string | Namespace obtained.|
778
779**Example**
780
781```ts
782import { util } from '@kit.ArkTS';
783
784let strXml =
785  '<?xml version="1.0" encoding="utf-8"?>' +
786  '<note xmlns:h="http://www.w3.org">' +
787    '<h:title>Happy</h:title>' +
788  '</note>';
789let textEncoder = new util.TextEncoder();
790let arrbuffer = textEncoder.encodeInto(strXml);
791let that = new xml.XmlPullParser(arrbuffer.buffer as object as ArrayBuffer);
792let str = "";
793function func(key: xml.EventType, value: xml.ParseInfo) {
794  str += 'key:' + key + ' value:' + value.getNamespace() + ' ';
795  return true; // Determines whether to continually parse, which is used to continue or terminate parsing.
796}
797let options: xml.ParseOptions = {supportDoctype:true, ignoreNameSpace:false, tokenValueCallbackFunction:func}
798that.parse(options);
799console.log(str);
800// 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:
801```
802### getPrefix
803
804getPrefix(): string
805
806Obtains the prefix of this element.
807
808**Atomic service API**: This API can be used in atomic services since API version 11.
809
810**System capability**: SystemCapability.Utils.Lang
811
812**Return value**
813
814| Type  | Description              |
815| ------ | ------------------ |
816| string | Element prefix obtained.|
817
818**Example**
819
820```ts
821import { util } from '@kit.ArkTS';
822
823let strXml =
824  '<?xml version="1.0" encoding="utf-8"?>' +
825  '<note xmlns:h="http://www.w3.org/TR/html4">' +
826    '<h:title>Happy</h:title>' +
827  '</note>';
828let textEncoder = new util.TextEncoder();
829let arrbuffer = textEncoder.encodeInto(strXml);
830let that = new xml.XmlPullParser(arrbuffer.buffer as object as ArrayBuffer);
831let str = "";
832function func(key: xml.EventType, value: xml.ParseInfo) {
833  str += 'key:' + key + ' value:' + value.getPrefix() + ' ';
834  return true; // Determines whether to continually parse, which is used to continue or terminate parsing.
835}
836let options: xml.ParseOptions = {supportDoctype:true, ignoreNameSpace:false, tokenValueCallbackFunction:func}
837that.parse(options);
838console.log(str);
839// key:0 value: key:2 value: key:2 value:h key:4 value: key:3 value:h key:3 value: key:1 value:
840```
841
842### getText
843
844getText(): string
845
846Obtains the text of the current event.
847
848**Atomic service API**: This API can be used in atomic services since API version 11.
849
850**System capability**: SystemCapability.Utils.Lang
851
852**Return value**
853
854| Type  | Description                    |
855| ------ | ------------------------ |
856| string | Text content obtained.|
857
858**Example**
859
860```ts
861import { util } from '@kit.ArkTS';
862
863let strXml = '<?xml version="1.0" encoding="utf-8"?><note>Happy</note>';
864let textEncoder = new util.TextEncoder();
865let arrbuffer = textEncoder.encodeInto(strXml);
866let that = new xml.XmlPullParser(arrbuffer.buffer as object as ArrayBuffer);
867let str = "";
868function func(key: xml.EventType, value: xml.ParseInfo) {
869  str += 'key:' + key + ' value:' + value.getText() + ' ';
870  return true; // Determines whether to continually parse, which is used to continue or terminate parsing.
871}
872let options: xml.ParseOptions = {supportDoctype:true, ignoreNameSpace:true, tokenValueCallbackFunction:func}
873that.parse(options);
874console.log(str);
875// key:0 value: key:2 value: key:4 value:Happy key:3 value: key:1 value:
876```
877### isEmptyElementTag
878
879isEmptyElementTag(): boolean
880
881Checks whether the current element is empty.
882
883**Atomic service API**: This API can be used in atomic services since API version 11.
884
885**System capability**: SystemCapability.Utils.Lang
886
887**Return value**
888
889| Type   | Description                        |
890| ------- | ---------------------------- |
891| boolean | Returns **true** if the element is empty; returns **false** otherwise.|
892
893**Example**
894
895```ts
896import { util } from '@kit.ArkTS';
897
898let strXml =
899  '<?xml version="1.0" encoding="utf-8"?>' +
900  '<note importance="high" logged="true">' +
901    '<title/>' +
902  '</note>';
903let textEncoder = new util.TextEncoder();
904let arrbuffer = textEncoder.encodeInto(strXml);
905let that = new xml.XmlPullParser(arrbuffer.buffer as object as ArrayBuffer);
906let str = "";
907function func(key: xml.EventType, value: xml.ParseInfo) {
908  str += 'key:' + key + ' value:' + value.isEmptyElementTag() + ' ';
909  return true; // Determines whether to continually parse, which is used to continue or terminate parsing.
910}
911let options: xml.ParseOptions = {supportDoctype:true, ignoreNameSpace:true, tokenValueCallbackFunction:func}
912that.parse(options);
913console.log(str);
914// key:0 value:false key:2 value:false key:2 value:true key:3 value:false key:3 value:false key:1 value:false
915```
916### isWhitespace
917
918isWhitespace(): boolean
919
920Checks whether the current event contains only whitespace characters.
921
922**Atomic service API**: This API can be used in atomic services since API version 11.
923
924**System capability**: SystemCapability.Utils.Lang
925
926**Return value**
927
928| Type   | Description                                  |
929| ------- | -------------------------------------- |
930| boolean | Returns **true** if the text event contains only whitespace characters; returns **false** otherwise.|
931
932**Example**
933
934```ts
935import { util } from '@kit.ArkTS';
936
937let strXml =
938  '<?xml version="1.0" encoding="utf-8"?>' +
939  '<note importance="high" logged="true">' +
940    '<title> </title>' +
941  '</note>';
942let textEncoder = new util.TextEncoder();
943let arrbuffer = textEncoder.encodeInto(strXml);
944let that = new xml.XmlPullParser(arrbuffer.buffer as object as ArrayBuffer);
945let str = "";
946function func(key: xml.EventType, value: xml.ParseInfo) {
947  str += 'key:' + key + ' value:' + value.isWhitespace() + ' ';
948  return true; // Determines whether to continually parse, which is used to continue or terminate parsing.
949}
950let options: xml.ParseOptions = {supportDoctype:true, ignoreNameSpace:true, tokenValueCallbackFunction:func}
951that.parse(options);
952console.log(str);
953// 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
954```
955### getAttributeCount
956
957getAttributeCount(): number
958
959Obtains the number of attributes for the current start tag.
960
961**Atomic service API**: This API can be used in atomic services since API version 11.
962
963**System capability**: SystemCapability.Utils.Lang
964
965**Return value**
966| Type  | Description                  |
967| ------ | ---------------------- |
968| number | Number of attributes obtained.|
969
970**Example**
971
972```ts
973import { util } from '@kit.ArkTS';
974
975let strXml = '<?xml version="1.0" encoding="utf-8"?><note importance="high" logged="true"/>';
976let textEncoder = new util.TextEncoder();
977let arrbuffer = textEncoder.encodeInto(strXml);
978let that = new xml.XmlPullParser(arrbuffer.buffer as object as ArrayBuffer);
979let str = "";
980function func(key: xml.EventType, value: xml.ParseInfo) {
981  str += 'key:' + key + ' value:' + value.getAttributeCount() + ' ';
982  return true; // Determines whether to continually parse, which is used to continue or terminate parsing.
983}
984let options: xml.ParseOptions = {supportDoctype:true, ignoreNameSpace:true, tokenValueCallbackFunction:func}
985that.parse(options);
986console.log(str);
987// key:0 value:0 key:2 value:2 key:3 value:2 key:1 value:0
988```
989
990## EventType
991
992Enumerates the event types.
993
994**Atomic service API**: This API can be used in atomic services since API version 11.
995
996**System capability**: SystemCapability.Utils.Lang
997
998| Name            | Value  | Description                 |
999| ---------------- | ---- | --------------------- |
1000| START_DOCUMENT   | 0    | Start document event.       |
1001| END_DOCUMENT     | 1    | End document event.       |
1002| START_TAG        | 2    | Start tag event.       |
1003| END_TAG          | 3    | End tag event.       |
1004| TEXT             | 4    | Text event.           |
1005| CDSECT           | 5    | CDATA section event.          |
1006| COMMENT          | 6    | XML comment event.        |
1007| DOCDECL          | 7    | XML document type declaration event.|
1008| INSTRUCTION      | 8    | XML processing instruction event.|
1009| ENTITY_REFERENCE | 9    | Entity reference event.       |
1010| WHITESPACE       | 10   | Whitespace character event.           |
1011