Jetpack Compose für XR

Räumliche UI-Layouts deklarativ erstellen, die die räumlichen Funktionen von Android XR nutzen
Letzte Aktualisierung Stabile Version Releasekandidat Beta-Ausgabe Alpharelease
30. Juli 2025 - – - 1.0.0-alpha05

Abhängigkeiten deklarieren

Wenn Sie eine Abhängigkeit von XR Compose hinzufügen möchten, müssen Sie Ihrem Projekt das Google Maven-Repository hinzufügen. Weitere Informationen finden Sie im Maven-Repository von Google.

Fügen Sie der Datei build.gradle für Ihre App oder Ihr Modul die Abhängigkeiten für die benötigten Artefakte hinzu:

Cool

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"
}

Kotlin

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")
}

Weitere Informationen zu Abhängigkeiten finden Sie unter Build-Abhängigkeiten hinzufügen.

Feedback

Ihr Feedback hilft uns, Jetpack zu verbessern. Lassen Sie es uns wissen, wenn Sie neue Probleme entdecken oder Ideen zur Verbesserung dieser Bibliothek haben. Sehen Sie sich die vorhandenen Probleme in dieser Bibliothek an, bevor Sie ein neues erstellen. Sie können für ein vorhandenes Problem abstimmen, indem Sie auf die Schaltfläche mit dem Stern klicken.

Neues Problem erstellen

Weitere Informationen finden Sie in der Dokumentation zur Problemverfolgung.

Version 1.0

Version 1.0.0-alpha05

30. Juli 2025

androidx.xr.compose:compose:1.0.0-alpha05 und androidx.xr.compose:compose-testing:1.0.0-alpha05 werden veröffentlicht. Version 1.0.0-alpha05 enthält diese Commits.

Neue Funktionen

  • Die Annotationsklasse SubspaceComposable wurde öffentlich gemacht. (Ic2a34, b/399432430)
  • Zwei neue SpatialExternalSurface-Composables, die 180- und 360-Grad-Kugeln darstellen. (I40ef2, b/391705799)
  • SubspaceModifier.aspectRatio hinzugefügt (Ide5ab, b/399729509, b/414762147)
  • Die SceneCoreEntity API wurde hinzugefügt, um die Interoperabilität zwischen SceneCore und Compose für XR zu verbessern. (I50bb3, b/423020989)
  • GravityAlignedsubspace-API zur Unterstützung der nicht skalierten Funktion „Und“ bereitgestellt (I07359)GravityAligned

