相機觀景窗

  
獨立的可組合函式和以 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-beta03androidx.camera.viewfinder:viewfinder-core:1.5.0-beta03androidx.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 搭配使用。這項變更可確保透過實作 AndroidViewonReset 回呼,成功重設 Composable,同時支援 EMBEDDEDEXTERNAL 實作。(I0d9be)
  • 修正 Android 10/11 的問題:由於轉換作業 (例如縮放或平移) 套用時間過早,EXTERNAL Viewfinder 可能會顯示拉伸或錯誤。系統現在會等待建立 Surface,然後在版面配置階段套用這些轉換,確保輸出內容正確無誤。(Icc77c)

1.5.0-beta02 版

2025 年 6 月 4 日

發布 androidx.camera.viewfinder:viewfinder-compose:1.5.0-beta02androidx.camera.viewfinder:viewfinder-core:1.5.0-beta02androidx.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-beta01androidx.camera.viewfinder:viewfinder-core:1.5.0-beta01androidx.camera.viewfinder:viewfinder-view:1.5.0-beta01。1.5.0-beta01 版包含這些修訂項目

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

新功能

  • 您現在可以在以 Compose 為基礎的觀景窗中使用 ContentScaleAlignment,在容器中縮放及放置顯示的表面,與 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-alpha13androidx.camera.viewfinder:viewfinder-core:1.4.0-alpha13androidx.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-alpha12androidx.camera.viewfinder:viewfinder-core:1.4.0-alpha12androidx.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 版的預設值)。(I7bcd7b/326456246)

1.4.0-alpha11 版

2024 年 12 月 11 日

發布 androidx.camera.viewfinder:viewfinder-compose:1.4.0-alpha11androidx.camera.viewfinder:viewfinder-core:1.4.0-alpha11androidx.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-alpha10androidx.camera.viewfinder:viewfinder-core:1.4.0-alpha10androidx.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-alpha09androidx.camera.viewfinder:viewfinder-core:1.4.0-alpha09androidx.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-alpha08androidx.camera.viewfinder:viewfinder-core:1.4.0-alpha08androidx.camera.viewfinder:viewfinder-view:1.4.0-alpha08。1.4.0-alpha08 版包含這些修訂項目

新功能

更新至 1.4.0-alpha08 後,CameraX Viewfinder 構件已移至專屬程式庫群組。這項變更有助於提升 CameraX 程式庫的模組化程度和可維護性。

如果您先前依附於 androidx.camera:camera-viewfinderandroidx.camera:camera-viewfinder-composeandroidx.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 運作方式。