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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

استيراد صورة واحدة حالية

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

تقديم واجهة مستخدِم خاصة بك

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

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

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

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

إذا أردت فلترة أنواع الصور التي تعرِضها أداة اختيار النظام للمستخدمين للاختيار من بينها، يمكنك استخدام رمزَي 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 لتصدير الملفات غير المتعلقة بالوسائط إلى الجهاز.

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

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

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

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

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

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

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

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

إيقاف التخزين الفرعي مؤقتًا

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

الإيقاف في اختباراتك

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

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

مصادر إضافية

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

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

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