2025/8/20

【Jetpack Compose/Android】TextFieldの使い方！ラベルやキーボードタイプの指定

この記事からわかること

Kotlin/Android Jetpack ComposeのTextFieldの使い方
ラベルやデザインの変更方法

index

[open]

＼アプリをリリースしました／

友達や家族の誕生日をメモ！通知も届く-みんなの誕生日-

posted withアプリーチ

環境

Android Studio：Narwhal Feature Drop
Kotlin：2.1.10
Material3
AGP：8.9.2
Gradle：8.11.1
Mac M1：Sequoia 15.4

Jetpack Compose自体の基本的な使用方法に関しては以下の記事を参考にしてください。

Jetpack ComposeのTextFiledの種類

Jetpack Composeで文字の入力ボックスを実装する方法としてTextFieldとOutlinedTextFieldが用意されてします。ただOutlinedTextFieldはMaterial3以降でしか使えないので注意してください。

違い

TextField・・・・・・入力エリア全体が色のついたボックス
OutlinedTextField・・・アウトラインだけの入力ボックス

ただどちらも基本的な機能や指定できる引数などもほとんど同じになっています。

TextField(
    value = name,
    onValueChange = {
        name = it
    },
    label = { Text("TextField") },
    modifier = Modifier.fillMaxWidth()
)

OutlinedTextField(
    value = memo,
    onValueChange = {
        memo = it
    },
    label = { Text("OutlinedTextField") },
    modifier = Modifier.fillMaxWidth()
)

TextFiledの実装方法

TextFiledを実装するためには入力された文字を保持するためのState型の変数が必要になります。State型の変数を用意して引数valueにセットしないとおかないと文字を入力してもその変化がUIに更新されないので注意してください。

// 変数を用意して引数valueにセットしないとUIが更新されない
var name by rememberSaveable { mutableStateOf("") }

TextField(
    value = name,
    onValueChange = {
        name = it
    },
    label = { Text("お名前") },
    modifier = Modifier.fillMaxWidth()
)

また引数onValueChangeで変化した値をState型の変数に格納し直すことも必要です。単にTextFieldを定義しただけでは期待通りに動かず、ちゃんと変化し値を保持する仕組みと更新する仕組みの実装を記述する必要があります。

定義を確認

定義を確認してみると指定できる機能がたくさんあることがわかります。その中からよく使うものなどをピックアップして紹介していきます。

定義
@OptIn(ExperimentalMaterial3Api::class)
@Composable
fun TextField(
    // 現在のテキストの値（必須: Stateなどで保持する）
    value: String,

    // テキストが変更されたときに呼ばれるコールバック（必須）
    onValueChange: (String) -> Unit,

    // レイアウトやスタイルを適用するためのModifier
    modifier: Modifier = Modifier,

    // 入力を有効/無効にするフラグ
    enabled: Boolean = true,

    // 読み取り専用にするフラグ（trueだと入力できないが選択は可能）
    readOnly: Boolean = false,

    // テキストのスタイル（フォント、色など）
    textStyle: TextStyle = LocalTextStyle.current,

    // ラベル（TextFieldの上に表示されるヒントやタイトル）
    label: @Composable (() -> Unit)? = null,

    // プレースホルダー（入力前に表示される薄いテキスト）
    placeholder: @Composable (() -> Unit)? = null,

    // 左側に表示するアイコン
    leadingIcon: @Composable (() -> Unit)? = null,

    // 右側に表示するアイコン
    trailingIcon: @Composable (() -> Unit)? = null,

    // 入力テキストの先頭に表示するコンテンツ（例: ￥, $ 記号など）
    prefix: @Composable (() -> Unit)? = null,

    // 入力テキストの末尾に表示するコンテンツ（例: 単位 "kg" など）
    suffix: @Composable (() -> Unit)? = null,

    // 補助テキスト（エラーメッセージや説明文など）
    supportingText: @Composable (() -> Unit)? = null,

    // エラー状態かどうか（trueで赤枠やエラーカラー適用）
    isError: Boolean = false,

    // テキストの表示変換（例: PasswordVisualTransformation で「●●●」に変換）
    visualTransformation: VisualTransformation = VisualTransformation.None,

    // キーボードの種類や入力オプション（数値入力、IMEアクションなど）
    keyboardOptions: KeyboardOptions = KeyboardOptions.Default,

    // キーボードのアクション（EnterやNext押下時の挙動を定義）
    keyboardActions: KeyboardActions = KeyboardActions.Default,

    // trueで単一行のTextField（改行不可）
    singleLine: Boolean = false,

    // 最大行数
    maxLines: Int = if (singleLine) 1 else Int.MAX_VALUE,

    // 最小行数
    minLines: Int = 1,

    // ユーザーのインタラクション（フォーカス、クリックなど）を監視するためのソース
    interactionSource: MutableInteractionSource? = null,

    // TextFieldの形状（角丸やカスタムシェイプ）
    shape: Shape = TextFieldDefaults.shape,

    // TextFieldの色（背景色、テキスト色、カーソル色などを制御）
    colors: TextFieldColors = TextFieldDefaults.colors()
)

