Получайте богатый контент

Пользователи любят изображения, видео и другой выразительный контент, но вставлять и перемещать этот контент в приложениях не всегда легко. Чтобы приложениям было проще получать разнообразный контент, в Android 12 (уровень API 31) представлен унифицированный API, который позволяет вашему приложению принимать контент из любого источника: буфера обмена, клавиатуры или перетаскивания.

Вы можете прикрепить интерфейс, например OnReceiveContentListener , к компонентам пользовательского интерфейса и получать обратный вызов, когда контент вставляется с помощью любого механизма. Обратный вызов становится единственным местом, где ваш код обрабатывает получение всего контента: от простого и стилизованного текста до разметки, изображений, видео, аудиофайлов и т. д.

Для обратной совместимости с предыдущими версиями Android этот API также доступен в AndroidX, начиная с Core 1.7 и Appcompat 1.4 , которые мы рекомендуем использовать при реализации этой функциональности.

Обзор

В случае с другими существующими API каждый механизм пользовательского интерфейса, например меню касания и удержания или перетаскивание, имеет свой собственный соответствующий API. Это означает, что вам придется интегрироваться с каждым API отдельно, добавляя аналогичный код для каждого механизма вставки контента:

API OnReceiveContentListener объединяет эти различные пути кода, создавая единый API для реализации, поэтому вы можете сосредоточиться на логике, специфичной для вашего приложения, и позволить платформе позаботиться обо всем остальном:

Этот подход также означает, что когда на платформу добавляются новые способы вставки контента, вам не нужно вносить дополнительные изменения в код, чтобы включить поддержку в вашем приложении. И если вашему приложению необходимо реализовать полную настройку для конкретного варианта использования, вы все равно можете использовать существующие API, которые продолжают работать так же.

Выполнение

API представляет собой интерфейс прослушивателя с одним методом OnReceiveContentListener . Для поддержки более старых версий платформы Android мы рекомендуем использовать соответствующий интерфейс OnReceiveContentListener в библиотеке AndroidX Core.

Чтобы использовать API, реализуйте прослушиватель, указав, какие типы контента может обрабатывать ваше приложение:

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

После указания всех типов MIME контента, которые поддерживает ваше приложение, реализуйте остальную часть прослушивателя:

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;
     }
 }

Если ваше приложение уже поддерживает совместное использование с намерениями, вы можете повторно использовать логику, специфичную для приложения, для обработки URI контента. Верните все оставшиеся данные, чтобы делегировать обработку этих данных платформе.

После реализации прослушивателя установите его для соответствующих элементов пользовательского интерфейса вашего приложения:

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

Разрешения на чтение предоставляются и освобождаются платформой автоматически для любых URI контента в полезных данных, передаваемых в OnReceiveContentListener .

Обычно ваше приложение обрабатывает URI контента в сервисе или действии. Для длительной обработки используйте WorkManager . При реализации этого расширите разрешения для целевой службы или действия, передав содержимое с помощью Intent.setClipData и установив флаг FLAG_GRANT_READ_URI_PERMISSION .

Альтернативно вы можете использовать фоновый поток в текущем контексте для обработки содержимого. В этом случае вы должны сохранить ссылку на объект payload , полученный прослушивателем, чтобы гарантировать, что разрешения не будут преждевременно отозваны платформой.

Пользовательские представления

Если ваше приложение использует пользовательский подкласс View , позаботьтесь о том, чтобы OnReceiveContentListener не был обойден.

Если ваш класс View переопределяет метод onCreateInputConnection , используйте API Jetpack InputConnectionCompat.createWrapper для настройки InputConnection .

Если ваш класс View переопределяет метод onTextContextMenuItem , делегируйте его суперу, когда пункт меню — R.id.paste или R.id.pasteAsPlainText .

Сравнение с API изображения клавиатуры

Вы можете думать об API OnReceiveContentListener как о следующей версии существующего API изображения клавиатуры . Этот унифицированный API поддерживает функциональность API изображения клавиатуры, а также некоторые дополнительные функции. Совместимость устройств и функций зависит от того, используете ли вы библиотеку Jetpack или собственные API из Android SDK.