textfield-best-practices

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

TextField Best Practices

TextField 最佳实践

Description: When building forms or search inputs using TextFields in Jetpack Compose, follow these practical rules to ensure a seamless and accessible user experience.

说明：在使用Jetpack Compose的TextField构建表单或搜索输入时，请遵循以下实用规则，以确保流畅且无障碍的用户体验。

1. Window Insets & IME Padding

1. 窗口内边距与输入法填充

Always ensure the parent or top-level scrolling container has

Modifier.imePadding()

applied. This ensures that when the on-screen keyboard appears, the UI automatically scrolls or adjusts so that the focused TextField is not obscured.

kotlin

Scaffold(
    modifier = Modifier.imePadding(),
    // ...
) { padding ->
    LazyColumn(modifier = Modifier.padding(padding)) {
        // ...
    }
}

务必确保父容器或顶级滚动容器应用了

Modifier.imePadding()

。这样可以确保当屏幕键盘弹出时，UI会自动滚动或调整，使获得焦点的TextField不会被遮挡。

kotlin

Scaffold(
    modifier = Modifier.imePadding(),
    // ...
) { padding ->
    LazyColumn(modifier = Modifier.padding(padding)) {
        // ...
    }
}

2. Keyboard Options & Capitalization

2. 键盘选项与大小写设置

Always apply appropriate

KeyboardOptions

to your TextFields. Specify the

capitalization

rules based on the expected input (e.g.,

KeyboardCapitalization.Words

for names,

KeyboardCapitalization.Sentences

for descriptions).

务必为TextField设置合适的

KeyboardOptions

。根据预期输入内容指定大小写规则（例如，姓名使用

KeyboardCapitalization.Words

，描述文本使用

KeyboardCapitalization.Sentences

）。

3. IME Actions & Focus Navigation (Forms)

3. 输入法操作与焦点导航（表单场景）

For forms with multiple inputs, configure the

imeAction

to guide the user:

Use
```
ImeAction.Next
```
for all fields except the last one.
Use
```
ImeAction.Done
```
for the final field to complete the form.
Use
```
keyboardActions
```
to handle the focus movement explicitly.

kotlin

@Composable
fun UserForm() {
    val focusManager = LocalFocusManager.current
    var firstName by remember { mutableStateOf("") }
    var lastName by remember { mutableStateOf("") }

    Column {
        OutlinedTextField(
            value = firstName,
            onValueChange = { firstName = it },
            label = { Text("First Name") },
            keyboardOptions = KeyboardOptions(
                capitalization = KeyboardCapitalization.Words,
                imeAction = ImeAction.Next
            ),
            keyboardActions = KeyboardActions(
                onNext = { focusManager.moveFocus(FocusDirection.Down) }
            )
        )

        OutlinedTextField(
            value = lastName,
            onValueChange = { lastName = it },
            label = { Text("Last Name") },
            keyboardOptions = KeyboardOptions(
                capitalization = KeyboardCapitalization.Words,
                imeAction = ImeAction.Done
            ),
            keyboardActions = KeyboardActions(
                onDone = {
                    focusManager.clearFocus()
                    // Submit form
                }
            )
        )
    }
}

对于包含多个输入框的表单，配置

imeAction

来引导用户：

使用
```
ImeAction.Next
```
用于除最后一个字段外的所有字段。
使用
```
ImeAction.Done
```
用于最后一个字段以完成表单。
使用
```
keyboardActions
```
显式处理焦点移动。

kotlin

@Composable
fun UserForm() {
    val focusManager = LocalFocusManager.current
    var firstName by remember { mutableStateOf("") }
    var lastName by remember { mutableStateOf("") }

    Column {
        OutlinedTextField(
            value = firstName,
            onValueChange = { firstName = it },
            label = { Text("First Name") },
            keyboardOptions = KeyboardOptions(
                capitalization = KeyboardCapitalization.Words,
                imeAction = ImeAction.Next
            ),
            keyboardActions = KeyboardActions(
                onNext = { focusManager.moveFocus(FocusDirection.Down) }
            )
        )

        OutlinedTextField(
            value = lastName,
            onValueChange = { lastName = it },
            label = { Text("Last Name") },
            keyboardOptions = KeyboardOptions(
                capitalization = KeyboardCapitalization.Words,
                imeAction = ImeAction.Done
            ),
            keyboardActions = KeyboardActions(
                onDone = {
                    focusManager.clearFocus()
                    // Submit form
                }
            )
        )
    }
}

4. Explicit Search Inputs

4. 搜索专用输入框

When a TextField is used for searching, use

ImeAction.Search

to show the correct icon on the keyboard (a magnifying glass). Use

keyboardActions

with

onSearch

to trigger the search event and clear focus to hide the keyboard.

kotlin

@Composable
fun SearchBar(
    query: String,
    onQueryChanged: (String) -> Unit,
    onSearchTriggered: () -> Unit
) {
    val focusManager = LocalFocusManager.current

    OutlinedTextField(
        value = query,
        onValueChange = onQueryChanged,
        placeholder = { Text("Search...") },
        singleLine = true,
        keyboardOptions = KeyboardOptions(
            capitalization = KeyboardCapitalization.Sentences,
            imeAction = ImeAction.Search
        ),
        keyboardActions = KeyboardActions(
            onSearch = {
                focusManager.clearFocus() // Hide keyboard
                onSearchTriggered() // Execute the explicit search action
            }
        )
    )
}

当TextField用于搜索功能时，使用

ImeAction.Search

让键盘显示正确的图标（放大镜）。结合

keyboardActions

的

onSearch

来触发搜索事件，并清除焦点以隐藏键盘。

kotlin

@Composable
fun SearchBar(
    query: String,
    onQueryChanged: (String) -> Unit,
    onSearchTriggered: () -> Unit
) {
    val focusManager = LocalFocusManager.current

    OutlinedTextField(
        value = query,
        onValueChange = onQueryChanged,
        placeholder = { Text("Search...") },
        singleLine = true,
        keyboardOptions = KeyboardOptions(
            capitalization = KeyboardCapitalization.Sentences,
            imeAction = ImeAction.Search
        ),
        keyboardActions = KeyboardActions(
            onSearch = {
                focusManager.clearFocus() // Hide keyboard
                onSearchTriggered() // Execute the explicit search action
            }
        )
    )
}