此页面由 Cloud Translation API 翻译。

自定义您的设置 Android Jetpack 的一部分。

本文档介绍了如何自定义层次结构中的 Preference 对象。

查找偏好设置

如需访问单独的 Preference（例如在获取或设置 Preference 值时），请使用 PreferenceFragmentCompat.findPreference()。此方法会在整个层次结构中搜索具有指定键的 Preference。

例如，要访问 EditTextPreference，带有 "signature" 键，请执行以下操作：

<EditTextPreference
        app:key="signature"
        app:title="Your signature"/>

使用以下代码检索此 Preference：

Kotlin

override fun onCreatePreferences(savedInstanceState: Bundle?, rootKey: String?) {
    setPreferencesFromResource(R.xml.preferences, rootKey)
    val signaturePreference: EditTextPreference? = findPreference("signature")
    // Do something with this preference.
}

Java

@Override
public void onCreatePreferences(Bundle savedInstanceState, String rootKey) {
    setPreferencesFromResource(R.xml.preferences, rootKey);
    EditTextPreference signaturePreference = findPreference("signature");
    // Do something with this preference.
}

控制偏好设置可见性

您可以控制当用户对用户可见的 Preference 对象时前往“设置”屏幕例如，如果某个 Preference 仅在对应的功能启用时才有意义，不妨在该功能停用时隐藏该 Preference。

如需仅在满足条件时显示 Preference，请先设置 Preference 在 XML 中将可见性设置为 false，如以下示例所示：

<EditTextPreference
        app:key="signature"
        app:title="Your signature"
        app:isPreferenceVisible="false"/>

在 onCreatePreferences() 中，在以下情况下显示 Preference：条件：

Kotlin

override fun onCreatePreferences(savedInstanceState: Bundle?, rootKey: String?) {
    setPreferencesFromResource(R.xml.preferences, rootKey)
    if(/*some feature*/) {
        val signaturePreference: EditTextPreference? = findPreference("signature")
        signaturePreference?.isVisible = true
    }
}

Java

@Override
public void onCreatePreferences(Bundle savedInstanceState, String rootKey) {
    setPreferencesFromResource(R.xml.preferences, rootKey);
    if(/*some feature*/) {
        EditTextPreference signaturePreference = findPreference("signature");
        if (signaturePreference != null) {
            signaturePreference.setVisible(true);
        }
    }
}

动态更新摘要

保留数据的 Preference 必须在其摘要，以帮助用户更好地了解 Preference。例如，EditTextPreference 必须显示已保存的文本值，并且 ListPreference 必须显示选定的列表条目。您可能还会有 Preference 个对象需要根据内部更新或外部应用状态，例如显示版本的 Preference 数字。为此，您可以使用 SummaryProvider。

使用 SimpleSummaryProvider

ListPreference 和 EditTextPreference 包含一个自动将已保存的 Preference 值显示为摘要的简单 SummaryProvider 实现。如果未保存任何值，则会显示“未保存” 。”

要从 XML 中启用这些实现，请将 app:useSimpleSummaryProvider="true"。

或者，您也可以通过代码启用：使用 ListPreference.SimpleSummaryProvider.getInstance() 和 EditTextPreference.SimpleSummaryProvider.getInstance() 获取简单的 SummaryProvider 实例，然后在 Preference 上进行设置，如以下示例所示：

Kotlin

listPreference.summaryProvider = ListPreference.SimpleSummaryProvider.getInstance()
editTextPreference.summaryProvider = EditTextPreference.SimpleSummaryProvider.getInstance()

Java

listPreference.setSummaryProvider(ListPreference.SimpleSummaryProvider.getInstance());
editTextPreference.setSummaryProvider(EditTextPreference.SimpleSummaryProvider.getInstance());

使用自定义 SummaryProvider

无论 Preference 何时提出摘要请求，您都可以创建自己的 SummaryProvider 并替换 provideSummary()，以便对摘要进行自定义。对于下面的 EditTextPreference 显示了其已保存文本的长度值作为摘要：

显示 EditTextPreference 示例的图片 — **图 1.** `EditTextPreference` 示例。

举例来说，假设存在以下 EditTextPreference：

<EditTextPreference
        app:key="counting"
        app:title="Counting preference"/>

在 onCreatePreferences() 中，您可以创建新的 SummaryProvider 并替换 provideSummary()，用于返回要显示的摘要：

Kotlin

val countingPreference: EditTextPreference? = findPreference("counting")

