• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# 触摸测试控制
2<!--Kit: ArkUI-->
3<!--Subsystem: ArkUI-->
4<!--Owner: @jiangtao92-->
5<!--Designer: @piggyguy-->
6<!--Tester: @songyanhong-->
7<!--Adviser: @HelloCrease-->
8
9设置组件的触摸测试类型。在ArkUI开发框架中，处理触屏事件时，会在触屏事件触发前进行按压点与组件区域的触摸测试，以收集需响应触屏事件的组件。基于测试结果，框架会分发相应的触屏事件。hitTestBehavior属性用于设置不同的触摸测试响应模式，影响触摸测试收集结果及后续触屏事件分发。具体影响参考[HitTestMode](./ts-appendix-enums.md#hittestmode9)枚举说明。
10
11>  **说明：**
12>  - 从API version 9开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。
13>  - 当Stack组件中有多个节点触摸区域重叠时，如两个节点，默认只会对显示在最上层的节点做触摸测试，若需要显示在下层的节点触发触摸测试，请给显示在上层的节点设置hitTestBehavior为HitTestMode.Transparent。
14
15## hitTestBehavior
16
17hitTestBehavior(value: HitTestMode): T
18
19设置组件的触摸测试类型。如果组件不设置hitTestBehavior，其默认触摸测试类型为HitTestMode.Default。
20
21**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。
22
23**系统能力：** SystemCapability.ArkUI.ArkUI.Full
24
25**参数：**
26
27| 参数名            | 类型     | 必填                             | 说明                               |
28| -------------------- | -------- | ---------------------------------------- | ---------------------------------------- |
29| value | [HitTestMode](./ts-appendix-enums.md#hittestmode9) | 是 | 设置当前组件的触摸测试类型。|
30
31**返回值：**
32
33| 类型 | 说明 |
34| -------- | -------- |
35| T | 返回当前组件。 |
36
37## 示例
38
39### 示例1（触摸测试类型为Block和Transparent的触摸测试效果）
40
41该示例通过设置不同的HitTestMode值演示了Block和Transparent的触摸测试效果。
42
43```ts
44// xxx.ets
45@Entry
46@Component
47struct HitTestBehaviorExample {
48  build() {
49    // outer stack
50    Stack() {
51      Button('outer button')
52        .onTouch((event) => {
53          console.info('outer button touched type: ' + (event as TouchEvent).type)
54        })
55      // inner stack
56      Stack() {
57        Button('inner button')
58          .onTouch((event) => {
59            console.info('inner button touched type: ' + (event as TouchEvent).type)
60          })
61      }
62      .width("100%").height("100%")
63      .hitTestBehavior(HitTestMode.Block)
64      .onTouch((event) => {
65        console.info('stack touched type: ' + (event as TouchEvent).type)
66      })
67
68      Text('Transparent')
69        .hitTestBehavior(HitTestMode.Transparent)
70        .width("100%").height("100%")
71        .onTouch((event) => {
72          console.info('text touched type: ' + (event as TouchEvent).type)
73        })
74    }.width(300).height(300)
75  }
76}
77```
78
79### 示例2（触摸测试类型为BLOCK_HIERARCHY时的触摸测试效果）
80
81该示例演示了设置触摸测试类型为BLOCK_HIERARCHY时的触摸测试效果。
82
83```ts
84// xxx.ets
85@Entry
86@Component
87struct BlockHierarchy {
88  build() {
89    // outer stack
90    Stack() {
91      Stack() {
92        Button('outer button')
93          .onTouch((event) => {
94            console.info('HitTestMode outer button touched type: ' + (event as TouchEvent).type);
95          })
96          .width(200)
97          .height(200)
98          .backgroundColor('#D5D5D5')
99        // inner stack
100        Stack() {
101          Button()
102            .id('button150')
103            .backgroundColor('#F7F7F7')
104            .width(150)
105            .height(150)
106            .onTouch((event) => {
107              console.info('HitTestMode button150 touched type: ' + (event as TouchEvent).type);
108            })
109            .hitTestBehavior(HitTestMode.Transparent)
110          Button()
111            .id('button100')
112            .backgroundColor('#707070')
113            .width(100)
114            .height(100)
115            .onTouch((event) => {
116              console.info('HitTestMode button100 touched type: ' + (event as TouchEvent).type);
117            })
118            .hitTestBehavior(HitTestMode.Transparent)
119          Button()
120            .id('button050')
121            .backgroundColor('#D5D5D5')
122            .width(50)
123            .height(50)
124            .onTouch((event) => {
125              console.info('HitTestMode button050 touched type: ' + (event as TouchEvent).type);
126            })
127            .hitTestBehavior(HitTestMode.Transparent)
128        }
129        .width("100%").height("100%")
130        // 设置触摸测试模式，自身和子节点响应触摸测试，阻止所有优先级较低的兄弟节点和父节点参与触摸测试
131        .hitTestBehavior(HitTestMode.BLOCK_HIERARCHY)
132        .onTouch((event) => {
133          console.info('HitTestMode stack touched type: ' + (event as TouchEvent).type);
134        })
135
136        Text('Transparent')
137          .hitTestBehavior(HitTestMode.Transparent)
138          .width("100%").height("100%")
139          .onTouch((event) => {
140            console.info('HitTestMode text touched type: ' + (event as TouchEvent).type);
141          })
142      }.width(300).height(300)
143      .borderWidth(2)
144      .onTouch((event) => {
145        console.info('HitTestMode father stack touched type: ' + (event as TouchEvent).type);
146      })
147    }.width(500).height(500)
148    .borderWidth(2)
149    .onTouch((event) => {
150      console.info('HitTestMode grandfather stack touched type: ' + (event as TouchEvent).type);
151    })
152  }
153}
154```
155
156### 示例3（触摸测试类型为BLOCK_DESCENDANTS时的触摸测试效果）
157
158该示例演示了设置触摸测试类型为BLOCK_DESCENDANTS时的触摸测试效果。
159
160```ts
161// xxx.ets
162@Entry
163@Component
164struct BlockDescendants {
165  build() {
166    // outer stack
167    Stack() {
168      Stack() {
169        Button('outer button')
170          .onTouch((event) => {
171            console.info('HitTestMode outer button touched type: ' + (event as TouchEvent).type);
172          })
173          .width(200)
174          .height(200)
175          .backgroundColor('#D5D5D5')
176        // inner stack
177        Stack() {
178          Button('inner button')
179            .width(100)
180            .height(100)
181            .onTouch((event) => {
182              console.info('HitTestMode inner button touched type: ' + (event as TouchEvent).type);
183            })
184        }
185        .width("100%").height("100%")
186        // 设置触摸测试模式，自身不响应触摸测试，并且所有的后代（孩子，孙子等）也不响应触摸测试
187        .hitTestBehavior(HitTestMode.BLOCK_DESCENDANTS)
188        .onTouch((event) => {
189          console.info('HitTestMode stack touched type: ' + (event as TouchEvent).type);
190        })
191
192        Text('Transparent')
193          .hitTestBehavior(HitTestMode.Transparent)
194          .width("100%").height("100%")
195          .onTouch((event) => {
196            console.info('HitTestMode text touched type: ' + (event as TouchEvent).type);
197          })
198      }.width(300).height(300)
199      .borderWidth(2)
200      .onTouch((event) => {
201        console.info('HitTestMode father stack touched type: ' + (event as TouchEvent).type);
202      })
203    }.width(500).height(500)
204    .borderWidth(2)
205    .onTouch((event) => {
206      console.info('HitTestMode grandfather stack touched type: ' + (event as TouchEvent).type);
207    })
208  }
209}
210```