Eingebettete Bildauswahl

Die eingebettete Bildauswahl ist eine andere Form der Bildauswahl, die eine direkte Interaktion in den Benutzeroberflächen von Apps ermöglicht. Er bietet im Vergleich zur klassischen Bildauswahl erweiterte Integrations- und Anpassungsoptionen. Da sie auf einem 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, ihre Aktivität befindet sich in einem fortgesetzten Zustand und kann in Echtzeit auf Nutzerauswahlen reagieren.

Die eingebettete Bildauswahl bietet eine nahtlosere UI-Integration, behält aber dieselben Sicherheits- und Datenschutzfunktionen wie die Standardbildauswahl bei, da sie auf einem speziellen SurfaceView gerendert wird.

Geräteverfügbarkeit

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

Geräte, die diese Funktionen nicht unterstützen, können über die Google Play-Dienste auf die klassische Bildauswahl oder die rückkompatible Version zurückgreifen.

Jetpack-Bibliotheksabhängigkeit

Fügen Sie die Jetpack-Bibliothek für die Fotoauswahl 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 einzubinden. Mit dieser Composable wird ein SurfaceView erstellt, in dem die eingebettete Benutzeroberfläche der Bildauswahl gehostet wird. Sie verwaltet die Verbindung zum EmbeddedPhotoPicker-Dienst, verarbeitet Nutzerinteraktionen und kommuniziert ausgewählte Media-URIs mit der aufrufenden 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 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 eine reibungslose Nutzererfahrung sorgt.

Heben Sie die Auswahl von Uri mit der Methode deselectUri oder deselectUris auf, um den eingebetteten Picker darüber zu informieren, dass der Nutzer ein Element in der Benutzeroberfläche der App abgewählt hat.pickerState 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

Standardmäßig verwendet die eingebettete Bildauswahl die dynamischen Farben, die vom System bereitgestellt werden. Diese können vom Nutzer in den Designoptionen des Geräts für alle Apps festgelegt werden. Die Akzentfarbe wird für verschiedene primäre Elemente in der Bildauswahl verwendet. Alle anderen Farben werden gemäß den Android-Material-Richtlinien 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 Akzentfarbe festzulegen	Mit Akzentfarbe (Spitze)	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

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

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

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

Integration von Aufrufen

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 Fotoauswahl in der onCreate-Methode Ihrer Aktivität, indem Sie Folgendes tun:

1. Referenz auf EmbeddedPhotoPickerView aus dem Layout abrufen
2. Fügen Sie EmbeddedPhotoPickerStateChangeListener hinzu, um Auswahlereignisse zu verarbeiten.
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()
    )
}

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

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