Di chuyển sang trường văn bản dựa trên trạng thái

Trang này cung cấp các ví dụ về cách di chuyển TextField dựa trên giá trị sang TextField dựa trên trạng thái. Hãy xem trang Định cấu hình trường văn bản để biết thông tin về sự khác biệt giữa TextField dựa trên giá trị và trạng thái.

Cách sử dụng cơ bản

Dựa trên giá trị

@Composable
fun OldSimpleTextField() {
    var state by rememberSaveable { mutableStateOf("") }
    TextField(
        value = state,
        onValueChange = { state = it },
        singleLine = true,
    )
}
TextFieldMigrationSnippets.kt

Dựa trên trạng thái

@Composable
fun NewSimpleTextField() {
    TextField(
        state = rememberTextFieldState(),
        lineLimits = TextFieldLineLimits.SingleLine
    )
}
TextFieldMigrationSnippets.kt

  • Thay thế value, onValueChange và remember { mutableStateOf("") } bằng rememberTextFieldState().
  • Thay thế singleLine = true với lineLimits = TextFieldLineLimits.SingleLine.

Lọc qua onValueChange

Dựa trên giá trị

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

Dựa trên trạng thái

@Preview
@Composable
fun NewNoLeadingZeros() {
    TextField(
        state = rememberTextFieldState(),
        inputTransformation = InputTransformation {
            while (length > 0 && charAt(0) == '0') delete(0, 1)
        }
    )
}
TextFieldMigrationSnippets.kt

  • Thay thế vòng lặp gọi lại giá trị bằng rememberTextFieldState().
  • Triển khai lại logic lọc trong onValueChange bằng cách sử dụng InputTransformation.
  • Sử dụng TextFieldBuffer trong phạm vi bộ thu của InputTransformation để cập nhật state.
    • InputTransformation được gọi ngay sau khi phát hiện thấy hoạt động đầu vào của người dùng.
    • Các thay đổi do InputTransformation đề xuất thông qua TextFieldBuffer sẽ được áp dụng ngay lập tức, tránh vấn đề đồng bộ hoá giữa bàn phím phần mềm và TextField.

Trình định dạng thẻ tín dụng TextField

Dựa trên giá trị

@Composable
fun OldTextFieldCreditCardFormatter() {
    var state by remember { mutableStateOf("") }
    TextField(
        value = state,
        onValueChange = { if (it.length <= 16) state = it },
        visualTransformation = VisualTransformation { text ->
            // Making XXXX-XXXX-XXXX-XXXX string.
            var out = ""
            for (i in text.indices) {
                out += text[i]
                if (i % 4 == 3 && i != 15) out += "-"
            }

            TransformedText(
                text = AnnotatedString(out),
                offsetMapping = object : OffsetMapping {
                    override fun originalToTransformed(offset: Int): Int {
                        if (offset <= 3) return offset
                        if (offset <= 7) return offset + 1
                        if (offset <= 11) return offset + 2
                        if (offset <= 16) return offset + 3
                        return 19
                    }

                    override fun transformedToOriginal(offset: Int): Int {
                        if (offset <= 4) return offset
                        if (offset <= 9) return offset - 1
                        if (offset <= 14) return offset - 2
                        if (offset <= 19) return offset - 3
                        return 16
                    }
                }
            )
        }
    )
}
TextFieldMigrationSnippets.kt

Dựa trên trạng thái

@Composable
fun NewTextFieldCreditCardFormatter() {
    val state = rememberTextFieldState()
    TextField(
        state = state,
        inputTransformation = InputTransformation.maxLength(16),
        outputTransformation = OutputTransformation {
            if (length > 4) insert(4, "-")
            if (length > 9) insert(9, "-")
            if (length > 14) insert(14, "-")
        },
    )
}
TextFieldMigrationSnippets.kt

  • Thay thế bộ lọc trong onValueChange bằng InputTransformation để đặt chiều dài tối đa của dữ liệu đầu vào.
  • Thay thế VisualTransformation bằng OutputTransformation để thêm dấu gạch ngang.
    • Với VisualTransformation, bạn chịu trách nhiệm tạo văn bản mới bằng dấu gạch ngang và tính toán cách ánh xạ các chỉ mục giữa văn bản hình ảnh và trạng thái sao lưu.
    • OutputTransformation sẽ tự động xử lý việc ánh xạ độ dời. Bạn chỉ cần thêm dấu gạch ngang vào đúng vị trí bằng cách sử dụng TextFieldBuffer từ phạm vi bộ thu của OutputTransformation.transformOutput.

Cập nhật trạng thái (đơn giản)

Dựa trên giá trị

@Composable
fun OldTextFieldStateUpdate(userRepository: UserRepository) {
    var username by remember { mutableStateOf("") }
    LaunchedEffect(Unit) {
        username = userRepository.fetchUsername()
    }
    TextField(
        value = username,
        onValueChange = { username = it }
    )
}
TextFieldMigrationSnippets.kt

