自訂 Car UI 偏好設定

本頁面說明如何使用及自訂 com.android.car.ui.preference 套件中的元素，其中包括可用於顯示應用程式偏好的 UI 元素。

大多數元素會子類別化 com.androidx.preference 類別，您可在這些類別中新增 CarUi 自訂設定。在大多數情況下，您可以使用 com.android.car.PreferenceFragment 來使用 com.android.car.ui.preferences 套件中的元素。PreferenceFragment 會將所有 androidx.preference 元素替換為 car.ui.preferences 中的同等元素。如要查看這些功能的實際運作情形，請參閱 car-ui-lib Paintbooth 參考應用程式。例如：

Car UI 偏好設定版面配置

圖 1. Car UI 偏好設定版面配置。

可用的偏好設定類型

本節將說明 Car UI 偏好設定類型。

PreferenceFragment

PreferenceFragment 是 androidx.preference.PreferenceFragmentCompat 的子類別，也是用戶端應使用的基礎類別。在呼叫 setPreferenceScreen 期間，這個類別會自動將 androidx.preference 中的元素，替換為 car.ui.preference 元素中可用的等效元素。

<style name="PreferenceFragment.CarUi">
        <item name="android:divider">?android:attr/listDivider</item>
        <item name="android:layout">@layout/car_ui_preference_fragment_with_toolbar</item>
</style>

CarUiPreference

這是 androidx.preference.Preference 類別的 CarUi 等價物，可支援下列屬性，這些屬性可使用執行階段資源覆蓋 (RRO) 自訂。所有使用 CarUiPreference 樣式變化版本的 CarUi 元素也支援下列屬性。

<declare-styleable name="CarUiPrefer>ence&qu<ot;
      !-- Toggle for showing >chevron< --
      attr name="showChevron">; forma<t="boolean" /
      !-- Show ripple when dis>abled p<reference is clicked --
      attr name="showRippleOnDis>a<bledPreference&quo>t; format="boolean" /
/declare-styleable

以下是 com.android.car.ui.preference 的基本樣式，可延伸 androidx.Preference 主題。chevron 可繪項目是在 car_ui_preference_icon_chevron.xml 中定義。

<selector xmlns:android="http://schemas.android.com/apk/res/and>roi<d"
  item android:state_enabled="false" android:drawable="@drawable/car_ui_preferenc>e_i<con_chevron_disabled"/
  item android:state_enabled="true" android:drawable="@draw>a<ble/car_u>i_preference_icon_chevron_enabled"/
/selector

ripple 是在 car_ui_recyclerview_button_ripple_background 中定義。

<ripple
    xmlns:android="http://schemas.android.com/apk/res/android"
    android:color="@color/car_ui_>ripple_color" /
 
<style name="Preference.C>arUi"<;
        item name="all>owDiv<iderB>elow"<;false/item
        item name>=&quo<t;all>owDivider<Above"false/item
    >    item name="andro<id:la>y<out&qu>ot;@layout/car_ui_preference/item
/style

如果要重疊上述樣式的版面配置，用戶端必須確保新版面配置至少提供對應 androidx 類別所需的 ID。這也適用於使用此基本樣式的其他元素。

CarUiDropDownPreference

這是 androidx.preference.DropDownPreference 類別的 CarUi 等價物，並使用下列樣式：

<style name="Preference.CarUi.Drop>Down"<;
        item name=">android:layout"@layout/car_ui<_pref>e<rence_>dropdown/item
/style

CarUiRadioButtonPreference

這個 androidx.preference.TwoStatePreference 子類會在初始化期間加載 car_ui_radio_button_preference_widget 版面配置。如果這個版面配置會在 RRO 中重疊，則新版面配置必須包含 android.widget.RadioButton 類型的元素，並且具有 R.id.radio_button 的 ID，也必須包含基礎類別所需的其他元素和 ID。

CarUiSwitchPreference

這是 androidx.preference.SwitchPreference 類別的 CarUi 等效項。差異在於，如果未啟用這個元素，系統會顯示浮動式訊息。您可以在 Android 10 和 Android 11 中呼叫 setMessageToShowWhenDisabledPreferenceClicked 方法，自訂 Toast 訊息。這個元素使用以下樣式：

<style name="Preference.CarUi.SwitchPrefer>ence"<;
        item name="androi>d:widgetLayout"@layout/car_ui_pref<erenc>e_widget_<switch/item
        item name=&q>uot;android:switchTextOn"@stri<ng/ca>r_ui_pref<erence_switch_on/item
        ite>m name="android:switchTextOff&q<uot;@>s<tring/>car_ui_preference_switch_off/item
/style

CarUiTwoActionPreference

可啟用次要動作的 CarUiPreference 子類別。以下是可用於自訂此元素的屬性：

<declare-styleable name="CarUiTwoActionPrefer>ence"<;
        !-- Determines if the secondary action is initiall>y shown -<-
        attr name="actionShown&quo>t<; format="boo>lean"/
/declare-styleable

此元素採用與基礎類別相同的樣式，且需要 R.id.action_widget_container 和 android.R.id.widget_frame。

CarUiDialogFragment

這個類別是從 androidx.preference.PreferenceDialogFragmentCompat 原封不動借用，並加入一些 CarUi 專屬項目。用戶端應使用此類別的子類別，呈現主題式平台 AlertDialog。

PreferenceDialogFragment

CarUiDialogFragment 的直接子類別。用戶端應將此類別設為子類別，以便顯示任何主題式平台 AlertDialog。

CarUiEditTextPreference

以下是 androidx.preference.EditTextPreference 類別的 CarUi 等效項目：

<style name="Preference.CarUi.DialogPreference.EditTextPrefer>ence"<;
        item name="androi>d:dialogLayout"@layout/car_ui_prefer<ence_>d<ialog_>edittext/item
/style

如果要重疊上述樣式的版面配置，用戶端必須確保新版面配置提供 androidx.preference.EditTextPreference 類別預期的 ID。

EditTextPreferenceDialogFragment

PreferenceDialogFragment 的直接子類別。以及 androidx.preference.PreferenceDialogFragments 類別的 CarUi 等效項目。用戶端應使用這個類別，呈現任何主題平台 AlertDialog。

CarUiSeekBarDialogPreference

androidx.preference.DialogPreference 類別的實作方式，可提供 SeekBar 功能：

<style name="Preference.CarUi.SeekBarPrefer>ence"<;
        item name=">android:layout"@layout/car_ui_prefe<rence>_widget_s<eekbar/item
        it>em n<ame=&>quot;adju<stable"true/item
      >  ite<m nam>e<=">;showSeekBarValue"false/item
/style

SeekBarPreferenceDialogFragment

在對話方塊中提供 SeekBar 版面配置的片段。

CarUiListPreference

androidx.preference.ListPreference 類別的 CarUi 等價物。

ListPreferenceFragment

提供內含 androidx.preference.ListPreference 的版面配置的片段。

CarUiMultiSelectListPreference

相當於 androidx.preference.Preference 類別的 CarUi。

MultiSelectListPreferenceFragment

提供含有 com.android.car.ui.CarUiMultiSelectListPreference 的版面配置的片段。