cw-omnibus 实战:用 PreferenceActivity 双面板实现大屏 Master-Detail 偏好设置

原创2026-10-15 11:05:431,890 阅读
文章标签:示例工程教程

cw-omnibus 实战:用 PreferenceActivity 双面板实现大屏 Master-Detail 偏好设置

本文基于开源仓库 cw-omnibus 中 Prefs/SingleHeader 示例工程,系统讲解如何基于 PreferenceActivity 的 headers + fragments 机制,在平板等大屏设备上以 Master-Detail(左列设置项分组、右列偏好编辑区)风格呈现设置界面,同时在小屏设备上自动降级为单页列表。读完本文,你将掌握 onBuildHeaders、isValidFragment、PreferenceFragment 动态资源加载与 SharedPreferences 回读展示的完整套路。

一、示例工程要解决什么问题

Prefs/SingleHeader/README.markdown 的开篇说明非常直白:这是一个用于演示在更大屏幕上以 Master-Detail 风格组织偏好设置的 Android 示例应用。这类场景在真实产品中极为常见——手机屏幕只能一屏一屏地翻设置项,而平板、横屏设备有充足显示区域,可以将"设置分组导航"与"具体偏好编辑"并排摆放,减少跳转层级。

原文档指出该示例对应《The Busy Coder's Guide to Android Development》中关于高级偏好设置技巧(advanced preference tips)的章节。仓库内工程完整落地了这一技巧,代码规模小、职责清晰,非常适合作为理解 Android 官方偏好框架的入门样本。

二、工程结构与三条代码主线

Prefs/SingleHeader 目录是一个标准的 Gradle Android 工程,关键源码集中在 app/src/main 下:

角色 文件 职责
应用入口 FragmentsDemo.java 启动界面,通过菜单项跳转设置页
设置宿主 EditPreferences.java 继承 PreferenceActivity,决定双面板/单面板布局
通用偏好 Fragment StockPreferenceFragment.java 根据传入参数动态加载任意偏好 XML
偏好回显 Fragment PreferenceContentsFragment.java 读取 SharedPreferences,把当前值展示在表格中
Header 导航定义 preference_headers.xml 声明设置分组与对应 Fragment
偏好项定义 preferences.xml 四种典型偏好控件
布局与资源 main.xml、content.xml、arrays.xml、strings.xml、styles.xml 界面骨架、文案、列表数据与样式

从 AndroidManifest.xml 可以看到 minSdkVersion="14"、targetSdkVersion="14"——即该示例面向 Android 4.0(API 14)及以上,这个版本恰好是 PreferenceActivity 引入 headers 机制的起点。

三、入口导航:从菜单到设置页

应用主页 FragmentsDemo.java 是一个普通的 Activity,在 onCreate 中加载 main.xml。main.xml 极简到只有一个 <fragment> 标签:

<fragment xmlns:android="http://schemas.android.com/apk/res/android"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    android:name="com.commonsware.android.pref1header.PreferenceContentsFragment"/>

也就是说,应用首页直接用静态 Fragment 方式嵌入了"当前偏好值一览表"(详见第五节)。

进入设置界面的入口在选项菜单中。菜单资源 actions.xml 声明了一个 settings 菜单项,onOptionsItemSelected 里通过显式 Intent 启动设置页:

case R.id.settings:
    startActivity(new Intent(this, EditPreferences.class));
    return(true);

这条调用链的走向非常清晰:首页 → 菜单 → EditPreferences(PreferenceActivity)→ 系统根据屏幕尺寸决定单/双面板呈现。

四、核心:EditPreferences 的双面板决策逻辑

设置页宿主 EditPreferences.java 是本示例的灵魂。它继承 PreferenceActivity,重写了三个关键回调:

4.1 onBuildHeaders:装载导航

@Override
public void onBuildHeaders(List<Header> target) {
    if (onIsHidingHeaders() || !onIsMultiPane()) {
        needResource = true;
    }
    else {
        loadHeadersFromResource(R.xml.preference_headers, target);
    }
}

