فتح الملفات باستخدام إطار عمل الوصول إلى مساحة التخزين

تنظيم صفحاتك في مجموعات يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.

يقدّم الإصدار 4.4 من نظام التشغيل Android (المستوى 19 لواجهة برمجة التطبيقات) "إطار عمل الوصول إلى مساحة التخزين" (SAF). تتيح واجهة SAF للمستخدمين تصفُّح المستندات والصور والملفات الأخرى وفتحها من خلال جميع مقدّمي مساحات تخزين المستندات المفضّلين لديهم. تتيح واجهة المستخدم العادية والسهلة الاستخدام للمستخدمين تصفُّح الملفات والوصول إلى الملفات الأخيرة بطريقة متسقة في جميع التطبيقات ومقدّمي الخدمات.

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

تشمل مبادرة SAF ما يلي:

• مقدّم المستندات: مقدّم محتوى يسمح للخدمة التخزين، مثل Google Drive، بالكشف عن الملفات التي يديرها. يتم تنفيذ مقدّم المستندات كصنف فرعي من فئة DocumentsProvider. يستند مخطّط مقدّم المستندات إلى التسلسل الهرمي التقليدي للملفات، ولكنّ طريقة تخزين مقدّم المستندات للبيانات تعود إليك. يتضمّن نظام Android الأساسي العديد من مقدّمي المستندات المدمجين، مثل عمليات التنزيل والصور والفيديوهات.
• تطبيق العميل: تطبيق مخصّص يستدعي إجراءات النية ACTION_CREATE_DOCUMENT و ACTION_OPEN_DOCUMENT و و ACTION_OPEN_DOCUMENT_TREE ويتلقّى الملفات التي يعرضها مقدّمو المستندات.
• أداة الاختيار: واجهة مستخدم للنظام تتيح للمستخدمين الوصول إلى المستندات من جميع موفّري المستندات الذين يستوفون معايير البحث في تطبيق العميل.

توفّر ميزة "التخزين الآمن للملفّات" الميزات التالية:

• السماح للمستخدمين بتصفّح المحتوى من جميع مقدّمي المستندات، وليس من تطبيق واحد فقط
• يتيح لتطبيقك الوصول الدائم والمستمر إلى المستندات التي يملكها موفِّر مستندات. من خلال هذا الإذن بالوصول، يمكن للمستخدمين إضافة الملفات وتعديلها وحفظها وحذفها على موفّر الخدمة.
• تتيح هذه الميزة حسابات مستخدمين متعددة وجذورًا مؤقتة، مثل موفِّري مساحة تخزين USB، والتي لا تظهر إلا إذا كان محرك الأقراص متصلاً.

نظرة عامة

تركّز خدمة SAF على مقدّم محتوى يمثّل فئة فرعية من فئة DocumentsProvider. ضمن موفّر المستندات، يتم تنظيم البيانات على شكل تسلسل هرمي تقليدي للملفات:

ملاحظات:

• يُبلغ كل مقدّم مستندات عن جذر واحد أو أكثر، وهي نقاط بداية لاستكشاف شجرة مستندات. يحتوي كل جذر على COLUMN_ROOT_ID فريد، ويشير إلى مستند (دليل) يمثّل المحتوى ضمن هذا الجذر. تكون الجذور ديناميكية بطبيعتها لتلبية حالات الاستخدام، مثل الحسابات المتعدّدة، وأجهزة التخزين المؤقتة USB، أو تسجيل دخول المستخدم وتسجيل خروجه.
• ضمن كل جذر، يتوفّر مستند واحد. يشير هذا المستند إلى مستند واحد إلى N مستند، ويمكن أن يشير كلّ منها بدوره إلى مستند واحد إلى N مستند.
• تعرِض كل خدمة خلفية لتخزين البيانات الملفات والمجلدات الفردية من خلال الإشارة إليها باستخدام COLUMN_DOCUMENT_ID فريد. تكون أرقام تعريف المستندات فريدة ولا تتغيّر بعد إصدارها، لأنّها تُستخدَم لمنح أذونات دائمة لعناوين URI عند إعادة تشغيل الجهاز.
• يمكن أن تكون المستندات إما ملفًا قابلاً للفتح بنوع MIME محدّد، أو ملفًا في directory يحتوي على مستندات إضافية بنوع MIME هو MIME_TYPE_DIR.
• يمكن أن يكون لكل مستند إمكانات مختلفة، كما هو موضّح في COLUMN_FLAGS. على سبيل المثال، FLAG_SUPPORTS_WRITE FLAG_SUPPORTS_DELETE FLAG_SUPPORTS_THUMBNAIL. يمكن تضمين COLUMN_DOCUMENT_ID نفسها في أدلة متعددة.

التحكّم في التدفق

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

يوضّح الشكل 2 كيفية استخدام تطبيق الصور لإطار عمل SAF للوصول إلى البيانات المخزّنة:

ملاحظات:

• في SAF، لا يتفاعل مقدّمو الخدمات مع العملاء بشكل مباشر. يطلب العميل إذنًا للتفاعل مع الملفات، أي قراءة الملفات أو تعديلها أو إنشاؤها أو حذفها.
• يبدأ التفاعل عندما يُطلق تطبيق، وهو في هذا المثال تطبيق صور، النية ACTION_OPEN_DOCUMENT أو ACTION_CREATE_DOCUMENT. يمكن أن يتضمّن الطلب فلاتر لتحسين المعايير بشكل أكبر، مثل "أريد جميع الملفات القابلة للفتح التي لها نوع MIME هو "صورة"".
• بعد بدء النية، ينتقل أداة اختيار النظام إلى كل مقدّم خدمة مسجَّل ويعرِض للمستخدم جذر المحتوى المطابق.
• يوفّر أداة الاختيار للمستخدمين واجهة عادية للوصول إلى المستندات، حتى إذا كان مقدّمو المستندات الأساسيون مختلفين جدًا. على سبيل المثال، يعرض الشكل 2 مقدّم خدمة Google Drive ومقدّم خدمة USB ومقدّم خدمة السحابة الإلكترونية.

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

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

كتابة تطبيق عملاء

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

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

في الإصدار 5.0 من Android (المستوى 21 لواجهة برمجة التطبيقات) والإصدارات الأحدث، يمكنك أيضًا استخدام ACTION_OPEN_DOCUMENT_TREE intent، الذي يتيح للمستخدم اختيار دليل لتطبيق العميل للوصول إليه.

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

مصادر إضافية

لمزيد من المعلومات عن مقدّمي المستندات، يمكنك الاستفادة من المراجع التالية:

نماذج

• StorageProvider

الفيديوهات

• DevBytes: إطار عمل الوصول إلى مساحة التخزين في Android 4.4: مقدّم الخدمة
• الملفات الافتراضية في إطار عمل الوصول إلى مساحة التخزين