嵌入式照片选择器

动画：显示连续照片选择器选择过程

嵌入式照片选择器是一种不同的照片选择体验，允许在应用的用户界面中直接与之互动。与经典照片选择器相比，它提供了增强的集成和自定义选项。由于它是使用 setChildSurfacePackage 方法在 SurfaceView 上呈现的，因此它保留了非嵌入式版本的相同安全和隐私保护功能。

借助嵌入式照片选择器，用户可以从设备和云端照片库中持续选择照片和视频而不会在客户端应用中失去焦点。客户端应用保持活跃状态，其 activity 处于恢复状态并且可以实时响应用户选择。

嵌入式照片选择器提供了更无缝的界面集成，但由于它是呈现在特殊的 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 （推荐）或 View 集成嵌入式照片选择器。

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

持续选择

动画：显示连续照片选择器选择过程

借助嵌入式照片选择器，用户可以持续选择和取消选择照片库中的项，而无需关闭选择器。在应用界面中选择和取消选择的项会与照片选择器同步，从而提供无缝的用户体验。

使用 deselectUri 或 deselectUris 方法从 pickerState 取消选择 Uri，以通知嵌入式选择器用户已从应用界面中取消选择某个项。手动更新您自己的应用界面状态是必要的，因为调用这些方法不会通过 onUriPermissionRevoked 回调通知您的应用任何新撤消的 URI。

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

未设置强调色	已设置强调色（峰值）	已设置强调色（展开）

强调色必须完全不透明。系统会忽略 Alpha（透明度）值。仅允许使用亮度值介于 0.05 和 0.9 之间的颜色。

尺寸

默认情况下，嵌入式选择器的大小不受限制，但您可以指定修饰符来限制它：

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

无限制（展开）	限制为 500 dp（展开）

View 集成

如需使用 View 添加嵌入式照片选择器，请向布局文件添加条目：

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

然后，在 activity 的 onCreate 方法中初始化照片选择器，方法如下：

从布局中获取对 EmbeddedPhotoPickerView 的引用
添加 EmbeddedPhotoPickerStateChangeListener 以处理选择事件
使用 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)

嵌入式照片选择器 使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。