Layout e grids

VSnapGrid

Componente7 exemplos14 props

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

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

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

  1. Keyboard accessible (arrow key nudge) — mover objectos com setas; canvas focável.
  2. Visible focus indicators — foco visível em objectos, handles e controlos do painel Grid.
  3. ARIA labels for canvas region — role="application"/region + aria-label do canvas e das réguas.
  4. Screen reader friendly descriptions — descrições textuais da posição ("x: 400 y: 120") e do snapping.
  5. Sufficient color contrast for grid and guides — grelha #E5E7EB/guias #06B6D4/selecção #3B82F6 com contraste suficiente.
  6. Does not rely on color alone — snapping/selecção também com forma (tracejado, handles, mira), não só cor.
  7. Works with zoom up to 200% — utilizável com zoom até 200%.
  8. (Implícito do painel) Controlos nativos: toggle, select (Size/Style) e checkbox (rulers/guides/snapping) com labels.

Props

PropTipoDefaultDescrição
objectsVSnapGridObject[]
VSnapObject[]
—Objetos posicionados no canvas (`v-model:objects`), em px.
variantVSnapGridVariant"visible"Estilo da grade: `visible`, `subtle`, `magnetic` (só pontos de encaixe) ou `rulers` (grade com réguas).
sizeVSnapGridSize"medium"Densidade: `fine` 8px, `medium` 24px, `coarse` 48px.
gridSizenumber—Passo da grade em px. Sobrepõe `size`.
snapbooleantrueEncaixe magnético na grade.
snapToObjectsbooleantrueEncaixe nas bordas e centros de outros objetos.
showGuidesbooleantrueMostra as guias de alinhamento durante o arrasto.
showRulersbooleanfalseMostra as réguas (sempre ligadas em `variant="rulers"`).
hideGridbooleanfalseEsconde a grade (o encaixe continua valendo).
thresholdnumber6Distância de atração das guias (px).
heightnumber320Altura do canvas (px).
selectedstring | nullnullID do objeto selecionado (`v-model:selected`).
disabledbooleanfalseDesativa toda a interação.
ariaLabelstring"Canvas com grade de encaixe"Nome acessível do canvas.

Events

EventoPayloadDescrição
@update:objectsobjects: VSnapGridObject[]—
@update:selectedid: string | null—
@movepayload: { id: string; x: number; y: number }Objeto movido (arrasto ou setas).
@resizepayload: { id: string; w: number; h: number }Objeto redimensionado pelas alças.

Slots

SlotProps do slot
#objectobjectselected

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