Jetpack Compose para XR

Declarar dependências

Para adicionar uma dependência ao XR Compose, adicione o repositório Maven do Google ao seu projeto. Leia Repositório Maven do Google para ver mais informações.

Adicione as dependências dos artefatos necessários ao arquivo build.gradle do seu app ou módulo:

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

Para mais informações sobre dependências, consulte Adicionar dependências de build.

Feedback

Seu feedback ajuda a melhorar o Jetpack. Avise se você descobrir novos problemas ou tiver ideias para melhorar esta biblioteca. Consulte os problemas conhecidos nesta biblioteca antes de criar um novo. Adicione seu voto a um problema clicando no botão de estrela.

Criar novo problema

Consulte a documentação do Issue Tracker para saber mais.

Versão 1.0

Versão 1.0.0-alpha05

30 de julho de 2025

Lançamento de androidx.xr.compose:compose:1.0.0-alpha05 e androidx.xr.compose:compose-testing:1.0.0-alpha05. A versão 1.0.0-alpha05 contém estas confirmações.

Novos recursos

• Tornamos a classe de anotação SubspaceComposable pública. (Ic2a34, b/399432430)
• Dois novos elementos combináveis SpatialExternalSurface que representam esferas de 180 e 360 graus. (I40ef2, b/391705799).
• Adição de SubspaceModifier.aspectRatio (Ide5ab, b/399729509, b/414762147).
• Adição da API SceneCoreEntity para melhorar a interoperabilidade entre SceneCore e o Compose para XR. (I50bb3, b/423020989)
• Foi fornecida a API GravityAlignedsubspace para oferecer suporte ao recurso GravityAligned e sem escalonamento (I07359).

Mudanças na API

• O SpatialDialog() vai seguir a configuração de pressionamento de SpatialDialogProperties.dismissOnBack. (Ib453b, b/416797132)
• Atualize minimumPanelDimension para um novo tamanho padrão de dimensão de Dimensions(0.1f, 0.1f, 0.1f) devido à representação em metros. (Ib852a).
• Os subespaços e os orbitadores agora vão manter o estado interno no espaço da casa e quando o app estiver em segundo plano. No modo de espaço compacto, o Subspace ainda vai configurar a cena em preparação para a mudança para o modo de espaço ampliado. (I40317, b/416037751).
• Agora, SpatialDialogs vai manter o estado quando o app estiver em segundo plano. (I6aa56).
• Agora, o ApplicationSubspace herda a escala e a posição recomendadas do sistema. (I4565f, b/418834194)
• Adição de uma mensagem de erro melhor e acionamento do erro mais cedo quando um SubspaceComposable é usado em um contexto não SubspaceComposable. (Iee2ae, b/416484684)
• Atualização de ExperimentalSubspaceVolumeApi de "Aviso" para "Erro" porque os avisos geralmente são ignorados ao usar APIs combináveis de maneira incorreta. (I427aa, b/424864286)
• O Subspace e o ApplicationSubspace agora são restritos pelo recommendedContentBoxInFullSpace. Antes, ela era restrita pelo campo de visão de SpatialUser. (I41015, b/423074142).
• Atualização de SpatialElevation para usar o tamanho mínimo e não mais o tamanho codificado (I2dbe6, b/427785338).
• Atualize como fazemos o scrim do SpatialAcitivityPanel para atualizar quando uma variável principal é modificada. (I0f64d, b/427999029)
• Remova VolumeConstraints.Unbounded e defina os valores de restrição padrão como o equivalente. (Ie24ec, b/407938414)
• O SpatialFeatheringSize não é mais público (I1c15b, b/399432430).
• Renomeamos o Placeable do XR como SubspacePlaceable para diferenciá-lo do Placeable do Compose. (I74874).
• Remoção das configurações do Orbiter e adição de shouldRenderInNonSpatial como um novo parâmetro. Além disso, remova a classe EdgeOffset e adicione orbiterOffsetType como um novo parâmetro para consolidar as funções Orbiter(). Além de renomear OrbiterEdge como ContentEdge. (Iebf3d).
• Renomeado Measurable para SubspaceMeasurable para diferenciar o tipo do tipo Measurable do Compose. (I9726c).
• MeasureResult foi renomeado como SubspaceMeasureResult (I9f34d).
• Removemos a API setSubspaceContent para usar o setContent do Compose com um elemento combinável Subspace. (Ifff4c, b/421427391, b/421427391)
• MeasurePolicy foi renomeado como SubspaceMeasurePolicy. (I37a9b, b/422553904)
• Transforme SubspaceSemanticsInfo em uma interface selada porque não será possível adicionar membros sem os padrões. (I372f9, b/423704068)
• Atualização da documentação de SpatialExternalSurface e renomeação de ContentSecurityLevel para SurfaceProtection (I3c460, b/420982808).
• Fornecido construtor sobrecarregado para modificador móvel que permite ancoragem. (Ic0c70)
• Adição de mais um provedor de posição para dicas. Agora os desenvolvedores podem controlar se a dica é colocada acima, abaixo, à esquerda ou à direita da âncora. Adicione uma API que receba uma forma para acentos circunflexos, para que mais formas personalizadas possam ser fornecidas. (Ie513c, b/374766087, b/418854637).
• CoreEntity removido como PublishedApi (Ifee05)

