가이드
Capacitor에서 Text Interaction 사용법
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에 포함되면, 다음을 통해 실행 위치와 시점을 변경할 수 있습니다: Capgo live update App Store 심사를 기다릴 필요가 없습니다.