تنظیمات خود را سفارشی کنید بخشی از Android Jetpack .
این سند نحوه سفارشی کردن اشیاء Preference
را در سلسله مراتب خود شرح می دهد.
ترجیحات را پیدا کنید
برای دسترسی به یک Preference
فردی، مانند هنگام دریافت یا تنظیم یک مقدار Preference
، از PreferenceFragmentCompat.findPreference()
استفاده کنید. این روش کل سلسله مراتب را برای یک Preference
با کلید داده شده جستجو می کند.
به عنوان مثال، برای دسترسی به EditTextPreference
با کلید "signature"
، موارد زیر را انجام دهید:
<EditTextPreference app:key="signature" app:title="Your signature"/>
این Preference
با استفاده از کد زیر بازیابی کنید:
کاتلین
override fun onCreatePreferences(savedInstanceState: Bundle?, rootKey: String?) { setPreferencesFromResource(R.xml.preferences, rootKey) val signaturePreference: EditTextPreference? = findPreference("signature") // Do something with this preference. }
جاوا
@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
هنگامی که شرط مربوطه برآورده شد نشان دهید:
کاتلین
override fun onCreatePreferences(savedInstanceState: Bundle?, rootKey: String?) { setPreferencesFromResource(R.xml.preferences, rootKey) if(/*some feature*/) { val signaturePreference: EditTextPreference? = findPreference("signature") signaturePreference?.isVisible = true } }
جاوا
@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
تنظیم کنید، همانطور که در مثال زیر نشان داده شده است:
کاتلین
listPreference.summaryProvider = ListPreference.SimpleSummaryProvider.getInstance() editTextPreference.summaryProvider = EditTextPreference.SimpleSummaryProvider.getInstance()
جاوا
listPreference.setSummaryProvider(ListPreference.SimpleSummaryProvider.getInstance()); editTextPreference.setSummaryProvider(EditTextPreference.SimpleSummaryProvider.getInstance());
از یک SummaryProvider سفارشی استفاده کنید
شما می توانید SummaryProvider
خود را ایجاد کنید و provideSummary()
برای سفارشی کردن خلاصه هر زمان که توسط Preference
درخواست شد لغو کنید. به عنوان مثال، EditTextPreference
زیر طول مقدار ذخیره شده خود را به عنوان خلاصه نمایش می دهد:
![تصویری که نمونه EditTextPreference را نشان می دهد](https://developer.android.com/static/develop/ui/views/components/settings/images/settings-customsummaryprovider.png?authuser=2&hl=fa)
EditTextPreference
. به عنوان مثال، EditTextPreference
زیر را فرض کنید:
<EditTextPreference app:key="counting" app:title="Counting preference"/>
در onCreatePreferences()
، می توانید یک SummaryProvider
جدید ایجاد کنید و provideSummary()
را لغو کنید تا خلاصه نمایش داده شود:
کاتلین
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 } }
جاوا
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
به کاربر نشان داده شود، آن را سفارشی کنید.
کاتلین
val numberPreference: EditTextPreference? = findPreference("number") numberPreference?.setOnBindEditTextListener { editText -> editText.inputType = InputType.TYPE_CLASS_NUMBER }
جاوا
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
، میتوانید یک Intent
مستقیماً روی Preference
تنظیم کنید یا میتوانید یک OnPreferenceClickListener
را برای منطق خاصتر تنظیم کنید.
یک Intent تنظیم کنید
میتوانید یک Intent
on Preference
را تنظیم کنید تا هر زمان که روی Preference
ضربه میزنید، یک Fragment
، Activity
یا برنامه جداگانه راهاندازی شود. این همان استفاده از Context.startActivity()
با یک Intent
است.
شما می توانید یک Intent
را در XML با استفاده از یک تگ <intent>
تودرتو تنظیم کنید. مثال زیر یک Intent
را تعریف می کند که یک Activity
راه اندازی می کند:
<Preference app:key="activity" app:title="Launch activity"> <intent android:targetPackage="com.example" android:targetClass="com.example.ExampleActivity"/> </Preference>
از طرف دیگر، میتوانید از setIntent()
مستقیماً در یک Preference
به صورت زیر استفاده کنید:
کاتلین
val intent = Intent(context, ExampleActivity::class.java) activityPreference.setIntent(intent)
جاوا
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>
در اینجا نمونه ای از Preference
با Intent
است که یک صفحه وب را راه اندازی می کند:
<Preference app:key="webpage" app:title="View webpage"> <intent android:action="android.intent.action.VIEW" android:data="http://www.google.com" /> </Preference>
کاتلین
val intent = Intent(Intent.ACTION_VIEW) intent.data = Uri.parse("http://www.google.com") val webpagePreference = findPreference("webpage") webpagePreference?.intent = intent
جاوا
Intent intent = new Intent(Intent.ACTION_VIEW); intent.setData(Uri.parse("http://www.google.com")); webpagePreference.setIntent(intent);
OnPreferenceClickListener
میتوانید یک OnPreferenceClickListener
را روی یک Preference
تنظیم کنید، که وقتی روی Preference
ضربه زده میشود، یک تماس برگشتی به onPreferenceClick()
اضافه میکند. برای مثال، اگر منطق پیچیدهتری برای مدیریت پیمایش دارید، میتوانید از شنونده برای پیمایش به Fragment
یا Activity
دیگری استفاده کنید.
برای تنظیم OnPreferenceClickListener
، از کدی شبیه به زیر استفاده کنید:
کاتلین
onClickPreference.setOnPreferenceClickListener({ // Do something. true })
جاوا
onClickPreference.setOnPreferenceClickListener(preference -> { // Do something. return true; });