حالات استخدام مساحة التخزين على Android وأفضل الممارسات المتعلِّقة بها

لمنح المستخدمين المزيد من التحكّم في ملفاتهم والحدّ من تشوّش الملفات، قدّمت نظام التشغيل Android 10 نموذجًا جديدًا لمساحة التخزين خاصًا بالتطبيقات يُعرف باسم مساحة التخزين المحصورة. تغيّر ميزة "نطاق التخزين" طريقة تخزين التطبيقات للملفات والوصول إليها على وحدة التخزين الخارجية للجهاز. لمساعدتك في نقل تطبيقك إلى مساحة التخزين المحصورة النطاق، اتّبِع أفضل الممارسات لحالات الاستخدام الشائعة لمساحة التخزين الموضّحة في هذا الدليل. يتم تنظيم حالات الاستخدام في فئتَين: التعامل مع ملفات الوسائط والتعامل مع الملفات غير الخاصة بالوسائط.

في كثير من الحالات، ينشئ تطبيقك ملفات لا تحتاج التطبيقات الأخرى إلى الوصول إليها أو لا يجب أن تصل إليها. يوفّر النظام مواقع تخزين خاصة بالتطبيقات لإدارة هذه الملفات.

لمزيد من المعلومات حول كيفية تخزين الملفات والوصول إليها على Android، يُرجى الاطّلاع على أدلة التدريب الخاصة بمساحة التخزين.

التعامل مع ملفات الوسائط

يوضّح هذا القسم بعض حالات الاستخدام الشائعة للتعامل مع ملفات الوسائط (ملفات الفيديو والصور والصوت)، ويشرح النهج العام الذي يمكن أن يستخدمه تطبيقك. يلخّص الجدول التالي كل حالة من حالات الاستخدام هذه، ويتضمّن روابط تؤدي إلى كل قسم من الأقسام التي تتضمّن المزيد من التفاصيل.

عرض ملفات الصور أو الفيديوهات من مجلدات متعددة

طلب البحث عن مجموعة وسائط باستخدام واجهة query() API لفلترة ملفات الوسائط أو ترتيبها، عدِّل المَعلمات projection وselection وselectionArgs وsortOrder.

عرض صور أو فيديوهات من مجلد معيّن

اتّبِع الخطوات التالية:

1. اتّبِع أفضل الممارسات الموضّحة في طلب أذونات التطبيق، واطلب إذن READ_EXTERNAL_STORAGE.
2. استرداد ملفات الوسائط استنادًا إلى قيمة MediaColumns.DATA، التي تحتوي على مسار نظام الملفات المطلق إلى عنصر الوسائط على القرص

الوصول إلى معلومات الموقع الجغرافي من الصور

إذا كان تطبيقك يستخدم مساحة التخزين المحصورة النطاق، اتّبِع الخطوات الواردة في قسم معلومات الموقع الجغرافي في الصور ضمن دليل تخزين الوسائط.

تحديد مكان التخزين لعمليات التنزيل الجديدة

إذا كان تطبيقك يستخدم ميزة "مساحة التخزين المحصورة"، عليك الانتباه إلى الموقع الجغرافي الذي تختار تخزين ملفات الوسائط التي تنزّلها فيه.

إذا كانت التطبيقات الأخرى تتطلّب الوصول إلى الملفات، ننصحك باستخدام مجموعات وسائط محددة جيدًا لعمليات التنزيل أو مجموعات المستندات.

في نظام التشغيل Android 11 والإصدارات الأحدث، لا يمكن للتطبيقات الأخرى الوصول إلى الملفات داخل الدليل الخارجي الخاص بالتطبيق، حتى إذا كنت تستخدم DownloadManager لجلب هذه الملفات.

تصدير ملفات وسائط المستخدم إلى جهاز

حدِّد موقعًا جغرافيًا تلقائيًا مناسبًا لتخزين ملفات الوسائط الخاصة بالمستخدمين:

