處理使用者輸入內容

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

選擇 TextField 實作方式

TextField 實作分為兩個層級:

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

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

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

含有字詞的可編輯文字欄位

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

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

可編輯的文字欄位,帶有紫色邊框和標籤。

樣式 TextField

TextFieldBasicTextField 共用許多常用參數,可供自訂 具體做法是指示 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)
    )
}

多行 TextField,含有兩行可編輯行加上標籤

如果設計需要TextFieldBasicTextField Material TextFieldOutlineTextField。不過,應使用 BasicTextField

使用 Brush API 設定樣式輸入

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

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

使用 TextStyle 實作彩色漸層

如要在 TextField 中輸入時實作彩色漸層,請設定筆刷 做為 TextFieldTextStyle。本例使用 內建 linearGradient 的筆刷,可檢視彩虹梯度效果,如 文字會輸入至 TextField

var text by remember { mutableStateOf("") }
val brush = remember {
    Brush.linearGradient(
        colors = rainbowColors
    )
}
TextField(
    value = text, onValueChange = { text = it }, textStyle = TextStyle(brush = brush)
)

使用 buildAnnotatedString、SpanStyle 和 LinearGradient 來自訂一段文字。
圖 3.使用 buildAnnotatedStringSpanStyle 搭配 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)
    )
}

密碼文字輸入欄位,文字遮蓋

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

清除輸入

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

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

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

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

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

狀態的最佳做法

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

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

class SignUpViewModel : ViewModel() {

    var username by mutableStateOf("")
        private set

    /* ... */
}

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

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