本頁面由 Cloud Translation API 翻譯而成。

相機觀景窗

獨立的可組合函式和以 View 為基礎的攝影機觀景窗"

下表列出 androidx.camera-viewfinder 群組的所有構件。

構件	穩定版	候選版	Beta 版	Alpha 版
viewfinder-compose	-	-	1.5.0-beta03	1.4.0-alpha13
viewfinder-core	-	-	1.5.0-beta03	1.4.0-alpha13
viewfinder-view	-	-	1.5.0-beta03	1.4.0-alpha13

本程式庫上次更新日期：2025 年 7 月 16 日

宣告依附元件

如要新增 camera-viewfinder 的依附元件，必須將 Google Maven 存放區新增至專案。詳情請參閱 Google 的 Maven 存放區。

在應用程式或模組的 build.gradle 檔案中，新增所需構件的依附元件：

Groovy

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

}

Kotlin

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


}

如要進一步瞭解依附元件，請參閱「新增建構依附元件」一文。

意見回饋

您的意見可協助我們改善 Jetpack。如果您發現新問題，或是有改進這個程式庫的建議，請告訴我們。回報新問題前，請先查看這個程式庫的現有問題。只要按一下星號按鈕，即可投票給現有的問題。

建立新問題

詳情請參閱 Issue Tracker 說明文件。

1.5 版本

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 版包含這些修訂項目。

修正錯誤

現在，系統會根據預設 ImplementationMode，在 Viewfinder (Compose 和以檢視區塊為基礎) 中，智慧選取 EXTERNAL (提升效能) 和 EMBEDDED (適用於舊版 API/異常裝置)。您還是可以透過 ViewfinderSurfaceRequest 或 XML 屬性 (在以 View 為基礎的 API 上) 中的明確設定，覆寫這項行為。(Iecd3a)
使用 API 29 以上版本時，允許 ViewfinderSurfaceSession 在 Surface 建立/終止生命週期中保持運作，藉此改善 Surface 工作階段管理。這項功能適用於 TextureView 或 SurfaceView。(I112d9)
Viewfinder 現在可確保 Surface 在適當時間釋出，只有在工作階段不再使用時才會釋出，而不是在可組合函式遭到處置時一律釋出。對於 EXTERNAL (SurfaceView)，這項行為目前僅適用於 API 29 以上版本。對於 EMBEDDED (TextureView)，這項行為適用於所有 API 級別。(I9a03f)
現在，Viewfinder 可正確處理表面替換作業，例如 API 級別 28 以下的 EXTERNAL 取景器移出畫面，或是 Viewfinder (含任何 ImplementationMode) 屬於 moveableContentOf() 的情況。(I79432)
可組合函式 Viewfinder 現在可與 Compose 的 Pager 搭配使用。這項變更可確保透過實作 AndroidView 的 onReset 回呼，成功重設 Composable，同時支援 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 版包含這些修訂項目。

這是第一個正式發布的 Beta 版，提供以 View 為基礎和以 Compose 為基礎的觀景窗，可彈性搭配 Camera2 使用。如要尋找搭配 CameraX 使用的 View 或可組合項，請參閱 PreviewView 和 CameraXViewfinder。

新功能

您現在可以在以 Compose 為基礎的觀景窗中使用 ContentScale 和 Alignment，在容器中縮放及放置顯示的表面，與 androidx.compose.foundation.Image 的行為類似。(Ibcea3)

API 變更

TransformationInfo 現在所有引數都有預設值。這樣一來，您就能建立 Viewfinder，而不需要任何 TransformationInfo，系統會將來源旋轉角度預設為 0、不鏡像處理來源，且不裁剪矩形。(I2b1b2)
可組合的取景器現在會採用結尾的 lambda 來接收 Surface 工作階段，與 AndroidExternalSurface 類似。提供的 lambda 會使用 ViewfinderInitScope 做為接收器，因此可以安裝回呼來接收新的 Surface 工作階段。這些介面工作階段超出範圍時，會自動釋放觀景窗持有的資源。(Ib2b0d)
ViewfinderSurfaceRequest.Builder.populateFromCharacteristics 現已移除，並替換為一組同等的靜態 API，可用於產生 TransformationInfo，而這會產生與 populateFromCharacteristics 相同的轉換。這些靜態方法會新增至 Camera2TransformationInfo 類別。(Idc6af)
ViewfinderSurfaceRequest 不再包含用於擷取介面的非同步 API。現在是不可變動的資料型別。擷取 Surface 的 API 現在已移至觀景窗。(I30127)
CameraViewfinder 已重新命名為「ViewfinderView」，以便與 Viewfinder 可組合項目的命名方式一致，並表示該項目可用於相機來源以外的來源。(Id9e6b)
viewfinder-view 中的類別已從 androidx.camera.viewfinder 套件移至 androidx.camera.viewfinder.view 子套件。(I6cb44)
在以檢視區塊為基礎的取景器中新增 API，可設定來源旋轉、鏡像和裁剪矩形。這個 TransformationInfo 類別與以 Compose 為基礎的 Viewfinder 所用類別相同。(I907c3)
以檢視區塊為基礎的觀景窗現在使用新的 ViewfinderSurfaceRequest 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 空值註解，這些註解屬於型別用途。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 Viewfinder 構件已移至專屬程式庫群組。這項變更有助於提升 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

您應該不需要變更任何程式碼，即可完成這項轉換。舊的 Viewfinder Maven 座標將不再收到更新。

此外，如果您使用 Compose 和 CameraX，現在可以透過新的 Alpha 版 Compose 優先程式庫 androidx.camera:camera-compose，這會提供 CameraXViewfinder 可組合函式，這是 Compose 慣用的觀景窗，可將 CameraX 的 SurfaceRequest 調整為 Compose，類似於 PreviewView 的 Views 運作方式。