Jetpack Compose para XR

Crea 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
30 de julio de 2025 - - - 1.0.0-alpha05

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:

Groovy

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

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-alpha05

30 de julio de 2025

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

Nuevas funciones

  • Se hizo pública la clase de anotación SubspaceComposable. (Ic2a34, b/399432430)
  • Dos nuevos elementos SpatialExternalSurface componibles que representan esferas de 180 y 360 grados. (I40ef2, b/391705799)
  • Se agregó SubspaceModifier.aspectRatio (Ide5ab, b/399729509, b/414762147).
  • Se agregó la API de SceneCoreEntity para mejorar la interoperabilidad entre SceneCore y Compose para XR. (I50bb3, b/423020989)
  • Se proporcionó la API de GravityAlignedsubspace para admitir la función GravityAligned sin escalar (I07359).

Cambios en la API

  • SpatialDialog() seguirá la configuración de presión de SpatialDialogProperties.dismissOnBack. (Ib453b, b/416797132)
  • Actualiza minimumPanelDimension a un nuevo tamaño de dimensión predeterminado de Dimensions(0.1f, 0.1f, 0.1f) debido a su representación en metros. (Ib852a)
  • Los subespacios y los orbitadores ahora conservarán su estado interno en el espacio principal y cuando la app esté en segundo plano. En el modo de espacio principal, Subspace seguirá configurando su escena en preparación para el cambio al modo de espacio completo. (I40317, b/416037751)
  • SpatialDialogs ahora conservará su estado cuando la app esté en segundo plano. (I6aa56)
  • ApplicationSubspace ahora heredará su posición y escala recomendadas del sistema. (I4565f, b/418834194)
  • Se agregó un mejor mensaje de error y se activa el error antes cuando se usa un SubspaceComposable en un contexto que no es de SubspaceComposable. (Iee2ae, b/416484684)
  • Se actualizó ExperimentalSubspaceVolumeApi de Advertencia a Error porque, a menudo, se pasan por alto las advertencias cuando se usan de forma incorrecta las APIs componibles. (I427aa, b/424864286)
  • Ahora, el subespacio y ApplicationSubspace están restringidos por recommendedContentBoxInFullSpace. Anteriormente, estaba restringido por el campo de visión de SpatialUser. (I41015, b/423074142)
  • Se actualizó SpatialElevation para que use el tamaño mínimo y ya no use el tamaño codificado de forma rígida (I2dbe6, b/427785338).
  • Actualiza la forma en que realizamos el scrim del SpatialAcitivityPanel para que se actualice cuando se modifique una variable clave. (I0f64d, b/427999029)
  • Quita VolumeConstraints.Unbounded y establece los valores de restricción predeterminados en el equivalente. (Ie24ec, b/407938414)
  • SpatialFeatheringSize ya no es público (I1c15b, b/399432430).
  • Se cambió el nombre de Placeable de XR a SubspacePlaceable para distinguirlo del Placeable de Compose. (I74874)
  • Se quitaron los parámetros de configuración de Orbiter y se agregó shouldRenderInNonSpatial como un parámetro nuevo. Además, se quitó la clase EdgeOffset y se agregó orbiterOffsetType como un nuevo parámetro para consolidar las funciones de Orbiter(). Además de cambiar el nombre de OrbiterEdge a ContentEdge (Iebf3d)
  • Se cambió el nombre de Measurable a SubspaceMeasurable para diferenciar el tipo del tipo Measurable de Compose. (I9726c)
  • Se cambió el nombre de MeasureResult por SubspaceMeasureResult (I9f34d).
  • Se quitó la API de setSubspaceContent y se reemplazó por setContent de Compose con un elemento Subspace componible. (Ifff4c, b/421427391, b/421427391)
  • El nombre de MeasurePolicy cambió por SubspaceMeasurePolicy. (I37a9b, b/422553904)
  • Convierte SubspaceSemanticsInfo en una interfaz sellada porque no podremos agregar miembros sin los valores predeterminados. (I372f9, b/423704068)
  • Se actualizó la documentación de SpatialExternalSurface y se cambió el nombre de ContentSecurityLevel a SurfaceProtection (I3c460, b/420982808).
  • Se proporcionó un constructor sobrecargado para el modificador movible que permite el anclaje. (Ic0c70)
  • Se agregaron más proveedores de posición para las sugerencias, de modo que ahora los desarrolladores pueden controlar si la sugerencia se coloca arriba, abajo, a la izquierda o a la derecha del elemento de anclaje. Agrega una API que tome una forma para los cursores, de modo que se puedan proporcionar más formas personalizadas. (Ie513c, b/374766087, b/418854637)
  • Se quitó CoreEntity como PublishedApi (Ifee05)

Correcciones de errores

  • Se corrigió el problema por el que SpatialDialog parpadeaba cuando se renderizaba. (Ife73c, b/401619909)
  • Se corrigió un problema por el que SpatialDialog no podía aplicar una pantalla de atenuación al panel de actividades. (I8ca6c, b/367442109)
  • Se corrigió un problema por el que el diálogo de XR no mostraba parte del contenido (I17cd5, b/418062437).
  • Se corrigió el problema por el que se descartaba SpatialPopup cuando se hacía clic dentro del contenido. (If262c, b/417245722)
  • Se corrigió el problema por el que, cuando se encadenaba resizable().movable(), SpatialPanel no cambiaba de tamaño correctamente al nuevo tamaño. (I02ee3, b/422264230)
  • Se corrigió el problema de superposición de topBar con el menú en SpatialComposeVideoPlayer (Id33bc, b/427168167).
  • Se corrigió el problema por el que no se renderizaba el radio de esquina (I975fe, b/428261830).

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.

