Tastaturaktionen verarbeiten

Wenn der Nutzer den Fokus auf eine bearbeitbare Textkomponente wie TextField legt und das Gerät eine Hardwaretastatur hat, wird die gesamte Eingabe vom System verarbeitet. Sie können Tastenkombinationen festlegen, indem Sie Schlüsselereignisse verarbeiten.

Standard-Tastenkombinationen

Die folgenden Tastenkombinationen sind standardmäßig verfügbar.

Wichtige Ereignisse

In Compose können Sie für einzelne Tastenanschläge den onKeyEvent-Modifikator. Der Modifikator akzeptiert eine Lambda-Funktion, die Die geänderte Komponente empfängt ein Schlüsselereignis. Ein Schlüsselereignis wird als KeyEvent-Objekt beschrieben. Sie können die Informationen zu jedem Schlüsselereignis abrufen, indem Sie im Lambda auf das Objekt verweisen, das an den onKeyEvent-Modifikator übergeben wird.

Bei einem Tastenanschlag werden zwei Schlüsselereignisse gesendet. Eine wird ausgelöst, wenn der Nutzer die Taste drückt, die andere, wenn er sie loslässt. Sie können die beiden Schlüsselereignisse durch Verweisen auf das Attribut type des KeyEvent-Objekts.

Der Rückgabewert der Lambda-Funktion onKeyEvent gibt an, ob das Schlüsselereignis verarbeitet wird oder nicht. Geben Sie true zurück, wenn Ihre App das Tastenereignis verarbeitet. Dadurch wird die Weiterleitung des Ereignisses verhindert.

Das folgende Snippet zeigt, wie eine doSomething()-Funktion aufgerufen wird wenn der Nutzer den Schlüssel S für die Komponente Box loslässt:

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

Modifikatortasten

Ein KeyEvent-Objekt hat die folgenden Attribute, die angeben, ob Modifikatortasten gedrückt werden:

• isAltPressed
• isCtrlPressed
• isMetaPressed
• isShiftPressed

Beschreiben Sie genau, welche Schlüsselereignisse Ihre App verarbeitet. Im folgenden Snippet wird eine doSomething()-Funktion nur aufgerufen, wenn der Nutzer nur den S-Schlüssel loslässt. Wenn der Nutzer eine Modifikatortaste wie die Umschalttaste drückt, ruft die App die Funktion nicht auf.

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")
}

Klickereignisse für die Leertaste und die Eingabetaste

Auch die Leertaste und die Eingabetaste lösen Klickereignisse aus. Beispielsweise können Nutzer die Medienwiedergabe ein- oder ausschalten. mit der Leertaste oder der Eingabetaste indem Click-Events wie folgt verarbeitet werden:

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

Der clickable-Modifikator fängt Schlüsselereignisse ab und ruft den onClick()-Callback auf, wenn die Leertaste oder Die Eingabetaste wurde gedrückt. Deshalb heißt die Funktion togglePausePlay() indem Sie im Snippet die Leertaste oder die Eingabetaste drücken.

Nicht verwendete Schlüsselereignisse

Nicht verwendete Schlüsselereignisse werden von der Komponente weitergegeben an der das Ereignis in der einschließenden äußeren Komponente aufgetreten ist. Im folgenden Beispiel verbraucht die InnerComponent Schlüsselereignisse, wenn die Taste S losgelassen wird. Die OuterComponent erhält daher keine Schlüsselereignisse, die durch das Loslassen der Taste S ausgelöst werden. Daher wird die Funktion actionB() nie aufgerufen.

Andere wichtige Ereignisse auf InnerComponent, wie das Loslassen der Taste D, kann vom OuterComponent verarbeitet werden. Die Funktion actionC() wird aufgerufen, weil das Schlüsselereignis zum Loslassen der Taste D an die OuterComponent weitergegeben wird.

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
            }
        }
    )
}

onKeyPreviewEvent-Modifikator

In einigen Fällen möchten Sie ein Schlüsselereignis abfangen, bevor es die Standardaktion auslöst. Einem TextField werden normalerweise benutzerdefinierte Verknüpfungen hinzugefügt. Mit dem folgenden Snippet können Nutzer zur nächsten fokussierbaren Komponente wechseln, und drücken Sie die Tabulatortaste.

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
        }
    }
)

Standardmäßig fügt die Komponente „TextField“ ein Tabulatorzeichen jedes Mal, wenn ein Nutzer die Tabulatortaste drückt, selbst wenn das Schlüsselereignis mit dem onKeyEvent-Modifikator verarbeitet wird. Wenn Sie den Tastaturfokus verschieben möchten, ohne Tabulatorzeichen hinzuzufügen, das Schlüsselereignis zu verarbeiten, bevor die mit dem Schlüsselereignis verknüpften Aktionen ausgelöst werden (wie im Snippet). Das Lambda onKeyPreviewEvent() fängt das Schlüsselereignis ab, indem es true zurückgibt.

Die übergeordnete Komponente kann das Schlüsselereignis abfangen, das bei ihren untergeordneten Komponenten auftritt. Im folgenden Snippet wird die Funktion previewSKey() aufgerufen, wenn Nutzer die Taste S drücken, anstatt die Funktion actionForPreview() aufzurufen.

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")
  }
}

Das onPreviewKeyEvent()-Lambda für die Box-Komponente wird auch nicht ausgelöst, wenn Nutzer die Tabulatortaste drücken. Das Lambda onPreviewKeyEvent() wird zuerst für die übergeordnete Komponente aufgerufen, dann wird onPreviewKeyEvent() in der untergeordneten Komponente aufgerufen. Auf diese Weise können Sie Tastenkombinationen auf allen Bildschirmen implementieren.

Weitere Informationen

• Hilfe zu Tastenkombinationen: Systembildschirm, auf dem Nutzer nach den Tastenkombinationen suchen können, die Ihre App bietet.