適用於 XR 的 Jetpack Compose

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

宣告依附元件

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

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

Groovy

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

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

Kotlin

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

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

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

意見回饋

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

建立新問題

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

1.0 版本

1.0.0-beta01 版

2026 年 9 月 23 日

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

API 變更

  • 已移除已淘汰的 DragPolicy。請改用 SubspaceModifier.movable()。(I108d4)
  • 移除了已淘汰的 ResizePolicy，以及 SpatialPanel 和 SpatialExternalSurface 中的用法。移除已淘汰的 SubspaceModifier.resizable 函式。請改用新的 SubspaceModifier.resizable 和新的 ResizePolicy。(I59e6b)
  • 新增 isPitchUpdateEnabled 參數，可獨立啟用或停用音高追蹤功能。(Ie9e86)
  • 移除了 pitchLimits 的可為空值性，並將 PitchLimits.UNCONSTRAINED 重新命名為 PitchLimits.FullRange。(I0154f)
  • ExposedDropdownMenu 現在是 ExposedDropdownMenuBoxScope 的擴充功能函式，而非成員。您可能需要使用新的匯入項目更新程式碼。(Ie8a65)
  • 已移除已淘汰的 SurfaceProtection 類別。請改用 SpatialExternalSurfaceProtection。(Iab2c6)
  • 已淘汰採用 OrbiterPoseProvider 的 Orbiter 函式，請改用採用 SpatialAlignment 的函式。(I4d12b)
  • SpatialActivityPanel 現在需要 SpatialActivityPanelController (使用 rememberSpatialActivityPanelController 例項化) 才能啟動及管理內嵌活動。(Id25c6)
  • 從 rotateToLookAtUser 移除 upDirection 參數，並新增旋轉限制參數 (isYawUpdateEnabled 和 pitchLimits)。(I1370a)

修正錯誤

  • 修正各種 InteractionPolicy 問題。如果輸入事件發生時，可組合項或子項 (例如 Orbiter) 剛好啟動處置序列，就會發生當機情形。此外，也修正了子項會收到懸停事件的問題。(Ifc477)
  • 縮減 RotateToLookAtUserActivity 中的面板大小，避免在視野較小的裝置上遭到裁剪。(I8d672)

已知問題

  • Compose XR 面板存在問題，在單一活動中建立多個面板時，即使面板已毀損，所檢視的內容仍可能出現部分損毀。

1.0.0-alpha17 版本

2026 年 8 月 12 日

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

API 變更

  • 移除 Meter 值類別，Scenecore 中的 virtualPixelDensity 會取代該類別。(I690ee)
  • SpatialGltfModel API 目前處於實驗階段，必須選擇加入才能使用。(I4557e)
  • 將 system 設為可調整大小的可為空值 (Ib0093)
  • 公開 Density 中的 SubspaceSemanticsInfo 以進行測試。(I2e826)
  • 將 ResizePolicy 預設選項重新命名為 system，並新增不含參數的 Default 選項 (Ic8b16)
  • 將 FollowTarget 標示為實驗性質。整個 FollowingSubspace API 現在都處於實驗階段。(Id4ee3)
  • 移除 GltfAnimation API (Ic2894)
  • 已將參數化 MovePolicy.default() 方法重新命名為 MovePolicy.system()。推出 val MovePolicy.Default 屬性，代表標準預設移動行為。(Iedcc9)
  • 將 ExperimentalMoveAnchorPolicy 選擇加入規定擴展至 PlaneSemantic 和 PlaneOrientation (Ief927)
  • 從 VolumeConstraints.offset 移除 resetMins (Ib2f2f)
  • 已移除淘汰的 SceneCoreEntitySizeAdapter 函式。(Ib6722)
  • 已移除淘汰的 Subspace 超載 (使用 allowUnboundedSubspace)。(I8e97f)
  • 移除了已淘汰的語意修飾符超載。(I4ac10)

修正錯誤

  • 修正問題：附加 InteractionPolicy 的 Composable 子項會觸發輸入事件 (Icdba6)

1.0.0-alpha16 版本

2026 年 7 月 15 日

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