API-Änderungen

  • SpatialDialog() folgt der Konfiguration für SpatialDialogProperties.dismissOnBack. (Ib453b, b/416797132)
  • Aktualisieren Sie minimumPanelDimension auf die neue Standarddimensionsgröße Dimensions(0.1f, 0.1f, 0.1f), da sie in Metern angegeben wird. (Ib852a)
  • Unterbereiche und Orbiters behalten jetzt ihren internen Status im Home-Bereich und wenn die App im Hintergrund ausgeführt wird. Im Home Space-Modus richtet Subspace die Szene weiterhin vor, um zum Full Space-Modus zu wechseln. (I40317, b/416037751)
  • SpatialDialogs behalten jetzt ihren Status bei, wenn die App im Hintergrund ausgeführt wird. (I6aa56)
  • ApplicationSubspace übernimmt jetzt die empfohlene Skalierung und Position aus dem System. (I4565f, b/418834194)
  • Es wurde eine bessere Fehlermeldung hinzugefügt und der Fehler wird früher ausgelöst, wenn SubspaceComposable in einem Kontext verwendet wird, der nicht SubspaceComposable ist. (Iee2ae, b/416484684)
  • ExperimentalSubspaceVolumeApi wird von „Warnung“ zu „Fehler“ aktualisiert, da Warnungen bei der missbräuchlichen Verwendung zusammensetzbarer APIs oft übersehen werden. (I427aa, b/424864286)
  • Der Unterraum und ApplicationSubspace werden jetzt durch recommendedContentBoxInFullSpace eingeschränkt. Bisher war sie durch das Sichtfeld von SpatialUser eingeschränkt. (I41015, b/423074142)
  • SpatialElevation aktualisieren, um die Mindestgröße zu verwenden und keine fest codierte Größe mehr zu nutzen (I2dbe6, b/427785338)
  • Aktualisieren Sie, wie wir die SpatialAcitivityPanel testen, um zu sehen, wann eine wichtige Variable geändert wird. (I0f64d, b/427999029)
  • Entfernen Sie VolumeConstraints.Unbounded und legen Sie stattdessen die Standardwerte für die Einschränkung fest. (Ie24ec, b/407938414)
  • SpatialFeatheringSize ist nicht mehr öffentlich (I1c15b, b/399432430)
  • Die XR-Placeable wurde in SubspacePlaceable umbenannt, um sie von der Placeable von Compose zu unterscheiden. (I74874)
  • Entfernen der Orbiter-Einstellungen und Hinzufügen von shouldRenderInNonSpatial als neuer Parameter. Außerdem wird die Klasse EdgeOffset entfernt und orbiterOffsetType als neuer Parameter hinzugefügt, um Orbiter()-Funktionen zusammenzuführen. Außerdem wurde OrbiterEdge in ContentEdge umbenannt. (Iebf3d)
  • Measurable wurde in SubspaceMeasurable umbenannt, um den Typ vom Measurable-Typ von Compose zu unterscheiden. (I9726c)
  • MeasureResult in SubspaceMeasureResult umbenennen (I9f34d)
  • Die setSubspaceContent API wurde entfernt. Stattdessen wird setContent mit einem Subspace-Composable verwendet. (Ifff4c, b/421427391, b/421427391)
  • MeasurePolicy wird in SubspaceMeasurePolicy umbenannt. (I37a9b, b/422553904)
  • Machen Sie SubspaceSemanticsInfo zu einem versiegelten Interface, da wir ohne die Standardwerte keine Mitglieder hinzufügen können. (I372f9, b/423704068)
  • Die Dokumentation für SpatialExternalSurface wurde aktualisiert und ContentSecurityLevel wurde in SurfaceProtection umbenannt (I3c460, b/420982808).
  • Es wurde ein überladener Konstruktor für den verschiebbaren Modifier bereitgestellt, der das Verankern ermöglicht. (Ic0c70)
  • Es wurde ein weiterer Positionsanbieter für Tooltips hinzugefügt. Entwickler können jetzt festlegen, ob der Tooltip über, unter, links oder rechts vom Anker platziert wird. Fügen Sie eine API hinzu, die eine Form für Carets akzeptiert, damit mehr benutzerdefinierte Formen bereitgestellt werden können. (Ie513c, b/374766087, b/418854637)
  • CoreEntity wurde als PublishedApi entfernt (Ifee05)

Fehlerkorrekturen

  • Ein Problem wurde behoben, bei dem SpatialDialog beim Rendern blinkte. (Ife73c, b/401619909)
  • Ein Problem wurde behoben, durch das SpatialDialog das Aktivitätsfeld nicht abdunkeln konnte. (I8ca6c, b/367442109)
  • Fehler behoben: Im XR-Dialogfeld werden einige Inhalte nicht angezeigt (I17cd5, b/418062437)
  • Das Problem, dass SpatialPopup geschlossen wurde, wenn innerhalb des Inhalts darauf geklickt wurde, wurde behoben. (If262c, b/417245722)
  • Das Problem wurde behoben, bei dem das SpatialPanel bei der Verkettung von resizable().movable() nicht richtig an die neue Größe angepasst wurde. (I02ee3, b/422264230)
  • Das topBar überlappt sich nicht mehr mit dem Menü in SpatialComposeVideoPlayer (Id33bc, b/427168167).
  • Fester Eckenradius wird nicht gerendert (I975fe, b/428261830)

Version 1.0.0-alpha04

7. Mai 2025

androidx.xr.compose:compose:1.0.0-alpha04 und androidx.xr.compose:compose-testing:1.0.0-alpha04 werden veröffentlicht. Version 1.0.0-alpha04 enthält diese Commits.

Neue Funktionen

  • Die CompositionLocalConsumerSubspaceModifierNode-Schnittstelle wurde hinzugefügt, damit benutzerdefinierte SubspaceModifier-Typen auf lokale Werte der Komposition zugreifen können.
  • Es wurde eine neue SpatialPanel-API hinzugefügt, die dem Compose-Implementierungsstil AndroidView folgt und die vorherige ViewBased SpatialPanel ersetzt.
  • Das VolumeConstraints.Unbounded-Begleitobjekt wurde hinzugefügt, das unbegrenzte Einschränkungen darstellt.
  • SubspaceModifier.onPointSourceParams wurde hinzugefügt, um eine räumliche Audioquelle zu ermöglichen.
  • Es wurde ein öffentliches ApplicationSubspace hinzugefügt, das optionales VolumeConstraints bietet, um einen 3D-Bereich zu definieren, in dem die App räumliche Inhalte rendern kann. Wenn keine Einschränkungen angegeben sind, wird der Unterraum standardmäßig durch das aktuelle Sichtfeld des SpatialUser in Breite und Höhe begrenzt. Nutzer können Einschränkungen angeben, die verwendet werden sollen, wenn das Sichtfeld nicht ermittelt werden kann. Andernfalls werden die Standardwerte für die Breite und Höhe des Sichtfelds verwendet.
  • SpatialExternalSurface wurde hinzugefügt. Damit lassen sich stereoskopische Inhalte rendern. SpatialExternalSurface kann mit Modifikatoren (außer Alpha) und einem Weichzeichnungseffekt für Kanten angepasst werden.
  • Es wurde ein neuer pointerHoverIcon-Unterraummodifikator hinzugefügt, mit dem Nutzer das Symbol für den räumlichen Zeiger festlegen können.

API-Änderungen

  • Die Einschränkung RequiresApi(34) wurde für alle Jetpack XR-Pakete entfernt. Diese Einschränkung war überflüssig, da Jetpack XR derzeit nur auf Geräten mit API-Level 34 oder höher verfügbar ist. (Iae0f8)
  • Für Projekte, die mit Kotlin 2.0 veröffentlicht wurden, ist KGP 2.0.0 oder höher erforderlich. (Idb6b5)
  • Die Rücktaste funktioniert jetzt auch bei räumlichen Bereichen ohne eingebettete Aktivitäten. Damit die Rücktaste funktioniert, müssen Sie android:enableOnBackInvokedCallback="true" im Android-Manifest angeben.
  • Die Rückgabe von Ergebnissen funktioniert jetzt auch bei räumlichen Dialogen. Damit die Rücktaste funktioniert, müssen Sie android:enableOnBackInvokedCallback="true" im Android-Manifest angeben.
  • Compose-basierte und View-basierte SpatialPanels können jetzt ihre Größe basierend auf ihrem Inhalt anpassen.
  • Entwickler können jetzt eigene benutzerdefinierte SpatialElevationLevel-Werte festlegen und sind nicht mehr auf die vordefinierten Stufen beschränkt.
  • Die Höhe des Orbiters kann jetzt über den Parameter elevation angepasst werden.
  • Der Unterbereich kann jetzt standardmäßig durch das Sichtfeld des SpatialUser in Breite und Höhe begrenzt werden. Wenn das Sichtfeld nicht bestimmt werden kann, werden die Standardwerte für die Breite und Höhe des Sichtfelds verwendet.
  • Dem Modifikator Movable wurden die neuen Callbacks onMoveStart und onMoveEnd hinzugefügt. Die Callbacks onMoveStart und onMoveEnd werden aufgerufen, wenn der Nutzer beginnt und beendet, einen Subspace-Composable mit dem Modifier „movable“ zu verschieben.
  • Der Parameter name wurde aus räumlichen APIs wie SpatialRow und SpatialPanel entfernt. Verwenden Sie stattdessen SubspaceModifier.testTag, um räumliche Compose-Bäume zu debuggen.
  • Eine nicht unterstützte Überladung von SpatialPopup wurde entfernt, die nur spatialElevationLevel und content enthält. Verwenden Sie die Oberfläche, die onDimissRequest unterstützt.
  • Der onPoseChange-Callback aus dem Movable-Modifier wurde entfernt. Verwenden Sie stattdessen onMove.
  • SubspaceModifiers wendet seine Effekte nicht mehr an, wenn es getrennt wurde oder gerade getrennt wird.
  • Die vorhandene SpatialRow API wurde in SpatialRow und SpatialCurvedRow aufgeteilt. Wenn Sie zuvor den Parameter curveRadius von SpatialRow verwendet haben, verwenden Sie jetzt stattdessen SpatialCurvedRow. Das Verhalten ist dasselbe.
  • MainPanel und ActivityPanel haben keine Titelleisten mehr, wenn sie auf einem ähnlich aktuellen System-Image ausgeführt werden.
  • Alpha- und Skalierungsmodifikatoren sind jetzt stapelbar und ihre Werte werden für den endgültigen angewendeten Alpha- oder Skalierungswert multipliziert.
  • Der onPoseChange-Rückruf des Movable-Modifikators wurde optimiert, um eine flüssigere Bewegung der Pose zu ermöglichen.
  • Die verschiebbaren und in der Größe anpassbaren Modifikatoren führen ihre Callbacks jetzt im Hauptthread aus, damit Zustandsänderungen eine Neuzusammensetzung auslösen.
  • Der Layout- und Messphase wurde eine Statusbeobachtung hinzugefügt, damit Statusänderungen in SubspaceLayout ein neues Layout auslösen.
  • Die Kette der optimierten Modifikatoren wurde aktualisiert, um vorhandene Modifikatoren besser wiederzuverwenden.

Fehlerkorrekturen

  • Das Scrimming wurde beendet, als ein SpatialDialog angezeigt wurde. (Ic4594)
  • Anfragen zum Neugestalten, die gestellt werden, während Modifikator-Knoten getrennt sind, werden jetzt ignoriert.
  • Phasen für das Neugestalten des Layouts, die durch die Modifikatoren „Movable“ und „Resizable“ ausgelöst werden, wurden entfernt.
  • Ein Absturz in der zusammensetzbaren Funktion MainPanel() wurde behoben, der aufgetreten ist, wenn eine der beiden Dimensionen direkt oder während einer Layoutberechnung, z.B. einer SpatialRow/SpatialColumn-Berechnung, auf null gesetzt wurde. Das Feld wird jetzt stattdessen ausgeblendet. Diese Korrektur bezieht sich speziell auf Abstürze während der Layoutphase. Das Anpassen der Größe des Bereichs auf null durch Nutzerinteraktion wird separat behandelt. Das ausgeblendete Feld hat keine UI-Affordances.
  • Ein Problem mit maintainAspectRatio aus dem Modifier für die Größenanpassung wurde behoben. Das Seitenverhältnis sollte jetzt beibehalten werden.
  • Ein Problem mit verschachtelten Unterbereichen wurde behoben, bei dem sie für einen einzelnen Frame falsch positioniert wurden.
  • Ein Problem wurde behoben, durch das abgerundete Ecken manchmal nicht angewendet wurden, obwohl sie hätten angewendet werden sollen.
  • NestedSubspaces wird nicht mehr für ein Frame am falschen Ort angezeigt.

Version 1.0.0-alpha03

26. Februar 2025

androidx.xr.compose:compose:1.0.0-alpha03 und androidx.xr.compose:compose-testing:1.0.0-alpha03 werden ohne nennenswerte Änderungen seit der letzten Alphaversion veröffentlicht. Version 1.0.0-alpha03 enthält diese Commits.

Version 1.0.0-alpha02

12. Februar 2025

androidx.xr.compose:compose:1.0.0-alpha02 und androidx.xr.compose:compose-testing:1.0.0-alpha02 werden veröffentlicht. Version 1.0.0-alpha02 enthält diese Commits.

Neue Funktionen

  • Der Inhalt des Aktivitätsbereichs kann jetzt abgedunkelt werden, wenn ein räumlicher Dialog aktiviert wird.
  • Die Orbiter API kann jetzt in SubspaceComposable-Kontexten verwendet werden. Orbiters werden an das nächstgelegene SubspaceLayout-basierte zusammensetzbare übergeordnete Element angehängt.
  • LayoutCoordinatesAwareModifierNode wurde eingeführt, um benutzerdefinierte positionierungsbasierte Modifikatoren zu ermöglichen.
  • SubspaceModifier.Node wurden Methoden für den Lebenszyklus zum Anhängen/Abtrennen hinzugefügt.
  • scaleWithDistance wurde dem beweglichen Modifikator hinzugefügt. Wenn scaleWithDistance aktiviert ist, wird das verschobene Unterraum-Element vergrößert oder verkleinert. Außerdem wird die explizite Skalierung beibehalten, die vor der Bewegung festgelegt war.

API-Änderungen

  • SessionCallbackProvider wurde zugunsten von SpatialCapabilities entfernt.

Sonstige Änderungen

  • minSDK auf 24 reduziert. Für alle Jetpack XR-APIs ist weiterhin API 34 zur Laufzeit erforderlich.
  • Die Konstruktoren Orbiter EdgeOffset.inner, EdgeOffset.outer und EdgeOffset.overlap sind keine @Composable-Methoden mehr, sodass sie in nicht zusammensetzbaren Kontexten verwendet werden können.
  • Die räumlichen Erhebungsebenen wurden an die aktuelle UX-Spezifikation angepasst.
  • Implementieren Sie die SubspaceSemanticsInfo-Schnittstelle in MeasurableLayout.
  • SubspaceModifierElement wurde in SubspaceModifierNodeElement umbenannt.

Fehlerkorrekturen

  • Fehlerbehebungen zur Stabilisierung der SubspaceModifier-Bestellung. SubspaceModifier sollte zuverlässiger funktionieren. Die Modifikatoren „Offset“, „Drehen“, „Skalieren“, „Verschiebbar“ und „Größe anpassbar“ sollten jetzt in beliebiger Reihenfolge verwendet werden können.

Version 1.0.0-alpha01

12. Dezember 2024

androidx.xr.compose:compose-*1.0.0-alpha01 wird veröffentlicht.

