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

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

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

يشمل برنامج SAF ما يلي:

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

توفّر منصة SAF الميزات التالية:

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

نظرة عامة

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

الشكل 1. نموذج بيانات موفّر المستندات يشير الجذر إلى وثيقة واحدة، والتي بعد ذلك تبدأ المروحة من الشجرة.

لاحظ ما يلي:

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

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

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

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

الشكل 2. مسار عمل إطار الوصول إلى مساحة التخزين

لاحظ ما يلي:

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

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

الشكل 3. يعرض المنتقي مجلد "التنزيلات" محددًا كموقع بحث.

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

الشكل 4. الصور المخزنة في مجلد "عمليات التنزيل"، كما تظهر في منتقي النظام.

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

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

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

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

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

مراجع إضافية

لمزيد من المعلومات حول موفري المستندات، استفد من الموارد التالية:

عيّنات

• StorageProvider

الفيديوهات الطويلة

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