Jetpack Compose para XR

Jetpack Compose para XR

Guía del usuario  Muestra de código  Codelab

Referencia de la 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

Compila de forma declarativa diseños de IU espaciales que aprovechen las capacidades espaciales de Android XR.

Actualización más reciente	Versión estable	Versión potencial	Versión beta	Versión alfa
7 de mayo de 2025	-	-	-	1.0.0-alpha04

Cómo declarar dependencias

Para agregar una dependencia en XR Compose, debes agregar el repositorio de Maven de Google a tu proyecto. Consulta el repositorio de Maven de Google para obtener más información.

Agrega las dependencias de los artefactos que necesites en el archivo build.gradle de tu app o módulo:

GroovyKotlin Más

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

Para obtener más información sobre las dependencias, consulta Cómo agregar dependencias de compilación.

Comentarios

Tus comentarios ayudan a mejorar Jetpack. Avísanos si descubres nuevos errores o tienes ideas para mejorar esta biblioteca. Consulta los errores existentes de esta biblioteca antes de crear uno nuevo. Puedes agregar tu voto a un error existente haciendo clic en el botón de la estrella.

Crear un error nuevo

Consulta la documentación sobre la Herramienta de seguimiento de errores para obtener más información.

Versión 1.0

Versión 1.0.0-alpha04

7 de mayo de 2025

Lanzamiento de androidx.xr.compose:compose:1.0.0-alpha04 y androidx.xr.compose:compose-testing:1.0.0-alpha04. La versión 1.0.0-alpha04 contiene estas confirmaciones.

Nota: Necesitarás Android Emulator versión 35.6.7 o posterior para usar esta versión de la biblioteca.

Nuevas funciones

• Se agregó la interfaz CompositionLocalConsumerSubspaceModifierNode para permitir que los tipos SubspaceModifier personalizados accedan a los valores locales de composición.
• Se agregó una nueva API de SpatialPanel que sigue el estilo de implementación de AndroidView de Compose y deja de estar disponible la ViewBased SpatialPanel anterior.
• Se agregó el objeto complementario VolumeConstraints.Unbounded, que representa restricciones ilimitadas.
• Se agregó SubspaceModifier.onPointSourceParams para permitir una fuente de audio espacializada.
• Se agregó un ApplicationSubspace público que ofrece VolumeConstraints opcional para definir un área 3D en la que la app puede renderizar contenido espacial. De forma predeterminada, si no se especifican restricciones, el subespacio estará limitado por el campo de visión actual de SpatialUser en ancho y alto. Los usuarios pueden proporcionar restricciones para usar si no se puede determinar el campo de visión. De lo contrario, se usan los valores de ancho y alto del campo de visión predeterminados.
• Se agregó SpatialExternalSurface, que se puede usar para renderizar contenido estereoscópico. SpatialExternalSurface se puede personalizar con modificadores (excepto alfa) y un efecto de difuminado de bordes.
• Se agregó un nuevo modificador de subespacio pointerHoverIcon que permite a los usuarios establecer el ícono del puntero espacial.

Cambios en la API

• Se quitó la restricción de RequiresApi(34) en todos los paquetes de Jetpack XR. Esta restricción era redundante, ya que Jetpack XR actualmente solo está disponible en dispositivos con nivel de API 34 y versiones posteriores. (Iae0f8)
• Los proyectos lanzados con Kotlin 2.0 requieren KGP 2.0.0 o una versión posterior para su consumo. (Idb6b5).
• El manejo de Atrás ahora funcionará en paneles espaciales sin actividades incorporadas. Para que funcione el manejo del botón Atrás, debes especificar android:enableOnBackInvokedCallback="true" en el manifiesto de Android.
• El manejo del botón Atrás ahora funcionará en los diálogos espaciales. Para que funcione el manejo de atrás, debes especificar android:enableOnBackInvokedCallback="true" en el manifiesto de Android.
• Los SpatialPanel basados en Compose y en View ahora pueden ajustar su tamaño según su contenido.
• Ahora, los desarrolladores pueden establecer sus propios valores SpatialElevationLevel personalizados y no se limitan a los niveles predefinidos.
• Ahora se puede personalizar el nivel de elevación del orbitador a través del parámetro elevation.
• El subespacio ahora puede estar limitado por el campo de visión de SpatialUser en ancho y alto de forma predeterminada. Si no se puede determinar el campo de visión, se usan los valores predeterminados de ancho y alto del campo de visión.
• Se agregaron nuevas devoluciones de llamada onMoveStart y onMoveEnd al modificador Movable. Se llama a las devoluciones de llamada onMoveStart y onMoveEnd cuando el usuario comienza y finaliza el movimiento de un subespacio componible con el modificador movible.
• Se quitó el parámetro name de las APIs espaciales, como SpatialRow y SpatialPanel. Para depurar árboles de composición espacial, usa SubspaceModifier.testTag en su lugar.
• Se quitó una sobrecarga no admitida de SpatialPopup que solo tiene spatialElevationLevel y content. Usa la interfaz que admite onDimissRequest.
• Se quitó la devolución de llamada onPoseChange del modificador Movable. Usa onMove en su lugar.
• SubspaceModifiers ya no aplicará sus efectos si están separados o se están separando.
• La API de SpatialRow existente se dividió en SpatialRow y SpatialCurvedRow. Si antes usabas el parámetro curveRadius de SpatialRow, ahora usa SpatialCurvedRow, que ofrece el mismo comportamiento.
• MainPanel y ActivityPanel ya no tienen barras de título cuando se ejecutan en una imagen del sistema similarmente reciente.
• Los modificadores de escala y alfa ahora se pueden apilar y multiplicarán sus valores para el valor de escala o alfa aplicado final.
• Se optimizó la devolución de llamada onPoseChange del modificador Movable para realizar un movimiento de pose más fluido.
• Los modificadores móviles y de cambio de tamaño ahora realizarán sus devoluciones de llamada en el subproceso principal para garantizar que los cambios de estado activen la recomposición.
• Se agregó la observación de estado a las fases de diseño y medición para garantizar que los cambios de estado en SubspaceLayout activen el rediseño.
• Se optimizaron las actualizaciones de la cadena de modificadores para reutilizar mejor los modificadores existentes.