Nuevas funciones

  • Se agregó la interfaz CompositionLocalConsumerSubspaceModifierNode para permitir que los tipos de 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 dejó de estar disponible la API de ViewBased SpatialPanel anterior.
  • Se agregó el objeto complementario VolumeConstraints.Unbounded, que representa restricciones no acotadas.
  • Se agregó SubspaceModifier.onPointSourceParams para permitir una fuente de audio espacializado.
  • Se agregó un ApplicationSubspace público que ofrece un 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 del SpatialUser en ancho y alto. Los usuarios pueden proporcionar restricciones para usarse si no se puede determinar el campo de visión. De lo contrario, se usan los valores predeterminados de ancho y alto del campo de visión.
  • 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 el nivel de API 34 y versiones posteriores. (Iae0f8)
  • Los proyectos lanzados con Kotlin 2.0 requieren que se consuma KGP 2.0.0 o una versión posterior. (Idb6b5)
  • El control de la acción Atrás ahora funcionará en paneles espaciales sin actividades integradas. Para que funcione el control de atrás, debes especificar android:enableOnBackInvokedCallback="true" en el manifiesto de Android.
  • El control de la acción de volver ahora funcionará en los diálogos espaciales. Para que el control de atrás funcione, debes especificar android:enableOnBackInvokedCallback="true" en el manifiesto de Android.
  • Los SpatialPanel basados en Compose y en View ahora pueden ajustarse según su contenido.
  • Ahora, los desarrolladores pueden establecer sus propios valores de SpatialElevationLevel personalizados y no están limitados a los niveles predefinidos.
  • Ahora se puede personalizar el nivel de elevación del orbitador a través del parámetro elevation.
  • Ahora, de forma predeterminada, el subespacio puede estar limitado por el campo de visión de SpatialUser en ancho y altura. 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 las nuevas devoluciones de llamada onMoveStart y onMoveEnd al modificador Movable. Se llaman a las devoluciones de llamada onMoveStart y onMoveEnd cuando el usuario comienza y termina de mover un elemento componible de subespacio con el modificador movable.
  • 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 compatible 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 se desconecta o se está desconectando.
  • 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 reciente similar.
  • Los modificadores alfa y de escala ahora se pueden apilar y multiplicarán sus valores para obtener el valor final de alfa o escala aplicado.
  • Se optimizó la devolución de llamada onPoseChange del modificador Movable para que el movimiento de la postura sea más fluido.
  • Los modificadores movibles y redimensionables 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 del 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 scrimming cuando se muestra un SpatialDialog. (Ic4594)
  • Ahora se ignorarán las solicitudes de nuevo diseño realizadas mientras los nodos de modificador están separados.
  • Se quitaron las fases de nuevo diseño activadas por los modificadores Movable y Resizable.
  • Se corrigió una falla en el elemento MainPanel() componible que se producía cuando cualquiera de las dimensiones se establecía en cero, ya sea directamente o durante un cálculo de diseño, p.ej., un cálculo de SpatialRow/SpatialColumn. En su lugar, ahora se ocultará el panel. 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 no tiene indicaciones visuales de la IU.
  • Se corrigió un problema con maintainAspectRatio del modificador redimensionable. Ahora se debería mantener la relación de aspecto.
  • 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 aplicarse.
  • NestedSubspaces ya no aparecerá en 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

  • Ahora, el Panel de actividad puede aplicar una capa de atenuación a su contenido cuando se activa un diálogo espacial.
  • Ahora se puede usar la API de Orbiter en contextos de SubspaceComposable y se adjuntarán los Orbiters a su elemento SubspaceLayout componible principal más cercano.
  • Se introdujo LayoutCoordinatesAwareModifierNode para permitir modificadores personalizados basados en la posición.
  • Se agregaron métodos de ciclo de vida de adjuntar/separar a SubspaceModifier.Node.
  • Se agregó scaleWithDistance al modificador de movimiento. Cuando scaleWithDistance está habilitado, el elemento del subespacio que se mueve crecerá o se reducirá. 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 tiempo de ejecución.
  • Los constructores Orbiter EdgeOffset.inner, EdgeOffset.outer y EdgeOffset.overlap ya no son métodos @Composable, lo que permite usarlos 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 ordenamiento de SubspaceModifier. SubspaceModifier debería comportarse de forma más confiable. Los modificadores de desplazamiento, rotación, escala, movimiento y cambio de tamaño ahora 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

  • Se lanzó la versión 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 portando una app 2D existente a XR o creando una nueva app para XR desde cero. Esta biblioteca proporciona elementos componibles espaciales y de subespacio, como paneles espaciales y orbitadores, que te permiten colocar tu IU existente basada en Compose o Views en un diseño espacial. Se presenta el elemento componible del subespacio Volume, 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 espacial y en 2D sin perder el contexto entre los archivos. Esto facilita compartir elementos como la arquitectura de la app existente entre la 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 la app.

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

    • Orbitador: Un orbitador es un componente de la IU espacial. Está diseñado para adjuntarse a un panel espacial correspondiente y contiene elementos de acción contextual y de navegación relacionados con ese panel espacial. Por ejemplo, si creaste un panel espacial para mostrar contenido de video, podrías 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 SubspaceModifiers para personalizar tu diseño.

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

    • SpatialDialog: El panel se desplazará ligeramente hacia atrás en la profundidad Z para mostrar un diálogo elevado.
    • SpatialPopUp: El panel se desplazará ligeramente hacia atrás en la profundidad 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 tu app puede cambiarlas, 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 se admiten en 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 que se solicite 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 pasar al espacio completo.
  • Es posible que los glTF en los elementos Volume Composables parpadeen inicialmente en la ubicación incorrecta.
  • Si usas un SpatialDialog en un panel que se movió de forma significativa, el contenido se desplazará en la dirección incorrecta.