状態ベースのテキスト フィールドに移行する

このページでは、値ベースの TextField を状態ベースの TextField に移行する方法の例を示します。値ベースと状態ベースの TextField の違いについては、テキスト フィールドを構成するをご覧ください。

基本的な使用方法

値ベース

@Composable
fun OldSimpleTextField() {
    var state by rememberSaveable { mutableStateOf("") }
    TextField(
        value = state,
        onValueChange = { state = it },
        singleLine = true,
    )
}

状態ベース

@Composable
fun NewSimpleTextField() {
    TextField(
        state = rememberTextFieldState(),
        lineLimits = TextFieldLineLimits.SingleLine
    )
}

  • value, onValueChange と remember { mutableStateOf("") } を rememberTextFieldState() に置き換えます。
  • singleLine = true を lineLimits = TextFieldLineLimits.SingleLine に置き換えます。

onValueChange によるフィルタリング

値ベース

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

状態ベース

@Preview
@Composable
fun NewNoLeadingZeros() {
    TextField(
        state = rememberTextFieldState(),
        inputTransformation = InputTransformation {
            while (length > 0 && charAt(0) == '0') delete(0, 1)
        }
    )
}

  • 値のコールバック ループを rememberTextFieldState() に置き換えます。
  • InputTransformation を使用して、onValueChange でフィルタリング ロジックを再実装します。
  • InputTransformation のレシーバー スコープから TextFieldBuffer を使用して、state を更新します。
    • InputTransformation は、ユーザー入力が検出された直後に呼び出されます。
    • TextFieldBuffer を介して InputTransformation によって提案された変更はすぐに適用されるため、ソフトウェア キーボードと TextField の間で同期の問題が発生することはありません。

クレジット カード フォーマッタ TextField

値ベース

@Composable
fun OldTextFieldCreditCardFormatter() {
    var state by remember { mutableStateOf("") }
    TextField(
        value = state,
        onValueChange = { if (it.length <= 16) state = it },
        visualTransformation = VisualTransformation { text ->
            // Making XXXX-XXXX-XXXX-XXXX string.
            var out = ""
            for (i in text.indices) {
                out += text[i]
                if (i % 4 == 3 && i != 15) out += "-"
            }

            TransformedText(
                text = AnnotatedString(out),
                offsetMapping = object : OffsetMapping {
                    override fun originalToTransformed(offset: Int): Int {
                        if (offset <= 3) return offset
                        if (offset <= 7) return offset + 1
                        if (offset <= 11) return offset + 2
                        if (offset <= 16) return offset + 3
                        return 19
                    }

                    override fun transformedToOriginal(offset: Int): Int {
                        if (offset <= 4) return offset
                        if (offset <= 9) return offset - 1
                        if (offset <= 14) return offset - 2
                        if (offset <= 19) return offset - 3
                        return 16
                    }
                }
            )
        }
    )
}

状態ベース

@Composable
fun NewTextFieldCreditCardFormatter() {
    val state = rememberTextFieldState()
    TextField(
        state = state,
        inputTransformation = InputTransformation.maxLength(16),
        outputTransformation = OutputTransformation {
            if (length > 4) insert(4, "-")
            if (length > 9) insert(9, "-")
            if (length > 14) insert(14, "-")
        },
    )
}

  • onValueChange のフィルタリングを InputTransformation に置き換えて、入力の最大長を設定します。
  • VisualTransformation を OutputTransformation に置き換えて、ダッシュを追加します。
    • VisualTransformation では、ダッシュ付きの新しいテキストの作成と、表示テキストとバッキング状態の間でインデックスがどのようにマッピングされるかの計算の両方を行う必要があります。
    • OutputTransformation は、オフセット マッピングを自動的に処理します。OutputTransformation.transformOutput のレシーバー スコープから TextFieldBuffer を使用して、正しい位置にダッシュを追加するだけです。

状態の更新（シンプル）

値ベース

@Composable
fun OldTextFieldStateUpdate(userRepository: UserRepository) {
    var username by remember { mutableStateOf("") }
    LaunchedEffect(Unit) {
        username = userRepository.fetchUsername()
    }
    TextField(
        value = username,
        onValueChange = { username = it }
    )
}

