باز کردن فایل ها با استفاده از چارچوب دسترسی ذخیره سازی، باز کردن فایل ها با استفاده از چارچوب دسترسی به حافظه، باز کردن فایل ها با استفاده از چارچوب دسترسی به حافظه، باز کردن فایل ها با استفاده از چارچوب دسترسی به حافظه

Android 4.4 (سطح API 19) چارچوب دسترسی به فضای ذخیره سازی (SAF) را معرفی می کند. SAF به کاربران امکان می دهد اسناد، تصاویر و سایر فایل ها را در همه ارائه دهندگان ذخیره سازی اسناد دلخواه خود مرور و باز کنند. یک رابط کاربری ساده و استاندارد به کاربران امکان می‌دهد فایل‌ها را مرور کنند و به فایل‌های اخیر به روشی ثابت در بین برنامه‌ها و ارائه‌دهندگان دسترسی داشته باشند.

سرویس‌های ذخیره‌سازی ابری یا محلی می‌توانند با پیاده‌سازی DocumentsProvider که خدمات آن‌ها را محصور می‌کند، در این اکوسیستم شرکت کنند. برنامه های مشتری که نیاز به دسترسی به اسناد ارائه دهنده دارند می توانند با چند خط کد با SAF ادغام شوند.

SAF شامل موارد زیر است:

  • ارائه‌دهنده سند: ارائه‌دهنده محتوا که به یک سرویس ذخیره‌سازی، مانند Google Drive، اجازه می‌دهد فایل‌هایی را که مدیریت می‌کند، آشکار کند. یک ارائه‌دهنده سند به‌عنوان یک زیر کلاس از کلاس DocumentsProvider پیاده‌سازی می‌شود. طرح ارائه دهنده سند بر اساس سلسله مراتب فایل سنتی است، اگرچه نحوه ذخیره فیزیکی داده ها توسط ارائه دهنده اسناد به شما بستگی دارد. پلتفرم اندروید شامل چندین ارائه دهنده اسناد داخلی مانند دانلودها، تصاویر و ویدیوها می باشد.
  • برنامه مشتری: یک برنامه سفارشی که اقدامات هدف ACTION_CREATE_DOCUMENT ، ACTION_OPEN_DOCUMENT و ACTION_OPEN_DOCUMENT_TREE را فراخوانی می کند و فایل های بازگردانده شده توسط ارائه دهندگان سند را دریافت می کند.
  • Picker: یک رابط کاربری سیستمی که به کاربران امکان می دهد به اسنادی از همه ارائه دهندگان اسنادی که معیارهای جستجوی برنامه مشتری را برآورده می کنند دسترسی داشته باشند.

SAF ویژگی های زیر را ارائه می دهد:

  • به کاربران امکان می دهد محتوا را از همه ارائه دهندگان اسناد مرور کنند، نه فقط یک برنامه.
  • این امکان را برای برنامه شما فراهم می کند که دسترسی طولانی مدت و دائمی به اسناد متعلق به ارائه دهنده اسناد داشته باشد. از طریق این دسترسی، کاربران می توانند فایل ها را در ارائه دهنده اضافه، ویرایش، ذخیره و حذف کنند.
  • از چندین حساب کاربری و ریشه های گذرا مانند ارائه دهندگان حافظه USB پشتیبانی می کند که فقط در صورت وصل بودن درایو ظاهر می شوند.

نمای کلی

SAF حول یک ارائه دهنده محتوا متمرکز است که زیر کلاس کلاس DocumentsProvider است. در یک ارائه دهنده سند، داده ها به عنوان یک سلسله مراتب فایل سنتی ساختار یافته اند:

مدل داده

شکل 1. مدل داده های ارائه دهنده سند. یک ریشه به یک سند واحد اشاره می‌کند، که سپس fan-out درخت را شروع می‌کند.

به موارد زیر توجه کنید:

  • هر ارائه‌دهنده سند یک یا چند ریشه را گزارش می‌کند که نقطه‌ی شروعی برای کاوش درختی از اسناد هستند. هر ریشه یک COLUMN_ROOT_ID منحصر به فرد دارد و به یک سند (یک دایرکتوری) اشاره می کند که محتوای زیر آن ریشه را نشان می دهد. روت ها از نظر طراحی پویا هستند تا از موارد استفاده مانند چندین حساب، دستگاه های ذخیره سازی USB موقت یا ورود و خروج کاربر پشتیبانی کنند.
  • زیر هر ریشه یک سند واحد وجود دارد. آن سند به اسناد 1 تا N اشاره می کند که هر کدام به نوبه خود می توانند به اسناد 1 تا 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 API به آن دسترسی داشته باشید، می‌توانید داده‌های خود را به صورت فیزیکی ذخیره کنید. به عنوان مثال، می توانید از ذخیره سازی ابری مبتنی بر برچسب برای داده های خود استفاده کنید.

شکل 2 نشان می دهد که چگونه یک برنامه عکس ممکن است از SAF برای دسترسی به داده های ذخیره شده استفاده کند:

برنامه

شکل 2. جریان چارچوب دسترسی به ذخیره سازی.

به موارد زیر توجه کنید:

  • در SAF، ارائه دهندگان و مشتریان مستقیماً با هم تعامل ندارند. یک کلاینت برای تعامل با فایل‌ها، یعنی خواندن، ویرایش، ایجاد یا حذف فایل‌ها، اجازه می‌خواهد.
  • این تعامل زمانی شروع می‌شود که یک برنامه کاربردی، در این مثال، یک برنامه عکس، هدف ACTION_OPEN_DOCUMENT یا ACTION_CREATE_DOCUMENT را اجرا می‌کند. این هدف می‌تواند شامل فیلترهایی برای اصلاح بیشتر معیارها باشد، مانند «همه فایل‌های قابل باز شدنی که نوع MIME «تصویر» دارند را به من بدهید.
  • هنگامی که intent فعال می شود، انتخابگر سیستم به هر ارائه دهنده ثبت شده می رود و ریشه های محتوای منطبق را به کاربر نشان می دهد.
  • انتخابگر به کاربران یک رابط استاندارد برای دسترسی به اسناد می دهد، حتی زمانی که ارائه دهندگان اسناد اساسی بسیار متفاوت هستند. به عنوان مثال، شکل 2 یک ارائه دهنده Google Drive، یک ارائه دهنده USB و یک ارائه دهنده ابر را نشان می دهد.

در شکل 3، کاربر در حال انتخاب پوشه Downloads از یک انتخابگر باز شده در جستجوی تصاویر است. انتخابگر همچنین تمام ریشه های موجود برای برنامه مشتری را نشان می دهد.

اسکرین شات انتخاب پوشه در انتخابگر سیستم

شکل 3. انتخابگر پوشه Downloads را که به عنوان مکان جستجو انتخاب شده است را نشان می دهد.

پس از انتخاب پوشه Downloads توسط کاربر، تصاویر نمایش داده می شوند. شکل 4 نتیجه این فرآیند را نشان می دهد. کاربر اکنون می تواند با روش هایی که ارائه دهنده و برنامه مشتری پشتیبانی می کنند با تصاویر تعامل داشته باشد.

اسکرین شات پوشه دانلودها

شکل 4. تصاویر ذخیره شده در پوشه Downloads، همانطور که در انتخابگر سیستم مشاهده می شود.

یک برنامه مشتری بنویسید

در Android نسخه 4.3 و پایین‌تر، اگر می‌خواهید برنامه شما فایلی را از برنامه دیگری بازیابی کند، باید هدفی مانند ACTION_PICK یا ACTION_GET_CONTENT فراخوانی کند. سپس کاربر یک برنامه واحد را انتخاب می کند که از آن یک فایل را انتخاب کند. برنامه انتخاب شده باید یک رابط کاربری برای کاربر فراهم کند تا بتواند فایل های موجود را مرور و انتخاب کند.

در Android 4.4 (سطح API 19) و بالاتر، گزینه دیگری برای استفاده از هدف ACTION_OPEN_DOCUMENT دارید که یک رابط انتخابگر کنترل شده توسط سیستم را نشان می دهد که به کاربر امکان می دهد تمام فایل هایی را که سایر برنامه ها در دسترس قرار داده اند مرور کند. از این رابط کاربری واحد، کاربر می تواند یک فایل را از هر یک از برنامه های پشتیبانی شده انتخاب کند.

در Android نسخه 5.0 (سطح API 21) و بالاتر، می‌توانید از هدف ACTION_OPEN_DOCUMENT_TREE نیز استفاده کنید که به کاربر امکان می‌دهد فهرستی را برای دسترسی یک برنامه مشتری انتخاب کند.

توجه: ACTION_OPEN_DOCUMENT جایگزینی برای ACTION_GET_CONTENT نیست. موردی که استفاده می کنید به نیازهای برنامه شما بستگی دارد:

  • اگر می‌خواهید برنامه‌تان داده‌ها را بخواند یا وارد کند، از ACTION_GET_CONTENT استفاده کنید. با این رویکرد، برنامه یک کپی از داده ها، مانند یک فایل تصویری را وارد می کند.
  • اگر می‌خواهید برنامه شما دسترسی طولانی‌مدت و دائمی به اسناد متعلق به ارائه‌دهنده سند داشته باشد، از ACTION_OPEN_DOCUMENT استفاده کنید. به عنوان مثال یک برنامه ویرایش عکس است که به کاربران امکان می دهد تصاویر ذخیره شده در یک ارائه دهنده سند را ویرایش کنند.

برای اطلاعات بیشتر در مورد نحوه پشتیبانی از مرور فایل‌ها و فهرست‌ها با استفاده از رابط کاربری انتخابگر سیستم، به راهنمای دسترسی به اسناد و فایل‌های دیگر مراجعه کنید.

منابع اضافی

برای اطلاعات بیشتر در مورد ارائه دهندگان اسناد، از منابع زیر استفاده کنید:

نمونه ها

ویدئوها

،

Android 4.4 (سطح API 19) چارچوب دسترسی به فضای ذخیره سازی (SAF) را معرفی می کند. SAF به کاربران امکان می دهد اسناد، تصاویر و سایر فایل ها را در همه ارائه دهندگان ذخیره سازی اسناد دلخواه خود مرور و باز کنند. یک رابط کاربری ساده و استاندارد به کاربران امکان می‌دهد فایل‌ها را مرور کنند و به فایل‌های اخیر به روشی ثابت در بین برنامه‌ها و ارائه‌دهندگان دسترسی داشته باشند.

سرویس‌های ذخیره‌سازی ابری یا محلی می‌توانند با پیاده‌سازی DocumentsProvider که خدمات آن‌ها را محصور می‌کند، در این اکوسیستم شرکت کنند. برنامه های مشتری که نیاز به دسترسی به اسناد ارائه دهنده دارند می توانند با چند خط کد با SAF ادغام شوند.

SAF شامل موارد زیر است:

  • ارائه‌دهنده سند: ارائه‌دهنده محتوا که به یک سرویس ذخیره‌سازی، مانند Google Drive، اجازه می‌دهد فایل‌هایی را که مدیریت می‌کند، آشکار کند. یک ارائه‌دهنده سند به‌عنوان یک زیر کلاس از کلاس DocumentsProvider پیاده‌سازی می‌شود. طرح ارائه دهنده سند بر اساس سلسله مراتب فایل سنتی است، اگرچه نحوه ذخیره فیزیکی داده ها توسط ارائه دهنده اسناد به شما بستگی دارد. پلتفرم اندروید شامل چندین ارائه دهنده اسناد داخلی مانند دانلودها، تصاویر و ویدیوها می باشد.
  • برنامه مشتری: یک برنامه سفارشی که اقدامات هدف ACTION_CREATE_DOCUMENT ، ACTION_OPEN_DOCUMENT و ACTION_OPEN_DOCUMENT_TREE را فراخوانی می کند و فایل های بازگردانده شده توسط ارائه دهندگان سند را دریافت می کند.
  • Picker: یک رابط کاربری سیستمی که به کاربران امکان می دهد به اسنادی از همه ارائه دهندگان اسنادی که معیارهای جستجوی برنامه مشتری را برآورده می کنند دسترسی داشته باشند.

SAF ویژگی های زیر را ارائه می دهد:

  • به کاربران امکان می دهد محتوا را از همه ارائه دهندگان اسناد مرور کنند، نه فقط یک برنامه.
  • این امکان را برای برنامه شما فراهم می کند که دسترسی طولانی مدت و دائمی به اسناد متعلق به ارائه دهنده اسناد داشته باشد. از طریق این دسترسی، کاربران می توانند فایل ها را در ارائه دهنده اضافه، ویرایش، ذخیره و حذف کنند.
  • از چندین حساب کاربری و ریشه های گذرا مانند ارائه دهندگان حافظه USB پشتیبانی می کند که فقط در صورت وصل بودن درایو ظاهر می شوند.

نمای کلی

SAF حول یک ارائه دهنده محتوا متمرکز است که زیر کلاس کلاس DocumentsProvider است. در یک ارائه‌دهنده سند، داده‌ها به عنوان یک سلسله مراتب فایل سنتی ساختار می‌یابند:

مدل داده

شکل 1. مدل داده های ارائه دهنده سند. یک ریشه به یک سند واحد اشاره می‌کند، که سپس fan-out درخت را شروع می‌کند.

به موارد زیر توجه کنید:

  • هر ارائه‌دهنده سند یک یا چند ریشه را گزارش می‌کند که نقطه‌ی شروعی برای کاوش درختی از اسناد هستند. هر ریشه یک COLUMN_ROOT_ID منحصر به فرد دارد و به یک سند (یک دایرکتوری) اشاره می کند که محتوای زیر آن ریشه را نشان می دهد. روت ها از نظر طراحی پویا هستند تا از موارد استفاده مانند چندین حساب، دستگاه های ذخیره سازی USB موقت یا ورود و خروج کاربر پشتیبانی کنند.
  • زیر هر ریشه یک سند واحد وجود دارد. آن سند به اسناد 1 تا N اشاره می کند که هر کدام به نوبه خود می توانند به اسناد 1 تا 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 API به آن دسترسی داشته باشید، می‌توانید داده‌های خود را به صورت فیزیکی ذخیره کنید. به عنوان مثال، می توانید از ذخیره سازی ابری مبتنی بر برچسب برای داده های خود استفاده کنید.

شکل 2 نشان می دهد که چگونه یک برنامه عکس ممکن است از SAF برای دسترسی به داده های ذخیره شده استفاده کند:

برنامه

شکل 2. جریان چارچوب دسترسی به ذخیره سازی.

به موارد زیر توجه کنید:

  • در SAF، ارائه دهندگان و مشتریان مستقیماً با هم تعامل ندارند. یک کلاینت برای تعامل با فایل‌ها، یعنی خواندن، ویرایش، ایجاد یا حذف فایل‌ها، اجازه می‌خواهد.
  • این تعامل زمانی شروع می‌شود که یک برنامه کاربردی، در این مثال، یک برنامه عکس، هدف ACTION_OPEN_DOCUMENT یا ACTION_CREATE_DOCUMENT را اجرا می‌کند. این هدف می‌تواند شامل فیلترهایی برای اصلاح بیشتر معیارها باشد، مانند «همه فایل‌های قابل باز شدنی که نوع MIME «تصویر» دارند را به من بدهید.
  • هنگامی که intent فعال می شود، انتخابگر سیستم به هر ارائه دهنده ثبت شده می رود و ریشه های محتوای منطبق را به کاربر نشان می دهد.
  • انتخابگر به کاربران یک رابط استاندارد برای دسترسی به اسناد می دهد، حتی زمانی که ارائه دهندگان اسناد اساسی بسیار متفاوت هستند. به عنوان مثال، شکل 2 یک ارائه دهنده Google Drive، یک ارائه دهنده USB و یک ارائه دهنده ابر را نشان می دهد.

در شکل 3، کاربر در حال انتخاب پوشه Downloads از یک انتخابگر باز شده در جستجوی تصاویر است. انتخابگر همچنین تمام ریشه های موجود برای برنامه مشتری را نشان می دهد.

اسکرین شات انتخاب پوشه در انتخابگر سیستم

شکل 3. انتخابگر پوشه Downloads را که به عنوان مکان جستجو انتخاب شده است را نشان می دهد.

پس از انتخاب پوشه Downloads توسط کاربر، تصاویر نمایش داده می شوند. شکل 4 نتیجه این فرآیند را نشان می دهد. کاربر اکنون می تواند با تصاویر به روشی که ارائه دهنده و برنامه مشتری پشتیبانی می کند، تعامل داشته باشد.

اسکرین شات پوشه دانلودها

شکل 4. تصاویر ذخیره شده در پوشه Downloads، همانطور که در انتخابگر سیستم مشاهده می شود.

یک برنامه مشتری بنویسید

در Android نسخه 4.3 و پایین‌تر، اگر می‌خواهید برنامه شما فایلی را از برنامه دیگری بازیابی کند، باید هدفی مانند ACTION_PICK یا ACTION_GET_CONTENT فراخوانی کند. سپس کاربر یک برنامه واحد را انتخاب می کند که از آن یک فایل را انتخاب کند. برنامه انتخاب شده باید یک رابط کاربری برای مرور و انتخاب از بین فایل های موجود در اختیار کاربر قرار دهد.

در Android 4.4 (سطح API 19) و بالاتر، گزینه دیگری برای استفاده از هدف ACTION_OPEN_DOCUMENT دارید که یک رابط انتخابگر کنترل شده توسط سیستم را نشان می دهد که به کاربر امکان می دهد تمام فایل هایی را که سایر برنامه ها در دسترس قرار داده اند مرور کند. از این رابط کاربری واحد، کاربر می تواند یک فایل را از هر یک از برنامه های پشتیبانی شده انتخاب کند.

در Android نسخه 5.0 (سطح API 21) و بالاتر، می‌توانید از هدف ACTION_OPEN_DOCUMENT_TREE نیز استفاده کنید که به کاربر امکان می‌دهد فهرستی را برای دسترسی یک برنامه مشتری انتخاب کند.

توجه: ACTION_OPEN_DOCUMENT جایگزینی برای ACTION_GET_CONTENT نیست. موردی که استفاده می کنید به نیازهای برنامه شما بستگی دارد:

  • اگر می‌خواهید برنامه‌تان داده‌ها را بخواند یا وارد کند، از ACTION_GET_CONTENT استفاده کنید. با این رویکرد، برنامه یک کپی از داده ها، مانند یک فایل تصویر را وارد می کند.
  • اگر می‌خواهید برنامه شما دسترسی طولانی‌مدت و دائمی به اسناد متعلق به ارائه‌دهنده سند داشته باشد، از ACTION_OPEN_DOCUMENT استفاده کنید. به عنوان مثال یک برنامه ویرایش عکس است که به کاربران امکان می دهد تصاویر ذخیره شده در یک ارائه دهنده سند را ویرایش کنند.

برای اطلاعات بیشتر در مورد نحوه پشتیبانی از مرور فایل‌ها و فهرست‌ها با استفاده از رابط کاربری انتخابگر سیستم، به راهنمای دسترسی به اسناد و فایل‌های دیگر مراجعه کنید.

منابع اضافی

برای اطلاعات بیشتر در مورد ارائه دهندگان اسناد، از منابع زیر استفاده کنید:

نمونه ها

ویدئوها

،

Android 4.4 (سطح API 19) چارچوب دسترسی به فضای ذخیره سازی (SAF) را معرفی می کند. SAF به کاربران امکان می دهد اسناد، تصاویر و سایر فایل ها را در همه ارائه دهندگان ذخیره سازی اسناد دلخواه خود مرور و باز کنند. یک رابط کاربری ساده و استاندارد به کاربران امکان می‌دهد فایل‌ها را مرور کنند و به فایل‌های اخیر به روشی ثابت در بین برنامه‌ها و ارائه‌دهندگان دسترسی داشته باشند.

سرویس‌های ذخیره‌سازی ابری یا محلی می‌توانند با پیاده‌سازی DocumentsProvider که خدمات آن‌ها را محصور می‌کند، در این اکوسیستم شرکت کنند. برنامه های مشتری که نیاز به دسترسی به اسناد ارائه دهنده دارند می توانند با چند خط کد با SAF ادغام شوند.

SAF شامل موارد زیر است:

  • ارائه‌دهنده سند: ارائه‌دهنده محتوا که به یک سرویس ذخیره‌سازی، مانند Google Drive، اجازه می‌دهد فایل‌هایی را که مدیریت می‌کند، آشکار کند. یک ارائه‌دهنده سند به‌عنوان یک زیر کلاس از کلاس DocumentsProvider پیاده‌سازی می‌شود. طرح ارائه دهنده سند بر اساس سلسله مراتب فایل سنتی است، اگرچه نحوه ذخیره فیزیکی داده ها توسط ارائه دهنده اسناد به شما بستگی دارد. پلتفرم اندروید شامل چندین ارائه دهنده اسناد داخلی مانند دانلودها، تصاویر و ویدیوها می باشد.
  • برنامه مشتری: یک برنامه سفارشی که اقدامات هدف ACTION_CREATE_DOCUMENT ، ACTION_OPEN_DOCUMENT و ACTION_OPEN_DOCUMENT_TREE را فراخوانی می کند و فایل های بازگردانده شده توسط ارائه دهندگان سند را دریافت می کند.
  • Picker: یک رابط کاربری سیستمی که به کاربران امکان می دهد به اسنادی از همه ارائه دهندگان اسنادی که معیارهای جستجوی برنامه مشتری را برآورده می کنند دسترسی داشته باشند.

SAF ویژگی های زیر را ارائه می دهد:

  • به کاربران امکان می دهد محتوا را از همه ارائه دهندگان اسناد مرور کنند، نه فقط یک برنامه.
  • این امکان را برای برنامه شما فراهم می کند که دسترسی طولانی مدت و دائمی به اسناد متعلق به ارائه دهنده اسناد داشته باشد. از طریق این دسترسی، کاربران می توانند فایل ها را در ارائه دهنده اضافه، ویرایش، ذخیره و حذف کنند.
  • از چندین حساب کاربری و ریشه های گذرا مانند ارائه دهندگان حافظه USB پشتیبانی می کند که فقط در صورت وصل بودن درایو ظاهر می شوند.

نمای کلی

SAF حول یک ارائه دهنده محتوا متمرکز است که زیر کلاس کلاس DocumentsProvider است. در یک ارائه دهنده سند، داده ها به عنوان یک سلسله مراتب فایل سنتی ساختار یافته اند:

مدل داده

شکل 1. مدل داده های ارائه دهنده سند. یک ریشه به یک سند واحد اشاره می کند، که سپس fan-out درخت را شروع می کند.

به موارد زیر توجه کنید:

  • هر ارائه‌دهنده سند یک یا چند ریشه را گزارش می‌کند که نقطه‌ی شروعی برای کاوش درختی از اسناد هستند. هر ریشه یک COLUMN_ROOT_ID منحصر به فرد دارد و به یک سند (یک دایرکتوری) اشاره می کند که محتوای زیر آن ریشه را نشان می دهد. روت ها از نظر طراحی پویا هستند تا از موارد استفاده مانند چندین حساب، دستگاه های ذخیره سازی USB موقت یا ورود و خروج کاربر پشتیبانی کنند.
  • زیر هر ریشه یک سند واحد وجود دارد. آن سند به اسناد 1 تا N اشاره می کند که هر کدام به نوبه خود می توانند به اسناد 1 تا 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 API به آن دسترسی داشته باشید، می‌توانید داده‌های خود را به صورت فیزیکی ذخیره کنید. به عنوان مثال، می توانید از ذخیره سازی ابری مبتنی بر برچسب برای داده های خود استفاده کنید.

شکل 2 نشان می دهد که چگونه یک برنامه عکس ممکن است از SAF برای دسترسی به داده های ذخیره شده استفاده کند:

برنامه

شکل 2. جریان چارچوب دسترسی به ذخیره سازی.

به موارد زیر توجه کنید:

  • در SAF، ارائه دهندگان و مشتریان مستقیماً با هم تعامل ندارند. یک کلاینت برای تعامل با فایل‌ها، یعنی خواندن، ویرایش، ایجاد یا حذف فایل‌ها، اجازه می‌خواهد.
  • این تعامل زمانی شروع می‌شود که یک برنامه کاربردی، در این مثال، یک برنامه عکس، هدف ACTION_OPEN_DOCUMENT یا ACTION_CREATE_DOCUMENT را اجرا می‌کند. این هدف می‌تواند شامل فیلترهایی برای اصلاح بیشتر معیارها باشد، مانند «همه فایل‌های قابل باز شدنی که نوع MIME «تصویر» دارند را به من بدهید.
  • هنگامی که intent فعال می شود، انتخابگر سیستم به هر ارائه دهنده ثبت شده می رود و ریشه های محتوای منطبق را به کاربر نشان می دهد.
  • انتخابگر به کاربران یک رابط استاندارد برای دسترسی به اسناد می دهد، حتی زمانی که ارائه دهندگان اسناد اساسی بسیار متفاوت هستند. به عنوان مثال، شکل 2 یک ارائه دهنده Google Drive، یک ارائه دهنده USB و یک ارائه دهنده ابر را نشان می دهد.

در شکل 3، کاربر در حال انتخاب پوشه Downloads از یک انتخابگر باز شده در جستجوی تصاویر است. انتخابگر همچنین تمام ریشه های موجود برای برنامه مشتری را نشان می دهد.

اسکرین شات انتخاب پوشه در انتخابگر سیستم

شکل 3. انتخابگر پوشه Downloads را که به عنوان مکان جستجو انتخاب شده است را نشان می دهد.

پس از انتخاب پوشه Downloads توسط کاربر، تصاویر نمایش داده می شوند. شکل 4 نتیجه این فرآیند را نشان می دهد. کاربر اکنون می تواند با تصاویر به روشی که ارائه دهنده و برنامه مشتری پشتیبانی می کند، تعامل داشته باشد.

اسکرین شات پوشه دانلودها

شکل 4. تصاویر ذخیره شده در پوشه Downloads، همانطور که در انتخابگر سیستم مشاهده می شود.

یک برنامه مشتری بنویسید

در Android نسخه 4.3 و پایین‌تر، اگر می‌خواهید برنامه شما فایلی را از برنامه دیگری بازیابی کند، باید هدفی مانند ACTION_PICK یا ACTION_GET_CONTENT فراخوانی کند. سپس کاربر یک برنامه واحد را انتخاب می کند که از آن یک فایل را انتخاب کند. برنامه انتخاب شده باید یک رابط کاربری برای کاربر فراهم کند تا بتواند فایل های موجود را مرور و انتخاب کند.

در Android 4.4 (سطح API 19) و بالاتر، گزینه دیگری برای استفاده از هدف ACTION_OPEN_DOCUMENT دارید که یک رابط انتخابگر کنترل شده توسط سیستم را نشان می دهد که به کاربر امکان می دهد تمام فایل هایی را که سایر برنامه ها در دسترس قرار داده اند مرور کند. از این رابط کاربری واحد، کاربر می تواند یک فایل را از هر یک از برنامه های پشتیبانی شده انتخاب کند.

در Android نسخه 5.0 (سطح API 21) و بالاتر، می‌توانید از هدف ACTION_OPEN_DOCUMENT_TREE نیز استفاده کنید که به کاربر امکان می‌دهد فهرستی را برای دسترسی یک برنامه مشتری انتخاب کند.

توجه: ACTION_OPEN_DOCUMENT جایگزینی برای ACTION_GET_CONTENT نیست. موردی که استفاده می کنید به نیازهای برنامه شما بستگی دارد:

  • اگر می‌خواهید برنامه‌تان داده‌ها را بخواند یا وارد کند، از ACTION_GET_CONTENT استفاده کنید. با این رویکرد، برنامه یک کپی از داده ها، مانند یک فایل تصویری را وارد می کند.
  • اگر می‌خواهید برنامه شما دسترسی طولانی‌مدت و دائمی به اسناد متعلق به ارائه‌دهنده سند داشته باشد، از ACTION_OPEN_DOCUMENT استفاده کنید. به عنوان مثال یک برنامه ویرایش عکس است که به کاربران امکان می دهد تصاویر ذخیره شده در یک ارائه دهنده سند را ویرایش کنند.

برای اطلاعات بیشتر در مورد نحوه پشتیبانی از مرور فایل‌ها و فهرست‌ها با استفاده از رابط کاربری انتخابگر سیستم، به راهنمای دسترسی به اسناد و فایل‌های دیگر مراجعه کنید.

منابع اضافی

برای اطلاعات بیشتر در مورد ارائه دهندگان اسناد، از منابع زیر استفاده کنید:

نمونه ها

ویدئوها

،

Android 4.4 (سطح API 19) چارچوب دسترسی به فضای ذخیره سازی (SAF) را معرفی می کند. SAF به کاربران امکان می دهد اسناد، تصاویر و سایر فایل ها را در تمام ارائه دهندگان ذخیره سازی اسناد دلخواه خود مرور و باز کنند. یک رابط کاربری ساده و استاندارد به کاربران امکان می‌دهد فایل‌ها را مرور کنند و به فایل‌های اخیر به روشی ثابت در میان برنامه‌ها و ارائه‌دهندگان دسترسی داشته باشند.

سرویس‌های ذخیره‌سازی ابری یا محلی می‌توانند با پیاده‌سازی DocumentsProvider که خدمات آن‌ها را محصور می‌کند، در این اکوسیستم شرکت کنند. برنامه های مشتری که نیاز به دسترسی به اسناد ارائه دهنده دارند می توانند با چند خط کد با SAF ادغام شوند.

SAF شامل موارد زیر است:

  • ارائه‌دهنده سند: ارائه‌دهنده محتوا که به یک سرویس ذخیره‌سازی، مانند Google Drive، اجازه می‌دهد فایل‌هایی را که مدیریت می‌کند، آشکار کند. یک ارائه‌دهنده سند به‌عنوان یک زیر کلاس از کلاس DocumentsProvider پیاده‌سازی می‌شود. طرح ارائه‌دهنده سند بر اساس سلسله مراتب فایل سنتی است، اگرچه نحوه ذخیره فیزیکی داده‌ها توسط ارائه‌دهنده سند به شما بستگی دارد. پلتفرم اندروید شامل چندین ارائه‌دهنده اسناد داخلی است، مانند دانلودها، تصاویر و ویدیوها.
  • برنامه مشتری: یک برنامه سفارشی که اقدامات هدف ACTION_CREATE_DOCUMENT ، ACTION_OPEN_DOCUMENT و ACTION_OPEN_DOCUMENT_TREE را فراخوانی می کند و فایل های بازگردانده شده توسط ارائه دهندگان سند را دریافت می کند.
  • Picker: یک رابط کاربری سیستمی که به کاربران امکان می دهد به اسنادی از همه ارائه دهندگان اسنادی که معیارهای جستجوی برنامه مشتری را برآورده می کنند دسترسی داشته باشند.

SAF ویژگی های زیر را ارائه می دهد:

  • به کاربران امکان می دهد محتوا را از همه ارائه دهندگان اسناد مرور کنند، نه فقط یک برنامه.
  • این امکان را برای برنامه شما فراهم می کند که دسترسی طولانی مدت و دائمی به اسناد متعلق به ارائه دهنده اسناد داشته باشد. از طریق این دسترسی، کاربران می توانند فایل ها را در ارائه دهنده اضافه، ویرایش، ذخیره و حذف کنند.
  • از چندین حساب کاربری و ریشه های گذرا مانند ارائه دهندگان حافظه USB پشتیبانی می کند که فقط در صورت وصل بودن درایو ظاهر می شوند.

نمای کلی

SAF حول یک ارائه دهنده محتوا متمرکز است که زیر کلاس کلاس DocumentsProvider است. در یک ارائه دهنده سند، داده ها به عنوان یک سلسله مراتب فایل سنتی ساختار یافته اند:

مدل داده

شکل 1. مدل داده های ارائه دهنده سند. یک ریشه به یک سند واحد اشاره می‌کند، که سپس fan-out درخت را شروع می‌کند.

به موارد زیر توجه کنید:

  • هر ارائه‌دهنده سند یک یا چند ریشه را گزارش می‌کند که نقطه‌ی شروعی برای کاوش درختی از اسناد هستند. هر ریشه یک COLUMN_ROOT_ID منحصر به فرد دارد و به یک سند (یک دایرکتوری) اشاره می کند که محتوای زیر آن ریشه را نشان می دهد. روت ها از نظر طراحی پویا هستند تا از موارد استفاده مانند چندین حساب، دستگاه های ذخیره سازی USB موقت یا ورود و خروج کاربر پشتیبانی کنند.
  • زیر هر ریشه یک سند واحد وجود دارد. آن سند به اسناد 1 تا N اشاره می کند که هر کدام به نوبه خود می توانند به اسناد 1 تا 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 API به آن دسترسی داشته باشید، می‌توانید داده‌های خود را به صورت فیزیکی ذخیره کنید. به عنوان مثال، می توانید از ذخیره سازی ابری مبتنی بر برچسب برای داده های خود استفاده کنید.

شکل 2 نشان می دهد که چگونه یک برنامه عکس ممکن است از SAF برای دسترسی به داده های ذخیره شده استفاده کند:

برنامه

شکل 2. جریان چارچوب دسترسی به ذخیره سازی.

به موارد زیر توجه کنید:

  • در SAF، ارائه دهندگان و مشتریان مستقیماً با هم تعامل ندارند. یک کلاینت برای تعامل با فایل‌ها، یعنی خواندن، ویرایش، ایجاد یا حذف فایل‌ها، اجازه می‌خواهد.
  • این تعامل زمانی شروع می‌شود که یک برنامه کاربردی، در این مثال، یک برنامه عکس، هدف ACTION_OPEN_DOCUMENT یا ACTION_CREATE_DOCUMENT را اجرا می‌کند. این هدف می‌تواند شامل فیلترهایی برای اصلاح بیشتر معیارها باشد، مانند "همه فایل‌های قابل باز شدنی که دارای نوع MIME" تصویر هستند را به من بدهید."
  • هنگامی که intent فعال می شود، انتخابگر سیستم به هر ارائه دهنده ثبت شده می رود و ریشه های محتوای منطبق را به کاربر نشان می دهد.
  • انتخابگر به کاربران یک رابط استاندارد برای دسترسی به اسناد می دهد، حتی زمانی که ارائه دهندگان اسناد اساسی بسیار متفاوت هستند. به عنوان مثال، شکل 2 یک ارائه دهنده Google Drive، یک ارائه دهنده USB و یک ارائه دهنده ابر را نشان می دهد.

در شکل 3، کاربر در حال انتخاب پوشه Downloads از یک انتخابگر باز شده در جستجوی تصاویر است. انتخابگر همچنین تمام ریشه های موجود در برنامه مشتری را نشان می دهد.

اسکرین شات انتخاب پوشه در انتخابگر سیستم

شکل 3. انتخابگر پوشه Downloads را که به عنوان مکان جستجو انتخاب شده است را نشان می دهد.

پس از انتخاب پوشه Downloads توسط کاربر، تصاویر نمایش داده می شوند. شکل 4 نتیجه این فرآیند را نشان می دهد. کاربر اکنون می تواند با روش هایی که ارائه دهنده و برنامه مشتری پشتیبانی می کنند با تصاویر تعامل داشته باشد.

اسکرین شات پوشه دانلودها

شکل 4. تصاویر ذخیره شده در پوشه Downloads، همانطور که در انتخابگر سیستم مشاهده می شود.

یک برنامه مشتری بنویسید

در Android نسخه 4.3 و پایین‌تر، اگر می‌خواهید برنامه شما فایلی را از برنامه دیگری بازیابی کند، باید هدفی مانند ACTION_PICK یا ACTION_GET_CONTENT فراخوانی کند. سپس کاربر یک برنامه واحد را انتخاب می کند که از آن یک فایل را انتخاب کند. برنامه انتخاب شده باید یک رابط کاربری برای کاربر فراهم کند تا بتواند فایل های موجود را مرور و انتخاب کند.

در Android 4.4 (سطح API 19) و بالاتر، گزینه دیگری برای استفاده از هدف ACTION_OPEN_DOCUMENT دارید که یک رابط انتخابگر کنترل شده توسط سیستم را نشان می دهد که به کاربر امکان می دهد تمام فایل هایی را که سایر برنامه ها در دسترس قرار داده اند مرور کند. از این رابط کاربری واحد، کاربر می تواند یک فایل را از هر یک از برنامه های پشتیبانی شده انتخاب کند.

در Android نسخه 5.0 (سطح API 21) و بالاتر، می‌توانید از هدف ACTION_OPEN_DOCUMENT_TREE نیز استفاده کنید که به کاربر امکان می‌دهد فهرستی را برای دسترسی یک برنامه مشتری انتخاب کند.

توجه: ACTION_OPEN_DOCUMENT جایگزینی برای ACTION_GET_CONTENT نیست. موردی که استفاده می کنید به نیازهای برنامه شما بستگی دارد:

  • اگر می‌خواهید برنامه‌تان داده‌ها را بخواند یا وارد کند، از ACTION_GET_CONTENT استفاده کنید. با این رویکرد، برنامه یک کپی از داده ها، مانند یک فایل تصویری را وارد می کند.
  • اگر می‌خواهید برنامه شما دسترسی طولانی‌مدت و دائمی به اسناد متعلق به ارائه‌دهنده سند داشته باشد، از ACTION_OPEN_DOCUMENT استفاده کنید. به عنوان مثال یک برنامه ویرایش عکس است که به کاربران امکان می دهد تصاویر ذخیره شده در یک ارائه دهنده سند را ویرایش کنند.

برای اطلاعات بیشتر در مورد نحوه پشتیبانی از مرور فایل‌ها و فهرست‌ها با استفاده از رابط کاربری انتخابگر سیستم، به راهنمای دسترسی به اسناد و فایل‌های دیگر مراجعه کنید.

منابع اضافی

برای اطلاعات بیشتر در مورد ارائه دهندگان اسناد، از منابع زیر استفاده کنید:

نمونه ها

ویدئوها

قبلی
ایجاد یک ارائه دهنده محتوا
بعدی
یک ارائه دهنده اسناد سفارشی ایجاد کنید