• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
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 '@ohos.convertxml';
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**System capability**: SystemCapability.Utils.Lang
25
26**Parameters**
27
28| Name | Type                             | Mandatory| Description           |
29| ------- | --------------------------------- | ---- | --------------- |
30| xml     | string                            | Yes  | XML text to convert.|
31| 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. |
32
33**Return value**
34
35| Type  | Description                        |
36| ------ | ---------------------------- |
37| Object | JavaScript object.|
38
39**Error codes**
40
41For details about the error codes, see [Utils Error Codes](../errorcodes/errorcode-utils.md).
42
43| ID| Error Message|
44| -------- | -------- |
45| 10200002 | Invalid xml string. |
46
47**Example**
48
49```ts
50try {
51  let xml =
52    '<?xml version="1.0" encoding="utf-8"?>' +
53      '<note importance="high" logged="true">' +
54      '    <title>Happy</title>' +
55      '    <todo>Work</todo>' +
56      '    <todo>Play</todo>' +
57      '</note>';
58  let conv = new convertxml.ConvertXML()
59  let options: convertxml.ConvertOptions = {
60    trim: false, declarationKey: "_declaration",
61    instructionKey: "_instruction", attributesKey: "_attributes",
62    textKey: "_text", cdataKey: "_cdata", doctypeKey: "_doctype",
63    commentKey: "_comment", parentKey: "_parent", typeKey: "_type",
64    nameKey: "_name", elementsKey: "_elements"
65  }
66  let result = JSON.stringify(conv.convertToJSObject(xml, options));
67  console.log(result);
68} catch (e) {
69  console.log((e as Object).toString());
70}
71// Output (non-compact)
72// {"_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"}]}]}]}
73```
74
75### convert<sup>(deprecated)</sup>
76
77convert(xml: string, options?: ConvertOptions) : Object
78
79Converts an XML text into a JavaScript object.
80
81> **NOTE**
82>
83> 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.
84
85**System capability**: SystemCapability.Utils.Lang
86
87**Parameters**
88
89| Name | Type                             | Mandatory| Description           |
90| ------- | --------------------------------- | ---- | --------------- |
91| xml     | string                            | Yes  | XML text to convert.|
92| 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. |
93
94**Return value**
95
96| Type  | Description                        |
97| ------ | ---------------------------- |
98| Object | JavaScript object.|
99
100**Example**
101
102```ts
103let xml =
104  '<?xml version="1.0" encoding="utf-8"?>' +
105    '<note importance="high" logged="true">' +
106    '    <title>Happy</title>' +
107    '    <todo>Work</todo>' +
108    '    <todo>Play</todo>' +
109    '</note>';
110let conv = new convertxml.ConvertXML();
111let options: convertxml.ConvertOptions = {trim : false, declarationKey:"_declaration",
112  instructionKey : "_instruction", attributesKey : "_attributes",
113  textKey : "_text", cdataKey:"_cdata", doctypeKey : "_doctype",
114  commentKey : "_comment", parentKey : "_parent", typeKey : "_type",
115  nameKey : "_name", elementsKey : "_elements"}
116let result = JSON.stringify(conv.convert(xml, options));
117console.log(result);
118// Output (non-compact)
119// {"_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"}]}]}]}
120```
121
122## ConvertOptions
123
124Options for conversion.
125
126**System capability**: SystemCapability.Utils.Lang
127
128| Name             | Type| Mandatory| Description                                                       |
129| ----------------- | -------- | ---- | ----------------------------------------------------------- |
130| trim              | boolean  | Yes  | Whether to trim the whitespace characters before and after the text.                |
131| ignoreDeclaration | boolean  | No  | Whether to ignore the XML declaration. The default value is **false**.                       |
132| ignoreInstruction | boolean  | No  | Whether to ignore the XML processing instruction. The default value is **false**.                     |
133| ignoreAttributes  | boolean  | No  | Whether to print attributes across multiple lines and indent attributes. The default value is **false**.                  |
134| ignoreComment     | boolean  | No  | Whether to ignore element comments. The default value is **false**.                        |
135| ignoreCDATA       | boolean  | No  | Whether to ignore the element's CDATA information. The default value is **false**.                       |
136| ignoreDoctype     | boolean  | No  | Whether to ignore the element's Doctype information. The default value is **false**.                     |
137| ignoreText        | boolean  | No  | Whether to ignore the element's text information. The default value is **false**.                        |
138| declarationKey    | string   | Yes  | Name of the attribute key for **declaration** in the output object.|
139| instructionKey    | string   | Yes  | Name of the attribute key for **instruction** in the output object.|
140| attributesKey     | string   | Yes  | Name of the attribute key for **attributes** in the output object.  |
141| textKey           | string   | Yes  | Name of the attribute key for **text** in the output object.              |
142| cdataKey          | string   | Yes  | Name of the attribute key for **cdata** in the output object.            |
143| doctypeKey        | string   | Yes  | Name of the attribute key for **doctype** in the output object.        |
144| commentKey        | string   | Yes  | Name of the attribute key for **comment** in the output object.        |
145| parentKey         | string   | Yes  | Name of the attribute key for **parent** in the output object.          |
146| typeKey           | string   | Yes  | Name of the attribute key for **type** in the output object.              |
147| nameKey           | string   | Yes  | Name of the attribute key for **name** in the output object.              |
148| elementsKey       | string   | Yes  | Name of the attribute key for **elements** in the output object.      |
149