Compose 中的自动填充

某些应用（如密码管理器）可以使用用户提供的数据填充其他应用中的组件。填充其他应用组件的应用称为自动填充服务。自动填充框架管理应用和自动填充服务之间的通信。

填写凭据和表单是一项耗时且容易出错的任务。自动填充可帮助用户节省填写字段的时间，并最大限度地减少用户输入错误。

只需几行代码，即可在 Compose 中实现自动填充。此功能可为用户带来以下优势：

填充凭据

自动填充允许用户通过以下方式填充其凭据：

  • 当用户点按已设置自动填充语义的字段时，系统会为用户显示自动填充建议。
  • 系统会为用户显示自动填充建议，并根据用户输入的内容进行过滤。

保存凭据

用户可以通过以下方式通过自动填充保存凭据：

  • 当用户在启用自动填充的字段中输入新的或更新的信息时，系统会触发保存对话框，提示用户保存信息。保存可以通过两种方式完成：
    • 显式地，通过提交信息（例如，通过点击按钮）
    • 隐式地，当用户离开页面时
  • 根据您的凭据提供商，当字段设置了 ContentType.NewPassword 时，系统可能会向用户建议一个强密码。

您可以在应用中使用自动填充来简化用户保存数据的检索。自动填充通过 BasicTextField 以及所有基于该组件构建的 Material 文本字段支持文本组件。

设置自动填充

在使用设备或模拟器上的自动填充 API 之前，您必须在“设置”中激活自动填充。在那里，您可以为自动填充指定一个凭据提供商来存储您的凭据。

A settings page that shows how to specify a credential provider.
图 1. 显示如何指定凭据提供商的设置页面。

使用内容类型将自动填充添加到您的文本字段

要指示 TextField 已启用自动填充，请使用字段可以接受的类型设置 ContentType 语义。这会向自动填充服务指示哪些类型的用户数据可能与此特定字段相关。使用 ContentType.Username 来设置一个用户可以用其用户名填充的 TextField。

通过设置 ContentType 语义，您的用户可以访问其设备凭据提供商中已保存的自动填充信息。例如，如果用户已通过笔记本电脑上的 Chrome 浏览器登录您的应用并通过凭据提供商保存了密码，那么他们的凭据将通过自动填充提供给他们。

基于值的文本字段

TextField(
    value = textFieldValue.value,
    onValueChange = {textFieldValue.value = it},
    modifier = Modifier.semantics { contentType = ContentType.Username }
)
AutofillSnippets.kt

基于状态的文本字段

TextField(
    state = rememberTextFieldState(),
    modifier = Modifier.semantics { contentType = ContentType.Username }
)
AutofillSnippets.kt

添加具有多种类型的自动填充字段

在某些情况下，您可能希望您的 TextField 接受多种 ContentType。例如，登录字段可以接受电子邮件地址或用户名。您可以使用 + 运算符为您的 TextField 添加多种内容类型。

有关可使用自动填充保存的所有数据类型，请参阅 ContentType 参考。

基于值的文本字段

TextField(
    value = textFieldValue.value,
    onValueChange = { textFieldValue.value = it },
    modifier = Modifier.semantics {
        contentType = ContentType.Username + ContentType.EmailAddress
    }
)
AutofillSnippets.kt

基于状态的文本字段

TextField(
    state = rememberTextFieldState(),
    modifier = Modifier.semantics {
        contentType = ContentType.Username + ContentType.EmailAddress
    }
)
AutofillSnippets.kt

使用自动填充填充数据

当您在 TextField 中添加 ContentType 后，无需进行其他操作，用户即可填充凭据。

当用户点击启用自动填充的字段时，如果存储了相关数据，他们会在键盘上方的工具栏中看到一个提示他们填充凭据的浮窗提示。

Chips in the text toolbar showing saved credentials.
图 2. 文本工具栏中显示已保存凭据的浮窗提示。

通过导航使用自动填充保存数据

Compose 会自动尝试确定用户何时从页面导航离开并提交输入的凭据。一旦字段启用自动填充，当用户离开页面时，它将自动保存凭据信息，无需任何额外代码。

显式地使用自动填充保存数据

要通过启用自动填充的文本字段显式保存新凭据，应由自动填充管理器提交（或取消）自动填充上下文。本地自动填充管理器会在必要时与自动填充框架通信。如果您想移除用户输入的凭据，请调用 AutofillManager.cancel 以删除任何待处理数据而不保存。

以下代码段展示了如何使用按钮显式地通过自动填充保存数据：

  1. 创建一个局部变量来保存自动填充管理器，可以通过以下方式获取：

    val autofillManager = LocalAutofillManager.current
    AutofillSnippets.kt

  2. 在您的 TextField(s) 中，通过 Modifier.semantics 添加您选择的内容类型

    • 使用基于值的文本字段

      val autofillManager = LocalAutofillManager.current

