Layout e grids
VSnapGrid
`VSnapGrid` é o canvas de construção com grade de encaixe para editores, builders e áreas de arrastar e soltar. Objetos (`v-model:objects`) são arrastados com atração magnética à grade e às bordas/centros dos vizinhos (com guias de alinhamento), redimensionados pelas 8 alças e movidos pelo teclado (setas: 1px; Shift + setas: um passo da grade).
<script setup lang="ts">
import { VSnapGrid } from 'vueui-nova-kit'
</script>Uso
Ligue v-model:objects (posições em px) e v-model:selected. Arrastar encaixa na grade e nas bordas/centros dos vizinhos, com guias tracejadas e um rótulo de posição; as 8 alças redimensionam com encaixe. Pelo teclado: Tab chega aos objetos, Enter seleciona, setas deslocam 1px e Shift + setas um passo da grade; cada mudança é anunciada num aria-live. Objetos com disabled ficam travados. O canvas rola por dentro quando os objetos passam da largura, sem estourar a página.
<script setup lang="ts">
import { ref } from 'vue'
import { VSnapGrid, type VSnapGridObject } from 'vueui-nova-kit'
const objects = ref<VSnapGridObject[]>([
{ id: 'hero', label: 'Hero', x: 24, y: 24, w: 216, h: 96 },
{ id: 'card', label: 'Card', x: 24, y: 144, w: 192, h: 120 },
])
const selected = ref<string | null>('card')
</script>
<template>
<VSnapGrid
v-model:objects="objects"
v-model:selected="selected"
variant="rulers"
size="medium"
:height="340"
aria-label="Canvas do editor" />
</template>Playground
Os controles abaixo são gerados a partir das props declaradas em VSnapGrid.types.ts; o código acompanha cada mudança.
Exemplos
Variantes, tamanhos e estados, extraídos das stories da biblioteca.
Default
Arraste os blocos: eles encaixam na grade de 24px e se alinham aos vizinhos (guias tracejadas). Clique para selecionar e use as alças para redimensionar; o bloco "Texto" está travado.
Ver código
<script setup lang="ts">
import { ref } from 'vue'
import { VSnapGrid } from 'vueui-nova-kit'
const args = {
variant: 'visible',
size: 'medium',
snap: true,
snapToObjects: true,
showGuides: true,
showRulers: false,
height: 320,
disabled: false
}
const objects = ref([
{
id: 'hero-section',
label: 'Hero',
x: 24,
y: 24,
w: 216,
h: 96
},
{
id: 'image',
label: 'Imagem',
x: 264,
y: 24,
w: 144,
h: 96
},
{
id: 'card',
label: 'Card do produto',
x: 24,
y: 144,
w: 192,
h: 120
},
{
id: 'button',
label: 'Botão',
x: 240,
y: 168,
w: 120,
h: 48
},
{
id: 'text',
label: 'Texto (travado)',
x: 384,
y: 168,
w: 120,
h: 48,
disabled: true
}
])
const selected = ref('card')
</script>
<template>
<VSnapGrid v-bind="args" v-model:objects="objects" v-model:selected="selected" aria-label="Canvas do editor" />
</template>In Context
Editor completo: painel de camadas (selecionar pelo nome), canvas com réguas e painel de grade com densidade e interruptores (grade, réguas, guias, encaixe magnético e encaixe em objetos).
Ver código
<script setup lang="ts">
import { ref } from 'vue'
import { VSnapGrid, VSegmentedControl, VSwitch } from 'vueui-nova-kit'
const objects = ref([
{
id: 'hero-section',
label: 'Hero',
x: 24,
y: 24,
w: 216,
h: 96
},
{
id: 'image',
label: 'Imagem',
x: 264,
y: 24,
w: 144,
h: 96
},
{
id: 'card',
label: 'Card do produto',
x: 24,
y: 144,
w: 192,
h: 120
},
{
id: 'button',
label: 'Botão',
x: 240,
y: 168,
w: 120,
h: 48
},
{
id: 'text',
label: 'Texto (travado)',
x: 384,
y: 168,
w: 120,
h: 48,
disabled: true
}
])
const selected = ref('card')
const size = ref('medium')
const showGrid = ref(true)
const rulers = ref(true)
const guides = ref(true)
const magnetic = ref(true)
const toObjects = ref(true)
</script>
<template>
<div style="display:grid;grid-template-columns:repeat(auto-fit,minmax(min(100%,200px),1fr));gap:12px;align-items:start">
<nav aria-label="Camadas" data-test-id="v-snap-grid-layers" style="border:1px solid var(--v-color-border);border-radius:12px;padding:8px;display:flex;flex-direction:column;gap:2px">
<strong style="font-size:13px;padding:4px 8px">Camadas</strong>
<button v-for="o in objects" :key="o.id" type="button" :aria-pressed="String(selected === o.id)" @click="selected = o.id"
:style="'text-align:left;border:0;border-radius:8px;padding:6px 8px;font:inherit;font-size:13px;cursor:pointer;color:var(--v-color-text);background:' + (selected === o.id ? 'color-mix(in srgb, var(--v-color-primary) 16%, transparent)' : 'transparent')">{{ o.label }}</button>
</nav>
<div style="grid-column:span 2;min-width:0">
<VSnapGrid variant="rulers" :show-rulers="rulers" :hide-grid="!showGrid" :size="size" :snap="magnetic" :snap-to-objects="toObjects" :show-guides="guides" v-model:objects="objects" v-model:selected="selected" :height="340" aria-label="Canvas do editor" />
</div>
<section aria-label="Grade" style="border:1px solid var(--v-color-border);border-radius:12px;padding:12px;display:flex;flex-direction:column;gap:10px;font-size:13px">
<strong>Grade</strong>
<VSegmentedControl v-model="size" aria-label="Densidade" :options="[{ value: 'fine', label: '8px' }, { value: 'medium', label: '24px' }, { value: 'coarse', label: '48px' }]" />
<VSwitch v-model="showGrid" label="Mostrar grade" data-test-id="v-snap-grid-panel-grid-toggle" />
<VSwitch v-model="rulers" label="Réguas" data-test-id="v-snap-grid-panel-show-rulers" />
<VSwitch v-model="guides" label="Guias" data-test-id="v-snap-grid-panel-show-guides" />
<VSwitch v-model="magnetic" label="Encaixe magnético" data-test-id="v-snap-grid-panel-magnetic-snapping" />
<VSwitch v-model="toObjects" label="Encaixar em objetos" data-test-id="v-snap-grid-panel-snap-objects" />
</section>
</div>
</template>Variants
visible (pontos e linhas), subtle (linhas quase invisíveis), magnetic (só pontos de encaixe) e rulers (grade com réguas numeradas).
Ver código
<script setup lang="ts">
import { VSnapGrid } from 'vueui-nova-kit'
</script>
<template>
<VSnapGrid />
</template>Sizes
Densidade da grade: fine (8px), medium (24px, padrão) e coarse (48px). O passo também define o salto de Shift + setas.
Ver código
<script setup lang="ts">
import { VSnapGrid } from 'vueui-nova-kit'
</script>
<template>
<VSnapGrid />
</template>States
Estados dos objetos: padrão, hover (contorno), selecionado (contorno sólido e 8 alças), encaixando (contorno tracejado e guias durante o arrasto) e desativado (tracejado e dessaturado, sem arrastar nem selecionar).
Ver código
<script setup lang="ts">
import { ref } from 'vue'
import { VSnapGrid } from 'vueui-nova-kit'
const objects = ref([
{
id: 'default',
label: 'Padrão',
x: 24,
y: 48,
w: 96,
h: 72
},
{
id: 'hover',
label: 'Hover',
x: 144,
y: 48,
w: 96,
h: 72
},
{
id: 'selected',
label: 'Selecionado',
x: 264,
y: 48,
w: 120,
h: 72
},
{
id: 'disabled',
label: 'Desativado',
x: 408,
y: 48,
w: 120,
h: 72,
disabled: true
}
])
const selected = ref('selected')
</script>
<template>
<VSnapGrid data-test-id="docs-snap-grid-states" v-model:objects="objects" v-model:selected="selected" :height="180" aria-label="Estados" />
</template>Rulers
Variante rulers: réguas sincronizadas com a rolagem do canvas.
Ver código
<script setup lang="ts">
import { VSnapGrid } from 'vueui-nova-kit'
const objects = [
{
id: 'hero-section',
label: 'Hero',
x: 24,
y: 24,
w: 216,
h: 96,
},
{
id: 'image',
label: 'Imagem',
x: 264,
y: 24,
w: 144,
h: 96,
},
{
id: 'card',
label: 'Card do produto',
x: 24,
y: 144,
w: 192,
h: 120,
},
{
id: 'button',
label: 'Botão',
x: 240,
y: 168,
w: 120,
h: 48,
},
{
id: 'text',
label: 'Texto (travado)',
x: 384,
y: 168,
w: 120,
h: 48,
disabled: true,
},
]
</script>
<template>
<VSnapGrid variant="rulers" :objects="objects" />
</template>Disabled
disabled trava o canvas inteiro.
Ver código
<script setup lang="ts">
import { VSnapGrid } from 'vueui-nova-kit'
const objects = [
{
id: 'hero-section',
label: 'Hero',
x: 24,
y: 24,
w: 216,
h: 96,
},
{
id: 'image',
label: 'Imagem',
x: 264,
y: 24,
w: 144,
h: 96,
},
{
id: 'card',
label: 'Card do produto',
x: 24,
y: 144,
w: 192,
h: 120,
},
{
id: 'button',
label: 'Botão',
x: 240,
y: 168,
w: 120,
h: 48,
},
{
id: 'text',
label: 'Texto (travado)',
x: 384,
y: 168,
w: 120,
h: 48,
disabled: true,
},
]
</script>
<template>
<VSnapGrid disabled :objects="objects" />
</template>Acessibilidade
- Keyboard accessible (arrow key nudge) — mover objectos com setas; canvas focável.
- Visible focus indicators — foco visível em objectos, handles e controlos do painel Grid.
- ARIA labels for canvas region —
role="application"/region+aria-labeldo canvas e das réguas. - Screen reader friendly descriptions — descrições textuais da posição ("x: 400 y: 120") e do snapping.
- Sufficient color contrast for grid and guides — grelha
#E5E7EB/guias#06B6D4/selecção#3B82F6com contraste suficiente. - Does not rely on color alone — snapping/selecção também com forma (tracejado, handles, mira), não só cor.
- Works with zoom up to 200% — utilizável com zoom até 200%.
- (Implícito do painel) Controlos nativos:
toggle,select(Size/Style) echeckbox(rulers/guides/snapping) com labels.
Props
| Prop | Tipo | Default | Descrição |
|---|---|---|---|
objects | VSnapGridObject[] | — | Objetos posicionados no canvas (`v-model:objects`), em px. |
variant | VSnapGridVariant | "visible" | Estilo da grade: `visible`, `subtle`, `magnetic` (só pontos de encaixe) ou `rulers` (grade com réguas). |
size | VSnapGridSize | "medium" | Densidade: `fine` 8px, `medium` 24px, `coarse` 48px. |
gridSize | number | — | Passo da grade em px. Sobrepõe `size`. |
snap | boolean | true | Encaixe magnético na grade. |
snapToObjects | boolean | true | Encaixe nas bordas e centros de outros objetos. |
showGuides | boolean | true | Mostra as guias de alinhamento durante o arrasto. |
showRulers | boolean | false | Mostra as réguas (sempre ligadas em `variant="rulers"`). |
hideGrid | boolean | false | Esconde a grade (o encaixe continua valendo). |
threshold | number | 6 | Distância de atração das guias (px). |
height | number | 320 | Altura do canvas (px). |
selected | string | null | null | ID do objeto selecionado (`v-model:selected`). |
disabled | boolean | false | Desativa toda a interação. |
ariaLabel | string | "Canvas com grade de encaixe" | Nome acessível do canvas. |
Events
| Evento | Payload | Descrição |
|---|---|---|
@update:objects | objects: VSnapGridObject[] | — |
@update:selected | id: string | null | — |
@move | payload: { id: string; x: number; y: number } | Objeto movido (arrasto ou setas). |
@resize | payload: { id: string; w: number; h: number } | Objeto redimensionado pelas alças. |
Slots
| Slot | Props do slot |
|---|---|
#object | objectselected |
Fonte: src/components/grid/VSnapGrid/VSnapGrid.vue · tipos: src/components/grid/VSnapGrid/VSnapGrid.types.ts