Dựa trên trạng thái

@Composable
fun NewTextFieldStateUpdate(userRepository: UserRepository) {
    val usernameState = rememberTextFieldState()
    LaunchedEffect(Unit) {
        usernameState.setTextAndPlaceCursorAtEnd(userRepository.fetchUsername())
    }
    TextField(state = usernameState)
}
TextFieldMigrationSnippets.kt

  • Thay thế vòng lặp gọi lại giá trị bằng rememberTextFieldState().
  • Thay đổi giá trị chỉ định bằng TextFieldState.setTextAndPlaceCursorAtEnd.

Cập nhật trạng thái (phức tạp)

Dựa trên giá trị

@Composable
fun OldTextFieldAddMarkdownEmphasis() {
    var markdownState by remember { mutableStateOf(TextFieldValue()) }
    Button(onClick = {
        // add ** decorations around the current selection, also preserve the selection
        markdownState = with(markdownState) {
            copy(
                text = buildString {
                    append(text.take(selection.min))
                    append("**")
                    append(text.substring(selection))
                    append("**")
                    append(text.drop(selection.max))
                },
                selection = TextRange(selection.min + 2, selection.max + 2)
            )
        }
    }) {
        Text("Bold")
    }
    TextField(
        value = markdownState,
        onValueChange = { markdownState = it },
        maxLines = 10
    )
}
TextFieldMigrationSnippets.kt

Dựa trên trạng thái

@Composable
fun NewTextFieldAddMarkdownEmphasis() {
    val markdownState = rememberTextFieldState()
    LaunchedEffect(Unit) {
        // add ** decorations around the current selection
        markdownState.edit {
            insert(originalSelection.max, "**")
            insert(originalSelection.min, "**")
            selection = TextRange(originalSelection.min + 2, originalSelection.max + 2)
        }
    }
    TextField(
        state = markdownState,
        lineLimits = TextFieldLineLimits.MultiLine(1, 10)
    )
}
TextFieldMigrationSnippets.kt

Trong trường hợp sử dụng này, một nút sẽ thêm các phần trang trí Markdown để in đậm văn bản xung quanh con trỏ hoặc phần văn bản đang được chọn. Phương thức này cũng duy trì vị trí lựa chọn sau khi thay đổi.

  • Thay thế vòng lặp gọi lại giá trị bằng rememberTextFieldState().
  • Thay thế maxLines = 10 với lineLimits = TextFieldLineLimits.MultiLine(maxHeightInLines = 10).
  • Thay đổi logic tính toán TextFieldValue mới bằng lệnh gọi TextFieldState.edit.
    • TextFieldValue mới được tạo bằng cách nối văn bản hiện có dựa trên vùng chọn hiện tại và chèn các phần trang trí Markdown vào giữa.
    • Ngoài ra, lựa chọn được điều chỉnh theo các chỉ mục mới của văn bản.
    • TextFieldState.edit có cách chỉnh sửa trạng thái hiện tại tự nhiên hơn bằng cách sử dụng TextFieldBuffer.
    • Lựa chọn này xác định rõ vị trí chèn các phần trang trí.
    • Sau đó, điều chỉnh lựa chọn tương tự như phương pháp onValueChange.

Cấu trúc StateFlow của ViewModel

Nhiều ứng dụng tuân theo Nguyên tắc phát triển ứng dụng hiện đại, trong đó khuyến khích sử dụng StateFlow để xác định trạng thái giao diện người dùng của một màn hình hoặc một thành phần thông qua một lớp không thể thay đổi duy nhất chứa tất cả thông tin.

Trong các loại ứng dụng này, một biểu mẫu như màn hình Đăng nhập có phương thức nhập văn bản thường được thiết kế như sau:

class LoginViewModel : ViewModel() {
    private val _uiState = MutableStateFlow(UiState())
    val uiState: StateFlow<UiState>
        get() = _uiState.asStateFlow()

    fun updateUsername(username: String) = _uiState.update { it.copy(username = username) }

    fun updatePassword(password: String) = _uiState.update { it.copy(password = password) }
}

data class UiState(
    val username: String = "",
    val password: String = ""
)

@Composable
fun LoginForm(
    loginViewModel: LoginViewModel,
    modifier: Modifier = Modifier
) {
    val uiState by loginViewModel.uiState.collectAsStateWithLifecycle()
    Column(modifier) {
        TextField(
            value = uiState.username,
            onValueChange = { loginViewModel.updateUsername(it) }
        )
        TextField(
            value = uiState.password,
            onValueChange = { loginViewModel.updatePassword(it) },
            visualTransformation = PasswordVisualTransformation()
        )
    }
}
TextFieldMigrationSnippets.kt

