استفاده از مقادیر «اولویت» ذخیره‌شده   بخشی از 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، به ذخیره داده‌های کلید-مقدار مراجعه کنید.

برای کسب اطلاعات درباره روش‌های مختلف ذخیره کردن داده‌ها در 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، می‌توانید بین دو میانای زیر انتخاب کنید:

• Preference.OnPreferenceChangeListener
• SharedPreferences.OnSharedPreferenceChangeListener

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

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(...);

هشدار: برای جلوگیری از جمع‌آوری ناخواسته زباله، مرجع قوی برای شنونده ذخیره کنید. وقتی registerOnSharedPreferenceChangeListener() را فراخوانی می‌کنید، SharedPreferenceManager مرجع قوی‌ای برای شنونده ذخیره نمی‌کند. برای رسیدگی به این موضوع، می‌توانید onSharedPreferenceChanged() را مستقیماً در PreferenceFragmentCompat پیاده‌سازی کنید. همچنین می‌توانید متغیر نمونه ایجاد کنید، همان‌طور که در مثال زیر نشان داده شده است:

کاتلین

    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 حفظ کنید، می‌توانید از پایگاه داده سفارشی نیز استفاده کنید. اگر برنامه شما مقادیر را در پایگاه داده حفظ می‌کند یا اگر مقادیر مختص دستگاه هستند، همان‌طور که در مثال‌های زیر نشان داده شده است، یک پایگاه داده سفارشی می‌تواند مفید باشد.

پیاده‌سازی Datastore

برای پیاده‌سازی یک ذخیره‌گاه داده سفارشی، کلاسی ایجاد کنید که 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.
    }
}

توجه: فقط روش‌هایی را لغو کنید که توسط اشیاء Preference شما استفاده می‌شوند. فراخوانی روشی که پیاده‌سازی نکرده‌اید منجر به UnsupportedOperationException می‌شود.

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

فعال کردن datastore

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

برای فعال کردن پایگاه داده سفارشی برای 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 خاصی تنظیم شده است، هر مجموعه داده‌ای را که برای سلسله‌مراتب مربوطه تنظیم شده است لغو می‌کند. در بیشتر موارد، یک پایگاه داده برای کل سلسله‌مراتب تنظیم می‌کنید.

توجه: اگر پس‌از پیوست شدن Preference به سلسله‌مراتب، برای آن Preference یک datastore تنظیم کنید، مقدار اولیه برای آن Preference دوباره منتشر نمی‌شود.