Эта страница переведена с помощью Cloud Translation API.

Jetpack Compose для XR

Руководство пользователя Пример кода Codelab

Справочник API
androidx.xr.compose.platform
androidx.xr.compose.spatial
androidx.xr.compose.subspace
androidx.xr.compose.subspace.layout
androidx.xr.compose.subspace.node
androidx.xr.compose.unit

Декларативно создавайте пространственные макеты пользовательского интерфейса, которые используют пространственные возможности Android XR.

Последнее обновление	Стабильный релиз	Кандидат на релиз	Бета-версия	Альфа-релиз
22 октября 2025 г.	-	-	-	1.0.0-альфа08

Объявление зависимостей

Чтобы добавить зависимость от XR Compose, необходимо добавить репозиторий Google Maven в свой проект. Подробнее см. в репозитории Google Maven .

Добавьте зависимости для необходимых артефактов в файл build.gradle вашего приложения или модуля:

классный

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

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

Котлин

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

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

Дополнительные сведения о зависимостях см. в разделе Добавление зависимостей сборки .

Обратная связь

Ваши отзывы помогают улучшить Jetpack. Сообщите нам, если вы обнаружите новые проблемы или у вас есть идеи по улучшению этой библиотеки. Пожалуйста, ознакомьтесь с уже существующими проблемами в этой библиотеке, прежде чем создавать новую. Вы можете проголосовать за существующую проблему, нажав на кнопку со звёздочкой.

Создать новый выпуск

Более подробную информацию см. в документации по системе отслеживания проблем .

Версия 1.0

Версия 1.0.0-альфа08

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 )

Исправления ошибок

Предотвращение сбоя при уничтожении активности с помощью подпространства. ( I595a1 )

Версия 1.0.0-альфа07

24 сентября 2025 г.

Выпущены androidx.xr.compose:compose:1.0.0-alpha07 и androidx.xr.compose:compose-testing:1.0.0-alpha07 . Версия 1.0.0-alpha07 содержит эти коммиты .

Изменения API

Улучшен KDocs для SpatialMainPanel . ( I27b70 , b/444467891 )
Представлен интерфейс SpatialArrangement для размещения дочерних элементов вдоль главной оси в трёхмерных макетах, таких как SpatialRow и SpatialColumn . Этот новый 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 для составных подпространств и замена параметра constraints на SubspaceModifier с SubspaceModifiers , зависящим от размера. Если allowUnboundedSubspace равно true, подпространства по-прежнему могут иметь неограниченные ограничения. ( Ib06e6 , b/433331675 )
Отказ от поддержки перемещаемых и изменяемых по размеру SubspaceModifiers теперь, когда DragPolicy() и ResizePolicy() являются частью API SpatialPanel и SpatialExternalSurface ( I397bf , b/437924639 )
Добавлена поддержка LayoutDirection в пространственных макетах. Компоновка с использованием SpatialAlignment теперь корректно размещает элементы как в контекстах с направлением слева направо, так и справа налево. ( I964bb , b/436300273 )
Добавьте параметры Resizable и Movable в API-интерфейсы Panel , чтобы гарантировать, что эти поведения могут применяться только к поддерживаемым контейнерам. ( Id491c )
Добавлены SubspaceModifiers sizeIn , widthIn , heightIn , depthIn , которые позволяют вам устанавливать точные минимальные и максимальные ограничения для ширины, высоты и глубины. ( I1af09 , b/433330761 )

Версия 1.0.0-альфа06

13 августа 2025 г.

Выпущены 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-альфа05

30 июля 2025 г.

Выпущены 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 Composables, представляющих сферы на 180 и 360 градусов. ( I40ef2 , b/391705799 )
Добавлен SubspaceModifier.aspectRatio ( Ide5ab , b/399729509 , b/414762147 )
Добавлен API SceneCoreEntity для улучшения взаимодействия между SceneCore и Compose для XR. ( I50bb3 , b/423020989 )
Предоставлен API GravityAlignedsubspace для поддержки немасштабированной функции And GravityAligned ( I07359 )

Изменения API

