קל לארגן דפים בעזרת אוספים
אפשר לשמור ולסווג תוכן על סמך ההעדפות שלך.
ב-Android 4.4 (רמת API 19) הוצגה Storage Access Framework (SAF). באמצעות SAF, המשתמשים יכולים לעיין במסמכים, בתמונות ובקבצים אחרים, ולפתוח אותם בכל ספקי האחסון המועדפים עליהם. ממשק משתמש סטנדרטי וקל לשימוש שמאפשר למשתמשים לעיין בקבצים ולגשת לקבצים האחרונים באופן עקבי באפליקציות ובספקים שונים.
שירותי אחסון בענן או מקומיים יכולים להשתתף בסביבה העסקית הזו על ידי הטמעת DocumentsProvider שמכיל את השירותים שלהם. אפליקציות לקוח שצריכות גישה למסמכים של ספק יכולות להשתלב עם SAF באמצעות כמה שורות קוד.
SAF כולל את הפריטים הבאים:
ספק מסמכים: ספק תוכן שמאפשר לשירות אחסון, כמו Google Drive, לחשוף את הקבצים שהוא מנהל. ספק מסמכים מיושם כסוג משנה של הכיתה DocumentsProvider.
הסכימה של ספק המסמכים מבוססת על היררכיית קבצים מסורתית, אבל האופן שבו ספק המסמכים שומר את הנתונים פיזית הוא באחריותכם.
פלטפורמת Android כוללת כמה ספקי מסמכים מובנים, כמו 'הורדות', 'תמונות' ו'סרטונים'.
בורר: ממשק משתמש מערכת שמאפשר למשתמשים לגשת למסמכים מכל ספקי המסמכים שעומדים בקריטריונים לחיפוש באפליקציית הלקוח.
SAF כולל את התכונות הבאות:
מאפשרת למשתמשים לעיין בתוכן מכל ספקי המסמכים, ולא רק מאפליקציה אחת.
מאפשר לאפליקציה שלכם לקבל גישה קבועה לטווח ארוך למסמכים שבבעלות ספק המסמכים. הגישה הזו מאפשרת למשתמשים להוסיף, לערוך, לשמור ולמחוק קבצים אצל הספק.
תמיכה בכמה חשבונות משתמשים ובשורשים זמניים, כמו ספקי אחסון USB, שמופיעים רק אם הכונן מחובר.
סקירה כללית
ה-SAF מתמקד בספק תוכן שהוא תת-סוג של הכיתה DocumentsProvider. בתוך ספק מסמכים, הנתונים מובְנים בתור היררכיית קבצים מסורתית:
איור 1. מודל הנתונים של ספק המסמכים. השורש מפנה למסמך יחיד, שממנו מתחיל ההסתעפות של העץ.
חשוב לזכור:
כל ספק מסמכים מדווח על שורש אחד או יותר, שהם נקודות התחלה לחקירה של עץ מסמכים.
לכל שורש יש COLUMN_ROOT_ID ייחודי, והוא מפנה למסמך (ספרייה) שמייצג את התוכן שמתחת לאותו שורש.
השורשים הם דינמיים מטבעם כדי לתמוך בתרחישי שימוש כמו כמה חשבונות, מכשירי אחסון USB זמניים או כניסה של משתמשים ויציאה שלהם.
מתחת לכל עץ יש מסמך אחד. המסמך הזה מפנה למסמכים 1 עד N, שכל אחד מהם יכול להפנות למסמכים 1 עד N.
כל קצה עורפי של אחסון מציג קבצים ומספרי קבצים ספציפיים באמצעות הפניה אליהם באמצעות COLUMN_DOCUMENT_ID ייחודי.
מזהי המסמכים הם ייחודיים ולא משתנים אחרי שהם מונפקים, כי הם משמשים להענקת הרשאות URI קבועות במהלך הפעלות מחדש של המכשיר.
מסמכים יכולים להיות קובץ שניתן לפתוח, עם סוג MIME ספציפי, או ספרייה שמכילה מסמכים נוספים, עם סוג ה-MIME MIME_TYPE_DIR.
מודל הנתונים של ספק המסמכים מבוסס על היררכיית קבצים מסורתית. עם זאת, אתם יכולים לאחסן את הנתונים פיזית בכל דרך שתרצו, כל עוד תוכלו לגשת אליהם באמצעות ה-API של DocumentsProvider. לדוגמה, אתם יכולים להשתמש באחסון בענן שמבוסס על תגים לנתונים שלכם.
באיור 2 מוצג איך אפליקציית תמונות עשויה להשתמש ב-SAF כדי לגשת לנתונים שמאוחסנים:
איור 2. התהליך של Storage Access Framework.
חשוב לזכור:
בסביבת SAF, הספקים והלקוחות לא מתקשרים ישירות. לקוח מבקש הרשאה לבצע פעולות בקובצים, כלומר לקרוא, לערוך, ליצור או למחוק אותם.
האינטראקציה מתחילה כשאפליקציה, בדוגמה הזו אפליקציית תמונות, מפעילה את הכוונה ACTION_OPEN_DOCUMENT או ACTION_CREATE_DOCUMENT.
הכוונה יכולה לכלול מסננים כדי לחדד את הקריטריונים, למשל "הצגת כל הקבצים שניתן לפתוח עם סוג ה-MIME 'image'".
אחרי שהכוונה מופעלת, הבורר של המערכת עובר לכל ספק רשום ומציג למשתמש את שורשי התוכן התואמים.
הבורר מספק למשתמשים ממשק סטנדרטי לגישה למסמכים, גם אם ספקי המסמכים הבסיסיים שונים מאוד. לדוגמה, באיור 2 מוצגים ספק של Google Drive, ספק USB וספק ענן.
באיור 3, המשתמש בוחר את תיקיית ההורדות מבורר שנפתח בחיפוש תמונות. בבורר מוצגים גם כל שורשי הנתונים שזמינים לאפליקציית הלקוח.
איור 3. בורר שבו תיקיית ההורדות נבחרה כמיקום חיפוש.
אחרי שהמשתמש בוחר בתיקיית ההורדות, התמונות מוצגות. באיור 4 מוצגת התוצאה של התהליך הזה. עכשיו המשתמש יכול לבצע פעולות עם התמונות בדרכים שבהן הספק ואפליקציית הלקוח תומכים.
איור 4. תמונות שמורות בתיקיית ההורדות, כפי שמוצגות בבורר המערכת.
כתיבת אפליקציית לקוח
ב-Android 4.3 וגרסאות ישנות יותר, אם רוצים שהאפליקציה תוכל לאחזר קובץ מאפליקציה אחרת, צריך להפעיל כוונה (intent) כמו ACTION_PICK או ACTION_GET_CONTENT. לאחר מכן המשתמש בוחר אפליקציה אחת כדי לבחור קובץ. האפליקציה שנבחרה חייבת לספק ממשק משתמש שמאפשר למשתמשים לעיין בקבצים הזמינים ולבחור מהם.
ב-Android 4.4 ואילך (רמת API 19 ואילך), יש לכם אפשרות נוספת להשתמש ב-intent ACTION_OPEN_DOCUMENT, שמציג ממשק משתמש של בורר שמנוהל על ידי המערכת ומאפשר למשתמש לעיין בכל הקבצים שהאפליקציות האחרות הפכו לזמינים. ממשק המשתמש היחיד הזה מאפשר למשתמשים לבחור קובץ מכל אחת מהאפליקציות הנתמכות.
ב-Android 5.0 (רמת API 21) ואילך, אפשר גם להשתמש ב-intent ACTION_OPEN_DOCUMENT_TREE, שמאפשר למשתמש לבחור ספרייה שאפליקציית לקוח תקבל גישה אליה.
הערה: האפשרות ACTION_OPEN_DOCUMENT היא לא תחליף ל-ACTION_GET_CONTENT.
האפשרות שבה תשתמשו תלויה בצרכים של האפליקציה:
משתמשים ב-ACTION_GET_CONTENT אם רוצים שהאפליקציה תוכל לקרוא או לייבא נתונים. בגישה הזו, האפליקציה מייבאת עותק של הנתונים, למשל קובץ תמונה.
משתמשים ב-ACTION_OPEN_DOCUMENT אם רוצים לאפליקציה גישה מתמשכת לטווח ארוך למסמכים שבבעלות ספק המסמכים. דוגמה לכך היא אפליקציה לעריכת תמונות שמאפשרת למשתמשים לערוך תמונות שמאוחסנות אצל ספק מסמכים.
מידע נוסף על תמיכה בגלישה בקבצים ובספריות באמצעות ממשק המשתמש של בורר המערכת זמין במדריך בנושא גישה למסמכים ולקבצים אחרים.
דוגמאות התוכן והקוד שבדף הזה כפופות לרישיונות המפורטים בקטע רישיון לתוכן. Java ו-OpenJDK הם סימנים מסחריים או סימנים מסחריים רשומים של חברת Oracle ו/או של השותפים העצמאיים שלה.
עדכון אחרון: 2025-07-27 (שעון UTC).
[[["התוכן קל להבנה","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 (שעון UTC)."],[],[],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)"]]
