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

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

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

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

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

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

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

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

استخدم هذا النهج:

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

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

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

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

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

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

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

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

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

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

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

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

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

استخدم هذا النهج:

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

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

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

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

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

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

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

استخدم هذا النهج:

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

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

تعمل على إصدارات قديمة

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

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

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

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

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

إذا كان تطبيقك يستهدف نظام التشغيل Android 11

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

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

إذا كان تطبيقك يستهدف نظام التشغيل Android 10

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

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

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

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

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

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

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

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

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

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

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

تعتمد الطريقة التي يجب عليك استخدامها على نوع الملفات التي تحتاجها للتخزين المؤقت.

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

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

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

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

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

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

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

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

-e no-isolated-storage 1

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

إيقاف الميزة في تطبيق الإنتاج

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