適用於 XR 的 Jetpack Compose

宣告依附元件

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

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

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

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

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

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

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

意見回饋

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

建立新問題

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

1.0 版本

1.0.0-beta02 版

2026 年 10 月 21 日

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

API 變更

• 程式庫現在指定 Kotlin 2.2，且需要 kotlinc 2.2 (I82396、b/498369605)
• 將 FollowMode.soft() 的 halfLifeMs 參數重新命名為 halfLifeMillis。(I39187)
• 將 PitchLimits 轉換為 @JvmInline value class，將兩個浮點數封裝為 Long，以消除物件分配。(Id43c3)
• 新增 FollowMode.soft 的參數：halfLifeMs、startDelay 和 startThresholds 參數。從 smoothStep 演算法轉換為 exponentialDecay 演算法後，不再需要 durationMs 參數，因此已移除。(If0140)
• 移除已淘汰的 SpatialActivityPanel 超載。請改用接受 SpatialActivityPanelController 的 SpatialActivityPanel 超載。(I5abc3)
• 在 FullSpaceMode 的單一 Activity 中，啟用 3D 和 2D 可組合內容之間的轉換。這項變更受 SpatialComposeFlags.isMainPanelResetOnSubspaceDisposeEnabled 管制。(I4e237)
• 公開實驗性 Subspace 超載，接受 FollowTarget 參數，以支援追蹤內容。(Iec1a9)
• 移除已淘汰的可移動修飾符。請改用新的可移動修飾符，接受新的 MovePolicy 做為參數。(Ib135d)
• 移除已淘汰的 DragPolicy。請改用 SubspaceModifier.movable()。(I108d4)
• 淘汰無狀態 Slider 和 RangeSlider 超載，改用有狀態版本。將 RangeSliderState 中的 activeRangeStart 和 activeRangeEnd 重新命名為 startValue 和 endValue，並淘汰舊版未升級和實驗性的 Slider API，改用 DeprecationLevel.HIDDEN。(If8995)

修正錯誤

• 修正 RotateToLookAtUser，方法是導入 poseInActivitySpace，確保所有子空間類型 (包括附加至錨點或使用者的類型) 都能正確計算姿勢。Ica367b
• 修正 Orbiter 附加至大型面板時的 Constraints 異常終止問題 (I8c4bf)
• 修正 SubspaceLayoutNode 中的錯誤，避免 removeAll() 導致不必要的 ArrayList 分配。此外，我們也修正了深度計算效能。I34a10a
• androidx.lifecycle:lifecycle-runtime 依附元件已更新至 2.10.0。如要搭配 AGP 9.5.0-alpha04 以上版本執行套裝生命週期執行階段 Lint 檢查，則必須使用這個版本。(I99bfd、b/556807521)
• 改善與 AudioOutputProvider 相關的 kdoc，強調不應與多個 ExoPlayer 執行個體重複使用 (I6b18e)
• 修正 KDoc 的拼字和文法小問題 (Id3ba6)

已知問題

