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

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

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

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

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

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 لتصدير الملفات غير المتعلقة بالوسائط إلى الجهاز.

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

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

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

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

مصادر إضافية

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

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

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