--- title: "Canvas UI" version: snapshot-2026-10-06 engineGeneration: astra-current language: C# status: source-reviewed runtimeVerified: false platformEvidence: [] url: https://astraengine.com.br/pt-br/snapshot-2026-10-06/componentes/astra-ui-canvas/ --- # Canvas UI Instância independente de documento de UI, na tela ou no objeto **Família:** Renderização · **Grupo:** Interface · **Identificador:** `astra.ui.canvas` · **Payload:** 2 :::note[Escopo da evidência] Este contrato foi extraído dos descritores compilados da engine, incluindo padrões resolvidos. A presença do contrato não substitui a validação do comportamento em um aparelho. ::: ## Para que usar Instância independente de documento de UI, na tela ou no objeto Salve um documento .aeui, atribua Documento UI e escolha Tela para HUD ou Mundo para plano na cena. Elementos Image/Text/Button são criados dentro desse documento. ## Criar e configurar Hierarquia → selecione o objeto → Inspector → Adicionar componente → **Renderização** / **Interface** → **Canvas UI**. O schema permite múltiplas instâncias no mesmo objeto; identifique a instância antes de editar ou remover. A fachada C# correspondente é [Astra.Components.UiCanvas](/pt-br/snapshot-2026-10-06/api/astra-components-uicanvas/). O recurso Documento UI não entra na tabela numérica abaixo. Ele é escolhido por recurso registrado; em C#, use GetDocument/SetDocument. Image está dentro do .aeui, não neste componente. ## Exemplo de uso Siga o tutorial HUD de corações: três Images cheias sobre três vazias e HeartHud ligado a PlayerHealth. [HUD de corações completo](/pt-br/snapshot-2026-10-06/ui/hud-coracoes/) · [Image e seus campos](/pt-br/snapshot-2026-10-06/ui/image/) · [Onde fica a UI](/pt-br/snapshot-2026-10-06/ui/comece-aqui/) ## Dependências Nenhuma regra adicional declarada no schema deste componente. ## Conflitos Nenhuma regra adicional declarada no schema deste componente. ## Edição e ciclo de vida | Operação | Contrato | |---|---| | Adicionar/remover em Play | ponto seguro | | Alterar propriedades em Play | ponto seguro | | Múltiplas instâncias | Sim | | Versão do payload | 2 | Alterações em ponto seguro são aplicadas entre passos da simulação. Um componente exigido por outro não pode ser removido enquanto a dependência existir. Salvar a cena autoral e modificar o mundo de Play são operações distintas; veja [Play e cena autoral](/pt-br/snapshot-2026-10-06/conceitos/play-e-cena-autoral/). ## Propriedades Valores abaixo são resolvidos pelo descritor de um componente recém-criado. Campos por slot dependem dos recursos atribuídos. Um campo sem padrão significa que o descritor não fornece um valor independente de contexto. ### Apresentação | Propriedade | Tipo / unidade | Padrão | Domínio | |---|---|---|---| | [**Posição X**](#field-offset-x)
`offset_x` | número · m | 0 | -100000 … 100000 | | [**Posição Y**](#field-offset-y)
`offset_y` | número · m | 0 | -100000 … 100000 | | [**Posição Z**](#field-offset-z)
`offset_z` | número · m | 0 | -100000 … 100000 | | [**Rotação X**](#field-rotation-x)
`rotation_x` | número · ° | 0 | -36000 … 36000 | | [**Rotação Y**](#field-rotation-y)
`rotation_y` | número · ° | 0 | -36000 … 36000 | | [**Rotação Z**](#field-rotation-z)
`rotation_z` | número · ° | 0 | -36000 … 36000 |

Posição X · offset_x

**Onde:** Inspector → **Canvas UI** → **Apresentação** → **Posição X**. **Uso e efeito:** Aplica-se ao Canvas no mundo; Tela usa o viewport. **Valor:** 0 · **Tipo:** número · **Unidade:** m · **Domínio:** -100000 … 100000. Campo condicional: o modo/forma/recurso selecionado controla a disponibilidade.

Posição Y · offset_y

**Onde:** Inspector → **Canvas UI** → **Apresentação** → **Posição Y**. **Uso e efeito:** Aplica-se ao Canvas no mundo; Tela usa o viewport. **Valor:** 0 · **Tipo:** número · **Unidade:** m · **Domínio:** -100000 … 100000. Campo condicional: o modo/forma/recurso selecionado controla a disponibilidade.

Posição Z · offset_z

**Onde:** Inspector → **Canvas UI** → **Apresentação** → **Posição Z**. **Uso e efeito:** Aplica-se ao Canvas no mundo; Tela usa o viewport. **Valor:** 0 · **Tipo:** número · **Unidade:** m · **Domínio:** -100000 … 100000. Campo condicional: o modo/forma/recurso selecionado controla a disponibilidade.

Rotação X · rotation_x

**Onde:** Inspector → **Canvas UI** → **Apresentação** → **Rotação X**. **Uso e efeito:** Aplica-se ao Canvas no mundo; Tela usa o viewport. **Valor:** 0 · **Tipo:** número · **Unidade:** ° · **Domínio:** -36000 … 36000. Campo condicional: o modo/forma/recurso selecionado controla a disponibilidade.

Rotação Y · rotation_y

**Onde:** Inspector → **Canvas UI** → **Apresentação** → **Rotação Y**. **Uso e efeito:** Aplica-se ao Canvas no mundo; Tela usa o viewport. **Valor:** 0 · **Tipo:** número · **Unidade:** ° · **Domínio:** -36000 … 36000. Campo condicional: o modo/forma/recurso selecionado controla a disponibilidade.

Rotação Z · rotation_z

**Onde:** Inspector → **Canvas UI** → **Apresentação** → **Rotação Z**. **Uso e efeito:** Aplica-se ao Canvas no mundo; Tela usa o viewport. **Valor:** 0 · **Tipo:** número · **Unidade:** ° · **Domínio:** -36000 … 36000. Campo condicional: o modo/forma/recurso selecionado controla a disponibilidade. ### Canvas | Propriedade | Tipo / unidade | Padrão | Domínio | |---|---|---|---| | [**Largura**](#field-width)
`width` | número · px | 800 | 1 … 16384 | | [**Altura**](#field-height)
`height` | número · px | 600 | 1 … 16384 | | [**Unidades por pixel**](#field-units-per-pixel)
`units_per_pixel` | número · m/px | 0.005 | 0.00001 … 10 | | [**Ordem**](#field-order)
`order` | número | 0 | -10000 … 10000 | | [**Habilitado**](#field-enabled)
`enabled` | booleano | verdadeiro | verdadeiro \| falso | | [**Oclusão no mundo**](#field-occlusion)
`occlusion` | booleano | verdadeiro | verdadeiro \| falso | | [**Apresentação**](#field-mode)
`mode` | enumeração | Tela | Tela \| Mundo / objeto |

Largura · width

**Onde:** Inspector → **Canvas UI** → **Canvas** → **Largura**. **Uso e efeito:** Resolução local do plano no modo Mundo. No modo Tela, o retângulo é o viewport; não é resolução de referência para escala. **Valor:** 800 · **Tipo:** número · **Unidade:** px · **Domínio:** 1 … 16384. Campo condicional: o modo/forma/recurso selecionado controla a disponibilidade.

Altura · height

**Onde:** Inspector → **Canvas UI** → **Canvas** → **Altura**. **Uso e efeito:** Resolução local do plano no modo Mundo. No modo Tela, o retângulo é o viewport; não é resolução de referência para escala. **Valor:** 600 · **Tipo:** número · **Unidade:** px · **Domínio:** 1 … 16384. Campo condicional: o modo/forma/recurso selecionado controla a disponibilidade.

Unidades por pixel · units_per_pixel

**Onde:** Inspector → **Canvas UI** → **Canvas** → **Unidades por pixel**. **Uso e efeito:** Aplica-se ao Canvas no mundo; Tela usa o viewport. **Valor:** 0.005 · **Tipo:** número · **Unidade:** m/px · **Domínio:** 0.00001 … 10. Campo condicional: o modo/forma/recurso selecionado controla a disponibilidade.

Ordem · order

**Onde:** Inspector → **Canvas UI** → **Canvas** → **Ordem**. **Uso e efeito:** Ordena apresentação dos Canvas; compare sobreposição e entrada com o modo efetivo. **Valor:** 0 · **Tipo:** número · **Domínio:** -10000 … 10000.

Habilitado · enabled

**Onde:** Inspector → **Canvas UI** → **Canvas** → **Habilitado**. **Uso e efeito:** Ativa/desativa a participação do componente no sistema consumidor; não remove seus dados. **Valor:** verdadeiro · **Tipo:** booleano · **Domínio:** verdadeiro \| falso.

Oclusão no mundo · occlusion

**Onde:** Inspector → **Canvas UI** → **Canvas** → **Oclusão no mundo**. **Uso e efeito:** Depth e hit de Canvas no mundo. **Valor:** verdadeiro · **Tipo:** booleano · **Domínio:** verdadeiro \| falso. Campo condicional: o modo/forma/recurso selecionado controla a disponibilidade.

Apresentação · mode

**Onde:** Inspector → **Canvas UI** → **Canvas** → **Apresentação**. **Uso e efeito:** Seleciona o modo do componente no domínio indicado; revise os campos que aparecem após trocar. **Valor:** Tela · **Tipo:** enumeração · **Domínio:** Tela \| Mundo / objeto. ### Entrada | Propriedade | Tipo / unidade | Padrão | Domínio | |---|---|---|---| | [**Espaço do movimento**](#field-movement-space)
`movement_space` | enumeração | Mundo | Mundo \| Local do jogador \| Camera de entrada | | [**Jogador / receptor**](#field-input-receiver)
`input_receiver` | referência | Acoes globais | objeto compatível com o receptor | | [**Camera de entrada**](#field-input-camera)
`input_camera` | referência | Nenhuma | astra.camera |

Espaço do movimento · movement_space

**Onde:** Inspector → **Canvas UI** → **Entrada** → **Espaço do movimento**. **Uso e efeito:** Escolhe espaço do vetor de movimento: mundo, jogador ou câmera de entrada. **Valor:** Mundo · **Tipo:** enumeração · **Domínio:** Mundo \| Local do jogador \| Camera de entrada.

Jogador / receptor · input_receiver

**Onde:** Inspector → **Canvas UI** → **Entrada** → **Jogador / receptor**. **Uso e efeito:** Character ou motor de corpo dinâmico ativo. **Valor:** Acoes globais · **Tipo:** referência · **Domínio:** objeto compatível com o receptor.

Camera de entrada · input_camera

**Onde:** Inspector → **Canvas UI** → **Entrada** → **Camera de entrada**. **Uso e efeito:** Câmera usada para o espaço de movimento/olhar dos controles do Canvas. **Valor:** Nenhuma · **Tipo:** referência · **Domínio:** astra.camera. ## Roadmap deste componente [Canvas e UI de jogo](/pt-br/snapshot-2026-10-06/ui/roadmap/). R0–R12: imagem/skins, autoria, foco/input, controles, layout, texto, bindings, inventário, apresentações, animação, templates e acesso. Consulte estados e critérios por função na página dedicada. Os campos acima pertencem ao contrato existente; novas funções dependem do fechamento da família. Não há datas individuais prometidas para cada propriedade. ## Conferir na sua cena 1. Crie **Canvas UI** pelo fluxo indicado e resolva as dependências. 2. Altere uma propriedade por vez e observe o efeito esperado na cena. 3. Salve, reabra e confira os valores autorais. 4. Entre em Play e verifique o comportamento com os recursos reais do projeto. 5. Pare o Play e confira a cena autoral. Este é um roteiro de conferência; não representa um teste executado nesta publicação. ## Limitações da referência A tabela cobre os tipos de propriedade disponíveis no descritor de reflexão. Não presume persistência de campos transitórios, equivalência com outras engines ou suporte em todos os aparelhos. Recursos, coleções e operações podem exigir APIs específicas. **Referência de arquitetura registrada pela engine:** [documentação oficial](https://docs.unity3d.com/Packages/com.unity.ugui@2.0/manual/class-Canvas.html). Essa referência não representa paridade funcional.