Correções de bugs

• Correção do problema em que SpatialDialog piscava ao ser renderizado. (Ife73c, b/401619909)
• Correção de um problema em que SpatialDialog não podia encobrir o painel de atividades. (I8ca6c, b/367442109)
• Correção da caixa de diálogo de RV que não mostrava alguns conteúdos (I17cd5, b/418062437).
• Correção de um problema em que o SpatialPopup era dispensado quando clicado dentro do conteúdo. (If262c, b/417245722)
• Corrigimos o problema em que, ao encadear resizable().movable(), o SpatialPanel não era redimensionado corretamente para o novo tamanho. (I02ee3, b/422264230)
• Correção da sobreposição de topBar com o menu em SpatialComposeVideoPlayer (Id33bc, b/427168167).
• Correção do raio do canto que não estava sendo renderizado (I975fe, b/428261830).

Versão 1.0.0-alpha04

7 de maio de 2025

Lançamento de androidx.xr.compose:compose:1.0.0-alpha04 e androidx.xr.compose:compose-testing:1.0.0-alpha04. A versão 1.0.0-alpha04 contém estas confirmações.

Novos recursos

• Adição da interface CompositionLocalConsumerSubspaceModifierNode para permitir que tipos SubspaceModifier personalizados acessem valores locais de composição.
• Adicionamos uma nova API SpatialPanel que segue o estilo de implementação do AndroidView do Compose e descontinuamos a ViewBased SpatialPanel anterior.
• Adicionado o objeto complementar VolumeConstraints.Unbounded, que representa restrições ilimitadas.
• Adicionamos SubspaceModifier.onPointSourceParams para permitir uma fonte de áudio espacializada.
• Um ApplicationSubspace público foi adicionado, oferecendo VolumeConstraints opcionais para definir uma área 3D em que o app pode renderizar conteúdo espacial. Por padrão, se nenhuma restrição for especificada, o subespaço será limitado pelo campo de visão atual da SpatialUser em largura e altura. Os usuários podem fornecer restrições a serem usadas se o campo de visão não puder ser determinado. Caso contrário, os valores padrão de largura e altura do campo de visão serão usados.
• Adição de SpatialExternalSurface, que pode ser usado para renderizar conteúdo estereoscópico. SpatialExternalSurface pode ser personalizado com modificadores (exceto alfa) e um efeito de esmaecimento de borda.
• Adicionamos um novo modificador de subespaço pointerHoverIcon que permite aos usuários definir o ícone do ponteiro espacial.

Mudanças na API

