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