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