自定义车载 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 preference layout

图 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="CarUiPreference">
      <!-- Toggle for showing chevron -->
      <attr name="showChevron" format="boolean" />
      <!-- Show ripple when disabled preference is clicked -->
      <attr name="showRippleOnDisabledPreference" 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/android">
  <item android:state_enabled="false" android:drawable="@drawable/car_ui_preference_icon_chevron_disabled"/>
  <item android:state_enabled="true" android:drawable="@drawable/car_ui_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.CarUi">
        <item name="allowDividerBelow">false</item>
        <item name="allowDividerAbove">false</item>
        <item name="android:layout">@layout/car_ui_preference</item>
</style>

如果上面的样式中的布局正在被叠加，则客户端需要确保新布局至少提供相应的 androidx 类所需的 ID。这也适用于使用此基本样式的其他元素。

CarUiDropDownPreference

这是 androidx.preference.DropDownPreference 类的 CarUi 等效类，并使用以下样式

<style name="Preference.CarUi.DropDown">
        <item name="android:layout">@layout/car_ui_preference_dropdown</item>
</style>

CarUiRadioButtonPreference

此 androidx.preference.TwoStatePreference 的子类在初始化期间会扩充 car_ui_radio_button_preference_widget 布局。如果此布局在 RRO 中被叠加，则新布局必须包含 android.widget.RadioButton 类型的元素，ID 为 R.id.radio_button，并且还必须包含基类所需的其他元素和 ID。

CarUiSwitchPreference

这是 androidx.preference.SwitchPreference 类的 CarUi 等效类。区别在于，当此元素未启用时，会显示一个 Toast 消息。可以通过在 Android 10 和 Android 11 中调用 setMessageToShowWhenDisabledPreferenceClicked 方法来自定义 Toast 消息。此元素使用以下样式

<style name="Preference.CarUi.SwitchPreference">
        <item name="android:widgetLayout">@layout/car_ui_preference_widget_switch</item>
        <item name="android:switchTextOn">@string/car_ui_preference_switch_on</item>
        <item name="android:switchTextOff">@string/car_ui_preference_switch_off</item>
</style>

CarUiTwoActionPreference

启用辅助操作的 CarUiPreference 的子类。下面提供了可用于自定义此元素的属性。

<declare-styleable name="CarUiTwoActionPreference">
        <!-- Determines if the secondary action is initially shown -->
        <attr name="actionShown" format="boolean"/>
</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.EditTextPreference">
        <item name="android:dialogLayout">@layout/car_ui_preference_dialog_edittext</item>
</style>

如果上面的样式中的布局正在被叠加，则客户端需要确保新布局提供 androidx.preference.EditTextPreference 类所需的 ID。

EditTextPreferenceDialogFragment

PreferenceDialogFragment 的直接子类。此外，也是 androidx.preference.PreferenceDialogFragments 类的 CarUi 等效类。客户端应使用此类来呈现任何主题化的平台 AlertDialog。

CarUiSeekBarDialogPreference

androidx.preference.DialogPreference 类的实现，它提供 SeekBar 功能

<style name="Preference.CarUi.SeekBarPreference">
        <item name="android:layout">@layout/car_ui_preference_widget_seekbar</item>
        <item name="adjustable">true</item>
        <item name="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 的布局的片段。