在 Capacitor iOS 应用中禁用文本选择和放大镜
@capgo/capacitor-textinteraction 只需调用一次即可为 iOS 上的 Capacitor WebView 切换文本交互功能的开启或关闭。关闭后，长按文本将不再触发文本选择、复制菜单或 iOS 15 重新引入的放大镜。这能让你的 Web App 彻底摆脱在原生壳子里像个网页的感觉。
插件底层通过设置 WKPreferences.isTextInteractionEnabled 在应用的 WKWebView来工作。除此之外不会修改任何其他内容。
使用场景
- 游戏、自助终端和绘图应用 在这些场景下，长按和拖拽手势不应触发文本选择。
- 自定义长按菜单 避免与原生的选择手柄和弹出菜单产生冲突。
- 媒体播放器、地图和轮播图 防止缓慢滑动时意外触发放大镜。
- 品牌化、类 App 的 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 hook 中（例如 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 | 无操作。解析 { success: false }。如果需要限制选择，请使用 CSS。 |
| Web 端 | toggle 抛出未实现的错误。通过以下调用进行防护： Capacitor.getPlatform(). |
故障排除
- 输入功能失效。 文本交互仍处于禁用状态。请在
toggle({ enabled: true })显示表单之前调用。 - Android 上没有任何变化。 符合预期。该插件仅支持 iOS。
TextInteraction.toggle is not available on web. 调用发生在浏览器或桌面浏览器开发环境下。请将其包裹在平台检查逻辑中。- 重启应用后，选中的文本才会返回。 每次启动都会创建一个启用了文本交互的新 WebView。请在
toggle({ enabled: false })启动期间调用。
相关插件
- 隐私屏幕 在 iOS 应用切换器中隐藏应用内容，并拦截 Android 截图。
- 主屏幕指示条 在沉浸式屏幕模式下隐藏 iOS Home Indicator。
- 屏幕方向 锁定并读取屏幕方向。
- 浏览全部 按 Capgo 查看 Capacitor 插件.
无需经过 App Store 审核即可发布变更
切换文本交互仅需 JavaScript。一旦插件集成到你的 Native Build 中，你就可以通过 Capgo live update 来控制运行的位置和时机，而无需等待 App Store 审核。