• Removemos a restrição RequiresApi(34) de todos os pacotes do Jetpack XR. Essa restrição era redundante, já que o Jetpack XR está disponível apenas em dispositivos com nível 34 ou mais da API. (Iae0f8)
• Os projetos lançados com o Kotlin 2.0 exigem o KGP 2.0.0 ou mais recente para serem consumidos. (Idb6b5)
• O processamento de volta agora funciona em painéis espaciais sem atividades incorporadas. Para que o processamento de volta funcione, é necessário especificar android:enableOnBackInvokedCallback="true" no manifesto do Android.
• O processamento de volta agora funciona em caixas de diálogo espaciais. Para que o processamento de volta funcione, é necessário especificar android:enableOnBackInvokedCallback="true" no manifesto do Android.
• Os SpatialPanels baseados em Compose e em visualização agora podem se dimensionar com base no conteúdo.
• Agora, os desenvolvedores podem definir seus próprios valores de SpatialElevationLevel personalizados e não estão limitados aos níveis predefinidos.
• Agora é possível personalizar o nível de elevação do Orbiter usando o parâmetro elevation.
• Agora, o subespaço pode ser limitado pelo campo de visão do SpatialUser em largura e altura por padrão. Se não for possível determinar o campo de visão, os valores padrão de largura e altura serão usados.
• Adição dos novos callbacks onMoveStart e onMoveEnd ao modificador Movable. Os callbacks onMoveStart e onMoveEnd são chamados quando o usuário começa e termina de mover um elemento combinável de subespaço com o modificador móvel.
• O parâmetro name foi removido das APIs espaciais, como SpatialRow e SpatialPanel. Para depurar árvores de composição espacial, use SubspaceModifier.testTag.
• Removemos uma sobrecarga sem suporte de SpatialPopup que só tem spatialElevationLevel e content. Use a interface compatível com onDimissRequest.
• O callback onPoseChange do modificador Movable foi removido. Use onMove.
• SubspaceModifiers não vai mais aplicar os efeitos se estiverem separados ou em processo de separação.
• A API SpatialRow atual foi dividida em SpatialRow e SpatialCurvedRow. Se você usava o parâmetro curveRadius de SpatialRow, agora use SpatialCurvedRow, que oferece o mesmo comportamento.
• MainPanel e ActivityPanel não têm mais barras de título quando executados em uma imagem do sistema igualmente recente.
• Os modificadores de alfa e escala agora podem ser combinados e multiplicam os valores para o valor final de alfa ou escala aplicado.
• O callback onPoseChange do modificador Movable foi otimizado para realizar movimentos de postura mais suaves.
• Agora, os modificadores móveis e redimensionáveis vão executar os callbacks na linha de execução principal para garantir que as mudanças de estado acionem a recomposição.
• Adição de observação de estado às fases de layout e medição para garantir que as mudanças de estado em SubspaceLayout acionem um novo layout.
• Atualizações otimizadas da cadeia de modificadores para reutilizar melhor os modificadores atuais.

Correções de bugs

• A tela esmaecida para de aparecer quando um SpatialDialog é mostrado. (Ic4594)
• As solicitações de readequação feitas enquanto os nós modificadores estão separados agora serão ignoradas.
• Remoção das fases de readequação acionadas pelos modificadores Movable e Resizable.
• Corrigimos uma falha no elemento combinável MainPanel() que ocorria quando uma das dimensões era definida como zero, diretamente ou durante um cálculo de layout, por exemplo, um cálculo de SpatialRow/SpatialColumn. Em vez disso, o painel vai ficar oculto. Essa correção aborda especificamente falhas durante a fase de layout. O redimensionamento do painel para zero por interação do usuário será tratado separadamente. O painel oculto não tem recursos de acessibilidade da interface.
• Correção do problema com maintainAspectRatio do modificador redimensionável. A proporção será mantida.
• Foi corrigido um problema com subespaços aninhados que eram posicionados incorretamente em um único frame.
• Correção de um problema em que, às vezes, os cantos arredondados não eram aplicados quando deveriam ser.
• NestedSubspaces não vai mais aparecer por um frame no local errado.

Versão 1.0.0-alpha03

26 de fevereiro de 2025

Lançamento de androidx.xr.compose:compose:1.0.0-alpha03 e androidx.xr.compose:compose-testing:1.0.0-alpha03, sem mudanças importantes desde a última versão Alfa. A versão 1.0.0-alpha03 contém estas confirmações.

Versão 1.0.0-alpha02

12 de fevereiro de 2025

Lançamento de androidx.xr.compose:compose:1.0.0-alpha02 e androidx.xr.compose:compose-testing:1.0.0-alpha02. A versão 1.0.0-alpha02 contém estas confirmações.

Novos recursos

• O painel de atividades agora pode escurecer o conteúdo quando uma caixa de diálogo espacial é ativada.
• A API Orbiter agora pode ser usada em contextos SubspaceComposable e vai anexar Orbiters ao elemento combinável pai mais próximo com base em SubspaceLayout.
• Introdução de LayoutCoordinatesAwareModifierNode para permitir modificadores personalizados com base no posicionamento.
• Adição de métodos de ciclo de vida de anexação/desanexação a SubspaceModifier.Node.
• Adição de scaleWithDistance ao modificador móvel. Quando scaleWithDistance está ativado, o elemento do subespaço movido aumenta ou diminui. Ele também vai manter qualquer escala explícita que tinha antes do movimento.

Mudanças na API

• SessionCallbackProvider foi removido em favor de SpatialCapabilities.

Outras mudanças

• Reduzimos minSDK para 24. Todas as APIs do Jetpack XR ainda exigem a API 34 no tempo de execução.
• Os construtores Orbiter EdgeOffset.inner, EdgeOffset.outer e EdgeOffset.overlap não são mais métodos @Composable, o que permite que sejam usados em contextos não combináveis.
• Atualize os níveis de elevação espacial para corresponder à especificação de UX mais recente.
• Implemente a interface SubspaceSemanticsInfo em MeasurableLayout.
• SubspaceModifierElement foi renomeado como SubspaceModifierNodeElement

