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

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

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

لمزيد من المعلومات حول كيفية تخزين الملفات والوصول إليها على 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

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

أن يعمل جهازك بالإصدار 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

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

أن يعمل جهازك بالإصدار 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 لواجهة برمجة التطبيقات) والإصدارات الأحدث. وتُعدّ هذه المواقع مكانًا مناسبًا لتخزين البيانات الحساسة التي لا يمكن لأي تطبيق آخر غير تطبيقك الوصول إليها.

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

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

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

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

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

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

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

في نظام التشغيل Android 10 (المستوى 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