Compose 中的自動填入功能

密碼管理工具等應用程式可以將使用者提供的資料，填入其他應用程式的元件。這類將資料填入其他應用程式元件的應用程式，通稱為「自動填入服務」。自動填入架構會管理應用程式和自動填入服務之間的通訊。

填寫憑證和表單是耗時又容易出錯的工作。 自動填入功能可讓使用者節省填寫欄位所需的時間，並盡可能減少使用者輸入錯誤。

只要幾行程式碼，您就能在 Compose 中實作自動填入功能。這項功能可為使用者帶來下列好處：

填寫憑證

自動填入功能可讓使用者透過下列方式填入憑證：

• 當使用者輕觸已設定自動填入語義的欄位時，系統會顯示自動填入建議。
• 系統會為使用者顯示自動填入建議，並根據使用者輸入的內容進行篩選。

儲存憑證

使用者可以透過下列方式透過自動填入功能儲存憑證：

• 系統會觸發儲存對話方塊，當使用者在啟用自動填入功能的欄位中輸入新資訊或更新資訊時，系統會提示使用者儲存資訊。儲存方式有兩種：
  • 明確地透過提交資訊 (例如按下按鈕)
  • 隱含地，當使用者離開網頁時
• 視憑證提供者而定，當欄位設定 ContentType.NewPassword 時，系統可能會向使用者建議高強度密碼。

您可以在應用程式中使用自動填入功能，為使用者簡化擷取已儲存資料的流程。自動填入功能會透過 BasicTextField 和該元件所建立的所有 Material 文字欄位，支援文字元件。

設定自動填入功能

在裝置或模擬器上使用自動填入 API 前，您必須先在「設定」中啟用自動填入功能。您可以在該處指定自動填入功能的憑證提供者，以便儲存憑證。

使用內容類型在文字欄位中加入自動填入功能

如要指出 TextField 是否啟用自動填入功能，請將 ContentType 語義設為欄位可接受的類型。這會向自動填入服務指出，哪些使用者資料可能與此特定欄位相關。使用 ContentType.Username 設定 TextField，讓使用者填入使用者名稱。

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

設定 ContentType 語意後，使用者就能存取已儲存在裝置憑證提供者中的自動填入資訊。舉例來說，如果使用者已透過筆電上的 Chrome 瀏覽器登入應用程式，並透過憑證提供者儲存密碼，系統就會透過自動填入功能提供憑證。

新增多種類型的自動填入欄位

在某些情況下，您可能會希望 TextField 負責處理多個 ContentType。舉例來說，登入欄位可能會接受電子郵件地址或使用者名稱。您可以使用 + 運算子，在 TextField 中新增多種內容類型。

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

如要瞭解可透過自動填入功能儲存的所有資料類型，請參閱 ContentType 參考資料。

使用自動填入功能填入資料

在 TextField 中加入 ContentType 後，您不需要再採取任何行動，使用者就能填入憑證。

使用者點選啟用自動填入功能的欄位時，如果系統已儲存相關資料，鍵盤上方的工具列就會顯示一個方塊，提示使用者填入憑證。

透過導覽功能使用自動填入功能，節省資料用量

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

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

每當使用者離開畫面時，系統就會呼叫 Commit。如果「提交」按鈕已連結至導覽，則不需要呼叫「提交」。如果您仍想透過點選「提交」觸發儲存對話方塊，請在此新增「提交」。

使用者按下按鈕後，系統會顯示底部功能表，提示他們將憑證儲存至所選憑證提供者：

透過自動填寫功能建議高強度密碼，節省資料

視憑證提供者而定，當您使用 NewUsername 和 NewPassword 內容類型時，使用者可能會在鍵盤中看到「建議高強度密碼」按鈕。點選後，系統就會顯示底部功能表，讓使用者儲存憑證。您不需要實作其他任何內容，使用者就能享有這項體驗。

疑難排解

在叫用「儲存」使用者歷程時，如果您點選「暫時不儲存」的次數超過一次，憑證提供者可能就不會再顯示底部工作表。如要重新啟用並再次顯示這項功能，請移除已封鎖「記住這組密碼嗎？」的特定應用程式。

進一步自訂自動填入功能

在典型的自動填入使用者歷程中，當支援自動填入功能的元件填入憑證後，會變更顏色並醒目顯示，向使用者傳達自動填入功能已順利完成。

如要自訂這項醒目顯示顏色，請使用 CompositionLocal，並提供您想要的顏色。

val customHighlightColor = Color.Red

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

預設的自動填入醒目顯示顏色定義為 Color(0x4dffeb3b)。