موارد استفاده و بهترین روش های ذخیره سازی اندروید

برای اینکه کاربران کنترل بیشتری بر فایل‌های خود داشته باشند و از شلوغی فایل‌ها جلوگیری شود، اندروید ۱۰ یک الگوی ذخیره‌سازی جدید برای برنامه‌ها به نام ذخیره‌سازی محدود (scoped storage) معرفی کرد. ذخیره‌سازی محدود، نحوه ذخیره‌سازی و دسترسی برنامه‌ها به فایل‌ها در حافظه خارجی دستگاه را تغییر می‌دهد. برای کمک به شما در انتقال برنامه خود به پشتیبانی از ذخیره‌سازی محدود، بهترین شیوه‌ها را برای موارد استفاده رایج از ذخیره‌سازی که در این راهنما ذکر شده است، دنبال کنید. موارد استفاده به دو دسته تقسیم می‌شوند: مدیریت فایل‌های رسانه‌ای و مدیریت فایل‌های غیررسانه‌ای .

در بسیاری از موارد، برنامه شما فایل‌هایی ایجاد می‌کند که سایر برنامه‌ها نیازی به دسترسی به آنها ندارند یا نباید به آنها دسترسی داشته باشند. سیستم ، مکان‌های ذخیره‌سازی مخصوص برنامه را برای مدیریت چنین فایل‌هایی فراهم می‌کند.

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

مدیریت فایل‌های رسانه‌ای

این بخش برخی از موارد استفاده رایج برای مدیریت فایل‌های رسانه‌ای (ویدئو، تصویر و فایل‌های صوتی) را شرح می‌دهد و رویکرد سطح بالایی را که برنامه شما می‌تواند از آن استفاده کند، توضیح می‌دهد. جدول زیر خلاصه‌ای از هر یک از این موارد استفاده را ارائه می‌دهد و به هر یک از بخش‌هایی که حاوی جزئیات بیشتر هستند، لینک می‌دهد.

نمایش فایل‌های تصویر یا ویدیو از چندین پوشه

با استفاده از API query() یک مجموعه رسانه را جستجو کنید . برای فیلتر کردن یا مرتب‌سازی فایل‌های رسانه، پارامترهای projection ، selection ، selectionArgs و sortOrder را تنظیم کنید.

نمایش تصاویر یا ویدیوها از یک پوشه خاص

از این رویکرد استفاده کنید:

1. با پیروی از بهترین شیوه‌های ذکر شده در «درخواست مجوزهای برنامه» ، مجوز READ_EXTERNAL_STORAGE را درخواست کنید.
2. فایل‌های رسانه‌ای را بر اساس مقدار MediaColumns.DATA بازیابی کنید، که شامل مسیر مطلق فایل سیستم به آیتم رسانه‌ای روی دیسک است.

دسترسی به اطلاعات موقعیت مکانی از روی عکس‌ها

اگر برنامه شما از فضای ذخیره‌سازی محدود (scoped storage) استفاده می‌کند، مراحل موجود در بخش اطلاعات موقعیت مکانی در عکس‌ها از راهنمای فضای ذخیره‌سازی رسانه را دنبال کنید.

تعریف محل ذخیره‌سازی برای دانلودهای جدید

اگر برنامه شما از فضای ذخیره‌سازی محدود (scoped storage) استفاده می‌کند، به مکانی که برای ذخیره فایل‌های رسانه‌ای که دانلود می‌کنید انتخاب می‌کنید، توجه داشته باشید.

اگر برنامه‌های دیگر نیاز به دسترسی به فایل‌ها دارند، استفاده از مجموعه‌های رسانه‌ای تعریف‌شده برای دانلودها یا مجموعه‌های اسناد را در نظر بگیرید.

در اندروید ۱۱ و بالاتر، فایل‌های داخل دایرکتوری مخصوص برنامه خارجی شما برای سایر برنامه‌ها قابل دسترسی نیستند، حتی اگر از DownloadManager برای دریافت این فایل‌ها استفاده کنید.