SpatialDialog() будет следовать конфигурации нажатия SpatialDialogProperties.dismissOnBack . ( Ib453b , b/416797132 )
Обновите minimumPanelDimension до нового размера Dimension по умолчанию Dimensions(0.1f, 0.1f, 0.1f) поскольку он представлен в метрах. ( Ib852a )
Подпространства и орбитеры теперь сохраняют своё внутреннее состояние в домашнем пространстве и когда приложение находится в фоновом режиме. В режиме домашнего пространства Подпространство по-прежнему будет настраивать сцену для подготовки к переходу в режим полного пространства. ( 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 , чтобы отличать его от Placeable из Compose. ( I74874 )
Удалены настройки Orbiter и добавлен новый параметр shouldRenderInNonSpatial . Кроме того, удален класс EdgeOffset и добавлен новый параметр orbiterOffsetType для объединения функций Orbiter() . Кроме того, OrbiterEdge переименован в ContentEdge . ( Iebf3d )
Переименован Measurable в SubspaceMeasurable , чтобы отличать тип от типа Measurable в Compose. ( I9726c )
Переименовать MeasureResult в SubspaceMeasureResult ( I9f34d )
Удален API setSubspaceContent в пользу использования setContent Compose с компонуемым Subspace . ( Ifff4c , b/421427391 , b/421427391 )
MeasurePolicy переименован в SubspaceMeasurePolicy . ( I37a9b , b/422553904 )
Превратите SubspaceSemanticsInfo в запечатанный интерфейс, поскольку мы не сможем добавлять элементы без значений по умолчанию. ( I372f9 , b/423704068 )
Обновлена документация SpatialExternalSurface , ContentSecurityLevel переименован в SurfaceProtection ( I3c460 , b/420982808 ).
Предоставлен перегруженный конструктор для модификатора movable, который позволяет выполнять якорную фиксацию. ( Ic0c70 )
Добавлен дополнительный поставщик позиционирования для всплывающих подсказок, чтобы разработчики могли управлять размещением подсказки над, под, слева или справа от якоря. Добавлен 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 )
Исправлено перекрытие topBar меню в SpatialComposeVideoPlayer ( Id33bc , b/427168167 )
Исправлена ошибка, из-за которой не отображался радиус угла ( I975fe , b/428261830 ).

Версия 1.0.0-альфа04

7 мая 2025 г.

Выпущены androidx.xr.compose:compose:1.0.0-alpha04 и androidx.xr.compose:compose-testing:1.0.0-alpha04 . Версия 1.0.0-alpha04 содержит эти коммиты .

Новые функции

Добавлен интерфейс CompositionLocalConsumerSubspaceModifierNode , позволяющий пользовательским типам SubspaceModifier получать доступ к локальным значениям композиции.
Добавлен новый API SpatialPanel , который следует стилю реализации AndroidView и отменяет поддержку предыдущего ViewBased SpatialPanel .
Добавлен сопутствующий объект VolumeConstraints.Unbounded , представляющий неограниченные ограничения.
Добавлен SubspaceModifier.onPointSourceParams для разрешения пространственного источника звука.
Добавлено публичное ApplicationSubspace с опциональными VolumeConstraints для определения трёхмерной области, в которой приложение может отображать пространственный контент. По умолчанию, если ограничения не указаны, подпространство будет ограничено текущим полем зрения SpatialUser по ширине и высоте. Пользователи могут указать ограничения, которые будут использоваться, если поле зрения определить невозможно. В противном случае используются значения ширины и высоты поля зрения по умолчанию.
Добавлен SpatialExternalSurface , который можно использовать для рендеринга стереоскопического контента. SpatialExternalSurface можно настраивать с помощью модификаторов (кроме альфа-канала) и эффекта размытия краёв.
Добавлен новый модификатор подпространства pointerHoverIcon , позволяющий пользователям устанавливать значок для пространственного указателя.

Изменения API