API 變更

  • 移除 ComponentOverride API (I820c4)
  • GltfAnimation 和 SpatialGltfModelAnimation API 已標示為實驗性質。部分屬性已轉換為 getter。(I8d689、b/524771027)
  • 建立公尺和像素之間的轉換，修正整體密度行為。已淘汰的 Meter.kt，現在可以改用 Session.scene.virtualPixelDensity。(I122ff、b/430097855、b/474168798)
  • 更新可調整大小的修飾符，改用 ResizePolicy，而非兩個修飾符 (I7fb0f、b/496257436、b/519672992)
  • 在 SubspaceAssertions.kt 中，為所有公開的浮點維度和位置等式判斷，新增容差：Dp = Dp(0.5f) 參數。預設容差行為 (0.5.dp) 已完整記錄在文件中。(I266cb、b/521491915)
  • 新增具有 movePolicy 參數的可移動超載，並淘汰 transformingMovable 和 movable (Ic88c1、b/481781189)
  • 新增標準清單項目和區隔清單項目的非互動式變體，符合 Material Expressive 規格。非表情符號版本已淘汰，(Ide4de、b/491994186)
  • 對於子空間，allowUnboundedSubspace 參數現已淘汰並隱藏。現在應使用 Subspace 修飾符的 SubspaceModifier.requiredSizeIn(maxWidth = Dp.Infinity、maxHeight = Dp.Infinity、maxDepth = Dp.Infinity) 達成無界行為。allowUnboundedSubspace 參數已從 FollowingSubspace 中移除。(Ia72ae、b/433624021)
  • 已將 Session.create 轉換為暫停函式。(I5d27f)
  • 新增 SubspaceModifier.spatializedAudioOutput，可透過 ExoPlayer 或 SoundEffectPlayer 空間化音訊播放 (I46697、b/489421980、b/497867019)
  • 更新 ComponentActivity.requestHomeSpace() 和 requestFullSpace()，傳回 SpaceRequestResult 以驗證狀態。(If1672)
  • 已將 AnchorEntity 更新為 AnchorSpace (Ifa95e、b/513619219)
  • 解除 SpatialGltfModelSource 的 fromResource 方法限制 (I1f5a1、b/503047416)
  • SubspaceSemanticsMatcher 成員為公開：description 屬性、隨附的工廠方法 (expectValue、keyIsDefined、keyNotDefined)、成員函式 (matches、matchesAny) 和運算子 (and、or、not)。(I972a4、b/460427288)
  • 更新 SubspaceModifier.semantics、SubspaceModifier.testTag、SubspaceSemanticsInfo、SubspaceSemanticsModifierNode，使用精選的空間語意類型。(I80dea、b/460427288)
  • 已將 SpatialAlignment 中的 position 重新命名為 align，並移除個別方向的位移方法，改用統一的 align API。(I9bdb2、b/479805937)
  • 從 SpatialConfiguration 移除已淘汰的 Space Mode API。(I1ef5c、b/458712461)
  • SubspaceSemanticsConfiguration 導入。這是 Spatial 節點的語義屬性設定。這個類別會安全地公開 3D 語意查詢方法，不會將基礎 2D 語意功能洩漏給外部消費者。(Id025e、b/460427288)
  • 推出 SubspaceSemanticsPropertyReceiver：專用包裝函式，可將 3D 版面配置容器屬性限制為有效欄位 (最初為 testTag 和 contentDescription)。(I5cf5c、b/460427288)

修正錯誤

  • 更新了語意修飾符的 hasContentDescription，預設為子字串比對。(I08214)
  • 新增受限制的 FollowBehavior.ExponentialDecay()，可提供由彈性物理引導的軟性追蹤行為。(I7449c、b/485639909、b/500493335)

大多數 API 都會受到影響。具體來說，LocalSession CompositionLocal 和所有依附於 LocalSession 的 CompositionLocals (例如 LocalSpatialConfiguration、LocalSpatialCapabilities 等)，現在都會在 Session 初始化前解析為 null 或非 XR 版本。

Session 可用後，系統會以正確狀態觸發重新組合作業。(I0cfa4、b/514712835、b/514712835)

  • 釐清 ComponentActivity.requestHomeSpace 和 ComponentActivity.requestFullSpace 的說明文件，說明暫停行為、取消和並行。更新了測試，驗證 CancellationException 傳播情形。(I22f75、b/493289528)

1.0.0-alpha15 版本

2026 年 6 月 17 日

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

