사용자 입력 처리

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

TextField 구현 선택

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

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

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

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

수정 가능한 텍스트 필드

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

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

보라색 테두리와 라벨이 있는 수정 가능한 텍스트 입력란.

스타일 TextField

TextFieldBasicTextField는 맞춤설정할 수 있는 많은 공통 매개변수를 공유합니다. 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)
    )
}

여러 줄의 TextField, 수정 가능한 두 줄과 라벨이 있음

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

Brush API를 사용한 스타일 입력

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

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

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

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

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

<ph type="x-smartling-placeholder">
</ph> linearGRadient와 함께 buildAnnotatedString 및 SpanStyle을 사용하여 텍스트 일부만 맞춤설정합니다.
그림 3. buildAnnotatedStringSpanStylelinearGradient과 함께 사용하여 텍스트 일부만 맞춤설정합니다.

키보드 옵션 설정

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)
    )
}

비밀번호 텍스트 입력란, 텍스트는 가려짐

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

입력 지우기

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

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

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

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

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

상태 관련 권장사항

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

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

class SignUpViewModel : ViewModel() {

    var username by mutableStateOf("")
        private set

    /* ... */
}

  • 상태 업데이트를 위한 지연 방지: 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) }
        /*...*/
    )
}

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