Xử lý hoạt động đầu vào của người dùng

TextField cho phép người dùng nhập và sửa đổi văn bản. Trang này mô tả cách bạn có thể triển khai TextField, tạo kiểu cho đầu vào TextField và định cấu hình các tuỳ chọn TextField khác, chẳng hạn như tuỳ chọn bàn phím và biến đổi hình ảnh hoạt động đầu vào của người dùng.

Chọn cách triển khai TextField

Có 2 cấp độ triển khai TextField:

  1. TextField là cách triển khai Material Design. Bạn nên chọn cách triển khai này vì nó tuân theo Material Design nguyên tắc:
    • Kiểu mặc định là filled
    • OutlinedTextField là phiên bản định kiểu outline
  2. BasicTextField cho phép người dùng chỉnh sửa văn bản thông qua phần cứng hoặc phần mềm bàn phím nhưng không cung cấp thành phần trang trí như gợi ý hoặc phần giữ chỗ.

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

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

Một trường văn bản có thể chỉnh sửa có chứa từ 

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

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

Một trường văn bản có thể chỉnh sửa với đường viền và nhãn màu tím.

Kiểu TextField

TextField và BasicTextField cùng có chung nhiều thông số phổ biến để tuỳ chỉnh các thông số đó. Danh sách đầy đủ cho TextField có sẵn trong nguồn TextField . Đây là danh sách không đầy đủ một vài thông số hữu ích:

  • 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

Một TextField nhiều dòng, có hai dòng có thể chỉnh sửa cùng với nhãn

Bạn nên dùng TextField thay vì BasicTextField khi thiết kế yêu cầu một Chất liệu TextField hoặc OutlineTextField. Tuy nhiên, bạn nên dùng BasicTextField khi tạo thiết kế không cần trang trí từ thông số Material.

Nhập kiểu bằng API Bút vẽ

Bạn có thể dùng Brush API để tạo kiểu nâng cao hơn trong TextField. Chiến lược phát hành đĩa đơn phần sau mô tả cách bạn có thể sử dụng Bút vẽ để thêm dải chuyển màu cho đầu vào TextField.

Để biết thêm thông tin về cách sử dụng API Bút vẽ để tạo kiểu cho văn bản, hãy xem Bật tính năng tạo kiểu nâng cao bằng API Bút vẽ.

Triển khai độ dốc màu bằng TextStyle

Để triển khai độ dốc màu khi bạn nhập trong TextField, hãy thiết lập bút vẽ lựa chọn làm TextStyle cho TextField của bạn. Trong ví dụ này, chúng tôi sử dụng bút vẽ tích hợp có linearGradient để xem hiệu ứng chuyển màu cầu vồng dưới dạng được nhập vào 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

Sử dụng buildAnnotationdString và SpanStyle, cùng với linearGradient để chỉ tuỳ chỉnh một đoạn văn bản.
Hình 3. Sử dụng buildAnnotatedString và SpanStyle cùng với linearGradient để tuỳ chỉnh một đoạn văn bản.

Đặt tuỳ chọn bàn phím

TextField cho phép bạn cài đặt các tuỳ chọn cấu hình bàn phím, chẳng hạn như bố cục bàn phím hoặc bật tính năng tự động sửa lỗi nếu được bàn phím hỗ trợ. Một số tuỳ chọn có thể không được đảm bảo nếu bàn phím phần mềm không tuân thủ các tuỳ chọn được cung cấp ở đây. Dưới đây là danh sách các bàn phím được hỗ trợ tuỳ chọn:

  • capitalization
  • autoCorrect
  • keyboardType
  • imeAction

Định dạng phương thức nhập

TextField cho phép bạn thiết lập VisualTransformation trên giá trị nhập, ví dụ như thay thế các ký tự bằng * đối với mật khẩu hoặc chèn dấu gạch ngang cứ sau 4 chữ số đối với số thẻ tín dụng:

@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

Một trường văn bản nhập mật khẩu, với văn bản bị che

Bạn có thể xem thêm ví dụ trong mã nguồn VisualTransformationSamples.

Xoá dữ liệu đầu vào

Một tác vụ phổ biến khi chỉnh sửa văn bản là xoá các ký tự ở đầu hoặc biến đổi chuỗi nhập vào mỗi khi có sự thay đổi.

Như một mô hình, bạn nên giả định rằng bàn phím có thể tạo ra chỉnh sửa lớn và tuỳ ý cho từng onValueChange. Điều này có thể xảy ra, ví dụ như khi người dùng sử dụng tính năng tự động sửa, thay thế một từ bằng một biểu tượng cảm xúc hoặc các tính năng chỉnh sửa thông minh khác. Để xử lý chính xác điều này, hãy viết bất kỳ logic chuyển đổi nào với giả định rằng văn bản hiện tại đã được chuyển đến onValueChange không liên quan đến các giá trị trước đó hoặc tiếp theo sẽ được chuyển tới onValueChange.

Để triển khai trường văn bản không cho phép các số 0 ở đầu, bạn có thể thực hiện bằng cách loại bỏ tất cả số 0 đứng đầu trên mọi thay đổi giá trị.

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

Để kiểm soát vị trí con trỏ khi xóa văn bản, hãy sử dụng phương thức nạp chồng TextFieldValue của TextField như là một phần của trạng thái.

Các phương pháp hay nhất về trạng thái

Sau đây là một loạt phương pháp hay nhất để xác định và cập nhật TextField để ngăn chặn các vấn đề về dữ liệu đầu vào trong ứng dụng của bạn.

  • Sử dụng MutableState để thể hiện trạng thái TextField: Tránh sử dụng các luồng phản ứng như StateFlow để thể hiện TextField, vì các cấu trúc này có thể gây ra độ trễ không đồng bộ.

class SignUpViewModel : ViewModel() {

    var username by mutableStateOf("")
        private set

    /* ... */
}
TextSnippets.kt

  • Tránh chậm trễ khi cập nhật tiểu bang: Khi bạn gọi onValueChange, hãy cập nhật TextField của bạn một cách đồng bộ và ngay lập tức:

// 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

  • Nơi xác định tiểu bang: Nếu tiểu bang TextField của bạn yêu cầu doanh nghiệp xác thực logic khi bạn nhập, việc chuyển trạng thái lên trên là chính xác ViewModel. Nếu không, bạn có thể sử dụng các thành phần kết hợp hoặc lớp phần tử giữ trạng thái như nguồn đáng tin cậy. Để tìm hiểu thêm về vị trí chuyển trạng thái lên trên, hãy xem tài liệu về state hoisting (chuyển trạng thái lên trên).