Eingebettete Bildauswahl

Die eingebettete Bildauswahl ist eine andere Form der Bildauswahl und ermöglicht eine direkte Interaktion in den Benutzeroberflächen von Apps ermöglicht. Sie bietet im Vergleich zur klassischen Bildauswahl erweiterte Integrations- und Anpassungsmöglichkeiten. Da sie auf einer SurfaceView mit der Methode setChildSurfacePackage gerendert wird, bietet sie dieselben Sicherheits- und Datenschutzfunktionen wie die nicht eingebettete Version.

Mit der eingebetteten Bildauswahl können Nutzer kontinuierlich Fotos und Videos sowohl von ihrem Gerät als auch aus ihrer Cloud-Fotogalerie auswählen, ohne den Fokus in der Client-App zu verlieren. Die Client-App bleibt aktiv, befindet sich im Status „RESUMED“ und kann in Echtzeit auf Auswahlen durch die Nutzer reagieren.

Die eingebettete Bildauswahl bietet eine nahtlosere UI-Integration, verfügt aber über dieselben Sicherheits- und Datenschutzfunktionen wie die Standardbildauswahl, da sie auf einer speziellen SurfaceView gerendert wird.

Verfügbarkeit auf Geräten

Die eingebettete Bildauswahl wird auf Geräten mit Android 14 (API-Level 34) mit SDK-Erweiterungen ab Version 15 unterstützt.

Geräte, die diese Anforderungen nicht erfüllen, können über die Google Play-Dienste auf die klassische Bildauswahl oder die rückportierte Version zurückgreifen.

Abhängigkeit von Jetpack-Bibliothek

Fügen Sie die Jetpack-Bildauswahl-Bibliothek als Abhängigkeit hinzu:

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

Sie können die eingebettete Bildauswahl mit Jetpack Compose (empfohlen) oder Views einbinden.

Jetpack Compose-Integration

Die zusammensetzbare Funktion EmbeddedPhotoPicker bietet einen Mechanismus, um die eingebettete Benutzeroberfläche der Bildauswahl direkt in Ihren Jetpack Compose-Bildschirm einzufügen. Mit dieser zuammensetzbaren Funktion wird eine SurfaceView erstellt, in der die eingebettete Benutzeroberfläche der Bildauswahl gehostet wird. Sie verwaltet die Verbindung zum EmbeddedPhotoPicker-Dienst, verarbeitet Nutzerinteraktionen und kommuniziert ausgewählte Media-URIs an die aufrufende Anwendung. Dazu sind nur wenige Parameter erforderlich:

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

Kontinuierliche Auswahl

Mit der eingebetteten Bildauswahl können Nutzer kontinuierlich Elemente aus der Fotogalerie auswählen und die Auswahl aufheben, ohne die Auswahl zu schließen. Die in der Benutzeroberfläche der App ausgewählten und abgewählten Elemente werden mit der Bildauswahl synchronisiert, was für ein reibungsloses Nutzungserlebnis sorgt.

Heben Sie die Auswahl von Uri mit der Methode deselectUri oder deselectUris aus pickerState auf, damit die eingebettete Auswahl erfährt, dass der Nutzer ein Element aus der Benutzeroberfläche der App abgewählt hat. Sie müssen den UI-Status Ihrer eigenen App manuell aktualisieren, da Ihre App durch den Aufruf dieser Methoden nicht über neu widerrufene URIs über den onUriPermissionRevoked-Callback benachrichtigt wird.

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
}

Bildauswahl personalisieren

Die eingebettete Bildauswahl bietet Optionen zur Personalisierung, mit denen Sie ihr Erscheinungsbild und Verhalten an das Design und die Nutzerfreundlichkeit Ihrer App anpassen können.

Akzentfarbe

Die eingebettete Bildauswahl verwendet standardmäßig die dynamischen Farben, die vom System bereitgestellt werden und die der Nutzer in den Optionen für das Gerätedesign für alle Apps festlegen kann. Die Akzentfarbe wird für verschiedene primäre Elemente in der Bildauswahl verwendet. Alle anderen Farben werden gemäß den „Material Design“-Richtlinien von Android festgelegt. Wenn Sie die Akzentfarbe der Auswahl personalisieren möchten, definieren Sie die Option EmbeddedPhotoPickerFeatureInfo:

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

EmbeddedPhotoPicker(
    embeddedPhotoPickerFeatureInfo = info,
    ...
)

Ohne festgelegte Akzentfarbe	Mit Akzentfarbe (nicht erweitert (Peak))	Mit Akzentfarbe (erweitert)

Die Akzentfarbe muss vollständig deckend sein. Der Alphawert (Transparenz) wird ignoriert. Es sind nur Farben mit einem Luminanzwert (Helligkeit) zwischen 0,05 und 0,9 zulässig.

Abmessungen

Die Größe der eingebetteten Auswahl ist standardmäßig nicht begrenzt. Sie können jedoch einen Modifikator angeben, um sie zu begrenzen:

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

Ohne Limit (erweitert)	Mit Limit von 500 dp (erweitert)

Integration von Views

Wenn Sie die eingebettete Bildauswahl mit Views hinzufügen möchten, fügen Sie Ihrer Layoutdatei einen Eintrag hinzu:

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

Initialisieren Sie dann die Bildauswahl in der Methode onCreate Ihrer Aktivität, indem Sie Folgendes tun:

1. Rufen Sie eine Referenz zu Ihrer EmbeddedPhotoPickerView aus dem Layout ab.
2. Fügen Sie den EmbeddedPhotoPickerStateChangeListener für die Verarbeitung von Auswahlereignissen hinzu.
3. Konfigurieren Sie die Bildauswahl mit EmbeddedPhotoPickerFeatureInfo, einschließlich aller benutzerdefinierten Einstellungen wie der Akzentfarbe.

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

Um mit der eingebetteten Auswahl zu interagieren, können Sie sie mit den verschiedenen Methoden von EmbeddedPhotoPickerSession aufrufen:

// 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)