1# XML Parsing and Generation 2 3> **NOTE** 4> 5> 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. 6 7 8## Modules to Import 9 10``` 11import xml from '@ohos.xml'; 12``` 13 14## XmlSerializer 15 16 17### constructor 18 19constructor(buffer: ArrayBuffer | DataView, encoding?: string) 20 21A constructor used to create an **XmlSerializer** instance. 22 23**System capability**: SystemCapability.Utils.Lang 24 25**Parameters** 26 27| Name| Type| Mandatory| Description| 28| -------- | -------- | -------- | -------- | 29| buffer | ArrayBuffer \| DataView | Yes| **ArrayBuffer** or **DataView** for storing the XML information to write.| 30| encoding | string | No| Encoding format.| 31 32**Example** 33 34```js 35var arrayBuffer = new ArrayBuffer(1024); 36var bufView = new DataView(arrayBuffer); 37var thatSer = new xml.XmlSerializer(bufView); 38``` 39 40 41### setAttributes 42 43setAttributes(name: string, value: string): void 44 45Sets an attribute. 46 47**System capability**: SystemCapability.Utils.Lang 48 49**Parameters** 50 51| Name| Type| Mandatory| Description| 52| -------- | -------- | -------- | -------- | 53| name | string | Yes| Key of the attribute.| 54| value | string | Yes| Value of the attribute.| 55 56**Example** 57 58```js 59var arrayBuffer = new ArrayBuffer(1024); 60var bufView = new DataView(arrayBuffer); 61var thatSer = new xml.XmlSerializer(bufView); 62thatSer.setAttributes("importance", "high"); 63``` 64 65 66### addEmptyElement 67 68addEmptyElement(name: string): void 69 70Adds an empty element. 71 72**System capability**: SystemCapability.Utils.Lang 73 74**Parameters** 75 76| Name| Type| Mandatory| Description| 77| -------- | -------- | -------- | -------- | 78| name | string | Yes| Name of the empty element to add.| 79 80**Example** 81 82```js 83var arrayBuffer = new ArrayBuffer(1024); 84var bufView = new DataView(arrayBuffer); 85var thatSer = new xml.XmlSerializer(bufView); 86thatSer.addEmptyElement("b"); // => <b/> 87``` 88 89 90### setDeclaration 91 92setDeclaration(): void 93 94Sets a declaration. 95 96**System capability**: SystemCapability.Utils.Lang 97 98**Example** 99 100```js 101var arrayBuffer = new ArrayBuffer(1024); 102var bufView = new DataView(arrayBuffer); 103var thatSer = new xml.XmlSerializer(bufView); 104thatSer.setDeclaration() // => <?xml version="1.0" encoding="utf-8"?>; 105``` 106 107 108### startElement 109 110startElement(name: string): void 111 112Writes the start tag based on the given element name. 113 114**System capability**: SystemCapability.Utils.Lang 115 116**Parameters** 117 118| Name| Type| Mandatory| Description| 119| -------- | -------- | -------- | -------- | 120| name | string | Yes| Name of the element.| 121 122**Example** 123 124```js 125var arrayBuffer = new ArrayBuffer(1024); 126var thatSer = new xml.XmlSerializer(arrayBuffer); 127thatSer.startElement("notel"); 128thatSer.endElement();// => '<notel/>'; 129``` 130 131 132### endElement 133 134endElement(): void 135 136Writes the end tag of the element. 137 138**System capability**: SystemCapability.Utils.Lang 139 140**Example** 141 142```js 143var arrayBuffer = new ArrayBuffer(1024); 144var bufView = new DataView(arrayBuffer); 145var thatSer = new xml.XmlSerializer(bufView); 146thatSer.setNamespace("h", "http://www.w3.org/TR/html4/"); 147thatSer.startElement("table"); 148thatSer.setAttributes("importance", "high"); 149thatSer.setText("Happy"); 150endElement(); // => <h:table importance="high" xmlns:h="http://www.w3.org/TR/html4/">Happy</h:table> 151``` 152 153 154### setNamespace 155 156setNamespace(prefix: string, namespace: string): void 157 158Sets the namespace for an element tag. 159 160**System capability**: SystemCapability.Utils.Lang 161 162**Parameters** 163 164| Name| Type| Mandatory| Description| 165| -------- | -------- | -------- | -------- | 166| prefix | string | Yes| Prefix of the element and its child elements.| 167| namespace | string | Yes| Namespace to set.| 168 169**Example** 170 171```js 172var arrayBuffer = new ArrayBuffer(1024); 173var thatSer = new xml.XmlSerializer(arrayBuffer); 174thatSer.setDeclaration(); 175thatSer.setNamespace("h", "http://www.w3.org/TR/html4/"); 176thatSer.startElement("note"); 177thatSer.endElement();// = >'<?xml version="1.0" encoding="utf-8"?>\r\n<h:note xmlns:h="http://www.w3.org/TR/html4/"/>'; 178``` 179 180### setComment 181 182setComment(text: string): void 183 184Sets the comment. 185 186**System capability**: SystemCapability.Utils.Lang 187 188**Parameters** 189 190| Name| Type| Mandatory| Description| 191| -------- | -------- | -------- | -------- | 192| text | string | Yes| Comment to set.| 193 194**Example** 195 196```js 197var arrayBuffer = new ArrayBuffer(1024); 198var thatSer = new xml.XmlSerializer(arrayBuffer); 199thatSer.startElement("note"); 200thatSer.setComment("Hi!"); 201thatSer.endElement(); // => '<note>\r\n <!--Hi!-->\r\n</note>'; 202``` 203 204 205### setCDATA 206 207setCDATA(text: string): void 208 209Sets CDATA attributes. 210 211**System capability**: SystemCapability.Utils.Lang 212 213**Parameters** 214 215| Name| Type| Mandatory| Description| 216| -------- | -------- | -------- | -------- | 217| text | string | Yes| CDATA attribute to set.| 218 219**Example** 220 221```js 222var arrayBuffer = new ArrayBuffer(1028); 223var thatSer = new xml.XmlSerializer(arrayBuffer); 224thatSer.setCDATA('root SYSTEM') // => '<![CDATA[root SYSTEM]]>'; 225``` 226 227 228### setText 229 230setText(text: string): void 231 232Sets **Text**. 233 234**System capability**: SystemCapability.Utils.Lang 235 236**Parameters** 237 238| Name| Type| Mandatory| Description| 239| -------- | -------- | -------- | -------- | 240| text | string | Yes| Content of the **Text** to set.| 241 242**Example** 243 244```js 245var arrayBuffer = new ArrayBuffer(1024); 246var thatSer = new xml.XmlSerializer(arrayBuffer); 247thatSer.startElement("note"); 248thatSer.setAttributes("importance", "high"); 249thatSer.setText("Happy1"); 250thatSer.endElement(); // => '<note importance="high">Happy1</note>'; 251``` 252 253 254### setDocType 255 256setDocType(text: string): void 257 258Sets **DocType**. 259 260**System capability**: SystemCapability.Utils.Lang 261 262**Parameters** 263 264| Name| Type| Mandatory| Description| 265| -------- | -------- | -------- | -------- | 266| text | string | Yes| Content of **DocType** to set.| 267 268**Example** 269 270```js 271var arrayBuffer = new ArrayBuffer(1024); 272var thatSer = new xml.XmlSerializer(arrayBuffer); 273thatSer.setDocType('root SYSTEM'); // => '<!DOCTYPE root SYSTEM>'; 274``` 275 276 277## XmlPullParser 278 279 280### XmlPullParser 281 282constructor(buffer: ArrayBuffer | DataView, encoding?: string) 283 284Creates and returns an **XmlPullParser** object. The **XmlPullParser** object passes two parameters. The first parameter is the memory of the **ArrayBuffer** or **DataView** type, and the second parameter is the file format (UTF-8 by default). 285 286**System capability**: SystemCapability.Utils.Lang 287 288**Parameters** 289 290| Name| Type| Mandatory| Description| 291| -------- | -------- | -------- | -------- | 292| buffer | ArrayBuffer \| DataView | Yes| **ArrayBuffer** or **DataView** that contains XML text information.| 293| encoding | string | No| Encoding format. Only UTF-8 is supported.| 294 295**Example** 296 297```js 298var strXml = 299 '<?xml version="1.0" encoding="utf-8"?>' + 300 '<note importance="high" logged="true">' + 301 ' <title>Happy</title>' + 302 ' <todo>Work</todo>' + 303 ' <todo>Play</todo>' + 304 '</note>'; 305var arrayBuffer = new ArrayBuffer(strXml.length*2); 306var bufView = new Uint8Array(arrayBuffer); 307var strLen = strXml.length; 308for (var i = 0; i < strLen; ++i) { 309 bufView[i] = strXml.charCodeAt(i);// Set the ArrayBuffer mode. 310} 311var that = new xml.XmlPullParser(arrayBuffer); 312``` 313 314 315### parse 316 317parse(option: ParseOptions): void 318 319Parses XML information. 320 321**System capability**: SystemCapability.Utils.Lang 322 323**Parameters** 324 325| Name| Type| Mandatory| Description| 326| -------- | -------- | -------- | -------- | 327| option | [ParseOptions](#parseoptions) | Yes| Options for controlling and obtaining the parsed information.| 328 329**Example** 330 331```js 332var strXml = 333 '<?xml version="1.0" encoding="utf-8"?>' + 334 '<note importance="high" logged="true">' + 335 ' <title>Happy</title>' + 336 ' <todo>Work</todo>' + 337 ' <todo>Play</todo>' + 338 '</note>'; 339var arrayBuffer = new ArrayBuffer(strXml.length*2); 340var bufView = new Uint8Array(arrayBuffer); 341var strLen = strXml.length; 342for (var i = 0; i < strLen; ++i) { 343 bufView[i] = strXml.charCodeAt(i); 344} 345var that = new xml.XmlPullParser(arrayBuffer); 346var arrTag = {}; 347arrTag[0] = '132'; 348var i = 1; 349function func(key, value){ 350 arrTag[i] = 'key:'+key+' value:'+ value.getDepth(); 351 i++; 352 return true; 353} 354var options = {supportDoctype:true, ignoreNameSpace:true, tokenValueCallbackFunction:func} 355that.parse(options); 356``` 357 358 359## ParseOptions 360 361Defines the XML parsing options. 362 363**System capability**: SystemCapability.Utils.Lang 364 365 366| Name| Type| Mandatory| Description| 367| -------- | -------- | -------- | -------- | 368| supportDoctype | boolean | No| Whether to ignore **Doctype**. The default value is **false**.| 369| ignoreNameSpace | boolean | No| Whether to ignore **Namespace**. The default value is **false**.| 370| tagValueCallbackFunction | (name: string, value: string)=> boolean | No| Callback used to return **tagValue**.| 371| attributeValueCallbackFunction | (name: string, value: string)=> boolean | No| Callback used to return **attributeValue**.| 372| tokenValueCallbackFunction | (eventType: [EventType](#eventtype), value: [ParseInfo](#parseinfo))=> boolean | No| Callback used to return **tokenValue**.| 373 374## ParseInfo 375 376Provides APIs to manage the parsed XML information. 377 378 379### getColumnNumber 380 381getColumnNumber(): number 382 383Obtains the column line number, which starts from 1. 384 385**System capability**: SystemCapability.Utils.Lang 386 387**Return value** 388 389| Type| Description| 390| -------- | -------- | 391| number | Column number obtained.| 392 393 394### getDepth 395 396getDepth(): number 397 398Obtains the depth of this element. 399 400**System capability**: SystemCapability.Utils.Lang 401 402**Return value** 403 404| Type| Description| 405| -------- | -------- | 406| number | Depth obtained.| 407 408 409### getLineNumber 410 411getLineNumber(): number 412 413Obtains the current line number, starting from 1. 414 415**System capability**: SystemCapability.Utils.Lang 416 417**Return value** 418 419| Type| Description| 420| -------- | -------- | 421| number | Line number obtained.| 422 423 424### getName 425 426getName(): string 427 428Obtains the name of this element. 429 430**System capability**: SystemCapability.Utils.Lang 431 432**Return value** 433 434| Type| Description| 435| -------- | -------- | 436| string | Element name obtained.| 437 438 439### getNamespace 440 441getNamespace(): string 442 443Obtains the namespace of this element. 444 445**System capability**: SystemCapability.Utils.Lang 446 447**Return value** 448 449| Type| Description| 450| -------- | -------- | 451| string | Namespace obtained.| 452 453 454### getPrefix 455 456getPrefix(): string 457 458Obtains the prefix of this element. 459 460**System capability**: SystemCapability.Utils.Lang 461 462**Return value** 463 464| Type| Description| 465| -------- | -------- | 466| string | Element prefix obtained.| 467 468 469### getText 470 471getText(): string 472 473Obtains the text of the current event. 474 475**System capability**: SystemCapability.Utils.Lang 476 477**Return value** 478 479| Type| Description| 480| -------- | -------- | 481| string | Text content obtained.| 482 483 484### isEmptyElementTag 485 486isEmptyElementTag(): boolean 487 488Checks whether the current element is empty. 489 490**System capability**: SystemCapability.Utils.Lang 491 492**Return value** 493 494| Type| Description| 495| -------- | -------- | 496| boolean | Returns **true** if the element is empty; returns **false** otherwise.| 497 498 499### isWhitespace 500 501isWhitespace(): boolean 502 503Checks whether the current text event contains only whitespace characters. 504 505**System capability**: SystemCapability.Utils.Lang 506 507**Return value** 508 509| Type| Description| 510| -------- | -------- | 511| boolean | Returns **true** if the text event contains only whitespace characters; returns **false** otherwise.| 512 513 514### getAttributeCount 515 516getAttributeCount(): number 517 518Obtains the number of attributes for the current start tag. 519 520**System capability**: SystemCapability.Utils.Lang 521 522**Return value** 523| Type| Description| 524| -------- | -------- | 525| number | Number of attributes obtained.| 526 527 528## EventType 529 530Enumerates the events. 531 532**System capability**: SystemCapability.Utils.Lang 533 534| Name| Value| Description| 535| -------- | -------- | -------- | 536| START_DOCUMENT | 0 | Indicates a start document event.| 537| END_DOCUMENT | 1 | Indicates an end document event.| 538| START_TAG | 2 | Indicates a start tag event.| 539| END_TAG | 3 | Indicates an end tag event.| 540| TEXT | 4 | Indicates a text event.| 541| CDSECT | 5 | Indicates a CDATA section event.| 542| COMMENT | 6 | Indicates an XML comment event.| 543| DOCDECL | 7 | Indicates an XML document type declaration event.| 544| INSTRUCTION | 8 | Indicates an XML processing instruction event.| 545| ENTITY_REFERENCE | 9 | Indicates an entity reference event.| 546| WHITESPACE | 10 | Indicates a whitespace character event.| 547