cw-omnibus 实战:用 PreferenceActivity 双面板实现大屏 Master-Detail 偏好设置
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 右内边距)。
八、大小屏适配的完整闭环
把上文各部分串起来,即可还原该示例完整的运行流程:
- 手机(小屏单面板):
onIsHidingHeaders()或!onIsMultiPane()成立 →needResource = true→onCreate中addPreferencesFromResource(R.xml.preferences),直接展示全部偏好项列表; - 平板(大屏双面板):走
loadHeadersFromResource(R.xml.preference_headers, target)→ 左列显示 "Some Settings" Header → 点击后实例化StockPreferenceFragment,并从<extra>注入的resource=preferences参数动态加载右侧编辑区; - 无论哪种形态,用户的每一项选择都会写入默认 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 白名单写法,可以覆盖绝大多数偏好设置界面的架构需求。