1# @ohos.convertxml (xml转换JavaScript)
2
3本模块提供转换xml文本为JavaScript对象的功能。
4
5> **说明:**
6>
7> 本模块首批接口从API version 8开始支持。后续版本的新增接口,采用上角标单独标记接口的起始版本。
8
9
10## 导入模块
11
12```ts
13import { convertxml } from '@kit.ArkTS';
14```
15
16## ConvertXML
17
18### fastConvertToJSObject<sup>14+</sup>
19
20fastConvertToJSObject(xml: string, options?: ConvertOptions) : Object
21
22转换xml文本为JavaScript对象。
23
24> **说明:**
25>
26> 在Windows环境中,通常以回车符(CR)和换行符(LF)一对字符来表示换行。fastConvertToJSObject接口转换后的对象以换行符(LF)表示换行。
27
28**原子化服务API**:从API version 14 开始,该接口支持在原子化服务中使用。
29
30**系统能力:** SystemCapability.Utils.Lang
31
32**参数:**
33
34| 参数名  | 类型                              | 必填 | 说明            |
35| ------- | --------------------------------- | ---- | --------------- |
36| xml     | string                            | 是   | xml文本,若包含“&”字符,请使用实体引用“\&amp;”替换。|
37| options | [ConvertOptions](#convertoptions) | 否   | 转换选项,默认值是ConvertOptions对象,由其中各个属性的默认值组成。|
38
39**返回值:**
40
41| 类型   | 说明                         |
42| ------ | ---------------------------- |
43| Object | 处理后返回的JavaScript对象。 |
44
45**错误码:**
46
47以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[语言基础类库错误码](errorcode-utils.md)。
48
49| 错误码ID | 错误信息 |
50| -------- | -------- |
51| 401      | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. |
52| 10200002 | Invalid xml string. |
53
54**示例:**
55
56```ts
57try {
58  let xml =
59    '<?xml version="1.0" encoding="utf-8"?>' +
60    '<note importance="high" logged="true">' +
61    '   <title>Hello\r\nWorld</title>' +
62    '   <todo><![CDATA[Work\r\n]]></todo>' +
63    '</note>';
64  let conv = new convertxml.ConvertXML()
65  let options: convertxml.ConvertOptions = {
66    trim: false, declarationKey: "_declaration",
67    instructionKey: "_instruction", attributesKey: "_attributes",
68    textKey: "_text", cdataKey: "_cdata", doctypeKey: "_doctype",
69    commentKey: "_comment", parentKey: "_parent", typeKey: "_type",
70    nameKey: "_name", elementsKey: "_elements"
71  }
72  let result = JSON.stringify(conv.fastConvertToJSObject(xml, options));
73  console.log(result);
74} catch (e) {
75  console.log((e as Object).toString());
76}
77// 输出(宽泛型)
78// {"_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":"Hello\nWorld"}]},{"_type":"element","_name":"todo","_elements":[{"_type":"cdata","_cdata":"Work\n"}]}]}]}
79```
80
81### convertToJSObject<sup>(deprecated)</sup>
82
83convertToJSObject(xml: string, options?: ConvertOptions) : Object
84
85转换xml文本为JavaScript对象。
86
87> **说明:**
88>
89> 从API version 9开始支持,从API version 14开始废弃,建议使用[fastConvertToJSObject<sup>14+</sup>](#fastconverttojsobject14)替代。
90
91**原子化服务API**:从API version 11 开始,该接口支持在原子化服务中使用。
92
93**系统能力:** SystemCapability.Utils.Lang
94
95**参数:**
96
97| 参数名  | 类型                              | 必填 | 说明            |
98| ------- | --------------------------------- | ---- | --------------- |
99| xml     | string                            | 是   | 传入的xml文本,若包含“&”字符,请使用实体引用“\&amp;”替换。|
100| options | [ConvertOptions](#convertoptions) | 否   | 转换选项,默认值是ConvertOptions对象,由其中各个属性的默认值组成。 |
101
102**返回值:**
103
104| 类型   | 说明                         |
105| ------ | ---------------------------- |
106| Object | 处理后返回的JavaScript对象。 |
107
108**错误码:**
109
110以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[语言基础类库错误码](errorcode-utils.md)。
111
112| 错误码ID | 错误信息 |
113| -------- | -------- |
114| 401      | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. |
115| 10200002 | Invalid xml string. |
116
117**示例:**
118
119```ts
120try {
121  let xml =
122    '<?xml version="1.0" encoding="utf-8"?>' +
123      '<note importance="high" logged="true">' +
124      '    <title>Happy</title>' +
125      '    <todo>Work</todo>' +
126      '    <todo>Play</todo>' +
127      '</note>';
128  let conv = new convertxml.ConvertXML()
129  let options: convertxml.ConvertOptions = {
130    trim: false, declarationKey: "_declaration",
131    instructionKey: "_instruction", attributesKey: "_attributes",
132    textKey: "_text", cdataKey: "_cdata", doctypeKey: "_doctype",
133    commentKey: "_comment", parentKey: "_parent", typeKey: "_type",
134    nameKey: "_name", elementsKey: "_elements"
135  }
136  let result = JSON.stringify(conv.convertToJSObject(xml, options));
137  console.log(result);
138} catch (e) {
139  console.log((e as Object).toString());
140}
141// 输出(宽泛型)
142// {"_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"}]}]}]}
143```
144
145### convert<sup>(deprecated)</sup>
146
147convert(xml: string, options?: ConvertOptions) : Object
148
149转换xml文本为JavaScript对象。
150
151> **说明:**
152>
153> 从API version 8开始支持,从API version 9开始废弃,建议使用[fastConvertToJSObject<sup>14+</sup>](#fastconverttojsobject14)替代。
154
155**系统能力:** SystemCapability.Utils.Lang
156
157**参数:**
158
159| 参数名  | 类型                              | 必填 | 说明            |
160| ------- | --------------------------------- | ---- | --------------- |
161| xml     | string                            | 是   | 传入的xml文本。 |
162| options | [ConvertOptions](#convertoptions) | 否   | 转换选项 , 默认值是ConvertOptions对象 , 由其中各个属性的默认值组成。  |
163
164**返回值:**
165
166| 类型   | 说明                         |
167| ------ | ---------------------------- |
168| Object | 处理后返回的JavaScript对象。 |
169
170**示例:**
171
172```ts
173let xml =
174  '<?xml version="1.0" encoding="utf-8"?>' +
175    '<note importance="high" logged="true">' +
176    '    <title>Happy</title>' +
177    '    <todo>Work</todo>' +
178    '    <todo>Play</todo>' +
179    '</note>';
180let conv = new convertxml.ConvertXML();
181let options: convertxml.ConvertOptions = {trim : false, declarationKey:"_declaration",
182  instructionKey : "_instruction", attributesKey : "_attributes",
183  textKey : "_text", cdataKey:"_cdata", doctypeKey : "_doctype",
184  commentKey : "_comment", parentKey : "_parent", typeKey : "_type",
185  nameKey : "_name", elementsKey : "_elements"}
186let result = JSON.stringify(conv.convert(xml, options));
187console.log(result);
188// 输出(宽泛型)
189// {"_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"}]}]}]}
190```
191
192## ConvertOptions
193
194转换选项。
195
196**原子化服务API**:从API version 11 开始,该接口支持在原子化服务中使用。
197
198**系统能力:** SystemCapability.Utils.Lang
199
200| 名称              | 类型 | 必填 | 说明                                                        |
201| ----------------- | -------- | ---- | ----------------------------------------------------------- |
202| trim              | boolean  | 是   | 是否修剪位于文本前后的空白字符。                 |
203| ignoreDeclaration | boolean  | 否   | 是否忽略xml写入声明指示,默认false。                        |
204| ignoreInstruction | boolean  | 否   | 是否忽略xml的写入处理指令,默认false。                      |
205| ignoreAttributes  | boolean  | 否   | 是否忽略元素的属性信息,默认false。                   |
206| ignoreComment     | boolean  | 否   | 是否忽略元素的注释信息,默认false。                         |
207| ignoreCDATA       | boolean  | 否   | 是否忽略元素的CDATA信息,默认false。                        |
208| ignoreDoctype     | boolean  | 否   | 是否忽略元素的Doctype信息,默认false。                      |
209| ignoreText        | boolean  | 否   | 是否忽略元素的文本信息,默认false。                         |
210| declarationKey    | string   | 是   | 用于输出对象中declaration的属性键的名称。 |
211| instructionKey    | string   | 是   | 用于输出对象中instruction的属性键的名称。 |
212| attributesKey     | string   | 是   | 用于输出对象中attributes的属性键的名称。   |
213| textKey           | string   | 是   | 用于输出对象中text的属性键的名称。               |
214| cdataKey          | string   | 是   | 用于输出对象中cdata的属性键的名称             |
215| doctypeKey        | string   | 是   | 用于输出对象中doctype的属性键的名称。         |
216| commentKey        | string   | 是   | 用于输出对象中comment的属性键的名称。         |
217| parentKey         | string   | 是   | 用于输出对象中parent的属性键的名称。           |
218| typeKey           | string   | 是   | 用于输出对象中type的属性键的名称。               |
219| nameKey           | string   | 是   | 用于输出对象中name的属性键的名称。               |
220| elementsKey       | string   | 是   | 用于输出对象中elements的属性键的名称。       |