Salta al contenuto principale
@capgo/capacitor-textinteraction UI e sistema Open source

Interazione testuale Plugin Capacitor

Disattiva la selezione del testo e la lente di ingrandimento di iOS nel WebView Capacitor quando la tua app deve sembrare nativa, poi riattivala prima che l'utente debba digitare.

  • iOS · Supportato (iOS 14.5+)
  • Android · Non supportato (risolve success: false)
  • Web · Non supportato (lancia unimplemented)

Installa

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

Guida

Come usare Text Interaction in Capacitor

Testa sul dispositivo

Scarica l'app Capgo, poi scansiona il QR code.

QR code per l'anteprima del plugin Text Interaction

Disabilita la selezione del testo e la lente d'ingrandimento nelle app Capacitor iOS

@capgo/capacitor-textinteraction ti permette di attivare o disattivare l'interazione con il testo nella Capacitor WebView su iOS con una sola chiamata. Quando è disattivata, la pressione prolungata sul testo non lo seleziona più, non mostra il callout di copia e non attiva la lente d'ingrandimento reintrodotta con iOS 15. La tua web app smette di sembrare una pagina web dentro una shell nativa.

Sotto il cofano, il plugin imposta WKPreferences.isTextInteractionEnabled on the app's WKWebView. Non cambia nient'altro.

Quando usarlo

  • Giochi, kiosk e app di disegno dove i gesti di pressione prolungata e trascinamento non devono mai selezionare il testo.
  • Menu personalizzati con pressione prolungata che vanno in conflitto con i selettori e il menu contestuale nativi.
  • Media player, mappe e carousel dove uno swipe lento attiva accidentalmente la lente d'ingrandimento.
  • UI di marca, stile app dove etichette e pulsanti selezionabili rompono la sensazione nativa.

Mantieni l'interazione con il testo attiva nelle schermate in cui gli utenti leggono contenuti lunghi che potrebbero voler copiare, o compilano moduli.

Installa

bun add @capgo/capacitor-textinteraction
bunx cap sync

No Info.plist chiavi, permessi o capacitor.config.ts voci sono necessari.

Versione del plugin Versione Capacitor Mantenuto
v8.x v8.x Sì
v7.x v7.x Su richiesta
v6.x e versioni precedenti v6.x e versioni precedenti No

Disabilita l'interazione con il testo all'avvio

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');
}

Passa sempre enabled esplicitamente. Il lato nativo tratta un valore mancante come false.

Riattivala prima che gli utenti digitino

Mentre l'interazione con il testo è disattivata, <input>, <textarea> e contenteditable gli elementi smettono di accettare input. Riattivalo per ogni schermata con un form, poi disattivalo quando l'utente esce.

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);

Con un router, chiama setTextInteraction(true) nell'hook enter delle rotte che contengono input (ad esempio Vue Router beforeEnter, un React useEffect, o Angular ionViewWillEnter) e setTextInteraction(false) quando le lasci.

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;
}

Il CSS funziona elemento per elemento, quindi tutto ciò che dimentichi resta selezionabile e non cambia il modo in cui la WebView gestisce il long-press. Il plugin agisce a livello di WebView: una sola chiamata copre ogni schermata, inclusa la lente d'ingrandimento. Molte app usano entrambi: il plugin per le schermate in stile app e il CSS per un controllo fine nelle schermate in cui l'interazione con il testo resta attiva.

riferimento API

toggle(options)

toggle(options: { enabled: boolean }): Promise<{ success: boolean }>

Attiva o disattiva l'interazione con il testo nella WebView di Capacitor.

  • enabled: true ripristina la selezione, il callout e la lente di ingrandimento. false li disabilita.
  • success: true quando la modifica è stata applicata (iOS 14.5+ con WebView disponibile). false su Android e quando non è disponibile una WebView.

getPluginVersion()

getPluginVersion(): Promise<{ version: string }>

Restituisce la versione del plugin nativo. Restituisce web nel browser.

Comportamento della piattaforma

Piattaforma Comportamento
iOS 14.5+ Imposta isTextInteractionEnabled su WKWebView. Applies to all pages until toggled again.
Android No-op. Risolve { success: false }. Usa CSS se devi limitare la selezione.
Web toggle lancia un errore non implementato. Proteggi le chiamate con Capacitor.getPlatform().

Risoluzione problemi

  • Gli input hanno smesso di funzionare. L'interazione con il testo è ancora disabilitata. Chiama toggle({ enabled: true }) prima che il form venga mostrato.
  • Niente cambia su Android. Atteso. Il plugin supporta solo iOS.
  • TextInteraction.toggle is not available on web. La chiamata è stata eseguita nel browser o durante lo sviluppo in un browser desktop. Incapsulala in un controllo della piattaforma.
  • La selezione viene restituita dopo il riavvio dell'app. Ogni avvio crea una nuova WebView con l'interazione testuale abilitata. Chiama toggle({ enabled: false }) durante l'avvio.

Rilascia la modifica senza la revisione dell'App Store

L'attivazione dell'interazione testuale è JavaScript. Una volta che il plugin è nella tua build nativa, puoi cambiare dove e quando viene eseguito con un Capgo live update invece di aspettare la revisione dell'App Store.

Riferimento completo

FAQ

FAQ del plugin Text Interaction

Come disabilito la selezione del testo in un'app iOS Capacitor?

Installa @capgo/capacitor-textinteraction, esegui bunx cap sync, poi chiama TextInteraction.toggle({ enabled: false }). Il plugin imposta isTextInteractionEnabled su false per il WKWebView, disattivando la selezione del testo e la lente di ingrandimento per l'intero WebView.

Perché CSS user-select: none non basta su iOS?

user-select e -webkit-touch-callout bloccano la maggior parte della selezione nel contenuto della pagina, ma il WKWebView può comunque mostrare la lente di ingrandimento e il comportamento di selezione al long-press, e ogni elemento a cui non hai applicato gli stili resta selezionabile. Il plugin disattiva l'interazione con il testo a livello di WebView, quindi una sola chiamata copre ogni schermata.

Gli utenti possono ancora digitare negli input mentre l'interazione con il testo è disabilitata?

No. Mentre l'interazione con il testo è disabilitata, gli input di testo, i textareas e gli elementi contenteditable smettono di funzionare. Chiama TextInteraction.toggle({ enabled: true }) prima di mostrare un modulo o un campo di ricerca, e disabilitalo di nuovo quando l'utente lascia quella schermata.

Il plugin funziona su Android o sul web?

No. Il toggle dell'interazione con il testo è solo per iOS. Su Android la chiamata si risolve con success impostato su false e non cambia nulla. Sul web la chiamata genera un errore non implementato, quindi proteggi la chiamata con Capacitor.getPlatform() === &quot;ios&quot;.

Quali versioni di iOS e Capacitor sono supportate?

Il API nativo richiede iOS 14.5 o successivo. Le versioni principali del plugin seguono Capacitor: usa il plugin v8 con Capacitor 8 e il plugin v7 con Capacitor 7.

L'impostazione persiste dopo il riavvio dell'app?

L'impostazione risiede nella configurazione del WebView, quindi rimane attiva tra le navigazioni di pagina finché non chiami di nuovo toggle. Un nuovo avvio dell'app crea un nuovo WebView con l'interazione con il testo abilitata, quindi chiama di nuovo toggle all'avvio se vuoi che sia disabilitata di default.

Come installo il plugin Text Interaction in un'app Capacitor?

Esegui &quot;bun add @capgo/capacitor-textinteraction&quot; (o &quot;npm install @capgo/capacitor-textinteraction&quot;), poi esegui &quot;bunx cap sync&quot; in modo che i progetti iOS e Android recuperino il code nativo. Importalo da &quot;@capgo/capacitor-textinteraction&quot; nel tuo code dell'app.

@capgo/capacitor-textinteraction funziona con React, Vue e Angular?

Sì. Text Interaction è un pacchetto Capacitor, quindi funziona con qualsiasi framework web che gira all'interno di Capacitor, incluso Ionic, React, Vue, Angular, Svelte e JavaScript puro.

Quale versione di Capacitor supporta @capgo/capacitor-textinteraction?

I plugin Capgo seguono la major version di Capacitor: usa la major version del plugin che corrisponde alla tua major version di Capacitor (ad esempio plugin v8 con Capacitor 8). La tabella di compatibilità nel README di GitHub elenca le versioni mantenute.

@capgo/capacitor-textinteraction è gratuito e open source?

Sì. Il codice sorgente di code è pubblico su GitHub all'indirizzo https://github.com/Cap-go/capacitor-textinteraction/ e il pacchetto si installa gratuitamente da npm. Bug report e pull request sono benvenuti.

Posso aggiornare code che usa Text Interaction senza una revisione dell'App Store?

Installare o aggiornare il plugin modifica il code nativo, quindi serve una nuova build per lo store. Dopo, le modifiche a JavaScript, HTML e CSS che chiamano il plugin possono essere rilasciate subito con le live updates di Capgo.

Rilascia le modifiche a Text Interaction senza attendere la revisione dell'app

Una volta incluso il plugin nel tuo store build, Capgo invia le modifiche a JavaScript, HTML e CSS tramite live updates in pochi minuti.

Inizia con Capgo