• السماح للمستخدمين باختيار ما إذا كانوا يريدون أن تكون ملفات الوسائط قابلة للقراءة من خلال تطبيقات أخرى أو لا، وذلك باستخدام مساحة التخزين الخاصة بالتطبيق أو مساحة التخزين المشتركة
• السماح للمستخدمين بتصدير الملفات من الأدلة الخاصة بالتطبيقات إلى موقع يسهل الوصول إليه بشكل عام استخدِم مجموعات الصور والفيديوهات والصوت في MediaStore لتصدير ملفات الوسائط إلى معرض الصور في الجهاز.

تعديل ملفات وسائط متعددة أو حذفها في عملية واحدة

تضمين منطق يستند إلى إصدارات Android التي يعمل عليها تطبيقك

تعمل على نظام التشغيل Android 11

اتّبِع الخطوات التالية:

1. أنشئ طلبًا معلّقًا بالكتابة أو الحذف في تطبيقك باستخدام MediaStore.createWriteRequest() أو MediaStore.createTrashRequest()، ثم اطلب من المستخدم الإذن بتعديل مجموعة من الملفات من خلال استدعاء هذا الطلب.

2. تقييم ردّ المستخدم:

   • إذا تم منح الإذن، يمكنك المتابعة لإجراء عملية التعديل أو الحذف.
   • إذا لم يتم منح الإذن، اشرح للمستخدم سبب حاجة الميزة في تطبيقك إلى هذا الإذن.

تعرَّف على مزيد من المعلومات عن كيفية إدارة مجموعات ملفات الوسائط باستخدام هذه الطرق المتاحة على نظام التشغيل Android 11 والإصدارات الأحدث.

على نظام التشغيل Android 10

إذا كان تطبيقك يستهدف الإصدار Android 10 (المستوى 29 لواجهة برمجة التطبيقات)، عليك إيقاف ميزة "مساحة التخزين المحصورة" ومواصلة استخدام الطريقة المخصّصة للإصدار Android 9 والإصدارات الأقدم لتنفيذ هذه العملية.

أن يعمل جهازك بالإصدار 9 أو الإصدارات الأقدم من Android

اتّبِع الخطوات التالية:

1. اتّبِع أفضل الممارسات الموضّحة في طلب أذونات التطبيق، واطلب إذن WRITE_EXTERNAL_STORAGE.
2. استخدِم واجهة برمجة التطبيقات MediaStore لتعديل ملفات الوسائط أو حذفها.

استيراد صورة واحدة سبق أن تم استيرادها

عندما تريد استيراد صورة واحدة حالية (على سبيل المثال، لاستخدامها كصورة لملف شخصي)، يمكن لتطبيقك استخدام واجهة المستخدم الخاصة به لإجراء العملية، أو يمكنه استخدام أداة اختيار النظام.

عرض واجهة المستخدم الخاصة بك

اتّبِع الخطوات التالية:

1. اتّبِع أفضل الممارسات الموضّحة في طلب أذونات التطبيق، واطلب إذن READ_EXTERNAL_STORAGE.
2. استخدِم query() API للاستعلام عن مجموعة وسائط.
3. عرض النتائج في واجهة المستخدم المخصّصة لتطبيقك

استخدام أداة اختيار النظام

استخدِم الغرض ACTION_GET_CONTENT الذي يطلب من المستخدم اختيار صورة لاستيرادها.

إذا أردت فلترة أنواع الصور التي تعرضها أداة اختيار الصور في النظام ليختار المستخدم من بينها، يمكنك استخدام setType() أو EXTRA_MIME_TYPES.

التقاط صورة واحدة

عندما تريد التقاط صورة واحدة لاستخدامها في تطبيقك (على سبيل المثال، لاستخدامها كصورة لملف شخصي خاص بمستخدم)، استخدِم الغرض ACTION_IMAGE_CAPTURE لطلب التقاط صورة من المستخدم باستخدام كاميرا الجهاز. يخزّن النظام الصورة التي تم التقاطها في جدول MediaStore.Images.

