تنظیمات خود را سفارشی کنید بخشی از 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 زیر را فرض کنید:

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