本頁面由 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 包含簡單的 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 會顯示儲存的內容的長度的值：

顯示 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敬上提供更具體的邏輯

設定意圖

您可以在 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 的額外項目：

<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 範例，其可啟動網頁：

<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;
});