此页面由 Cloud Translation API 翻译。

相机取景器

适用于相机的基于独立可组合项和视图的取景器"

下表列出了 androidx.camera-viewfinder 组中的所有工件。

制品	稳定版	候选版	Beta 版	Alpha 版
viewfinder-compose	1.5.0	-	-	1.4.0-alpha13
viewfinder-core	1.5.0	-	-	1.4.0-alpha13
取景器视图	1.5.0	-	-	1.4.0-alpha13

此库的最后更新时间：2025 年 9 月 10 日

声明依赖项

如需添加 camera-viewfinder 的依赖项，您必须将 Google Maven 代码库添加到项目中。如需了解详情，请参阅 Google 的 Maven 代码库。

在应用或模块的 build.gradle 文件中添加所需工件的依赖项：

Groovy

dependencies {
    // Use to implement camera viewfinders
    
    implementation "androidx.camera.viewfinder:viewfinder-view:1.5.0"
    implementation "androidx.camera.viewfinder:viewfinder-compose:1.5.0"
    implementation "androidx.camera.viewfinder:viewfinder-core:1.5.0"

}

Kotlin

dependencies {
    // Use to implement camera viewfinders
    implementation("androidx.camera.viewfinder:viewfinder-view:1.5.0")
    implementation("androidx.camera.viewfinder:viewfinder-core:1.5.0")
    implementation("androidx.camera.viewfinder:viewfinder-compose:1.5.0")


}

如需详细了解依赖项，请参阅添加 build 依赖项。

反馈

您的反馈将帮助我们改进 Jetpack。如果您发现了新问题，或对此库有任何改进建议，请告诉我们。创建新问题前，请先查看此库中的现有问题。您可以点击星标按钮，为现有问题投票。

创建新问题

如需了解详情，请参阅问题跟踪器文档。

版本 1.5

版本 1.5.0

2025 年 9 月 10 日

发布了 androidx.camera.viewfinder:viewfinder-compose:1.5.0、androidx.camera.viewfinder:viewfinder-core:1.5.0 和 androidx.camera.viewfinder:viewfinder-view:1.5.0。版本 1.5.0 中包含这些提交内容。

自 1.4.0 以来的重要变更：

这是 Camera Viewfinder 库的首个稳定版本，提供强大、具有生命周期感知能力且易于使用的基于 View 和 Compose 的 API。这些组件旨在用作相机取景器，并且可以直接与 Camera2 集成。

此版本还为新的 androidx.camera:camera-compose 制品奠定了基础，该制品引入了 CameraXViewfinder，这是一个与 CameraX SurfaceRequest 无缝集成的 Compose 惯用取景器，类似于 PreviewView 对基于 View 的布局的作用。以下是一些最重要的变更：

制品重定位：为了提高模块化程度，Viewfinder 制品已移至其自己的库组。之前使用 androidx.camera:camera-viewfinder* 依赖项的开发者应迁移到 androidx.camera.viewfinder:viewfinder-*。
API 稳定化和改进：此稳定版已对 API Surface 进行了优化。这包括将 CameraViewfinder 重命名为 ViewfinderView 以更好地反映其多功能性、重新整理软件包以提高清晰度，以及将 ViewfinderSurfaceRequest 设为不可变数据类型以实现更可预测的状态管理。
Compose API 更新：Compose Viewfinder API 现在支持 ContentScale 和 Alignment，可用于精细控制相机数据流在其容器中的显示方式，从而镜像标准 androidx.compose.foundation.Image 可组合函数的行为。
Surface 生命周期管理：现在，在 API 29 及更高级别上，ViewfinderSurfaceSession 在配置更改和生命周期事件期间保持有效。此更改旨在减少丢帧并提供更流畅的用户体验。
实现模式默认值：Viewfinder 现在默认采用智能 ImplementationMode，可自动选择最佳底层实现。它优先使用高性能的 SurfaceView（EXTERNAL 模式），并在旧版 API 级别或存在已知兼容性问题的设备上优雅地回退到更兼容的 TextureView（EMBEDDED 模式）。不过，开发者仍可覆盖此行为，以实现完全控制。

bug 修复

可组合函数 Viewfinder 现在可以在 Compose 的 Pager 中以及与 movableContentOf() 搭配使用，确保在复杂的界面场景中正确重置和管理界面。(I0d9be、 I79432)
修复了 Android 10 和 11 上基于 SurfaceView 的 Viewfinder 在应用转换时可能会拉伸的问题。(Icc77c)

版本 1.5.0-rc01

2025 年 8 月 13 日

发布了 androidx.camera.viewfinder:viewfinder-compose:1.5.0-rc01、androidx.camera.viewfinder:viewfinder-core:1.5.0-rc01 和 androidx.camera.viewfinder:viewfinder-view:1.5.0-rc01。版本 1.5.0-rc01 中包含这些提交内容。

bug 修复

将默认 minSdk 从 API 21 移至 API 23（Ibdfca、b/380448311、b/435705964、b/435705223）

版本 1.5.0-beta03

