본문 바로가기
@capgo/capacitor-textinteraction UI & 시스템 오픈 소스

텍스트 상호작용 Capacitor 플러그인

앱이 네이티브처럼 느껴져야 할 때는 Capacitor WebView에서 텍스트 선택과 iOS 확대경을 비활성화하고, 사용자가 입력을 시작하기 직전에 다시 활성화하세요.

  • iOS · 지원됨 (iOS 14.5+)
  • Android · 지원되지 않음 (resolves success: false)
  • 웹 · 지원되지 않음 (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 앱을 다운로드한 후 QR code을 스캔하세요.

Text Interaction 플러그인 미리보기 QR code

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+). false Android 및 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 }) 앱 시작 시에.

App Store 심사 없이 변경 사항 배포

텍스트 상호작용 토글은 JavaScript로 동작합니다. 플러그인이 Native Build에 포함되면, App Store 심사를 기다릴 필요 없이 Capgo live update 다음 기능을 통해 실행 시점과 위치를 변경할 수 있습니다.

전체 레퍼런스

자주 묻는 질문

Text Interaction 플러그인 FAQ

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 레벨에서 텍스트 상호작용을 꺼버리므로, 한 번의 호출로 모든 화면에 적용됩니다.

텍스트 상호작용이 비활성화된 상태에서도 사용자가 input에 타이핑할 수 있나요?

아니요. 텍스트 상호작용이 비활성화되면 text input, textarea 및 contenteditable 요소가 작동하지 않습니다. 폼이나 검색 필드를 보여주기 전에 TextInteraction.toggle({ enabled: true })를 호출하고, 사용자가 해당 화면을 벗어날 때 다시 비활성화하세요.

이 플러그인이 Android나 웹에서도 작동하나요?

아니요. Text interaction 토글 기능은 iOS 전용입니다. Android에서는 호출 시 success가 false로 반환되며 아무런 변경도 일어나지 않습니다. 웹에서는 구현되지 않았다는 에러가 발생하므로, Capacitor.getPlatform() === "ios" 조건문으로 방어 코드를 작성하세요.

지원되는 iOS 및 Capacitor 버전은 무엇인가요?

네이티브 API는 iOS 14.5 이상이 필요합니다. 플러그인 메이저 버전은 Capacitor를 따릅니다. Capacitor 8 버전에는 플러그인 v8을, Capacitor 7 버전에는 플러그인 v7을 사용하세요.

앱을 재시작해도 설정이 유지되나요?

설정은 WebView 구성에 저장되므로, 다시 toggle을 호출하기 전까지 페이지 이동 시에도 유지됩니다. 앱을 새로 실행하면 text interaction이 활성화된 새 WebView가 생성되므로, 기본적으로 비활성화 상태를 원한다면 앱 시작 시 다시 toggle을 호출하세요.

Capacitor 앱에 Text Interaction 플러그인을 어떻게 설치하나요?

"bun add @capgo/capacitor-textinteraction" (또는 "npm install @capgo/capacitor-textinteraction")를 실행한 후, "bunx cap sync"를 실행하여 iOS 및 Android 프로젝트에 네이티브 code가 반영되도록 하세요. 앱의 code에서 "@capgo/capacitor-textinteraction"를 통해 import 하면 됩니다.

@capgo/capacitor-textinteraction가 React, Vue, Angular와 호환되나요?

네. Text Interaction은 Capacitor 패키지이므로 Ionic, React, Vue, Angular, Svelte 및 일반 JavaScript를 포함하여 Capacitor에서 실행되는 모든 웹 프레임워크와 호환됩니다.

@capgo/capacitor-textinteraction에서 지원하는 Capacitor 버전은 무엇인가요?

Capgo 플러그인은 Capacitor의 메이저 버전을 따릅니다. 사용 중인 Capacitor 메이저 버전과 일치하는 플러그인 메이저 버전을 사용하세요 (예: Capacitor 8에는 플러그인 v8). 유지 관리되는 버전은 GitHub README의 호환성 표에서 확인할 수 있습니다.

@capgo/capacitor-textinteraction는 무료 오픈 소스인가요?

네. code 소스 코드는 GitHub의 https://github.com/Cap-go/capacitor-textinteraction/에서 공개되어 있으며, npm에서 무료로 설치할 수 있습니다. 버그 리포트와 pull request를 환영합니다.

App Store 심사 없이 Text Interaction을 사용하는 code를 업데이트할 수 있나요?

플러그인을 설치하거나 업그레이드하면 네이티브 code가 변경되므로 새로운 스토어 빌드가 필요합니다. 그 이후에는 플러그인을 호출하는 JavaScript, HTML, CSS 변경 사항을 Capgo live updates로 즉시 배포할 수 있습니다.

앱 심사 대기 없이 Text Interaction 변경 사항 배포

스토어 빌드에 플러그인이 포함되면, Capgo live updates로 JavaScript, HTML, CSS 변경 사항을 몇 분 만에 사용자에게 푸시할 수 있습니다.

Capgo로 시작하기