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

相機觀景窗

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

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

構件	穩定版	候選版	Beta 版	Alpha 版
viewfinder-compose	1.5.0	-	-	1.4.0-alpha13
viewfinder-core	1.5.0	-	-	1.4.0-alpha13
viewfinder-view	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")


}

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

意見回饋

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

建立新問題

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

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，這是 Compose 慣用的觀景窗，可與 CameraX SurfaceRequest 順暢整合，類似於 PreviewView 適用於以 View 為基礎的版面配置。其中幾項重大變更包括：

構件重新放置：為提升模組化程度，觀景窗構件已移至專屬程式庫群組。先前使用 androidx.camera:camera-viewfinder* 依附元件的開發人員應遷移至 androidx.camera.viewfinder:viewfinder-*。
API 穩定性和改良：這個穩定版已改善 API 介面。包括將 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 模式)。但開發人員仍可覆寫這項行為，取得完整控制權。

修正錯誤

可組合項 Viewfinder 現在可在 Compose 的 Pager 內和 movableContentOf() 中正常運作，確保在複雜的 UI 情況下，介面能正確重設及管理。(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 版包含這些修訂項目。

修正錯誤

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

修正錯誤

現在，系統會根據預設 ImplementationMode，在 Viewfinder (Compose 和以檢視區塊為基礎) 中，智慧地選取 EXTERNAL (提升效能) 和 EMBEDDED (適用於舊版 API/異常裝置)。您還是可以透過 ViewfinderSurfaceRequest 或 XML 屬性 (在以 View 為基礎的 API 上) 中的明確設定，覆寫這項行為。(Iecd3a)
使用 API 29 以上版本時，允許 ViewfinderSurfaceSession 在 Surface 建立/終止生命週期中保持運作，藉此改善 Surface 工作階段管理。這項功能適用於 TextureView 或 SurfaceView。(I112d9)
Viewfinder 現在可確保 Surface 在適當時間釋出，只有在工作階段不再使用時才會釋出，而不是在 Composable 遭到處置時一律釋出。對於 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 現在所有引數都有預設值。這樣一來，您就能建立不含任何 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 運作方式。