Layout e grids
VCanvasGrid
`VCanvasGrid` é o workspace infinito com grade de encaixe para editores e construtores visuais. Pan (modo mão, Espaço + arrastar, botão do meio ou setas com o canvas focado), zoom (Ctrl + roda, Ctrl +/−/0 ou os botões; `v-model:zoom`), objetos (`v-model:objects`) com seleção, 8 alças, encaixe na grade e nos vizinhos com guias, barra flutuante (comentar, duplicar, excluir) e minimapa clicável.
<script setup lang="ts">
import { VCanvasGrid } from 'vueui-nova-kit'
</script>Uso
Dê ao canvas uma altura (height) e ligue v-model:objects e v-model:selected. Com o canvas focado, as setas movem a vista e Ctrl +/−/0 controlam o zoom; Ctrl + roda (ou pinça) dá zoom no cursor, e a roda sem modificador continua rolando a página. Espaço + arrastar, o botão do meio ou o modo mão movem a vista. Com um objeto focado, setas deslocam 1px (Shift: um passo da grade), Enter seleciona, Delete exclui e Esc devolve o foco ao canvas. O slot object desenha o conteúdo de cada bloco.
<script setup lang="ts">
import { ref } from 'vue'
import { VCanvasGrid, type VCanvasGridObject } from 'vueui-nova-kit'
const objects = ref<VCanvasGridObject[]>([
{ id: 'header', label: 'Cabeçalho', x: 48, y: 32, w: 320, h: 64 },
{ id: 'card', label: 'Card', x: 48, y: 128, w: 160, h: 144 },
])
const selected = ref<string | null>(null)
const zoom = ref(1)
</script>
<template>
<VCanvasGrid
v-model:objects="objects"
v-model:selected="selected"
v-model:zoom="zoom"
variant="dots"
:height="420"
aria-label="Quadro do editor"
@comment="({ id }) => abrirComentarios(id)" />
</template>Playground
Os controles abaixo são gerados a partir das props declaradas em VCanvasGrid.types.ts; o código acompanha cada mudança.
Exemplos
Variantes, tamanhos e estados, extraídos das stories da biblioteca.
Default
Canvas com quatro blocos. Arraste para mover (encaixa a cada 16px), selecione para ver as alças e a barra de ações, use os controles de zoom e o minimapa. Com o canvas focado, as setas movem a vista; com um bloco focado, as setas o deslocam 1px (Shift: um passo da grade) e Delete o exclui.
Ver código
<script setup lang="ts">
import { ref } from 'vue'
import { VCanvasGrid } from 'vueui-nova-kit'
const args = {
variant: 'lines',
size: 'default',
snap: true,
showControls: true,
showMinimap: true,
showToolbar: true,
height: 380,
disabled: false
}
const objects = ref([
{
id: 'header',
label: 'Cabeçalho',
x: 48,
y: 32,
w: 320,
h: 64
},
{
id: 'hero',
label: 'Hero',
x: 48,
y: 128,
w: 208,
h: 144
},
{
id: 'card',
label: 'Card',
x: 288,
y: 128,
w: 160,
h: 144
},
{
id: 'footer',
label: 'Rodapé (travado)',
x: 48,
y: 304,
w: 400,
h: 48,
disabled: true
}
])
const selected = ref('card')
const zoom = ref(1)
const pan = ref({
x: 0,
y: 0
})
</script>
<template>
<VCanvasGrid v-bind="args" v-model:objects="objects" v-model:selected="selected" v-model:zoom="zoom" v-model:pan="pan" aria-label="Quadro do editor" />
</template>In Context
Construtor de páginas: o slot object desenha cada bloco com conteúdo próprio, e um painel externo mostra zoom, posição da vista e o objeto selecionado (tudo via v-model). Comentários disparam o evento comment.
Ver código
<script setup lang="ts">
import { ref } from 'vue'
import { VCanvasGrid } from 'vueui-nova-kit'
const objects = ref([
{
id: 'header',
label: 'Cabeçalho',
x: 48,
y: 32,
w: 320,
h: 64
},
{
id: 'hero',
label: 'Hero',
x: 48,
y: 128,
w: 208,
h: 144
},
{
id: 'card',
label: 'Card',
x: 288,
y: 128,
w: 160,
h: 144
},
{
id: 'footer',
label: 'Rodapé (travado)',
x: 48,
y: 304,
w: 400,
h: 48,
disabled: true
}
])
const selected = ref('hero')
const zoom = ref(1)
const pan = ref({
x: 16,
y: 8
})
const comments = ref([])
</script>
<template>
<div style="display:flex;flex-direction:column;gap:10px">
<VCanvasGrid variant="dots" v-model:objects="objects" v-model:selected="selected" v-model:zoom="zoom" v-model:pan="pan" :height="420" aria-label="Construtor de páginas" @comment="comments.push($event.id)">
<template #object="{ object, selected: isSel }">
<div style="display:flex;flex-direction:column;gap:6px;width:100%;height:100%;pointer-events:none">
<strong style="font-size:12px">{{ object.label }}</strong>
<span v-for="n in Math.max(1, Math.floor(object.h / 40))" :key="n" :style="'height:6px;border-radius:3px;background:var(--v-color-surface-muted);width:' + (90 - n * 12) + '%'" />
<span v-if="isSel" style="margin-top:auto;font-size:11px;color:var(--v-color-primary-text)">{{ object.w }} × {{ object.h }}</span>
</div>
</template>
</VCanvasGrid>
<p style="margin:0;font-size:13px;color:var(--v-color-text-muted)">Zoom {{ Math.round(zoom * 100) }}% · vista ({{ pan.x }}, {{ pan.y }}) · selecionado: {{ selected ?? 'nenhum' }} · comentários: {{ comments.length }}</p>
</div>
</template>Variants
lines (linhas sólidas), dots (pontos discretos), dense (linhas menores + maiores a cada 4 passos, para precisão) e presentation (espaçamento amplo para visão geral).
Ver código
<script setup lang="ts">
import { VCanvasGrid } from 'vueui-nova-kit'
</script>
<template>
<VCanvasGrid :height="380" />
</template>Sizes
Densidade: compact (8px), default (16px, padrão) e wide (32px). O passo define o encaixe e o salto de Shift + setas.
Ver código
<script setup lang="ts">
import { VCanvasGrid } from 'vueui-nova-kit'
</script>
<template>
<VCanvasGrid :height="380" />
</template>States
Estados: ocioso, hover (contorno tracejado), selecionando (caixa com alças), encaixando (guias durante o arrasto), foco (anel de foco no objeto ou no canvas) e desativado (disabled: sem pan, zoom nem edição).
Ver código
<script setup lang="ts">
import { ref } from 'vue'
import { VCanvasGrid } from 'vueui-nova-kit'
const objects = ref([
{
id: 'a',
label: 'A',
x: 32,
y: 32,
w: 96,
h: 64
},
{
id: 'b',
label: 'B',
x: 160,
y: 64,
w: 80,
h: 80
}
])
const selected = ref('b')
const off = ref([
{
id: 'a',
label: 'A',
x: 32,
y: 32,
w: 96,
h: 64
},
{
id: 'b',
label: 'B',
x: 160,
y: 64,
w: 80,
h: 80
}
])
</script>
<template>
<div style="display:grid;grid-template-columns:repeat(auto-fit,minmax(min(100%,280px),1fr));gap:16px">
<div data-test-id="docs-canvasgrid-state-selecting"><p style="margin:0 0 6px;font-size:12px;color:var(--v-color-text-muted)">selecionando</p>
<VCanvasGrid :height="220" :show-minimap="false" v-model:objects="objects" v-model:selected="selected" aria-label="Selecionando" /></div>
<div data-test-id="docs-canvasgrid-state-disabled"><p style="margin:0 0 6px;font-size:12px;color:var(--v-color-text-muted)">desativado</p>
<VCanvasGrid :height="220" :show-minimap="false" :objects="off" disabled aria-label="Desativado" /></div>
</div>
</template>Zoomed
Zoom inicial de 150% (zoom).
Ver código
<script setup lang="ts">
import { VCanvasGrid } from 'vueui-nova-kit'
const objects = [
{
id: 'header',
label: 'Cabeçalho',
x: 48,
y: 32,
w: 320,
h: 64,
},
{
id: 'hero',
label: 'Hero',
x: 48,
y: 128,
w: 208,
h: 144,
},
{
id: 'card',
label: 'Card',
x: 288,
y: 128,
w: 160,
h: 144,
},
{
id: 'footer',
label: 'Rodapé (travado)',
x: 48,
y: 304,
w: 400,
h: 48,
disabled: true,
},
]
</script>
<template>
<VCanvasGrid :height="380" :zoom="1.5" :objects="objects" />
</template>Without Controls
Sem controles nem minimapa: zoom e pan só pelo teclado, roda e gestos.
Ver código
<script setup lang="ts">
import { VCanvasGrid } from 'vueui-nova-kit'
const objects = [
{
id: 'header',
label: 'Cabeçalho',
x: 48,
y: 32,
w: 320,
h: 64,
},
{
id: 'hero',
label: 'Hero',
x: 48,
y: 128,
w: 208,
h: 144,
},
{
id: 'card',
label: 'Card',
x: 288,
y: 128,
w: 160,
h: 144,
},
{
id: 'footer',
label: 'Rodapé (travado)',
x: 48,
y: 304,
w: 400,
h: 48,
disabled: true,
},
]
</script>
<template>
<VCanvasGrid
:show-controls="false"
:show-minimap="false"
:height="380"
:objects="objects" />
</template>Acessibilidade
Checklist literal ("Accessibility — Built with accessibility in mind"):
- Keyboard panning (arrow keys).
- Keyboard zoom (Ctrl + / Ctrl −).
- Screen reader friendly labels.
- Sufficient color contrast.
- Supports reduced motion.
- Clear focus indicators.
- ARIA labels for controls.
- Works in both light and dark mode.
Props
| Prop | Tipo | Default | Descrição |
|---|---|---|---|
objects | VCanvasGridObject[] | — | Objetos do canvas (`v-model:objects`), em coordenadas do mundo (px com zoom 100%). |
variant | VCanvasGridVariant | "lines" | Estilo da grade: `lines`, `dots`, `dense` (linhas menores + maiores) ou `presentation` (espaçamento amplo). |
size | VCanvasGridSize | "default" | Densidade: `compact` 8px, `default` 16px, `wide` 32px. |
gridSize | number | — | Passo da grade em px. Sobrepõe `size`. |
snap | boolean | true | Encaixe na grade e nos objetos ao arrastar. |
showControls | boolean | true | Mostra os controles de zoom, mão (pan) e tela cheia. |
showMinimap | boolean | true | Mostra o minimapa de navegação. |
showToolbar | boolean | true | Mostra a barra flutuante de ações do objeto selecionado. |
zoom | number | — | Zoom (`v-model:zoom`). 1 = 100%. |
minZoom | number | 0.25 | — |
maxZoom | number | 4 | — |
pan | VCanvasGridPan | — | Deslocamento da vista em px de tela (`v-model:pan`). |
selected | string | null | null | ID do objeto selecionado (`v-model:selected`). |
height | number | 360 | Altura do canvas (px). |
disabled | boolean | false | Desativa pan, zoom e edição. |
ariaLabel | string | — | Nome acessível do canvas. |
Events
| Evento | Payload | Descrição |
|---|---|---|
@update:objects | objects: VCanvasGridObject[] | — |
@update:selected | id: string | null | — |
@update:zoom | zoom: number | — |
@update:pan | pan: VCanvasGridPan | — |
@comment | payload: { id: string } | Botão de comentário da barra do objeto. |
@change | payload: { object: VCanvasGridObject; kind: 'move' | 'resize' | 'nudge' | 'duplicate' | 'delete' } | Objeto movido ou redimensionado. |
Slots
| Slot | Props do slot |
|---|---|
#object | objectselected |
Fonte: src/components/grid/VCanvasGrid/VCanvasGrid.vue · tipos: src/components/grid/VCanvasGrid/VCanvasGrid.types.ts