فایل‌های رسانه‌ای کاربر را به یک دستگاه صادر کنید

یک مکان پیش‌فرض مناسب برای ذخیره فایل‌های رسانه‌ای کاربر تعریف کنید:

• به کاربران اجازه دهید انتخاب کنند که آیا فایل‌های رسانه‌ای خود را با استفاده از app-specific-storage یا shared storage ، برای سایر برنامه‌ها قابل خواندن کنند یا خیر.
• به کاربران اجازه دهید فایل‌ها را از دایرکتوری‌های خاص برنامه به مکانی با دسترسی عمومی‌تر صادر کنند. از مجموعه‌های تصاویر، ویدیو و صدای MediaStore برای صادر کردن فایل‌های رسانه‌ای به گالری دستگاه استفاده کنید.

چندین فایل رسانه‌ای را در یک عملیات واحد تغییر دهید یا حذف کنید

منطق را بر اساس نسخه‌های اندرویدی که برنامه شما روی آنها اجرا می‌شود، لحاظ کنید.

اجرا روی اندروید ۱۱

از این رویکرد استفاده کنید:

1. با استفاده از MediaStore.createWriteRequest() یا MediaStore.createTrashRequest() یک intent در حال انتظار برای درخواست نوشتن یا حذف برنامه خود ایجاد کنید و سپس با فراخوانی آن intent، از کاربر اجازه ویرایش مجموعه‌ای از فایل‌ها را بگیرید.

2. ارزیابی پاسخ کاربر:

   • اگر مجوز داده شد، عملیات تغییر یا حذف را ادامه دهید.
   • اگر مجوز اعطا نشده بود، به کاربر توضیح دهید که چرا این ویژگی در برنامه شما به این مجوز نیاز دارد.

درباره نحوه مدیریت گروه‌های فایل‌های رسانه‌ای با استفاده از این روش‌های موجود در اندروید ۱۱ و بالاتر بیشتر بدانید.

اجرا روی اندروید ۱۰

اگر برنامه شما اندروید ۱۰ (سطح API ۲۹) را هدف قرار می‌دهد، از ذخیره‌سازی محدود (scoped storage) صرف نظر کنید و برای انجام این عملیات، به استفاده از رویکرد مربوط به اندروید ۹ و پایین‌تر ادامه دهید.

قابل اجرا روی اندروید ۹ یا پایین‌تر

از این رویکرد استفاده کنید:

1. با پیروی از بهترین شیوه‌های ذکر شده در «درخواست مجوزهای برنامه» ، مجوز WRITE_EXTERNAL_STORAGE را درخواست کنید.
2. از API MediaStore برای تغییر یا حذف فایل‌های رسانه‌ای استفاده کنید.

یک تصویر واحد که از قبل وجود دارد را وارد کنید

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

رابط کاربری خودتان را ارائه دهید

از این رویکرد استفاده کنید:

1. با پیروی از بهترین شیوه‌های ذکر شده در «درخواست مجوزهای برنامه» ، مجوز READ_EXTERNAL_STORAGE را درخواست کنید.
2. از API query() برای جستجو در یک مجموعه رسانه استفاده کنید.
3. نتایج را در رابط کاربری سفارشی برنامه خود نمایش دهید.

از انتخابگر سیستم استفاده کنید

از هدف ACTION_GET_CONTENT استفاده کنید، که از کاربر می‌خواهد تصویری را برای وارد کردن انتخاب کند.

اگر می‌خواهید انواع تصاویری را که انتخابگر سیستم برای انتخاب به کاربر ارائه می‌دهد، فیلتر کنید، می‌توانید از setType() یا EXTRA_MIME_TYPES استفاده کنید.

ثبت یک تصویر واحد