Correcciones de errores

• Se detuvo el recorte cuando se muestra un SpatialDialog. (Ic4594).
• Ahora se ignorarán las solicitudes de rediseño que se realicen mientras los nodos de modificador estén separados.
• Se quitaron las fases de rediseño activadas por los modificadores Movable y Resizable.
• Se corrigió una falla en el elemento componible MainPanel() que se producía cuando se establecía una dimensión en cero, ya sea directamente o durante un cálculo de diseño, p.ej., un cálculo de SpatialRow/SpatialColumn. En su lugar, el panel se ocultará. Ten en cuenta que esta corrección aborda específicamente las fallas durante la fase de diseño. El cambio de tamaño del panel a cero a través de la interacción del usuario se controlará por separado. El panel oculto carece de indicaciones visuales de la IU.
• Se corrigió el problema con maintainAspectRatio del modificador de tamaño variable. La relación de aspecto debería mantenerse ahora.
• Se corrigió un problema con los subespacios anidados en el que se posicionaban de forma incorrecta para un solo fotograma.
• Se corrigió un problema por el que, a veces, no se aplicaban las esquinas redondeadas cuando debían.
• NestedSubspaces ya no aparecerá para un fotograma en la ubicación incorrecta.

Versión 1.0.0-alpha03

26 de febrero de 2025

Lanzamiento de androidx.xr.compose:compose:1.0.0-alpha03 y androidx.xr.compose:compose-testing:1.0.0-alpha03 sin cambios notables desde la última versión alfa. La versión 1.0.0-alpha03 contiene estas confirmaciones.

Versión 1.0.0-alpha02

12 de febrero de 2025

Lanzamiento de androidx.xr.compose:compose:1.0.0-alpha02 y androidx.xr.compose:compose-testing:1.0.0-alpha02. La versión 1.0.0-alpha02 contiene estas confirmaciones.

Nuevas funciones

• El panel de actividades ahora puede ocultar su contenido cuando se activa un diálogo espacial.
• La API de Orbiter ahora se puede usar en contextos SubspaceComposable y adjuntará Orbiters a su elemento superior componible basado en SubspaceLayout más cercano.
• Se introdujo LayoutCoordinatesAwareModifierNode para permitir modificadores basados en posicionamiento personalizado.
• Se agregaron métodos de ciclo de vida de conexión/desconexión a SubspaceModifier.Node.
• Se agregó scaleWithDistance al modificador móvil. Cuando se habilita scaleWithDistance, el elemento de subespacio que se mueve aumentará o disminuirá. También mantendrá cualquier escala explícita que tuviera antes del movimiento.

Cambios en la API

• Se quitó SessionCallbackProvider a favor de SpatialCapabilities.

Otros cambios

• Se redujo minSDK a 24. Todas las APIs de Jetpack XR siguen requiriendo la API 34 en el entorno de ejecución.
• Los constructores Orbiter EdgeOffset.inner, EdgeOffset.outer y EdgeOffset.overlap ya no son métodos @Composable, lo que les permite usarse en contextos no componibles.
• Se actualizaron los niveles de elevación espacial para que coincidan con la especificación de UX más reciente.
• Implementa la interfaz SubspaceSemanticsInfo en MeasurableLayout.
• Se cambió el nombre de SubspaceModifierElement a SubspaceModifierNodeElement.