Thiết kế này phù hợp hoàn hảo với TextFields sử dụng mô hình chuyển trạng thái value, onValueChange lên trên. Tuy nhiên, có những nhược điểm không lường trước được của phương pháp này khi nhập văn bản. Các vấn đề về đồng bộ hoá sâu với phương pháp này được giải thích chi tiết trong bài đăng trên blog Quản lý trạng thái hiệu quả cho TextField trong Compose.

Vấn đề là thiết kế TextFieldState mới không tương thích trực tiếp với trạng thái giao diện người dùng ViewModel được StateFlow hỗ trợ. Có vẻ lạ khi thay thế username: String và password: String bằng username: TextFieldState và password: TextFieldState, vì TextFieldState vốn là một cấu trúc dữ liệu có thể thay đổi.

Bạn nên tránh đặt các phần phụ thuộc giao diện người dùng vào ViewModel. Mặc dù đây thường là một phương pháp hay, nhưng đôi khi có thể bị hiểu sai. Điều này đặc biệt đúng đối với các phần phụ thuộc Compose chỉ là cấu trúc dữ liệu và không mang theo bất kỳ thành phần giao diện người dùng nào, chẳng hạn như TextFieldState.

Các lớp như MutableState hoặc TextFieldState là các phần tử giữ trạng thái đơn giản được hệ thống trạng thái tổng quan nhanh của Compose hỗ trợ. Các phần phụ thuộc này không khác gì các phần phụ thuộc như StateFlow hoặc RxJava. Do đó,bạn nên đánh giá lại cách áp dụng nguyên tắc "không có phần phụ thuộc giao diện người dùng trong ViewModel" trong mã của mình. Việc giữ lại tệp đối chiếu đến TextFieldState trong ViewModel không phải là một phương pháp tệ.

Bạn nên trích xuất các giá trị như username hoặc password từ UiState và lưu giữ tham chiếu riêng cho các giá trị đó trong ViewModel.

class LoginViewModel : ViewModel() {
    val usernameState = TextFieldState()
    val passwordState = TextFieldState()
}

@Composable
fun LoginForm(
    loginViewModel: LoginViewModel,
    modifier: Modifier = Modifier
) {
    Column(modifier) {
        TextField(state = loginViewModel.usernameState,)
        SecureTextField(state = loginViewModel.passwordState)
    }
}
TextFieldMigrationSnippets.kt

  • Thay thế MutableStateFlow<UiState> bằng một vài giá trị TextFieldState.
  • Truyền các đối tượng TextFieldState đó đến TextFields trong thành phần kết hợp LoginForm.

Phương pháp tuân thủ

Những loại thay đổi về cấu trúc này không phải lúc nào cũng dễ dàng. Bạn có thể không có quyền tự do thực hiện những thay đổi này hoặc thời gian đầu tư có thể lớn hơn lợi ích của việc sử dụng TextField mới. Trong trường hợp này, bạn vẫn có thể sử dụng các trường văn bản dựa trên trạng thái bằng một chút điều chỉnh.

class LoginViewModel : ViewModel() {
    private val _uiState = MutableStateFlow(UiState())
    val uiState: StateFlow<UiState>
        get() = _uiState.asStateFlow()

    fun updateUsername(username: String) = _uiState.update { it.copy(username = username) }

    fun updatePassword(password: String) = _uiState.update { it.copy(password = password) }
}

data class UiState(
    val username: String = "",
    val password: String = ""
)

@Composable
fun LoginForm(
    loginViewModel: LoginViewModel,
    modifier: Modifier = Modifier
) {
    val initialUiState = remember(loginViewModel) { loginViewModel.uiState.value }
    Column(modifier) {
        val usernameState = rememberTextFieldState(initialUiState.username)
        LaunchedEffect(usernameState) {
            snapshotFlow { usernameState.text.toString() }.collectLatest {
                loginViewModel.updateUsername(it)
            }
        }
        TextField(usernameState)

        val passwordState = rememberTextFieldState(initialUiState.password)
        LaunchedEffect(usernameState) {
            snapshotFlow { usernameState.text.toString() }.collectLatest {
                loginViewModel.updatePassword(it)
            }
        }
        SecureTextField(passwordState)
    }
}
TextFieldMigrationSnippets.kt

  • Giữ nguyên các lớp ViewModel và UiState.
  • Thay vì chuyển trạng thái trực tiếp vào ViewModel và biến trạng thái đó thành nguồn đáng tin cậy cho TextFields, hãy chuyển ViewModel thành một trình lưu giữ dữ liệu đơn giản.
    • Để làm việc này, hãy quan sát các thay đổi đối với từng TextFieldState.text bằng cách thu thập snapshotFlow trong LaunchedEffect.
  • ViewModel của bạn vẫn sẽ có các giá trị mới nhất từ giao diện người dùng, nhưng uiState: StateFlow<UiState> của nó sẽ không điều khiển TextField.
  • Mọi logic cố định khác được triển khai trong ViewModel của bạn đều có thể giữ nguyên.