사용자 입력 처리

TextField를 사용하면 사용자가 텍스트를 입력하고 수정할 수 있습니다. 이 페이지에서는 TextField를 구현하고 TextField 입력의 스타일을 지정하며 기타 TextField 옵션(예: 키보드 옵션 및 시각적 변환) 사용자 입력입니다.

TextField 구현 선택

TextField 구현에는 두 가지 수준이 있습니다.

1. TextField는 머티리얼 디자인 구현입니다. 이 구현은 머티리얼 디자인을 따릅니다. 가이드라인을 참고하세요. <ph type="x-smartling-placeholder">
   </ph>
   • 기본 스타일이 채워집니다.
   • OutlinedTextField는 개요 스타일 버전입니다.
2. BasicTextField를 사용하면 사용자가 하드웨어나 소프트웨어를 통해 텍스트를 수정할 수 있습니다. 힌트나 자리표시자와 같은 장식은 제공하지 않습니다.

@Composable
fun SimpleFilledTextFieldSample() {
    var text by remember { mutableStateOf("Hello") }

    TextField(
        value = text,
        onValueChange = { text = it },
        label = { Text("Label") }
    )
}
TextSnippets.kt

@Composable
fun SimpleOutlinedTextFieldSample() {
    var text by remember { mutableStateOf("") }

    OutlinedTextField(
        value = text,
        onValueChange = { text = it },
        label = { Text("Label") }
    )
}
TextSnippets.kt

스타일 TextField

TextField 및 BasicTextField는 맞춤설정할 수 있는 많은 공통 매개변수를 공유합니다. TextField의 전체 목록은 TextField 소스에서 확인할 수 있습니다. 코드가 필요합니다. 다음은 유용한 매개변수의 일부 목록입니다.

• singleLine
• maxLines
• textStyle

@Composable
fun StyledTextField() {
    var value by remember { mutableStateOf("Hello\nWorld\nInvisible") }

    TextField(
        value = value,
        onValueChange = { value = it },
        label = { Text("Enter text") },
        maxLines = 2,
        textStyle = TextStyle(color = Color.Blue, fontWeight = FontWeight.Bold),
        modifier = Modifier.padding(20.dp)
    )
}
TextSnippets.kt

디자인에 다음이 필요한 경우 BasicTextField보다 TextField를 권장합니다. Material TextField 또는 OutlineTextField 하지만 BasicTextField를 사용해야 합니다. 을 사용합니다.

Brush API를 사용한 스타일 입력

Brush API를 사용하여 TextField에서 고급 스타일을 지정할 수 있습니다. 이 다음 섹션에서는 브러시를 사용하여 색상 그라데이션을 추가하는 방법을 설명합니다. TextField 입력.

Brush API를 사용하여 텍스트 스타일을 지정하는 방법에 대한 자세한 내용은 다음을 참조하세요. Brush API로 고급 스타일 지정을 사용 설정합니다.

주의: TextStyle에서 현재 Brush API를 사용하는 것은 실험용입니다. 실험용 API는 향후 변경될 수 있습니다.

TextStyle를 사용하여 색상 그라디언트 구현

TextField 내에 입력할 때 색상 그라데이션을 구현하려면 브러시를 설정하세요. TextField의 TextStyle로 선택합니다. 이 예에서는 무지개 그라데이션 효과를 볼 수 있는 linearGradient가 있는 기본 브러시 TextField에 입력됩니다.

var text by remember { mutableStateOf("") }
val brush = remember {
    Brush.linearGradient(
        colors = rainbowColors
    )
}
TextField(
    value = text, onValueChange = { text = it }, textStyle = TextStyle(brush = brush)
)
TextSnippets.kt

참고: remember 함수를 사용하여 브러시가 계속 유지되도록 해야 합니다. 리컴포지션. 새로운 유형이 지정된 각 문자에서 TextField 상태가 변경될 때.

<ph type="x-smartling-placeholder">

</ph>

그림 3. buildAnnotatedString 및 SpanStyle를 linearGradient과 함께 사용하여 텍스트 일부만 맞춤설정합니다.

키보드 옵션 설정