Убрано ограничение RequiresApi(34) для всех пакетов Jetpack XR. Это ограничение было излишним, поскольку Jetpack XR в настоящее время доступен только на устройствах с API уровня 34 и выше. ( Iae0f8 )
Для проектов, выпущенных с использованием Kotlin 2.0, требуется использование KGP 2.0.0 или более поздней версии. ( Idb6b5 )
Обратная обработка теперь будет работать на пространственных панелях без встроенных действий. Для этого необходимо указать android:enableOnBackInvokedCallback="true" в манифесте Android.
Обратный доступ теперь работает в пространственных диалогах. Для этого необходимо указать android:enableOnBackInvokedCallback="true" в манифесте Android.
SpatialPanel на основе Compose- и View-ориентированных элементов теперь могут менять свой размер в зависимости от своего содержимого.
Разработчики теперь могут задавать собственные значения SpatialElevationLevel и не ограничиваться предопределенными уровнями.
Уровень возвышения орбитального аппарата теперь можно настраивать с помощью параметра elevation .
Подпространство теперь может быть ограничено полем зрения SpatialUser по ширине и высоте по умолчанию. Если поле зрения определить невозможно, используются значения ширины и высоты поля зрения по умолчанию.
Добавлены новые обратные вызовы onMoveStart и onMoveEnd для модификатора Movable . Обратные вызовы onMoveStart и onMoveEnd вызываются, когда пользователь начинает и заканчивает перемещение подпространства, скомпонованного с модификатором Movable.
Параметр name был удалён из пространственных API, таких как SpatialRow и SpatialPanel . Для отладки пространственных составных деревьев используйте SubspaceModifier.testTag .
Удалена неподдерживаемая перегрузка SpatialPopup , которая содержит только spatialElevationLevel и content . Используйте интерфейс с поддержкой onDimissRequest .
Обратный вызов onPoseChange из модификатора Movable был удалён. Вместо него используйте onMove .
SubspaceModifiers больше не будут применять свои эффекты, если они отсоединены или в данный момент отсоединяются.
Существующий API SpatialRow был разделён на SpatialRow и SpatialCurvedRow . Если ранее использовался параметр curveRadius SpatialRow , теперь используйте SpatialCurvedRow , который обеспечивает то же поведение.
MainPanel и ActivityPanel больше не имеют заголовков при запуске на аналогичном последнем образе системы.
Модификаторы альфы и масштаба теперь можно суммировать, и они будут умножать свои значения для получения окончательного применяемого значения альфы или масштаба.
Обратный вызов onPoseChange из модификатора Movable был оптимизирован для обеспечения более плавного перемещения позы.
Перемещаемые и изменяемые по размеру модификаторы теперь будут выполнять свои обратные вызовы в основном потоке, чтобы гарантировать, что изменения состояния приведут к рекомпозиции.
Добавлено наблюдение за состоянием в фазы макета и измерения, чтобы гарантировать, что изменения состояния в SubspaceLayout приведут к запуску перераспределения.
Оптимизированные обновления цепочки модификаторов для более эффективного повторного использования существующих модификаторов.

Исправления ошибок

Остановлен скриминг при отображении SpatialDialog . ( Ic4594 )
Запросы на перекомпоновку, сделанные при отсоединенных узлах-модификаторах, теперь будут игнорироваться.
Удалены фазы перераспределения, вызываемые модификаторами Movable и Resizable.
Исправлен сбой в компонуемом элементе MainPanel() , возникавший при установке любого из измерений в ноль, как напрямую, так и во время расчёта макета, например, при расчёте SpatialRow/SpatialColumn . Панель теперь будет скрыта. Обратите внимание, что это исправление специально предназначено для устранения сбоев на этапе макета; изменение размера панели до нуля посредством взаимодействия с пользователем будет обрабатываться отдельно. Скрытая панель не имеет возможностей пользовательского интерфейса.
Исправлена проблема с maintainAspectRatio модификатора resizable. Теперь соотношение сторон должно сохраняться.
Исправлена проблема с вложенными подпространствами, из-за которой они неправильно позиционировались для одного кадра.
Исправлена ошибка, из-за которой скругленные углы иногда не применялись, когда это было необходимо.
NestedSubspaces больше не будет отображаться для одного кадра в неправильном месте.

Версия 1.0.0-альфа03

26 февраля 2025 г.

androidx.xr.compose:compose:1.0.0-alpha03 и androidx.xr.compose:compose-testing:1.0.0-alpha03 выпущены без каких-либо заметных изменений с момента последней альфа-версии. Версия 1.0.0-alpha03 содержит следующие коммиты.

Версия 1.0.0-альфа02

12 февраля 2025 г.

Выпущены androidx.xr.compose:compose:1.0.0-alpha02 и androidx.xr.compose:compose-testing:1.0.0-alpha02 . Версия 1.0.0-alpha02 содержит эти коммиты .

Новые функции

Панель действий теперь может просматривать свое содержимое при активации пространственного диалога.
API Orbiter теперь можно использовать в контекстах SubspaceComposable , и он будет прикреплять Orbiter к ближайшему компонуемому родительскому элементу на основе SubspaceLayout .
Введен LayoutCoordinatesAwareModifierNode для поддержки пользовательских модификаторов на основе позиционирования.
Добавлены методы жизненного цикла присоединения/отсоединения к SubspaceModifier.Node .
Добавлено значение scaleWithDistance для модификатора перемещения. При включении scaleWithDistance перемещаемый элемент подпространства будет увеличиваться или уменьшаться. При этом он сохранит свой явный масштаб, который был до перемещения.

Изменения API

Удален SessionCallbackProvider в пользу SpatialCapabilities .

Другие изменения

minSDK уменьшен до 24. Все API Jetpack XR по-прежнему требуют API 34 во время выполнения.
Конструкторы Orbiter EdgeOffset.inner , EdgeOffset.outer и EdgeOffset.overlap больше не являются методами @Composable , что позволяет использовать их в некомпозируемых контекстах.
Обновите уровни пространственной высоты в соответствии с последней спецификацией UX.
Реализовать интерфейс SubspaceSemanticsInfo в MeasurableLayout .
SubspaceModifierElement переименован в SubspaceModifierNodeElement .

