Layout e grids

VCanvasGrid

Componente7 exemplos16 props

`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.

Importação
<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.

Exemplo
<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
vue
<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
vue
<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
vue
<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
vue
<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
vue
<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
vue
<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
vue
<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

PropTipoDefaultDescrição
objectsVCanvasGridObject[]
VSnapObject[]
—Objetos do canvas (`v-model:objects`), em coordenadas do mundo (px com zoom 100%).
variantVCanvasGridVariant"lines"Estilo da grade: `lines`, `dots`, `dense` (linhas menores + maiores) ou `presentation` (espaçamento amplo).
sizeVCanvasGridSize"default"Densidade: `compact` 8px, `default` 16px, `wide` 32px.
gridSizenumber—Passo da grade em px. Sobrepõe `size`.
snapbooleantrueEncaixe na grade e nos objetos ao arrastar.
showControlsbooleantrueMostra os controles de zoom, mão (pan) e tela cheia.
showMinimapbooleantrueMostra o minimapa de navegação.
showToolbarbooleantrueMostra a barra flutuante de ações do objeto selecionado.
zoomnumber—Zoom (`v-model:zoom`). 1 = 100%.
minZoomnumber0.25—
maxZoomnumber4—
panVCanvasGridPan—Deslocamento da vista em px de tela (`v-model:pan`).
selectedstring | nullnullID do objeto selecionado (`v-model:selected`).
heightnumber360Altura do canvas (px).
disabledbooleanfalseDesativa pan, zoom e edição.
ariaLabelstring—Nome acessível do canvas.

Events

EventoPayloadDescrição
@update:objectsobjects: VCanvasGridObject[]—
@update:selectedid: string | null—
@update:zoomzoom: number—
@update:panpan: VCanvasGridPan—
@commentpayload: { id: string }Botão de comentário da barra do objeto.
@changepayload: { object: VCanvasGridObject; kind: 'move' | 'resize' | 'nudge' | 'duplicate' | 'delete' }Objeto movido ou redimensionado.

Slots

SlotProps do slot
#objectobjectselected

Fonte: src/components/grid/VCanvasGrid/VCanvasGrid.vue · tipos: src/components/grid/VCanvasGrid/VCanvasGrid.types.ts