Android 10, kullanıcılara dosyaları üzerinde daha fazla kontrol imkanı sunmak ve dosya karmaşasını azaltmak için uygulamalara yönelik kapsamlı depolama adlı yeni bir depolama paradigması sunuyor. Kapsamlı depolama, uygulamaların bir cihazın harici depolama alanındaki dosyaları depolama ve bu dosyalara erişme şeklini değiştirir. Uygulamanızı kapsamlı depolamayı destekleyecek şekilde taşımanıza yardımcı olmak için bu kılavuzda açıklanan, yaygın depolama alanı kullanım alanlarına yönelik en iyi uygulamaları takip edin. Kullanım alanları iki kategoride düzenlenir: medya dosyalarını işleme ve medya dışı dosyaları işleme.
Çoğu durumda uygulamanız, diğer uygulamaların erişmesi gerekmeyen veya erişmemesi gereken dosyalar oluşturur. Sistem, bu tür dosyaları yönetmek için uygulamaya özel depolama konumları sağlar.
Android'de dosyaları depolama ve dosyalara erişme hakkında daha fazla bilgi edinmek için depolama alanı eğitim kılavuzlarına göz atın.
Medya dosyalarını işleme
Bu bölümde, medya dosyalarını (video, resim ve ses dosyaları) işleme ile ilgili bazı yaygın kullanım alanları açıklanmakta ve uygulamanızın kullanabileceği üst düzey yaklaşım anlatılmaktadır. Aşağıdaki tabloda bu kullanım alanlarının her biri özetlenmiş ve daha fazla ayrıntı içeren bölümlere bağlantılar verilmiştir.
Kullanım alanına | Özet |
---|---|
Tüm resim veya video dosyalarını göster | Android'in tüm sürümlerinde aynı yaklaşımı kullanın. |
Belirli bir klasördeki resimleri veya videoları gösterme | Android'in tüm sürümlerinde aynı yaklaşımı kullanın. |
Fotoğraflardaki konum bilgilerine erişme | Uygulamanız kısıtlı depolama kullanıyorsa bir yaklaşım kullanın. Uygulamanız kısıtlı depolamayı devre dışı bırakıyorsa farklı bir yaklaşım kullanın. |
Yeni indirmeler için depolama konumunu tanımlama | Uygulamanız kısıtlı depolama kullanıyorsa bir yaklaşım kullanın. Uygulamanız kısıtlı depolamayı devre dışı bırakıyorsa farklı bir yaklaşım kullanın. |
Kullanıcı medya dosyalarını cihaza aktarma | Android'in tüm sürümlerinde aynı yaklaşımı kullanın. |
Tek bir işlemde birden fazla medya dosyasını değiştirme veya silme | Android 11 için tek bir yaklaşım kullanın. Android 10'da kapsamlı depolama alanını devre dışı bırakın ve bunun yerine Android 9 ile önceki sürümlerdeki yaklaşımı kullanın. |
Zaten var olan tek bir resmi içe aktarma | Android'in tüm sürümlerinde aynı yaklaşımı kullanın. |
Tek bir görüntü yakalama | Android'in tüm sürümlerinde aynı yaklaşımı kullanın. |
Medya dosyalarını diğer uygulamalarla paylaşma | Android'in tüm sürümlerinde aynı yaklaşımı kullanın. |
Medya dosyalarını belirli bir uygulamayla paylaşma | Android'in tüm sürümlerinde aynı yaklaşımı kullanın. |
Doğrudan dosya yollarını kullanan kod veya kitaplıklardan dosyalara erişme | Android 11 için tek bir yaklaşım kullanın. Android 10'da kapsamlı depolama alanını devre dışı bırakın ve bunun yerine Android 9 ile önceki sürümlerde kullanılan yaklaşımı uygulayın. |
Birden fazla klasördeki resim veya video dosyalarını gösterme
query()
API'sini kullanarak medya koleksiyonu sorgulama. Medya dosyalarını filtrelemek veya sıralamak için projection
, selection
, selectionArgs
ve sortOrder
parametrelerini ayarlayın.
Belirli bir klasördeki resimleri veya videoları gösterme
Bu yaklaşımı kullanın:
- Uygulama İzinleri İste bölümünde belirtilen en iyi uygulamalara uyarak
READ_EXTERNAL_STORAGE
iznini isteyin. - Disk üzerindeki medya öğesinin mutlak dosya sistemi yolunu içeren
MediaColumns.DATA
değerine göre medya dosyalarını alın.
Not: Mevcut bir medya dosyasına eriştiğinizde mantığınızda DATA
sütununun değerini kullanabilirsiniz. Bunun nedeni, bu değerin geçerli bir dosya yoluna sahip olmasıdır.
Ancak dosyanın her zaman kullanılabileceğini varsaymayın. Oluşabilecek dosya tabanlı G/Ç hatalarını işlemeye hazır olun.
Öte yandan, medya dosyası oluşturmak veya güncellemek için DATA
sütununu kullanmayın. Bunun yerine DISPLAY_NAME
ve RELATIVE_PATH
sütunlarını kullanın.
Fotoğraflardaki konum bilgilerine erişme
Uygulamanız kapsamlı depolama kullanıyorsa medya depolama kılavuzunun Fotoğraflardaki konum bilgileri bölümündeki adımları uygulayın.
Yeni indirmeler için depolama konumunu tanımlama
Uygulamanız kapsamlı depolama kullanıyorsa indirdiğiniz medya dosyalarını depolamak için seçtiğiniz konuma dikkat edin.
Diğer uygulamaların dosyalara erişmesi gerekiyorsa indirme işlemleri veya doküman koleksiyonları için iyi tanımlanmış medya koleksiyonlarını kullanabilirsiniz.
Android 11 ve sonraki sürümlerde, harici uygulamaya özel dizininizdeki dosyalar, bu dosyaları getirmek için DownloadManager
kullansanız bile diğer uygulamalar tarafından erişilemez.
Kullanıcı medya dosyalarını cihaza aktarma
Kullanıcı medya dosyalarını depolamak için uygun bir varsayılan konum tanımlayın:
- Kullanıcıların, uygulamaya özel depolama alanı veya paylaşılan depolama alanı kullanarak medya dosyalarını diğer uygulamalar tarafından okunabilir hale getirip getirmeyeceklerini seçmelerine izin verin.
- Kullanıcıların, dosyaları uygulamaya özel dizinlerden daha genel olarak erişilebilen bir konuma aktarmasına izin verin. Medya dosyalarını cihazın galerisine aktarmak için MediaStore'un resim, video ve ses koleksiyonlarını kullanın.
Tek bir işlemde birden fazla medya dosyasını değiştirme veya silme
Uygulamanızın çalıştığı Android sürümlerine göre mantık ekleyin.
Android 11'de çalışıyor
Bu yaklaşımı kullanın:
MediaStore.createWriteRequest()
veyaMediaStore.createTrashRequest()
kullanarak uygulamanızın yazma veya silme isteği için bekleyen bir amaç oluşturun. Ardından, bu amacı çağırarak kullanıcıdan bir dizi dosyayı düzenleme izni isteyin.Kullanıcının yanıtını değerlendirin:
- İzin verildiyse değiştirme veya silme işlemine devam edin.
- İzin verilmediyse uygulamanızdaki özelliğin neden bu izne ihtiyacı olduğunu kullanıcıya açıklayın.
Android 11 ve sonraki sürümlerde kullanılabilen bu yöntemleri kullanarak medya dosyası gruplarını yönetme hakkında daha fazla bilgi edinin.
Android 10'da çalışıyorsa
Uygulamanız Android 10'u (API düzeyi 29) hedefliyorsa kapsamlı depolama alanını devre dışı bırakın ve bu işlemi gerçekleştirmek için Android 9 ve önceki sürümlerdeki yaklaşımı kullanmaya devam edin.
Android 9 veya önceki bir sürümü çalıştırıyorsanız
Bu yaklaşımı kullanın:
- Uygulama İzinleri İste bölümünde belirtilen en iyi uygulamalara uyarak
WRITE_EXTERNAL_STORAGE
iznini isteyin. - Medya dosyalarını değiştirmek veya silmek için
MediaStore
API'yi kullanın.
Zaten var olan tek bir resmi içe aktarma
Halihazırda var olan tek bir resmi içe aktarmak istediğinizde (örneğin, kullanıcının profil fotoğrafı olarak kullanmak için) uygulamanız bu işlem için kendi kullanıcı arayüzünü veya sistem seçiciyi kullanabilir.
Kendi kullanıcı arayüzünüzü sunma
Bu yaklaşımı kullanın:
- Uygulama İzinleri İste bölümünde belirtilen en iyi uygulamalara uyarak
READ_EXTERNAL_STORAGE
iznini isteyin. query()
API'yi kullanarak medya koleksiyonuna sorgu gönderme- Sonuçları uygulamanızın özel kullanıcı arayüzünde gösterin.
Sistem seçiciyi kullanma
Kullanıcıdan içe aktarılacak bir resim seçmesini isteyen ACTION_GET_CONTENT
amacını kullanın.
Sistem seçicinin kullanıcıya seçim yapması için sunduğu resim türlerini filtrelemek istiyorsanız setType()
veya EXTRA_MIME_TYPES
kullanabilirsiniz.
Tek bir görüntü yakalama
Uygulamanızda kullanmak üzere tek bir resim çekmek istediğinizde (örneğin, kullanıcının profil fotoğrafı olarak kullanmak için) ACTION_IMAGE_CAPTURE
amacını kullanarak kullanıcıdan cihazın kamerasını kullanarak fotoğraf çekmesini isteyin. Sistem, çekilen fotoğrafı MediaStore.Images
tablosunda saklar.
Medya dosyalarını diğer uygulamalarla paylaşma
Kayıtları doğrudan MediaStore'a eklemek için
insert()
yöntemini kullanın. Daha fazla bilgi için medya depolama kılavuzunun Öğe ekleme bölümüne bakın.
Medya dosyalarını belirli bir uygulamayla paylaşma
Dosya paylaşımını ayarlama kılavuzunda açıklandığı gibi Android FileProvider
bileşenini kullanın.
Doğrudan dosya yollarını kullanan kod veya kitaplıklardaki dosyalara erişme
Uygulamanızın çalıştığı Android sürümlerine göre mantık ekleyin.
Android 11'de çalışıyor
Bu yaklaşımı kullanın:
- Uygulama İzinleri İste bölümünde belirtilen en iyi uygulamalara uyarak
READ_EXTERNAL_STORAGE
iznini isteyin. - Doğrudan dosya yollarını kullanarak dosyalara erişin.
Daha fazla bilgi için doğrudan dosya yollarını kullanarak medya dosyalarını açma bölümüne bakın.
Android 10'da çalışıyorsa
Uygulamanız Android 10'u (API düzeyi 29) hedefliyorsa kapsamlı depolama alanını devre dışı bırakın ve bu işlemi gerçekleştirmek için Android 9 ve önceki sürümlerdeki yaklaşımı kullanmaya devam edin.
Android 9 veya önceki bir sürümü çalıştırıyorsanız
Bu yaklaşımı kullanın:
- Uygulama İzinleri İste bölümünde belirtilen en iyi uygulamalara uyarak
WRITE_EXTERNAL_STORAGE
iznini isteyin. - Doğrudan dosya yollarını kullanarak dosyalara erişin.
Medya harici dosyaları işleme
Bu bölümde, medya dışı dosyaların işlenmesiyle ilgili bazı yaygın kullanım alanları açıklanmakta ve uygulamanızın kullanabileceği üst düzey yaklaşım anlatılmaktadır. Aşağıdaki tabloda bu kullanım alanlarının her biri özetlenmiş ve daha fazla ayrıntı içeren bölümlere bağlantılar verilmiştir.
Kullanım alanına | Özet |
---|---|
Doküman dosyası açma | Android'in tüm sürümlerinde aynı yaklaşımı kullanın. |
İkincil depolama birimlerindeki dosyalara yazma | Android 11 için tek bir yaklaşım kullanın. Android'in önceki sürümlerinde farklı bir yaklaşım kullanın. |
Mevcut dosyaları eski bir depolama konumundan taşıma | Mümkün olduğunda dosyalarınızı kapsamlı depolamaya taşıyın. Gerekirse Android 10'da kapsamlı depolamayı devre dışı bırakın. |
Diğer uygulamalarla içerik paylaşma | Android'in tüm sürümlerinde aynı yaklaşımı kullanın. |
Medya dışı dosyaları önbelleğe alma | Android'in tüm sürümlerinde aynı yaklaşımı kullanın. |
Medya dışı dosyaları bir cihaza aktarma | Uygulamanız kısıtlı depolama kullanıyorsa bir yaklaşım kullanın. Uygulamanız kısıtlı depolamayı devre dışı bırakıyorsa farklı bir yaklaşım kullanın. |
Doküman dosyası açma
Kullanıcıdan sistem seçiciyi kullanarak açılacak bir dosya seçmesini istemek için ACTION_OPEN_DOCUMENT
amacını kullanın. Sistem seçicinin kullanıcıya seçmesi için sunacağı dosya türlerini filtrelemek istiyorsanız setType()
veya EXTRA_MIME_TYPES
kullanabilirsiniz.
Örneğin, aşağıdaki kodu kullanarak tüm PDF, ODT ve TXT dosyalarını bulabilirsiniz:
Kotlin
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 )
Java
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);
İkincil depolama birimlerindeki dosyalara yazma
İkincil depolama birimleri arasında SD kartlar bulunur. StorageVolume
sınıfını kullanarak belirli bir depolama birimiyle ilgili bilgilere erişebilirsiniz.
Uygulamanızın üzerinde çalıştığı Android sürümüne göre mantık ekleyin.
Android 11'de çalıştırılan cihazlar
Bu yaklaşımı kullanın:
- Kapsamlı depolama alanı modelini kullanın.
- Android 10 (API düzeyi 29) veya önceki sürümleri hedefleyin.
WRITE_EXTERNAL_STORAGE
iznini beyan edin.- Aşağıdaki erişim türlerinden birini gerçekleştirin:
MediaStore
API'yi kullanarak dosya erişimi.File
veyafopen()
gibi API'ler kullanılarak doğrudan dosya yolu erişimi.
Eski sürümlerde çalıştırma
Kullanıcıların, uygulamanızın dosyayı yazabileceği ikincil depolama birimindeki konumu seçmesine olanak tanıyan depolama alanı erişim çerçevesini kullanın.
Mevcut dosyaları eski bir depolama konumundan taşıma
Bir dizin, uygulamaya özel bir dizin veya herkese açık bir paylaşılan dizin değilse eski depolama konumu olarak kabul edilir. Uygulamanız eski bir depolama konumunda dosya oluşturuyor veya kullanıyorsa uygulamanızın dosyalarını kapsamlı depolama ile erişilebilen konumlara taşımanızı ve kapsamlı depolamadaki dosyalarla çalışmak için gerekli uygulama değişikliklerini yapmanızı öneririz.
Veri taşıma için eski depolama konumuna erişimi sürdürme
Uygulama dosyalarını kapsamlı depolama alanı ile erişilebilen konumlara taşımak için uygulamanızın eski depolama konumuna erişimi sürdürmesi gerekir. Kullanmanız gereken yaklaşım, uygulamanızın hedef API düzeyine bağlıdır.
Uygulamanız Android 11'i hedefliyorsa
Uygulamanızın, Android 11'i hedefleyen yeni sürümüne yükselten kullanıcıların verilerini taşıyabilmesi için eski depolama modelini korumak üzere
preserveLegacyExternalStorage
işaretinitrue
olarak ayarlayın.Uygulamanızın Android 10 cihazlarda eski depolama konumundaki dosyalarınıza erişmeye devam edebilmesi için kapsamlı depolamayı devre dışı bırakmaya devam edin.
Uygulamanız Android 10'u hedefliyorsa
Kapsamlı depolama özelliğini devre dışı bırakarak uygulamanızın davranışını Android sürümlerinde daha kolay koruyabilirsiniz.
Uygulama verilerini taşıma
Uygulamanız taşınmaya hazır olduğunda aşağıdaki yaklaşımı kullanın:
- Android 10 veya önceki sürümleri hedefleyin.
- Uygulamanızın taşımanız gereken dosyalara erişebilmesi için kapsamlı depolama alanını devre dışı bırakın.
-
Dosyaları
File
API'yi kullanarak/sdcard/
altındaki mevcut konumlarından kapsamlı depolama ile erişilebilen bir konuma taşımak için kod dağıtın:- Gizli uygulama dosyalarını,
getExternalFilesDir()
yöntemi tarafından döndürülen dizine taşıyın. - Paylaşılan medya dışı dosyaları
Downloads/
dizininin uygulamaya özel bir alt dizinine taşıma
- Gizli uygulama dosyalarını,
- Uygulamanızın eski depolama dizinlerini
/sdcard/
dizininden kaldırın.
Kullanıcılar uygulamanızın yeni sürümünü yükledikten sonra cihazlarında veri taşıma işlemini tamamlar. Bir analiz etkinliği oluşturarak kullanıcı tabanınızdaki taşıma sürecini izleyebilirsiniz.
Kullanıcılar verilerini taşıdıktan sonra uygulamanızda Android 11'i hedefleyen başka bir güncelleme yayınlayın.
Diğer uygulamalarla içerik paylaşma
Uygulamanızın dosyalarını tek bir uygulamayla paylaşmak için bir
FileProvider
kullanın. Birbirleriyle dosya paylaşması gereken uygulamalar için her uygulamada içerik sağlayıcı kullanmanızı ve ardından uygulamalar koleksiyona eklendikçe verileri senkronize etmenizi öneririz.
Medya dışı dosyaları önbelleğe alma
Kullanmanız gereken yaklaşım, önbelleğe almanız gereken dosya türlerine bağlıdır.
- Küçük dosyalar veya hassas bilgiler içeren dosyalar:
Context#getCacheDir()
simgesini kullanın. - Büyük dosyalar veya hassas bilgi içermeyen dosyalar:
Context#getExternalCacheDir()
simgesini kullanın.
Medya harici dosyaları cihaza aktarma
Medya dışı dosyaların depolanacağı uygun bir varsayılan konum tanımlayın. Kullanıcıların, dosyaları uygulamaya özel dizinlerden daha genel olarak erişilebilen bir konuma aktarmasına izin verin. Medya dışı dosyaları cihaza aktarmak için MediaStore'un indirme veya doküman koleksiyonlarını kullanın.
Uygulamaya Özel Dosyaları İşleme
Uygulamanızın, diğer uygulamaların erişmesine gerek olmayan veya erişmemesi gereken dosyalar oluşturması durumunda bu dosyaları uygulamaya özel depolama konumlarında saklayabilirsiniz.
Dahili depolama dizinleri
Sistem, diğer uygulamaların bu konumlara erişmesini engeller ve Android 10 (API düzeyi 29) ve sonraki sürümlerde bu konumlar şifrelenir. Bu konumlar, yalnızca uygulamanızın erişebileceği hassas verileri depolamak için uygundur.
Harici depolama dizinleri
Dahili depolama alanı, uygulamaya özel dosyaları depolamak için yeterli alan sağlamıyorsa bunun yerine harici depolama alanını kullanabilirsiniz. Başka bir uygulamanın uygun izinlere sahip olması durumunda bu dizinlere erişmesi mümkün olsa da bu dizinlerde depolanan dosyalar yalnızca uygulamanız tarafından kullanılmak üzere tasarlanmıştır.
Android 4.4 (API düzeyi 19) veya sonraki sürümlerde, uygulamanızın harici depolama alanındaki uygulamaya özel dizinlere erişmek için depolamayla ilgili herhangi bir izin istemesi gerekmez.
Kullanıcı uygulamanızın yüklemesini kaldırdığında uygulamaya özel depolama alanına kaydedilen dosyalar kaldırılır. Bu nedenle, kullanıcının uygulamanızdan bağımsız olarak kalıcı olmasını beklediği hiçbir şeyi kaydetmek için bu depolama alanını kullanmamalısınız.
Kapsamlı depolamayı geçici olarak devre dışı bırakma
Uygulamanız kapsamlı depolama ile tam olarak uyumlu hale gelmeden önce hem testlerinizde hem de üretim uygulamanızda kapsamlı depolamayı geçici olarak devre dışı bırakabilirsiniz.
Testlerinizde devre dışı bırakma
Android 10 (API düzeyi 29) ve sonraki sürümlerde uygulamanızın testleri varsayılan olarak depolama alanında sandbox'ta çalışır. Bu sanal alan, uygulamanızın uygulamaya özel dizin ve herkese açık olarak paylaşılan dizinler dışındaki dosyalara erişmesini engeller.
Bir test, ana makine için ekran görüntüleri, hata ayıklama verileri, kapsam verileri veya performans metrikleri gibi dosyalar oluşturuyorsa bu dosyaları genel dizinlere yazabilirsiniz. Bunu yapmak için am instrument
işlevini çağıran ilgili koşuma aşağıdaki işareti ekleyin:
-e no-isolated-storage 1
Bu işaret, enstrümanlı test senaryosunun tüm davranışlarını ve çağrılan tüm test kodlarını etkiler. Bu nedenle, bu işareti kullandığınızda uygulamanızın kapsamlı depolama ile uyumluluğunu doğrulayamazsınız. Test çıkışı için bunun yerine kabuk tarafından okunabilen uygulama kapsamlı depolama alanına yazmak daha iyidir. Ardından, bu uygulama kapsamlı dizini çekebilirsiniz. Hangi dizinden çekileceğini belirlemek için getExternalMediaDirs()
işlevini çağırın.
Üretim uygulamanızda kapsam dışında kalma
Uygulamanız Android 10'u (API düzeyi 29) veya daha eski bir sürümü hedefliyorsa üretim uygulamanızda kapsamlı depolama alanını geçici olarak devre dışı bırakabilirsiniz. Ancak Android 10'u hedefliyorsanız uygulamanızın manifest dosyasında requestLegacyExternalStorage
değerini true
olarak ayarlamanız gerekir:
<manifest ... > <!-- This attribute is "false" by default on apps targeting Android 10. --> <application android:requestLegacyExternalStorage="true" ... > ... </application> </manifest>
Kapsamlı depolama alanını kullanan Android 10 veya daha eski sürümleri hedefleyen bir uygulamanın nasıl davrandığını test etmek için requestLegacyExternalStorage
değerini false
olarak ayarlayarak bu davranışı etkinleştirebilirsiniz. Android 11'in yüklü olduğu bir cihazda test yapıyorsanız uygulamanızın kapsamlı depolama alanı ile veya kapsamlı depolama alanı olmadan davranışını test etmek için uygulama uyumluluğu işaretlerini de kullanabilirsiniz.
Ek kaynaklar
Android depolama alanı hakkında daha fazla bilgi için aşağıdaki materyallere göz atın: