自訂設定 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 範例的圖片](https://developer.android.google.cn/static/develop/ui/views/components/settings/images/settings-customsummaryprovider.png?authuser=9&hl=zh-tw)
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; });