Jetpack Compose na potrzeby XR

Deklarowanie zależności

Aby dodać zależność od XR Compose, musisz dodać repozytorium Google Maven do projektu. Więcej informacji znajdziesz w repozytorium Maven Google.

Dodaj zależności dotyczące potrzebnych artefaktów w pliku build.gradle aplikacji lub modułu:

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

Więcej informacji o zależnościach znajdziesz w artykule Dodawanie zależności kompilacji.

Opinia

Twoja opinia pomoże nam ulepszyć Jetpacka. Jeśli odkryjesz nowe problemy lub masz pomysły na ulepszenie tej biblioteki, daj nam znać. Zanim utworzysz nową kartę, zapoznaj się z dotychczasowymi problemami w tej bibliotece. Możesz dodać swój głos do istniejącego problemu, klikając przycisk gwiazdki.

Tworzenie nowego problemu

Więcej informacji znajdziesz w dokumentacji narzędzia Issue Tracker.

Wersja 1.0

Wersja 1.0.0-alpha05

30 lipca 2025 r.

androidx.xr.compose:compose:1.0.0-alpha05 i androidx.xr.compose:compose-testing:1.0.0-alpha05 zostają opublikowane. Wersja 1.0.0-alpha05 zawiera te commity.

Nowe funkcje

• Udostępniono publicznie klasę adnotacji SubspaceComposable. (Ic2a34, b/399432430)
• Dwa nowe komponenty SpatialExternalSurface reprezentujące sfery o kącie widzenia 180 i 360 stopni. (I40ef2, b/391705799)
• Dodano SubspaceModifier.aspectRatio (Ide5ab, b/399729509, b/414762147)
• Dodano interfejs SceneCoreEntity API, aby zwiększyć interoperacyjność między SceneCore a Compose XR. (I50bb3, b/423020989)
• Udostępniliśmy interfejs GravityAlignedsubspace API do obsługi funkcji bez skalowania i GravityAligned (I07359).

Zmiany w interfejsie API

• SpatialDialog() będzie zgodny z konfiguracją naciśnięcia SpatialDialogProperties.dismissOnBack. (Ib453b, b/416797132)
• Zaktualizuj minimumPanelDimension do nowego domyślnego rozmiaru wymiaru Dimensions(0.1f, 0.1f, 0.1f) ze względu na jego reprezentację w metrach. (Ib852a)
• Podprzestrzenie i Orbiter będą teraz zachowywać swój stan wewnętrzny w przestrzeni domowej i gdy aplikacja działa w tle. W trybie obszaru domowego Subspace nadal będzie konfigurować scenę w ramach przygotowań do przejścia na tryb pełnego obszaru. (I40317, b/416037751)
• SpatialDialogs zachowają teraz swój stan, gdy aplikacja będzie działać w tle. (I6aa56)
• Urządzenie ApplicationSubspace odziedziczy teraz zalecaną skalę i pozycję z systemu. (I4565f, b/418834194)
• Dodaliśmy lepszy komunikat o błędzie i wcześniej wywołujemy błąd, gdy w kontekście innym niż SubspaceComposable używany jest znak SubspaceComposable. (Iee2ae, b/416484684)
• Zmieniamy ExperimentalSubspaceVolumeApi z ostrzeżenia na błąd, ponieważ ostrzeżenia są często pomijane w przypadku nieprawidłowego użycia interfejsów API z możliwością komponowania. (I427aa, b/424864286)
• Podprzestrzeń i ApplicationSubspace są teraz ograniczone przez recommendedContentBoxInFullSpace. Wcześniej był on ograniczony przez SpatialUser. (I41015, b/423074142)
• Zaktualizuj SpatialElevation, aby używać minimalnego rozmiaru i nie korzystać już z rozmiaru zakodowanego na stałe (I2dbe6, b/427785338)
• Zaktualizuj sposób, w jaki sprawdzamy SpatialAcitivityPanel, aby aktualizować go, gdy zmieniana jest kluczowa zmienna. (I0f64d, b/427999029)
• Usuń VolumeConstraints.Unbounded i ustaw domyślne wartości ograniczeń na równoważne. (Ie24ec, b/407938414)
• SpatialFeatheringSize nie jest już publiczny (I1c15b, b/399432430)
• Zmieniliśmy nazwę XR Placeable na SubspacePlaceable, aby odróżnić ją od Placeable w Compose. (I74874)
• Usunięcie ustawień Orbiter i dodanie shouldRenderInNonSpatial jako nowego parametru. Dodatkowo usunęliśmy klasę EdgeOffset i dodaliśmy orbiterOffsetType jako nowy parametr, aby skonsolidować funkcje Orbiter(). Oprócz zmiany nazwy OrbiterEdge na ContentEdge. (Iebf3d)
• Zmieniono nazwę Measurable na SubspaceMeasurable, aby odróżnić ten typ od typu Measurable w narzędziu Compose. (I9726c)
• Zmiana nazwy MeasureResult na SubspaceMeasureResult (I9f34d)
• Usunęliśmy interfejs setSubspaceContent API na rzecz korzystania z interfejsu setContent w Compose z funkcją kompozycyjną Subspace. (Ifff4c, b/421427391, b/421427391)
• Nazwa MeasurePolicy została zmieniona na SubspaceMeasurePolicy. (I37a9b, b/422553904)
• Przekształć SubspaceSemanticsInfo w zamknięty interfejs, ponieważ bez ustawień domyślnych nie będziemy mogli dodawać użytkowników. (I372f9, b/423704068)
• Zaktualizowano dokumentację SpatialExternalSurface, zmieniono nazwę ContentSecurityLevel na SurfaceProtection (I3c460, b/420982808)
• Dodano przeciążony konstruktor modyfikatora przenośnego, który umożliwia zakotwiczenie. (Ic0c70)
• Dodaliśmy więcej dostawców pozycji dla etykietek, dzięki czemu deweloperzy mogą teraz określać, czy etykietka ma być umieszczana nad, pod, po lewej czy po prawej stronie elementu zakotwiczonego. Dodaj interfejs API, który przyjmuje kształt karetki, aby można było podać więcej niestandardowych kształtów. (Ie513c, b/374766087, b/418854637)
• Usunięto CoreEntity jako PublishedApi (Ifee05)

