تنظيم صفحاتك في مجموعات
يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.
إذا كانت لديك مجموعة صغيرة نسبيًا من القيم الأساسية التي ترغب في حفظها،
يمكنك استخدام واجهات برمجة تطبيقات SharedPreferences. كائن SharedPreferences
تشير إلى ملف يحتوي على أزواج المفتاح/القيمة ويوفر طرقًا بسيطة لقراءة
وأكتبها. تتم إدارة كل ملف SharedPreferences من خلال إطار العمل
يمكن أن تكون خاصة أو مشتركة.
توضّح لك هذه الصفحة كيفية استخدام واجهات برمجة تطبيقات SharedPreferences لتخزين
لاسترداد قيم بسيطة.
التعرُّف على الإعدادات المفضّلة المشتركة
يمكنك إنشاء ملف إعدادات مفضّل مشترك جديد أو الوصول إلى ملف حالي عن طريق طلب
باستخدام إحدى هذه الطرق:
getSharedPreferences(): استخدِم هذا الخيار إذا كنت بحاجة إلى ملفات مشتركة متعددة
ملفات التفضيلات المحددة بالاسم، والتي تحددها أولاً
. يمكنك الاتصال بهذا الاسم من أي Context في تطبيقك.
getPreferences(): يمكنك استخدام هذا الرمز من Activity إذا كنت بحاجة إلى ذلك.
استخدام ملف تفضيل مشترك واحد فقط للنشاط. لأن هذا
تسترد ملف تفضيل مشترك افتراضي ينتمي إلى النشاط،
ولا تحتاج إلى تقديم اسم.
على سبيل المثال، يصل الرمز التالي إلى ملف التفضيلات المشترك و
التي تم تحديدها بواسطة سلسلة المورد R.string.preference_file_key وفتحها
باستخدام الوضع الخاص حتى لا يتمكن أحد سوى تطبيقك من الوصول إلى الملف:
عند تسمية ملفات التفضيلات المشتركة، يجب استخدام اسم فريد
يمكن التعرف عليها من خلال تطبيقك. وهناك طريقة جيدة للقيام بذلك وهي بادئة اسم الملف
معرّف الطلب. مثل:
"com.example.myapp.PREFERENCE_FILE_KEY"
بدلاً من ذلك، إذا كنت تحتاج إلى ملف تفضيلات مشترك واحد فقط لنشاطك،
يمكنك استخدام الطريقة getPreferences():
إذا كنت تستخدم واجهة برمجة تطبيقات SharedPreferences لحفظ إعدادات التطبيق، عليك
بدلاً من ذلك استخدام getDefaultSharedPreferences() للحصول على القيمة التلقائية
مشاركة ملف الإعدادات المفضّلة لتطبيقك بالكامل. لمزيد من المعلومات، يُرجى الاطّلاع على
دليل مطوِّري الإعدادات
الكتابة إلى الإعدادات المفضّلة المشتركة
للكتابة إلى ملف الإعدادات المفضّلة المشتركة، يمكنك إنشاء SharedPreferences.Editor.
من خلال الاتصال بـ edit() على SharedPreferences.
مرِّر المفاتيح والقيم التي تريد كتابتها باستخدام طرق مثل:
putInt() وputString() اتصِل بعد ذلك بالرقم apply() أو
commit() لحفظ التغييرات. مثلاً:
يغيّر apply() الكائن SharedPreferences في الذاكرة على الفور، ولكن
يكتب التحديثات على القرص بشكل غير متزامن. بدلاً من ذلك، يمكنك استخدام commit().
لكتابة البيانات على القرص بشكل متزامن. ولكن نظرًا لأن commit() متزامن،
يجب تجنُّب استدعائه من سلسلة التعليمات الرئيسية لأنّه قد يؤدي إلى إيقاف واجهة المستخدم مؤقتًا
العرض.
القراءة من الإعدادات المفضّلة المشتركة
لاسترداد القيم من ملف تفضيلات مشترك، يمكن استخدام طرق الاتصال مثل
getInt() وgetString()، لتوفير المفتاح للقيمة التي
نريده، واختياريًا قيمة افتراضية يتم عرضها إذا لم يكن المفتاح موجودًا. بالنسبة
مثال:
يخضع كل من المحتوى وعيّنات التعليمات البرمجية في هذه الصفحة للتراخيص الموضحّة في ترخيص استخدام المحتوى. إنّ Java وOpenJDK هما علامتان تجاريتان مسجَّلتان لشركة Oracle و/أو الشركات التابعة لها.
تاريخ التعديل الأخير: 2025-07-27 (حسب التوقيت العالمي المتفَّق عليه)
[null,null,["تاريخ التعديل الأخير: 2025-07-27 (حسب التوقيت العالمي المتفَّق عليه)"],[],[],null,["# Save simple data with SharedPreferences\n\nIf you have a relatively small collection of key-values that you'd like to save,\nyou can use the [`SharedPreferences`](/reference/android/content/SharedPreferences) APIs. A `SharedPreferences` object\npoints to a file containing key-value pairs and provides simple methods to read\nand write them. Each `SharedPreferences` file is managed by the framework and\ncan be private or shared.\n\nThis page shows you how to use the `SharedPreferences` APIs to store and\nretrieve simple values.\n| **Caution:** `DataStore` is a modern data storage solution that you should use instead of `SharedPreferences`. It builds on Kotlin coroutines and Flow, and overcomes many of the drawbacks of `SharedPreferences`.\n|\n| Read the [DataStore guide](/topic/libraries/architecture/datastore) for more information.\n| **Note:** The `SharedPreferences` APIs are for reading and writing key-value pairs, and you shouldn't confuse them with the [`Preference`](/reference/android/preference/Preference) APIs, which help you build a user interface for your app settings (although they also use `SharedPreferences` to save the user's settings). For information about the [`Preference`](/reference/android/preference/Preference) APIs, see the [Settings developer guide](/guide/topics/ui/settings).\n\nGet a handle to shared preferences\n----------------------------------\n\nYou can create a new shared preference file or access an existing one by calling\none of these methods:\n\n- **[`getSharedPreferences()`](/reference/android/content/Context#getSharedPreferences(java.lang.String,%20int)):** Use this if you need multiple shared preference files identified by name, which you specify with the first parameter. You can call this from any [`Context`](/training/data-storage/shared-preferences#kotlin:%7E:text=this%20from%20any-,Context,-in%20your%20app) in your app.\n- **[`getPreferences()`](/reference/android/app/Activity#getPreferences(int)):** Use this from an [`Activity`](/reference/android/app/Activity) if you need to use only one shared preference file for the activity. Because this retrieves a default shared preference file that belongs to the activity, you don't need to supply a name.\n\nFor example, the following code accesses the shared preferences file that's\nidentified by the resource string `R.string.preference_file_key` and opens it\nusing the private mode so the file is accessible by only your app: \n\n### Kotlin\n\n```kotlin\nval sharedPref = activity?.getSharedPreferences(\n getString(R.string.preference_file_key), Context.MODE_PRIVATE)\n```\n\n### Java\n\n```java\nContext context = getActivity();\nSharedPreferences sharedPref = context.getSharedPreferences(\n getString(R.string.preference_file_key), Context.MODE_PRIVATE);\n```\n\nWhen naming your shared preference files, you should use a name that's uniquely\nidentifiable to your app. A good way to do this is prefix the file name with\nyour [application ID](/studio/build/configure-app-module#set_the_application_id). For example:\n`\"com.example.myapp.PREFERENCE_FILE_KEY\"`\n\nAlternatively, if you need just one shared preference file for your activity,\nyou can use the [`getPreferences()`](/reference/android/app/Activity#getPreferences(int)) method: \n\n### Kotlin\n\n```kotlin\nval sharedPref = activity?.getPreferences(Context.MODE_PRIVATE)\n```\n\n### Java\n\n```java\nSharedPreferences sharedPref = getActivity().getPreferences(Context.MODE_PRIVATE);\n```\n| **Caution:** The [`MODE_WORLD_READABLE`](/reference/android/content/Context#MODE_WORLD_READABLE) and [`MODE_WORLD_WRITEABLE`](/reference/android/content/Context#MODE_WORLD_WRITEABLE) modes have been deprecated since API level 17.\n|\n| Starting with Android 7.0 (API level 24), Android throws a\n| [`SecurityException`](/reference/java/lang/SecurityException) if you use them. If your app needs to share private\n| files with other apps, it may use a [`FileProvider`](/reference/androidx/core/content/FileProvider) with the\n| [`FLAG_GRANT_READ_URI_PERMISSION`](/reference/android/content/Intent#FLAG_GRANT_READ_URI_PERMISSION). For more information, also see\n| [Sharing Files](/training/secure-file-sharing).\n\nIf you're using the `SharedPreferences` API to save app settings, you\nshould instead use [`getDefaultSharedPreferences()`](/reference/android/preference/PreferenceManager#getDefaultSharedPreferences(android.content.Context)) to get the default\nshared preference file for your entire app. For more information, see the\n[Settings developer guide](/guide/topics/ui/settings).\n\nWrite to shared preferences\n---------------------------\n\nTo write to a shared preferences file, create a [`SharedPreferences.Editor`](/reference/android/content/SharedPreferences.Editor)\nby calling [`edit()`](/reference/android/content/SharedPreferences#edit()) on your `SharedPreferences`.\n\nPass the keys and values you want to write with methods such as:\n[`putInt()`](/reference/android/content/SharedPreferences.Editor#putInt()) and[`putString()`](/reference/android/content/SharedPreferences.Editor#putString()). Then call [`apply()`](/reference/android/content/SharedPreferences.Editor#apply()) or\n[`commit()`](/reference/android/content/SharedPreferences.Editor#commit()) to save the changes. For example: \n\n### Kotlin\n\n```kotlin\nval sharedPref = activity?.getPreferences(Context.MODE_PRIVATE) ?: return\nwith (sharedPref.edit()) {\n putInt(getString(R.string.saved_high_score_key), newHighScore)\n apply()\n}\n```\n\n### Java\n\n```java\nSharedPreferences sharedPref = getActivity().getPreferences(Context.MODE_PRIVATE);\nSharedPreferences.Editor editor = sharedPref.edit();\neditor.putInt(getString(R.string.saved_high_score_key), newHighScore);\neditor.apply();\n```\n\n`apply()` changes the in-memory `SharedPreferences` object immediately but\nwrites the updates to disk asynchronously. Alternatively, you can use `commit()`\nto write the data to disk synchronously. But because `commit()` is synchronous,\nyou should avoid calling it from your main thread because it could pause your UI\nrendering.\n\nRead from shared preferences\n----------------------------\n\nTo retrieve values from a shared preferences file, call methods such as\n[`getInt()`](/reference/android/content/SharedPreferences#getInt(java.lang.String,%20int)) and [`getString()`](/reference/android/content/SharedPreferences#getString(java.lang.String,%20java.lang.String)), providing the key for the value you\nwant, and optionally a default value to return if the key isn't present. For\nexample: \n\n### Kotlin\n\n```kotlin\nval sharedPref = activity?.getPreferences(Context.MODE_PRIVATE) ?: return\nval defaultValue = resources.getInteger(R.integer.saved_high_score_default_key)\nval highScore = sharedPref.getInt(getString(R.string.saved_high_score_key), defaultValue)\n```\n\n### Java\n\n```java\nSharedPreferences sharedPref = getActivity().getPreferences(Context.MODE_PRIVATE);\nint defaultValue = getResources().getInteger(R.integer.saved_high_score_default_key);\nint highScore = sharedPref.getInt(getString(R.string.saved_high_score_key), defaultValue);\n```"]]
