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

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

查找偏好设置

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

例如，要访问键为 "signature" 的 EditTextPreference，请执行以下操作

<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 中将 Preference 可见性设置为 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 包含简单的 SummaryProvider 实现，这些实现会自动将保存的 Preference 值显示为摘要。如果未保存任何值，则显示“未设置”。

要从 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

您可以创建自己的 SummaryProvider 并重写 provideSummary() 以在 Preference 请求摘要时自定义摘要。例如，以下 EditTextPreference 将其保存值的长度显示为摘要

An image showing an example 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添加操作，可以直接在Preference上设置Intent，或者为了更具体的逻辑，可以设置OnPreferenceClickListener。

设置 Intent

可以在Preference上设置Intent，以便在点击Preference时启动新的Fragment、Activity或单独的应用。这与使用给定Intent的Context.startActivity()相同。

可以使用嵌套的<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中包含额外数据。

<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>

这是一个带有Intent的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;
});

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

查找偏好设置

Kotlin

Java

控制 Preference 可见性

Kotlin

Java

动态更新摘要

使用 SimpleSummaryProvider

Kotlin

Java

使用自定义 SummaryProvider

Kotlin

Java

自定义 EditTextPreference 对话框

Kotlin

Java

Preference 操作

设置 Intent

Kotlin

Java

Kotlin

Java

OnPreferenceClickListener

Kotlin

Java

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