Informazioni sui modificatori di sottospazio

Dispositivi XR applicabili
Queste indicazioni ti aiutano a creare esperienze per questi tipi di dispositivi XR.
Scopri di più sui tipi di dispositivi XR →
Visori XR
Occhiali XR con cavo
Scopri di più sui tipi di dispositivi XR →

Un SubspaceModifier è simile a un modificatore di Compose per i componibili in un Subspace. Un SubspaceModifier ti consente di manipolare i composabili nello spazio 3D, aiutandoti a posizionare, ruotare e aggiungere comportamenti ai nodi di layout 3D.

Layout

Per impostazione predefinita, un Subspace è delimitato dallo spazio consigliato per la visualizzazione di un'app. Questi limiti vengono utilizzati per misurare il layout dei componenti dello spazio secondario, in modo simile ai limiti nei layout di Compose 2D.

Riempi i limiti

I modificatori fillMaxSize, fillMaxWidth, fillMaxHeight e fillMaxDepth fanno sì che i contenuti riempiano (parzialmente) i limiti del relativo elemento principale. L'utilizzo dei modificatori di riempimento aiuta l'app a disporre i contenuti in modo indipendente dalle caratteristiche del display del dispositivo XR.

Imposta le dimensioni e le dimensioni richieste

I modificatori size, width, height e depth dichiarano le dimensioni preferite dei contenuti. Per dichiarare le dimensioni esatte dei contenuti, utilizza requiredSize, requiredWidth, requiredHeight e requiredDepth. Queste unità devono essere specificate in dp; per convertire i metri in dp, utilizza Meter.toDp().

Posiziona gli elementi componibili

offset

Il modificatore offset sposta il composable nello spazio 3D lungo gli assi x, y e z. Queste unità devono essere specificate in dp; per convertire i metri in dp, utilizza Meter.toDp().

rotate

Il modificatore rotate ruota l'elemento composable specificato nello spazio. Puoi specificare la direzione e la quantità di rotazione in diversi modi:

  • Utilizzando beccheggio, imbardata e rollio, che specificano la rotazione rispettivamente attorno agli assi x, y e z.
  • Utilizzando un axisAngle, ovvero un Vector3 che rappresenta l'asse di rotazione, e il numero di gradi di rotazione,
  • Utilizzando un Quaternion che rappresenta la rotazione.

rotateToLookAtUser

Il modificatore rotateToLookAtUser ruota continuamente i contenuti in modo che siano sempre rivolti verso l'utente. Puoi anche utilizzare questo modificatore per ottenere un effetto "billboard" in cui i contenuti ruotano per rivolgersi all'utente sull'asse Y, rimanendo comunque in posizione verticale e allineati con la gravità. Per farlo, combina il modificatore rotateToLookAtUser con il modificatore gravityAligned.

Sposta e ridimensiona i componibili

Consenti agli utenti di manipolare direttamente la posizione e le dimensioni degli oggetti nello spazio 3D.

Sposta gli elementi

Quando il modificatore movable è presente e attivato, vengono mostrati i controlli UI trascinabili che consentono all'utente di spostare l'elemento nello spazio 3D. Puoi applicare i modificatori movable a un intero Subspace, ai componenti di layout spaziale (come SpatialRow e SpatialColumn) e ai singoli componenti (come SpatialPanel e SpatialGltfModel).

Il comportamento specifico di questo movimento è definito dal movePolicy fornito:

  • MovePolicy.Default (o MovePolicy.system()): il sistema gestisce interamente il movimento e calcola e applica automaticamente la nuova posa e la nuova scala in base all'input dell'utente.
  • MovePolicy.custom(): il sistema calcola il Pose target in base all'input, ma non lo applica automaticamente all'elemento associato. Questa opzione è utile per limitare i movimenti o creare movimenti personalizzati nella tua app.
  • MovePolicy.anchor(): consente all'utente di agganciare e ancorare l'elemento mobile ai piani reali rilevati.

Ancorare gli elementi componibili

Per poter ancorare un composable di sottospazio mobile alle superfici del mondo reale, passa MovePolicy.anchor() al modificatore movable. Questa policy consente agli utenti di agganciare elementi (come SpatialPanel e SpatialGltfModel) a superfici fisiche come tavoli, pareti o pavimenti.

Puoi filtrare i piani rilevati a cui un elemento può agganciarsi utilizzando i seguenti parametri (se lasciati vuoti, l'elemento può essere ancorato a qualsiasi piano rilevato):

  • anchorPlaneOrientations: un insieme di valori PlaneOrientation (Horizontal, Vertical o Any).
  • anchorPlaneSemantics: un insieme di valori PlaneSemantic (Wall, Floor, Ceiling, Table o Any).

Ridimensiona gli elementi

Quando il modificatore resizable() è presente e attivato, vengono mostrati i controlli UI che consentono all'utente di ridimensionare l'elemento nello spazio 3D. Il comportamento specifico del ridimensionamento è definito dal valore resizePolicy fornito:

  • ResizePolicy.default(): il sistema gestisce automaticamente il gesto di ridimensionamento e applica le nuove dimensioni ai contenuti.
  • ResizePolicy.custom(): il sistema fornisce un SpatialResizeEvent e non applica automaticamente il risultato del ridimensionamento all'elemento associato.

Modifica l'aspetto dei componibili

alpha

Il modificatore alpha imposta l'opacità dell'elemento e dei relativi elementi secondari, dove 0f rappresenta la trasparenza completa e 1.0f l'opacità completa.

scale

Il modificatore scale scala i contenuti del composable lungo gli assi orizzontale, verticale e di profondità.

Test e accessibilità

semantics

Il modificatore semantics aggiunge la semantica al nodo del layout, per l'utilizzo nei test e nell'accessibilità. Consulta Semantica in Jetpack Compose e SemanticsModifier.

testTag

Il modificatore testTag è un'abbreviazione di SemanticsPropertyReceiver.testTag, che consente ai framework di test di trovare l'elemento nei test.