مشاركة ملفات الوسائط مع تطبيقات أخرى

استخدِم طريقة insert() لإضافة السجلات مباشرةً إلى MediaStore. لمزيد من المعلومات، يُرجى الاطّلاع على قسم إضافة عنصر في دليل تخزين الوسائط.

مشاركة ملفات الوسائط مع تطبيق محدّد

استخدِم مكوِّن FileProvider في Android، كما هو موضّح في دليل إعداد مشاركة الملفات.

الوصول إلى الملفات من الرموز أو المكتبات التي تستخدم مسارات الملفات المباشرة

تضمين منطق يستند إلى إصدارات Android التي يعمل عليها تطبيقك

تعمل على نظام التشغيل Android 11

اتّبِع الخطوات التالية:

1. اتّبِع أفضل الممارسات الموضّحة في طلب أذونات التطبيق، واطلب إذن READ_EXTERNAL_STORAGE.
2. الوصول إلى الملفات باستخدام مسارات الملفات المباشرة

لمزيد من المعلومات، يُرجى الاطّلاع على القسم حول كيفية فتح ملفات الوسائط باستخدام مسارات الملفات المباشرة.

على نظام التشغيل Android 10

إذا كان تطبيقك يستهدف الإصدار Android 10 (المستوى 29 لواجهة برمجة التطبيقات)، عليك إيقاف ميزة "مساحة التخزين المحصورة" ومواصلة استخدام الطريقة المخصّصة للإصدار Android 9 والإصدارات الأقدم لتنفيذ هذه العملية.

أن يعمل جهازك بالإصدار 9 أو الإصدارات الأقدم من Android

اتّبِع الخطوات التالية:

1. اتّبِع أفضل الممارسات الموضّحة في طلب أذونات التطبيق، واطلب إذن WRITE_EXTERNAL_STORAGE.
2. الوصول إلى الملفات باستخدام مسارات الملفات المباشرة

التعامل مع الملفات غير المتعلقة بالوسائط

يوضّح هذا القسم بعض حالات الاستخدام الشائعة للتعامل مع الملفات غير الوسائط، ويشرح النهج العام الذي يمكن أن يستخدمه تطبيقك. يلخّص الجدول التالي كل حالة من حالات الاستخدام هذه، ويتضمّن روابط تؤدي إلى كل قسم من الأقسام التي تحتوي على مزيد من التفاصيل.

فتح ملف مستند

استخدِم الغرض ACTION_OPEN_DOCUMENT لطلب اختيار ملف من المستخدم لفتحه باستخدام أداة اختيار الملفات في النظام. إذا أردت فلترة أنواع الملفات التي ستعرضها أداة اختيار الملفات التابعة للنظام للمستخدم ليختار من بينها، يمكنك استخدام setType() أو EXTRA_MIME_TYPES.

على سبيل المثال، يمكنك العثور على جميع ملفات PDF وODT وTXT باستخدام الرمز التالي:

startActivityForResult(
        Intent(Intent.ACTION_OPEN_DOCUMENT).apply {
            addCategory(Intent.CATEGORY_OPENABLE)
            type = "*/*"
            putExtra(Intent.EXTRA_MIME_TYPES, arrayOf(
                    "application/pdf", // .pdf
                    "application/vnd.oasis.opendocument.text", // .odt
                    "text/plain" // .txt
            ))
        },
        REQUEST_CODE
      )

Intent intent = new Intent(Intent.ACTION_OPEN_DOCUMENT);
        intent.addCategory(Intent.CATEGORY_OPENABLE);
        intent.setType("*/*");
        intent.putExtra(Intent.EXTRA_MIME_TYPES, new String[] {
                "application/pdf", // .pdf
                "application/vnd.oasis.opendocument.text", // .odt
                "text/plain" // .txt
        });
        startActivityForResult(intent, REQUEST_CODE);

