適用於 XR 的 Jetpack Compose

以宣告式方式建構空間 UI 版面配置，充分運用 Android XR 的空間功能。
最近更新時間 穩定版 候選版 Beta 版 Alpha 版
2025 年 5 月 7 日 - - - 1.0.0-alpha04

宣告依附元件

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

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

GroovyKotlin 
dependencies {
    implementation "androidx.xr.compose:compose:1.0.0-alpha04"

    // Use to write unit tests
    testImplementation "androidx.xr.compose:compose-testing:1.0.0-alpha04"
}
 
dependencies {
    implementation("androidx.xr.compose:compose:1.0.0-alpha04")

    // Use to write unit tests
    testImplementation("androidx.xr.compose:compose-testing:1.0.0-alpha04")
}

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

意見回饋

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

建立新問題

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

1.0 版本

1.0.0-alpha04 版本

2025 年 5 月 7 日

發布 androidx.xr.compose:compose:1.0.0-alpha04 和 androidx.xr.compose:compose-testing:1.0.0-alpha04。1.0.0-alpha04 版包含這些修訂版本。

新功能

  • 新增 CompositionLocalConsumerSubspaceModifierNode 介面，讓自訂 SubspaceModifier 類型存取組合本機值。
  • 新增了 SpatialPanel API，遵循 Compose AndroidView 實作樣式，並淘汰先前的 ViewBased SpatialPanel。
  • 新增代表無限約束條件的 VolumeConstraints.Unbounded 隨附物件。
  • 新增 SubspaceModifier.onPointSourceParams，允許使用空間化音訊來源。
  • 我們已新增公開 ApplicationSubspace，提供選用的 VolumeConstraints，用於定義應用程式可轉譯空間內容的 3D 區域。根據預設，如果未指定限制條件，子空間的寬度和高度會受限於 SpatialUser 目前的視野範圍。如果無法判斷視野範圍，使用者可以提供要使用的限制條件。否則，系統會使用預設的視野寬度和高度值。
  • 新增 SpatialExternalSurface，可用於算繪立體內容。SpatialExternalSurface 可透過修飾符 (alpha 除外) 和邊緣羽化效果進行自訂。
  • 新增 pointerHoverIcon 子空間修飾符，讓使用者設定空間指標的圖示。

API 變更

  • 已針對所有 Jetpack XR 套件移除 RequiresApi(34) 限制。由於 Jetpack XR 目前僅適用於 API 級別 34 以上的裝置，因此這項限制已不必要 (Iae0f8)。
  • 使用 Kotlin 2.0 發布的專案需要使用 KGP 2.0.0 以上版本。(Idb6b5)。
  • 返回處理功能現在可在沒有嵌入活動的空間面板上運作。如要讓返回處理功能正常運作，您必須在 Android 資訊清單中指定 android:enableOnBackInvokedCallback="true"。
  • 回傳處理功能現在可用於空間對話方塊。如要讓回溯處理功能運作，您必須在 Android 資訊清單中指定 android:enableOnBackInvokedCallback="true"。
  • 以 Compose 和 View 為基礎的 SpatialPanel 現在可以根據內容自行調整大小。
  • 開發人員現在可以自行設定 SpatialElevationLevel 值，不必侷限於預先定義的等級。
  • 您現在可以透過 elevation 參數自訂 Orbiter 的高度。
  • 子空間現在可以根據 SpatialUser 的視野範圍，在寬度和高度上受到限制。如果無法判斷視野範圍，系統會使用預設的視野範圍寬度和高度值。
  • 已將新的回呼 onMoveStart 和 onMoveEnd 新增至 Movable 修飾符。當使用者開始和結束使用可移動修飾符移動子集可組合項時，系統會呼叫 onMoveStart 和 onMoveEnd 回呼。
  • name 參數已從 SpatialRow 和 SpatialPanel 等空間 API 中移除。如要偵錯空間組合樹狀結構，請改用 SubspaceModifier.testTag。
  • 移除僅有 spatialElevationLevel 和 content 的 SpatialPopup 超載，因為這類超載不受支援。請使用支援 onDimissRequest 的介面。
  • 已移除 Movable 修飾符中的 onPoseChange 回呼。改用 onMove。
  • 如果 SubspaceModifiers 已分離或正在分離，就不會再套用效果。
  • 現有的 SpatialRow API 已分割為 SpatialRow 和 SpatialCurvedRow。如果先前使用 SpatialRow 的 curveRadius 參數，現在請改用 SpatialCurvedRow，因為這兩者提供相同的行為。
  • 在最近的類似系統映像檔上執行時，MainPanel 和 ActivityPanel 不再顯示標題列。
  • Alpha 和比例修飾符現在可堆疊，且會將其值相乘，以便套用最終 Alpha 或比例值。
  • 我們已對 Movable 修飾符的 onPoseChange 回呼進行最佳化，以便執行更流暢的姿勢移動。
  • 可移動和可調整大小的修飾符現在會在主執行緒上執行回呼，確保狀態變更會觸發重組。
  • 在版面配置和測量階段新增狀態觀察功能，確保 SubspaceLayout 中的狀態變更會觸發重新版面配置。
  • 更新最佳化修飾符鏈結，以便更有效地重複使用現有的修飾符。

