Aller au contenu

Tâche Click In Element

Résumé

  • Nom interne : ClickInElement
  • Catégorie : Android UI
  • Objectif : Cliquer (ou appui long) sur le premier élément correspondant à un sélecteur, en attendant éventuellement son apparition.
  • Type de tâche : Normal

Compatibilité

  • Version AndroMate minimale : 1.1.0
  • Version AndroMate maximale : 1.1.0
  • Android minimum : Android 13 (API 33)
  • Android testé maximum : Android 16 (API 36)

  • Fabricants supportés :

    • Samsung (One UI 6.x / 7.x / 8.x)
    • Autres fabricants - pas encore supportés (Xiaomi HyperOS et Google Pixel en cours d'adaptation)
    • Permissions requises :
    • ACCESSIBILITY_SERVICE

Description détaillée

La tâche Click In Element (anciennement nommée "Click In Text" - renommée car elle correspond à bien plus qu'un simple texte) recherche dans l'arbre d'accessibilité le premier élément correspondant à un sélecteur et clique dessus. Définir ClickInElement_timeout_ms au-dessus de 0 fait sonder la tâche toutes les 300ms jusqu'à ce que l'élément apparaisse (ou que le délai expire) avant de cliquer - le même comportement d'attente que Wait For Element, suivi d'un clic.

Seuls les éléments considérés "cliquables" par l'arbre d'accessibilité sont pris en compte (le parent cliquable d'un nœud non-cliquable est utilisé à la place, s'il existe) - cela reflète la manière dont un vrai tap serait acheminé. Si votre cible est un champ éditable plutôt qu'un élément à cliquer, utilisez plutôt Fill Text, qui ne requiert pas la cliquabilité.

Paramètres d'entrée

Paramètre Type Requis Valeurs possibles Compatibilité Android Compatibilité AndroMate Défaut
ClickInElement_textSelector Enum / String (résolvable) Oui text, contentDescription, tooltipText, resourceId, className, hintText, anyOf Android 13 (API 33) -> Android 16 (API 36) 1.1.0 -> 1.1.0 ""
ClickInElement_CompareType Enum / String (résolvable) Oui exactText, startWith, contain Android 13 (API 33) -> Android 16 (API 36) 1.1.0 -> 1.1.0 ""
ClickInElement_Index Entier (résolvable) Non Index base 0 parmi les correspondances Android 13 (API 33) -> Android 16 (API 36) 1.1.0 -> 1.1.0 0
ClickInElement_text String (résolvable) Oui Le texte/description/id à faire correspondre Android 13 (API 33) -> Android 16 (API 36) 1.1.0 -> 1.1.0 ""
ClickInElement_timeout_ms Entier (résolvable) Non ≥ 0 millisecondes Android 13 (API 33) -> Android 16 (API 36) 1.1.0 -> 1.1.0 0 (pas d'attente)
ClickInElement_clickType Enum / String (résolvable) Non click, longClick Android 13 (API 33) -> Android 16 (API 36) 1.1.0 -> 1.1.0 click

Paramètres de sortie

Cette tâche ne produit aucune variable de sortie. Elle retourne un VoidResult en cas de succès.

Exceptions

Code Nom de l'exception Description
SCREEN-AUTOMATOR-ERROR-003 Invalid Action Type ClickInElement_clickType n'est ni click ni longClick.
SCREEN-AUTOMATOR-ERROR-006 Unsupported Text Selector ClickInElement_textSelector n'est pas une valeur de sélecteur reconnue.
SCREEN-AUTOMATOR-ERROR-010 Screen Automator Service Not Connected Le service d'accessibilité AndroMate n'est pas activé/connecté.
SCREEN-AUTOMATOR-ERROR-011 Screen Automator Action Failed Aucun élément cliquable correspondant trouvé avant expiration du délai, ou l'action de clic a été refusée - inclut le sélecteur/compare/index/texte/timeout résolus dans le détail de l'erreur.

Diagramme d'exécution

flowchart TD
    Start([ClickInElement]) --> CheckConnected{Service d'accessibilité\nconnecté ?}
    CheckConnected -->|Non| E1[SCREEN-AUTOMATOR-ERROR-010\nSERVICE_NOT_CONNECTED]
    CheckConnected -->|Oui| Loop[Recherche dans l'arbre\nd'accessibilité]
    Loop --> Found{Correspondance\ntrouvée ?}
    Found -->|Oui| Click[performAction\nCLICK ou LONG_CLICK]
    Found -->|Non| Timeout{Temps écoulé ≥\ntimeout_ms ?}
    Timeout -->|Non| Sleep[attendre 300ms] --> Loop
    Timeout -->|Oui| E2[SCREEN-AUTOMATOR-ERROR-011\nACTION_FAILED]
    Click --> Success([VoidResult])

    E1 --> Error([Exception])
    E2 --> Error

    style Start fill:#e3f2fd
    style Success fill:#c8e6c9
    style Error fill:#ffcdd2
    style Click fill:#fff9c4
    style Loop fill:#f3e5f5

Fonctionnement :

  1. Vérifier la connexion : échoue immédiatement avec SERVICE_NOT_CONNECTED si le service d'accessibilité n'est pas activé.
  2. Rechercher : cherche un nœud cliquable dont la valeur du sélecteur correspond à ClickInElement_text selon ClickInElement_CompareType, à l'index ClickInElement_Index parmi les correspondances.
  3. Attendre si besoin : si non trouvé et timeout_ms > 0, attend 300ms et recherche à nouveau, jusqu'à trouver ou expiration du délai.
  4. Agir : clique (ou appui long) sur la correspondance ; si jamais trouvé à temps, lève ACTION_FAILED.

Exemples de code

Exemple 1 - Cliquer un bouton par son texte

{
  "ClickInElement": [
    {
      "id": "1",
      "title": "Cliquer Allow",
      "ClickInElement_textSelector": "text",
      "ClickInElement_CompareType": "exactText",
      "ClickInElement_Index": 0,
      "ClickInElement_text": "Allow",
      "ClickInElement_timeout_ms": 0,
      "ClickInElement_clickType": "click"
    }
  ]
}

Exemple 2 - Attendre jusqu'à 5s un bouton puis appui long

{
  "ClickInElement": [
    {
      "id": "2",
      "title": "Appui long icône Paramètres",
      "ClickInElement_textSelector": "contentDescription",
      "ClickInElement_CompareType": "contain",
      "ClickInElement_Index": 0,
      "ClickInElement_text": "Settings",
      "ClickInElement_timeout_ms": 5000,
      "ClickInElement_clickType": "longClick"
    }
  ]
}

Détails des paramètres d'entrée

1. Paramètre d'entrée : ClickInElement_textSelector

D'où provient le texte comparé.

Valeur Description
text Le texte visible de l'élément.
contentDescription Sa description d'accessibilité.
tooltipText Son texte d'infobulle (s'il existe).
resourceId Son nom de ressource d'ID de vue Android complet (ex. com.app:id/button_ok).
className Son nom de classe de vue Android (ex. android.widget.Button).
hintText Son texte d'indice/placeholder (utile pour les champs éditables vides).
anyOf Correspond si l'un de text, contentDescription ou tooltipText correspond - pas resourceId/className, qui décrivent la structure plutôt que le texte affiché/prononcé.

Exemple

"ClickInElement_textSelector": "text"

2. Paramètre d'entrée : ClickInElement_CompareType

Comment la comparaison est effectuée (insensible à la casse).

Valeur Description
exactText Correspondance exacte.
startWith La valeur de l'élément commence par ClickInElement_text.
contain La valeur de l'élément contient ClickInElement_text.

Exemple

"ClickInElement_CompareType": "contain"

3. Paramètre d'entrée : ClickInElement_Index

Si plusieurs éléments correspondent, sélectionne le n-ième (base 0). Hors limites, se replie sur la première correspondance.

Exemple

"ClickInElement_Index": 0

4. Paramètre d'entrée : ClickInElement_text

La valeur à faire correspondre, selon ClickInElement_textSelector/ClickInElement_CompareType.

Exemple

"ClickInElement_text": "Allow"

5. Paramètre d'entrée : ClickInElement_timeout_ms

Durée de recherche avant abandon. 0 (défaut) vérifie une seule fois, immédiatement.

Exemple

"ClickInElement_timeout_ms": 5000

6. Paramètre d'entrée : ClickInElement_clickType

Effectuer un clic normal ou un appui long sur l'élément trouvé.

Valeur Description
click AccessibilityNodeInfo.ACTION_CLICK (défaut).
longClick AccessibilityNodeInfo.ACTION_LONG_CLICK.

Exemple

"ClickInElement_clickType": "longClick"

Détails des paramètres de sortie

Cette tâche n'a pas de paramètres de sortie.

Exemple JSON complet

{
  "ClickInElement": [
    {
      "id": "1",
      "title": "Cliquer OK",
      "ClickInElement_textSelector": "text",
      "ClickInElement_CompareType": "exactText",
      "ClickInElement_Index": 0,
      "ClickInElement_text": "OK",
      "ClickInElement_timeout_ms": 3000,
      "ClickInElement_clickType": "click"
    }
  ]
}