وقتی می‌خواهید یک تصویر واحد را برای استفاده در برنامه خود ثبت کنید (برای مثال، برای استفاده به عنوان عکس پروفایل کاربر)، از اینتنت ACTION_IMAGE_CAPTURE برای درخواست از کاربر برای گرفتن عکس با استفاده از دوربین دستگاه استفاده کنید. سیستم عکس ثبت شده را در جدول MediaStore.Images ذخیره می‌کند.

اشتراک‌گذاری فایل‌های رسانه‌ای با سایر برنامه‌ها

از متد insert() برای اضافه کردن مستقیم رکوردها به MediaStore استفاده کنید. برای اطلاعات بیشتر، به بخش «افزودن یک آیتم» در راهنمای ذخیره‌سازی رسانه مراجعه کنید.

اشتراک‌گذاری فایل‌های رسانه‌ای با یک برنامه خاص

همانطور که در راهنمای راه‌اندازی اشتراک‌گذاری فایل توضیح داده شده است، از کامپوننت FileProvider اندروید استفاده کنید.

دسترسی به فایل‌ها از کد یا کتابخانه‌هایی که از مسیرهای مستقیم فایل استفاده می‌کنند

منطق را بر اساس نسخه‌های اندرویدی که برنامه شما روی آنها اجرا می‌شود، لحاظ کنید.

اجرا روی اندروید ۱۱

از این رویکرد استفاده کنید:

1. با پیروی از بهترین شیوه‌های ذکر شده در «درخواست مجوزهای برنامه» ، مجوز READ_EXTERNAL_STORAGE را درخواست کنید.
2. دسترسی به فایل‌ها با استفاده از مسیرهای مستقیم فایل.

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

اجرا روی اندروید ۱۰

اگر برنامه شما اندروید ۱۰ (سطح API ۲۹) را هدف قرار می‌دهد، از ذخیره‌سازی محدود (scoped storage) صرف نظر کنید و برای انجام این عملیات، به استفاده از رویکرد مربوط به اندروید ۹ و پایین‌تر ادامه دهید.

قابل اجرا روی اندروید ۹ یا پایین‌تر

از این رویکرد استفاده کنید:

1. با پیروی از بهترین شیوه‌های ذکر شده در «درخواست مجوزهای برنامه» ، مجوز WRITE_EXTERNAL_STORAGE را درخواست کنید.
2. دسترسی به فایل‌ها با استفاده از مسیرهای مستقیم فایل.

مدیریت فایل‌های غیررسانه‌ای

این بخش برخی از موارد استفاده رایج برای مدیریت فایل‌های غیررسانه‌ای را شرح می‌دهد و رویکرد سطح بالایی را که برنامه شما می‌تواند از آن استفاده کند، توضیح می‌دهد. جدول زیر خلاصه‌ای از هر یک از این موارد استفاده را ارائه می‌دهد و به هر یک از بخش‌هایی که حاوی جزئیات بیشتر هستند، لینک می‌دهد.

باز کردن یک فایل سند

از تابع ACTION_OPEN_DOCUMENT برای درخواست از کاربر جهت انتخاب فایلی جهت باز کردن با استفاده از انتخابگر سیستم استفاده کنید. اگر می‌خواهید انواع فایل‌هایی را که انتخابگر سیستم برای انتخاب به کاربر ارائه می‌دهد، فیلتر کنید، می‌توانید از setType() یا EXTRA_MIME_TYPES استفاده کنید.

برای مثال، می‌توانید تمام فایل‌های PDF، ODT و TXT را با استفاده از کد زیر پیدا کنید:

startActivityForResult(
        Intent(Intent.ACTION_OPEN_DOCUMENT).apply {
            addCategory(Intent.CATEGORY_OPENABLE)
            type = "*/*"
            putExtra(Intent.EXTRA_MIME_TYPES, arrayOf(
                    "application/pdf", // .pdf
                    "application/vnd.oasis.opendocument.text", // .odt
                    "text/plain" // .txt
            ))
        },
        REQUEST_CODE
      )

Intent intent = new Intent(Intent.ACTION_OPEN_DOCUMENT);
        intent.addCategory(Intent.CATEGORY_OPENABLE);
        intent.setType("*/*");
        intent.putExtra(Intent.EXTRA_MIME_TYPES, new String[] {
                "application/pdf", // .pdf
                "application/vnd.oasis.opendocument.text", // .odt
                "text/plain" // .txt
        });
        startActivityForResult(intent, REQUEST_CODE);

نوشتن روی فایل‌ها روی حافظه‌های ثانویه

حافظه‌های ثانویه شامل کارت‌های SD می‌شوند. شما می‌توانید با استفاده از کلاس StorageVolume به اطلاعات مربوط به یک حافظه داده شده دسترسی داشته باشید.

منطق را بر اساس نسخه اندرویدی که برنامه شما روی آن اجرا می‌شود، در برنامه بگنجانید.

اجرا روی اندروید ۱۱

از این رویکرد استفاده کنید:

1. از مدل ذخیره‌سازی محدود (scoped storage model) استفاده کنید.
2. اندروید ۱۰ (سطح API ۲۹) یا پایین‌تر را هدف قرار دهید.
3. مجوز WRITE_EXTERNAL_STORAGE را اعلام کنید.
4. یکی از انواع دسترسی زیر را انجام دهید:
   • دسترسی به فایل با استفاده از API MediaStore .
   • دسترسی مستقیم به مسیر فایل با استفاده از APIهایی مانند File یا fopen() ‎.

اجرا روی نسخه‌های قدیمی‌تر

از چارچوب دسترسی به حافظه (Storage Access Framework) استفاده کنید، که به کاربران اجازه می‌دهد مکانی را روی یک حافظه ثانویه انتخاب کنند که برنامه شما بتواند فایل را در آن بنویسد.

انتقال فایل‌های موجود از یک محل ذخیره‌سازی قدیمی

یک دایرکتوری اگر یک دایرکتوری مخصوص برنامه یا یک دایرکتوری اشتراکی عمومی نباشد، یک مکان ذخیره‌سازی قدیمی در نظر گرفته می‌شود. اگر برنامه شما فایل‌ها را در یک مکان ذخیره‌سازی قدیمی ایجاد یا استفاده می‌کند، توصیه می‌کنیم فایل‌های برنامه خود را به مکان‌هایی که با ذخیره‌سازی محدود قابل دسترسی هستند، منتقل کنید و هرگونه تغییر لازم در برنامه را برای کار با فایل‌های موجود در ذخیره‌سازی محدود انجام دهید.

دسترسی به محل ذخیره‌سازی قدیمی را برای انتقال داده‌ها حفظ کنید

برنامه شما برای انتقال فایل‌های برنامه به مکان‌هایی که با ذخیره‌سازی محدود قابل دسترسی هستند، باید به مکان ذخیره‌سازی قدیمی دسترسی داشته باشد. رویکردی که باید استفاده کنید به سطح API هدف برنامه شما بستگی دارد.

اگر برنامه شما اندروید ۱۱ را هدف قرار داده است

1. برای حفظ مدل ذخیره‌سازی قدیمی، پرچم preserveLegacyExternalStorage را روی true تنظیم کنید تا برنامه شما بتواند داده‌های کاربر را هنگام ارتقاء به نسخه جدید برنامه که برای اندروید ۱۱ طراحی شده است، منتقل کند.

2. همچنان از ذخیره‌سازی محدود شده انصراف دهید تا برنامه شما بتواند به فایل‌های شما در محل ذخیره‌سازی قدیمی در دستگاه‌های اندروید ۱۰ دسترسی داشته باشد.

اگر برنامه شما اندروید ۱۰ را هدف قرار داده است

