メインコンテンツへスキップ
@capgo/capacitor-textinteraction UI & システム オープンソース

テキスト操作 Capacitor プラグイン

アプリをネイティブに感じさせたいときは、Capacitor WebViewのテキスト選択とiOSの拡大鏡をオフにし、ユーザーが入力する前にオンに戻します。

  • iOSと ・対応 (iOS 14.5+)
  • Androidでは ・未対応 (success: false を返す)
  • Web ・未対応 (unimplementedエラー)

インストール

bun add @capgo/capacitor-textinteraction bunx cap sync
npm、pnpm、または yarn
  • npm install @capgo/capacitor-textinteraction
  • pnpm add @capgo/capacitor-textinteraction
  • yarn add @capgo/capacitor-textinteraction

ガイド

Capacitor で Text Interaction を使う方法

実機でテストする

Capgo アプリをダウンロードして、QR code をスキャンしてください。

Text Interaction プラグインのプレビューQR code

Capacitor iOSアプリでテキスト選択と拡大鏡を無効化

@capgo/capacitor-textinteraction iOSのCapacitor WebViewにおけるテキストインタラクションのオン/オフを、たった1回の呼び出しで切り替えられます。オフにすると、テキストの長押しによる選択、コピーメニューの表示、iOS 15から再導入された拡大鏡の表示が行われなくなります。これにより、Webアプリがネイティブシェルの中で動いているような違和感を解消できます。

内部的には、このプラグインは以下の設定を行います: WKPreferences.isTextInteractionEnabled アプリの WKWebViewに設定します。それ以外の箇所には影響しません。

ユースケース

  • ゲーム、キオスク端末、描画アプリ 長押しやドラッグ操作でテキストを選択させたくない場合。
  • カスタム長押しメニュー ネイティブの選択ハンドルやメニューと干渉してしまう場合。
  • メディアプレーヤー、マップ、カルーセル ゆっくりとしたスワイプで誤って拡大鏡が起動してしまう場合。
  • ブランド感のあるアプリ風UI 選択可能なラベルやボタンがネイティブな操作感を損なう場面。

ユーザーがコピーしたくなる長文を読む画面や、フォームに入力する画面では、テキストインタラクションを有効にしてください。

インストール

bun add @capgo/capacitor-textinteraction
bunx cap sync

いいえ Info.plist キー、権限、または capacitor.config.ts エントリが必要です。

プラグインのバージョン Capacitor バージョン メンテナンス済み
v8.x v8.x はい
v7.x v7.x オンデマンド
v6.x 以前 v6.x 以前 いいえ

アプリ起動時にテキスト操作を無効化

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

常に明示的に enabled 値を渡してください。ネイティブ側では、値がない場合は false.

ユーザーが入力する前に再度有効化

テキスト操作が無効な間、 <input>, <textarea> と contenteditable 要素は入力を受け付けなくなります。フォームがある画面では再度有効にし、ユーザーが離れるときにまた無効にしてください。

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

ルーターを使う場合は、 setTextInteraction(true) 入力があるルートの enter フック内で呼び出します(例:Vue Router beforeEnter、React useEffect、または Angular ionViewWillEnter)、離れるときは setTextInteraction(false) 同様に呼び出します。

プラグイン vs CSS

CSS でほとんどの選択を非表示にできます:

body {
  -webkit-user-select: none;
  user-select: none;
  -webkit-touch-callout: none;
}

input,
textarea,
[contenteditable] {
  -webkit-user-select: text;
  user-select: text;
}

CSS は要素ごとに適用されるため、設定を忘れた要素は選択可能なままになり、WebView 自体の長押しの挙動も変わりません。一方、プラグインは WebView レベルで動作するので、拡大レンズを含むすべての画面を一度の呼び出しでカバーできます。多くのアプリでは、アプリらしい画面にはプラグインを、テキスト操作を残す画面内の細かい制御には CSS を、という形で両方を併用しています。

API リファレンス

toggle(options)

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

Capacitor WebView のテキストインタラクションを有効または無効にします。

  • enabled: true 選択、コールアウト、拡大鏡を復元します。 false これらを無効にします。
  • success: true 変更が適用された時点(WebView が利用可能な iOS 14.5 以降)。 false Android の場合と、WebView が利用できない場合。

getPluginVersion()

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

ネイティブプラグインのバージョンを返します。返り値は web ブラウザでは。

プラットフォームの動作

プラットフォーム 動作
iOS 14.5以上 設定します isTextInteractionEnabled 上で WKWebView再度切り替えるまで、すべてのページに適用されます。
Androidでは No-op。解決します { success: false }選択範囲を制限したい場合は CSS を使用してください。
Web toggle 未実装エラーをスローします。呼び出しは次でガードしてください Capacitor.getPlatform().