API 變更

  • 淘汰 ResizePolicy 和舊版可調整大小的修飾符，並替換為新的 SubspaceModifier.resizable 多載和 SubspaceModifier.transformingResizable。(I9e4bc)
  • 更新 SpatialGltfModel API：新增透過 SpatialGltfModelSource.fromResource 從資源載入模型的支援。在 SpatialGltfModelAnimation 中將速度重新命名為 playbackSpeed，並新增 resume() 方法。SpatialGltfModelStatus。Loaded 和 Loading 現在是物件。(I523de)
  • 將 rotateToLookAtUser 標示為實驗性 API。(I86c16)
  • 已將受保護的變數 targetCurrentPose 移至區域變數 currentTargetPoseMeter，並重新命名。(Ia557c)
  • 更新 SpatialPanel 和 SpatialExternalSurface kdoc，加入物件在版面配置大小內算繪的位置 (I72104)
  • 在 SpatialGltfModelState 中封裝 SpatialGltfModel 載入邏輯，並說明失敗行為。(Ibe98b)
  • 在 SubspaceModifer.size KDoc 中說明 depth (I0f84f)

1.0.0-alpha14 版本

2026 年 5 月 19 日

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

API 變更

  • 推出 transformingMovable，用於預設系統處理的 3D 動作，並推出 movable 的新多載，用於處理自訂動作行為。(I50960)
  • 已移除「SpatialGltfModel.fromData()」，(I4d083)
  • 新增修飾符節點介面 SubspaceMeasuredSizeAwareModifierNode，可在測量階段後提供 onRemeasured 回呼。SubspaceLayoutAwareModifierNode 現在會擴充這個新介面。onSizeChanged 修飾符已更新為使用 onRemeasured，確保回呼會在測量後立即觸發，而非在放置後觸發。(Iafbae)
  • 已將 InteractionPolicy 更新為 Interface (I0ff30)
  • 將 Compose compileSdk 更新至 API 37。也就是說，使用 Compose 時，AGP 最低版本必須為 9.2.0。(Id45cd)
  • 更新 Size KDoc (Iefa9a)

1.0.0-alpha13 版

2026 年 5 月 6 日

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

API 變更

  • Orbiter API 尚待進一步變更，建議您暫時隱藏 Orbiter 的淘汰通知，並密切注意後續版本中的 Orbiter 變更。
  • 使用 SceneCoreEntity 轉譯 glTF 的使用者應確保將 session.scene.activitySpace 傳遞至 GltfModel.create 呼叫的 parent 參數，確保 glTF 會轉譯。
  • 新增 SpatialGltfModel API，方便開發人員將 Gltf 新增至 Compose For XR 應用程式。開發人員也可以查詢 Gltf 模型中的動畫和節點。(I8b542、b/495422586)
  • 將 SceneCoreEntitySizeAdapter 從類別變更為介面 (I5a784、b/475292310)
  • SurfaceProtection 已重新命名為 SpatialExternalSurfaceProtection。更新 SpatialExternalSurface KDoc (Ifad0a、b/485231082)
  • 淘汰 currentWindowAdaptiveInfo 並推出 V2 版 (I40ecf、b/424442112)
  • resizable 修飾符現已公開，適用於群組 (例如 SpatialRow)。(I2bcf6、b/348483527、b/489753178、b/479530787)
  • movable 修飾符現已公開。目前這個修飾符適用於 SpatialPanels 和 SpatialExternalSurface，但我們希望所有 SubspaceComposables 都能支援這個修飾符。(I9a3cd、b/479530787、b/478935063、b/478935063)
  • SpatialEnterTransition 和 SpatialExitTransition 標示為 @Immutable (If1710、b/487757837)
  • SpatialGltfModel API 在這個版本中標示為受限，等待額外測試。(Ibf003、b/466090694)
  • 已將 DeviceTrackingMode.LAST_KNOWN 重新命名為 SPATIAL_LAST_KNOWN (並加入已淘汰的備用廣告)、為 3DoF 追蹤新增 INERTIAL_LAST_KNOWN，以及在 TrackingState 中新增 TRACKING_DEGRADED。(Ie661c、b/445466590)
  • 移除已淘汰的 SpatialLayoutSpacer (I7b36c)
  • 移除已淘汰的邊框間距 API (If1886)
  • 已將 floatRange 新增至偏差值。移除 LayoutDirection 的預設值 (I9d74e)

修正錯誤

  • 新增 SpatialColumn、SpatialRow 和 SpatialCurvedRow 的程式碼範例和 KDoc 說明文件。(Iaf54f、b/495777633)