状態ベース

@Composable
fun NewTextFieldStateUpdate(userRepository: UserRepository) {
    val usernameState = rememberTextFieldState()
    LaunchedEffect(Unit) {
        usernameState.setTextAndPlaceCursorAtEnd(userRepository.fetchUsername())
    }
    TextField(state = usernameState)
}

  • 値のコールバック ループを rememberTextFieldState() に置き換えます。
  • TextFieldState.setTextAndPlaceCursorAtEnd で値の割り当てを変更します。

状態の更新（複雑）

値ベース

@Composable
fun OldTextFieldAddMarkdownEmphasis() {
    var markdownState by remember { mutableStateOf(TextFieldValue()) }
    Button(onClick = {
        // add ** decorations around the current selection, also preserve the selection
        markdownState = with(markdownState) {
            copy(
                text = buildString {
                    append(text.take(selection.min))
                    append("**")
                    append(text.substring(selection))
                    append("**")
                    append(text.drop(selection.max))
                },
                selection = TextRange(selection.min + 2, selection.max + 2)
            )
        }
    }) {
        Text("Bold")
    }
    TextField(
        value = markdownState,
        onValueChange = { markdownState = it },
        maxLines = 10
    )
}

状態ベース

@Composable
fun NewTextFieldAddMarkdownEmphasis() {
    val markdownState = rememberTextFieldState()
    LaunchedEffect(Unit) {
        // add ** decorations around the current selection
        markdownState.edit {
            insert(originalSelection.max, "**")
            insert(originalSelection.min, "**")
            selection = TextRange(originalSelection.min + 2, originalSelection.max + 2)
        }
    }
    TextField(
        state = markdownState,
        lineLimits = TextFieldLineLimits.MultiLine(1, 10)
    )
}

このユースケースでは、ボタンをクリックすると、カーソルまたは現在の選択範囲の周囲のテキストが太字になるように Markdown 装飾が追加されます。また、変更後も選択位置が維持されます。

  • 値のコールバック ループを rememberTextFieldState() に置き換えます。
  • maxLines = 10 を lineLimits = TextFieldLineLimits.MultiLine(maxHeightInLines = 10) に置き換えます。
  • TextFieldState.edit 呼び出しで新しい TextFieldValue を計算するロジックを変更します。
    • 新しい TextFieldValue は、現在の選択範囲に基づいて既存のテキストをスプライシングし、その間に Markdown 装飾を挿入することで生成されます。
    • また、テキストの新しいインデックスに合わせて選択範囲が調整されます。
    • TextFieldState.edit では、TextFieldBuffer を使用して現在の状態をより自然に編集できます。
    • 選択範囲は、装飾を挿入する場所を明示的に定義します。
    • 次に、onValueChange アプローチと同様に選択範囲を調整します。

ViewModel StateFlow アーキテクチャ

多くのアプリケーションは、最新のアプリ開発ガイドラインに沿って、 StateFlowを使用して、画面またはコンポーネントの UI 状態を すべての情報を含む単一の不変クラスを介して定義しています。

このようなアプリケーションでは、テキスト入力を含むログイン画面などのフォームは通常、次のように設計されます。

class LoginViewModel : ViewModel() {
    private val _uiState = MutableStateFlow(UiState())
    val uiState: StateFlow<UiState>
        get() = _uiState.asStateFlow()

    fun updateUsername(username: String) = _uiState.update { it.copy(username = username) }

    fun updatePassword(password: String) = _uiState.update { it.copy(password = password) }
}

data class UiState(
    val username: String = "",
    val password: String = ""
)

@Composable
fun LoginForm(
    loginViewModel: LoginViewModel,
    modifier: Modifier = Modifier
) {
    val uiState by loginViewModel.uiState.collectAsStateWithLifecycle()
    Column(modifier) {
        TextField(
            value = uiState.username,
            onValueChange = { loginViewModel.updateUsername(it) }
        )
        TextField(
            value = uiState.password,
            onValueChange = { loginViewModel.updatePassword(it) },
            visualTransformation = PasswordVisualTransformation()
        )
    }
}

