Handflächenablehnung mit Eingabestift

Symbol für Bewertung mit fünf Sternen

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

Best Practices

Ihre App muss fremde Touch-Ereignisse erkennen und ignorieren. In Jetpack Compose können Sie über ein PointerEvent auf das zugrunde liegende Android MotionEvent zugreifen. Prüfen Sie das MotionEvent auf ACTION_CANCEL. Dies gibt an, dass eine Geste beendet werden sollte und möglicherweise zurückgesetzt werden muss. Unter Android 13 (API-Level 33) und höher prüfen Sie bei ACTION_CANCEL- und ACTION_POINTER_UP-Ereignissen das FLAG_CANCELED Flag . Dies 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-Modifikator, 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 das zugrunde liegende Android-MotionEvent bietet (kann null sein).
  • MotionEvent: Stellt Touch- und Bewegungsereignisse dar. Enthält die Informationen, die erforderlich sind, um zu bestimmen, ob ein Ereignis ignoriert werden soll.
  • ACTION_CANCEL: MotionEvent-Konstante, die angibt, dass eine Geste abgebrochen wurde. Die Geste sollte beendet werden und muss möglicherweise zurückgesetzt werden.
  • ACTION_POINTER_UP: MotionEvent-Konstante, die angibt, dass ein anderer Zeiger 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 Anheben des Zeigers ein unbeabsichtigtes Touch-Ereignis verursacht hat. Wird unter Android 13 (API-Level 33) und höher zu ACTION_POINTER_UP- und ACTION_CANCEL-Ereignissen hinzugefügt.

Schritte

Untersuchen Sie die MotionEvent-Objekte, die an Ihre App gesendet werden. Verwenden Sie die MotionEvent-APIs, um die Ereigniseigenschaften zu bestimmen:

  • Ereignisse mit einem Zeiger : Prüfen Sie auf ACTION_CANCEL. Dies gibt an, dass die Geste beendet werden sollte. Unter Android 13 und höher prüfen Sie auch auf FLAG_CANCELED, 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 zurücksetzen.

1. Bewegungsereignisobjekte abrufen

Verwenden Sie Modifier.pointerInput, um Zeigereingaben für ein Composable zu verarbeiten. Verwenden Sie im Bereich für Zeigereingaben awaitPointerEventScope und awaitPointerEvent, um Ereignisse zu empfangen, und rufen Sie das zugrunde liegende Android-MotionEvent mit der motionEvent-Eigenschaft 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 Flags bestimmen

Prüfen Sie das MotionEvent auf ACTION_CANCEL. Dies gibt auf allen API-Levels ein Ereignis mit einem Zeiger an. Prüfen Sie unter Android 13 und höher 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

Sobald Sie eine Berührung mit der Handfläche erkannt haben, können Sie die Auswirkungen der Geste auf dem Bildschirm rückgängig machen.

Ihre App muss einen Verlauf der Nutzeraktionen speichern, damit unbeabsichtigte Eingaben wie Berührungen mit der Handfläche rückgängig gemacht werden können. Ein Beispiel finden Sie im Codelab Implement a basic drawing app (Eine einfache Zeichen-App implementieren) unter Enhance stylus support in an Android app (Unterstützung für Eingabestifte in Android-Apps verbessern).

Ergebnisse

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

Zusätzliche Ressourcen

Hier finden Sie weitere Informationen: