فتح الملفات باستخدام إطار عمل الوصول إلى مساحة التخزين
تنظيم صفحاتك في مجموعات
يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.
يقدّم الإصدار 4.4 من نظام التشغيل Android (المستوى 19 لواجهة برمجة التطبيقات) "إطار عمل الوصول إلى مساحة التخزين" (SAF). تتيح واجهة SAF للمستخدمين تصفُّح المستندات والصور والملفات الأخرى وفتحها
من خلال جميع مقدّمي مساحات تخزين المستندات المفضّلين لديهم. تتيح واجهة المستخدم العادية والسهلة الاستخدام للمستخدمين تصفُّح الملفات والوصول إلى الملفات الأخيرة بطريقة متسقة في جميع التطبيقات ومقدّمي الخدمات.
يمكن لخدمات التخزين في السحابة الإلكترونية أو التخزين المحلي المشاركة في هذه المنظومة المتكاملة من خلال تنفيذ
DocumentsProvider التي تُحاط بخدماتها. يمكن دمج التطبيقات العميلة التي تحتاج إلى الوصول إلى مستندات مقدّم الخدمة مع SAF باستخدام بضع سطور من الرمز البرمجي.
تشمل مبادرة SAF ما يلي:
مقدّم المستندات: مقدّم محتوى يسمح للخدمة
التخزين، مثل Google Drive، بالكشف عن الملفات التي يديرها. يتم تنفيذ مقدّم المستندات
كصنف فرعي من فئة DocumentsProvider.
يستند مخطّط مقدّم المستندات إلى التسلسل الهرمي التقليدي للملفات،
ولكنّ طريقة تخزين مقدّم المستندات للبيانات تعود إليك.
يتضمّن نظام Android الأساسي العديد من مقدّمي المستندات المدمجين، مثل
عمليات التنزيل والصور والفيديوهات.
السماح للمستخدمين بتصفّح المحتوى من جميع مقدّمي المستندات، وليس من تطبيق واحد فقط
يتيح لتطبيقك الوصول الدائم والمستمر إلى
المستندات التي يملكها موفِّر مستندات. من خلال هذا الإذن بالوصول، يمكن للمستخدمين إضافة الملفات وتعديلها
وحفظها وحذفها على موفّر الخدمة.
تتيح هذه الميزة حسابات مستخدمين متعددة وجذورًا مؤقتة، مثل موفِّري مساحة تخزين USB، والتي لا تظهر إلا إذا كان محرك الأقراص متصلاً.
نظرة عامة
تركّز خدمة SAF على مقدّم محتوى يمثّل
فئة فرعية من فئة DocumentsProvider. ضمن موفّر المستندات، يتم
تنظيم البيانات على شكل تسلسل هرمي تقليدي للملفات:
الشكل 1. نموذج بيانات مقدّم المستند يشير الجذر إلى مستند واحد، ما يؤدي إلى بدء توسيع الشجرة.
ملاحظات:
يُبلغ كل مقدّم مستندات عن جذر واحد أو أكثر، وهي نقاط بداية لاستكشاف شجرة مستندات.
يحتوي كل جذر على COLUMN_ROOT_ID فريد، ويشير إلى مستند (دليل) يمثّل المحتوى ضمن هذا الجذر.
تكون الجذور ديناميكية بطبيعتها لتلبية حالات الاستخدام، مثل الحسابات المتعدّدة،
وأجهزة التخزين المؤقتة USB، أو تسجيل دخول المستخدم وتسجيل خروجه.
ضمن كل جذر، يتوفّر مستند واحد. يشير هذا المستند إلى مستند واحد إلى N مستند،
ويمكن أن يشير كلّ منها بدوره إلى مستند واحد إلى N مستند.
تعرِض كل خدمة خلفية لتخزين البيانات
الملفات والمجلدات الفردية من خلال الإشارة إليها باستخدام
COLUMN_DOCUMENT_ID فريد.
تكون أرقام تعريف المستندات فريدة ولا تتغيّر بعد إصدارها، لأنّها تُستخدَم لمنح أذونات دائمة لعناوين URI عند إعادة تشغيل الجهاز.
يمكن أن تكون المستندات إما ملفًا قابلاً للفتح بنوع MIME محدّد، أو ملفًا في directory يحتوي على مستندات إضافية بنوع MIME هو
MIME_TYPE_DIR.
يستند نموذج بيانات مقدّم المستندات إلى التسلسل الهرمي التقليدي
للملفات. ومع ذلك، يمكنك تخزين بياناتك بشكلٍ مادي بالطريقة التي تريدها، ما دام بإمكانك الوصول إليها باستخدام DocumentsProvider
واجهة برمجة التطبيقات. على سبيل المثال، يمكنك استخدام مساحة تخزين في السحابة الإلكترونية تستند إلى العلامات لبياناتك.
يوضّح الشكل 2 كيفية استخدام تطبيق الصور لإطار عمل SAF
للوصول إلى البيانات المخزّنة:
الشكل 2. مسار عمل إطار عمل الوصول إلى مساحة التخزين
ملاحظات:
في SAF، لا يتفاعل مقدّمو الخدمات مع العملاء
بشكل مباشر. يطلب العميل إذنًا للتفاعل
مع الملفات، أي قراءة الملفات أو تعديلها أو إنشاؤها أو حذفها.
يبدأ التفاعل عندما يُطلق تطبيق، وهو في هذا المثال تطبيق صور، النية
ACTION_OPEN_DOCUMENT أو ACTION_CREATE_DOCUMENT.
يمكن أن يتضمّن الطلب فلاتر
لتحسين المعايير بشكل أكبر، مثل "أريد جميع الملفات القابلة للفتح
التي لها نوع MIME هو "صورة"".
بعد بدء النية، ينتقل أداة اختيار النظام إلى كل مقدّم خدمة مسجَّل ويعرِض للمستخدم جذر المحتوى المطابق.
يوفّر أداة الاختيار للمستخدمين واجهة عادية للوصول إلى المستندات، حتى
إذا كان مقدّمو المستندات الأساسيون مختلفين جدًا. على سبيل المثال، يعرض الشكل 2
مقدّم خدمة Google Drive ومقدّم خدمة USB ومقدّم خدمة السحابة الإلكترونية.
في الشكل 3، يختار المستخدم مجلد "عمليات التنزيل" من أداة اختيار تم فتحها في بحث عن
صور. يعرض أداة الاختيار أيضًا جميع الجذور المتاحة لتطبيق العميل.
الشكل 3. أداة اختيار تعرِض مجلد "التنزيلات" الذي تم اختياره كموقع بحث
بعد اختيار المستخدم لمجلد "عمليات التنزيل"، يتم عرض الصور. يوضّح الشكل
4 نتيجة هذه العملية. يمكن للمستخدم الآن التفاعل مع الصور
بالطُرق التي يتيحها مقدّم الخدمة وتطبيق العميل.
الشكل 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، الذي يتيح للمستخدم اختيار دليل لتطبيق العميل للوصول إليه.
ملاحظة: ACTION_OPEN_DOCUMENT ليس بديلاً عن ACTION_GET_CONTENT.
يعتمد الخيار الذي تستخدمه على احتياجات تطبيقك:
استخدِم ACTION_GET_CONTENT إذا كنت تريد أن يقرأ تطبيقك
البيانات أو يستوردها. وباستخدام هذا النهج، يستورد التطبيق نسخة من البيانات،
مثل ملف صورة.
استخدِم ACTION_OPEN_DOCUMENT إذا كنت تريد أن يحصل
تطبيقك على إذن وصول دائم وطويل الأمد إلى المستندات التي يملكها أحد مقدّمي خدمات
المستندات. على سبيل المثال، تطبيق تعديل الصور الذي يتيح للمستخدمين تعديل
الصور المخزّنة في مقدّم مستندات.
لمزيد من المعلومات حول كيفية إتاحة إمكانية تصفُّح الملفات والأدلة
باستخدام واجهة مستخدم أداة اختيار النظام، اطّلِع على الدليل حول
الوصول إلى المستندات وغيرها من الملفات.
مصادر إضافية
لمزيد من المعلومات عن مقدّمي المستندات، يمكنك الاستفادة من المراجع التالية:
يخضع كل من المحتوى وعيّنات التعليمات البرمجية في هذه الصفحة للتراخيص الموضحّة في ترخيص استخدام المحتوى. إنّ Java وOpenJDK هما علامتان تجاريتان مسجَّلتان لشركة Oracle و/أو الشركات التابعة لها.
تاريخ التعديل الأخير: 2025-07-27 (حسب التوقيت العالمي المتفَّق عليه)
[[["يسهُل فهم المحتوى.","easyToUnderstand","thumb-up"],["ساعَدني المحتوى في حلّ مشكلتي.","solvedMyProblem","thumb-up"],["غير ذلك","otherUp","thumb-up"]],[["لا يحتوي على المعلومات التي أحتاج إليها.","missingTheInformationINeed","thumb-down"],["الخطوات معقدة للغاية / كثيرة جدًا.","tooComplicatedTooManySteps","thumb-down"],["المحتوى قديم.","outOfDate","thumb-down"],["ثمة مشكلة في الترجمة.","translationIssue","thumb-down"],["مشكلة في العيّنات / التعليمات البرمجية","samplesCodeIssue","thumb-down"],["غير ذلك","otherDown","thumb-down"]],["تاريخ التعديل الأخير: 2025-07-27 (حسب التوقيت العالمي المتفَّق عليه)"],[],[],null,["# Open files using the Storage Access Framework\n\nAndroid 4.4 (API level 19) introduces the Storage Access Framework (SAF). The SAF\nlets users browse and open documents, images, and other files\nacross all of their preferred document storage providers. A standard, easy-to-use UI\nlets users browse files and access recent files in a consistent way across apps and providers.\n\nCloud or local storage services can participate in this ecosystem by implementing a\n[DocumentsProvider](/reference/android/provider/DocumentsProvider) that encapsulates their services. Client\napps that need access to a provider's documents can integrate with the SAF with a few\nlines of code.\n\nThe SAF includes the following:\n\n- **Document provider:** a content provider that lets a storage service, such as Google Drive, reveal the files it manages. A document provider is implemented as a subclass of the [DocumentsProvider](/reference/android/provider/DocumentsProvider) class. The document-provider schema is based on a traditional file hierarchy, though how your document provider physically stores data is up to you. The Android platform includes several built-in document providers, such as Downloads, Images, and Videos.\n- **Client app:** a custom app that invokes the [ACTION_CREATE_DOCUMENT](/reference/android/content/Intent#ACTION_CREATE_DOCUMENT), [ACTION_OPEN_DOCUMENT](/reference/android/content/Intent#ACTION_OPEN_DOCUMENT), and [ACTION_OPEN_DOCUMENT_TREE](/reference/android/content/Intent#ACTION_OPEN_DOCUMENT_TREE) intent actions and receives the files returned by document providers.\n- **Picker:** a system UI that lets users access documents from all document providers that satisfy the client app's search criteria.\n\nSAF offers the following features:\n\n- Lets users browse content from all document providers, not just a single app.\n- Makes it possible for your app to have long-term, persistent access to documents owned by a document provider. Through this access, users can add, edit, save, and delete files on the provider.\n- Supports multiple user accounts and transient roots such as USB storage providers, which only appear if the drive is plugged in.\n\nOverview\n--------\n\nThe SAF centers around a content provider that is a\nsubclass of the [DocumentsProvider](/reference/android/provider/DocumentsProvider) class. Within a document provider, data is\nstructured as a traditional file hierarchy:\n**Figure 1.** Document provider data model. A root points to a single document, which then starts the fan-out of the tree.\n\nNote the following:\n\n- Each document provider reports one or more *roots* , which are starting points into exploring a tree of documents. Each root has a unique [COLUMN_ROOT_ID](/reference/android/provider/DocumentsContract.Root#COLUMN_ROOT_ID), and it points to a document (a directory) representing the contents under that root. Roots are dynamic by design to support use cases like multiple accounts, transient USB storage devices, or user login and logout.\n- Under each root is a single document. That document points to 1 to *N* documents, each of which in turn can point to 1 to *N* documents.\n- Each storage backend surfaces individual files and directories by referencing them with a unique [COLUMN_DOCUMENT_ID](/reference/android/provider/DocumentsContract.Document#COLUMN_DOCUMENT_ID). Document IDs are unique and don't change once issued, since they are used for persistent URI grants across device reboots.\n- Documents can be either an openable file, with a specific MIME type, or a directory containing additional documents, with the [MIME_TYPE_DIR](/reference/android/provider/DocumentsContract.Document#MIME_TYPE_DIR) MIME type.\n- Each document can have different capabilities, as described by [COLUMN_FLAGS](/reference/android/provider/DocumentsContract.Document#COLUMN_FLAGS). For example, [FLAG_SUPPORTS_WRITE](/reference/android/provider/DocumentsContract.Document#FLAG_SUPPORTS_WRITE), [FLAG_SUPPORTS_DELETE](/reference/android/provider/DocumentsContract.Document#FLAG_SUPPORTS_DELETE), and [FLAG_SUPPORTS_THUMBNAIL](/reference/android/provider/DocumentsContract.Document#FLAG_SUPPORTS_THUMBNAIL). The same `COLUMN_DOCUMENT_ID` can be included in multiple directories.\n\nControl flow\n------------\n\nThe document provider data model is based on a traditional\nfile hierarchy. However, you can physically store your data however you like, as\nlong as you can access it using the [DocumentsProvider](/reference/android/provider/DocumentsProvider)\nAPI. For example, you can use tag-based cloud storage for your data.\n\nFigure 2 shows how a photo app might use the SAF\nto access stored data:\n**Figure 2.** Storage Access Framework flow.\n\nNote the following:\n\n- In the SAF, providers and clients don't interact directly. A client requests permission to interact with files, meaning to read, edit, create, or delete files.\n- The interaction starts when an application, in this example a photo app, fires the intent [ACTION_OPEN_DOCUMENT](/reference/android/content/Intent#ACTION_OPEN_DOCUMENT) or [ACTION_CREATE_DOCUMENT](/reference/android/content/Intent#ACTION_CREATE_DOCUMENT). The intent can include filters to further refine the criteria, such as \"give me all openable files that have the 'image' MIME type.\"\n- Once the intent fires, the system picker goes to each registered provider and shows the user the matching content roots.\n- The picker gives users a standard interface for accessing documents, even when the underlying document providers are very different. For example, figure 2 shows a Google Drive provider, a USB provider, and a cloud provider.\n\nIn Figure 3, the user is selecting the Downloads folder from a picker opened in a search for\nimages. The picker also shows all of the roots available to the client app.\n**Figure 3.** Picker showing Downloads folder selected as a search location.\n\nAfter the user selects the Downloads folder, the images are displayed. Figure\n4 shows the result of this process. The user can now interact with the images\nin the ways that the provider and client app support.\n**Figure 4.** Images stored in the Downloads folder, as viewed in the system picker.\n\nWrite a client app\n------------------\n\nOn Android 4.3 and lower, if you want your app to retrieve a file from another\napp, it must invoke an intent such as [ACTION_PICK](/reference/android/content/Intent#ACTION_PICK)\nor [ACTION_GET_CONTENT](/reference/android/content/Intent#ACTION_GET_CONTENT). The user then selects\na single app from which to pick a file. The selected app must provide a user\ninterface for the user to browse and pick from the available files.\n\nOn Android 4.4 (API level 19) and higher, you have the additional option of using the\n[ACTION_OPEN_DOCUMENT](/reference/android/content/Intent#ACTION_OPEN_DOCUMENT) intent,\nwhich displays a system-controlled picker UI that lets the user\nbrowse all files that other apps have made available. From this single UI, the\nuser can pick a file from any of the supported apps.\n\nOn Android 5.0 (API level 21) and higher, you can also use the\n[ACTION_OPEN_DOCUMENT_TREE](/reference/android/content/Intent#ACTION_OPEN_DOCUMENT_TREE)\nintent, which lets the user choose a directory for a client app to\naccess. \n**Note:** `ACTION_OPEN_DOCUMENT` isn't a replacement for `ACTION_GET_CONTENT`.\nThe one you use depends on the needs of your app:\n\n- Use `ACTION_GET_CONTENT` if you want your app to read or import data. With this approach, the app imports a copy of the data, such as an image file.\n- Use `ACTION_OPEN_DOCUMENT` if you want your app to have long-term, persistent access to documents owned by a document provider. An example is a photo-editing app that lets users edit images stored in a document provider.\n\nFor more information about how to support browsing for files and directories\nusing the system picker UI, see the guide about\n[accessing documents and\nother files](/training/data-storage/shared/documents-files).\n\nAdditional resources\n--------------------\n\nFor more information about document providers, take advantage of the\nfollowing resources:\n\n### Samples\n\n- [StorageProvider](https://github.com/android/storage-samples/tree/main/StorageProvider)\n\n### Videos\n\n- [DevBytes: Android 4.4 Storage Access Framework: Provider](http://www.youtube.com/watch?v=zxHVeXbK1P4)\n- [Virtual Files in the Storage Access Framework](https://www.youtube.com/watch?v=4h7yCZt231Y)"]]