برای اینکه بتوانید رفتار برنامه خود را در نسخه‌های مختلف اندروید راحت‌تر حفظ کنید ، از فضای ذخیره‌سازی محدود (scoped storage) خارج شوید .

انتقال داده‌های برنامه

وقتی برنامه شما آماده مهاجرت است، از رویکرد زیر استفاده کنید:

1. اندروید ۱۰ یا پایین‌تر را هدف قرار دهید.
2. از فضای ذخیره‌سازی محدود (scoped storage) خارج شوید تا برنامه شما به فایل‌هایی که برای انتقال نیاز دارید دسترسی داشته باشد.

3. کدی را مستقر کنید که از API File برای انتقال فایل‌ها از مکان فعلی‌شان در /sdcard/ به مکانی که با ذخیره‌سازی محدود قابل دسترسی است، استفاده کند:

   1. فایل‌های خصوصی برنامه را به دایرکتوری که توسط متد getExternalFilesDir() برگردانده می‌شود، منتقل کنید.
   2. هرگونه فایل غیررسانه‌ای اشتراکی را به یک زیرشاخه اختصاصی برنامه در پوشه Downloads/ منتقل کنید.
4. دایرکتوری‌های ذخیره‌سازی قدیمی برنامه خود را از دایرکتوری /sdcard/ حذف کنید.

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

پس از اینکه کاربران داده‌های خود را منتقل کردند، به‌روزرسانی دیگری برای برنامه خود منتشر کنید، که در آن اندروید ۱۱ را هدف قرار داده‌اید.

اشتراک‌گذاری محتوا با سایر برنامه‌ها

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

فایل‌های غیررسانه‌ای را در حافظه پنهان (cache) ذخیره کنید

رویکردی که باید استفاده کنید بستگی به نوع فایل‌هایی دارد که باید کش کنید.

• فایل‌های کوچک یا فایل‌هایی که حاوی اطلاعات حساس هستند : از Context#getCacheDir() استفاده کنید.
• فایل‌های بزرگ یا فایل‌هایی که حاوی اطلاعات حساس نیستند : از Context#getExternalCacheDir() استفاده کنید.

فایل‌های غیررسانه‌ای را به یک دستگاه صادر کنید

یک مکان پیش‌فرض مناسب برای ذخیره فایل‌های غیررسانه‌ای تعریف کنید. به کاربران اجازه دهید فایل‌ها را از دایرکتوری‌های خاص برنامه به مکانی با دسترسی عمومی‌تر صادر کنند. از دانلودها یا مجموعه‌های اسناد MediaStore برای صادر کردن فایل‌های غیررسانه‌ای به دستگاه استفاده کنید.

مدیریت فایل‌های مخصوص برنامه

در صورتی که برنامه شما فایل‌هایی ایجاد کند که سایر برنامه‌ها نیازی به دسترسی به آنها ندارند یا نباید به آنها دسترسی داشته باشند، می‌توانید این فایل‌ها را در مکان‌های ذخیره‌سازی مخصوص برنامه ذخیره کنید.

دایرکتوری‌های حافظه داخلی

سیستم از دسترسی سایر برنامه‌ها به این مکان‌ها جلوگیری می‌کند و در اندروید ۱۰ (سطح API ۲۹) و بالاتر، این مکان‌ها رمزگذاری می‌شوند. این مکان‌ها مکان مناسبی برای ذخیره داده‌های حساس هستند که فقط برنامه شما می‌تواند به آنها دسترسی داشته باشد.

دایرکتوری‌های ذخیره‌سازی خارجی

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

در اندروید ۴.۴ (سطح API ۱۹) یا بالاتر، برنامه شما برای دسترسی به دایرکتوری‌های مخصوص برنامه در حافظه خارجی، نیازی به درخواست مجوزهای مربوط به حافظه ندارد.

