Entender os modificadores de subespaço

Dispositivos XR relevantes
Estas orientações ajudam você a criar experiências para esses tipos de dispositivos XR.
Saiba mais sobre tipos de dispositivos XR →
Headsets XR
Óculos XR com fio
Saiba mais sobre tipos de dispositivos XR →

Um SubspaceModifier é semelhante a um modificador do Compose para elementos combináveis em um Subspace. Um SubspaceModifier permite manipular elementos combináveis no espaço 3D, ajudando a posicionar, girar e adicionar comportamentos a nós de layout 3D.

Layout

Por padrão, um Subspace é limitado pelo espaço recomendado para visualizar um app. Esses limites são usados ao medir o layout dos componentes do subespaço, semelhante aos limites em layouts do Compose 2D.

Preencher limites

Os modificadores fillMaxSize, fillMaxWidth, fillMaxHeight e fillMaxDepth fazem com que o conteúdo preencha (parcialmente) os limites do pai. O uso de modificadores de preenchimento ajuda o layout do app a conteúdo independente das características de exibição do dispositivo XR.

Definir o tamanho e o tamanho necessário

Os modificadores size, width, height, e depth declaram o tamanho preferencial do conteúdo. Para declarar o tamanho exato do conteúdo, use requiredSize, requiredWidth, requiredHeight e requiredDepth. Essas unidades precisam ser especificadas em dp. Para converter de metros para dp, use Meter.toDp().

Posicionar elementos combináveis

offset

O modificador offset move o elemento combinável no espaço 3D ao longo dos eixos x, y, e z. Essas unidades precisam ser especificadas em dp. Para converter de metros para dp, use Meter.toDp().

rotate

O rotate modificador gira o elemento combinável fornecido no espaço. É possível especificar a direção e a quantidade de rotação de maneiras diferentes:

  • Usando inclinação, guinada e rolagem, que especificam a rotação em torno dos eixos x, y e z, respectivamente,
  • Usando um axisAngle, que é um Vector3 que representa o eixo de rotação e a quantidade de graus que ele precisa ser girado,
  • Usando um Quaternion que representa a rotação.

rotateToLookAtUser

O modificador rotateToLookAtUser gira continuamente o conteúdo para que ele fique de frente para o usuário o tempo todo. Também é possível usar esse modificador para conseguir um efeito de "outdoor" em que o conteúdo gira para ficar de frente para o usuário no eixo Y, mas ainda permanece na vertical e alinhado com a gravidade. Para fazer isso, combine o modificador rotateToLookAtUser com o modificador gravityAligned.

Mover e redimensionar com elementos combináveis

Permita que os usuários manipulem diretamente a posição e o tamanho dos objetos no espaço 3D. É possível adicionar esses modificadores a componentes individuais (como SpatialPanel), subespaços e componentes de layout espacial (como SpatialRow ou SpatialColumn).

Mover elementos

Quando o modificador movable está presente e ativado, controles de IU arrastáveis são mostrados, permitindo que o usuário mova o elemento no espaço 3D. O comportamento específico desse movimento é definido pela movePolicy fornecida:

  • MovePolicy.default: o sistema processa o movimento de forma completa e calcula e aplica automaticamente a nova pose e escala com base na entrada do usuário.
  • MovePolicy.custom: o sistema calcula a pose de destino com base na entrada, mas não a aplica automaticamente ao elemento associado. Isso é útil para restringir o movimento ou criar um movimento personalizado no app.

Redimensionar elementos

Quando o modificador resizable() está presente e ativado, controles de IU são mostrados, permitindo que o usuário redimensione o elemento no espaço 3D. O comportamento específico do redimensionamento é definido pela resizePolicy fornecida:

  • ResizePolicy.default(): o sistema processa automaticamente o gesto de redimensionamento e aplica as novas dimensões ao conteúdo.
  • ResizePolicy.custom(): o sistema fornece um SpatialResizeEvent e não aplica automaticamente o resultado do redimensionamento ao elemento associado.

Mudar a aparência de elementos combináveis

alpha

O modificador alpha define a opacidade do elemento e dos filhos dele, em que 0f representa totalmente transparente e 1.0f representa completamente opaco.

scale

O modificador scale dimensiona o conteúdo do elemento combinável ao longo dos eixos horizontal, vertical e de profundidade.

Testes e acessibilidade

semantics

O modificador semantics adiciona semântica ao nó de layout para uso em testes e acessibilidade. Consulte Semântica no Jetpack Compose e SemanticsModifier.

testTag

O modificador testTag é uma abreviação de SemanticsPropertyReceiver.testTag, que permite que frameworks de teste encontrem o elemento em testes.