Poprawki błędów

• Rozwiązaliśmy problem polegający na tym, że podczas renderowania symbol SpatialDialog migał. (Ife73c, b/401619909)
• Rozwiązaliśmy problem, który uniemożliwiał przyciemnienie panelu aktywności za pomocą funkcji SpatialDialog. (I8ca6c, b/367442109)
• Naprawiono problem z wyświetlaniem niektórych treści w oknie XR (I17cd5, b/418062437)
• Rozwiązaliśmy problem polegający na tym, że po kliknięciu w treści zamykało się okno SpatialPopup. (If262c, b/417245722)
• Rozwiązaliśmy problem polegający na tym, że podczas łączenia paneli resizable().movable() panel SpatialPanel nie zmieniał prawidłowo rozmiaru. (I02ee3, b/422264230)
• Naprawiono nakładanie się przycisku topBar na menu w SpatialComposeVideoPlayer (Id33bc, b/427168167)
• Stały promień narożnika nie jest renderowany (I975fe, b/428261830)

Wersja 1.0.0-alpha04

7 maja 2025 r.

androidx.xr.compose:compose:1.0.0-alpha04 i androidx.xr.compose:compose-testing:1.0.0-alpha04 zostają opublikowane. Wersja 1.0.0-alpha04 zawiera te zmiany.

Nowe funkcje

• Dodano interfejs CompositionLocalConsumerSubspaceModifierNode, który umożliwia niestandardowym typom SubspaceModifier dostęp do lokalnych wartości kompozycji.
• Dodaliśmy nowy interfejs API SpatialPanel, który jest zgodny ze stylem implementacji AndroidView i wycofuje poprzedni interfejs ViewBased SpatialPanel.
• Dodano obiekt towarzyszący VolumeConstraints.Unbounded, który reprezentuje nieograniczone ograniczenia.
• Dodano SubspaceModifier.onPointSourceParams, aby umożliwić przestrzenne źródło dźwięku.
• Dodano publiczną ApplicationSubspace, która oferuje opcjonalną VolumeConstraints do zdefiniowania obszaru 3D, w którym aplikacja może renderować treści przestrzenne. Domyślnie, jeśli nie określono żadnych ograniczeń, podprzestrzeń będzie ograniczona bieżącym polem widzenia elementu SpatialUser pod względem szerokości i wysokości. Użytkownicy mogą podać ograniczenia, które będą używane, jeśli nie można określić pola widzenia. W przeciwnym razie używane są domyślne wartości szerokości i wysokości pola widzenia.
• Dodano SpatialExternalSurface, którego można używać do renderowania treści stereoskopowych. SpatialExternalSurface można dostosować za pomocą modyfikatorów (z wyjątkiem przezroczystości) i efektu rozmycia krawędzi.
• Dodano nowy pointerHoverIconmodyfikator podprzestrzenipointerHoverIcon, który umożliwia użytkownikom ustawienie ikony wskaźnika przestrzennego.

Zmiany w interfejsie API

• Usunięto ograniczenie RequiresApi(34) we wszystkich pakietach Jetpack XR. To ograniczenie było zbędne, ponieważ Jetpack XR jest obecnie dostępny tylko na urządzeniach z poziomem API 34 lub wyższym. (Iae0f8)
• Projekty wydane w Kotlinie 2.0 wymagają użycia KGP w wersji 2.0.0 lub nowszej. (Idb6b5)
• Obsługa przycisku Wstecz będzie teraz działać w przypadku paneli przestrzennych bez osadzonych aktywności. Aby działała obsługa przycisku Wstecz, w pliku manifestu Androida musisz określić android:enableOnBackInvokedCallback="true".
• Funkcja cofania będzie teraz działać w przypadku okien przestrzennych. Aby działało cofanie, musisz określić android:enableOnBackInvokedCallback="true" w manifeście Androida.
• Komponenty SpatialPanel oparte na komponowaniu i widoku mogą teraz dostosowywać swój rozmiar do zawartości.
• Deweloperzy mogą teraz ustawiać własne wartości SpatialElevationLevel i nie są ograniczeni do wstępnie zdefiniowanych poziomów.
• Poziom wysokości orbity można teraz dostosowywać za pomocą parametru elevation.
• Podprzestrzeń może być teraz domyślnie ograniczona polem widzenia elementu SpatialUser pod względem szerokości i wysokości. Jeśli nie można określić pola widzenia, używane są domyślne wartości szerokości i wysokości pola widzenia.
• Dodaliśmy nowe wywołania zwrotne onMoveStart i onMoveEnd do modyfikatora Movable. Wywołania zwrotne onMoveStart i onMoveEnd są wywoływane, gdy użytkownik zaczyna i kończy przesuwanie elementu kompozycyjnego podprzestrzeni za pomocą modyfikatora movable.
• Parametr name został usunięty z interfejsów API przestrzennych, takich jak SpatialRow i SpatialPanel. Do debugowania drzew kompozycji przestrzennych używaj SubspaceModifier.testTag.
• Usunięto nieobsługiwane przeciążenie funkcji SpatialPopup, która ma tylko spatialElevationLevel i content. Użyj interfejsu, który obsługuje onDimissRequest.
• Wywołanie zwrotne onPoseChange z modyfikatora Movable zostało usunięte. Zamiast niej używaj zasady onMove.
• SubspaceModifiers nie będą już stosować swoich efektów, jeśli zostaną odłączone lub są w trakcie odłączania.
• Dotychczasowy interfejs API SpatialRow został podzielony na interfejsy SpatialRow i SpatialCurvedRow. Jeśli wcześniej używasz parametru SpatialRowcurveRadius, teraz używaj parametru SpatialCurvedRow, który działa tak samo.
• MainPanel i ActivityPanel nie mają już pasków tytułu, gdy są uruchamiane na podobnie aktualnym obrazie systemu.
• Modyfikatory alfa i skali można teraz łączyć w stosy, a ich wartości będą mnożone, aby uzyskać ostateczną wartość alfa lub skali.
• onPoseChange Wywołanie zwrotne z modyfikatora Ruchomy zostało zoptymalizowane pod kątem płynniejszego ruchu w pozy.
• Modyfikatory, które można przesuwać i których rozmiar można zmieniać, będą teraz wywoływać swoje wywołania zwrotne w głównym wątku, aby zmiany stanu powodowały ponowne komponowanie.
• Dodano obserwację stanu do faz układu i pomiaru, aby zmiany stanu w SubspaceLayout powodowały ponowne ułożenie.
• Zoptymalizowane aktualizacje łańcucha modyfikatorów, aby lepiej wykorzystywać istniejące modyfikatory.

Poprawki błędów

• Zatrzymano przyciemnianie, gdy wyświetlono SpatialDialog. (Ic4594)
• Żądania ponownego układu wysyłane, gdy węzły modyfikatora są odłączone, będą teraz ignorowane.
• Usunięto fazy zmiany układu wywoływane przez modyfikatory Movable i Resizable.
• Naprawiliśmy awarię w funkcji kompozycyjnej MainPanel(), która występowała, gdy jeden z wymiarów był ustawiony na zero, bezpośrednio lub podczas obliczania układu, np. obliczania SpatialRow/SpatialColumn. Panel zostanie teraz ukryty. Pamiętaj, że ta poprawka dotyczy konkretnie awarii podczas fazy układu. Zmiana rozmiaru panelu na zero w wyniku interakcji użytkownika będzie obsługiwana osobno. Ukryty panel nie ma elementów interfejsu.
• Rozwiązanie problemu z symbolem maintainAspectRatio w przypadku modyfikatora o zmienianym rozmiarze. Proporcje powinny zostać zachowane.
• Rozwiązaliśmy problem z zagnieżdżonymi podprzestrzeniami, które były nieprawidłowo pozycjonowane w jednej klatce.
• Rozwiązaliśmy problem polegający na tym, że zaokrąglone rogi czasami nie były stosowane, gdy powinny.
• NestedSubspaces nie będzie już widoczny w nieprawidłowej lokalizacji przez jedną klatkę.

Wersja 1.0.0-alpha03

26 lutego 2025 r.

Wersje androidx.xr.compose:compose:1.0.0-alpha03 i androidx.xr.compose:compose-testing:1.0.0-alpha03 nie zawierają żadnych istotnych zmian w porównaniu z ostatnią wersją alfa. Wersja 1.0.0-alpha03 zawiera te zmiany

Wersja 1.0.0-alpha02

12 lutego 2025 r.

androidx.xr.compose:compose:1.0.0-alpha02 i androidx.xr.compose:compose-testing:1.0.0-alpha02 zostają opublikowane. Wersja 1.0.0-alpha02 zawiera te zmiany.

Nowe funkcje

• Panel aktywności może teraz przyciemniać swoją zawartość, gdy jest aktywne okno przestrzenne.
• Interfejs Orbiter API jest teraz dostępny w kontekstach SubspaceComposable i będzie dołączać orbitery do najbliższego elementu nadrzędnego opartego na SubspaceLayout.
• Wprowadzono LayoutCoordinatesAwareModifierNode, aby umożliwić stosowanie modyfikatorów opartych na niestandardowym pozycjonowaniu.
• Dodaliśmy do SubspaceModifier.Node metody cyklu życia dołączania i odłączania.
• Dodano scaleWithDistance do przenośnego modyfikatora. Gdy opcja scaleWithDistance jest włączona, przeniesiony element podprzestrzeni powiększy się lub zmniejszy. Zachowa też skalę, którą miał przed przeniesieniem.

Zmiany w interfejsie API

• Usunięto SessionCallbackProvider na rzecz SpatialCapabilities.

Inne zmiany

• Zmniejszono wartość minSDK do 24. Wszystkie interfejsy Jetpack XR API nadal wymagają interfejsu API w wersji 34 w czasie działania.
• Konstruktory Orbiter EdgeOffset.inner, EdgeOffset.outer i EdgeOffset.overlap nie są już @Composable metodami, dzięki czemu można ich używać w kontekstach niekomponowalnych.
• Zaktualizuj poziomy wysokości przestrzennej, aby były zgodne z najnowszą specyfikacją UX.
• Zaimplementuj interfejs SubspaceSemanticsInfo w MeasurableLayout.
• Zmieniono nazwę SubspaceModifierElement na SubspaceModifierNodeElement.

Poprawki błędów

• Poprawki stabilizujące zamawianie SubspaceModifier. SubspaceModifier powinna działać bardziej niezawodnie. Modyfikatory przesunięcia, obrotu, skalowania, przenoszenia i zmiany rozmiaru powinny być teraz dostępne w dowolnej kolejności.

Wersja 1.0.0-alpha01

12 grudnia 2024 r.

Zostanie wycofaneandroidx.xr.compose:compose-*1.0.0-alpha01

Funkcje pierwszej wersji