修正錯誤

  • 在顯示 SpatialDialog 時停止裁剪。(Ic4594)。
  • 系統現在會忽略在分離修飾符節點時提出的重新排版要求。
  • 移除由可移動和可調整大小修飾符觸發的重排版階段。
  • 修正 MainPanel() 可組合項中，當任一維度直接設為零或在版面配置計算期間 (例如 SpatialRow/SpatialColumn 計算) 發生當機的問題。面板現在會改為隱藏。請注意，這項修正特別針對版面配置階段發生的當機問題；透過使用者互動將面板大小調整為零的情況會另外處理。隱藏的面板缺少 UI 操作元素。
  • 修正了可調整大小修飾符的 maintainAspectRatio 問題。顯示比例現在應該會維持不變。
  • 修正巢狀子空間的問題，這些子空間會在單一影格中錯誤定位。
  • 修正在應套用圓角時，有時未套用圓角的問題。
  • NestedSubspaces 不會再出現在錯誤位置的一個影格。

1.0.0-alpha03 版本

2025 年 2 月 26 日

發布 androidx.xr.compose:compose:1.0.0-alpha03 和 androidx.xr.compose:compose-testing:1.0.0-alpha03，此兩版與上一個 Alpha 版沒有差別。1.0.0-alpha03 版包含這些修訂版本

1.0.0-alpha02 版

2025 年 2 月 12 日

發布 androidx.xr.compose:compose:1.0.0-alpha02 和 androidx.xr.compose:compose-testing:1.0.0-alpha02。1.0.0-alpha02 版包含這些修訂項目。

新功能

  • 啟用空間對話方塊時，活動面板現在可以遮蔽內容。
  • Orbiter API 現在可在 SubspaceComposable 情境中使用，並會將 Orbiter 附加至最近的 SubspaceLayout 可組合項父項。
  • 推出 LayoutCoordinatesAwareModifierNode，允許自訂以位置為準的修飾符。
  • 已將附加/卸除生命週期方法新增至 SubspaceModifier.Node。
  • 在可移動修飾符中新增 scaleWithDistance。啟用 scaleWithDistance 後，移動的子區元素會擴大或縮小。並保留移動前設定的任何明確比例。

API 變更

  • 移除 SessionCallbackProvider，改用 SpatialCapabilities。

其他變更

  • 將 minSDK 降至 24。所有 Jetpack XR API 在執行階段仍需要 API 34。
  • Orbiter EdgeOffset.inner、EdgeOffset.outer 和 EdgeOffset.overlap 建構函式不再是 @Composable 方法，因此可用於非可組合函式內容。
  • 更新空間標高層級，以符合最新的使用者體驗規格。
  • 將 SubspaceSemanticsInfo 介面導入 MeasurableLayout。
  • SubspaceModifierElement 已重新命名為 SubspaceModifierNodeElement。