2025 年 7 月 16 日

发布了 androidx.camera.viewfinder:viewfinder-compose:1.5.0-beta03、androidx.camera.viewfinder:viewfinder-core:1.5.0-beta03 和 androidx.camera.viewfinder:viewfinder-view:1.5.0-beta03。版本 1.5.0-beta03 中包含这些提交内容。

bug 修复

Viewfinder（基于 Compose 和基于 View）的默认 ImplementationMode 现在可以在 EXTERNAL（用于提升性能）和 EMBEDDED（用于在旧版 API/存在问题的设备上实现兼容性）之间智能选择。不过，您仍可以通过 ViewfinderSurfaceRequest 或 XML 属性（在基于 View 的 API 上）中的明确设置来替换此行为。(Iecd3a)
改进了 Surface 会话管理，允许在 API 29 及更高版本上使用 TextureView 或 SurfaceView 时，使 ViewfinderSurfaceSession 在整个 Surface 创建/销毁生命周期内保持活动状态。(I112d9)
Viewfinder 现在可确保在适当的时间释放 Surface，仅当会话不再使用 Surface 时才释放，而不是在可组合项被处置时始终释放。对于 EXTERNAL (SurfaceView)，此行为目前仅适用于 API 29 及更高级别。对于 EMBEDDED (TextureView)，此行为适用于所有 API 级别。(I9a03f)
Viewfinder 现在可以正确处理表面替换，例如在以下情况下：API 级别为 28 或更低级别的 EXTERNAL 取景器移出屏幕，或者 Viewfinder（带有任何 ImplementationMode）是 moveableContentOf() 的一部分。(I79432)
可组合函数 Viewfinder 现在可与 Compose 的 Pager 正常搭配使用。此更改通过实现 AndroidView 的 onReset 回调来确保可组合项能够成功重置，同时支持 EMBEDDED 和 EXTERNAL 实现。(I0d9be)
修复了 Android 10/11 上的一个问题，即由于过早应用了转换操作（例如缩放或平移），导致 EXTERNAL Viewfinder 看起来拉伸或不正确。系统现在会等待 Surface 创建完毕，然后再在布局阶段应用这些转换，从而确保输出正确。(Icc77c)

版本 1.5.0-beta02

2025 年 6 月 4 日

发布了 androidx.camera.viewfinder:viewfinder-compose:1.5.0-beta02、androidx.camera.viewfinder:viewfinder-core:1.5.0-beta02 和 androidx.camera.viewfinder:viewfinder-view:1.5.0-beta02。版本 1.5.0-beta02 中包含这些提交内容。

版本 1.5.0-beta01

2025 年 5 月 7 日

发布了 androidx.camera.viewfinder:viewfinder-compose:1.5.0-beta01、androidx.camera.viewfinder:viewfinder-core:1.5.0-beta01 和 androidx.camera.viewfinder:viewfinder-view:1.5.0-beta01。版本 1.5.0-beta01 中包含这些提交内容。

这是基于视图和基于 Compose 的取景器的第一个正式版 Beta 版，这些取景器非常灵活，可与 Camera2 搭配使用。如果您正在寻找可与 CameraX 搭配使用的 View 或可组合项，请参阅 PreviewView 和 CameraXViewfinder。

新功能

现在，可以在基于 Compose 的取景器中使用 ContentScale 和 Alignment 来缩放和放置容器中显示的 Surface，这与 androidx.compose.foundation.Image 的行为类似。(Ibcea3)

API 变更

TransformationInfo 现在为所有实参设置了默认值。这样一来，便可创建不含任何 TransformationInfo 的取景器，这些取景器将默认采用 0 的来源旋转、无来源镜像和无裁剪矩形。(I2b1b2)
可组合的取景器现在采用尾随 lambda 来接收 Surface 会话，类似于 AndroidExternalSurface。提供的 lambda 使用 ViewfinderInitScope 作为接收器，从而允许安装回调以接收新的 Surface 会话。这些界面会话在超出范围时会自动释放 Viewfinder 持有的资源。(Ib2b0d)
ViewfinderSurfaceRequest.Builder.populateFromCharacteristics 已被移除，现在已替换为一组等效的静态 API，可用于生成 TransformationInfo，该 API 将产生与 populateFromCharacteristics 相同的转换。这些静态方法已添加到 Camera2TransformationInfo 类中。(Idc6af)
ViewfinderSurfaceRequest 不再包含用于检索界面的异步 API。现在，它是一种不可变的数据类型。用于检索 Surface 的 API 现在已移至取景器。(I30127)
CameraViewfinder 已重命名为 ViewfinderView，以便命名与取景器可组合项的命名保持一致，并表明它不仅可以与相机来源搭配使用。(Id9e6b)
已将 viewfinder-view 中的类从 androidx.camera.viewfinder 软件包移至 androidx.camera.viewfinder.view 子软件包。(I6cb44)
为基于视图的取景器添加了新的 API，可用于设置来源旋转、镜像和裁剪矩形。此 TransformationInfo 类与基于 Compose 的取景器所使用的类相同。(I907c3)
基于视图的取景器现在使用新的 ViewfinderSurfaceRequest API，这些 API 不再在内部处理 Surface 响应。requestSurfaceSession() API 现在返回 ListenableFuture<ViewfinderSurfaceSession>，而不是 ListenableFuture<Surface>。ListenableFuture<ViewfinderSurfaceSession> 会返回一个 AutoCloseable 类，该类在关闭时与调用旧版 ViewfinderSurfaceRequest.markSurfaceSafeToRelease() API 的行为方式相同。这样可以更清晰地划分界面请求和界面响应之间的责任。(I19041)

版本 1.4

版本 1.4.0-alpha13

2025 年 2 月 26 日

发布了 androidx.camera.viewfinder:viewfinder-compose:1.4.0-alpha13、androidx.camera.viewfinder:viewfinder-core:1.4.0-alpha13 和 androidx.camera.viewfinder:viewfinder-view:1.4.0-alpha13。版本 1.4.0-alpha13 包含这些提交内容。

版本 1.4.0-alpha12

2025 年 1 月 15 日

发布了 androidx.camera.viewfinder:viewfinder-compose:1.4.0-alpha12、androidx.camera.viewfinder:viewfinder-core:1.4.0-alpha12 和 androidx.camera.viewfinder:viewfinder-view:1.4.0-alpha12。版本 1.4.0-alpha12 中包含这些提交内容。

新功能

将 compileSdk 升级为 35，以便使用 Android 15 相关 API。使用 CameraX 库的应用还需要升级其 compileSdk 配置设置。(Ic80cd)
此库现在使用 JSpecify nullness 注解，这些注解属于 type-use 类型。Kotlin 开发者应使用以下编译器实参来强制执行正确用法：-Xjspecify-annotations=strict（这是 Kotlin 编译器从 2.1.0 版开始的默认实参）。（I7bcd7、b/326456246）

版本 1.4.0-alpha11

2024 年 12 月 11 日

发布了 androidx.camera.viewfinder:viewfinder-compose:1.4.0-alpha11、androidx.camera.viewfinder:viewfinder-core:1.4.0-alpha11 和 androidx.camera.viewfinder:viewfinder-view:1.4.0-alpha11。版本 1.4.0-alpha11 中包含这些提交内容。

API 变更

viewfinder-core 类已移入与其所属库一致的软件包中。(I431c6)
CameraViewfinder.ScaleType 已移至 viewfinder-core，以便在 Compose 中重复使用 (I87ef1)
移除了已废弃的 CameraViewfinder 类。请使用提供等效功能的新 API。(I6e59a)

版本 1.4.0-alpha10

2024 年 10 月 30 日

发布了 androidx.camera.viewfinder:viewfinder-compose:1.4.0-alpha10、androidx.camera.viewfinder:viewfinder-core:1.4.0-alpha10 和 androidx.camera.viewfinder:viewfinder-view:1.4.0-alpha10。版本 1.4.0-alpha10 中包含这些提交内容。

版本 1.4.0-alpha09

2024 年 10 月 2 日

发布了 androidx.camera.viewfinder:viewfinder-compose:1.4.0-alpha09、androidx.camera.viewfinder:viewfinder-core:1.4.0-alpha09 和 androidx.camera.viewfinder:viewfinder-view:1.4.0-alpha09。版本 1.4.0-alpha09 中包含这些提交内容。

版本 1.4.0-alpha08

2024 年 9 月 4 日

发布了 androidx.camera.viewfinder:viewfinder-compose:1.4.0-alpha08、androidx.camera.viewfinder:viewfinder-core:1.4.0-alpha08 和 androidx.camera.viewfinder:viewfinder-view:1.4.0-alpha08。版本 1.4.0-alpha08 中包含这些提交内容。

新功能

更新到 1.4.0-alpha08 后，CameraX 取景器制品已移至其自己的库组。此变更对于提高 CameraX 库的模块化程度和可维护性是必要的。

如果您之前依赖于 androidx.camera:camera-viewfinder、androidx.camera:camera-viewfinder-compose 或 androidx.camera:camera-viewfinder-core，则需要将依赖项转换为以下内容：

androidx.camera:camera-viewfinder -> androidx.camera.viewfinder:viewfinder-view
androidx.camera:camera-viewfinder-compose -> androidx.camera.viewfinder:viewfinder-compose
androidx.camera:camera-viewfinder-core -> androidx.camera.viewfinder:viewfinder-core

您无需进行任何代码更改即可完成此过渡。旧的取景器 Maven 工件坐标将不再接收更新。

此外，如果您将 Compose 与 CameraX 搭配使用，现在可以使用新的 Compose-first 库（目前处于 Alpha 版）：androidx.camera:camera-compose。这提供了 CameraXViewfinder 可组合项，这是一个符合 Compose 惯例的取景器，可将 CameraX 的 SurfaceRequest 适配到 Compose，类似于 PreviewView 对视图的作用。