Исправления ошибок

Исправления для стабилизации порядка SubspaceModifier . SubspaceModifier должен работать более надёжно. Модификаторы смещения, поворота, масштабирования, перемещения и изменения размера теперь можно использовать в любом порядке.

Версия 1.0.0-альфа01

12 декабря 2024 г.

Выпущен androidx.xr.compose:compose-*1.0.0-alpha01 .

Особенности первоначального выпуска

Первая версия Jetpack Compose для XR, разработанная разработчиками. Используйте знакомые концепции Compose, такие как строки и столбцы, для создания пространственных макетов пользовательского интерфейса в XR, независимо от того, портируете ли вы существующее 2D-приложение в XR или создаёте новое приложение XR с нуля. Эта библиотека предоставляет подпространственные и пространственные компоновочные элементы, такие как пространственные панели и орбитеры, которые позволяют размещать существующий 2D-Compose или пользовательский интерфейс на основе Views в пространственном макете. Она представляет подпространственный компоновочный элемент Volume, который позволяет размещать сущности SceneCore, такие как 3D-модели, относительно вашего пользовательского интерфейса. Подробнее в этом руководстве для разработчиков :
- Subspace : этот компонуемый объект можно разместить в любом месте иерархии пользовательского интерфейса вашего приложения, что позволяет поддерживать макеты для двухмерного и пространственного пользовательского интерфейса без потери контекста между файлами. Это упрощает обмен такими элементами, как существующая архитектура приложения, между XR и другими форм-факторами без необходимости переносить состояние по всему дереву пользовательского интерфейса или перестраивать архитектуру приложения.
- SpatialPanel : Пространственная панель — это компонуемое подпространство, позволяющее отображать содержимое приложения. Например, на пространственной панели можно отображать воспроизведение видео, неподвижные изображения или любой другой контент.
- Орбитер : Орбитер — это пространственный компонент пользовательского интерфейса. Он предназначен для присоединения к соответствующей пространственной панели и содержит элементы навигации и контекстные действия, связанные с этой пространственной панелью. Например, если вы создали пространственную панель для отображения видеоконтента, вы можете добавить элементы управления воспроизведением видео внутрь орбитера.
- Объем : Размещайте сущности SceneCore, такие как 3D-модели, относительно вашего пользовательского интерфейса.
Пространственная компоновка: вы можете создать несколько пространственных панелей и разместить их в пространственной компоновке, используя SpatialRow , SpatialColumn , SpatialBox и SpatialLayoutSpacer . Используйте SubspaceModifier для настройки компоновки.
Пространственные компоненты пользовательского интерфейса: эти элементы можно повторно использовать в вашем двухмерном пользовательском интерфейсе, а их пространственные атрибуты будут видны только при включенных пространственных возможностях.
- SpatialDialog : Панель слегка сдвинется назад по оси Z, чтобы отобразить приподнятое диалоговое окно.
- SpatialPopUp : Панель слегка отодвинется назад по оси Z, чтобы отобразить приподнятое всплывающее окно.
- SpatialElevation : SpatialElevationLevel можно задать для добавления высоты.
SpatialCapabilities: Пространственные возможности могут меняться по мере взаимодействия пользователей с вашим приложением или системой, а также могут быть изменены самим приложением, например, при переходе в Home Space или Full Space. Во избежание проблем вашему приложению необходимо проверять LocalSpatialCapabilities.current , чтобы определить, какие API поддерживаются в текущей среде. isSpatialUiEnabled : Пространственные элементы пользовательского интерфейса (например, SpatialPanel) isContent3dEnabled : 3D-объекты isAppEnvironmentEnabled : Среда; isPassthroughControlEnabled : Может ли приложение управлять состоянием сквозного пропуска isSpatialAudioEnabled : Пространственный звук.

Известные проблемы

В настоящее время для использования Jetpack Compose для XR требуется minSDK 30. В качестве обходного решения можно добавить следующую запись в манифест <uses-sdk tools:overrideLibrary="androidx.xr.scenecore, androidx.xr.compose"/> , чтобы сборка и запуск происходили с minSDK 23.
В настоящее время приложения Jetpack XR требуют запроса разрешения android.permission.SCENE_UNDERSTANDING в AndroidManifest.
Когда приложение запускается непосредственно в Full Space с использованием свойства PROPERTY_XR_ACTIVITY_START_MODE в своем манифесте, действия/приложения изначально открываются в Home Space, а затем переходят в Full Space.
glTF в Volume Composables могут изначально мерцать в неправильном месте.
Использование SpatialDialog на панели, которая была значительно перемещена, сместит содержимое в неправильном направлении.