1# 组件标识 2 3id为组件的唯一标识，在整个应用内唯一。本模块提供组件标识相关接口，可以获取指定id组件的属性，也提供向指定id组件发送事件的功能。 4 5> **说明：** 6> 7> - 从API Version 8开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。 8> 9> - 若同一个组件设置了多个id或者key，最后设置的生效。 10 11## 属性 12 13### id 14 15id(value: string): T 16 17组件的唯一标识，唯一性由使用者保证。 18 19**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 20 21**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 22 23**系统能力：** SystemCapability.ArkUI.ArkUI.Full 24 25**参数：** 26 27| 名称 | 类型 | 必填 | 说明 | 28| ------ | -------- | -----|---------------------- | 29| value | string | 是 | 组件的唯一标识，唯一性由使用者保证。<br>默认值：''<br/> | 30 31### key<sup>12+</sup> 32 33key(value: string): T 34 35组件的唯一标识，唯一性由使用者保证。 36 37此接口仅用于对应用的测试。与id同时使用时，后赋值的属性会覆盖先赋值的属性，建议仅设置id。 38 39**系统能力：** SystemCapability.ArkUI.ArkUI.Full 40 41**参数：** 42 43| 名称 | 类型 | 必填 | 说明 | 44| ------ | -------- | -----|---------------------- | 45| value | string | 是 | 组件的唯一标识，唯一性由使用者保证。<br>默认值：''<br/> | 46 47 48## 接口 49 50 51### getInspectorByKey<sup>9+</sup> 52 53getInspectorByKey(id: string): string 54 55获取指定id的组件的所有属性，不包括子组件信息。 56 57此接口仅用于对应用的测试。由于耗时长，不建议使用。 58 59**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 60 61**参数:** 62 63| 参数名 | 类型 | 必填 | 说明 | 64| ---- | -------- | ---- | -------------| 65| id | string | 是 | 要获取属性的组件id。 | 66 67**返回值:** 68 69| 类型 | 说明 | 70| -------| -------------- | 71| string | 组件属性列表的JSON字符串。<br />**说明**：<br /> 字符串信息包含组件的tag、id、位置信息(相对于窗口左上角的坐标)以及用于测试检查的组件所包含的相关属性信息。 | 72 73### getInspectorTree<sup>9+</sup> 74 75getInspectorTree(): Object 76 77获取组件树及组件属性。 78 79此接口仅用于对应用的测试。由于耗时长，不建议使用。 80 81**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 82 83**返回值:** 84 85| 类型 | 说明 | 86| ------ | --------------------------- | 87| Object | 组件树及组件属性列表的JSON对象。 | 88 89### sendEventByKey<sup>9+</sup> 90 91sendEventByKey(id: string, action: number, params: string): boolean 92 93给指定id的组件发送事件。 94 95此接口仅用于对应用的测试。由于耗时长，不建议使用。 96 97**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 98 99**参数:** 100 101| 参数名 | 类型 | 必填 | 说明 | 102| ------ | -------| ---- | -------------------------- | 103| id | string | 是 | 要触发事件的组件的id。 | 104| action | number | 是 | 要触发的事件类型，目前支持取值：<br/>- 点击事件Click: 10<br/>- 长按事件LongClick: 11。 | 105| params | string | 是 | 事件参数，无参数传空字符串 ""。 | 106 107**返回值:** 108 109| 类型 | 说明 | 110| -------- | --------------------------| 111| boolean | 找不到指定id的组件时返回false，其余情况返回true。 | 112 113### sendTouchEvent<sup>9+</sup> 114 115sendTouchEvent(event: TouchObject): boolean 116 117发送触摸事件。 118 119此接口仅用于对应用的测试。由于耗时长，不建议使用。 120 121**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 122 123**参数:** 124 125| 参数名 | 类型 | 必填 | 说明 | 126| ----- | ----------- | ---- | ------------------------------------------------------------ | 127| event | [TouchObject](ts-universal-events-touch.md#touchobject对象说明) | 是 | 触发触摸事件的位置，event参数见[TouchEvent](ts-universal-events-touch.md#touchevent对象说明)中TouchObject的介绍。 | 128 129**返回值:** 130 131| 类型 | 说明 | 132| ------- | ---------------------------| 133| boolean | 事件发送失败时返回false，其余情况返回true。 | 134 135### sendKeyEvent<sup>9+</sup> 136 137sendKeyEvent(event: KeyEvent): boolean 138 139发送按键事件。 140 141此接口仅用于对应用的测试。由于耗时长，不建议使用。 142 143**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 144 145**参数:** 146 147| 参数名 | 类型 | 必填 | 说明 | 148| ----- | -------- | ---- | ------------------------------------------------------------ | 149| event | [KeyEvent](ts-universal-events-key.md#keyevent对象说明) | 是 | 按键事件，event参数见[KeyEvent](ts-universal-events-key.md#keyevent对象说明)介绍。 | 150 151**返回值:** 152 153| 类型 | 说明 | 154| ------- | ------------------------------| 155| boolean | 事件发送失败时时返回false，其余情况返回true。 | 156 157### sendMouseEvent<sup>9+</sup> 158 159sendMouseEvent(event: MouseEvent): boolean 160 161发送鼠标事件。 162 163此接口仅用于对应用的测试。由于耗时长，不建议使用。 164 165**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 166 167**参数：** 168 169| 参数名 | 类型 | 必填 | 说明 | 170| ----- | ---------- | ---- | --------------------------------------- | 171| event | [MouseEvent](ts-universal-mouse-key.md#mouseevent对象说明) | 是 | 鼠标事件，event参数见[MouseEvent](ts-universal-mouse-key.md#mouseevent对象说明)介绍。 | 172 173**返回值：** 174 175| 类型 | 说明 | 176| ------- | ---------------------------------- | 177| boolean | 事件发送失败时返回false，其余情况返回true。 | 178 179## 示例 180 181该示例主要展示如何通过组件标识接口，获取特定id组件的属性，以及如何向该id的组件触发事件。 182 183```ts 184// xxx.ets 185import { IntentionCode } from '@kit.InputKit' 186 187class Utils { 188 static rect_left: number 189 static rect_top: number 190 static rect_right: number 191 static rect_bottom: number 192 static rect_value: Record<string, number> 193 194 //获取组件所占矩形区域坐标 195 static getComponentRect(key:string):Record<string, number> { 196 let strJson = getInspectorByKey(key) 197 let obj:Record<string, string> = JSON.parse(strJson) 198 console.info("[getInspectorByKey] current component obj is: " + JSON.stringify(obj)) 199 let rectInfo:string[] = JSON.parse('[' + obj.$rect + ']') 200 console.info("[getInspectorByKey] rectInfo is: " + rectInfo) 201 Utils.rect_left = JSON.parse('[' + rectInfo[0] + ']')[0] // 相对于组件左上角的水平方向坐标 202 Utils.rect_top = JSON.parse('[' + rectInfo[0] + ']')[1] // 相对于组件左上角的垂直方向坐标 203 Utils.rect_right = JSON.parse('[' + rectInfo[1] + ']')[0] // 相对于组件右下角的水平方向坐标 204 Utils.rect_bottom = JSON.parse('[' + rectInfo[1] + ']')[1] // 相对于组件右下角的垂直方向坐标 205 return Utils.rect_value = { 206 "left": Utils.rect_left, "top": Utils.rect_top, "right": Utils.rect_right, "bottom": Utils.rect_bottom 207 } 208 } 209} 210 211@Entry 212@Component 213struct IdExample { 214 @State text: string = '' 215 216 build() { 217 Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) { 218 219 Button() { 220 Text('onKeyTab').fontSize(25).fontWeight(FontWeight.Bold) 221 }.margin({ top: 20 }).backgroundColor('#0D9FFB') 222 .onKeyEvent(() => { 223 this.text = "onKeyTab" 224 }) 225 226 Button() { 227 Text('click to start').fontSize(25).fontWeight(FontWeight.Bold) 228 }.margin({ top: 20 }) 229 .onClick(() => { 230 console.info(getInspectorByKey("click")) 231 console.info(JSON.stringify(getInspectorTree())) 232 this.text = "Button 'click to start' is clicked" 233 setTimeout(() => { 234 sendEventByKey("longClick", 11, "") // 向id为"longClick"的组件发送长按事件 235 }, 2000) 236 }).id('click') 237 238 Button() { 239 Text('longClick').fontSize(25).fontWeight(FontWeight.Bold) 240 }.margin({ top: 20 }).backgroundColor('#0D9FFB') 241 .gesture( 242 LongPressGesture().onActionEnd(() => { 243 console.info('long clicked') 244 this.text = "Button 'longClick' is longclicked" 245 setTimeout(() => { 246 let rect = Utils.getComponentRect('onTouch') // 获取id为"onTouch"组件的矩形区域坐标 247 let touchPoint: TouchObject = { 248 id: 1, 249 type: TouchType.Down, 250 x: rect.left + (rect.right - rect.left) / 2, // 相对于组件左上角的水平方向坐标 251 y: rect.top + (rect.bottom - rect.top) / 2, // 相对于组件左上角的垂直方向坐标 252 screenX: rect.left + (rect.right - rect.left) / 2, // 相对于应用窗口左上角的水平方向坐标，API10已废弃，采用windowX替代 253 screenY: rect.left + (rect.right - rect.left) / 2, // 相对于应用窗口左上角的垂直方向坐标，API10已废弃，采用windowY替代 254 windowX: rect.left + (rect.right - rect.left) / 2, // 相对于应用窗口左上角的水平方向坐标 255 windowY: rect.left + (rect.right - rect.left) / 2, // 相对于应用窗口左上角的垂直方向坐标 256 displayX: rect.left + (rect.right - rect.left) / 2, // 相对于设备屏幕左上角的水平方向坐标 257 displayY: rect.left + (rect.right - rect.left) / 2, // 相对于设备屏幕左上角的垂直方向坐标 258 } 259 sendTouchEvent(touchPoint) // 发送触摸事件 260 touchPoint.type = TouchType.Up 261 sendTouchEvent(touchPoint) // 发送触摸事件 262 }, 2000) 263 })).id('longClick') 264 265 Button() { 266 Text('onTouch').fontSize(25).fontWeight(FontWeight.Bold) 267 }.type(ButtonType.Capsule).margin({ top: 20 }) 268 .onClick(() => { 269 console.info('onTouch is clicked') 270 this.text = "Button 'onTouch' is clicked" 271 setTimeout(() => { 272 let rect = Utils.getComponentRect('onMouse') // 获取id为"onMouse"组件的矩形区域坐标 273 let mouseEvent: MouseEvent = { 274 button: MouseButton.Left, 275 action: MouseAction.Press, 276 x: rect.left + (rect.right - rect.left) / 2, // 相对于组件左上角的水平方向坐标 277 y: rect.top + (rect.bottom - rect.top) / 2, // 相对于组件左上角的垂直方向坐标 278 screenX: rect.left + (rect.right - rect.left) / 2, // 相对于应用窗口左上角的水平方向坐标，API10已废弃，采用windowX替代 279 screenY: rect.left + (rect.right - rect.left) / 2, // 相对于应用窗口左上角的垂直方向坐标，API10已废弃，采用windowY替代 280 windowX: rect.left + (rect.right - rect.left) / 2, // 相对于应用窗口左上角的水平方向坐标 281 windowY: rect.left + (rect.right - rect.left) / 2, // 相对于应用窗口左上角的垂直方向坐标 282 displayX: rect.left + (rect.right - rect.left) / 2, // 相对于设备屏幕左上角的水平方向坐标 283 displayY: rect.left + (rect.right - rect.left) / 2, // 相对于设备屏幕左上角的垂直方向坐标 284 stopPropagation: () => { 285 }, 286 timestamp: 1, 287 target: { 288 area: { 289 width: 1, 290 height: 1, 291 position: { 292 x: 1, 293 y: 1 294 }, 295 globalPosition: { 296 x: 1, 297 y: 1 298 } 299 } 300 }, 301 source: SourceType.Mouse, 302 pressure: 1, 303 tiltX: 1, 304 tiltY: 1, 305 sourceTool: SourceTool.Unknown 306 } 307 sendMouseEvent(mouseEvent) // 发送鼠标事件 308 }, 2000) 309 }).id('onTouch') 310 311 Button() { 312 Text('onMouse').fontSize(25).fontWeight(FontWeight.Bold) 313 }.margin({ top: 20 }).backgroundColor('#0D9FFB') 314 .onMouse(() => { 315 console.info('onMouse') 316 this.text = "Button 'onMouse' in onMouse" 317 setTimeout(() => { 318 let keyEvent: KeyEvent = { 319 type: KeyType.Down, 320 keyCode: 2049, 321 keyText: 'tab', 322 keySource: 4, 323 deviceId: 0, 324 metaKey: 0, 325 timestamp: 0, 326 stopPropagation: () => { 327 }, 328 intentionCode: IntentionCode.INTENTION_DOWN 329 } 330 sendKeyEvent(keyEvent) // 发送按键事件 331 }, 2000) 332 }).id('onMouse') 333 334 Text(this.text).fontSize(25).padding(15) 335 } 336 .width('100%').height('100%') 337 } 338} 339``` 340