在 Capacitor iOS 应用中禁用文本选择和放大镜
@capgo/capacitor-textinteraction 只需一次调用,即可开启或关闭 iOS 上 Capacitor WebView 的文本交互。关闭后,长按文本不再选中文本、弹出复制菜单,也不会调出 iOS 15 重新引入的放大镜。你的 Web 应用在原生外壳里不再像网页。
底层实现上,插件会设置 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当更改已应用时(iOS 14.5+ 且 WebView 可用)。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 主屏幕指示器,以实现沉浸式屏幕体验。
- 屏幕方向 锁定并读取屏幕方向。
- 浏览全部 Capgo 的 Capacitor 插件.
无需经过 App Store 审核即可发布变更
切换文本交互功能由 JavaScript 控制。插件集成到原生构建后,您可以通过以下代码更改其运行位置和时机: Capgo live update 而无需等待 App Store 审核。