トラブルシューティング

  • 入力が機能しなくなりました。 テキスト操作は無効のままです。呼び出してください toggle({ enabled: true }) フォームが表示される前に。
  • Android では何も変更されません。 想定どおりです。このプラグインはiOSのみ対応しています。
  • TextInteraction.toggle is not available on web. 呼び出しがブラウザ、またはデスクトップブラウザでの開発中に実行されました。プラットフォームチェックで囲んでください。
  • アプリを再起動すると選択が戻ります。 起動のたびにテキスト操作が有効な新しいWebViewが作成されます。呼び出しは toggle({ enabled: false }) 起動時に行ってください。

App Store の審査なしで変更をリリース

テキストインタラクションの切り替えは JavaScript で行います。プラグインを Native Build に組み込んだ後は、実行場所とタイミングを次の方法で変更できます Capgo live update App Store の審査を待つ代わりに。

完全なリファレンス

よくある質問

Text Interaction plugin FAQ

Capacitor iOSアプリでテキスト選択を無効にするにはどうすればいいですか?

@capgo/capacitor-textinteraction をインストールして bunx cap sync を実行した後、TextInteraction.toggle({ enabled: false }) を呼び出します。このプラグインは WKWebView の isTextInteractionEnabled を false に設定し、WebView 全体でテキスト選択と拡大鏡(magnifier lens)を無効にします。

iOSで CSS の user-select: none だけでは不十分なのはなぜですか?

user-select や -webkit-touch-callout はページ内のほとんどの選択を停止させますが、WKWebView では長押し時に拡大鏡が表示されたり、スタイルの適用を忘れた要素が選択可能になったりすることがあります。このプラグインは WebView レベルでテキストインタラクションをオフにするため、一度の呼び出しですべての画面をカバーできます。

テキストインタラクションが無効な間でも、ユーザーは input に入力できますか?

いいえ。テキストインタラクションが無効な間は、text input、textarea、および contenteditable 要素は機能しません。フォームや検索フィールドを表示する前に TextInteraction.toggle({ enabled: true }) を呼び出し、ユーザーがその画面を離れる際に再度無効にしてください。

このプラグインは Android や Web でも動作しますか?

いいえ。テキストインタラクションの切り替えはiOSのみです。Androidでは呼び出しはsuccessがfalseで解決され、何も変更されません。Webでは未実装エラーがスローされるので、Capacitor.getPlatform() === "ios" でガードしてください。

サポートされているiOSとCapacitorのバージョンは?

ネイティブのAPIにはiOS 14.5以降が必要です。プラグインのメジャーバージョンはCapacitorに準拠します。Capacitor 8にはプラグインv8、Capacitor 7にはプラグインv7を使ってください。

アプリを再起動しても設定は保持されますか?

設定はWebViewの構成に保持されるため、再度toggleを呼び出すまでページ遷移しても有効なままです。アプリを新規起動するとテキストインタラクションが有効な新しいWebViewが作られるので、デフォルトでオフにしたい場合は起動時に再度toggleを呼び出してください。

CapacitorアプリにText Interactionプラグインをインストールする方法は?

"bun add @capgo/capacitor-textinteraction"(または "npm install @capgo/capacitor-textinteraction")を実行した後、"bunx cap sync" を実行してiOSおよびAndroidプロジェクトにネイティブのcodeを反映させてください。アプリのcodeで"@capgo/capacitor-textinteraction"からインポートします。

@capgo/capacitor-textinteractionはReact、Vue、Angularで動作しますか?

はい。Text InteractionはCapacitorパッケージなので、Ionic、React、Vue、Angular、Svelte、素のJavaScriptなど、Capacitor内で動くあらゆるWebフレームワークで使えます。

@capgo/capacitor-textinteractionはどのCapacitorバージョンをサポートしていますか?

Capgo プラグインは Capacitor のメジャーバージョンに合わせています。使用している Capacitor のメジャーバージョンに一致するプラグインのメジャーバージョンを使ってください (例: Capacitor 8 ならプラグイン v8)。GitHub の README にある互換性テーブルに、メンテナンス中のバージョンが記載されています。

@capgo/capacitor-textinteractionは無料かつオープンソースですか?

はい。codeのソースコードはGitHub(https://github.com/Cap-go/capacitor-textinteraction/)で公開されており、npmから無料でインストールできます。バグ報告やプルリクエストも歓迎しています。

Text Interactionを使用しているcodeを、App Storeの審査なしでアップデートできますか?

プラグインのインストールやアップグレードはネイティブの code を変更するため、新しいストアビルドが必要です。その後は、プラグインを呼び出す JavaScript、HTML、CSS の変更を Capgo Live Updates で即座に配信できます。

アプリの審査を待たずに Text Interaction の変更をリリース

プラグインをストア用ビルドに組み込めば、Capgo live updates で JavaScript、HTML、CSS の変更を数分でユーザーに配信できます

Capgo から始める