텍스트 필드에 포커스

사용자가 하드웨어 키보드, D패드 또는 로터리 컨트롤러로 Compose UI를 탐색하면 텍스트 필드가 다른 포커스 타겟과 함께 포커스 탐색에 참여합니다.

기본적으로 포커스는 텍스트 필드에 고정되지 않습니다. 사용자가 텍스트 필드를 벗어날 수 있도록 맞춤 키 이벤트 핸들러 (onKeyEvent 또는 onPreviewKeyEvent)를 추가할 필요는 없습니다. 사용자는 언제든지 Shift+Tab을 사용하거나 방향 키로 텍스트 경계를 지나 탐색하여 종료할 수 있습니다.

KeyboardOptions는 하드웨어 키보드 탐색과 조정되는 직관적인 소프트웨어 키보드 작업을 제공하는 데 사용할 수 있습니다. 예를 들어 ImeAction.Next는 포커스를 다음 포커스 타겟으로 이동합니다.

일차원 포커스 순회

1차원 포커스 순회에서 Tab 키의 동작은 텍스트 필드에 구성된 lineLimits에 따라 다릅니다.

• 단일 행 텍스트 필드 (TextFieldLineLimits.SingleLine) Tab 키를 누르면 포커스가 UI의 다음 포커스 타겟으로 이동합니다.
• 여러 줄 텍스트 필드 (TextFieldLineLimits.MultiLine() 또는 기본값): Tab 키를 누르면 포커스가 이동하는 대신 텍스트 버퍼에 탭 문자 (\t)가 삽입됩니다.
• 역방향 탐색 (Shift+Tab): Shift+Tab을 누르면 단일 행 및 다중 행 텍스트 필드에서 무조건 포커스가 이전 포커스 타겟으로 뒤로 이동합니다.

// Single-line text field: Tab advances focus to the next focus target
BasicTextField(
    state = singleLineState,
    lineLimits = TextFieldLineLimits.SingleLine,
    modifier = Modifier.fillMaxWidth()
)

// Multi-line text field: Tab inserts '\t'; Shift + Tab moves to previous target
BasicTextField(
    state = multiLineState,
    lineLimits = TextFieldLineLimits.MultiLine(),
    modifier = Modifier.fillMaxWidth()
)
FocusInTextFields.kt

2차원 포커스 순회

화살표 키 (또는 D패드)를 사용하면 방향 키가 먼저 텍스트 입력란 내에서 텍스트 커서 (캐럿)를 이동합니다.

• 세로 탐색 (위 / 아래): Down 키를 누르면 캐럿이 한 줄씩 아래로 이동합니다. 캐럿이 마지막 줄에 도달한 경우 아래쪽 키를 다시 누르면 포커스가 텍스트 필드 아래의 인접한 포커스 타겟으로 트랜스퍼됩니다. 첫 번째 줄에서 위쪽 키를 누르면 포커스가 이전 포커스 타겟으로 이동합니다.
• 가로 탐색 (왼쪽 / 오른쪽 / 시작 / 끝): 가로 화살표 키를 누르면 캐럿이 글자를 통과하여 이동합니다. 캐럿이 텍스트 버퍼의 시작 또는 끝에 도달하면 방향 키를 다시 눌러 해당 방향의 인접한 포커스 타겟으로 포커스를 트랜스퍼합니다.

Android TV의 텍스트 필드

Android TV에서 실제 키보드 없이 D패드 컨트롤러를 사용하는 경우:

1. 포커스를 텍스트 필드로 이동하면 터치 소프트웨어 키보드가 자동으로 표시됩니다.
2. 사용자가 D패드를 사용하여 소프트웨어 키보드의 키를 탐색합니다.
3. 뒤로 버튼을 누르면 텍스트 필드에 포커스가 유지되면서 소프트 키보드가 닫힙니다.
4. 소프트웨어 키보드가 닫히면 D패드 방향 키를 눌러 화면의 인접한 포커스 타겟으로 포커스를 이동합니다.
5. 뒤로 버튼을 두 번째로 누르면 표준 시스템 뒤로 탐색이 트리거됩니다.