• 這個版本的 androidx.xr.compose 具有 androidx.xr.scenecore:1.0.0-rc01 的依附元件，而該依附元件有已知的記憶體流失問題。在建構設定中，您可以明確將 SceneCore 依附元件覆寫為 1.0.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 面板有問題，在單一 Activity 中建立多個面板，可能會導致檢視內容損毀，即使面板已刪除也一樣。

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)
• 在 SubspaceSemanticsInfo 中公開 Density 以進行測試。(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 的所有公開浮點維度和位置相等斷言中，新增了 tolerance: Dp = Dp(0.5f) 參數。預設容許度行為 (0.5.dp) 已完整記錄。(I266cb、b/521491915)
• 新增含有 movePolicy 參數的可移動超載，並淘汰 transformingMovable 和 movable (Ic88c1、b/481781189)
• 新增標準清單項目和分段清單項目的非互動式變體，符合 Material Expressive 規格。非表達型版本已淘汰。(Ide4de、b/491994186)
• 在 Subspace 中，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 kdocs，納入物件在版面配置大小中的算繪位置 (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，讓開發人員在 Compose for XR 應用程式中加入 Gltf。開發人員也可以查詢 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 (包含已淘汰的備用方案)、新增 INERTIAL_LAST_KNOWN 以進行 3DoF 追蹤，並將 TRACKING_DEGRADED 新增至 TrackingState。(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 變更

• 移除已淘汰的 API - ApplicationSubspace (Ia6596、b/468345186)
• 將 SpatialShape 更新為密封介面 (I7e3f5、b/460426800)
• SpatialAlignment中已淘汰的 API 將移除。(Ib0b61、b/468011887)
• 淘汰 SpatialLayoutSpacer 並推出 SpatialSpacer。(I2ebf3、b/466071383)
• 更新 UserSubspace API，將「延遲鎖定」一詞替換為「軟鎖定」。(I9ded1、b/464035984)

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 行為已變更，現在只會以建議的姿勢和比例提供應用程式層級的子空間。
  • PlanarEmbeddedSubspace API 的推出，是為了在 2D 情境中提供嵌入式子空間。(Id3343)
• 在 SubspaceModifier.Node API 中新增 shouldAutoInvalidate 旗標。(I93902)
• 在 API 中新增 required(Size|Width|Depth|Height)，讓開發人員可將 @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 的 KDoc。(I27b70、b/444467891)
• 推出 SpatialArrangement，用於在 SpatialRow 和 SpatialColumn 等 3D 版面配置中，沿著主軸排列子項。這個新的 API 提供 2D Compose 中熟悉的排列選項，包括 Start、End、Center、SpaceBetween、SpaceAround 和 SpaceEvenly，並完整支援 LTR 和 RTL 版面配置方向。(I7db38、b/436289959)
• 為 SubspaceModifier.Node 新增基本介面，提升擴充功能介面的類型安全性和可用性，例如：
  • CompositionLocalConsumerSubspaceModifierNode
  • LayoutCoordinatesAwareModifierNode
  • SubspaceLayoutModifierNode
  • CoreEntityNode (內部) (Iede00、b/440599394、b/440599394)
• (I33315、b/439646773) 取消限制 SpatialExternalSurface
• 將 SubspaceModifier 導入 Subspace 可組合函式，並將 constraints 參數替換為 SubspaceModifier，以及與大小相關的 SubspaceModifiers。如果 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 可組合項，代表 180 度和 360 度球體。(I40ef2、b/391705799)
• 新增 SubspaceModifier.aspectRatio (Ide5ab、b/399729509、b/414762147)
• 新增 SceneCoreEntity API，改善 SceneCore 與 Compose for XR 之間的互通性。(I50bb3、b/423020989)
• 提供 GravityAlignedsubspace API，支援未縮放和 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 區域。根據預設，如未指定限制，子空間的寬度和高度會受限於 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 參數已從 SpatialRow 和 SpatialPanel 等空間 API 中移除。如要對空間 Compose 樹狀結構進行偵錯，請改用 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 情境中使用，並會將 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。

初始版本的功能

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

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

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

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

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

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

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

  • SpatialDialog：面板會稍微向後推，以顯示浮動對話方塊。
  • SpatialPopUp：面板會稍微向後推，在 z 軸深度上顯示浮動彈出式視窗
  • SpatialElevation：可設定 SpatialElevationLevel 來增加高度。

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

已知問題

• 目前，您必須使用 minSDK 30，才能使用 Jetpack Compose for XR。如要解決這個問題，您可以新增下列資訊清單項目 <uses-sdk tools:overrideLibrary="androidx.xr.scenecore, androidx.xr.compose"/>，以便使用 minSDK 23 建構及執行。
• Jetpack XR 應用程式目前需要在 AndroidManifest 中要求 android.permission.SCENE_UNDERSTANDING 權限。
• 如果應用程式使用資訊清單中的 PROPERTY_XR_ACTIVITY_START_MODE 屬性，直接在全螢幕啟動，則 Activity/應用程式一開始會在主畫面開啟，然後才轉換至全螢幕。
• Volume 可組合項中的 glTF 一開始可能會在錯誤的位置閃爍。
• 在大幅移動的面板中使用 SpatialDialog，會將內容推向錯誤的方向。