Correções de bugs

• Correções para estabilizar a ordenação de SubspaceModifier. SubspaceModifier vai funcionar de maneira mais confiável. Agora, os modificadores de deslocamento, rotação, escala, móvel e redimensionável podem ser usados em qualquer ordem.

Versão 1.0.0-alpha01

12 de dezembro de 2024

Lançamento de androidx.xr.compose:compose-*1.0.0-alpha01.

Recursos da versão inicial

• Versão inicial para desenvolvedores do Jetpack Compose para XR. Use conceitos conhecidos do Compose, como linhas e colunas, para criar layouts de interface espacial em XR, seja portando um app 2D para XR ou criando um novo app XR do zero. Essa biblioteca oferece elementos combináveis espaciais e de subespaço, como painéis espaciais e orbitadores, que permitem colocar sua interface 2D do Compose ou baseada em Views em um layout espacial. Ele apresenta o elemento combinável do subespaço de volume, que permite posicionar entidades do SceneCore, como modelos 3D, em relação à sua interface. Saiba mais neste guia para desenvolvedores:

  • Subspace: esse elemento combinável pode ser colocado em qualquer lugar na hierarquia da interface do app, permitindo manter layouts para interfaces 2D e espaciais sem perder o contexto entre os arquivos. Isso facilita o compartilhamento de elementos como a arquitetura de apps entre XR e outros formatos sem precisar elevar o estado por toda a árvore da interface ou reestruturar o app.

  • SpatialPanel: um painel espacial é um elemento combinável de subespaço que permite mostrar conteúdo do app. Por exemplo, você pode exibir reprodução de vídeo, imagens estáticas ou qualquer outro conteúdo em um painel espacial.

  • Orbitador: um orbitador é um componente espacial de UI. Ele foi projetado para ser anexado a um painel espacial correspondente e contém itens de navegação e ação contextual relacionados a esse painel. Por exemplo, se você criou um painel espacial para mostrar conteúdo de vídeo, é possível adicionar controles de reprodução de vídeo dentro de um orbiter.

  • Volume: posicione entidades do SceneCore, como modelos 3D, em relação à sua interface.

• Layout espacial: é possível criar vários painéis espaciais e colocá-los em um layout espacial usando SpatialRow, SpatialColumn, SpatialBox e SpatialLayoutSpacer. Use SubspaceModifiers para personalizar seu layout.

• Componentes de UI espacial: esses elementos podem ser reutilizados na sua UI 2D, e os atributos espaciais só ficam visíveis quando os recursos espaciais estão ativados.

  • SpatialDialog: o painel vai recuar um pouco na profundidade Z para mostrar uma caixa de diálogo elevada.
  • SpatialPopUp: o painel vai recuar um pouco na profundidade Z para mostrar um pop-up elevado.
  • SpatialElevation: SpatialElevationLevel pode ser definido para adicionar elevação.

• SpatialCapabilities: as funcionalidades espaciais podem mudar à medida que os usuários interagem com o app ou o sistema, ou até mesmo ser alteradas pelo próprio app, por exemplo, ao passar para o Espaço Compacto ou o Espaço Ampliado. Para evitar problemas, seu app precisa verificar LocalSpatialCapabilities.current para determinar quais APIs são compatíveis no ambiente atual. isSpatialUiEnabled: elementos de interface espacial (por exemplo, SpatialPanel) isContent3dEnabled: objetos 3D isAppEnvironmentEnabled: o ambiente isPassthroughControlEnabled: se o aplicativo pode ou não controlar o estado de transmissão direta isSpatialAudioEnabled: áudio espacial

Problemas conhecidos

• No momento, é necessário um minSDK de 30 para usar o Jetpack Compose para XR. Como alternativa, adicione a seguinte entrada de manifesto <uses-sdk tools:overrideLibrary="androidx.xr.scenecore, androidx.xr.compose"/> para criar e executar com um minSDK de 23.
• No momento, os apps Jetpack XR exigem a solicitação da permissão android.permission.SCENE_UNDERSTANDING no AndroidManifest.
• Quando um app é iniciado diretamente no Modo de Espaço Ampliado usando a propriedade PROPERTY_XR_ACTIVITY_START_MODE no manifesto, as atividades/aplicativos são abertos inicialmente no Modo de Espaço Compacto antes de fazer a transição para o Modo de Espaço Ampliado.
• Os glTFs em elementos combináveis de volume podem piscar inicialmente no local errado.
• Usar um SpatialDialog em um painel que foi movido significativamente vai empurrar o conteúdo na direção errada.