Capacitor iOS 앱에서 텍스트 선택 및 돋보기 렌즈 비활성화
@capgo/capacitor-textinteraction iOS의 Capacitor WebView에서 텍스트 상호작용을 켜거나 끌 수 있는 단일 호출을 제공합니다. 기능을 끄면 텍스트를 길게 눌러도 텍스트가 선택되지 않으며, 복사 메뉴가 나타나거나 iOS 15에서 다시 도입된 확대 렌즈도 표시되지 않습니다. 이를 통해 웹 앱이 네이티브 셸 안의 웹 페이지처럼 느껴지는 현상을 방지할 수 있습니다.
내부적으로 이 플러그인은 앱의 WKPreferences.isTextInteractionEnabled 에 WKWebView를 설정합니다. 그 외 다른 부분은 변경하지 않습니다.
사용 시점
- 게임, 키오스크, 드로잉 앱 등 길게 누르기나 드래그 제스처로 텍스트가 선택되면 안 되는 경우에 유용합니다.
- 네이티브 선택 핸들 및 호출 메뉴와 충돌하는 커스텀 롱프레스 메뉴를 사용하는 경우에 적합합니다.
- 미디어 플레이어, 지도, 캐러셀 등 느린 스와이프 동작이 실수로 확대 렌즈를 트리거하는 경우에 사용하세요.
- 브랜드 아이덴티티가 담긴 앱 스타일 UI 선택 가능한 라벨이나 버튼이 네이티브 느낌을 해치는 경우.
사용자가 긴 콘텐츠를 복사하거나 양식을 작성해야 하는 화면에서는 텍스트 상호작용을 활성화하세요.
설치
bun add @capgo/capacitor-textinteraction
bunx cap sync
아니요 Info.plist 키, 권한 또는 capacitor.config.ts 입력이 필요한 경우.
| Plugin 버전 | 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+).falseAndroid 및 WebView를 사용할 수 없는 경우.
getPluginVersion()
getPluginVersion(): Promise<{ version: string }>
네이티브 플러그인 버전을 반환합니다. 반환값: web 브라우저에서.
플랫폼별 동작
| 플랫폼 | 동작 방식 |
|---|---|
| iOS 14.5+ | 설정합니다 isTextInteractionEnabled 시에는 WKWebView. 다시 토글하기 전까지 모든 페이지에 적용됩니다. |
| Android | 동작 없음. resolve됩니다. { success: false }. 선택 범위를 제한하려면 CSS를 사용하세요. |
| 웹 | toggle 구현되지 않았다는 에러가 발생합니다. 다음을 통해 호출을 방지하세요: Capacitor.getPlatform(). |
문제 해결
- 입력이 작동을 멈췄습니다. 텍스트 상호작용이 아직 비활성화되어 있습니다. 다음을 호출하세요:
toggle({ enabled: true })폼이 표시되기 전에. - Android에서는 변경 사항이 없습니다. 예상된 결과입니다. 이 플러그인은 iOS만 지원합니다.
TextInteraction.toggle is not available on web. 브라우저에서, 또는 데스크톱 브라우저로 개발하는 중에 호출되었습니다. 플랫폼 체크로 감싸세요.- 앱을 재시작하면 선택 영역이 다시 나타납니다. 앱을 실행할 때마다 텍스트 상호작용이 활성화된 새 WebView가 생성됩니다. 다음을 호출하세요
toggle({ enabled: false })앱 시작 시에.
관련 플러그인
- Privacy Screen iOS 설정 iOS 앱 전환기에서 앱 콘텐츠를 숨기고 Android 스크린샷을 차단합니다.
- 홈 인디케이터 몰입형 화면을 위해 iOS 홈 인디케이터를 숨깁니다.
- 화면 방향 화면 방향을 고정하고 읽어옵니다.
- 전체 보기 Capgo의 Capacitor 플러그인.
App Store 심사 없이 변경 사항 배포
텍스트 상호작용 토글은 JavaScript로 동작합니다. 플러그인이 Native Build에 포함되면, App Store 심사를 기다릴 필요 없이 Capgo live update 다음 기능을 통해 실행 시점과 위치를 변경할 수 있습니다.