Встроенный выбор фотографий

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

Благодаря встроенному инструменту выбора фотографий пользователи могут непрерывно выбирать фотографии и видео как со своего устройства, так и из облачной фотобиблиотеки, не отвлекаясь от работы в клиентском приложении. Клиентское приложение остается активным, его активность находится в режиме возобновления, и оно может реагировать на выбор пользователя в режиме реального времени.

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

Доступность устройства

Встроенный инструмент выбора фотографий поддерживается на устройствах под управлением Android 14 (уровень API 34) с расширением SDK версии 15 или выше.

Устройства, не обладающие этими возможностями, могут использовать классический инструмент выбора фотографий или адаптированную версию, работающую через сервисы Google Play.

зависимость библиотеки Jetpack

Добавьте библиотеку выбора фотографий Jetpack в качестве зависимости:

// For apps using Jetpack Compose
implementation("androidx.photopicker:photopicker-compose:1.0.0-alpha01")

// For apps using Views
implementation("androidx.photopicker:photopicker:1.0.0-alpha01")

Встроенный инструмент выбора фотографий можно интегрировать с помощью Jetpack Compose (рекомендуется) или Views .

Интеграция с Jetpack Compose

Функция EmbeddedPhotoPicker являющаяся составным элементом, предоставляет механизм для непосредственного включения встроенного интерфейса выбора фотографий в экран Jetpack Compose. Этот составной элемент создает SurfaceView , который размещает встроенный интерфейс выбора фотографий. Он управляет подключением к службе EmbeddedPhotoPicker , обрабатывает взаимодействие с пользователем и передает выбранные URI медиафайлов вызывающему приложению с помощью нескольких параметров для работы:

val coroutineScope = rememberCoroutineScope()
val pickerState = rememberEmbeddedPhotoPickerState()

EmbeddedPhotoPicker(
    state = pickerState,
    onUriPermissionGranted = { uris ->
        _attachments.value += uris
    },
    onUriPermissionRevoked = { uris ->
        _attachments.value -= uris
    },
    onSelectionComplete = {
        // Hide the embedded photo picker as the user is done with the
        // photo/video selection
    },
)

Непрерывный отбор

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

Чтобы отменить выбор Uri , используйте методы deselectUri или deselectUris из pickerState , чтобы уведомить встроенный элемент выбора о том, что пользователь отменил выбор элемента в пользовательском интерфейсе приложения. Необходимо вручную обновлять состояние пользовательского интерфейса вашего приложения, поскольку вызов этих методов не уведомит ваше приложение о новых отозванных URI через обратный вызов onUriPermissionRevoked .

coroutineScope.launch {
    // Signal unselected media to the picker
    pickerState.deselectUris(uris)
    // Remove them from the list of selected media to be reflected in the app's UI
    _attachments.value -= uris
}

Настройте параметры выбора фотографий

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

Акцентный цвет

По умолчанию встроенный инструмент выбора фотографий использует динамические цвета, предоставляемые системой , которые пользователь может установить для разных приложений в параметрах темы оформления устройства. Акцентный цвет будет использоваться для различных основных элементов в инструменте выбора фотографий. Все остальные цвета будут устанавливаться в соответствии с рекомендациями Android Material. Чтобы персонализировать акцентный цвет инструмента выбора фотографий, определите параметр EmbeddedPhotoPickerFeatureInfo :

val info = EmbeddedPhotoPickerFeatureInfo.Builder().setAccentColor(0xFF0000).build()

EmbeddedPhotoPicker(
    embeddedPhotoPickerFeatureInfo = info,
    ...
)

Без указания акцентного цвета	С акцентным цветом (пиком)	С акцентным цветом (расширенный)

Акцентный цвет должен быть полностью непрозрачным. Значение альфа-канала (прозрачности) игнорируется. Допускаются только цвета со значением яркости от 0,05 до 0,9.

Размеры

По умолчанию размер встроенного средства выбора не ограничен, но вы можете указать модификатор для его ограничения:

EmbeddedPhotoPicker(
    modifier = Modifier.height(500.dp),
    ...
)

Без ограничений (расширено)	С ограничением в 500 знаков после запятой (расширенное)

Интеграция представлений

Чтобы добавить встроенный инструмент выбора фотографий с помощью Views, добавьте запись в файл макета:

<view class="androidx.photopicker.EmbeddedPhotoPickerView"
    android:id="@+id/photopicker"
    android:layout_width="match_parent"
    android:layout_height="match_parent" />

Затем инициализируйте средство выбора фотографий в методе onCreate вашего действия, выполнив следующие действия:

1. Получите ссылку на ваш EmbeddedPhotoPickerView из макета.
2. Добавьте обработчик EmbeddedPhotoPickerStateChangeListener для обработки событий выбора.
3. Настройте средство выбора фотографий с помощью EmbeddedPhotoPickerFeatureInfo , включая любые пользовательские параметры, такие как цвет акцента.

// Keep track of the selected media
private val _attachments = MutableStateFlow(emptyList<Uri>())
val attachments = _attachments.asStateFlow()

private lateinit var picker: EmbeddedPhotoPickerView
private var openSession: EmbeddedPhotoPickerSession? = null

val pickerListener = object : EmbeddedPhotoPickerStateChangeListener {
    override fun onSessionOpened(newSession: EmbeddedPhotoPickerSession) {
        // Keep reference to the session to notify the embedded picker of user
        // interactions on the calling app
        openSession = newSession
    }

    override fun onSessionError(throwable: Throwable) {}

    override fun onUriPermissionGranted(uris: List<Uri>) {
        // Add newly selected media to our tracked list
        _attachments += uris
    }

    override fun onUriPermissionRevoked(uris: List<Uri>) {
        // Remove newly unselected media from our tracked list
        _attachments -= uris
    }

    override fun onSelectionComplete() {
        // Hide the embedded photo picker as the user is done with the
        // photo/video selection
    }
}

override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)

    setContentView(R.layout.main_view)
    picker = findViewById(R.id.photopicker)

    // Attach the embedded picker event listener to update the app's UI
    picker.addEmbeddedPhotoPickerStateChangeListener(pickerListener)

    // Customize embedded picker's features: accent color, max selectable items,
    // pre-selected URIs, filter out mime types
    picker.setEmbeddedPhotoPickerFeatureInfo(
        // Set a custom accent color
        EmbeddedPhotoPickerFeatureInfo.Builder().setAccentColor(0xFF0000).build()
    )
}

Для взаимодействия со встроенным средством выбора фотографий можно использовать различные методы класса EmbeddedPhotoPickerSession :

// Notify the embedded picker of a configuration change
openSession.notifyConfigurationChanged(newConfig)

// Update the embedded picker to expand following a user interaction
openSession.notifyPhotoPickerExpanded(/* expanded: */ true)

// Resize the embedded picker
openSession.notifyResized(/* width: */ 512, /* height: */ 256)

// Show/hide the embedded picker (after a form has been submitted)
openSession.notifyVisibilityChanged(/* visible: */ false)

// Remove unselected media from the embedded picker after they have been
// unselected from the host app's UI
openSession.requestRevokeUriPermission(removedUris)