1# @ohos.convertxml (XML-to-JavaScript Conversion) 2 3The **convertxml** module provides APIs for converting XML text into JavaScript objects. 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```ts 13import { convertxml } from '@kit.ArkTS'; 14``` 15 16## ConvertXML 17 18### convertToJSObject<sup>9+</sup> 19 20convertToJSObject(xml: string, options?: ConvertOptions) : Object 21 22Converts an XML text into a JavaScript object. 23 24**Atomic service API**: This API can be used in atomic services since API version 11. 25 26**System capability**: SystemCapability.Utils.Lang 27 28**Parameters** 29 30| Name | Type | Mandatory | Description | 31| ------- | --------------------------------- | ---- | --------------- | 32| xml | string | Yes | XML text to convert. | 33| options | [ConvertOptions](#convertoptions) | No | Options for conversion. The default value is a **ConvertOptions** object, which consists of the default values of the attributes in the object. | 34 35**Return value** 36 37| Type | Description | 38| ------ | ---------------------------- | 39| Object | JavaScript object. | 40 41**Error codes** 42 43For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Utils Error Codes](errorcode-utils.md). 44 45| ID | Error Message | 46| -------- | -------- | 47| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 48| 10200002 | Invalid xml string. | 49 50**Example** 51 52```ts 53try { 54 let xml = 55 '<?xml version="1.0" encoding="utf-8"?>' + 56 '<note importance="high" logged="true">' + 57 ' <title>Happy</title>' + 58 ' <todo>Work</todo>' + 59 ' <todo>Play</todo>' + 60 '</note>'; 61 let conv = new convertxml.ConvertXML() 62 let options: convertxml.ConvertOptions = { 63 trim: false, declarationKey: "_declaration", 64 instructionKey: "_instruction", attributesKey: "_attributes", 65 textKey: "_text", cdataKey: "_cdata", doctypeKey: "_doctype", 66 commentKey: "_comment", parentKey: "_parent", typeKey: "_type", 67 nameKey: "_name", elementsKey: "_elements" 68 } 69 let result = JSON.stringify(conv.convertToJSObject(xml, options)); 70 console.log(result); 71} catch (e) { 72 console.log((e as Object).toString()); 73} 74// Output (non-compact) 75// {"_declaration":{"_attributes":{"version":"1.0","encoding":"utf-8"}},"_elements":[{"_type":"element","_name":"note","_attributes":{"importance":"high","logged":"true"},"_elements":[{"_type":"element","_name":"title","_elements":[{"_type":"text","_text":"Happy"}]},{"_type":"element","_name":"todo","_elements":[{"_type":"text","_text":"Work"}]},{"_type":"element","_name":"todo","_elements":[{"_type":"text","_text":"Play"}]}]}]} 76``` 77 78### convert<sup>(deprecated)</sup> 79 80convert(xml: string, options?: ConvertOptions) : Object 81 82Converts an XML text into a JavaScript object. 83 84> **NOTE** 85> 86> This API is supported since API version 8 and deprecated since API version 9. You are advised to use [convertToJSObject<sup>9+</sup>](#converttojsobject9) instead. 87 88**System capability**: SystemCapability.Utils.Lang 89 90**Parameters** 91 92| Name | Type | Mandatory | Description | 93| ------- | --------------------------------- | ---- | --------------- | 94| xml | string | Yes | XML text to convert. | 95| options | [ConvertOptions](#convertoptions) | No | Options for conversion. The default value is a **ConvertOptions** object, which consists of the default values of the attributes in the object. | 96 97**Return value** 98 99| Type | Description | 100| ------ | ---------------------------- | 101| Object | JavaScript object. | 102 103**Example** 104 105```ts 106let xml = 107 '<?xml version="1.0" encoding="utf-8"?>' + 108 '<note importance="high" logged="true">' + 109 ' <title>Happy</title>' + 110 ' <todo>Work</todo>' + 111 ' <todo>Play</todo>' + 112 '</note>'; 113let conv = new convertxml.ConvertXML(); 114let options: convertxml.ConvertOptions = {trim : false, declarationKey:"_declaration", 115 instructionKey : "_instruction", attributesKey : "_attributes", 116 textKey : "_text", cdataKey:"_cdata", doctypeKey : "_doctype", 117 commentKey : "_comment", parentKey : "_parent", typeKey : "_type", 118 nameKey : "_name", elementsKey : "_elements"} 119let result = JSON.stringify(conv.convert(xml, options)); 120console.log(result); 121// Output (non-compact) 122// {"_declaration":{"_attributes":{"version":"1.0","encoding":"utf-8"}},"_elements":[{"_type":"element","_name":"note","_attributes":{"importance":"high","logged":"true"},"_elements":[{"_type":"element","_name":"title","_elements":[{"_type":"text","_text":"Happy"}]},{"_type":"element","_name":"todo","_elements":[{"_type":"text","_text":"Work"}]},{"_type":"element","_name":"todo","_elements":[{"_type":"text","_text":"Play"}]}]}]} 123``` 124 125## ConvertOptions 126 127Options for conversion. 128 129**Atomic service API**: This API can be used in atomic services since API version 11. 130 131**System capability**: SystemCapability.Utils.Lang 132 133| Name | Type | Mandatory | Description | 134| ----------------- | -------- | ---- | ----------------------------------------------------------- | 135| trim | boolean | Yes | Whether to trim the whitespace characters before and after the text. | 136| ignoreDeclaration | boolean | No | Whether to ignore the XML declaration. The default value is **false**. | 137| ignoreInstruction | boolean | No | Whether to ignore the XML processing instruction. The default value is **false**. | 138| ignoreAttributes | boolean | No | Whether to ignore the element's attribute information. The default value is **false**. | 139| ignoreComment | boolean | No | Whether to ignore element comments. The default value is **false**. | 140| ignoreCDATA | boolean | No | Whether to ignore the element's CDATA information. The default value is **false**. | 141| ignoreDoctype | boolean | No | Whether to ignore the element's Doctype information. The default value is **false**. | 142| ignoreText | boolean | No | Whether to ignore the element's text information. The default value is **false**. | 143| declarationKey | string | Yes | Name of the attribute key for **declaration** in the output object. | 144| instructionKey | string | Yes | Name of the attribute key for **instruction** in the output object. | 145| attributesKey | string | Yes | Name of the attribute key for **attributes** in the output object. | 146| textKey | string | Yes | Name of the attribute key for **text** in the output object. | 147| cdataKey | string | Yes | Name of the attribute key for **cdata** in the output object. | 148| doctypeKey | string | Yes | Name of the attribute key for **doctype** in the output object. | 149| commentKey | string | Yes | Name of the attribute key for **comment** in the output object. | 150| parentKey | string | Yes | Name of the attribute key for **parent** in the output object. | 151| typeKey | string | Yes | Name of the attribute key for **type** in the output object. | 152| nameKey | string | Yes | Name of the attribute key for **name** in the output object. | 153| elementsKey | string | Yes | Name of the attribute key for **elements** in the output object. | 154