この設計は、TextFields 状態ホイスティング パラダイムを使用する value, onValueChange に最適です。ただし、テキスト入力に関しては、このアプローチには予測できない欠点があります。このアプローチによる深い同期 の問題については、Compose の TextField の効果的な状態 管理のブログ投稿で詳しく説明しています。

問題は、新しい TextFieldState デザインが、StateFlow でサポートされている ViewModel UI 状態と直接互換性がないことです。TextFieldState は本質的に可変のデータ 構造であるため、 username: String と password: String を username: TextFieldState と password: TextFieldState に置き換えるのは奇妙に思えるかもしれません。

ViewModel に UI 依存関係を配置しないことが一般的におすすめされています。これは一般的に良い方法ですが、誤解されることもあります。 これは、TextFieldState のように、純粋なデータ構造であり、UI 要素を含まない Compose 依存関係に特に当てはまります。

MutableState や TextFieldState などのクラスは、Compose のスナップショット状態システムによってサポートされるシンプルな状態ホルダーです。これらは、StateFlow や RxJava などの依存関係と変わりません。そのため、コードで「ViewModel に UI 依存関係がない」という原則をどのように適用しているかを再評価することをおすすめします。ViewModel 内で TextFieldState への参照を保持することは、本質的に悪い方法ではありません。

UiState から username や password などの値を抽出し、ViewModel で個別の参照を保持することをおすすめします。

class LoginViewModel : ViewModel() {
    val usernameState = TextFieldState()
    val passwordState = TextFieldState()
}

@Composable
fun LoginForm(
    loginViewModel: LoginViewModel,
    modifier: Modifier = Modifier
) {
    Column(modifier) {
        TextField(state = loginViewModel.usernameState,)
        SecureTextField(state = loginViewModel.passwordState)
    }
}

  • MutableStateFlow<UiState> をいくつかの TextFieldState 値に置き換えます。
  • これらの TextFieldState オブジェクトを LoginForm コンポーザブルの TextFields に渡します。

準拠アプローチ

このようなアーキテクチャの変更は必ずしも簡単ではありません。このような変更を行う自由がない場合や、新しい TextFieldを使用するメリットよりも時間投資の方が大きい場合があります。この場合でも、少し調整すれば状態ベースのテキスト フィールドを使用できます。

class LoginViewModel : ViewModel() {
    private val _uiState = MutableStateFlow(UiState())
    val uiState: StateFlow<UiState>
        get() = _uiState.asStateFlow()

    fun updateUsername(username: String) = _uiState.update { it.copy(username = username) }

    fun updatePassword(password: String) = _uiState.update { it.copy(password = password) }
}

data class UiState(
    val username: String = "",
    val password: String = ""
)

@Composable
fun LoginForm(
    loginViewModel: LoginViewModel,
    modifier: Modifier = Modifier
) {
    val initialUiState = remember(loginViewModel) { loginViewModel.uiState.value }
    Column(modifier) {
        val usernameState = rememberTextFieldState(initialUiState.username)
        LaunchedEffect(usernameState) {
            snapshotFlow { usernameState.text.toString() }.collectLatest {
                loginViewModel.updateUsername(it)
            }
        }
        TextField(usernameState)

        val passwordState = rememberTextFieldState(initialUiState.password)
        LaunchedEffect(usernameState) {
            snapshotFlow { usernameState.text.toString() }.collectLatest {
                loginViewModel.updatePassword(it)
            }
        }
        SecureTextField(passwordState)
    }
}

  • ViewModel クラスと UiState クラスはそのままにします。
  • 状態を ViewModel に直接ホイスティングして TextFields の信頼できる情報源にするのではなく、ViewModel をシンプルなデータホルダーにします。
    • これを行うには、LaunchedEffect で snapshotFlow を収集して、各 TextFieldState.text の変更を監視します。
  • ViewModel には UI の最新の値が引き続き含まれますが、uiState: StateFlow<UiState> は TextField を駆動しません。
  • ViewModel に実装されている他の永続化ロジックはそのままにできます。