キーボードタイプを数値のみなどに変更する

入力できる文字列を数値のみなどに変更したい場合は引数keyboardOptionsKeyboardOptions型でキーボードに関する設定を行い反映させます。例えば数値のみにするならkeyboardType = KeyboardType.Numberといったように指定します。

var count: Int? by rememberSaveable { mutableStateOf(null) }

OutlinedTextField(
    value = if (count == null) "" else count.toString(),
    onValueChange = {
        if (it.isEmpty()) {
            count = null
        } else {
            count = it.toIntOrNull() ?: 0
        }
    },
    keyboardOptions = KeyboardOptions.Default.copy(
        keyboardType = KeyboardType.Number
    ),
)

定義を確認してみると以下のように細かくキーボードの設定を指定することができるようです。

定義
class KeyboardOptions(
    // 入力時の大文字化ルール
    // None / Characters / Words / Sentences / Unspecified
    val capitalization: KeyboardCapitalization = KeyboardCapitalization.Unspecified,

    // 自動補正（予測変換）を使うかどうか
    @Suppress("AutoBoxing") @get:Suppress("AutoBoxing") val autoCorrectEnabled: Boolean? = null,

    // キーボードの種類を指定
    // Text / Ascii / Number / Phone / Uri / Email / Password / Decimal / Unspecified など
    val keyboardType: KeyboardType = KeyboardType.Unspecified,

    // キーボード右下ボタン（Enterキー相当）の種類
    // Done / Next / Search / Send / Go / Previous / Unspecified など
    val imeAction: ImeAction = ImeAction.Unspecified,


    // Android固有のIME挙動をカスタマイズするためのオプション
    val platformImeOptions: PlatformImeOptions? = null,
    
    // TextField にフォーカスが当たったとき、キーボードを自動的に開くかどうか
    @Suppress("AutoBoxing") @get:Suppress("AutoBoxing") val showKeyboardOnFocus: Boolean? = null,

    // 入力ヒント用のロケール（言語設定の指定）
    @get:Suppress("NullableCollection") val hintLocales: LocaleList? = null,
)

色を調整する

TextFieldの色を調整するには引数colorsにTextFieldColors型で指定します。色々細かく調整できるようになっているみたいです。

TextField(
    value = memo,
    onValueChange = { memo = it },

    // TextField の各種色設定
    colors = TextFieldDefaults.colors(

        // 入力された文字の色
        focusedTextColor = Color.Black,      // フォーカス時の文字色
        unfocusedTextColor = Color.DarkGray, // 非フォーカス時の文字色
        disabledTextColor = Color.Gray,      // 無効状態の文字色
        errorTextColor = Color.Red,          // エラー時の文字色

        // 背景色（container）
        focusedContainerColor = Color.White,      // フォーカス時の背景色
        unfocusedContainerColor = Color(0xFFF5F5F5), // 非フォーカス時の背景色
        disabledContainerColor = Color.LightGray, // 無効状態の背景色
        errorContainerColor = Color(0xFFFFEAEA),  // エラー時の背景色

        // カーソルの色
        cursorColor = Color.Blue,   // 通常時のカーソル
        errorCursorColor = Color.Red, // エラー時のカーソル

        // 下線やアウトライン（インジケータ）の色
        focusedIndicatorColor = Color.Blue,     // フォーカス時
        unfocusedIndicatorColor = Color.Gray,   // 非フォーカス時
        disabledIndicatorColor = Color.Transparent, // 無効状態（透明）
        errorIndicatorColor = Color.Red,        // エラー時

        // 左側アイコンの色
        focusedLeadingIconColor = Color.Blue,   // フォーカス時
        unfocusedLeadingIconColor = Color.Gray, // 非フォーカス時
        errorLeadingIconColor = Color.Red,      // エラー時

        // 右側アイコンの色
        focusedTrailingIconColor = Color.Blue,   // フォーカス時
        unfocusedTrailingIconColor = Color.Gray, // 非フォーカス時
        errorTrailingIconColor = Color.Red,      // エラー時

        // ラベル（ヒントが上に浮くテキスト）の色
        focusedLabelColor = Color.Blue,      // フォーカス時
        unfocusedLabelColor = Color.Gray,    // 非フォーカス時
        disabledLabelColor = Color.LightGray, // 無効状態
        errorLabelColor = Color.Red,         // エラー時

        // プレースホルダーの色（入力前に表示される薄いテキスト）
        focusedPlaceholderColor = Color.Gray,       // フォーカス時
        unfocusedPlaceholderColor = Color.LightGray, // 非フォーカス時
        disabledPlaceholderColor = Color.Gray,      // 無効状態
        errorPlaceholderColor = Color.Red,          // エラー時

        // サポートテキスト（エラーメッセージや補足説明）の色
        focusedSupportingTextColor = Color.Blue,    // フォーカス時
        unfocusedSupportingTextColor = Color.Gray,  // 非フォーカス時
        errorSupportingTextColor = Color.Red        // エラー時
    )
)

まだまだ勉強中ですので間違っている点や至らぬ点がありましたら教えていただけると助かります。

ご覧いただきありがとうございました。

Android