Android 4.4 (سطح میانای برنامه‌سازی کاربردی ۱۹) «چارچوب دسترسی به فضای ذخیره‌سازی» (SAF) را معرفی می‌کند. چارچوب دسترسی به فضای ذخیره‌سازی به کاربران اجازه می‌دهد اسناد، تصاویر، و فایل‌های دیگر را در همه ارائه‌دهندگان فضای ذخیره‌سازی سند ترجیحی‌شان مرور و باز کنند. رابط کاربری استاندارد و با کاربرد آسان به کاربران امکان می‌دهد فایل‌ها را مرور کنند و به فایل‌های اخیر به‌شکلی هماهنگ در سراسر برنامه‌ها و ارائه‌دهندگان دسترسی داشته باشند.
سرویس‌های فضای ابری یا فضای ذخیره‌سازی محلی می‌توانند با پیاده‌سازی یک
DocumentsProvider که سرویس‌هایشان را دربرمی‌گیرد، در این بوم‌سازگان مشارکت کنند. برنامه‌های کارخواه که به دسترسی به اسناد ارائه‌دهنده نیاز دارند می‌توانند با چند خط کد با SAF ادغام شوند.
«چارچوب دسترسی به فضای ذخیره‌سازی» شامل موارد زیر است:
- ارائه‌دهنده سند: ارائه‌دهنده محتوایی که به
سرویس فضای ذخیره‌سازی، مثل Google Drive، اجازه می‌دهد فایل‌هایی را که مدیریت می‌کند آشکار کند. ارائه‌دهنده سند به‌عنوان زیرکلاس کلاس
DocumentsProviderپیاده‌سازی می‌شود. طرح ارائه‌دهنده سند براساس سلسله‌مراتب فایل سنتی است، اگرچه نحوه ذخیره فیزیکی داده‌ها توسط ارائه‌دهنده سند به شما بستگی دارد. پلاتفرم Android شامل چندین ارائه‌دهنده سند داخلی است، مانند «بارگیری‌ها»، «تصاویر»، و «ویدیوها». - برنامه کارخواه: برنامه سفارشی‌ای که کنش‌های هدف
ACTION_CREATE_DOCUMENT،ACTION_OPEN_DOCUMENT، وACTION_OPEN_DOCUMENT_TREEرا فراخوانی می‌کند و فایل‌های برگردانده‌شده توسط ارائه‌دهندگان سند را دریافت می‌کند. - انتخابگر: واسط کاربر سیستمی که به کاربران امکان می‌دهد از همه ارائه‌دهندگان سند که با معیارهای جستجوی برنامه کارخواه مطابقت دارند به اسناد دسترسی پیدا کنند.
SAF ویژگی‌های زیر را ارائه می‌دهد:
- به کاربران اجازه می‌دهد محتوای همه ارائه‌دهندگان سند را مرور کنند، نه فقط یک برنامه.
- این امکان را برای برنامه شما فراهم می‌کند که دسترسی طولانی‌مدت و مداوم به اسناد متعلق به ارائه‌دهنده سند داشته باشد. ازطریق این دسترسی، کاربران می‌توانند فایل‌ها را در ارائه‌دهنده اضافه، ویرایش، ذخیره، و حذف کنند.
- از چندین حساب کاربری و ریشه‌های گذرا مانند ارائه‌دهندگان فضای ذخیره‌سازی USB پشتیبانی می‌کند که فقط در صورت اتصال درایو ظاهر می‌شوند.
نمای کلی
SAF حول یک ارائه‌دهنده محتوا متمرکز است که یک
زیرکلاس از کلاس DocumentsProvider است. در ارائه‌دهنده سند، داده‌ها
به‌صورت سلسله‌مراتب فایل سنتی ساختاردهی می‌شوند:
به موارد زیر توجه کنید:
- هر ارائه‌دهنده سند یک یا چند
ریشه را گزارش می‌کند که نقاط شروع برای کاوش درخت اسناد هستند.
هر ریشه دارای یک
COLUMN_ROOT_IDمنحصربه‌فرد است، و به سندی (دایرکتوری) اشاره می‌کند که محتویات زیر آن ریشه را نشان می‌دهد. ریشه‌ها به‌طور پویا طراحی شده‌اند تا از موارد استفاده مانند چندین حساب، دستگاه‌های ذخیره‌سازی USB گذرا، یا ورود و خروج کاربر پشتیبانی کنند. - زیر هر ریشه یک سند قرار دارد. آن سند به ۱ تا N سند اشاره می‌کند، که هرکدام از آن‌ها به‌نوبه خود می‌توانند به ۱ تا N سند اشاره کنند.
- هر باطن فضای ذخیره‌سازی، فایل‌ها و دایرکتوری‌های مجزا را با ارجاع دادن به آن‌ها با یک
COLUMN_DOCUMENT_IDمنحصربه‌فرد نمایش می‌دهد. شناسه‌های سند منحصربه‌فرد هستند و پس‌از صدور تغییر نمی‌کنند، زیرا برای اعطای URI دائمی در راه‌اندازی‌های مجدد دستگاه استفاده می‌شوند. - اسناد می‌توانند فایل قابل‌بازشدن با نوع MIME خاص یا دایرکتوری حاوی اسناد اضافی با نوع MIME
MIME_TYPE_DIRباشند. - هر سند می‌تواند قابلیت‌های متفاوتی داشته باشد، همان‌طور که در
COLUMN_FLAGSشرح داده شده است. برای مثال،FLAG_SUPPORTS_WRITE،FLAG_SUPPORTS_DELETE، وFLAG_SUPPORTS_THUMBNAIL.COLUMN_DOCUMENT_IDیکسان می‌تواند در چند فهرست راهنما گنجانده شود.
کنترل جریان
مدل داده ارائه‌دهنده سند براساس سلسله‌مراتب سنتی فایل است. بااین‌حال، می‌توانید داده‌هایتان را به‌صورت فیزیکی هرطور که دوست دارید ذخیره کنید، به‌شرطی که بتوانید بااستفاده از DocumentsProvider
API به آن دسترسی داشته باشید. برای مثال، می‌توانید از فضای ذخیره‌سازی ابری مبتنی بر برچسب برای داده‌هایتان استفاده کنید.
شکل ۲ نشان می‌دهد که چگونه یک برنامه عکس ممکن است از SAF برای دسترسی به داده‌های ذخیره‌شده استفاده کند:
به موارد زیر توجه کنید:
- در SAF، ارائه‌دهندگان و مشتریان به‌طور مستقیم با یکدیگر تعامل ندارند. کارخواه برای تعامل با فایل‌ها، یعنی خواندن، ویرایش، ایجاد، یا حذف فایل‌ها، درخواست اجازه می‌کند.
- تعامل زمانی شروع می‌شود که برنامه‌ای، در این مثال برنامه عکس، هدف
ACTION_OPEN_DOCUMENTیاACTION_CREATE_DOCUMENTرا فعال می‌کند. هدف می‌تواند شامل فیلترهایی برای پالایش بیشتر معیارها باشد، مثلاً «همه فایل‌های بازشدنی را که نوع MIME آن‌ها «تصویر» است به من بدهید». - وقتی قصد فعال می‌شود، انتخابگر سیستم به هر ارائه‌دهنده ثبت‌شده می‌رود و ریشه‌های محتوای منطبق را به کاربر نشان می‌دهد.
- انتخابگر میانای استانداردی برای دسترسی به اسناد دراختیار کاربران قرار می‌دهد، حتی وقتی ارائه‌دهندگان سند اصلی بسیار متفاوت باشند. برای مثال، شکل ۲ یک ارائه‌دهنده Google Drive، یک ارائه‌دهنده USB، و یک ارائه‌دهنده ابری را نشان می‌دهد.
در شکل ۳، کاربر پوشه «بارگیری‌ها» را از انتخابگری که در جستجوی تصاویر باز شده است انتخاب می‌کند. انتخابگر همچنین همه ریشه‌های دردسترس برای برنامه کارخواه را نشان می‌دهد.
پس‌از اینکه کاربر پوشه «بارگیری‌ها» را انتخاب کرد، تصاویر نمایش داده می‌شود. شکل ۴ نتیجه این فرایند را نشان می‌دهد. اکنون کاربر می‌تواند با تصاویر به روش‌هایی که ارائه‌دهنده و برنامه کارخواه پشتیبانی می‌کنند تعامل داشته باشد.
نوشتن برنامه کارخواه
در Android نسخه ۴.۳ و پایین‌تر، اگر می‌خواهید برنامه‌تان فایلی را از برنامه دیگری بازیابی کند، باید قصدی مثل ACTION_PICK یا ACTION_GET_CONTENT را فراخوانی کند. سپس کاربر یک برنامه را برای انتخاب فایل انتخاب می‌کند. برنامه انتخاب‌شده باید میانای کاربری برای کاربر فراهم کند تا بتواند فایل‌های دردسترس را مرور و انتخاب کند.
در Android 4.4 (سطح API ۱۹) و بالاتر، گزینه دیگری برای استفاده از
ACTION_OPEN_DOCUMENT قصد دارید،
که یک میانای کاربر انتخابگر تحت کنترل سیستم را نمایش می‌دهد که به کاربر اجازه می‌دهد
همه فایل‌هایی را که برنامه‌های دیگر دردسترس قرار داده‌اند مرور کند. از این واسط کاربر واحد،
کاربر می‌تواند فایلی را از هرکدام از برنامه‌های پشتیبانی‌شده انتخاب کند.
در Android 5.0 (سطح میانای برنامه‌سازی کاربردی ۲۱) و بالاتر، می‌توانید از هدف
ACTION_OPEN_DOCUMENT_TREE
نیز استفاده کنید که به کاربر اجازه می‌دهد دایرکتوری‌ای را برای دسترسی برنامه کارخواه
انتخاب کند.
توجه: ACTION_OPEN_DOCUMENT جایگزین ACTION_GET_CONTENT نیست.
اینکه از کدام‌یک استفاده کنید به نیازهای برنامه‌تان بستگی دارد:
- اگر می‌خواهید برنامه‌تان داده‌ها را بخواند یا وارد کند، از
ACTION_GET_CONTENTاستفاده کنید. با این رویکرد، برنامه نسخه‌ای از داده‌ها را وارد می‌کند، مثل فایل تصویری. - اگر می‌خواهید برنامه‌تان دسترسی بلندمدت و دائمی به اسناد متعلق به ارائه‌دهنده سند داشته باشد، از
ACTION_OPEN_DOCUMENTاستفاده کنید. نمونه‌ای از این مورد، برنامه ویرایش عکس است که به کاربران اجازه می‌دهد تصاویر ذخیره‌شده در ارائه‌دهنده سند را ویرایش کنند.
برای اطلاعات بیشتر درباره نحوه پشتیبانی از مرور فایل‌ها و دایرکتوری‌ها بااستفاده از میانای کاربری انتخابگر سیستم، راهنمای مربوط به دسترسی به اسناد و فایل‌های دیگر را ببینید.
منابع بیشتر
برای اطلاعات بیشتر درباره ارائه‌دهندگان سند، از منابع زیر استفاده کنید:
نمونه‌ها
ویدیوها
- DevBytes: Android 4.4 Storage Access Framework: Provider
- فایل‌های مجازی در چارچوب دسترسی به فضای ذخیره‌سازی