テキスト フィールドを構成する

TextField を使用すると、ユーザーがテキストの入力や変更を行えるようになります。使用できるテキスト フィールドには、状態ベースのテキスト フィールドと値ベースのテキスト フィールドの 2 種類があります。コンテンツを表示するタイプを選択します。

状態ベースのテキスト フィールドを使用することをおすすめします。このフィールドは、TextField の状態を管理するためのより完全で信頼性の高いアプローチを提供します。次の表に、これらのテキスト フィールドの種類の違いと、状態ベースのテキスト フィールドの主な利点を示します。

このページでは、TextField を実装し、TextField 入力をスタイル設定し、キーボード オプションやユーザー入力の視覚的な変換など、他の TextField オプションを構成する方法について説明します。

TextField 実装を選択する

TextField の実装には次の 2 つのレベルがあります。

1. TextField はマテリアル デザインの実装であり、次のようなマテリアル デザイン ガイドラインに沿っているため、この実装を選択することをおすすめします。
   • デフォルトのスタイル設定は塗りつぶしです。
   • OutlinedTextField は、アウトラインのスタイル設定バージョンです。
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 は、カスタマイズ用のパラメータを多数共有しています。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

デザインにマテリアルの TextField または OutlinedTextField が必要な場合は、BasicTextField ではなく TextField をおすすめします。ただし、マテリアル仕様の装飾を必要としないデザインを構築する場合には、BasicTextField を使用する必要があります。

Brush API で入力をスタイル設定する

TextField でより高度なスタイル設定を行うには、Brush API を使用します。次のセクションでは、ブラシを使用して TextField 入力にカラー グラデーションを追加する方法について説明します。

Brush API を使用してテキストのスタイルを設定する方法については、Brush 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

テキスト フィールドの状態を管理する

アプリで入力に関する問題が発生しないように、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 にホイストするのが適切です。そうでない場合は、コンポーザブルまたは状態ホルダー クラスを信頼できる情報源として使用できます。状態をホイスティングする場所について詳しくは、状態ホイスティングのドキュメントをご覧ください。

ユーザー入力を変更する

以降のセクションでは、ユーザー入力を変更する方法について説明します。

入力のフォーマット

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

テキストを削除する際にカーソルの位置を制御するには、状態の一部として TextField の TextFieldValue オーバーロードを使用します。

キーボード オプションを設定する

TextField を使用すると、キーボード レイアウトなどのキーボード構成オプションを設定できます。また、キーボードでサポートされている場合は、自動修正を有効にすることも可能です。ソフトウェア キーボードが次に示すオプションに対応していない場合、一部のオプションは保証されない可能性があります。サポートされているキーボード オプションのリストを次に示します。

• capitalization
• autoCorrect
• keyboardType
• imeAction

参考情報

• テキスト フィールドの電話番号を自動的に書式設定する
• ユーザーの切り替えに基づいてパスワードを表示または非表示にする
• ユーザーの入力時に検証する