Depolama Erişim Çerçevesi'ni kullanarak dosya açma

Android 4.4 (API düzeyi 19), Depolama Aksesuarı Çerçevesi'ni (SAF) kullanıma sunar. SAF, kullanıcıların tercih ettikleri tüm doküman depolama alanı sağlayıcılardaki dokümanlara, resimlere ve diğer dosyalara göz atmasına ve bunları açmalarına olanak tanır. Standart ve kullanımı kolay bir kullanıcı arayüzü, kullanıcıların uygulamalar ve sağlayıcılar arasında tutarlı bir şekilde dosyalara göz atmasına ve son dosyalara erişmesine olanak tanır.

Bulut veya yerel depolama hizmetleri, hizmetlerini kapsayan bir DocumentsProvider uygulayarak bu ekosisteme katılabilir. Bir sağlayıcının dokümanlarına erişmesi gereken istemci uygulamaları, birkaç kod satırı ile SAF ile entegre edilebilir.

SAF şunları içerir:

  • Doküman sağlayıcı: Google Drive gibi bir depolama hizmetinin, yönettiği dosyaları göstermesine olanak tanıyan bir içerik sağlayıcı. Belge sağlayıcı, DocumentsProvider sınıfının alt sınıfı olarak uygulanır. Belge sağlayıcı şeması geleneksel bir dosya hiyerarşisini temel alır ancak belge sağlayıcınızın verileri fiziksel olarak nasıl depoladığını belirleme hakkı size aittir. Android platformunda İndirilenler, Resimler ve Videolar gibi çeşitli yerleşik doküman sağlayıcılar bulunur.
  • İstemci uygulaması: ACTION_CREATE_DOCUMENT, ACTION_OPEN_DOCUMENT ve ACTION_OPEN_DOCUMENT_TREE istem işlemlerini çağıran ve belge sağlayıcılar tarafından döndürülen dosyaları alan özel bir uygulamadır.
  • Seçici: Kullanıcıların, istemci uygulamasının arama ölçütlerini karşılayan tüm doküman sağlayıcılardaki dokümanlara erişmesine olanak tanıyan bir sistem kullanıcı arayüzü.

SAF aşağıdaki özellikleri sunar:

  • Kullanıcıların yalnızca tek bir uygulamadan değil, tüm doküman sağlayıcılardaki içeriklere göz atmasına olanak tanır.
  • Uygulamanızın, bir doküman sağlayıcıya ait dokümanlara uzun süreli ve kalıcı erişmesine olanak tanır. Bu erişim sayesinde kullanıcılar sağlayıcıda dosya ekleyebilir, düzenleyebilir, kaydedebilir ve silebilir.
  • Birden fazla kullanıcı hesabını ve yalnızca sürücü takılıyken görünen USB depolama alanı sağlayıcıları gibi geçici kökleri destekler.

Genel Bakış

SAF, DocumentsProvider sınıfının alt sınıfı olan bir içerik sağlayıcıyı temel alır. Belge sağlayıcıda veriler geleneksel dosya hiyerarşisi olarak yapılandırılır:

Şekil 1. Doküman sağlayıcı veri modeli. Kök, tek bir dokümanı işaret eder ve ardından ağacın genişlemesini başlatır.

Aşağıdakileri göz önünde bulundurun:

  • Her doküman sağlayıcı, bir veya daha fazla kök bildirir. Bunlar, doküman ağacını keşfetmeye yönelik başlangıç noktalarıdır. Her kökün benzersiz bir COLUMN_ROOT_ID öğesi vardır ve bu öğe, söz konusu kökün altındaki içerikleri temsil eden bir dokümanı (dizin) işaret eder. Kökler, birden fazla hesap, geçici USB depolama cihazları veya kullanıcı girişi ve çıkışı gibi kullanım alanlarını desteklemek için tasarım gereği dinamiktir.
  • Her kökün altında tek bir doküman bulunur. Bu doküman, 1 ila N dokümanı işaret eder. Bu dokümanların her biri de 1 ila N dokümanı işaret edebilir.
  • Her depolama arka ucu, benzersiz bir COLUMN_DOCUMENT_ID ile referans vererek ayrı dosyaları ve dizinleri gösterir. Doküman kimlikleri benzersizdir ve cihaz yeniden başlatılırken kalıcı URI izinleri için kullanıldığından, yayınlandıktan sonra değişmez.
  • Dokümanlar, belirli bir MIME türüne sahip açılabilir bir dosya veya MIME_TYPE_DIR MIME türüne sahip ek dokümanlar içeren bir dizin olabilir.
  • Her dokümanın, COLUMN_FLAGS tarafından açıklandığı gibi farklı özellikleri olabilir. Örneğin, FLAG_SUPPORTS_WRITE, FLAG_SUPPORTS_DELETE ve FLAG_SUPPORTS_THUMBNAIL. Aynı COLUMN_DOCUMENT_ID birden fazla dizine dahil edilebilir.

Kontrol akışı

