Anleitung
Text Interaction in Capacitor nutzen
Deaktiviere Textauswahl und die Lupe in Capacitor iOS-Apps
@capgo/capacitor-textinteraction ermöglicht es dir, die Textinteraktion für die Capacitor WebView auf iOS mit einem einzigen Aufruf ein- oder auszuschalten. Wenn sie deaktiviert ist, wird Text bei langem Drücken nicht mehr ausgewählt, es erscheint kein Kopier-Callout mehr und auch die Lupe wird nicht mehr eingeblendet, die iOS 15 wieder eingeführt hat. Deine Web-App fühlt sich nicht mehr wie eine Webseite in einer nativen Shell an.
Im Hintergrund setzt das Plugin WKPreferences.isTextInteractionEnabled on the app's WKWebView. Sonst ändert es nichts.
Wann einsetzen
- Spiele, Kioske und Zeichen-Apps, bei denen Long-Press- und Drag-Gesten niemals Text auswählen sollen.
- Eigene Long-Press-Menüs, die mit den nativen Auswahlgriffen und dem Callout kollidieren.
- Media Player, Karten und Carousels, bei denen ein langsamer Swipe versehentlich die Lupe auslöst.
- Branded, app-like UI wenn auswählbare Labels und Buttons das native Gefühl stören.
Textinteraktion auf Screens aktiv lassen, auf denen Nutzer lange Inhalte lesen, die sie kopieren möchten, oder Formulare ausfüllen.
Installieren
bun add @capgo/capacitor-textinteraction
bunx cap sync
Nein Info.plist Keys, Berechtigungen oder capacitor.config.ts Einträge erforderlich sind.
| Plugin-Version | Capacitor-Version | Gepflegt |
|---|---|---|
| v8.x | v8.x | Ja |
| v7.x | v7.x | Bei Bedarf |
| v6.x und älter | v6.x und älter | Nein |
Textinteraktion beim App-Start deaktivieren
import { Capacitor } from '@capacitor/core';
import { TextInteraction } from '@capgo/capacitor-textinteraction';
if (Capacitor.getPlatform() === 'ios') {
const { success } = await TextInteraction.toggle({ enabled: false });
if (!success) console.warn('Text interaction could not be changed on this device');
}
Immer übergeben enabled explizit. Die native Seite behandelt einen fehlenden Wert als false.
Vor der Texteingabe wieder aktivieren
Während die Textinteraktion deaktiviert ist, <input>, <textarea> und contenteditable Elemente akzeptieren keine Eingaben mehr. Aktiviere es für jeden Bildschirm mit einem Formular und deaktiviere es wieder, wenn der Nutzer den Bildschirm verlässt.
import { Capacitor } from '@capacitor/core';
import { TextInteraction } from '@capgo/capacitor-textinteraction';
const isIos = Capacitor.getPlatform() === 'ios';
export async function setTextInteraction(enabled: boolean) {
if (!isIos) return false;
const { success } = await TextInteraction.toggle({ enabled });
return success;
}
// Entering a login, search or checkout screen
await setTextInteraction(true);
// Leaving it
await setTextInteraction(false);
Mit einem Router rufst du setTextInteraction(true) im Enter-Hook von Routen auf, die Eingabefelder enthalten (z. B. Vue Router beforeEnter, ein React useEffect, oder Angular ionViewWillEnter) und setTextInteraction(false) beim Verlassen dieser Routen.
Plugin vs. CSS
You can hide most selection with CSS:
body {
-webkit-user-select: none;
user-select: none;
-webkit-touch-callout: none;
}
input,
textarea,
[contenteditable] {
-webkit-user-select: text;
user-select: text;
}
CSS wirkt pro Element, daher bleibt alles, was du vergisst, weiterhin markierbar, und es ändert nichts daran, wie der WebView selbst Langdrücke verarbeitet. Das Plugin arbeitet auf WebView-Ebene: Ein Aufruf deckt jeden Bildschirm ab, einschließlich der Lupe. Viele Apps nutzen beides: das Plugin für app-ähnliche Bildschirme und CSS für die Feinsteuerung innerhalb von Bildschirmen, auf denen Textinteraktion aktiv bleibt.
API-Referenz
toggle(options)
toggle(options: { enabled: boolean }): Promise<{ success: boolean }>
Aktiviert oder deaktiviert die Textinteraktion für die Capacitor WebView.
enabled:truestellt die Auswahl, das Callout-Menü und die Lupe wieder her.falsedeaktiviert diese.success:truewann die Änderung angewendet wurde (iOS 14.5+ mit verfügbarer WebView).falseunter Android und wenn keine WebView verfügbar ist.
getPluginVersion()
getPluginVersion(): Promise<{ version: string }>
Gibt die native Plugin-Version zurück. Gibt web im Browser zurück.
Plattformverhalten
| Plattform | Verhalten |
|---|---|
| iOS 14.5+ | Legt fest isTextInteractionEnabled auf dem WKWebView. Gilt für alle Seiten, bis es erneut umgeschaltet wird. |
| Android | No-op. Wird aufgelöst { success: false }. Nutze CSS, wenn du die Auswahl einschränken willst. |
| Web | toggle wirft einen 'unimplemented'-Error. Schütze Aufrufe mit Capacitor.getPlatform(). |
Fehlerbehebung
- Inputs funktionieren nicht mehr. Textinteraktion ist weiterhin deaktiviert. Rufe
toggle({ enabled: true })auf, bevor das Formular angezeigt wird. - Auf Android ändert sich nichts. Erwartet. Das Plugin unterstützt nur iOS.
TextInteraction.toggle is not available on web. Der Aufruf lief im Browser oder während der Entwicklung in einem Desktop-Browser. Pack ihn in einen Platform-Check.- Die Auswahl kommt nach einem App-Neustart zurück. Bei jedem Start wird eine neue WebView mit aktivierter Text-Interaction erstellt. Rufe die Methode
toggle({ enabled: false })beim App-Startup auf.
Verwandte Plugins
- Privacy Screen verdeckt App-Inhalte im iOS App-Switcher und blockiert Screenshots unter Android.
- Home-Indikator blendet den iOS-Home-Indicator für immersive Screens aus.
- Bildschirmausrichtung sperrt und liest die Bildschirmausrichtung aus.
- Alle durchsuchen Capacitor-Plugins von Capgo.
Änderung ohne App Store Review deployen
Das Umschalten der Textinteraktion erfolgt in JavaScript. Sobald das Plugin in deinem Native Build enthalten ist, kannst du mit einem Capgo live update ändern, anstatt auf die App-Store-Prüfung zu warten.
Vollständige Referenz
- Doku: Dokumentation des Text-Interaction-Plugins
- Erste Schritte: Installations- und API-Guide
- Quelle: Cap-go/capacitor-textinteraction auf GitHub