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 esses dispositivos →
Headsets XR
Óculos XR com fio
Saiba mais sobre esses dispositivos →

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 você a posicionar, girar e adicionar comportamentos aos 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 2D do Compose.

Preencher limites

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

Definir o tamanho e o tamanho obrigató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 em 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 em dp, use Meter.toDp().

rotate

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

  • Usando inclinação, guinada e rotação, 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 o número de graus em 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 sempre voltado para o usuário. 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 permanece na vertical e alinhado com a gravidade. Para fazer isso, combine o modificador rotateToLookAtUser com o modificador gravityAligned.

Mover e redimensionar elementos combináveis

Permita que os usuários manipulem diretamente a posição e o tamanho dos objetos no espaço 3D.

Mover elementos

Quando o modificador movable está presente e ativado, são mostrados controles de interface arrastáveis que permitem ao usuário mover o elemento no espaço 3D. É possível aplicar modificadores movable a um Subspace inteiro, a componentes de layout espacial (como SpatialRow e SpatialColumn) e a componentes individuais (como SpatialPanel e SpatialGltfModel).

O comportamento específico desse movimento é definido pelo movePolicy fornecido:

  • MovePolicy.Default (ou MovePolicy.system()): o sistema processa o movimento por completo e calcula e aplica automaticamente a nova pose e escala com base na entrada do usuário.
  • MovePolicy.custom(): o sistema calcula o Pose de destino com base na entrada, mas não o aplica automaticamente ao elemento associado. Isso é útil para restringir o movimento ou criar um movimento personalizado no app.
  • MovePolicy.anchor(): permite que o usuário ajuste e fixe o elemento móvel em planos reais detectados.

Elementos combináveis de âncora

Para fixar um subespaço combinável móvel em superfícies do mundo real, transmita MovePolicy.anchor() para o modificador movable. Essa política permite que os usuários fixem elementos (como SpatialPanel e SpatialGltfModel) em superfícies físicas, como mesas, paredes ou pisos.

É possível filtrar os planos detectados em que um elemento pode ser fixado usando os seguintes parâmetros (se deixados em branco, o elemento pode ser fixado em qualquer plano detectado):

  • anchorPlaneOrientations: um conjunto de valores PlaneOrientation (Horizontal, Vertical ou Any).
  • anchorPlaneSemantics: um conjunto de valores PlaneSemantic (Wall, Floor, Ceiling, Table ou Any).

Redimensionar elementos

Quando o modificador resizable() está presente e ativado, os controles de interface são mostrados para que o usuário possa redimensionar o elemento no espaço 3D. O comportamento específico do redimensionamento é definido pelo resizePolicy fornecido:

  • 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 que podem ser compostos

alpha

O modificador alpha define a opacidade do elemento e dos filhos dele, em que 0f representa totalmente transparente e 1.0f representa totalmente 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 os frameworks de teste encontrem o elemento nos testes.