適用於 XR 的 Jetpack Compose

宣告依附元件

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

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

dependencies {
    implementation "androidx.xr.compose:compose:1.0.0-alpha05"

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

dependencies {
    implementation("androidx.xr.compose:compose:1.0.0-alpha05")

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

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

意見回饋

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

建立新問題

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

1.0 版本

1.0.0-alpha05 版本

2025 年 7 月 30 日

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

新功能

• 已將 SubspaceComposable 註解類別設為公開。(Ic2a34、b/399432430)
• 兩個新的 SpatialExternalSurface 可組合項，分別代表 180 度和 360 度的球體。(I40ef2、b/391705799)
• 新增 SubspaceModifier.aspectRatio (Ide5ab、b/399729509、b/414762147)
• 新增 SceneCoreEntity API，提升 SceneCore 與 XR 版 Compose 之間的互通性。(I50bb3、b/423020989)
• 提供 GravityAlignedsubspace API，支援未縮放的 And GravityAligned 功能 (I07359)

API 變更

• SpatialDialog() 會遵循 SpatialDialogProperties.dismissOnBack 按鈕設定。(Ib453b、b/416797132)
• 由於「公尺」的表示方式，請將 minimumPanelDimension 更新為新的預設維度大小 Dimensions(0.1f, 0.1f, 0.1f)。(Ib852a)
• 子空間和 Orbiters 現在會在主空間和應用程式於背景執行時，保留內部狀態。在首頁空間模式下，Subspace 仍會設定場景，準備切換至完整空間模式。(I40317、b/416037751)
• 應用程式在背景執行時，SpatialDialogs 現在會保留狀態。(I6aa56)
• ApplicationSubspace 現在會從系統沿用建議的比例和位置。(I4565f、b/418834194)
• 如果在非 SubspaceComposable 環境中使用 SubspaceComposable，系統會顯示更明確的錯誤訊息，並提早觸發錯誤。(Iee2ae、b/416484684)
• 將 ExperimentalSubspaceVolumeApi 從「警告」更新為「錯誤」，因為誤用可組合 API 時，警告通常會遭到忽略。(I427aa、b/424864286)
• Subspace 和 ApplicationSubspace 現在受 recommendedContentBoxInFullSpace 限制。先前是受 SpatialUser 的視野限制。(I41015、b/423074142)
• 更新 SpatialElevation 以使用最小尺寸，不再使用硬式編碼尺寸 (I2dbe6、b/427785338)
• 更新我們遮蓋 SpatialAcitivityPanel 的方式，以便在修改重要變數時更新。(I0f64d、b/427999029)
• 請移除 VolumeConstraints.Unbounded，改為將預設限制值設為等效值。(Ie24ec、b/407938414)
• SpatialFeatheringSize 不再公開 (I1c15b、b/399432430)
• 已將 XR Placeable 重新命名為 SubspacePlaceable，以區別於 Compose 的 Placeable。(I74874)
• 移除 Orbiter 設定，並新增 shouldRenderInNonSpatial 做為新參數。此外，我們也移除了 EdgeOffset 類別，並新增 orbiterOffsetType 做為新參數，以整合 Orbiter() 函式。並將 OrbiterEdge 重新命名為 ContentEdge。(Iebf3d)
• 已將 Measurable 重新命名為 SubspaceMeasurable，以區別類型與 Compose 的 Measurable 類型。(I9726c)
• 將 MeasureResult 重新命名為 SubspaceMeasureResult (I9f34d)
• 移除 setSubspaceContent API，改用 Compose 的 setContent 和 Subspace 可組合函式。(Ifff4c、b/421427391、b/421427391)
• MeasurePolicy 已重新命名為 SubspaceMeasurePolicy。(I37a9b、b/422553904)
• 將 SubspaceSemanticsInfo 設為密封介面，因為沒有預設值就無法新增成員。(I372f9、b/423704068)
• 更新 SpatialExternalSurface 說明文件，並將 ContentSecurityLevel 重新命名為 SurfaceProtection (I3c460、b/420982808)
• 為可移動的修飾符提供多載建構函式，可進行錨定。(Ic0c70)
• 為工具提示新增更多位置供應器，開發人員現在可以控制工具提示是否要放在錨點上方、下方、左側或右側。新增可接收插入號 Shape 的 API，以便提供更多自訂形狀。(Ie513c、b/374766087、b/418854637)
• 移除 CoreEntity 做為 PublishedApi (Ifee05)

修正錯誤

• 修正 SpatialDialog 在轉譯時會閃爍的問題。(Ife73c、b/401619909)
• 修正 SpatialDialog 無法遮蓋 Activity 面板的問題。(I8ca6c、 b/367442109)
• 修正 XR 對話方塊未顯示部分內容的問題 (I17cd5、b/418062437)
• 修正問題：點選內容內時，SpatialPopup 會遭到關閉。(If262c、b/417245722)
• 修正問題：鏈結 resizable().movable() 時，SpatialPanel 無法正確調整大小。(I02ee3、b/422264230)
• 修正 SpatialComposeVideoPlayer 中 topBar 與選單重疊的問題 (Id33bc、b/427168167)
• 修正圓角半徑未轉譯的問題 (I975fe、b/428261830)

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 區域。根據預設，如果未指定任何限制，Subspace 的寬度和高度會受限於 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 參數自訂軌道飛行器的高度。
• 現在，子空間預設會以 SpatialUser 的視野寬度和高度為界。如果無法判斷視野，系統會使用預設的視野寬度和高度值。
• 在 Movable 修飾符中新增 onMoveStart 和 onMoveEnd 回呼。當使用者開始和結束使用可移動修飾符移動子空間可組合函式時，系統會呼叫 onMoveStart 和 onMoveEnd 回呼。
• name 參數已從空間 API (例如 SpatialRow 和 SpatialPanel) 中移除。如要偵錯空間組合樹狀結構，請改用 SubspaceModifier.testTag。
• 已移除 SpatialPopup 的不支援超載，該超載僅具有 spatialElevationLevel 和 content。請使用支援 onDimissRequest 的介面。
• 已移除 Movable 修飾符的 onPoseChange 回呼。改用 onMove。
• 如果 SubspaceModifiers 已卸離或目前正在卸離，就不會再套用效果。
• 現有的 SpatialRow API 已分割成 SpatialRow 和 SpatialCurvedRow。如果先前使用 SpatialRow 的 curveRadius 參數，請改用 SpatialCurvedRow，兩者行為相同。
• 在類似的最新系統映像檔上執行時，MainPanel 和 ActivityPanel 不再有標題列。
• Alpha 和縮放比例修飾符現在可以堆疊，並將值相乘，做為最終套用的 Alpha 或縮放比例值。
• 我們已最佳化 Movable 修飾符的 onPoseChange 回呼，可執行更流暢的姿勢動作。
• 可移動和可調整大小的修飾符現在會在主執行緒上執行回呼，確保狀態變更會觸發重組。
• 在版面配置和測量階段新增狀態觀察，確保 SubspaceLayout 中的狀態變更會觸發重新配置。
• 最佳化修飾符鏈結更新，可更妥善地重複使用現有修飾符。

修正錯誤

• 顯示 SpatialDialog 時停止半透明遮罩。(Ic4594)
• 現在系統會忽略修飾符節點分離時提出的重新配置要求。
• 移除了由 Movable 和 Resizable 修飾符觸發的重新配置階段。
• 修正 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 環境中使用，並將 Orbiters 附加至最接近的 SubspaceLayout 型可組合項父項。
• 導入 LayoutCoordinatesAwareModifierNode，允許自訂位置型修飾符。
• 在 SubspaceModifier.Node 中新增附加/卸離生命週期方法。
• 在可移動修飾符中新增 scaleWithDistance。啟用 scaleWithDistance 後，移動的子空間元素會放大或縮小。也會維持移動前使用的任何明確比例。

API 變更

• 已移除 SessionCallbackProvider，改用 SpatialCapabilities。

其他變更

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

修正錯誤

• 修正問題，確保 SubspaceModifier 訂購流程穩定運作。SubspaceModifier 的行為應更可靠。現在可以依任意順序使用偏移、旋轉、縮放、可移動和可調整大小的修飾符。

1.0.0-alpha01 版

2024 年 12 月 12 日

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

初始版本的功能

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

  • Subspace：這個可組合函式可放置在應用程式 UI 階層中的任何位置，讓您維護 2D 和空間 UI 的版面配置，且不會遺失檔案之間的內容。這樣一來，您就能輕鬆在 XR 和其他外型規格之間共用現有應用程式架構等項目，不必透過整個 UI 樹狀結構升級狀態，也不必重新建構應用程式。

  • SpatialPanel：空間面板是子空間可組合項，可讓您顯示應用程式內容，例如在空間面板中顯示影片播放畫面、靜態圖片或任何其他內容。

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

  • 音量：相對於 UI 放置 SceneCore 實體，例如 3D 模型。

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

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

  • SpatialDialog：面板會在 Z 深度中稍微往後推，顯示高架對話方塊。
  • SpatialPopUp：面板會在 Z 深度中稍微往後推，以顯示高架彈出式視窗
  • SpatialElevation：可以設定 SpatialElevationLevel 來新增海拔高度。

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

已知問題

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