Funktionen der Erstversion

  • Erste Entwicklerversion von Jetpack Compose für XR. Verwenden Sie vertraute Compose-Konzepte wie Zeilen und Spalten, um räumliche UI-Layouts in XR zu erstellen. Das gilt sowohl, wenn Sie eine vorhandene 2D-App in XR portieren, als auch, wenn Sie eine neue XR-App von Grund auf neu erstellen. Diese Bibliothek bietet Unterraum- und räumliche Composables wie räumliche Panels und Orbiters, mit denen Sie Ihre vorhandene 2D-Benutzeroberfläche auf Basis von Compose oder Views in einem räumlichen Layout platzieren können. Es wird das zusammensetzbare Element „Volume“ eingeführt, mit dem Sie SceneCore-Entitäten wie 3D-Modelle relativ zur Benutzeroberfläche platzieren können. Weitere Informationen finden Sie in diesem Entwicklerleitfaden:

    • Subspace: Diese Composable-Funktion kann an beliebiger Stelle in der UI-Hierarchie Ihrer App platziert werden. So können Sie Layouts für 2D- und räumliche UIs beibehalten, ohne den Kontext zwischen Dateien zu verlieren. So können Sie beispielsweise die vorhandene App-Architektur einfacher zwischen XR und anderen Formfaktoren teilen, ohne den Status durch den gesamten UI-Baum zu übertragen oder Ihre App neu zu entwerfen.

    • SpatialPanel: Ein SpatialPanel ist eine untergeordnete Komponente, mit der Sie App-Inhalte anzeigen können, z. B. die Videowiedergabe, Standbilder oder andere Inhalte.

    • Orbiter: Ein Orbiter ist eine räumliche UI-Komponente. Sie ist für die Verknüpfung mit einem entsprechenden räumlichen Bereich konzipiert und enthält Navigations- und Kontextaktionen, die sich auf diesen räumlichen Bereich beziehen. Wenn Sie beispielsweise ein räumliches Panel zum Anzeigen von Videoinhalten erstellt haben, können Sie einem Orbiter Steuerelemente für die Videowiedergabe hinzufügen.

    • Volumen: SceneCore-Entitäten wie 3D-Modelle relativ zur Benutzeroberfläche platzieren.

  • Räumliches Layout: Sie können mehrere räumliche Bereiche erstellen und sie mit SpatialRow, SpatialColumn, SpatialBox und SpatialLayoutSpacer in einem räumlichen Layout platzieren. Mit SubspaceModifiers können Sie das Layout anpassen.

  • Räumliche UI-Komponenten: Diese Elemente können in Ihrer 2D-Benutzeroberfläche wiederverwendet werden. Ihre räumlichen Attribute sind nur sichtbar, wenn räumliche Funktionen aktiviert sind.

    • SpatialDialog: Das Feld wird in der Z-Tiefe leicht nach hinten verschoben, um ein erhöhtes Dialogfeld anzuzeigen.
    • SpatialPopUp: Das Feld wird in der Z-Tiefe leicht nach hinten verschoben, um ein Popup anzuzeigen.
    • SpatialElevation: SpatialElevationLevel kann festgelegt werden, um die Höhe hinzuzufügen.

  • SpatialCapabilities: Die räumlichen Funktionen können sich ändern, wenn Nutzer mit Ihrer App oder dem System interagieren oder sogar von Ihrer App selbst geändert werden, z. B. durch den Wechsel in den Home Space oder Full Space. Um Probleme zu vermeiden, muss Ihre App prüfen, ob LocalSpatialCapabilities.current vorhanden ist, um zu ermitteln, welche APIs in der aktuellen Umgebung unterstützt werden. isSpatialUiEnabled: Räumliche UI-Elemente (z. B. SpatialPanel) isContent3dEnabled: 3D-Objekte isAppEnvironmentEnabled: Die Umgebung isPassthroughControlEnabled: Gibt an, ob die Anwendung den Passthrough-Status steuern kann. isSpatialAudioEnabled: Spatial Audio

Bekannte Probleme

  • Derzeit ist für die Verwendung von Jetpack Compose für XR ein minSDK von 30 erforderlich. Als Workaround können Sie den folgenden Manifesteintrag <uses-sdk tools:overrideLibrary="androidx.xr.scenecore, androidx.xr.compose"/> hinzufügen, um mit einem minSDK von 23 zu erstellen und auszuführen.
  • Für Jetpack XR-Apps muss derzeit die Berechtigung android.permission.SCENE_UNDERSTANDING im AndroidManifest angefordert werden.
  • Wenn eine App direkt im Full Space gestartet wird und dazu die Eigenschaft PROPERTY_XR_ACTIVITY_START_MODE in ihrem Manifest verwendet, werden Aktivitäten/Anwendungen zuerst im Home Space geöffnet, bevor sie in den Full Space übergehen.
  • glTFs in Volume-Composables flackern möglicherweise anfangs am falschen Ort.
  • Wenn Sie einen SpatialDialog in einem Bereich verwenden, der erheblich verschoben wurde, werden die Inhalte in die falsche Richtung verschoben.