Handflächenablehnung mit Eingabestift

Symbol für Bewertung mit fünf Sternen

Ein Stylus kann ein äußerst produktives und kreatives Tool sein. Wenn Nutzer mit einem Eingabestift zeichnen, schreiben oder mit einer App interagieren, berühren sie den Bildschirm manchmal mit der Handfläche. Das Berührungsereignis kann an Ihre App gemeldet werden, bevor das System es als versehentliche Berührung mit der Handfläche erkennt und verwirft.

Best Practices

Ihre App muss zusätzliche Touch-Ereignisse erkennen und ignorieren. In Jetpack Compose können Sie über eine PointerEvent auf die zugrunde liegende Android-MotionEvent zugreifen. Prüfen Sie MotionEvent auf ACTION_CANCEL. Dies weist darauf hin, dass eine Geste beendet und möglicherweise rückgängig gemacht werden muss. Unter Android 13 (API‑Level 33) und höher können Sie bei ACTION_CANCEL- und ACTION_POINTER_UP-Ereignissen nach dem Flag FLAG_CANCELED suchen. Dieses Flag ist ein starkes Signal dafür, dass die Berührung unbeabsichtigt war, z. B. eine Berührung mit der Handfläche.

Zutaten

  • Modifier.pointerInput(): Der Compose-Modifier, der zum Verarbeiten von Zeigereingaben verwendet wird.
  • PointerEvent: Stellt ein Zeigerereignis in Compose dar, das eine oder mehrere Änderungen enthält.
  • PointerEvent.motionEvent: Erweiterungseigenschaft, die Zugriff auf die zugrunde liegende Android-MotionEvent bietet (kann null sein).
  • MotionEvent: Stellt Touch- und Bewegungsereignisse dar. Enthält die Informationen, die erforderlich sind, um festzustellen, ob ein Ereignis ignoriert werden soll.
  • ACTION_CANCEL: Die MotionEvent-Konstante, die angibt, dass eine Geste abgebrochen wurde. Die Geste sollte beendet und möglicherweise rückgängig gemacht werden.
  • ACTION_POINTER_UP: Die Konstante MotionEvent gibt an, dass ein anderer als der erste Zeiger nach oben bewegt wurde (d. h. den Kontakt mit dem Gerätebildschirm verloren hat).
  • FLAG_CANCELED: MotionEvent-Konstante, die angibt, dass das Hochgehen des Zeigers ein unbeabsichtigtes Touch-Ereignis verursacht hat. Wurde den Ereignissen ACTION_POINTER_UP und ACTION_CANCEL unter Android 13 (API‑Level 33) und höher hinzugefügt.

Schritte

Prüfen Sie die MotionEvent-Objekte, die an Ihre App gesendet werden. Verwenden Sie die MotionEvent-APIs, um die Ereignismerkmale zu ermitteln:

  • Ereignisse mit einem Zeiger: Prüfen Sie auf ACTION_CANCEL, um festzustellen, ob die Geste beendet werden soll. Prüfen Sie unter Android 13 und höher auch, ob das Symbol FLAG_CANCELED angezeigt wird, um zu bestätigen, dass die Berührung unbeabsichtigt war.
  • Ereignisse mit mehreren Zeigern: Prüfen Sie unter Android 13 und höher auf ACTION_POINTER_UP und FLAG_CANCELED, um unbeabsichtigte Berührungen zu erkennen.

Reagieren Sie auf diese Ereignisse, indem Sie die Geste beenden und alle temporären Änderungen rückgängig machen.

1. Objekte von Bewegungsereignissen abrufen

Verwenden Sie Modifier.pointerInput, um Zeigereingaben für eine Composable zu verarbeiten. Verwenden Sie im Bereich für die Zeigereingabe awaitPointerEventScope und awaitPointerEvent, um Ereignisse zu empfangen, und rufen Sie das zugrunde liegende Android-MotionEvent mit der Eigenschaft motionEvent ab:

import androidx.compose.ui.input.pointer.pointerInput
    Box(
        modifier = Modifier
            .fillMaxSize()
            .pointerInput(Unit) {
                awaitPointerEventScope {
                    while (true) {
                        val event = awaitPointerEvent()
                        val motionEvent = event.motionEvent
                        if (motionEvent != null) {
                            // Process motion event.
                        }
                    }
                }
            }
    )

2. Ereignisaktion und ‑kennzeichnungen festlegen

Prüfen Sie MotionEvent auf ACTION_CANCEL. Dies weist auf ein Single-Pointer-Ereignis auf allen API-Ebenen hin. Bei Android 13 und höher prüfen Sie ACTION_POINTER_UP auf FLAG_CANCELED:

import androidx.compose.ui.input.pointer.pointerInput
    Box(
        modifier = Modifier
            .fillMaxSize()
            .pointerInput(Unit) {
                awaitPointerEventScope {
                    while (true) {
                        val event = awaitPointerEvent()
                        val motionEvent = event.motionEvent ?: continue

                        when (motionEvent.actionMasked) {
                            MotionEvent.ACTION_CANCEL -> {
                                // Process canceled single-pointer motion event for all SDK versions.
                            }
                            MotionEvent.ACTION_POINTER_UP -> {
                                if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.TIRAMISU &&
                                    (motionEvent.flags and MotionEvent.FLAG_CANCELED) == MotionEvent.FLAG_CANCELED
                                ) {
                                    // Process canceled multi-pointer motion event for Android 13 and higher.
                                }
                            }
                        }
                    }
                }
            }
    )

3. Geste rückgängig machen

Wenn Sie eine Berührung mit der Handfläche erkannt haben, können Sie die Bildschirmeffekte der Geste rückgängig machen.

Ihre App muss einen Verlauf der Nutzeraktionen führen, damit unbeabsichtigte Eingaben wie Berührungen mit der Handfläche rückgängig gemacht werden können. Ein Beispiel finden Sie im Codelab Unterstützung für Eingabestifte in Android-Apps verbessern im Abschnitt Implement a basic drawing app.

Ergebnisse

Ihre App kann jetzt Handflächenberührungen für Ereignisse mit mehreren Zeigern unter Android 13 und höheren API-Levels sowie für Ereignisse mit einem einzelnen Zeiger auf allen API-Levels erkennen und ablehnen.

Zusätzliche Ressourcen

Hier finden Sie weitere Informationen: