Эта страница переведена с помощью 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.

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

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

Чтобы добавить зависимость от XR Compose, вам необходимо добавить в свой проект репозиторий Google Maven. Для получения дополнительной информации прочтите репозиторий Google Maven .

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

классный

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

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

Котлин

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

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

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

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

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

Создать новую задачу

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

Версия 1.0

Версия 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 , который соответствует стилю реализации Compose 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 на основе создания и просмотра теперь могут изменять свой размер в зависимости от их содержимого.
Разработчики теперь могут устанавливать свои собственные значения SpatialElevationLevel и не ограничиваться предопределенными уровнями.
Уровень возвышения орбитального аппарата теперь можно настроить с помощью параметра elevation .
Подпространство теперь может быть ограничено полем обзора SpatialUser по ширине и высоте по умолчанию. Если поле обзора невозможно определить, используются значения ширины и высоты поля обзора по умолчанию.
В модификатор Movable добавлены новые обратные вызовы onMoveStart и onMoveEnd . Обратные вызовы 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 был оптимизирован для обеспечения более плавного движения позы.
Модификаторы movable и resizeable теперь будут выполнять свои обратные вызовы в основном потоке, чтобы гарантировать, что изменения состояния вызовут рекомпозицию.
Добавлено наблюдение за состоянием в фазы макета и измерения, чтобы гарантировать, что изменения состояния в SubspaceLayout вызовут ретрансляцию.
Оптимизированы обновления цепочки модификаторов для лучшего повторного использования существующих модификаторов.

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

Перестал работать при отображении SpatialDialog . ( Ic4594 )
Запросы на ретрансляцию, сделанные при отсоединенных узлах-модификаторах, теперь будут игнорироваться.
Удалены фазы реле, запускаемые модификаторами Movable и Resizable.
Исправлен сбой в компонуемой функции MainPanel() , который возникал, когда для любого измерения было установлено нулевое значение либо непосредственно, либо во время расчета макета, например расчета SpatialRow/SpatialColumn . Вместо этого панель теперь будет скрыта. Обратите внимание, что это исправление специально предназначено для устранения сбоев на этапе макетирования; изменение размера панели до нуля посредством взаимодействия с пользователем будет обрабатываться отдельно. На скрытой панели отсутствуют возможности пользовательского интерфейса.
Исправлена проблема с maintainAspectRatio из модификатора изменяемого размера. Соотношение сторон теперь должно быть сохранено.
Исправлена проблема с вложенными подпространствами, из-за которой они неправильно располагались в одном кадре.
Исправлена ошибка, из-за которой закругленные углы иногда не применялись там, где это необходимо.
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 добавлены методы жизненного цикла присоединения/отсоединения.
К модификатору movable добавлен 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-композиции или представлений в пространственном макете. Он представляет компонуемое подпространство Volume, которое позволяет вам размещать объекты SceneCore, такие как 3D-модели, относительно вашего пользовательского интерфейса. Узнайте больше в этом руководстве для разработчиков :
- Subspace : этот составной элемент можно разместить в любом месте иерархии пользовательского интерфейса вашего приложения, что позволяет вам поддерживать макеты для 2D- и пространственного пользовательского интерфейса без потери контекста между файлами. Это упрощает совместное использование таких вещей, как существующая архитектура приложения, между XR и другими форм-факторами без необходимости поднимать состояние по всему дереву пользовательского интерфейса или перепроектировать ваше приложение.
- SpatialPanel : пространственная панель — это компонуемое подпространство, которое позволяет отображать содержимое приложения — например, вы можете отображать воспроизведение видео, неподвижные изображения или любой другой контент на пространственной панели.
- Орбитер : Орбитальный аппарат — это пространственный компонент пользовательского интерфейса. Он предназначен для прикрепления к соответствующей пространственной панели и содержит элементы навигации и контекстных действий, связанные с этой пространственной панелью. Например, если вы создали пространственную панель для отображения видеоконтента, вы можете добавить элементы управления воспроизведением видео внутри орбитального аппарата.
- Volume : размещайте объекты SceneCore, такие как 3D-модели, относительно вашего пользовательского интерфейса.
Пространственный макет: вы можете создать несколько пространственных панелей и разместить их в пространственном макете с помощью SpatialRow , SpatialColumn , SpatialBox и SpatialLayoutSpacer . Используйте SubspaceModifier для настройки макета.
Компоненты пространственного пользовательского интерфейса. Эти элементы можно повторно использовать в вашем 2D-интерфейсе, а их пространственные атрибуты будут видны только при включении пространственных возможностей.
- SpatialDialog : панель слегка отодвинется назад по оси Z, чтобы отобразить диалоговое окно с повышенными правами.
- SpatialPopUp : панель слегка отодвинется назад по оси Z, чтобы отобразить приподнятое всплывающее окно.
- SpatialElevation : можно задать SpatialElevationLevel для добавления высоты.
Пространственные возможности. Пространственные возможности могут меняться по мере взаимодействия пользователей с вашим приложением или системой или даже могут быть изменены самим вашим приложением, например при перемещении в «Домашнее пространство» или «Полное пространство». Чтобы избежать проблем, вашему приложению необходимо проверить 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.
Когда приложение запускается непосредственно в «Полном пространстве» с использованием свойства PROPERTY_XR_ACTIVITY_START_MODE в своем манифесте, действия/приложения сначала открываются в «Домашнем пространстве», а затем переходят в «Полное пространство».
glTF в Volume Composables может изначально мерцать в неправильном месте.
Использование SpatialDialog на панели, которая была значительно перемещена, приведет к смещению содержимого в неправильном направлении.