1# Component ID 2 3**id** identifies a component uniquely within an application. With the provided APIs, you can obtain the attributes of or sending events to the component with the specified ID. 4 5> **NOTE** 6> 7> - The APIs of this module are supported since API version 8. Updates will be marked with a superscript to indicate their earliest API version. 8> 9> - If a component is assigned multiple **id** or **key** values, the last one set takes effect. 10 11## Attributes 12 13### id 14 15id(value: string): T 16 17Sets a unique identifier for this component, with uniqueness guaranteed by the user. 18 19**Widget capability**: This API can be used in ArkTS widgets since API version 9. 20 21**Atomic service API**: This API can be used in atomic services since API version 11. 22 23**System capability**: SystemCapability.ArkUI.ArkUI.Full 24 25**Parameters** 26 27| Name | Type | Mandatory| Description | 28| ------ | -------- | -----|---------------------- | 29| value | string | Yes | Unique identifier for the component, with uniqueness guaranteed by the user.<br>Default value: **''**<br>| 30 31### key<sup>12+</sup> 32 33key(value: string): T 34 35Sets a unique identifier for this component, with uniqueness guaranteed by the user. 36 37This API is used only for test purposes. When this attribute is used in conjunction with **id**, the last assigned value takes effect. You are advised to set only **id**. 38 39**System capability**: SystemCapability.ArkUI.ArkUI.Full 40 41**Parameters** 42 43| Name | Type | Mandatory| Description | 44| ------ | -------- | -----|---------------------- | 45| value | string | Yes| Unique identifier for the component, with uniqueness guaranteed by the user.<br>Default value: **''**<br>| 46 47 48## APIs 49 50 51### getInspectorByKey<sup>9+</sup> 52 53getInspectorByKey(id: string): string 54 55Obtains all attributes of the component with the specified ID, excluding the information about child components. 56 57This API is used only for test purposes. It is time consuming and not recommended. 58 59**Atomic service API**: This API can be used in atomic services since API version 11. 60 61**Parameters** 62 63| Name | Type | Mandatory | Description | 64| ---- | -------- | ---- | -------------| 65| id | string | Yes | ID of the component whose attributes are to be obtained.| 66 67**Return value** 68 69| Type | Description | 70| -------| -------------- | 71| string | JSON string of the component attribute list.<br>**NOTE**<br> The string includes the tag, ID, location (relative to the coordinates in the upper left corner of the window), and other information of the component used for testing.| 72 73### getInspectorTree<sup>9+</sup> 74 75getInspectorTree(): Object 76 77Obtains the component tree and component attributes. 78 79This API is used only for test purposes. It is time consuming and not recommended. 80 81**Atomic service API**: This API can be used in atomic services since API version 11. 82 83**Return value** 84 85| Type | Description | 86| ------ | --------------------------- | 87| Object | JSON object of the component tree and component attribute list.| 88 89### sendEventByKey<sup>9+</sup> 90 91sendEventByKey(id: string, action: number, params: string): boolean 92 93Sends an event to the component with the specified ID. 94 95This API is used only for test purposes. It is time consuming and not recommended. 96 97**Atomic service API**: This API can be used in atomic services since API version 11. 98 99**Parameters** 100 101| Name | Type | Mandatory | Description | 102| ------ | -------| ---- | -------------------------- | 103| id | string | Yes | ID of the component to which the event is to be sent. | 104| action | number | Yes | Type of the event to be sent. The options are as follows:<br>- **10**: click event.<br>- **11**: long-click event.| 105| params | string | Yes | Event parameters. If there is no parameter, pass an empty string **""**. | 106 107**Return value** 108 109| Type | Description | 110| -------- | --------------------------| 111| boolean | Returns **true** if the component with the specified ID is found; returns **false** otherwise.| 112 113### sendTouchEvent<sup>9+</sup> 114 115sendTouchEvent(event: TouchObject): boolean 116 117Sends a touch event. 118 119This API is used only for test purposes. It is time consuming and not recommended. 120 121**Atomic service API**: This API can be used in atomic services since API version 11. 122 123**Parameters** 124 125| Name | Type | Mandatory | Description | 126| ----- | ----------- | ---- | ------------------------------------------------------------ | 127| event | [TouchObject](ts-universal-events-touch.md#touchobject) | Yes | Location where a touch event is triggered. For details, see [TouchEvent](ts-universal-events-touch.md#touchevent).| 128 129**Return value** 130 131| Type | Description | 132| ------- | ---------------------------| 133| boolean | Returns **true** if the event is sent successfully; returns **false** otherwise.| 134 135### sendKeyEvent<sup>9+</sup> 136 137sendKeyEvent(event: KeyEvent): boolean 138 139Sends a key event. 140 141This API is used only for test purposes. It is time consuming and not recommended. 142 143**Atomic service API**: This API can be used in atomic services since API version 11. 144 145**Parameters** 146 147| Name | Type | Mandatory | Description | 148| ----- | -------- | ---- | ------------------------------------------------------------ | 149| event | [KeyEvent](ts-universal-events-key.md#keyevent) | Yes | Key event. For details, see [KeyEvent](ts-universal-events-key.md#keyevent).| 150 151**Return value** 152 153| Type | Description | 154| ------- | ------------------------------| 155| boolean | Returns **true** if the event is sent successfully; returns **false** otherwise.| 156 157### sendMouseEvent<sup>9+</sup> 158 159sendMouseEvent(event: MouseEvent): boolean 160 161Sends a mouse event. 162 163This API is used only for test purposes. It is time consuming and not recommended. 164 165**Atomic service API**: This API can be used in atomic services since API version 11. 166 167**Parameters** 168 169| Name | Type | Mandatory | Description | 170| ----- | ---------- | ---- | --------------------------------------- | 171| event | [MouseEvent](ts-universal-mouse-key.md#mouseevent) | Yes | Mouse event. For details, see [MouseEvent](ts-universal-mouse-key.md#mouseevent).| 172 173**Return value** 174 175| Type | Description | 176| ------- | ---------------------------------- | 177| boolean | Returns **true** if the event is sent successfully; returns **false** otherwise.| 178 179## Example 180 181This example demonstrates how to use the **id** APIs to obtain attributes of a component with the specified by ID and trigger events on that component. 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 // Obtain the coordinates of the rectangular area occupied by the component. 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] // Horizontal coordinate relative to the upper left corner of the component. 202 Utils.rect_top = JSON.parse('[' + rectInfo[0] + ']')[1] // Vertical coordinate relative to the upper left corner of the component. 203 Utils.rect_right = JSON.parse('[' + rectInfo[1] + ']')[0] // Horizontal coordinate relative to the lower right corner of the component. 204 Utils.rect_bottom = JSON.parse('[' + rectInfo[1] + ']')[1] // Vertical coordinate relative to the lower right corner of the component. 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, "") // Send a long-click event to the component whose ID is "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') // Obtain the coordinates of the rectangular area occupied by the component whose ID is "onTouch". 247 let touchPoint: TouchObject = { 248 id: 1, 249 type: TouchType.Down, 250 x: rect.left + (rect.right - rect.left) / 2, // X coordinate relative to the upper left corner of the component. 251 y: rect.top + (rect.bottom - rect.top) / 2, // Y coordinate relative to the upper left corner of the component. 252 screenX: rect.left + (rect.right - rect.left) / 2, // X coordinate relative to the upper left corner of the application window. This API is deprecated since API version 10. Use windowX instead. 253 screenY: rect.left + (rect.right - rect.left) / 2, // Y coordinate relative to the upper left corner of the application window. This API is deprecated since API version 10. Use windowY instead. 254 windowX: rect.left + (rect.right - rect.left) / 2, // X coordinate relative to the upper left corner of the application window. 255 windowY: rect.left + (rect.right - rect.left) / 2, // Y coordinate relative to the upper left corner of the application window. 256 displayX: rect.left + (rect.right - rect.left) / 2, // X coordinate relative to the upper left corner of the device screen. 257 displayY: rect.left + (rect.right - rect.left) / 2, // Y coordinate relative to the upper left corner of the device screen. 258 } 259 sendTouchEvent(touchPoint) // Send a touch event. 260 touchPoint.type = TouchType.Up 261 sendTouchEvent(touchPoint) // Send a touch event. 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') // Obtain the coordinates of the rectangular area occupied by the component whose ID is "onMouse". 273 let mouseEvent: MouseEvent = { 274 button: MouseButton.Left, 275 action: MouseAction.Press, 276 x: rect.left + (rect.right - rect.left) / 2, // X coordinate relative to the upper left corner of the component. 277 y: rect.top + (rect.bottom - rect.top) / 2, // Y coordinate relative to the upper left corner of the component. 278 screenX: rect.left + (rect.right - rect.left) / 2, // X coordinate relative to the upper left corner of the application window. This API is deprecated since API version 10. Use windowX instead. 279 screenY: rect.left + (rect.right - rect.left) / 2, // Y coordinate relative to the upper left corner of the application window. This API is deprecated since API version 10. Use windowY instead. 280 windowX: rect.left + (rect.right - rect.left) / 2, // X coordinate relative to the upper left corner of the application window. 281 windowY: rect.left + (rect.right - rect.left) / 2, // Y coordinate relative to the upper left corner of the application window. 282 displayX: rect.left + (rect.right - rect.left) / 2, // X coordinate relative to the upper left corner of the device screen. 283 displayY: rect.left + (rect.right - rect.left) / 2, // Y coordinate relative to the upper left corner of the device screen. 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) // Send a mouse event. 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) // Send a key event. 331 }, 2000) 332 }).id('onMouse') 333 334 Text(this.text).fontSize(25).padding(15) 335 } 336 .width('100%').height('100%') 337 } 338} 339``` 340