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 & 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) => 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) => boolean | No | Parsing attribute and attribute value. The default value is **undefined**, indicating no parsing.| 605| tokenValueCallbackFunction | (eventType: [EventType](#eventtype), value: [ParseInfo](#parseinfo)) => 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