استفاده از مقادیر ترجیحی ذخیره شده بخشی از Android Jetpack .

این سند نحوه ذخیره و استفاده از مقادیر Preference را که توسط کتابخانه Preference ذخیره می شوند، توضیح می دهد.

ذخیره سازی داده ترجیحی

این بخش توضیح می دهد که چگونه یک Preference می تواند داده ها را حفظ کند.

SharedPreferences

به طور پیش فرض، یک Preference از SharedPreferences برای ذخیره مقادیر استفاده می کند. SharedPreferences API از خواندن و نوشتن جفت های کلید-مقدار ساده از فایلی که در جلسات برنامه ذخیره می شود، پشتیبانی می کند. کتابخانه Preference از یک نمونه SharedPreferences خصوصی استفاده می کند تا فقط برنامه شما بتواند به آن دسترسی داشته باشد.

به عنوان مثال، SwitchPreferenceCompat زیر را فرض کنید:

<SwitchPreferenceCompat
        app:key="notifications"
        app:title="Enable message notifications"/>

هنگامی که کاربر این سوئیچ را به حالت "روشن" تغییر می دهد، فایل SharedPreferences با یک جفت کلید-مقدار "notifications" : "true" . کلید استفاده شده همان کلید تنظیم شده برای Preference است.

برای اطلاعات بیشتر درباره SharedPreferences API، به ذخیره داده‌های کلید-مقدار مراجعه کنید.

برای اطلاعات در مورد روش‌های مختلف ذخیره‌سازی داده‌ها در Android، مرور کلی داده‌ها و ذخیره‌سازی فایل را ببینید.

PreferenceDataStore

اگرچه کتابخانه Preference داده ها را به طور پیش فرض با SharedPreferences حفظ می کند، SharedPreferences همیشه راه حل ایده آلی نیست. به عنوان مثال، اگر برنامه شما نیاز به ورود کاربر به سیستم دارد، ممکن است بخواهید تنظیمات برنامه را در فضای ابری ادامه دهید تا تنظیمات در سایر دستگاه ها و پلتفرم ها منعکس شود. به طور مشابه، اگر برنامه شما دارای گزینه‌های پیکربندی خاص دستگاه باشد، هر کاربر در دستگاه تنظیمات جداگانه‌ای دارد که SharedPreferences را به راه‌حلی کمتر از ایده‌آل تبدیل می‌کند.

یک PreferenceDataStore به شما امکان می دهد از یک ذخیره سازی سفارشی برای حفظ مقادیر Preference استفاده کنید. برای اطلاعات بیشتر، به استفاده از ذخیره‌گاه داده سفارشی مراجعه کنید.

مقادیر ترجیحی را بخوانید

برای بازیابی شی SharedPreferences که استفاده می شود، PreferenceManager.getDefaultSharedPreferences() را فراخوانی کنید. اگرچه این روش در هر نقطه از برنامه شما کار می کند، توصیه می کنیم برنامه خود را به لایه ها تقسیم کنید. برای اطلاعات بیشتر، به لایه داده مراجعه کنید.

به عنوان مثال، یک EditTextPreference با کلید "signature" به صورت زیر داده می شود:

<EditTextPreference
        app:key="signature"
        app:title="Your signature"/>

می توانید مقدار ذخیره شده برای این Preference به صورت جهانی بازیابی کنید:

کاتلین 

val sharedPreferences = PreferenceManager.getDefaultSharedPreferences(this /* Activity context */)
val name = sharedPreferences.getString("signature", "")

جاوا 

SharedPreferences sharedPreferences =
        PreferenceManager.getDefaultSharedPreferences(this /* Activity context */);
String name = sharedPreferences.getString("signature", "");

به تغییرات مقادیر ترجیحی گوش دهید

برای گوش دادن به تغییرات مقادیر Preference ، می‌توانید بین دو رابط یکی را انتخاب کنید:

جدول زیر تفاوت این دو رابط را نشان می دهد:

