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 phương thức triển khai TextField

Có hai 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ì cách này tuân theo các nguyên tắc Material Design:
   • 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 bàn phím phần cứng hoặc phần mềm, nhưng không cung cấp đồ 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

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

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

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

Bạn nên sử dụng TextField thay vì BasicTextField khi thiết kế yêu cầu một Material TextField hoặc OutlinedTextField. 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ể sử dụng Brush API để tạo kiểu nâng cao hơn trong TextField. Phần sau đây mô tả cách bạn có thể sử dụng Bút vẽ để thêm hiệu ứng chuyển màu vào dữ liệu đầ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ẽ.

Thận trọng: Việc sử dụng hiện tại của Brush API trong TextStyle đang ở giai đoạn thử nghiệm. API thử nghiệm có thể thay đổi trong tương lai.

Triển khai hiệu ứng chuyển màu bằng TextStyle

Để triển khai độ dốc 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

Lưu ý: Hãy nhớ sử dụng hàm remember để duy trì bút vẽ trên các lần kết hợp lại, khi trạng thái TextField thay đổi trên mỗi ký tự mới được nhập.

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 đầu vào

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

Bạn có thể xem thêm các 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 đề liên quan đến đầ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 độ trễ khi cập nhật trạng thái: Khi bạn gọi onValueChange, hãy cập nhật TextField đồ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

• Vị trí xác định trạng thái: Nếu trạng thái TextField của bạn yêu cầu xác thực logic nghiệp vụ khi bạn nhập, thì bạn nên chuyển trạng thái lên 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 làm 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).

Lưu ý: Để biết thêm thông tin về các phương pháp hay nhất này, hãy xem bài đăng trên blog Quản lý trạng thái hiệu quả cho TextField trong Compose.