Aller au contenu principal
@capgo/capacitor-textinteraction UI & système Open source

Interaction textuelle Plugin Capacitor

Désactivez la sélection de texte et la loupe iOS dans la WebView Capacitor quand votre app doit avoir un rendu natif, puis réactivez-les avant que l’utilisateur ait besoin de taper du texte.

  • iOS · Pris en charge (iOS 14.5+)
  • Android · Non pris en charge (résout success: false)
  • Le Web · Non pris en charge (lève unimplemented)

Installer

bun add @capgo/capacitor-textinteraction bunx cap sync
npm, pnpm ou yarn
  • npm install @capgo/capacitor-textinteraction
  • pnpm add @capgo/capacitor-textinteraction
  • yarn add @capgo/capacitor-textinteraction

Guide

Comment utiliser Text Interaction dans Capacitor

Tester sur l'appareil

Téléchargez l'application Capgo, puis scannez le QR code.

QR code d’aperçu du plugin Text Interaction code

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: true restaure la sélection, le menu contextuel et la loupe. false les désactive.
  • success: true lorsque la modification a été appliquée (iOS 14.5+ avec une WebView disponible). false sur 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.

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

FAQ

FAQ du plugin Text Interaction

Comment désactiver la sélection de texte dans une app iOS Capacitor ?

Installez @capgo/capacitor-textinteraction, exécutez bunx cap sync, puis appelez TextInteraction.toggle({ enabled: false }). Le plugin définit isTextInteractionEnabled à false sur la WKWebView, ce qui désactive la sélection de texte et la loupe pour toute la WebView.

Pourquoi CSS user-select: none ne suffit-il pas sur iOS ?

user-select et -webkit-touch-callout empêchent la plupart des sélections dans le contenu de la page, mais la WKWebView peut toujours afficher la loupe et le comportement de sélection lors d’un appui long, et tout élément que vous oubliez de styler reste sélectionnable. Le plugin désactive l’interaction texte au niveau de la WebView, donc un seul appel couvre tous les écrans.

Can users still type in inputs while text interaction is disabled?

Non. Lorsque l’interaction texte est désactivée, les champs de texte, les textareas et les éléments contenteditable cessent de fonctionner. Appelez TextInteraction.toggle({ enabled: true }) avant d’afficher un formulaire ou un champ de recherche, puis désactivez-l’à nouveau lorsque l’utilisateur quitte cet écran.

Le plugin fonctionne-t-il sur Android ou sur le web ?

Non. L'activation de l'interaction textuelle est réservée à iOS. Sur Android, l'appel se résout avec success à false et ne change rien. Sur le web, l'appel lève une erreur « non implémenté » : protégez-le donc avec Capacitor.getPlatform() === "ios".

Quelles versions d'iOS et de Capacitor sont prises en charge ?

L’API natif nécessite iOS 14.5 ou supérieur. Les versions majeures du plugin suivent Capacitor : utilisez le plugin v8 avec Capacitor 8 et le plugin v7 avec Capacitor 7.

Le paramètre persiste-t-il après le redémarrage de l'app ?

Le paramètre fait partie de la configuration de la WebView : il reste donc actif au fil des navigations jusqu'à ce que vous rappeliez toggle. À chaque lancement, l'app crée une nouvelle WebView avec l'interaction textuelle activée ; rappelez donc toggle au démarrage si vous la voulez désactivée par défaut.

Comment installer le plugin Text Interaction dans une app Capacitor ?

Exécutez "bun add @capgo/capacitor-textinteraction" (ou "npm install @capgo/capacitor-textinteraction"), puis lancez "bunx cap sync" pour que les projets iOS et Android prennent en compte le code natif. Importez-le depuis "@capgo/capacitor-textinteraction" dans le code de votre app.

Est-ce que @capgo/capacitor-textinteraction fonctionne avec React, Vue et Angular ?

Oui. Text Interaction est un package Capacitor, il fonctionne donc avec n'importe quel framework web exécuté dans Capacitor, y compris Ionic, React, Vue, Angular, Svelte et du JavaScript simple.

Quelle version de Capacitor est supportée par @capgo/capacitor-textinteraction ?

Les plugins Capgo suivent la version majeure de Capacitor : utilisez la version majeure du plugin qui correspond à la version majeure de votre Capacitor (par exemple le plugin v8 avec Capacitor 8). Le tableau de compatibilité du README de GitHub recense les versions maintenues.

Est-ce que @capgo/capacitor-textinteraction est gratuit et open source ?

Oui. Le code source de code est public sur GitHub à l'adresse https://github.com/Cap-go/capacitor-textinteraction/ et le package s'installe gratuitement depuis npm. Les rapports de bugs et les pull requests sont les bienvenus.

Puis-je mettre à jour code utilisant Text Interaction sans passer par une revue de l'App Store ?

L'installation ou la mise à jour du plugin modifie le code natif, ce qui impose un nouveau build pour les stores. Ensuite, les changements JavaScript, HTML et CSS qui appellent le plugin peuvent être livrés instantanément via les live updates de Capgo.

Déployez les changements de Text Interaction sans attendre la validation de l'app

Une fois le plugin intégré à votre build de store, Capgo live updates déploie vos changements JavaScript, HTML et CSS aux utilisateurs en quelques minutes.

Commencez avec Capgo