1.0.0-alpha12 版

2026 年 3 月 25 日

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

API 變更

  • 新增 SpatialGltfModel API 和 SpatialGltfModelAnimation API，以便轉譯 glTF 和控制動畫。已將 SpatialGltfModelState 變更為 AutoCloseable，現在必須關閉才能釋放資源。(I11fde、b/466065486、b/481379924)。不過，SpatialGltfModel API 在這個版本中標示為受限，需要經過額外測試。(Ibf003、b/466090694)
  • 為 SubspaceModifier.rotate 新增已淘汰的空白超載。(Idceb6)
  • 已將 SpatialSmoothFeatheringEffect 函式重新命名為 spatialSmoothFeatheringEffect，並移至繪圖模組。已將 SpatialExternalSurface 預設羽化值更新為空值，模擬舊版 ZeroFeatheringEffect 功能。(I5fdaa、b/460426800)
  • 已移除 onPointSourceParamsAvailable。我們將在不久的將來推出其他音訊空間化 API。(I86507、b/458513439)
  • 已為偏移子空間修飾符新增 RTL 行為。此外，還新增了 absoluteOffset，可忽略版面配置方向。(I30e4b、b/474409165)

1.0.0-alpha11 版本

2026 年 2 月 25 日

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

新功能

  • 將 SuperSampling 參數新增至 SpatialExternalSurfaces (Icd4d1)

已知問題

  • SceneCore 中的 SurfaceEntity 問題可能會導致應用程式在建立 SpatialExternalSurface 執行個體時當機。這個問題已在 androidx.xr.scenecore:scenecore-*:1.0.0-alpha13、androidx.xr.compose:compose:1.0.0-alpha12 和後續版本中解決。受影響的應用程式應更新至最新版本。

API 變更

  • 子空間修飾符邊框間距變更，可感知版面配置方向。(I53e25)
  • 「SpatialCapabilities」已封存，無法再延期。(I07aef)
  • 接受一般 SpatialAlignment 參數的 SpatialRow 和 SpatialColumn API 已淘汰，請改用分別接受 verticalAlignment 或 horizontalAlignment 的 SpatialRow 和 SpatialColumn API。(Iec390)
  • 合併超載 SubspaceLayout 函式 API (Idd30a)
  • 已將 SubspaceModifier.lookAtUser 重新命名為 rotateToLookAtUser，並將 up 參數重新命名為 upDirection。(Icafb8)
  • 將 SpatialRow 設為內嵌函式 (Ia2f20)
  • 將 SpatialColumn 設為內嵌函式 (I681be)
  • 移除看板 API (Ib76cd)

1.0.0-alpha10 版本

2026 年 1 月 28 日

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

API 變更

1.0.0-alpha09 版本

2025 年 12 月 3 日

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

API 變更

  • 新增 LookAtUser 和 Billboard 修飾符，讓內容一律面向使用者。(I49b99)
  • 新增設定 InteractionPolicy 至 SpatialExternalSurfaces 和 SpatialPanels 的功能，可偵測點擊和其他 3D 輸入事件。(Iae155)
  • 新增大小和 requiredSize 修飾符多載，寬度、高度和深度為 Dp 值。(I92f79)
  • ParentLayoutParamsModifier 介面現在會擴充 DelegatableSubspaceNode。(I1a6d4)
  • ApplicationSubspace 已淘汰，改用 Subspace API。
    • Subspace API 行為已變更，只會在建議的姿勢和比例提供應用程式範圍的 subspace。
    • PlanarEmbeddedSubspace API 可在 2D 情境中提供內嵌子空間。(Id3343)
  • 已將 shouldAutoInvalidate 旗標新增至 SubspaceModifier.Node API。(I93902)
  • 新增 required(Size|Width|Depth|Height)In API，可讓開發人員將 @SubspaceComposable 的大小限制在特定範圍內，並忽略父項傳入的測量限制。(Ifaa78)
  • 新增 SubspaceModifier.onSizeChanged，為開發人員提供簡單的回呼，以便在 @SubspaceComposable 的大小變更時做出反應。(I994f9)
  • 移除了 Volume API。請改用 SceneCoreEntity API，而非 Volume API。(I4162b)
  • 將 SubspaceLayoutModifierNode.requestRelayout 分成 invalidateMeasurement/invalidatePlacement。(I14805)
  • 新增 SpatialGltfModel API，方便開發人員在 Compose 中算繪 glTF。(Icc91f)
  • 推出 SpatialGltfModel 可組合 API，方便算繪 glTF (Iade67)