الكتابة إلى الملفات في وحدات تخزين ثانوية

تشمل وحدات التخزين الثانوية بطاقات SD. يمكنك الوصول إلى معلومات حول وحدة تخزين معيّنة باستخدام الفئة StorageVolume.

تضمين منطق يستند إلى إصدار Android الذي يعمل عليه تطبيقك

تعمل على نظام التشغيل Android 11

اتّبِع الخطوات التالية:

1. استخدِم نموذج مساحة التخزين المحصورة.
2. استهداف الإصدار 10 من نظام التشغيل Android (المستوى 29 لواجهة برمجة التطبيقات) أو إصدار أقدم
3. أدرِج إذن WRITE_EXTERNAL_STORAGE في البيان.
4. نفِّذ أحد أنواع الوصول التالية:
   • الوصول إلى الملفات باستخدام واجهة برمجة التطبيقات MediaStore
   • الوصول إلى مسار الملف المباشر باستخدام واجهات برمجة التطبيقات، مثل File أو fopen()

التشغيل على إصدارات قديمة

استخدِم إطار عمل أذونات الوصول إلى مساحة التخزين الذي يتيح للمستخدمين اختيار الموقع الجغرافي على وحدة تخزين ثانوية يمكن لتطبيقك كتابة الملف فيها.

نقل الملفات الحالية من موقع تخزين قديم

يُعد الدليل موقع تخزين قديمًا إذا لم يكن دليلاً خاصًا بتطبيق معيّن أو دليلاً مشتركًا متاحًا للجميع. إذا كان تطبيقك ينشئ ملفات أو يستخدمها في موقع تخزين قديم، ننصحك بنقل ملفات تطبيقك إلى مواقع يمكن الوصول إليها باستخدام ميزة "التخزين النطاقي" وإجراء أي تغييرات ضرورية على التطبيق للعمل مع الملفات في "التخزين النطاقي".

الحفاظ على إمكانية الوصول إلى موقع التخزين القديم لنقل البيانات

يجب أن يحتفظ تطبيقك بإذن الوصول إلى موقع التخزين الخارجي القديم من أجل نقل أي ملفات للتطبيق إلى مواقع يمكن الوصول إليها باستخدام ميزة "التخزين النطاقي". يعتمد النهج الذي يجب اتّباعه على مستوى واجهة برمجة التطبيقات المستهدَف لتطبيقك.

إذا كان تطبيقك يستهدف الإصدار 11 من نظام التشغيل Android

1. اضبط العلامة preserveLegacyExternalStorage على true من أجل الحفاظ على نموذج التخزين القديم حتى يتمكّن تطبيقك من نقل بيانات المستخدم عند الترقية إلى الإصدار الجديد من تطبيقك الذي يستهدف الإصدار Android 11.

2. يمكنك مواصلة إيقاف ميزة "مساحة التخزين المحصورة" ليتمكّن تطبيقك من مواصلة الوصول إلى ملفاتك في موقع التخزين القديم على أجهزة Android 10.

إذا كان تطبيقك يستهدف الإصدار 10 من نظام التشغيل Android

إيقاف ميزة "مساحة التخزين المحصورة" لتسهيل الحفاظ على سلوك تطبيقك في جميع إصدارات Android

نقل بيانات التطبيق

عندما يكون تطبيقك جاهزًا لنقل البيانات، اتّبِع الطريقة التالية:

1. استهداف الإصدار 10 من نظام التشغيل Android أو الإصدارات الأقدم
2. إيقاف ميزة "التخزين المحصور النطاق" حتى يتمكّن تطبيقك من الوصول إلى الملفات التي تحتاج إلى نقلها

