卸除式鍵盤管理

三顆星評等圖示

支援可拆卸式鍵盤有助於使用者在大螢幕裝置上發揮最大工作效率。每當鍵盤連接或拔除裝置時，Android 都會觸發設定變更，這可能會導致 UI 狀態遺失。您的應用程式可以儲存及還原狀態，讓系統處理活動重建作業，也可以限制鍵盤設定變更的活動重建作業。

在所有情況下，與鍵盤相關的所有資料都會儲存在 Configuration 物件中。設定物件的 keyboard 和 keyboardHidden 欄位包含鍵盤類型和可用性的相關資訊。

最佳做法

針對大螢幕最佳化的應用程式支援各種輸入裝置，包括軟體和硬體鍵盤、觸控筆、滑鼠、觸控板和其他周邊裝置。

支援外接鍵盤需要變更設定，您可以透過下列任一方式管理：

  1. 讓系統重新建立正在執行的活動，您則負責管理應用程式的狀態。
  2. 自行管理設定變更 (系統不會重新建立活動)：
    • 宣告所有鍵盤相關設定值
    • 建立設定變更處理常式

生產力應用程式通常需要精細控制 UI，才能輸入文字和其他內容，因此自行處理設定變更的做法，對這類應用程式很有幫助。

在特殊情況下，您可能會想在連接或拔除硬體鍵盤時變更應用程式版面配置，例如為工具或編輯視窗騰出更多空間。

在 Jetpack Compose 中，您可以透過兩種方式回應鍵盤設定變更：

  1. 反應式 UI：使用 LocalConfiguration.current 直接在可組合項中讀取目前的設定狀態。當鍵盤連接或卸除時，UI 會自動重組，以適應新狀態。
  2. 副作用回呼：使用生命週期感知 DisposableEffect 在主機 Activity 上註冊設定變更監聽器，這樣您就能觸發非 UI 事件 (例如記錄或數據分析)，不必重建 Activity 或例項化任何虛擬檢視區塊元素。

要件

  • android:configChanges：應用程式資訊清單 <activity> 元素的屬性，向系統回報應用程式管理的設定變更。
  • LocalConfiguration：可組合的本機供應器，會公開目前的裝置 Configuration。
  • DisposableEffect：Compose 副作用 API，會在可組合函式進入組合時執行程式碼區塊，並在離開時清除。

步驟

宣告 configChanges 屬性並新增鍵盤相關值，防止活動重新建立。然後使用 LocalConfiguration.current 動態調整可組合函式的版面配置，或使用 DisposableEffect 註冊設定監聽器。

1. 宣告 configChanges 屬性

更新應用程式資訊清單中的 <activity> 元素，將 keyboard|keyboardHidden 值新增至已管理的設定變更清單：

<activity
      …
      android:configChanges="...|keyboard|keyboardHidden">

2. 回應鍵盤設定變更

如要在 Jetpack Compose 中處理設定變更，請根據您要更新 UI 或執行副作用回呼，使用下列其中一個選項：

  • 選項 A：反應式 UI (建議)

    直接從 LocalConfiguration.current 讀取鍵盤類型。當硬體鍵盤連接或拔除時，這個值會變更，而 Compose 會自動重組 UI。

    val configuration = LocalConfiguration.current
val isPhysicalKeyboardAttached = configuration.keyboard == Configuration.KEYBOARD_QWERTY

if (isPhysicalKeyboardAttached) {
    // Render layout optimized for physical keyboard
} else {
    // Render default layout
}

  • 選項 B：副作用監聽器

    如果需要在設定變更時執行副作用 (例如記錄、更新本機資料庫或觸發 Analytics)，請使用 DisposableEffect 在主機 ComponentActivity 上註冊設定變更監聽器。

    val context = LocalActivity.current
DisposableEffect(context) {
    val activity = context as? ComponentActivity
    val listener = Consumer<Configuration> { newConfig ->
        val hasKeyboard = newConfig.keyboard == Configuration.KEYBOARD_QWERTY
        // Trigger non-UI actions, analytics, etc.
    }
    activity?.addOnConfigurationChangedListener(listener)
    onDispose {
        activity?.removeOnConfigurationChangedListener(listener)
    }
}

結果

現在，應用程式會在連接或卸離外接鍵盤時做出回應，不必重新建立執行中的活動。

其他資源

如要瞭解如何在設定變更 (例如鍵盤連接或拔除) 期間儲存應用程式的 UI 狀態，請參閱「儲存 UI 狀態」。