countingPreference?.summaryProvider = SummaryProvider<EditTextPreference> { preference ->
    val text = preference.text
    if (text.isNullOrEmpty()) {
        "Not set"
    } else {
        "Length of saved value: " + text.length
    }
}

Java

EditTextPreference countingPreference = findPreference("counting");

if (countingPreference != null) {
    countingPreference.setSummaryProvider(new SummaryProvider<EditTextPreference>() {
        @Override
        public CharSequence provideSummary(EditTextPreference preference) {
            String text = preference.getText();
            if (TextUtils.isEmpty(text) || text == null){
                return "Not set";
            }
            return "Length of saved value: " + text.length();
        }
    });
}

Preference 摘要会显示已保存值的长度，或为“未设置” 如果不存在已存值，则会发生此错误。

自定义 EditTextPreference 对话框

在 EditTextPreference 对话框中，您可以通过以下方式自定义文本字段行为：将一个 OnBindEditTextListener。系统在向用户显示对话框时会调用此监听器。

例如，您可以自定义对话框以仅接受数字。首先，创建 EditTextPreference：

<EditTextPreference
        app:key="number"
        app:title="Numbers only preference"/>

接下来，在 onCreatePreferences() 中创建一个新的 OnBindEditTextListener，并替换 onBindEditText() 以在向EditText 用户。

Kotlin

val numberPreference: EditTextPreference? = findPreference("number")

numberPreference?.setOnBindEditTextListener { editText ->
    editText.inputType = InputType.TYPE_CLASS_NUMBER
}

Java

EditTextPreference numberPreference = findPreference("number");

if (numberPreference != null) {
    numberPreference.setOnBindEditTextListener(
            new EditTextPreference.OnBindEditTextListener() {
                @Override
                public void onBindEditText(@NonNull EditText editText) {
                    editText.setInputType(InputType.TYPE_CLASS_NUMBER);
                }
            });
}

现在，当系统向用户显示对话框时，键盘会以纯数字模式打开模式，因此用户只能在 EditText 中输入数字。

偏好设置操作

在点按时，Preference 可产生特定操作。例如， Preference 可用作指向应用中单独部分的链接。添加操作设置为 Preference，您可以直接在 Preference 上设置 Intent，也可以可以设置 OnPreferenceClickListener 以了解更具体的逻辑。

设置 Intent

您可以在 Preference 上设置 Intent 以启动新的 Fragment， Activity 或单独的应用。Preference这是与使用 Context.startActivity() 具有指定 Intent 的实体。

您可以使用嵌套 <intent> 标记在 XML 中设置 Intent。以下示例定义了启动 Activity 的 Intent：

<Preference
        app:key="activity"
        app:title="Launch activity">
    <intent
            android:targetPackage="com.example"
            android:targetClass="com.example.ExampleActivity"/>
</Preference>

或者，您也可以直接在 Preference 上使用 setIntent()，如下所示：

Kotlin

val intent = Intent(context, ExampleActivity::class.java)
activityPreference.setIntent(intent)

Java

Intent intent = new Intent(getContext(), ExampleActivity.class);
activityPreference.setIntent(intent);

您还可以使用 XML 通过 Intent 添加 extra：

<Preference
        app:key="activity"
        app:title="Launch activity">
    <intent
            android:targetPackage="com.example"
            android:targetClass="com.example.ExampleActivity">
        <extra
                android:name="example_key"
                android:value="example_value"/>
    </intent>
</Preference>

以下为 Preference 的示例，其中带有启动网页的 Intent：

<Preference
        app:key="webpage"
        app:title="View webpage">
    <intent
            android:action="android.intent.action.VIEW"
            android:data="http://www.google.com" />
</Preference>

Kotlin

val intent = Intent(Intent.ACTION_VIEW)
intent.data = Uri.parse("http://www.google.com")

val webpagePreference = findPreference("webpage")
webpagePreference?.intent = intent

Java

Intent intent = new Intent(Intent.ACTION_VIEW);
intent.setData(Uri.parse("http://www.google.com"));
webpagePreference.setIntent(intent);

OnPreferenceClickListener

您可以在 Preference 上设置 OnPreferenceClickListener，这会添加一个在点按 Preference 时对 onPreferenceClick() 进行回调。例如：如果需要，您可以使用监听器导航到另一个 Fragment 或 Activity 具有更复杂的逻辑来处理导航。

如需设置 OnPreferenceClickListener，请使用与下方所示内容类似的代码：

Kotlin

onClickPreference.setOnPreferenceClickListener({
    // Do something.
    true
})

Java

onClickPreference.setOnPreferenceClickListener(preference -> {
    // Do something.
    return true;
});