跳转至正文

文本交互 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 App,然后扫描二维码 code。

Text Interaction 插件预览二维码 code

在 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 }) 启动时调用。

无需经过 App Store 审核即可发布变更

切换文本交互功能由 JavaScript 控制。插件集成到原生构建后,您可以通过以下代码更改其运行位置和时机: Capgo live update 而无需等待 App Store 审核。

完整参考文档

常见问题

Text Interaction 插件常见问题

如何在 Capacitor iOS 应用中禁用文本选择?

安装 @capgo/capacitor-textinteraction,运行 bunx cap sync,然后调用 TextInteraction.toggle({ enabled: false })。该插件会将 WKWebView 的 isTextInteractionEnabled 设置为 false,从而关闭整个 WebView 的文本选择和放大镜。

为什么在 iOS 上 CSS user-select: none 还不够?

user-select 和 -webkit-touch-callout 能阻止页面内容中的大部分选择行为,但 WKWebView 在长按时仍可能显示放大镜和选择行为,而且任何忘记设置样式的元素依然可被选中。该插件在 WebView 层级关闭文本交互,一次调用即可覆盖所有页面。

禁用文本交互后,用户还能在输入框中打字吗?

不能。禁用文本交互后,文本输入框、textarea 和 contenteditable 元素都会失效。请在显示表单或搜索框前调用 TextInteraction.toggle({ enabled: true }),用户离开该页面后再重新禁用。

这个插件在 Android 或 Web 上能用吗?

不。文本交互切换仅支持 iOS。在 Android 上,该调用会解析为 success 设为 false,且不产生任何更改。在 Web 上,该调用会抛出未实现错误,因此请使用 Capacitor.getPlatform() === &quot;ios&quot; 进行保护。

支持哪些 iOS 和 Capacitor 版本?

原生 API 需要 iOS 14.5 或更高版本。插件主要版本遵循 Capacitor:使用插件 v8 搭配 Capacitor 8,使用插件 v7 搭配 Capacitor 7。

设置会在应用重启后保留吗?

该设置位于 WebView 配置中,因此在页面导航期间保持生效,直到你再次调用 toggle。新的应用启动会创建一个启用文本交互的新 WebView,因此如果你希望默认关闭,请在启动时再次调用 toggle。

如何在 Capacitor 应用中安装 Text Interaction 插件?

运行 &quot;bun add @capgo/capacitor-textinteraction&quot;(或 &quot;npm install @capgo/capacitor-textinteraction&quot;),然后运行 &quot;bunx cap sync&quot; 以便 iOS 和 Android 项目获取原生 code。在你的应用 code 中从 &quot;@capgo/capacitor-textinteraction&quot; 导入它。

@capgo/capacitor-textinteraction 支持 React、Vue 和 Angular 吗?

是的。Text Interaction 是一个 Capacitor 包,因此它适用于任何在 Capacitor 内运行的 Web 框架,包括 Ionic、React、Vue、Angular、Svelte 和纯 JavaScript。

@capgo/capacitor-textinteraction 支持哪个 Capacitor 版本?

Capgo 插件遵循 Capacitor 的主版本号:请使用与 Capacitor 主版本号一致的插件主版本(例如插件 v8 对应 Capacitor 8)。GitHub README 中的兼容性表列出了仍在维护的版本。

@capgo/capacitor-textinteraction 是免费且开源的吗?

是的。code 的源代码在 GitHub 上公开,地址为 https://github.com/Cap-go/capacitor-textinteraction/,并且可以从 npm 免费安装。欢迎提交 Bug 报告和 Pull Request。

我能否在不经过 App Store 审核的情况下更新使用 Text Interaction 的 code?

安装或升级插件会改动原生 code,因此需要重新做一次商店构建。之后,调用该插件的 JavaScript、HTML 和 CSS 改动就能通过 Capgo live updates 立即发布。

无需等待应用审核,即可发布 Text Interaction 更改

只要插件已包含在你的商店版本中,Capgo live updates 就能在几分钟内把 JavaScript、HTML 和 CSS 的改动推送给用户。

开始使用 Capgo