接收多媒體內容

圖 1.統合式 API 可集中處理 無論特定 UI 機制為何 (例如貼上 方法與按住選單或使用拖曳功能。

使用者喜歡圖片、影片和其他生動的內容，但插畫和 在應用程式中移動這類內容並不容易為了讓應用程式更輕鬆 接收多媒體內容，Android 12 (API 級別 31) 導入了一個整合式 API， 可讓您的應用程式接受任何來源的內容，包括剪貼簿、鍵盤或拖曳。

您可以附加介面，例如 OnReceiveContentListener、 並可在內容插入內容時接收回呼 以注意力機制為基礎回呼會成為程式碼處理的單一位置 接收所有內容，包括純文字和樣式化的文字、標記、圖片、影片等 音訊檔案等

為了提供與 Android 舊版本的回溯相容性，這個 API 也可以 適用於 AndroidX Core 1.7 和 Appcompat 1.4、 我們建議您在實作這項功能時使用。

總覽

使用其他現有的 API 時，每種使用者介面機制 (例如觸控和按住選單 都有專屬的對應 API這表示您必須分別整合每個 API，針對插入內容的每個機制新增類似的程式碼：

圖 2 先前，應用程式為每個 UI 實作不同的 API 插入內容機制

OnReceiveContentListener API 會建立用於導入的單一 API 來整合這些不同程式碼的路徑，以便您可以專心處理應用程式的專屬邏輯，讓平台處理其餘的工作：

圖 3. 統合式 API 可讓您導入 支援所有 UI 機制的 API。

也就是說，當新增內容插入方式 您不需要進行其他程式碼變更 。如果您的應用程式需要針對 仍可使用現有的 API，因為 使用這個層即可

實作

注意： 請參閱 拖曳範例即可查看完整的 DropHelper，會導入 OnReceiveContentListener。詳情請參閱 啟用拖曳功能。

API 是具有單一方法 OnReceiveContentListener 的事件監聽器介面。如要支援舊版 Android 平台，建議您使用 比對 OnReceiveContentListener敬上 AndroidX Core 程式庫的介面。

如要使用此 API，請指定您希望取得的內容類型， 應用程式可處理：

Kotlin

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

Java

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

指定應用程式支援的所有內容 MIME 類型後，再導入事件監聽器的其餘部分：

Kotlin

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/*")
    }
}

Java

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

     @Override
     public ContentInfoCompat onReceiveContent(View view, ContentInfoCompat contentInfo) {
         Pair 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;
     }
 }

如果您的應用程式已支援與意圖共用資料，您可以重複使用 處理內容 URI 的應用程式專屬邏輯。傳回任何其餘資料，委派給平台進行資料處理。

實作事件監聽器後，請將其設定在 應用程式：

Kotlin

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())
    }
}

Java

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 權限

平台會自動授予及釋出 內容 URI 酬載傳遞給 OnReceiveContentListener。

通常，您的應用程式會在服務或活動中處理內容 URI。適用對象 需要長時間執行的處理程序 WorkManager。如果實作 就可以將權限擴充至目標服務或活動 內容 Intent.setClipData敬上 及設定 FLAG_GRANT_READ_URI_PERMISSION。

或者，您也可以透過目前的結構定義，使用背景執行緒來處理內容。在此情況下，您必須維護對 監聽器收到的 payload 物件，確保不會授予權限 平台提前撤銷。

自訂檢視畫面

如果您的應用程式使用自訂 View 子類別，請務必確保 未略過 OnReceiveContentListener。

如果 View 類別覆寫 onCreateInputConnection 方法，請使用 Jetpack API InputConnectionCompat.createWrapper 設定 InputConnection。

如果您的 View 類別覆寫了 onTextContextMenuItem 方法，並在選單項目發生時委派給 Super R.id.paste 或 R.id.pasteAsPlainText。

與鍵盤圖片 API 比較

您可以將 OnReceiveContentListener API 想成是現有 鍵盤映像檔 API 的下一個版本。這個統合式 API 支援鍵盤映像檔 API 的功能，以及一些其他功能。視您使用 Jetpack 程式庫或 Android SDK 中的原生 API 而定，裝置和功能相容性會有所不同。

表 1. 支援的功能和 API 級別 Jetpack。

動作或功能	鍵盤映像檔 API 支援	統合式 API 支援
透過鍵盤插入	是 (API 級別 13 以上)	是 (API 級別 13 以上)
使用輕觸和貼上功能插入按住選單	否	是
使用拖曳功能插入	否	是 (API 級別 24 以上)

表 2. 原生支援的功能和 API 級別 API 整合

動作或功能	鍵盤映像檔 API 支援	統合式 API 支援
透過鍵盤插入	是 (API 級別 25 以上)	是 (Android 12 以上版本)
使用輕觸和貼上功能插入按住選單	否
使用拖曳功能插入	否