Guide
Comment utiliser Text Interaction dans Capacitor
Désactivez la sélection de texte et la loupe dans les apps iOS Capacitor
@capgo/capacitor-textinteraction permet d'activer ou de désactiver l'interaction avec le texte de la WebView Capacitor sur iOS en un seul appel. Lorsqu'elle est désactivée, un appui long ne sélectionne plus le texte, n'affiche plus le menu de copie et ne déclenche plus la loupe réintroduite par iOS 15. Votre web app ne donne plus l'impression d'être une page web dans un shell natif.
Sous le capot, le plugin définit WKPreferences.isTextInteractionEnabled sur l’application WKWebView. Il ne modifie rien d'autre.
Quand l'utiliser
- Jeux, bornes et apps de dessin où les gestes d'appui long et de glissement ne doivent jamais sélectionner de texte.
- Menus d'appui long personnalisés qui entrent en conflit avec les poignées de sélection natives et le menu contextuel.
- Lecteurs média, cartes et carrousels où un balayage lent déclenche accidentellement la loupe.
- UI fidèl’à l’application où les libellés et boutons sélectionnables cassent le rendu natif.
Gardez l’interaction texte activée sur les écrans où les utilisateurs lisent du contenu long qu’ils peuvent vouloir copier, ou remplissent des formulaires.
Installer
bun add @capgo/capacitor-textinteraction
bunx cap sync
Non Info.plist clés, permissions ou capacitor.config.ts entrées sont nécessaires.
| Version du plugin | version Capacitor | Maintenu |
|---|---|---|
| v8.x | v8.x | Oui |
| v7.x | v7.x | À la demande |
| v6.x et versions antérieures | v6.x et versions antérieures | Non |
Disable text interaction on app start
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');
}
Toujours passer enabled explicitement. Le côté natif considère une valeur manquante comme false.
La réactiver avant que les utilisateurs ne tapent
Tant que l'interaction textuelle est désactivée, <input>, <textarea> et contenteditable les éléments cessent d'accepter la saisie. Réactivez-le pour tout écran contenant un formulaire, puis désactivez-l’à nouveau quand l'utilisateur quitte l'écran.
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);
Avec un routeur, appelez setTextInteraction(true) dans le hook d'entrée des routes qui contiennent des inputs (par exemple Vue Router beforeEnter, un React useEffect, ou Angular ionViewWillEnter) setTextInteraction(false) lorsque vous les quittez.
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;
}
Le CSS fonctionne par élément, donc tout ce que vous oubliez reste sélectionnable, et cela ne change pas la façon dont la WebView gère l'appui long. Le plugin agit au niveau de la WebView : un seul appel couvre tous les écrans, y compris la loupe. De nombreuses apps utilisent les deux : le plugin pour les écrans de type application et le CSS pour un contrôle précis dans les écrans où l'interaction textuelle reste active.
Référence API
toggle(options)
toggle(options: { enabled: boolean }): Promise<{ success: boolean }>
Active ou désactive l'interaction textuelle pour la WebView Capacitor.
enabled:truerestaure la sélection, le menu contextuel et la loupe.falseles désactive.success:truelorsque la modification a été appliquée (iOS 14.5+ avec une WebView disponible).falsesur Android et lorsqu'aucune WebView n'est disponible.
getPluginVersion()
getPluginVersion(): Promise<{ version: string }>
Retourne la version du plugin natif. Retourne web dans le navigateur.
Comportement par plateforme
| Plateforme | Comportement |
|---|---|
| iOS 14.5+ | Définit isTextInteractionEnabled sur la WKWebView. Applies to all pages until toggled again. |
| Android | Aucune action. Résout { success: false }. Utilisez CSS si vous devez limiter la sélection. |
| Le Web | toggle lève une erreur non implémentée. Protégez les appels avec Capacitor.getPlatform(). |
Troubleshooting
- Les entrées ne fonctionnent plus. L'interaction avec le texte est toujours désactivée. Appelez
toggle({ enabled: true })avant l'affichage du formulaire. - Rien ne change sur Android. Comme prévu. Le plugin ne prend en charge que iOS.
TextInteraction.toggle is not available on web. L’appel s’est exécuté dans le navigateur ou lors du développement dans un navigateur de bureau. Entourez-le d’une vérification de plateforme.- La sélection réapparaît après le redémarrage de l’application. Chaque lancement crée une nouvelle WebView avec l’interaction texte activée. Appelez
toggle({ enabled: false })au démarrage.
Plugins associés
- Écran de confidentialité masque le contenu de l’app dans le sélecteur d’apps iOS et bloque les captures d’écran Android.
- Indicateur d'accueil masque l’indicateur d’accueil iOS pour les écrans immersifs.
- Orientation de l'écran verrouille et lit l’orientation de l’écran.
- Tout parcourir Plugins Capacitor par Capgo.
Déployez la modification sans passer par une revue App Store
Basculer l’interaction avec le texte est du JavaScript. Une fois le plugin intégré à votre build natif, vous pouvez modifier où et quand il s’exécute avec un Capgo live update au lieu d’attendre la revue App Store.
Référence complète
- Docs : Documentation du plugin Text Interaction
- Pour commencer : Guide d’installation et de API
- Source : Cap-go/capacitor-textinteraction sur GitHub