حالات استخدام مساحة التخزين على 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 والإصدارات الأقدم لتنفيذ هذه العملية.

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

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

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

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

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

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

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

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

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

فتح ملف مستند

استخدِم ACTION_OPEN_DOCUMENT intent لطلب اختيار ملف من المستخدم لفتحه باستخدام أداة اختيار الملفات في النظام. إذا أردت فلترة أنواع الملفات التي ستعرضها أداة اختيار النظام أمام المستخدم للاختيار من بينها، يمكنك استخدام 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. نقل أي ملفات غير إعلامية مشترَكة إلى دليل فرعي مخصّص للتطبيق ضمن directoryDownloads/
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

تؤثر هذه العلامة في جميع سلوكيات نموذج الاختبار الذي تم اختباره، كما تؤثر في كل رمز اختبار يتم استدعاؤه. لذلك، عند استخدام هذه العلامة، لا يمكنك التحقّق من توافق تطبيقك مع ميزة "مساحة التخزين ذات النطاق المحدّد". بالنسبة إلى نتائج الاختبار، من الأفضل بدلاً من ذلك الكتابة في مساحة التخزين على مستوى التطبيق التي يمكن لوحدة التحكّم فيها. يمكنك بعد ذلك سحب هذا الدليل على مستوى التطبيق. لتحديد الدليل الذي سيتم سحب البيانات منه، اتصل بالرقم 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، يمكنك أيضًا استخدام علامات ملف APK الخاصة بالتوافق لاختبار سلوك تطبيقك باستخدام مساحة التخزين المخصّصة أو بدونها.

مصادر إضافية

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

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

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