Column {
    TextField(
        value = textFieldValue.value,
        onValueChange = { textFieldValue.value = it },
        modifier = Modifier.semantics { contentType = ContentType.NewUsername }
    )

    Spacer(modifier = Modifier.height(16.dp))

    TextField(
        value = textFieldValue.value,
        onValueChange = { textFieldValue.value = it },
        modifier = Modifier.semantics { contentType = ContentType.NewPassword }
    )
}
      AutofillSnippets.kt

    • 使用基于状态的文本字段

      val autofillManager = LocalAutofillManager.current

Column {
    TextField(
        state = rememberTextFieldState(),
        modifier = Modifier.semantics { contentType = ContentType.NewUsername }
    )

    Spacer(modifier = Modifier.height(16.dp))

    TextField(
        state = rememberTextFieldState(),
        modifier = Modifier.semantics { contentType = ContentType.NewPassword }
    )
}
      AutofillSnippets.kt

  3. 通过点击按钮根据需要提交自动填充上下文

    • 使用基于值的文本字段

      val autofillManager = LocalAutofillManager.current

Column {
    TextField(
        value = textFieldValue.value,
        onValueChange = { textFieldValue.value = it },
        modifier = Modifier.semantics { contentType = ContentType.NewUsername },
    )

    Spacer(modifier = Modifier.height(16.dp))

    TextField(
        value = textFieldValue.value,
        onValueChange = { textFieldValue.value = it },
        modifier = Modifier.semantics { contentType = ContentType.NewPassword },
    )

    // Submit button
    Button(onClick = { autofillManager?.commit() }) { Text("Reset credentials") }
}
      AutofillSnippets.kt

    • 使用基于状态的文本字段

      val autofillManager = LocalAutofillManager.current

Column {
    TextField(
        state = rememberTextFieldState(),
        modifier = Modifier.semantics { contentType = ContentType.NewUsername },
    )

    Spacer(modifier = Modifier.height(16.dp))

    TextField(
        state = rememberTextFieldState(),
        modifier = Modifier.semantics { contentType = ContentType.NewPassword },
    )

    // Submit button
    Button(onClick = { autofillManager?.commit() }) { Text("Reset credentials") }
}
      AutofillSnippets.kt

每当用户离开屏幕时，都会调用 Commit。如果 Submit 按钮与导航关联，则无需调用 Commit。如果您仍然希望点击 Submit 按钮触发保存对话框，请在此处添加 Commit。

当用户点击按钮时，他们会看到此底部抽屉式菜单，提示他们将凭据保存到选定的凭据提供商

Bottom sheet prompting users to save password.
图 3. 提示用户保存密码的底部抽屉式菜单。

通过“建议强密码”使用自动填充保存数据

根据您的凭据提供商，当您使用 NewUsername 和 NewPassword 内容类型时，用户可能会在键盘中看到一个“建议强密码”按钮。当他们点击此按钮时，会弹出一个底部抽屉式菜单，允许他们保存凭据。您无需为此用户体验实现任何其他功能。

The suggest strong password chip in the keyboard toolbar.
图 4. 键盘工具栏中的强密码建议浮窗提示。
Bottom sheet prompting users to use strong password.
图 5. 提示用户使用强密码的底部抽屉式菜单。

故障排除

在触发“保存”用户旅程时，如果您多次点击“暂不”，您的凭据提供商可能不再显示底部抽屉式菜单。要重新启用并让它再次出现，您需要移除已阻止“记住此密码？”的特定应用。

Bottom sheet prompting users to save password.
图 6. 提示用户保存密码的底部抽屉式菜单。

进一步自定义自动填充

在典型的自动填充用户旅程中，当已启用自动填充的组件填充了凭据时，它会改变颜色并高亮显示，以向用户表明自动填充已成功完成。

要自定义此高亮颜色，请使用 CompositionLocal 并提供您想要的任何颜色。默认的自动填充高亮颜色定义为 Color(0x4dffeb3b)。

基于值的文本字段

val customHighlightColor = Color.Red

CompositionLocalProvider(LocalAutofillHighlightColor provides customHighlightColor) {
    TextField(
        value = textFieldValue.value,
        onValueChange = { textFieldValue.value = it },
        modifier = Modifier.semantics { contentType = ContentType.Username }
    )
}
AutofillSnippets.kt

基于状态的文本字段

val customHighlightColor = Color.Red

CompositionLocalProvider(LocalAutofillHighlightColor provides customHighlightColor) {
    TextField(
        state = rememberTextFieldState(),
        modifier = Modifier.semantics { contentType = ContentType.Username }
    )
}
AutofillSnippets.kt