Belge sağlayıcı veri modeli, geleneksel bir dosya hiyerarşisini temel alır. Ancak, DocumentsProviderAPI'yi kullanarak erişebildiğiniz sürece verilerinizi fiziksel olarak istediğiniz şekilde saklayabilirsiniz. Örneğin, verileriniz için etiket tabanlı bulut depolama alanı kullanabilirsiniz.

Şekil 2'de, bir fotoğraf uygulamasının depolanan verilere erişmek için SAF'ı nasıl kullanabileceği gösterilmektedir:

Şekil 2. Depolama Erişim Çerçevesi akışı.

Aşağıdakileri göz önünde bulundurun:

  • SAF'ta sağlayıcılar ve istemciler doğrudan etkileşime girmez. Müşteri, dosyalarla etkileşim kurmak için izin ister. Bu, dosya okuma, düzenleme, oluşturma veya silme anlamına gelir.
  • Etkileşim, bir uygulama (bu örnekte fotoğraf uygulaması) ACTION_OPEN_DOCUMENT veya ACTION_CREATE_DOCUMENT intent'ini tetiklediğinde başlar. Intent, ölçütleri daha da hassaslaştırmak için filtreler içerebilir. Örneğin, ""image" MIME türüne sahip tüm açılabilir dosyaları göster".
  • Intent tetiklendiğinde sistem seçici, kayıtlı her sağlayıcıya gider ve kullanıcıya eşleşen içerik köklerini gösterir.
  • Seçici, temel doküman sağlayıcılar çok farklı olsa bile kullanıcılara dokümanlara erişmek için standart bir arayüz sunar. Örneğin, 2. şekil bir Google Drive sağlayıcısı, USB sağlayıcısı ve bulut sağlayıcısı göstermektedir.

Şekil 3'te kullanıcı, resim araması sırasında açılan bir seçiciden İndirilenler klasörünü seçiyor. Seçici, istemci uygulamasının kullanabileceği tüm kökleri de gösterir.

Sistem seçicide klasör seçimi.
Şekil 3. Arama konumu olarak İndirilenler klasörünün seçildiğini gösteren seçici.

Kullanıcı İndirilenler klasörünü seçtikten sonra resimler gösterilir. Şekil 4'te bu işlemin sonucu gösterilmektedir. Kullanıcı artık sağlayıcı ve istemci uygulamasının desteklediği şekillerde resimlerle etkileşime geçebilir.

Şekil 4. Sistem seçicide gösterildiği şekilde, İndirilenler klasöründe depolanan resimler.

İstemci uygulaması yazma

Android 4.3 ve önceki sürümlerde, uygulamanızın başka bir uygulamadan dosya almasını istiyorsanız ACTION_PICK veya ACTION_GET_CONTENT gibi bir intent çağırması gerekir. Ardından kullanıcı, dosya seçeceği tek bir uygulama belirler. Seçilen uygulama, kullanıcının mevcut dosyalara göz atıp seçim yapması için bir kullanıcı arayüzü sağlamalıdır.

Android 4.4 (API düzeyi 19) ve sonraki sürümlerde, kullanıcının diğer uygulamaların kullanıma sunduğu tüm dosyalara göz atmasına olanak tanıyan sistem kontrollü bir seçici kullanıcı arayüzü gösteren ACTION_OPEN_DOCUMENT intent'ini kullanma seçeneğiniz de vardır. Kullanıcı, bu tek kullanıcı arayüzünden desteklenen uygulamalardan herhangi birinde bir dosya seçebilir.

Android 5.0 (API düzeyi 21) ve sonraki sürümlerde, kullanıcının istemci uygulamasının erişeceği bir dizin seçmesine olanak tanıyan ACTION_OPEN_DOCUMENT_TREE intent'i de kullanabilirsiniz.

Not: ACTION_OPEN_DOCUMENT, ACTION_GET_CONTENT'in yerini almaz. Kullanacağınız yöntem, uygulamanızın ihtiyaçlarına bağlıdır:

  • Uygulamanızın veri okumasını veya içe aktarmasını istiyorsanız ACTION_GET_CONTENT seçeneğini kullanın. Bu yaklaşımda uygulama, verilerin bir kopyasını (ör. resim dosyası) içe aktarır.
  • Uygulamanızın bir doküman sağlayıcıya ait dokümanlara uzun süreli ve kalıcı erişimi olmasını istiyorsanız ACTION_OPEN_DOCUMENT değerini kullanın. Örneğin, kullanıcıların bir doküman sağlayıcıda depolanan resimleri düzenlemesine olanak tanıyan bir fotoğraf düzenleme uygulaması.

Sistem seçici kullanıcı arayüzünü kullanarak dosya ve dizinlere göz atma özelliğini destekleme hakkında daha fazla bilgi için belgelere ve diğer dosyalara erişme başlıklı kılavuzu inceleyin.

Ek kaynaklar

Belge sağlayıcılar hakkında daha fazla bilgi için aşağıdaki kaynaklardan yararlanabilirsiniz:

Örnekler

Videolar

Önceki
İçerik sağlayıcı oluşturma
Sonraki
Özel doküman sağlayıcı oluşturma