Gérer les actions du clavier

Lorsque l'utilisateur sélectionne un composant texte modifiable, comme TextField, et l'appareil dispose d'un clavier matériel connecté, toutes les entrées sont gérées par le système. Vous pouvez fournir des raccourcis clavier en gérant les événements de touche.

Raccourcis clavier par défaut

Les raccourcis clavier suivants sont prêts à l'emploi.

Événements clés

Dans Compose, vous pouvez gérer une frappe individuelle avec le modificateur onKeyEvent. Le modificateur accepte un lambda appelé lorsque le composant modifié reçoit un événement de touche. Un événement clé est décrit comme un objet KeyEvent. Vous pouvez obtenir les informations de chaque événement de touche en vous référant à l'objet dans le lambda transmis au modificateur onKeyEvent.

Une frappe envoie deux événements de touche. L'un est déclenché lorsque l'utilisateur appuie sur la touche, et l'autre lorsque la touche est relâchée. Vous pouvez distinguer les deux événements clés en vous référant à l'attribut type de l'objet KeyEvent.

La valeur renvoyée par le lambda onKeyEvent indique si l'événement clé est géré ou non. Renvoyez true si votre application gère l'événement clé. ce qui arrête la propagation de l'événement.

L'extrait de code suivant montre comment appeler une fonction doSomething() Lorsque l'utilisateur libère la clé S sur le composant Box:

Box(
    modifier = Modifier.focusable().onKeyEvent {
        if(
            it.type == KeyEventType.KeyUp &&
            it.key == Key.S
        ) {
            doSomething()
            true
        } else {
            false
        }
    }
)  {
    Text("Press S key")
}

Touches de modification

Un objet KeyEvent possède les attributs suivants, qui indiquent l'appui sur les touches de modification:

• isAltPressed
• isCtrlPressed
• isMetaPressed
• isShiftPressed

Décrivez précisément les événements clés gérés par votre application. L'extrait de code suivant appelle une fonction doSomething() uniquement si l'utilisateur libère uniquement la clé S. Si l'utilisateur appuie sur une touche modificateur, telle que la touche Maj, l'application n'appelle pas la fonction.

Box(
  modifier = Modifier.focusable().onKeyEvent{
     if(
       it.type == KeyEventType.KeyUp &&
       it.key == Key.S &&
       !it.isAltPressed &&
       !it.isCtrlPressed &&
       !it.isMetaPressed &&
       !it.isShiftPressed
     ) {
       doSomething()
       true
     } else {
       false
     }
  }
)  {
    Text("Press S key with a modifier key")
}

Barre d'espace et Entrée des événements de clic clé

Les touches Barre d'espace et Entrée déclenchent également des événements de clic. Par exemple, les utilisateurs peuvent lire ou mettre en pause la lecture des contenus multimédias. avec la barre d'espace ou la touche Entrée. en gérant les événements de clic comme suit:

MoviePlayer(
   modifier = Modifier.clickable { togglePausePlay() }
)

Le modificateur clickable intercepte les événements de touche. et appelle le rappel onClick() lorsque la barre d'espace ou la touche Entrée est enfoncée. C'est pourquoi la fonction togglePausePlay() est appelée en appuyant sur la barre d'espace ou sur la touche Entrée dans l'extrait.

Événements clés non consommés

Les événements de touche non consommés sont propagés du composant où l'événement s'est produit au composant externe englobant. Dans l'exemple ci-dessous, InnerComponent utilise des événements clés lorsque la touche S est relâchée, Ainsi, OuterComponent ne reçoit aucun événement clé déclenché. en relâchant la touche S. C'est pourquoi la fonction actionB() n'est jamais appelée.

Autres événements clés sur InnerComponent, tels que la libération de la touche D peuvent être gérées par OuterComponent. La fonction actionC() est appelée, car l'événement clé pour la libération de la clé D est propagée à OuterComponent.

OuterComponent(
    modifier = Modifier.onKeyEvent {
        when {
           it.type == KeyEventType.KeyUp && it.key == Key.S -> {
               actionB() // This function is never called.
               true
           }
           it.type == KeyEventType.KeyUp && it.key == Key.D -> {
               actionC()
               true
           }
           else -> false
        }
    }
) {
    InnerComponent(
        modifier = Modifier.onKeyEvent {
            if(it.type == KeyEventType.KeyUp && it.key == Key.S) {
                actionA()
                true
            } else {
                false
            }
        }
    )
}

Modificateur onKeyPreviewEvent

Dans certains cas d'utilisation, vous souhaitez intercepter un événement clé avant de déclencher l'action par défaut. L'ajout de raccourcis personnalisés à un TextField est un exemple typique. L'extrait de code suivant permet aux utilisateurs de passer au composant suivant pouvant recevoir la sélection en appuyant sur la touche Tabulation.

val focusManager = LocalFocusManager.current
var textFieldValue by remember { mutableStateOf(TextFieldValue()) }

TextField(
    textFieldValue,
    onValueChange = {
        textFieldValue = it
    },
    modifier = Modifier.onPreviewKeyEvent {
        if (it.type == KeyEventType.KeyUp && it.key == Key.Tab) {
            focusManager.moveFocus(FocusDirection.Next)
            true
        } else {
            false
        }
    }
)

Par défaut, le composant TextField ajoute un caractère de tabulation chaque fois que les utilisateurs appuient sur la touche Tabulation, même si l'événement de touche est géré avec le modificateur onKeyEvent. Pour déplacer le curseur au clavier sans ajouter de caractères de tabulation, gérer l'événement clé avant de déclencher les actions associées à l'événement clé, comme dans l'extrait. Le lambda onKeyPreviewEvent() intercepte l'événement clé. en renvoyant true.

Le composant parent peut intercepter l'événement clé qui se produit sur ses enfants. Dans l'extrait de code suivant, la fonction previewSKey() est appelée lorsque les utilisateurs appuient sur la touche S, au lieu d'appeler la fonction actionForPreview().

Column(
  modifier = Modifier.onPreviewKeyEvent{
    if(it.key == Key.S){
      previewSKey()
      true
    }else{
      false
    }
  }
) {
  Box(
    modifier = Modifier
        .focusable()
        .onPreviewKeyEvent {
            actionForPreview(it)
            false
        }
        .onKeyEvent {
            actionForKeyEvent(it)
            true
        }
  ) {
    Text("Press any key")
  }
}

Le lambda onPreviewKeyEvent() pour le composant Box n'est pas déclenché lorsque les utilisateurs appuient sur la touche Tabulation. Le lambda onPreviewKeyEvent() est d'abord appelé sur le composant parent, puis onPreviewKeyEvent() dans le composant enfant. Vous pouvez implémenter des raccourcis clavier à l'échelle de l'écran en utilisant ce comportement.

Ressources supplémentaires

• Outil d'aide pour les raccourcis clavier : écran système qui permet aux utilisateurs de rechercher les raccourcis clavier proposés par votre application.