OnPreferenceChangeListener OnSharedPreferenceChangeListener
روی یک Preference تنظیم کنید. برای همه اشیاء Preference اعمال می شود.
زمانی فراخوانی می‌شود که یک Preference قصد دارد مقدار ذخیره شده خود را تغییر دهد، حتی اگر مقدار در انتظار با مقدار ذخیره شده یکسان باشد. فقط زمانی فراخوانی می شود که مقدار ذخیره شده برای یک Preference تغییر کند.
فقط از طریق کتابخانه Preference تماس گرفته می شود. بخش جداگانه ای از برنامه می تواند مقدار ذخیره شده را تغییر دهد. هر زمان که مقدار ذخیره شده تغییر کند، فراخوانی می شود، حتی اگر از قسمت جداگانه ای از برنامه باشد.
قبل از ذخیره شدن مقدار معلق فراخوانی می شود. پس از ذخیره مقدار فراخوانی می شود.
هنگام استفاده از SharedPreferences یا PreferenceDataStore تماس گرفته می شود. فقط هنگام استفاده از SharedPreferences تماس گرفته می شود.

OnPreferenceChangeListener را پیاده سازی کنید

پیاده سازی OnPreferenceChangeListener به شما امکان می دهد به تغییرات معلق در مقدار یک Preference گوش دهید. سپس، می توانید تأیید کنید که آیا تغییر رخ می دهد یا خیر. به عنوان مثال، کد زیر نحوه گوش دادن به تغییر مقدار یک EditTextPreference را با کلید "name" نشان می دهد:

کاتلین 

override fun onPreferenceChange(preference: Preference, newValue: Any): Boolean {
    Log.e("preference", "Pending Preference value is: $newValue")
    return true
}

جاوا

@Override
public boolean onPreferenceChange(Preference preference, Object newValue) {
    Log.e("preference", "Pending Preference value is: " + newValue);
    return true;
}

در مرحله بعد، شما باید مستقیماً این شنونده را با setOnPreferenceChangeListener() به صورت زیر تنظیم کنید:

کاتلین 

preference.onPreferenceChangeListener = ...

جاوا 

preference.setOnPreferenceChangeListener(...);

OnSharedPreferenceChangeListener را پیاده سازی کنید

هنگامی که مقادیر Preference با استفاده از SharedPreferences ادامه می دهید، می توانید از SharedPreferences.OnSharedPreferenceChangeListener نیز برای گوش دادن به تغییرات استفاده کنید. این به شما امکان می‌دهد به زمانی که مقادیر ذخیره شده توسط Preference شما تغییر می‌کنند، مانند هنگام همگام‌سازی تنظیمات با یک سرور، گوش دهید. مثال زیر نشان می دهد که چگونه می توان برای تغییر مقدار یک EditTextPreference با کلید "name" گوش داد:

کاتلین 

override fun onSharedPreferenceChanged(sharedPreferences: SharedPreferences, key: String) {
    if (key == "signature") {
        Log.i(TAG, "Preference value was updated to: " + sharedPreferences.getString(key, ""))
    }
}

جاوا

@Override
public void onSharedPreferenceChanged(SharedPreferences sharedPreferences, String key) {
    if (key.equals("signature")) {
        Log.i(TAG, "Preference value was updated to: " + sharedPreferences.getString(key, ""));
    }
}

شنونده را با استفاده از registerOnSharedPreferenceChangedListener() به صورت زیر ثبت کنید:

کاتلین 

preferenceManager.sharedPreferences.registerOnSharedPreferenceChangeListener(...)

جاوا 

getPreferenceManager().getSharedPreferences().registerOnSharedPreferenceChangeListener(...);

کاتلین 

    val listener: SharedPreferences.OnSharedPreferenceChangeListener =
            SharedPreferences.OnSharedPreferenceChangeListener {...}

جاوا

    SharedPreferences.OnSharedPreferenceChangeListener listener =
            new SharedPreferences.OnSharedPreferenceChangeListener() {...}