PreferenceActivity 框架的机制是:当 Activity 被创建后,系统会调用 onBuildHeaders 让开发者填充设置分组(Header)。框架在大屏多面板模式下会先展示 Header 列表,用户点击某项后再把对应的 Fragment 塞进右侧编辑区;而在单面板模式下只显示一个列表。

这里的 onIsHidingHeaders() 与 onIsMultiPane() 正是框架暴露给子类判断当前布局形态的两个钩子:

  • onIsMultiPane() 返回当前是否处于双面板布局;
  • onIsHidingHeaders() 返回框架是否准备隐藏 Header 列表(即单面板直进模式)。

如果命中"隐藏 headers"或"非双面板"任一条件,意味着框架不会走"Header → Fragment"的导航流程,此时必须把整个偏好界面作为一个整体加载,于是设置 needResource = true 标记,等待 onCreate 兜底。

4.2 onCreate 兜底:单面板降级

@Override
public void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);

    if (needResource) {
        addPreferencesFromResource(R.xml.preferences);
    }
}

这是一个非常巧妙的"降级开关":双面板场景下由 loadHeadersFromResource 建立导航;单面板场景下则直接在 Activity 里 addPreferencesFromResource(R.xml.preferences),把 preferences.xml 中的全部偏好项一次性渲染为列表。开发者只需要维护同一个 preferences.xml,两套 UI 形态共用一份偏好定义。

4.3 isValidFragment:Fragment 白名单

@Override
protected boolean isValidFragment(String fragmentName) {
    return(StockPreferenceFragment.class.getName().equals(fragmentName));
}

这是 Android 4.2(API 17)之后的安全要求:PreferenceActivity 会从 Intent extra 或 Header 中解析 Fragment 类名并通过反射实例化,为防止"Fragment 注入"攻击,必须用 isValidFragment 校验目标类。这里把 StockPreferenceFragment 列入白名单,任何不属于白名单的 Fragment 名称都会被框架拒绝。

对照参考:仓库中的 Prefs/FragmentsBC 示例展示了白名单放行多个 Fragment 的写法——EditPreferences.isValidFragment 对内部静态类 First 与 Second 均返回 true,它们分别加载 preferences.xml 与 preferences2.xml。

五、通用 Fragment:一份代码加载任意偏好资源

StockPreferenceFragment.java 是一个高度可复用的 PreferenceFragment,它不从代码写死资源,而是从 Fragment 参数中读取 XML 资源名并动态解析:

int res = getActivity().getResources()
                       .getIdentifier(getArguments().getString("resource"),
                                      "xml",
                                      getActivity().getPackageName());

addPreferencesFromResource(res);
  • getArguments().getString("resource") 取出调用方传入的资源名(如 "preferences");
  • getResources().getIdentifier(name, "xml", packageName) 按包名 + xml 类型动态解析出资源 ID;
  • addPreferencesFromResource(res) 装载并渲染。

这种写法意味着多个 Header 可以共享同一个 Fragment 类,只需在 Header 的 <extra> 中传递不同的资源名,即可渲染不同的偏好分组,无需为每一组写一个 Fragment 子类。

对应的 Header 定义在 preference_headers.xml:

<preference-headers xmlns:android="http://schemas.android.com/apk/res/android">

    <header
        android:fragment="com.commonsware.android.pref1header.StockPreferenceFragment"
        android:summary="@string/header1summary"
        android:title="@string/header1title">
        <extra
            android:name="resource"
            android:value="preferences"/>
    </header>

</preference-headers>

要点拆解:

  • android:fragment 指向点击该 Header 时要启动的 Fragment 类;
  • <extra> 子元素会以 name/value 键值对形式注入 Fragment 的 arguments(即 StockPreferenceFragment 读取的 "resource" 参数);
  • android:title / android:summary 定义 Header 在左列导航中的标题与摘要文案,分别引用 strings.xml 中的 header1title("Some Settings")与 header1summary("A handful of values for you to tailor")。

