1# 自定义事件分发
2
3ArkUI在处理触屏事件时，会在触屏事件触发前进行按压点和组件区域的触摸测试，来收集需要响应触屏事件的组件，再基于触摸测试结果分发相应的触屏事件。在父节点，开发者可以通过onChildTouchTest决定如何让子节点去做触摸测试，影响子组件的触摸测试，最终影响后续的触屏事件分发，具体影响参考[TouchTestStrategy](#touchteststrategy枚举说明)枚举说明。
4
5>  **说明：**
6>
7>  - 从API Version 11开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。
8>
9>  - onClick以及旋转、捏合手势经过自定义事件分发之后可能会因为触摸热区没有命中导致事件不响应。
10
11## onChildTouchTest
12
13onChildTouchTest(event: (value: Array<TouchTestInfo>) => TouchResult): T
14
15当前组件可通过设置回调来自定义子节点如何去做触摸测试。
16
17**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。
18
19**系统能力：** SystemCapability.ArkUI.ArkUI.Full
20
21**参数：**
22
23| 参数名 | 类型                                       | 必填 | 说明                   |
24| ------ | ------------------------------------------ | ---- | ---------------------- |
25| value  | Array<[TouchTestInfo>](#touchtestinfo) | 是   | 包含子节点信息的数组。 |
26
27**返回值：**
28
29| 类型 | 说明 |
30| -------- | -------- |
31| T | 返回当前组件。 |
32
33>**说明：**
34>
35>子节点信息数组中只包含命名节点的信息，即开发者通过id属性设置了id的节点。
36
37## TouchTestInfo
38
39当前按压点所在组件的坐标系、id和尺寸相关信息。
40
41**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。
42
43**系统能力：** SystemCapability.ArkUI.ArkUI.Full
44
45| 名称          | 类型   | 描述                                       |
46| ------------- | ------ | ---------------------------------------- |
47| windowX | number | 按压点相对于窗口左上角的x轴坐标。 |
48| windowY   | number |按压点相对于窗口左上角的y轴坐标。|
49| parentX   | number |按压点相对于父组件左上角的x轴坐标。  |
50| parentY   | number |按压点相对于父组件左上角的y轴坐标。  |
51| x   | number | 按压点相对于子组件左上角的x轴坐标。 |
52| y   | number | 按压点相对于子组件左上角的y轴坐标。 |
53| rect   | [RectResult](ts-types.md#rectresult10) |子组件的大小。  |
54| [id](ts-universal-attributes-component-id.md)   | string | 通过id属性设置的组件id。 |
55
56## TouchResult
57
58自定义事件分发结果，开发者通过返回结果来影响事件分发。
59
60**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。
61
62**系统能力：** SystemCapability.ArkUI.ArkUI.Full
63
64| 名称      | 类型                                     | 必填   | 描述                                |
65| --------- | --------- | ---- |--------------------------------------- |
66| strategy  | [TouchTestStrategy](#touchteststrategy枚举说明) | 是    | 事件派发策略。                     |
67| id  | string | 否    | 通过id属性设置的组件id。<br>当strategy为TouchTestStrategy.DEFAULT时，id是可选的；当strategy是TouchTestStrategy.FORWARD_COMPETITION或TouchTestStrategy.FORWARD时，id是必需的（如果没有返回id，则当成TouchTestStrategy.DEFAULT处理）。 |
68
69## TouchTestStrategy枚举说明
70
71事件派发策略。
72
73**卡片能力：** 从API version 11开始，该接口支持在ArkTS卡片中使用。
74
75**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。
76
77**系统能力：** SystemCapability.ArkUI.ArkUI.Full
78
79| 名称          | 描述                                       |
80| ------------| ----------------------------------------- |
81| DEFAULT     | 自定义分发不产生影响，系统按当前节点命中状态分发事件。 |
82| FORWARD_COMPETITION       | 应用指定分发事件到某个子节点，其他兄弟节点是否分发事件交由系统决定。 |
83| FORWARD | 应用指定分发事件到某个子节点，系统不再处理分发事件到其他兄弟节点。 |
84
85## 示例
86
87### 示例1（设置事件派发策略为FORWARD_COMPETITION）
88
89该示例点击List下方空白区域后拖动，能够拖动List滑动。点击Button按钮，Button会响应onClick事件。
90
91```ts
92// xxx.ets
93import { promptAction } from '@kit.ArkUI';
94
95@Entry
96@Component
97struct ListExample {
98  private arr: number[] = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12]
99  @State text: string = 'Button'
100
101  build() {
102    Column() {
103      List({ space: 12, initialIndex: 0 }) {
104        ForEach(this.arr, (item: number) => {
105          ListItem() {
106            Text('Item ' + item)
107              .width('100%')
108              .height(56)
109              .fontSize(16)
110              .textAlign(TextAlign.Start)
111          }.borderRadius(24)
112          .backgroundColor(Color.White)
113          .padding({ left: 12, right: 12 })
114        }, (item: string) => item)
115      }
116      .listDirection(Axis.Vertical)
117      .scrollBar(BarState.Off)
118      .edgeEffect(EdgeEffect.Spring)
119      .onScrollIndex((start: number, end: number) => {
120        console.info('first' + start)
121        console.info('last' + end)
122      })
123      .onDidScroll((scrollOffset: number, scrollState: ScrollState) => {
124        console.info(`onScroll scrollState = ScrollState` + scrollState + `, scrollOffset = ` + scrollOffset)
125      })
126      .width('100%')
127      .height('65%')
128      .id('MyList')
129
130      Button(this.text)
131        .width(312)
132        .height(40)
133        .id('Mybutton')
134        .fontSize(16)
135        .fontWeight(FontWeight.Medium)
136        .margin({ top: 80 })
137        .onClick(() => {
138          this.text = 'click the button'
139          promptAction.showToast({ message: 'you click the button.', duration: 3000 })
140        })
141    }
142    .width('100%')
143    .height('100%')
144    .backgroundColor(0xF1F3F5)
145    .justifyContent(FlexAlign.End)
146    .padding({ left: 12, right: 12, bottom: 24 })
147    .onChildTouchTest((touchinfo) => {
148      for (let info of touchinfo) {
149        if (info.id == 'MyList') {
150          return { id: info.id, strategy: TouchTestStrategy.FORWARD_COMPETITION }
151        }
152      }
153      return { strategy: TouchTestStrategy.DEFAULT }
154    })
155  }
156}
157```
158
159![onchildtouchtest](figures/on-child-touch-test-competition.gif)
160
161### 示例2（设置事件派发策略为FORWARD）
162
163点击List下方空白区域后拖动，能够拖动List滑动。点击Button按钮，Button不会响应onClick事件。
164
165```ts
166// xxx.ets
167import { promptAction } from '@kit.ArkUI';
168
169@Entry
170@Component
171struct ListExample {
172  private arr: number[] = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12]
173  @State text: string = 'Button'
174
175  build() {
176    Column() {
177      List({ space: 12, initialIndex: 0 }) {
178        ForEach(this.arr, (item: number) => {
179          ListItem() {
180            Text('Item ' + item)
181              .width('100%')
182              .height(56)
183              .fontSize(16)
184              .textAlign(TextAlign.Start)
185          }.borderRadius(24)
186          .backgroundColor(Color.White)
187          .padding({ left: 12, right: 12 })
188        }, (item: string) => item)
189      }
190      .listDirection(Axis.Vertical)
191      .scrollBar(BarState.Off)
192      .edgeEffect(EdgeEffect.Spring)
193      .onScrollIndex((start: number, end: number) => {
194        console.info('first' + start)
195        console.info('last' + end)
196      })
197      .onDidScroll((scrollOffset: number, scrollState: ScrollState) => {
198        console.info(`onScroll scrollState = ScrollState` + scrollState + `, scrollOffset = ` + scrollOffset)
199      })
200      .width('100%')
201      .height('65%')
202      .id('MyList')
203
204      Button(this.text)
205        .width(312)
206        .height(40)
207        .id('Mybutton')
208        .fontSize(16)
209        .fontWeight(FontWeight.Medium)
210        .margin({ top: 80 })
211        .onClick(() => {
212          this.text = 'click the button'
213          promptAction.showToast({ message: 'you click the button.', duration: 3000 })
214        })
215    }
216    .width('100%')
217    .height('100%')
218    .backgroundColor(0xF1F3F5)
219    .justifyContent(FlexAlign.End)
220    .padding({ left: 12, right: 12, bottom: 24 })
221    .onChildTouchTest((touchinfo) => {
222      for (let info of touchinfo) {
223        if (info.id == 'MyList') {
224          return { id: info.id, strategy: TouchTestStrategy.FORWARD }
225        }
226      }
227      return { strategy: TouchTestStrategy.DEFAULT }
228    })
229  }
230}
231```
232
233![onchildtouchtest](figures/on-child-touch-test-forward.gif)
234
235### 示例3（设置事件派发策略为DEFAULT）
236
237点击List下方空白区域后拖动，List不会滑动。点击Button按钮，Button会响应onClick事件。
238
239```ts
240// xxx.ets
241import { promptAction } from '@kit.ArkUI';
242
243@Entry
244@Component
245struct ListExample {
246  private arr: number[] = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12]
247  @State text: string = 'Button'
248
249  build() {
250    Column() {
251      List({ space: 12, initialIndex: 0 }) {
252        ForEach(this.arr, (item: number) => {
253          ListItem() {
254            Text('Item ' + item)
255              .width('100%')
256              .height(56)
257              .fontSize(16)
258              .textAlign(TextAlign.Start)
259          }.borderRadius(24)
260          .backgroundColor(Color.White)
261          .padding({ left: 12, right: 12 })
262        }, (item: string) => item)
263      }
264      .listDirection(Axis.Vertical)
265      .scrollBar(BarState.Off)
266      .edgeEffect(EdgeEffect.Spring)
267      .onScrollIndex((start: number, end: number) => {
268        console.info('first' + start)
269        console.info('last' + end)
270      })
271      .onDidScroll((scrollOffset: number, scrollState: ScrollState) => {
272        console.info(`onScroll scrollState = ScrollState` + scrollState + `, scrollOffset = ` + scrollOffset)
273      })
274      .width('100%')
275      .height('65%')
276      .id('MyList')
277
278      Button(this.text)
279        .width(312)
280        .height(40)
281        .id('Mybutton')
282        .fontSize(16)
283        .fontWeight(FontWeight.Medium)
284        .margin({ top: 80 })
285        .onClick(() => {
286          this.text = 'click the button'
287          promptAction.showToast({ message: 'you click the button.', duration: 3000 })
288        })
289    }
290    .width('100%')
291    .height('100%')
292    .backgroundColor(0xF1F3F5)
293    .justifyContent(FlexAlign.End)
294    .padding({ left: 12, right: 12, bottom: 24 })
295    .onChildTouchTest((touchinfo) => {
296      return { strategy: TouchTestStrategy.DEFAULT }
297    })
298  }
299}
300```
301
302![onchildtouchtest](figures/on-child-touch-test-default.gif)