Zengin içerik alma

Kullanıcılar resimleri, videoları ve diğer etkileyici içerikleri sever ancak bu içerikleri uygulamalara eklemek ve taşımak her zaman kolay değildir. Uygulamaların zengin içerik almasını kolaylaştırmak için Android 12 (API düzeyi 31), uygulamanızın herhangi bir kaynaktan (ör. pano, klavye veya sürükleme) içerik kabul etmesine olanak tanıyan birleşik bir API sunar.

Kullanıcı arayüzü bileşenlerine OnReceiveContentListener gibi bir arayüz ekleyebilir ve herhangi bir mekanizma aracılığıyla içerik eklendiğinde geri çağırma alabilirsiniz. Geri çağırma, kodunuzun düz ve stilli metinden işaretlemeye, resimlere, videolara, ses dosyalarına ve diğer içeriklere kadar tüm içerikleri almasını sağlayan tek yer haline gelir.

Önceki Android sürümleriyle geriye dönük uyumluluk için bu API, Core 1.7 ve Appcompat 1.4'ten itibaren AndroidX'te de kullanılabilir. Bu işlevi uygularken bu sürümleri kullanmanızı öneririz.

Genel Bakış

Mevcut diğer API'lerde, dokunup basılı tutma menüsü veya sürükleme gibi her kullanıcı arayüzü mekanizmasının kendi API'si vardır. Bu, her API ile ayrı ayrı entegrasyon yapmanız ve içerik ekleyen her mekanizma için benzer kodlar eklemeniz gerektiği anlamına gelir:

OnReceiveContentListener API'si, uygulanacak tek bir API oluşturarak bu farklı kod yollarını birleştirir. Böylece, uygulamaya özel mantığınıza odaklanabilir ve geri kalanını platformun halletmesine izin verebilirsiniz:

Bu yaklaşım, platforma yeni içerik ekleme yöntemleri eklendiğinde uygulamanızda desteği etkinleştirmek için ek kod değişiklikleri yapmanız gerekmediği anlamına da gelir. Uygulamanızın belirli bir kullanım alanı için tam özelleştirme uygulaması gerekiyorsa aynı şekilde çalışmaya devam eden mevcut API'leri kullanabilirsiniz.

Uygulama

API, tek bir yöntemi olan bir dinleyici arayüzüdür: OnReceiveContentListener. Android platformunun eski sürümlerini desteklemek için AndroidX Core kitaplığındaki eşleşen OnReceiveContentListener arayüzünü kullanmanızı öneririz.

API'yi kullanmak için uygulamanızın işleyebileceği içerik türlerini belirterek dinleyiciyi uygulayın:

object MyReceiver : OnReceiveContentListener {
    val MIME_TYPES = arrayOf("image/*", "video/*")
    
    // ...
    
    override fun onReceiveContent(view: View, payload: ContentInfoCompat): ContentInfoCompat? {
        TODO("Not yet implemented")
    }
}

public class MyReceiver implements OnReceiveContentListener {
     public static final String[] MIME_TYPES = new String[] {"image/*", "video/*"};
     // ...
}

Uygulamanızın desteklediği tüm içerik MIME türlerini belirttikten sonra dinleyicinin geri kalanını uygulayın:

class MyReceiver : OnReceiveContentListener {
    override fun onReceiveContent(view: View, contentInfo: ContentInfoCompat): ContentInfoCompat {
        val split = contentInfo.partition { item: ClipData.Item -> item.uri != null }
        val uriContent = split.first
        val remaining = split.second
        if (uriContent != null) {
            // App-specific logic to handle the URI(s) in uriContent.
        }
        // Return anything that your app didn't handle. This preserves the
        // default platform behavior for text and anything else that you aren't
        // implementing custom handling for.
        return remaining
    }

    companion object {
        val MIME_TYPES = arrayOf("image/*", "video/*")
    }
}

 public class MyReceiver implements OnReceiveContentListener {
     public static final String[] MIME_TYPES = new String[] {"image/*", "video/*"};

     @Override
     public ContentInfoCompat onReceiveContent(View view, ContentInfoCompat contentInfo) {
         Pair<ContentInfoCompat, ContentInfoCompat> split = contentInfo.partition(
                 item -> item.getUri() != null);
         ContentInfo uriContent = split.first;
         ContentInfo remaining = split.second;
         if (uriContent != null) {
             // App-specific logic to handle the URI(s) in uriContent.
         }
         // Return anything that your app didn't handle. This preserves the
         // default platform behavior for text and anything else that you aren't
         // implementing custom handling for.
         return remaining;
     }
 }

Uygulamanız intent'lerle paylaşımı zaten destekliyorsa içerik URI'lerini işlemek için uygulamaya özel mantığınızı yeniden kullanabilirsiniz. Kalan verileri platforma döndürerek bu verilerin işlenmesini platforma devredin.

Dinleyiciyi uyguladıktan sonra uygulamanızdaki uygun kullanıcı arayüzü öğelerinde ayarlayın:

class MyActivity : Activity() {
    public override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        // ...
        val myInput = findViewById(R.id.my_input)
        ViewCompat.setOnReceiveContentListener(myInput, MyReceiver.MIME_TYPES, MyReceiver())
    }
}

public class MyActivity extends Activity {
     @Override
     public void onCreate(Bundle savedInstanceState) {
         // ...

         AppCompatEditText myInput = findViewById(R.id.my_input);
         ViewCompat.setOnReceiveContentListener(myInput, MyReceiver.MIME_TYPES, new MyReceiver());
     }
}

URI izinleri

Okuma izinleri, OnReceiveContentListener öğesine iletilen yükteki tüm içerik URI'leri için platform tarafından otomatik olarak verilir ve yayınlanır.

Normalde uygulamanız, içerik URI'lerini bir hizmet veya etkinlikte işler. Uzun süren işlemler için WorkManager'ı kullanın. Bunu uygularken, içeriği Intent.setClipData kullanarak iletip FLAG_GRANT_READ_URI_PERMISSION işaretini ayarlayarak izinleri hedef hizmete veya etkinliğe genişletin.

Alternatif olarak, içeriği işlemek için mevcut bağlamda bir arka plan iş parçacığı kullanabilirsiniz. Bu durumda, izinlerin platform tarafından erken iptal edilmemesi için dinleyici tarafından alınan payload nesnesine bir referans tutmanız gerekir.

Özel görünümler

Uygulamanız özel bir View alt sınıfı kullanıyorsa OnReceiveContentListener öğesinin atlanmadığından emin olun.

View sınıfınız onCreateInputConnection yöntemini geçersiz kılıyorsa InputConnection öğesini yapılandırmak için Jetpack API InputConnectionCompat.createWrapper kullanın.

View sınıfınız onTextContextMenuItem yöntemini geçersiz kılıyorsa menü öğesi R.id.paste veya R.id.pasteAsPlainText olduğunda süper sınıfa yetki verin.

Klavye resim API'si ile karşılaştırma

OnReceiveContentListener API'yi, mevcut klavye resmi API'sinin sonraki sürümü olarak düşünebilirsiniz. Bu birleştirilmiş API, klavye resim API'sinin işlevlerini ve bazı ek özellikleri destekler. Cihaz ve özellik uyumluluğu, Jetpack kitaplığını mı yoksa Android SDK'sındaki yerel API'leri mi kullandığınıza bağlı olarak değişir.