處理使用者輸入內容

TextField 可讓使用者輸入及修改文字。本頁面將說明 可實作 TextField、設定 TextField 輸入樣式，並設定 其他 TextField 選項，例如鍵盤選項和視覺轉換 使用者輸入內容

選擇 TextField 實作方式

TextField 實作分為兩個層級：

1. TextField 為質感設計實作。建議您選擇 因為它採用 Material Design 指南：
   • 已填入預設樣式
   • OutlinedTextField是 outline 樣式版本
2. BasicTextField 可讓使用者透過硬體或軟體編輯文字 但未提供提示或預留位置等裝飾

@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

樣式 TextField

TextField 和 BasicTextField 共用許多常用參數，可供自訂 具體做法是指示 Kubernetes 建立並維護 一或多個代表這些 Pod 的物件您可以在 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)
    )
}
TextSnippets.kt

如果設計需要TextFieldBasicTextField Material TextField 或 OutlineTextField。不過，應使用 BasicTextField 。

使用 Brush API 設定樣式輸入

您可以在 TextField 中使用 Brush API 使用更進階的樣式。 下一節說明如何使用筆刷新增彩色漸層 「TextField」輸入內容。

如要進一步瞭解如何使用 Brush API 設定文字樣式，請參閱 使用 Brush API 啟用進階樣式。

注意： 目前在 TextStyle 中使用 Brush API 的實驗功能。 實驗性 API 日後可能會變更。

使用 TextStyle 實作彩色漸層

如要在 TextField 中輸入時實作彩色漸層，請設定筆刷 做為 TextField 的 TextStyle。本例使用 內建 linearGradient 的筆刷，可檢視彩虹梯度效果，如 文字會輸入至 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

注意： 請務必使用 remember 函式，讓筆刷在 重新組成，當 TextField 狀態隨著每個新輸入的字元改變時。

圖 3.使用 buildAnnotatedString 和 SpanStyle 搭配 linearGradient，即可僅自訂一段文字。

設定鍵盤選項

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)
    )
}
TextSnippets.kt

如需更多範例，請參閱 VisualTransformationSamples 原始碼。

清除輸入

編輯文字的常見工作是移除開頭的字元，或是 轉換輸入字串。

以模型來說，您應假設鍵盤具有任意變化和更大的尺寸 編輯每個onValueChange。舉例來說，如果使用者使用 自動更正、使用表情符號取代字詞，或其他智慧編輯功能。目的地： 正確處理此情況並編寫任何轉換邏輯，假設 傳遞至 onValueChange 的目前文字與上一個或下一個文字無關 值，以便傳遞至 onValueChange。

如要實作不允許內容開頭為零的文字欄位，請執行下列步驟： 在每次值變更時去除所有開頭的零

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

如要在清理文字時控制遊標位置，請使用 TextFieldValue TextField 超載 作為狀態的一部分

狀態的最佳做法

以下是定義及更新 TextField 的一系列最佳做法 狀態，以免應用程式中的輸入問題發生。

• 使用 MutableState 代表 TextField 狀態：避免 再使用回應式串流 (例如 StateFlow) TextField 狀態，因為這些結構可能會導致非同步延遲。

class SignUpViewModel : ViewModel() {

    var username by mutableStateOf("")
        private set

    /* ... */
}
TextSnippets.kt

• 避免延遲更新狀態：呼叫 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) }
        /*...*/
    )
}
TextSnippets.kt

• 定義狀態的位置：如果 TextField 狀態需要商家 進行邏輯驗證時，正確的做法是將狀態提升至 ViewModel。如果不是，您可以使用可組合函式或狀態容器類別 並產生可靠結果如要進一步瞭解提升狀態的位置，請參閱 狀態提升說明文件。

，瞭解如何調查及移除這項存取權。

注意： 如要進一步瞭解這些最佳做法，請參閱 在 Compose 中有效管理 TextField 的狀態網誌文章。