• Pierwsza wersja Jetpack Compose na XR dla deweloperów. Używaj znanych koncepcji Compose, takich jak wiersze i kolumny, aby tworzyć przestrzenne układy interfejsu w XR, niezależnie od tego, czy przenosisz istniejącą aplikację 2D do XR, czy tworzysz nową aplikację XR od podstaw. Ta biblioteka udostępnia kompozycje podprzestrzenne i przestrzenne, takie jak panele przestrzenne i orbiter, które umożliwiają umieszczanie istniejącego interfejsu 2D opartego na Compose lub widokach w układzie przestrzennym. Wprowadza funkcję Volume subspace composable, która umożliwia umieszczanie elementów SceneCore, takich jak modele 3D, względem interfejsu. Więcej informacji znajdziesz w tym przewodniku dla programistów:

  • Subspace: ten komponent można umieścić w dowolnym miejscu w hierarchii interfejsu aplikacji, co pozwala zachować układy interfejsu 2D i przestrzennego bez utraty kontekstu między plikami. Ułatwia to udostępnianie elementów takich jak istniejąca architektura aplikacji między XR a innymi formatami bez konieczności przenoszenia stanu przez całe drzewo interfejsu lub przebudowywania aplikacji.

  • SpatialPanel: panel przestrzenny to komponent podrzędny, który umożliwia wyświetlanie treści aplikacji. Na przykład możesz wyświetlać odtwarzanie wideo, zdjęcia lub inne treści w panelu przestrzennym.

  • Orbiter: orbiter to przestrzenny komponent interfejsu. Jest on przeznaczony do dołączania do odpowiedniego panelu przestrzennego i zawiera elementy nawigacyjne oraz kontekstowe działania związane z tym panelem. Jeśli na przykład utworzysz panel przestrzenny do wyświetlania treści wideo, możesz dodać elementy sterujące odtwarzaniem wideo w orbiterze.

  • Objętość: umieszczaj elementy SceneCore, takie jak modele 3D, względem interfejsu.

• Układ przestrzenny: możesz utworzyć wiele paneli przestrzennych i umieścić je w układzie przestrzennym za pomocą funkcji SpatialRow, SpatialColumn, SpatialBox i SpatialLayoutSpacer. Użyj SubspaceModifier, aby dostosować układ.

• Komponenty interfejsu przestrzennego: te elementy można ponownie wykorzystać w interfejsie 2D, a ich atrybuty przestrzenne będą widoczne tylko wtedy, gdy włączone są funkcje przestrzenne.

  • SpatialDialog: panel lekko cofnie się w głąb, aby wyświetlić wysunięte okno.
  • SpatialPopUp: panel lekko się cofnie w głąb, aby wyświetlić wyskakujące okienko.
  • SpatialElevation: parametr SpatialElevationLevel można ustawić tak, aby dodać wysokość.

• SpatialCapabilities: możliwości przestrzenne mogą się zmieniać w miarę interakcji użytkowników z aplikacją lub systemem, a nawet być zmieniane przez samą aplikację – na przykład podczas przechodzenia do przestrzeni domowej lub pełnej. Aby uniknąć problemów, aplikacja musi sprawdzać wartość LocalSpatialCapabilities.current, aby określić, które interfejsy API są obsługiwane w bieżącym środowisku. isSpatialUiEnabled: elementy interfejsu przestrzennego (np.SpatialPanel), isContent3dEnabled: obiekty 3D, isAppEnvironmentEnabled: środowisko, isPassthroughControlEnabled: czy aplikacja może kontrolować stan passthrough, isSpatialAudioEnabled: dźwięk przestrzenny.

Znane problemy

• Obecnie do korzystania z Jetpack Compose na potrzeby XR wymagany jest pakiet SDK o wersji co najmniej 30. Aby obejść ten problem, możesz dodać ten wpis w pliku manifestu <uses-sdk tools:overrideLibrary="androidx.xr.scenecore, androidx.xr.compose"/>, aby móc tworzyć i uruchamiać aplikację z minimalnym SDK w wersji 23.
• Aplikacje Jetpack XR wymagają obecnie w pliku AndroidManifest prośby o uprawnienie android.permission.SCENE_UNDERSTANDING.
• Gdy aplikacja uruchamia się bezpośrednio w pełnej przestrzeni za pomocą właściwości PROPERTY_XR_ACTIVITY_START_MODE w pliku manifestu, działania/aplikacje są początkowo otwierane w przestrzeni domowej, a potem przechodzą do pełnej przestrzeni.
• Pliki glTF w komponentach Volume Composables mogą początkowo migać w nieprawidłowym miejscu.
• Użycie elementu SpatialDialog w panelu, który został znacznie przesunięty, spowoduje przesunięcie treści w niewłaściwym kierunku.