برای مدیریت صحیح چرخه حیات در Activity یا Fragment خود، همانطور که در مثال زیر نشان داده شده است، این شنونده را در فراخوانی های onResume() و onPause() ثبت و لغو ثبت کنید:

کاتلین 

override fun onResume() {
    super.onResume()
    preferenceManager.sharedPreferences.registerOnSharedPreferenceChangeListener(this)
}

override fun onPause() {
    super.onPause()
    preferenceManager.sharedPreferences.unregisterOnSharedPreferenceChangeListener(this)
}

جاوا 

@Override
public void onResume() {
    super.onResume();
    getPreferenceManager().getSharedPreferences().registerOnSharedPreferenceChangeListener(this);
}

@Override
public void onPause() {
    super.onPause();
    getPreferenceManager().getSharedPreferences().unregisterOnSharedPreferenceChangeListener(this);
}

از یک دیتا استور سفارشی استفاده کنید

اگرچه توصیه می‌کنیم اشیاء Preference با استفاده از SharedPreferences ادامه دهید، می‌توانید از یک ذخیره‌گاه داده سفارشی نیز استفاده کنید. همانطور که در مثال های زیر نشان داده شده است، اگر برنامه شما مقادیری را در یک پایگاه داده حفظ کند یا اگر مقادیر مختص دستگاه باشد، می تواند مفید باشد.

دیتا استور را پیاده سازی کنید

برای پیاده سازی یک دیتا استور سفارشی، کلاسی ایجاد کنید که PreferenceDataStore را گسترش دهد. مثال زیر یک Datastore ایجاد می کند که مقادیر String مدیریت می کند:

کاتلین 

class DataStore : PreferenceDataStore() {
    override fun putString(key: String, value: String?) {
        // Save the value somewhere.
    }

    override fun getString(key: String, defValue: String?): String? {
        // Retrieve the value.
    }
}

جاوا 

public class DataStore extends PreferenceDataStore {
    @Override
    public void putString(String key, @Nullable String value) {
        // Save the value somewhere.
    }
    @Override
    @Nullable
    public String getString(String key, @Nullable String defValue) {
        // Retrieve the value.
    }
}

برای جلوگیری از مسدود شدن رابط کاربری، هرگونه عملیات وقت گیر را از موضوع اصلی اجرا کنید. از آنجایی که ممکن است Fragment یا Activity حاوی داده‌استور در حین باقی ماندن یک مقدار از بین برود، داده‌ها را سریال کنید تا هیچ مقداری را که کاربر تغییر داده است از دست ندهید.

دیتا استور را فعال کنید

پس از پیاده سازی datastore خود، دیتا استور جدید را در onCreatePreferences() تنظیم کنید تا اشیاء Preference به جای استفاده از SharedPreferences پیش فرض، مقادیر را با datastore حفظ کنند. می‌توانید برای هر Preference یا برای کل سلسله‌مراتب، یک datastore فعال کنید.

برای فعال کردن یک دیتا استور سفارشی برای یک Preference خاص، setPreferenceDataStore() را در Preference فراخوانی کنید، همانطور که در مثال زیر نشان داده شده است:

کاتلین 

val preference: Preference? = findPreference("key")
preference?.preferenceDataStore = dataStore

جاوا

Preference preference = findPreference("key");
if (preference != null) {
    preference.setPreferenceDataStore(dataStore);
}

برای فعال کردن یک دیتا استور سفارشی برای کل سلسله مراتب، setPreferenceDataStore() را در PreferenceManager فراخوانی کنید:

کاتلین 

val preferenceManager = preferenceManager
preferenceManager.preferenceDataStore = dataStore

جاوا

PreferenceManager preferenceManager = getPreferenceManager();
preferenceManager.setPreferenceDataStore(dataStore);

ذخیره‌سازی داده‌ای که برای یک Preference خاص تنظیم شده است، هر ذخیره‌گاه داده‌ای را که برای سلسله مراتب مربوطه تنظیم شده است لغو می‌کند. در بیشتر موارد، شما یک دیتا استور برای کل سلسله مراتب تنظیم می کنید.