Tastaturaktionen verarbeiten

Wenn der Nutzer den Fokus auf eine bearbeitbare Textkomponente wie ein TextField legt und ein Hardware-Keyboard an das Gerät angeschlossen ist, wird die gesamte Eingabe vom System verarbeitet. Sie können Tastenkombinationen bereitstellen, indem Sie Tastenereignisse verarbeiten.

Standardtastenkombinationen

Die folgenden Tastenkombinationen sind sofort verfügbar.

Tastenkombination Aktion Composables, die die Tastenkombination unterstützen
Umschalttaste+Strg+Linkspfeil/Rechtspfeil Text bis zum Anfang/Ende des Wortes auswählen BasicTextField, TextField
Umschalttaste+Strg+Pfeil nach oben/Pfeil nach unten Text bis zum Anfang/Ende des Absatzes auswählen BasicTextField, TextField
Umschalttaste+Alt+Pfeil nach oben/Pfeil nach unten oder Umschalttaste+Meta+Linkspfeil/Rechtspfeil Text bis zum Anfang/Ende des Textes auswählen BasicTextField, TextField
Umschalttaste+Linkspfeil/Rechtspfeil Zeichen auswählen BasicTextField, TextField
Strg+A Alle auswählen BasicTextField, TextField
Strg+C/Strg+X/Strg+V Kopieren/Ausschneiden/Einfügen BasicTextField, TextField
Strg+Z/Strg+Umschalttaste+Z Rückgängig/Wiederholen BasicTextField, TextField
Bild ab/Bild auf Scrollen LazyColumn, der Modifikator verticalScroll, der Modifikator scrollable

Tastenereignisse

In Compose können Sie einen einzelnen Tastendruck mit dem onKeyEvent Modifikator verarbeiten. Der Modifikator akzeptiert eine Lambda-Funktion, die aufgerufen wird, wenn die geänderte Komponente ein Tastenereignis empfängt. Ein Tastenereignis wird als KeyEvent-Objekt beschrieben. Sie können die Informationen zu jedem Tastenereignis abrufen, indem Sie auf das Objekt in der Lambda-Funktion verweisen, die an den Modifikator onKeyEvent übergeben wird.

Ein Tastendruck sendet zwei Tastenereignisse. Eines wird ausgelöst, wenn der Nutzer die Taste drückt, das andere, wenn die Taste losgelassen wird. Sie können die beiden Tastenereignisse unterscheiden, indem Sie auf das type Attribut des KeyEvent Objekts verweisen.

Der Rückgabewert der onKeyEvent-Lambda-Funktion gibt an, ob das Tastenereignis verarbeitet wird oder nicht. Geben Sie true zurück, wenn Ihre App das Tastenereignis verarbeitet, wodurch die Weitergabe des Ereignisses beendet wird.

Das folgende Snippet zeigt, wie eine doSomething() Funktion aufgerufen wird, wenn der Nutzer die S Taste auf der Box Komponente loslässt:

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

Modifikatortasten

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

Beschreiben Sie die Tastenereignisse, die Ihre App verarbeitet, so genau wie möglich. Das folgende Snippet ruft eine doSomething() Funktion nur auf, wenn der Nutzer nur die S Taste loslässt. Wenn der Nutzer eine Modifikatortaste drückt, wie die Umschalttaste Taste, 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")
}

Click-Events für Leertaste und Eingabetaste

Die Leertaste und die Eingabetaste lösen ebenfalls Klickereignisse aus. Nutzer können beispielsweise die Medienwiedergabe mit der Leertaste oder der Eingabetaste umschalten (wiedergeben oder pausieren) indem sie Click-Events wie folgt verarbeiten:

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

Der clickable Modifikator fängt Tastenereignisse ab und ruft den onClick() Callback auf, wenn die Leertaste oder Eingabetaste gedrückt wird. Daher wird die togglePausePlay() Funktion durch Drücken der Leertaste oder der Eingabetaste im Snippet aufgerufen.

Nicht verarbeitete Tastenereignisse

Nicht verarbeitete Tastenereignisse werden von der Komponente, in der das Ereignis aufgetreten ist, an die umschließende äußere Komponente weitergegeben. Im folgenden Beispiel verarbeitet die InnerComponent Tastenereignisse wenn die Taste S losgelassen wird, und so empfängt die OuterComponent keine Tastenereignisse, die durch das Loslassen der Taste S ausgelöst werden. Aus diesem Grund wird die Funktion actionB() nie aufgerufen.

Andere Tastenereignisse in InnerComponent, z. B. das Loslassen der Taste D, können von der OuterComponent verarbeitet werden. Die actionC() Funktion wird aufgerufen, weil das Tastenereignis für das 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
            }
        }
    )
}

Modifikator onKeyPreviewEvent

In einigen Anwendungsfällen möchten Sie ein Tastenereignis abfangen, bevor es die Standardaktion auslöst. Ein typisches Beispiel ist das Hinzufügen benutzerdefinierter Tastenkombinationen zu einem TextField. Das folgende Snippet ermöglicht es Nutzern, mit der Tab-Taste zur nächsten fokussierbaren Komponente zu wechseln.

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 jedes Mal ein Tabulatorzeichen hinzu, wenn Nutzer die Taste Tab drücken, auch wenn das Tastenereignis mit dem Modifikator onKeyEvent verarbeitet wird. Wenn Sie den Tastaturfokus verschieben möchten, ohne Tabulatorzeichen hinzuzufügen, verarbeiten Sie das Tastenereignis, bevor Sie die mit dem Tastenereignis verknüpften Aktionen auslösen, wie im Snippet. Die onKeyPreviewEvent() Lambda-Funktion fängt das Tastenereignis ab , indem sie true zurückgibt.

Die übergeordnete Komponente kann das Tastenereignis abfangen, das in 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")
    }
}

Die onPreviewKeyEvent() Lambda-Funktion für die Box Komponente wird auch nicht ausgelöst , wenn Nutzer die Tab-Taste drücken. Die Lambda-Funktion onPreviewKeyEvent() wird zuerst in der übergeordneten Komponente aufgerufen, dann wird onPreviewKeyEvent() in der untergeordneten Komponente aufgerufen. Mit diesem Verhalten können Sie Tastenkombinationen für den gesamten Bildschirm implementieren.

Zusätzliche Ressourcen

  • Tastenkombinations-Hilfe: Systembildschirm, auf dem Nutzer nach den Tastenkombinationen suchen können, die Ihre App bietet.
Weiter
Hilfe für Tastenkombinationen