適用於 XR 的 Jetpack Compose

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

宣告依附元件

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

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

Groovy

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

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

Kotlin

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

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

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

意見回饋

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

建立新問題

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

1.0 版本

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 會隨著使用者與應用程式或系統互動而變更，甚至可能會由應用程式本身變更，例如進入 Home Space 或 Full Space。為避免發生問題，應用程式需要檢查 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 屬性，直接啟動至全螢幕模式，則活動/應用程式會先在 Home 模式中開啟，再轉換至全螢幕模式。
  • 在 Volume Composable 中，glTF 一開始可能會在錯誤的位置閃爍。
  • 如果在大幅移動的面板中使用 SpatialDialog，內容會推送至錯誤的方向。