修正錯誤

  • 修正 SubspaceModifier 排序問題，SubspaceModifier 應可靠地運作。偏移、旋轉、縮放、可移動和可調整大小的輔助鍵現在應該可以以任何順序使用。

1.0.0-alpha01 版

2024 年 12 月 12 日

發布 androidx.xr.compose:compose-*1.0.0-alpha01。

初始版本的功能

  • 適用於 XR 的 Jetpack Compose 初始開發人員版本。無論您是要將現有的 2D 應用程式移植至 XR，或是從頭開始建立新的 XR 應用程式，都可以使用熟悉的 Compose 概念 (例如資料列和欄)，在 XR 中建立空間 UI 版面配置。這個程式庫提供子空間和空間可組合項，例如空間面板和軌道器，可讓您將現有的 2D Compose 或以 View 為基礎的 UI 放置在空間版面配置中。這項功能會引入 Volume 子空間可組合項，讓您可以相對於 UI 放置 SceneCore 實體 (例如 3D 模型)。詳情請參閱這份開發人員指南：

    • Subspace：這個可組合函式可放置在應用程式 UI 階層中的任何位置，讓您維護 2D 和空間 UI 的版面配置，而不會在檔案之間遺失內容。這樣一來，您就能更輕鬆地在 XR 和其他板型之間共用現有應用程式架構，而不需要透過整個 UI 樹狀結構提升狀態，或重新設計應用程式。

    • SpatialPanel：SpatialPanel 是一種子區塊可組合項，可用於顯示應用程式內容，例如在 SpatialPanel 中顯示影片播放、靜態圖片或任何其他內容。

    • Orbiter：Orbiter 是空間 UI 元件。這個類別的設計目的是附加至對應的空間面板，並包含與該空間面板相關的導覽和情境動作項目。舉例來說，如果您已建立用於顯示影片內容的空間面板，就可以在軌道器中新增影片播放控制項。

    • Volume：相對於使用者介面放置 SceneCore 實體 (例如 3D 模型)。

  • 空間版面配置： 您可以使用 SpatialRow、SpatialColumn、SpatialBox 和 SpatialLayoutSpacer 建立多個空間面板，並將這些面板放置在空間版面配置中。使用 SubspaceModifier 自訂版面配置。

  • 空間 UI 元件：這些元素可在 2D UI 中重複使用，且只有在啟用空間功能時，其空間屬性才會顯示。

    • SpatialDialog：面板會在 z 深度中稍微向後推，以便顯示升高的對話方塊。
    • SpatialPopUp：面板會在 z 深度中稍微往後推，以便顯示升高的彈出式視窗
    • SpatialElevation：SpatialElevationLevel 可設為新增高度。

  • SpatialCapabilities：Spatial Capabilities 會隨著使用者與應用程式或系統互動而變更，甚至可能會由應用程式本身變更，例如進入首頁空間或全螢幕模式。為避免發生問題，應用程式需要檢查 LocalSpatialCapabilities.current，以判斷目前環境支援哪些 API。isSpatialUiEnabled：空間 UI 元素 (例如 SpatialPanel) isContent3dEnabled：3D 物件 isAppEnvironmentEnabled：環境 isPassthroughControlEnabled：應用程式是否可控制傳送狀態 isSpatialAudioEnabled：空間音訊

已知問題

  • 目前，您必須使用 30 以上的最低 SDK 版本，才能使用 Jetpack Compose 開發 XR 應用程式。解決方法是新增下列資訊清單項目 <uses-sdk tools:overrideLibrary="androidx.xr.scenecore, androidx.xr.compose"/>，以便以 23 的 minSDK 建構及執行。
  • Jetpack XR 應用程式目前需要在 AndroidManifest 中要求 android.permission.SCENE_UNDERSTANDING 權限。
  • 當應用程式使用資訊清單中的 PROPERTY_XR_ACTIVITY_START_MODE 屬性直接啟動至完整空間時，活動/應用程式會先在首頁空間中開啟，然後再轉換至完整空間。
  • 體積可組合項中的 glTF 可能一開始會在錯誤的位置閃爍。
  • 如果在大幅移動的面板中使用 SpatialDialog，內容會推送至錯誤的方向。