이 페이지는 Cloud Translation API를 통해 번역되었습니다.

텍스트 입력란의 스타일러스 입력

Android 14 (API 수준 34) 이상에서는 사용자가 스타일러스를 사용하여 모든 앱의 텍스트 입력란에 쓸 수 있습니다. EditText 구성요소와 WebView 텍스트 위젯을 포함한 Android 텍스트 입력 필드는 기본적으로 스타일러스 입력을 지원합니다.

그러나 앱에 맞춤 텍스트 입력란이 필요하거나 (맞춤 텍스트 편집기 참고) 그리기 표면을 오버레이하는 텍스트 입력란이 있는 복잡한 레이아웃이 있는 경우 앱을 맞춤설정해야 합니다.

그림 1. 스타일러스를 사용한 필기 입력입니다.

`EditText`

스타일러스 필기 입력은 Android 14 이상에서 기본적으로 모든 EditText 필드에 사용 설정됩니다. 뷰의 필기 입력 경계 내에서 스타일러스 모션 이벤트가 감지되면 EditText의 필기 입력 모드가 시작됩니다.

필기 입력 경계에는 뷰 주위의 세로 패딩 40dp와 가로 패딩 10dp가 포함됩니다. setHandwritingBoundsOffsets()를 사용하여 필기 입력 범위를 조정합니다. setAutoHandwritingEnabled(false)를 사용하여 필기 입력을 사용 중지합니다.

스타일러스 모션 이벤트 감지 범위를 나타내는 직사각형이 둘러싸인 입력 필드. — **그림 2.** `EditText` 필드의 필기 입력 경계

참고: 다음과 같이 비밀번호 입력 유형이 있는 EditText 필드에는 스타일러스 필기 입력이 지원되지 않습니다.

<EditText
    ...
    android:inputType="textPassword"
    ... />

android:inputType을 참고하세요.

입력 위임

앱은 자리표시자 UI 요소를 텍스트 입력란처럼 보이지만 실제로는 텍스트 입력 기능이 없는 정적 UI 요소인 자리표시자 UI 요소를 표시할 수 있습니다. 검색 필드가 일반적인 예입니다. 정적 UI 요소를 탭하면 입력에 중점을 둔 기능 텍스트 입력란이 포함된 새로운 UI로 전환됩니다.

그림 3. 정적 UI 요소에서 텍스트 입력란으로 입력 위임

스타일러스 입력 위임

필기 입력 위임 API를 사용하여 자리표시자 입력란에 스타일러스 필기 입력 입력을 지원합니다 (setHandwritingDelegatorCallback() 및 setIsHandwritingDelegate() 참고). 자리표시자 UI 요소는 필기 입력을 기능 입력 필드에 위임하도록 구성됩니다. 예를 들면 다음과 같습니다.

Kotlin

if (Build.VERSION.SDK_INT >= 34) {
    placeholderInputField.setHandwritingDelegatorCallback {
        showAndFocusDelegateInputField()
    }
    delegateInputField.setIsHandwritingDelegate(true)
}

Java

if (Build.VERSION.SDK_INT >= 34) {
    placeholderInputField.setHandwritingDelegatorCallback(this::showAndFocusInputFieldDelegate);
    delegateInputField.setIsHandwritingDelegate(true);
}

자리표시자 텍스트 입력란 뷰 위에 있는 스타일러스 모션이 콜백을 호출합니다. 콜백은 UI 전환을 트리거하여 기능 입력란을 표시하고 포커스를 맞춥니다. 콜백 구현은 일반적으로 자리표시자 요소의 클릭 리스너 구현과 동일합니다. 기능 입력 필드에서 InputConnection가 생성되면 스타일러스 필기 입력 모드가 시작됩니다.

그림 4. 정적 UI 요소에서 텍스트 입력란으로 스타일러스 입력 위임

Material Design

com.google.android.material.search 라이브러리는 자리표시자 UI 패턴 구현을 용이하게 하기 위해 SearchBar 및 SearchView 클래스를 제공합니다.

자리표시자 및 기능 검색 뷰는 setUpWithSearchBar()로 연결됩니다.

필기 입력 위임은 Material 라이브러리에서 구성되며 앱을 추가로 개발할 필요가 없습니다.

그리기 표면과 겹침

앱에 표면에 텍스트 필드가 오버레이된 그리기 노출 영역이 있는 경우 사용자가 그릴 수 있도록 스타일러스 필기 입력을 사용 중지해야 할 수 있습니다. setAutoHandwritingEnabled()를 참고하세요.

테스트

스타일러스 필기 입력은 호환되는 스타일러스 입력 기기와 Android 14 스타일러스 필기 입력 API를 지원하는 입력 방식 편집기 (IME)가 있는 Android 14 이상 기기에서 지원됩니다.

스타일러스 입력 기기가 없다면 다음 Android 디버그 브리지 (adb) 명령어를 사용하여 루트 액세스 권한이 있는 기기(에뮬레이터 포함)에서 스타일러스 입력을 시뮬레이션합니다.


// Android 14
adb shell setprop persist.debug.input.simulate_stylus_with_touch true && adb shell stop && adb shell start

// Android 15 and higher
// Property takes effect after screen reconfiguration such as orientation change.
adb shell setprop debug.input.simulate_stylus_with_touch true

스타일러스를 지원하지 않는 기기를 사용하는 경우 테스트용으로 Gboard 베타를 사용합니다.

추가 리소스

Material Design — 텍스트 필드
맞춤 텍스트 편집기