修正錯誤

  • 修正 SceneCoreEntity 中的版面配置錯誤。現在應該會正確遵循限制。(I11bb8)
  • 將 jxr-compose 模組降級至 Compile sdk = 34 (I2d5db)

1.0.0-alpha08 版本

October 22, 2025

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

API 變更

  • 已將 ResizePolicy 變更為接受 onResizeStart、onResizeUpdate 和 onResizeEnd。(I7e21f)

修正錯誤

  • 防止在銷毀含有 Subspace 的 Activity 時發生當機問題。(I595a1)

1.0.0-alpha07 版本

2025 年 9 月 24 日

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

API 變更

  • 改善 SpatialMainPanel 的 KDocs。(I27b70、b/444467891)
  • 導入 SpatialArrangement，可在 SpatialRow 和 SpatialColumn 等 3D 版面配置中，沿著主軸排列子項。這項新 API 提供 2D Compose 中常見的排列選項，包括 Start、End、Center、SpaceBetween、SpaceAround 和 SpaceEvenly，並完整支援由左至右和由右至左的版面配置方向。(I7db38、b/436289959)
  • 新增 SubspaceModifier.Node 的基本介面，提升擴充介面的型別安全性和可用性，例如：
    • CompositionLocalConsumerSubspaceModifierNode
    • LayoutCoordinatesAwareModifierNode
    • SubspaceLayoutModifierNode
    • CoreEntityNode (內部) (Iede00、b/440599394、b/440599394)
  • 取消限制 SpatialExternalSurface (I33315、b/439646773)
  • 將 SubspaceModifier 導入 Subspace 可組合函式，並以與大小相關的 SubspaceModifiers 取代限制參數 SubspaceModifier。如果 allowUnboundedSubspace 為 true，子空間仍可有無限的限制。(Ib06e6、b/433331675)
  • DragPolicy() 和 ResizePolicy() 現在是 SpatialPanel 和 SpatialExternalSurface API 的一部分，因此可移動和調整大小的 SubspaceModifiers 已遭淘汰 (I397bf、b/437924639)
  • 在空間版面配置中新增對 LayoutDirection 的支援。使用 SpatialAlignment 的可組合函式現在會在 LTR 和 RTL 情境中正確放置元素。(I964bb、b/436300273)
  • 在 Panel API 中新增 Resizable 和 Movable 參數，確保這些行為只能套用至支援的容器。(Id491c)
  • 新增 sizeIn、widthIn、heightIn、depthIn SubspaceModifiers，可讓你為寬度、高度和深度設定確切的最小和最大限制。(I1af09、b/433330761)

1.0.0-alpha06 版本

2025 年 8 月 13 日

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

修正錯誤

  • 生命週期擁有者遭到刪除時，請重新建立 ComposeXrOwnerLocals。(9123ce1)

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 Composable，分別代表 180 度和 360 度的球體。(I40ef2、b/391705799)
  • 新增 SubspaceModifier.aspectRatio (Ide5ab、b/399729509、b/414762147)
  • 新增 SceneCoreEntity API，提升 SceneCore 與 Compose for XR 之間的互通性。(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)
  • 子空間和 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 無法遮蓋「活動」面板的問題。(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 為基礎的 SpatialPanel 和以 View 為基礎的 可根據內容調整大小。
  • 開發人員現在可以自行設定自訂 SpatialElevationLevel 值，不必受限於預先定義的層級。
  • 現在可透過 elevation 參數自訂軌道飛行器的高度。
  • 子空間現在預設會以 SpatialUser 的視野寬度和高度為界。如果無法判斷視野，系統會使用預設的視野寬度和高度值。
  • 在 Movable 修飾符中新增 onMoveStart 和 onMoveEnd 回呼。當使用者使用可移動修飾符開始和結束移動子空間可組合函式時，系統會呼叫 onMoveStart 和 onMoveEnd 回呼。
  • name 參數已從空間 API 中移除，例如 SpatialRow 和 SpatialPanel。如要對空間組合樹狀結構進行偵錯，請改用 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)
  • 現在系統會忽略修飾符節點分離時提出的重新配置要求。
  • 移除了由 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：面板會稍微向後推移，顯示高架對話方塊。
    • 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 會將內容推向錯誤的方向。