3. يمكنك نشر رمز برمجي يستخدم واجهة برمجة التطبيقات File لنقل الملفات من موقعها الحالي ضمن /sdcard/ إلى موقع يمكن الوصول إليه باستخدام مساحة التخزين المحصورة النطاق:

   1. انقل أي ملفات تطبيقات خاصة إلى الدليل الذي يتم عرضه من خلال طريقة getExternalFilesDir().
   2. نقل أي ملفات مشترَكة غير خاصة بالوسائط إلى دليل فرعي مخصّص للتطبيق ضمن الدليل Downloads/
4. أزِل أدلة التخزين القديمة لتطبيقك من الدليل /sdcard/.

بعد أن يثبِّت المستخدمون الإصدار الجديد من تطبيقك، يكملون عملية نقل البيانات على أجهزتهم. يمكنك مراقبة عملية نقل البيانات على مستوى قاعدة المستخدمين من خلال إنشاء حدث إحصائي.

بعد أن ينقل المستخدمون بياناتهم، يمكنك نشر تحديث آخر لتطبيقك يستهدف الإصدار Android 11.

مشاركة المحتوى مع تطبيقات أخرى

لمشاركة ملفات تطبيقك مع تطبيق آخر واحد، استخدِم FileProvider. بالنسبة إلى التطبيقات التي تحتاج إلى مشاركة الملفات مع بعضها البعض، ننصح باستخدام موفّر محتوى لكل تطبيق، ثم مزامنة البيانات عند إضافة التطبيقات إلى المجموعة.

تخزين الملفات غير المرتبطة بالوسائط مؤقتًا

يعتمد النهج الذي يجب استخدامه على نوع الملفات التي تحتاج إلى تخزينها مؤقتًا.

• الملفات الصغيرة أو الملفات التي تحتوي على معلومات حساسة: استخدِم Context#getCacheDir().
• الملفات الكبيرة أو الملفات التي لا تحتوي على معلومات حساسة: استخدِم Context#getExternalCacheDir().

تصدير ملفات غير مرتبطة بالوسائط إلى جهاز

تحديد موقع جغرافي تلقائي مناسب لتخزين الملفات غير المرتبطة بالوسائط السماح للمستخدمين بتصدير الملفات من الأدلة الخاصة بالتطبيقات إلى موقع يسهل الوصول إليه بشكل عام استخدِم عمليات التنزيل أو مجموعات المستندات في MediaStore لتصدير الملفات غير المرتبطة بالوسائط إلى الجهاز.

التعامل مع الملفات الخاصة بالتطبيق

إذا كان تطبيقك ينشئ ملفات لا تحتاج التطبيقات الأخرى إلى الوصول إليها أو لا يجب أن تصل إليها، يمكنك تخزين هذه الملفات في مواقع تخزين خاصة بالتطبيق.

أدلة وحدة التخزين الداخلية

يمنع النظام التطبيقات الأخرى من الوصول إلى هذه المواقع الجغرافية، ويتم تشفيرها على الإصدار 10 من نظام التشغيل Android (المستوى 29 لواجهة برمجة التطبيقات) والإصدارات الأحدث. وتُعدّ هذه المواقع مكانًا مناسبًا لتخزين البيانات الحسّاسة التي لا يمكن لأي تطبيق آخر الوصول إليها.

أدلة مساحة التخزين الخارجية

إذا لم توفّر وحدة التخزين الداخلية مساحة كافية لتخزين الملفات الخاصة بالتطبيق، ننصحك باستخدام وحدة التخزين الخارجية بدلاً من ذلك. على الرغم من أنّه يمكن لتطبيق آخر الوصول إلى هذه الدلائل إذا كان لديه الأذونات المناسبة، فإنّ الملفات المخزّنة في هذه الدلائل مخصّصة للاستخدام من خلال تطبيقك فقط.

على نظام التشغيل Android 4.4 (المستوى 19 لواجهة برمجة التطبيقات) أو الإصدارات الأحدث، لا يحتاج تطبيقك إلى طلب أي أذونات متعلقة بالتخزين للوصول إلى الأدلة الخاصة بالتطبيق ضمن وحدة التخزين الخارجية.