仓库还保留了两个未启用的字符串 header2title/header2summary("More Settings"、"Well, we needed two headers"),从注释可以看出原始设计意图是演示多个 Header,即使最终只启用了一个,也完整保留了多分组扩展所需的全部资源定义。

六、偏好项定义:四种典型控件

双面板右侧编辑区加载的 preferences.xml 覆盖了 Android 偏好框架中最常用的四种控件类型:

偏好控件 key 交互形态
CheckBoxPreference checkbox 勾选框,开/关
RingtonePreference ringtone 弹出系统铃声选择器
EditTextPreference text 弹出文本输入对话框
ListPreference list 弹出单选列表对话框

以 ListPreference 为例,它通过 android:entries 与 android:entryValues 配对数据——显示名与存储值分离:

<ListPreference
    android:dialogTitle="@string/listdialogtitle"
    android:entries="@array/cities"
    android:entryValues="@array/airport_codes"
    android:key="list"
    android:summary="@string/pref4summary"
    android:title="@string/pref4title"/>

对应的数据定义在 arrays.xml:cities 是 9 个宾夕法尼亚城市名(Philadelphia、Pittsburgh、Allentown/Bethlehem、Erie、Reading、Scranton、Lancaster、Altoona、Harrisburg),airport_codes 是与之一一对应的机场三字码(PHL、PIT、ABE、ERI、RDG、AVP、LNS、AOO、MDT)。这种"显示城市、存储代码"的设计正是 ListPreference 最典型的业务用法。

RingtonePreference 还设置了 android:showDefault="true" 与 android:showSilent="true",让选择器额外提供"默认铃声"与"静音"两个选项,属于开箱即用的细节配置。EditTextPreference 通过 android:dialogTitle="@string/dialogtitle" 定制输入对话框标题。

所有偏好项都只声明 android:key 而不预置默认值,具体取值由用户交互产生,并由 PreferenceManager 统一写入默认 SharedPreferences 文件。

七、偏好回显:PreferenceContentsFragment 实时读取

