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

Встроенный фото-пикер — это другая форма опыта выбора фотографий, позволяющая взаимодействовать с ним напрямую в пользовательских интерфейсах приложений. Он предлагает улучшенные возможности интеграции и настройки по сравнению с классическим фото-пикером. Поскольку он отображается на 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 composable обеспечивает механизм для включения встроенного пользовательского интерфейса фото-выборщика непосредственно в экран 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. Чтобы персонализировать акцентный цвет фотовыборщика, определите параметр 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)