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文本,若包含“&”字符,请使用实体引用“\&”替换。| 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文本,若包含“&”字符,请使用实体引用“\&”替换。| 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的属性键的名称。 |