عندما يلغي المستخدم تثبيت تطبيقك، تتم إزالة الملفات المحفوظة في مساحة التخزين الخاصة بالتطبيق، وبالتالي، يجب عدم استخدام مساحة التخزين هذه لحفظ أي بيانات يتوقّع المستخدم أن تظل محفوظة بشكل مستقل عن تطبيقك.

إيقاف ميزة "التخزين النطاقي" مؤقتًا

قبل أن يصبح تطبيقك متوافقًا تمامًا مع ميزة "التخزين المحصور"، يمكنك إيقافها مؤقتًا في اختباراتك وتطبيقك على الإصدار العلني.

إيقاف المشاركة في الاختبارات

في الإصدار 10 من نظام التشغيل Android (المستوى 29 لواجهة برمجة التطبيقات) والإصدارات الأحدث، يتم تشغيل اختبارات تطبيقك في مساحة معزولة للتخزين تلقائيًا. يمنع هذا الوضع التطبيق من الوصول إلى الملفات خارج الدليل الخاص بالتطبيق والأدلة المشتركة بشكل علني.

إذا كان الاختبار ينتج ملفات للمضيف، مثل لقطات الشاشة أو بيانات تصحيح الأخطاء أو بيانات التغطية أو مقاييس الأداء، يمكنك كتابة هذه الملفات في الدلائل العامة. لإجراء ذلك، أضِف العلامة التالية إلى أداة الاختبار ذات الصلة التي تستدعي am instrument:

-e no-isolated-storage 1

يؤثّر هذا الخيار في جميع سلوكيات حالة الاختبار التي تم تتبُّعها، كما يؤثّر في جميع رموز الاختبار التي تم استدعاؤها. لذلك، عند استخدام هذه العلامة، لا يمكنك التحقّق من توافق تطبيقك مع ميزة "مساحة التخزين المحصورة". بالنسبة إلى ناتج الاختبار، من الأفضل بدلاً من ذلك الكتابة إلى مساحة تخزين مخصّصة للتطبيق يمكن قراءتها من خلال shell. يمكنك بعد ذلك سحب هذا الدليل الخاص بالتطبيق. لتحديد الدليل الذي سيتم استخدامه، اتّصِل بالرقم getExternalMediaDirs().

إلغاء الاشتراك في تطبيق الإصدار العلني

إذا كان تطبيقك يستهدف الإصدار 10 من نظام التشغيل Android (المستوى 29 من واجهة برمجة التطبيقات) أو إصدارًا أقدم، يمكنك إيقاف ميزة "التخزين المحصور" مؤقتًا في تطبيقك المتاح على قنوات الإصدار العلني. ومع ذلك، إذا كان تطبيقك يستهدف الإصدار 10 من نظام التشغيل Android، عليك ضبط قيمة requestLegacyExternalStorage على true في ملف البيان الخاص بتطبيقك:

<manifest ... >
  <!-- This attribute is "false" by default on apps targeting
       Android 10. -->
  <application android:requestLegacyExternalStorage="true" ... >
    ...
  </application>
</manifest>

لاختبار سلوك تطبيق يستهدف الإصدار 10 من نظام التشغيل Android أو إصدارًا أقدم عند استخدام مساحة التخزين المحصورة، يمكنك تفعيل هذا السلوك من خلال ضبط قيمة requestLegacyExternalStorage على false. إذا كنت تختبِر تطبيقك على جهاز يعمل بنظام التشغيل Android 11، يمكنك أيضًا استخدام علامات توافق التطبيقات لاختبار سلوك تطبيقك مع ميزة "التخزين المحصور" أو بدونها.

مراجع إضافية

لمزيد من المعلومات حول مساحة التخزين على Android، اطّلِع على المواد التالية:

مشاركات المدونة

• توفير مساحة تخزين حديثة لمستخدمي Viber