1# Arkts子系统变更说明
2
3## cl.arkts.1 xml.XmlPullParser.parse接口解析实体引用事件的行为变更
4
5**访问级别**
6
7公开接口
8
9**变更原因**
10
11parse接口解析xml时，会把实体引用事件识别为文本事件，用户在tokenValueCallbackFunction中指定的回调函数无法得到实体引用事件的解析结果，解析内容会被整合在文本事件中，不符合设计预期，需要修改。
12
13**变更影响**
14
15该变更为不兼容变更。
16
17变更前：实体引用事件的xml信息被解析为文本事件，用户无法在回调函数中针对实体引用事件进行操作，也无法仅通过xml解析结果判断实体引用事件是否存在。
18
19变更后：在API12及更高版本中，实体引用事件的xml信息被解析为实体引用事件，用户可以在回调函数中针对实体引用事件进行操作，也能仅通过xml解析结果判断实体引用事件是否存在。
20
21**起始API Level**
22
23API 12
24
25**变更发生版本**
26
27从OpenHarmony SDK 5.0.0.38开始。
28
29**变更的接口/组件**
30
31xml.XmlPullParser.parse
32
33**适配指导**
34
35如果xml原本就不会涉及实体引用事件，则无需适配，没有影响。
36
37如果xml涉及实体引用事件，以下面的例子说明变更前后差异，strXml存放待解析的xml，func为开发者自行准备的tokenValueCallbackFunction型回调函数，parse接口解析后得到的每个事件都会触发一次回调，并传入事件类型和对应的xml解析结果。
38```
39let strXml = '<?xml version="1.0" encoding="utf-8"?>\n' +
40                '<note>&amp;happy&amp;</note>';    // 此处第一个实体引用“&amp;”属于实体引用事件，而第二个实体引用“&amp;”由于紧随文本“happy”，“happy&amp;”作为整体属于文本事件。
41let textEncoder = new util.TextEncoder();
42let arrbuffer = textEncoder.encodeInto(strXml);
43let that = new xml.XmlPullParser(arrbuffer.buffer as object as ArrayBuffer, 'UTF-8');
44let str = "";
45function func(key: xml.EventType, value: xml.ParseInfo){
46  str += 'key:' + key +' value:' + value.getText() + '  ';
47  return true;
48}
49let options: xml.ParseOptions = {supportDoctype:true, ignoreNameSpace:true, tokenValueCallbackFunction:func}
50that.parse(options);
51console.log(str);
52```
53变更前
54```
55&amp;happy&amp;解析结果为：
56key为4（文本事件），value为&happy&
57```
58变更后
59```
60&amp;happy&amp;解析结果为2个：
61key为9（实体引用事件），value为&
62key为4（文本事件），value为happy&
63```
64
65开发者如果需要使用实体引用事件，需要至少使用API12，并在xml中严格遵从实体引用事件的格式，不在实体引用前加普通文本形成文本事件。
66开发者如果不需要使用实体引用事件，在xml中实体引用前面加普通文本形成文本事件就行，或者自行适配回调函数。
67
68实体引用事件说明：
69目前仅支持在XML中5个预定义的实体引用对应的实体引用事件：
70```
71&lt;    <  less than
72&gt;    >  greater than
73&amp;   &  ampersand
74&apos;  '  apostrophe
75&quot;  "  quotation mark
76```
77另外，实体引用前存在文本时会被一起视为文本事件，如：
78```
79<note>happy&lt;&gt;</note> 依次为：启动标签事件；文本事件；结束标签事件。
80<note>&lt;&gt;happy</note> 依次为：启动标签事件；实体引用事件；实体引用事件；文本事件；结束标签事件。
81```