TextField를 사용하면 키보드 레이아웃과 같은 키보드 구성 옵션을 설정하거나 키보드에서 지원하는 경우 자동 수정을 사용 설정할 수 있습니다. 소프트웨어 키보드가 여기에 제공된 옵션을 준수하지 않을 경우 일부 옵션이 보장되지 않을 수도 있습니다. 지원되는 키보드 목록은 다음과 같습니다. 옵션을 사용합니다.

• capitalization
• autoCorrect
• keyboardType
• imeAction

형식 입력

TextField를 사용하면 입력 값에 VisualTransformation을 설정할 수 있습니다. 예를 들어 비밀번호를 나타내는 문자를 * 기호로 바꾸거나 신용카드 번호의 4자리마다 하이픈을 삽입할 수 있습니다.

@Composable
fun PasswordTextField() {
    var password by rememberSaveable { mutableStateOf("") }

    TextField(
        value = password,
        onValueChange = { password = it },
        label = { Text("Enter password") },
        visualTransformation = PasswordVisualTransformation(),
        keyboardOptions = KeyboardOptions(keyboardType = KeyboardType.Password)
    )
}
TextSnippets.kt

VisualTransformationSamples 소스 코드에서 더 많은 예를 확인할 수 있습니다.

입력 지우기

텍스트를 수정할 때 일반적인 작업은 변경 시 선행 문자를 제거하거나 입력 문자열을 변환하는 것입니다.

모델에서는 키보드가 임의 및 대규모로 onValueChange를 각각 수정할 수 있다고 가정합니다. 예를 들어 사용자가 자동 수정을 사용하거나, 단어를 그림 이모티콘으로 대체하거나, 그 밖의 스마트 편집 기능이 있는 경우 이러한 상황이 발생할 수 있습니다. 이를 올바르게 처리하려면 onValueChange에 전달된 현재 텍스트가 onValueChange에 전달될 이전 또는 다음 값과 관련이 없다는 가정 하에 모든 변환 로직을 작성합니다.

앞의 0을 허용하지 않는 텍스트 입력란을 구현하려면 모든 값을 변경할 때 선행 0을 전부 제거하면 됩니다.

@Composable
fun NoLeadingZeroes() {
    var input by rememberSaveable { mutableStateOf("") }
    TextField(
        value = input,
        onValueChange = { newText ->
            input = newText.trimStart { it == '0' }
        }
    )
}
TextSnippets.kt

텍스트를 정리하는 동안 커서 위치를 제어하려면 상태의 일부로 TextField의 TextFieldValue 오버로드를 사용하세요.

상태 관련 권장사항

다음은 TextField를 정의하고 업데이트하기 위한 권장사항입니다. 앱의 입력 문제를 방지할 수 있습니다.

• MutableState를 사용하여 TextField 상태 표현: StateFlow 같은 반응형 스트림을 사용해 TextField 상태에 있을 수 있습니다.

class SignUpViewModel : ViewModel() {

    var username by mutableStateOf("")
        private set

    /* ... */
}
TextSnippets.kt

• 상태 업데이트를 위한 지연 방지: onValueChange를 호출하면 TextField를 동기식으로 즉시 동기화:

// SignUpViewModel.kt

class SignUpViewModel(private val userRepository: UserRepository) : ViewModel() {

    var username by mutableStateOf("")
        private set

    fun updateUsername(input: String) {
        username = input
    }
}

// SignUpScreen.kt

@Composable
fun SignUpScreen(/*...*/) {

    OutlinedTextField(
        value = viewModel.username,
        onValueChange = { username -> viewModel.updateUsername(username) }
        /*...*/
    )
}
TextSnippets.kt

• 주를 정의할 위치: TextField 주에 비즈니스가 필요한 경우 로직에 대한 유효성 검사가 필요하다면 상태를 ViewModel입니다. 그렇지 않은 경우 컴포저블 또는 상태 홀더 클래스를 다음과 같이 사용할 수 있습니다. 소스 저장소입니다 상태를 끌어올릴 위치에 관한 자세한 내용은 다음을 참고하세요. 상태 호이스팅 문서를 참조하세요.

를 통해 개인정보처리방침을 정의할 수 있습니다.

참고: 이러한 권장사항에 대한 자세한 내용은 Compose에서 TextField의 효과적인 상태 관리 블로그 게시물