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

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

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

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

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

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

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

استخدِم واجهة برمجة التطبيقات query() للاستعلام عن مجموعة وسائط. لفلترة ملفات الوسائط أو ترتيبها، عدِّل المَعلمات 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 والإصدارات الأقدم لإجراء هذه العملية.

التشغيل على Android 9 أو الإصدارات الأقدم

اتّبِع هذا النهج:

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

استيراد صورة واحدة موجودة

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

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

اتّبِع هذا النهج:

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

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

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

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

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

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

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

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

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

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

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

أدرِج منطقًا استنادًا إلى إصدارات Android التي يتم تشغيل تطبيقك عليها.

التشغيل على Android 11

اتّبِع هذا النهج:

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

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

التشغيل على Android 10

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

التشغيل على Android 9 أو الإصدارات الأقدم

اتّبِع هذا النهج:

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. استهدِف Android 10 (المستوى 29 من واجهة برمجة التطبيقات) أو الإصدارات الأقدم.
3. أعلِن عن الإذن WRITE_EXTERNAL_STORAGE.
4. نفِّذ أحد أنواع الوصول التالية:
   • الوصول إلى الملفات باستخدام واجهة برمجة التطبيقات MediaStore.
   • الوصول إلى مسار الملف المباشر باستخدام واجهات برمجة التطبيقات، مثل File أو fopen().

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

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

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

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

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

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

إذا كان تطبيقك يستهدف Android 11

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

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

إذا كان تطبيقك يستهدف Android 10

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

عدم استخدام "التخزين الفرعي" مؤقتًا

قبل أن يصبح تطبيقك متوافقًا تمامًا مع "التخزين الفرعي"، يمكنك عدم استخدامه مؤقتًا ، سواء في اختباراتك أو في تطبيقك الذي تنشرهالذي تنشره.

عدم استخدام "التخزين الفرعي" في اختباراتك

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

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

-e no-isolated-storage 1

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

عدم استخدام "التخزين الفرعي" في تطبيقك الذي تنشره

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

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

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

مراجع إضافية

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

منشورات المدوّنات

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