وقتی کاربر برنامه شما را حذف نصب می‌کند، فایل‌های ذخیره شده در فضای ذخیره‌سازی مخصوص برنامه نیز حذف می‌شوند و از این رو، شما نباید از این فضای ذخیره‌سازی برای ذخیره هر چیزی که کاربر انتظار دارد مستقل از برنامه شما باقی بماند، استفاده کنید.

انصراف موقت از ذخیره‌سازی محدود

قبل از اینکه برنامه شما کاملاً با فضای ذخیره‌سازی محدود سازگار شود، می‌توانید به طور موقت، چه در آزمایش‌ها و چه در برنامه اصلی خود، از این قابلیت انصراف دهید.

در آزمون‌های خود انصراف دهید

در اندروید ۱۰ (سطح API 29) و بالاتر، تست‌های برنامه شما به طور پیش‌فرض در یک فضای ذخیره‌سازی (storage sandbox) اجرا می‌شوند. این فضای ذخیره‌سازی مانع از دسترسی برنامه شما به فایل‌های خارج از دایرکتوری مخصوص برنامه و دایرکتوری‌های عمومی می‌شود.

اگر یک تست، فایل‌هایی را برای میزبان خروجی می‌دهد - مانند اسکرین‌شات‌ها، داده‌های اشکال‌زدایی، داده‌های پوشش یا معیارهای عملکرد - می‌توانید این فایل‌ها را در دایرکتوری‌های سراسری بنویسید. برای انجام این کار، پرچم زیر را به مهار مربوطه که am instrument فراخوانی می‌کند، اضافه کنید:

-e no-isolated-storage 1

این پرچم بر تمام رفتارهای مورد آزمایشیِ ابزار دقیق تأثیر می‌گذارد و بر تمام کدهای آزمایشی فراخوانی شده نیز تأثیر می‌گذارد. بنابراین، وقتی از این پرچم استفاده می‌کنید، نمی‌توانید سازگاری برنامه خود را با فضای ذخیره‌سازیِ محدود شده تأیید کنید. برای خروجی آزمایشی، بهتر است در فضای ذخیره‌سازیِ محدود شده به برنامه که توسط پوسته قابل خواندن است، بنویسید. سپس می‌توانید آن دایرکتوریِ محدود شده به برنامه را دریافت کنید. برای تعیین اینکه از کدام دایرکتوری باید دریافت کنید، تابع getExternalMediaDirs() را فراخوانی کنید.

در برنامه تولیدی خود انصراف دهید

اگر برنامه شما برای اندروید ۱۰ (سطح API 29) یا پایین‌تر طراحی شده است، می‌توانید موقتاً از ذخیره‌سازی محدود در برنامه اصلی خود صرف نظر کنید. با این حال، اگر برای اندروید ۱۰ طراحی شده است، باید مقدار requestLegacyExternalStorage را در فایل مانیفست برنامه خود روی true تنظیم کنید:

<manifest ... >
  <!-- This attribute is "false" by default on apps targeting
       Android 10. -->
  <application android:requestLegacyExternalStorage="true" ... >
    ...
  </application>
</manifest>

برای آزمایش نحوه رفتار یک برنامه با اندروید ۱۰ یا پایین‌تر هنگام استفاده از فضای ذخیره‌سازی محدود، می‌توانید با تنظیم مقدار requestLegacyExternalStorage به false ، این رفتار را انتخاب کنید. اگر در حال آزمایش روی دستگاهی هستید که اندروید ۱۱ را اجرا می‌کند، می‌توانید از پرچم‌های سازگاری برنامه نیز برای آزمایش رفتار برنامه خود با یا بدون فضای ذخیره‌سازی محدود استفاده کنید .

منابع اضافی

برای اطلاعات بیشتر در مورد فضای ذخیره‌سازی اندروید، مطالب زیر را مشاهده کنید:

پست‌های وبلاگ

• ارائه فضای ذخیره‌سازی مدرن برای کاربران وایبر