Correcciones de errores

• Se realizaron correcciones para estabilizar el orden de SubspaceModifier. SubspaceModifier debería comportarse de manera más confiable. Los modificadores de desplazamiento, rotación, escala, desplazamiento y tamaño se pueden usar en cualquier orden.

Versión 1.0.0-alpha01

12 de diciembre de 2024

Lanzamiento de androidx.xr.compose:compose-*1.0.0-alpha01.

Funciones de la versión inicial

• Lanzamiento inicial para desarrolladores de Jetpack Compose para XR. Usa conceptos conocidos de Compose, como filas y columnas, para crear diseños de IU espaciales en XR, ya sea que estés migrando una app 2D existente a XR o creando una nueva app de XR desde cero. Esta biblioteca proporciona elementos componibles espaciales y de subespacio, como paneles y orbitadores espaciales, que te permiten colocar tu IU existente de Compose 2D o basada en vistas en un diseño espacial. Presenta el elemento componible de subespacio de volumen, que te permite colocar entidades de SceneCore, como modelos 3D, en relación con tu IU. Obtén más información en esta guía para desarrolladores:

  • Subspace: Este elemento componible se puede colocar en cualquier lugar dentro de la jerarquía de la IU de tu app, lo que te permite mantener diseños para la IU 2D y espacial sin perder el contexto entre los archivos. Esto facilita compartir elementos como la arquitectura de la app existente entre XR y otros factores de forma sin necesidad de elevar el estado a través de todo el árbol de la IU ni volver a diseñar la arquitectura de tu app.

  • SpatialPanel: Un panel espacial es un subespacio componible que te permite mostrar contenido de la app. Por ejemplo, puedes mostrar la reproducción de videos, imágenes fijas o cualquier otro contenido en un panel espacial.

  • Orbitador: Un orbitador es un componente de IU espacial. Está diseñado para adjuntarse a un panel espacial correspondiente y contiene elementos de acción contextuales y de navegación relacionados con ese panel espacial. Por ejemplo, si creaste un panel espacial para mostrar contenido de video, puedes agregar controles de reproducción de video dentro de un orbitador.

  • Volumen: Coloca entidades de SceneCore, como modelos 3D, en relación con tu IU.

• Diseño espacial: Puedes crear varios paneles espaciales y colocarlos dentro de un diseño espacial con SpatialRow, SpatialColumn, SpatialBox y SpatialLayoutSpacer. Usa SubspaceModifier para personalizar tu diseño.

• Componentes de IU espaciales: Estos elementos se pueden volver a usar en tu IU 2D, y sus atributos espaciales solo serán visibles cuando se habiliten las capacidades espaciales.

  • SpatialDialog: El panel se empujará ligeramente hacia atrás en la profundidad en Z para mostrar un diálogo elevado.
  • SpatialPopUp: El panel se empujará ligeramente hacia atrás en la profundidad en Z para mostrar una ventana emergente elevada.
  • SpatialElevation: Se puede configurar SpatialElevationLevel para agregar elevación.

• SpatialCapabilities: Las capacidades espaciales pueden cambiar a medida que los usuarios interactúan con tu app o el sistema, o incluso pueden cambiarse desde la app, por ejemplo, cuando se pasa al espacio principal o al espacio completo. Para evitar problemas, tu app debe verificar LocalSpatialCapabilities.current para determinar qué APIs son compatibles con el entorno actual. isSpatialUiEnabled: Elementos de la IU espacial (p. ej., SpatialPanel) isContent3dEnabled: Objetos 3D isAppEnvironmentEnabled: El entorno isPassthroughControlEnabled: Indica si la aplicación puede controlar el estado de transferencia. isSpatialAudioEnabled: Audio espacial

Errores conocidos

• Actualmente, se requiere un minSDK de 30 para usar Jetpack Compose para XR. Como solución alternativa, puedes agregar la siguiente entrada de manifiesto <uses-sdk tools:overrideLibrary="androidx.xr.scenecore, androidx.xr.compose"/> para poder compilar y ejecutar con un minSDK de 23.
• Actualmente, las apps de Jetpack XR requieren solicitar el permiso android.permission.SCENE_UNDERSTANDING en AndroidManifest.
• Cuando una app se inicia directamente en el espacio completo con la propiedad PROPERTY_XR_ACTIVITY_START_MODE en su manifiesto, las actividades o aplicaciones se abren inicialmente en el espacio principal antes de migrar al espacio completo.
• Es posible que los glTF en elementos componibles de volumen parpadeen inicialmente en la ubicación incorrecta.
• Si usas un SpatialDialog en un panel que se movió de forma significativa, el contenido se enviará en la dirección incorrecta.