应用主页通过 PreferenceContentsFragment.java 把当前偏好值实时展示出来,其布局是 content.xml——一个五行两列的 TableLayout,左列是加粗标签(Checkbox、Ringtone、Checkbox #2、Text、List),右列是 30sp 大号取值文本。

读取逻辑集中在 onResume:

SharedPreferences prefs =
    PreferenceManager.getDefaultSharedPreferences(getActivity());

checkbox.setText(Boolean.valueOf(prefs.getBoolean("checkbox", false)).toString());
ringtone.setText(prefs.getString("ringtone", "<unset>"));
checkbox2.setText(Boolean.valueOf(prefs.getBoolean("checkbox2", false)).toString());
text.setText(prefs.getString("text", "<unset>"));
list.setText(prefs.getString("list", "<unset>"));

值得注意的几点:

  • 使用 PreferenceManager.getDefaultSharedPreferences() 获取默认偏好文件,这与偏好控件默认写入的位置一致,无需自行指定文件名;
  • 布尔值通过 Boolean.valueOf(...) 转成字符串,checkbox2 对应 strings.xml 中的 pref5title("On. Off. It really doesn't matter.")——文本型偏好项在未设置时以 "<unset>" 占位;
  • 放在 onResume 而非 onCreate,保证每次从设置页返回首页时都能刷新显示最新的值,形成"设置 → 返回 → 看到新值"的闭环验证体验。

行号标签 R.id.checkbox、R.id.ringtone 等在 content.xml 中与 @+id/... 一一对应;左侧标签样式与右侧取值样式分别定义于 styles.xml(label 继承 value,加粗并增加 5dp 右内边距)。

八、大小屏适配的完整闭环

把上文各部分串起来,即可还原该示例完整的运行流程:

  1. 手机(小屏单面板):onIsHidingHeaders() 或 !onIsMultiPane() 成立 → needResource = true → onCreate 中 addPreferencesFromResource(R.xml.preferences),直接展示全部偏好项列表;
  2. 平板(大屏双面板):走 loadHeadersFromResource(R.xml.preference_headers, target) → 左列显示 "Some Settings" Header → 点击后实例化 StockPreferenceFragment,并从 <extra> 注入的 resource=preferences 参数动态加载右侧编辑区;
  3. 无论哪种形态,用户的每一项选择都会写入默认 SharedPreferences,首页的 PreferenceContentsFragment 在 onResume 时读取并刷新展示。

为了对比"运行时判断"与"资源限定符判断"两种适配思路,仓库还提供了姊妹工程 Prefs/SingleHeader2。它的做法是:

  • 在 values/bools.xml 定义 suppressHeader=true(默认小屏);
  • 在 values-large/bools.xml 覆盖为 false(大屏显示 Header);
  • 入口 Activity 通过 PreferenceActivity.EXTRA_SHOW_FRAGMENT 与 EXTRA_SHOW_FRAGMENT_ARGUMENTS 两个 Intent extra,直接把 StockPreferenceFragment 与 resource=preferences 参数传给 EditPreferences,实现"直接跳转到指定设置分组":
Intent i = new Intent(this, EditPreferences.class);
i.putExtra(PreferenceActivity.EXTRA_SHOW_FRAGMENT,
           StockPreferenceFragment.class.getName());
Bundle b = new Bundle();
b.putString("resource", "preferences");
i.putExtra(PreferenceActivity.EXTRA_SHOW_FRAGMENT_ARGUMENTS, b);
startActivity(i);

这一对照说明了 Android 偏好框架适配大屏的两条主流路径:SingleHeader 依赖 Activity 自身对 onIsMultiPane() 的运行时感知,SingleHeader2 依赖资源目录限定符(values-large)做编译期分流,两者都复用同一份偏好定义,殊途同归。

九、构建与运行

工程为标准的 Gradle 结构,根目录 settings.gradle 仅声明 include ':app',gradle/wrapper/gradle-wrapper.properties 提供 Gradle Wrapper。在 Android Studio 中直接以 Prefs/SingleHeader 为根目录打开工程,或在命令行执行 Gradle 构建任务(如 gradlew assembleDebug)即可编译安装。运行环境前提是 Android 4.0(API 14)及以上设备或模拟器——因为 headers 机制、Theme.Holo.Light.DarkActionBar 主题(见 AndroidManifest.xml)均要求该 API 级别。

要观察 Master-Detail 效果,建议在平板模拟器或横屏大屏设备上运行:启动应用后点击菜单进入设置,即可看到左列 Header 导航与右列偏好编辑区的并排双面板;若改为手机尺寸运行,则自动退化为整页偏好列表。修改偏好值并返回首页,PreferenceContentsFragment 中的表格会即时反映最新取值。

十、小结

Prefs/SingleHeader 虽然 README 只有寥寥数行,却浓缩了 Android 偏好框架在大屏适配上的核心范式:

  • 一份偏好定义(preferences.xml)双形态复用,通过 onIsHidingHeaders() / onIsMultiPane() 运行时决策实现单/双面板自动切换;
  • 通用 PreferenceFragment + <extra> 参数传递,让一个 Fragment 类服务多个设置分组,配合 isValidFragment 白名单保障安全;
  • SharedPreferences 与 PreferenceFragment 各司其职,前者负责持久化,后者负责渲染编辑,通过 PreferenceManager.getDefaultSharedPreferences() 无缝衔接。

对于需要在平板产品中提供"设置导航 + 编辑区"一体式体验的开发者,这份工程是可直接参考的最小完整实现;配合 SingleHeader2 的资源限定符方案与 FragmentsBC 的多 Fragment 白名单写法,可以覆盖绝大多数偏好设置界面的架构需求。

登录后查看全文
cw-omnibus