Начало работы
Hello World и комментарии
Приложение Vue 3 начинается с createApp() и mount() в DOM-элемент. Интерполяция использует двойные фигурные скобки {{ }} для рендеринга реактивных данных. HTML-комментарии попадают в отрендеренный DOM; для комментариев, которые не должны утекать, используйте /* */ внутри блоков <script>.
<!-- index.html -->
<div id="app">
<p>{{ message }}</p>
<!-- This is an HTML comment, visible in DOM -->
</div>
<script type="module">
import { createApp } from 'vue'
createApp({
data() {
return { message: 'Hello Vue 3!' }
}
}).mount('#app')
</script>Структура SFC (однофайловый компонент)
SFC объединяет шаблон, скрипт и стили в одном .vue-файле. <script setup> — рекомендуемый синтаксис для Composition API: лаконично и без шаблонного кода. scoped-стили применяются только к текущему компоненту, предотвращая утечки. Каждый SFC компилируется в JavaScript-модуль.
<template>
<button @click="count++">Count: {{ count }}</button>
</template>
<script setup>
import { ref } from 'vue'
const count = ref(0)
</script>
<style scoped>
button { color: #42B883; }
</style>Экземпляр приложения и mount
createApp возвращает экземпляр приложения, ограниченный собой, — глобального состояния Vue нет, поэтому на одной странице можно смонтировать несколько независимых приложений. Регистрируйте плагины, предоставляйте глобальные значения и настраивайте config до вызова mount(). После mount изменения конфигурации не подействуют.
import { createApp } from 'vue'
import App from './App.vue'
const app = createApp(App)
// global config / plugins before mounting
app.config.errorHandler = (err) => console.error(err)
app.provide('apiKey', '12345')
app.mount('#app')Скаффолдинг проекта (Vite)
npm create vue@latest — официальный инструмент скаффолдинга с опциями TypeScript, Router, Pinia и Vitest. Он использует Vite для мгновенного запуска dev-сервера и HMR. create-vite — более низкоуровневый инструмент, если нужен минимальный шаблон без мнений Vue.
# scaffold a new Vue project with Vite
npm create vue@latest my-app
cd my-app
npm install
npm run dev # start dev server (HMR)
npm run build # production build to /dist
# or with create-vite directly
npm create vite@latest my-app -- --template vue-tsdefineOptions и defineProps
defineProps, defineEmits и defineOptions — макросы времени компиляции, их не нужно импортировать. defineProps объявляет контракт пропсов компонента с валидацией в рантайме. defineOptions позволяет задать name, inheritAttrs и другие опции, которые нельзя напрямую выразить в <script setup>.
<script setup>
// declare props with types and defaults
const props = defineProps({
title: String,
count: { type: Number, default: 0 }
})
// declare emits
const emit = defineEmits(['update', 'delete'])
// additional non-reactive options
defineOptions({ name: 'MyButton', inheritAttrs: false })
</script>Синтаксис шаблонов
Интерполяция текста
{{ }} безопасно рендерит текст (с HTML-экранированием). v-once замораживает привязку после первого рендера для статического контента. v-html вставляет сырой HTML — используйте только для доверенного контента, чтобы избежать XSS. Внутри {{ }} можно использовать любое одиночное JavaScript-выражение, но не операторы вроде присваиваний или объявлений var.
<template>
<p>{{ message }}</p>
<!-- renders the value of message -->
<!-- one-time binding (no updates after render) -->
<span v-once>{{ initialCount }}</span>
<!-- raw HTML (sanitize to avoid XSS!) -->
<div v-html="rawHtmlContent"></div>
<!-- expressions are supported -->
<p>{{ count * 2 }}</p>
<p>{{ isReady ? 'Yes' : 'No' }}</p>
<p>{{ message.split('').reverse().join('') }}</p>
</template>Привязка атрибутов
v-bind (сокращение :) реактивно привязывает атрибуты. Для class можно передать объект (истинные ключи применяются), массив или строку. style принимает объект с ключами в camelCase или kebab-case. Синтаксис динамического аргумента :[expr] позволяет самому имени атрибута быть реактивным — полезно для имён событий и локализованных атрибутов.
<template>
<!-- bind an attribute -->
<img v-bind:src="imageUrl" />
<img :src="imageUrl" /> <!-- shorthand -->
<!-- bind class -->
<div :class="{ active: isActive, error: hasError }"></div>
<div :class="['btn', isActive && 'active']"></div>
<!-- bind style -->
<div :style="{ color: textColor, fontSize: size + 'px' }"></div>
<!-- dynamic attribute name -->
<button :[eventName]="handler">Click</button>
</template>Булевы и многозначные атрибуты
Для булевых атрибутов вроде disabled или checked Vue рендерит атрибут, только когда значение истинно. class и style особенные: Vue объединяет статические и привязанные значения, а не заменяет их. Для полей форм предпочитайте v-model ручной привязке :value и @input.
<template>
<!-- boolean attribute: presence depends on value -->
<input :disabled="isDisabled" />
<button :disabled="!canSubmit">Submit</button>
<!-- class merging: bound class merges with static class -->
<div class="card" :class="{ highlighted: isFeatured }"></div>
<!-- style merging: bound style merges with static style -->
<div style="color: red" :style="{ fontSize: '14px' }"></div>
<!-- form attributes: value is bound with v-model instead -->
<input v-model="text" />
</template>Модификаторы и выражения
Модификаторы — постфиксы через точку, задающие особую обработку. Модификаторы событий (.prevent, .stop, .once, .self) оборачивают обработчик соответствующим DOM-методом. Модификаторы клавиш (.enter, .esc, .ctrl) фильтруют события по клавише. Модификаторы v-model (.trim, .number, .lazy) преобразуют ввод до присваивания.
<template>
<!-- .prevent calls event.preventDefault() -->
<form @submit.prevent="onSubmit">...</form>
<!-- .stop calls event.stopPropagation() -->
<button @click.stop="doStuff">Click</button>
<!-- .once runs handler only one time -->
<button @click.once="init">Init</button>
<!-- .trim and .lazy modifiers on v-model -->
<input v-model.trim="email" />
<input v-model.lazy="text" />
<!-- chain multiple modifiers -->
<input @keyup.enter.ctrl="onCombo" />
</template>Template refs
Template refs дают прямой доступ к DOM-элементам. Объявите ref() с тем же именем, что и атрибут ref, — Vue присвоит DOM-узел после монтирования. Обращайтесь внутри onMounted (или позже); до монтирования ref равен null. Для v-for ref становится массивом элементов. Не тянитесь к refs, когда достаточно реактивного потока данных.
<script setup>
import { ref, onMounted } from 'vue'
// declare a ref matching the template ref attribute
const inputEl = ref(null)
onMounted(() => {
// access the DOM node after mount
inputEl.value.focus()
})
</script>
<template>
<input ref="inputEl" />
</template>Директивы
v-if / v-else-if / v-else
v-if условно рендерит элементы — они добавляются и удаляются из DOM. v-else-if и v-else связываются с предшествующим v-if. Оборачивайте несколько элементов в <template v-if>, когда не нужно лишнее обёрточное element. У v-if выше стоимость переключения (создание DOM), но ниже начальная стоимость, чем у v-show, когда условие ложно.
<template>
<div v-if="type === 'A'">Type A</div>
<div v-else-if="type === 'B'">Type B</div>
<div v-else-if="type === 'C'">Type C</div>
<div v-else>Unknown type</div>
<!-- use <template> for invisible wrapper -->
<template v-if="showHeader">
<h1>Title</h1>
<p>Subtitle</p>
</template>
</template>v-show против v-if
Используйте v-if, когда условие меняется редко: элементы уничтожаются и создаются заново, экономя стоимость рендера, когда скрыты. Используйте v-show для часто переключаемых элементов (вкладки, выпадающие списки): элемент остаётся в DOM, переключается только display:none, поэтому переключение дешёвое. v-show не работает с <template> и v-else.
<template>
<!-- v-if removes from DOM when false -->
<p v-if="isVisible">I'm created/destroyed</p>
<!-- v-show just toggles display:none -->
<p v-show="isVisible">I'm always in DOM, just hidden</p>
</template>
<script setup>
import { ref } from 'vue'
const isVisible = ref(true)
</script>v-for и :key
v-for перебирает массивы, объекты или диапазон чисел. Атрибут :key ОБЯЗАТЕЛЕН для идентификации при переупорядочивании — он позволяет Vue эффективно переиспользовать DOM-узлы. Используйте стабильный уникальный id как key; никогда не берите индекс массива (ломается при перемещении элементов). v-for имеет более высокий приоритет, чем v-if на том же элементе, — не используйте оба сразу.
<template>
<!-- iterate over array -->
<li v-for="item in items" :key="item.id">
{{ item.name }}
</li>
<!-- iterate with index -->
<li v-for="(item, index) in items" :key="item.id">
{{ index }}: {{ item.name }}
</li>
<!-- iterate over object -->
<li v-for="(value, key) in user" :key="key">
{{ key }}: {{ value }}
</li>
<!-- range (1 to n) -->
<span v-for="n in 10" :key="n">{{ n }}</span>
</template>Привязки v-model
v-model — двусторонняя привязка для полей форм: он синхронизирует значение ввода с реактивным состоянием. Один чекбокс привязывается к boolean; несколько чекбоксов с одним v-model привязываются к массиву отмеченных значений. Используйте модификаторы: .lazy (синхронизация по change вместо input), .number (приведение к числу), .trim (обрезка пробелов).
<template>
<!-- text input -->
<input v-model="text" />
<!-- multi-line textarea -->
<textarea v-model="message"></textarea>
<!-- checkbox (single = boolean, multiple = array) -->
<input type="checkbox" v-model="isChecked" />
<input type="checkbox" value="apple" v-model="fruits" />
<input type="checkbox" value="banana" v-model="fruits" />
<!-- radio -->
<input type="radio" value="A" v-model="picked" />
<!-- select -->
<select v-model="selected">
<option value="a">A</option>
<option value="b">B</option>
</select>
</template>Свои директивы
Свои директивы позволяют напрямую манипулировать DOM-элементами. В <script setup> любая переменная с именем vSomething (camelCase) автоматически доступна как v-something в шаблоне. У объекта директивы есть хуки жизненного цикла: mounted, updated, unmounted и др. Предпочитайте компоненты директивам, когда нужна реактивность, — директивы для низкоуровневой работы с DOM: фокус, подсказки, перетаскивание.
<script setup>
// local directive: function form (mounted + updated)
const vFocus = {
mounted: (el) => el.focus()
}
// global registration
// app.directive('focus', { mounted: el => el.focus() })
</script>
<template>
<input v-focus />
</template>Вычисляемые свойства
Базовый computed
computed создаёт кэширующий getter, который пересчитывается только при изменении зависимостей. В отличие от вызова метода, повторное обращение возвращает кэшированное значение, пока зависимость не обновится. В <script> доступ через .value; в шаблонах Vue разворачивает автоматически. Используйте computed вместо методов, когда значение зависит от реактивного состояния: это быстрее и декларативнее.
<script setup>
import { ref, computed } from 'vue'
const firstName = ref('John')
const lastName = ref('Doe')
// computed caches based on dependencies
const fullName = computed(() => {
return firstName.value + ' ' + lastName.value
})
// access via .value in script
console.log(fullName.value) // 'John Doe'
</script>
<template>
<!-- use without .value in template -->
<p>{{ fullName }}</p>
</template>Записываемый computed
По умолчанию computed только для чтения, но можно задать getter и setter. Setter вызывается при присваивании .value. Полезно для двусторонней привязки производного состояния, например синхронизации поля полного имени с полями имени и фамилии. Осторожно с бесконечными циклами: setter не должен напрямую менять зависимости самого computed так, чтобы запускать себя снова.
<script setup>
import { ref, computed } from 'vue'
const firstName = ref('John')
const lastName = ref('Doe')
const fullName = computed({
get() {
return firstName.value + ' ' + lastName.value
},
set(newValue) {
[firstName.value, lastName.value] = newValue.split(' ')
}
})
// assignment triggers the setter
fullName.value = 'Jane Smith'
</script>Computed против методов
Вычисляемые свойства кэшируют результат по зависимостям — они пересчитываются, только когда items меняется. Методы перезапускаются при каждом рендере независимо от того, что изменилось. Используйте computed для значений, производных от реактивного состояния; методы — для действий с параметрами или побочными эффектами. Computed также яснее выражает намерение: «это значение производное» против «сделай это».
<script setup>
import { ref, computed } from 'vue'
const items = ref([1, 2, 3, 4, 5])
// computed: cached, re-runs only if items changes
const doubled = computed(() =>
items.value.map(x => x * 2)
)
// method: re-runs on every render
function getDoubled() {
return items.value.map(x => x * 2)
}
</script>
<template>
<!-- cached, no recompute on unrelated re-renders -->
<p>{{ doubled }}</p>
<!-- re-invoked on every render -->
<p>{{ getDoubled() }}</p>
</template>Ловушки getter'а computed
Getter'ы computed должны быть чистыми: без побочных эффектов (без мутаций, async, запросов). Не вызывайте Date.now() или Math.random() — они не реактивны, поэтому computed не обновится. Если нужен побочный эффект, используйте watcher. Если нужен async, computed не будет ждать — используйте watch с ref или async setup с Suspense.
<script setup>
import { ref, computed } from 'vue'
const date = ref(new Date())
// BAD: non-reactive Date.now() — won't update
const badTime = computed(() => Date.now())
// BAD: side effect inside computed
const count = ref(0)
const bad = computed(() => {
count.value++ // never mutate state in computed!
return count.value
})
// GOOD: pure function of reactive state
const formatted = computed(() =>
date.value.toLocaleDateString()
)
</script>Computed в Options API
В Options API объявляйте computed в опции computed. К ним обращаются как this.total (без .value и без скобок) — Vue разворачивает автоматически. Записываемый computed использует функции get/set. Вычисляемые свойства доступны на экземпляре компонента наряду с data и methods, всё через this.
<script>
export default {
data() {
return { price: 100, quantity: 2 }
},
computed: {
total() {
return this.price * this.quantity
},
discounted: {
get() { return this.total * 0.9 },
set(v) { this.price = v / 0.9 / this.quantity }
}
},
methods: {
checkout() { console.log(this.total) }
}
}
</script>Watchers
Базовый watch
watch запускает колбэк при изменении отслеживаемого источника. Источником может быть ref, свойство reactive-объекта (через getter) или массив источников. Колбэк получает (newValue, oldValue). Используйте getter () => x.y, чтобы отслеживать вложенные реактивные свойства. Watchers — для побочных эффектов (запрос, лог, сохранение), а не для вывода состояния (для этого computed).
<script setup>
import { ref, watch } from 'vue'
const question = ref('')
// watch a ref
watch(question, (newValue, oldValue) => {
console.log('changed from', oldValue, 'to', newValue)
})
// watch a getter (computed source)
watch(
() => question.value.length,
(newLen) => {
if (newLen > 100) console.warn('Too long!')
}
)
</script>Глубокий watch и immediate
deep: true заставляет watch срабатывать на изменения любого вложенного свойства объекта — полезно, но дорого на больших структурах. immediate: true запускает колбэк сразу при настройке (oldValue при первом вызове undefined). Избегайте глубокого watch на огромных объектах — предпочитайте отслеживание конкретного getter'а () => obj.specificField ради производительности.
<script setup>
import { reactive, watch } from 'vue'
const user = reactive({
name: 'Alice',
address: { city: 'NYC', zip: '10001' }
})
// deep: watch nested property changes
watch(
() => user.address,
(newAddr) => console.log('address changed', newAddr),
{ deep: true }
)
// immediate: run callback right away
watch(
user,
(val) => saveToServer(val),
{ deep: true, immediate: true }
)
</script>watchEffect (авто-отслеживание)
watchEffect запускает колбэк сразу и автоматически отслеживает все реактивные зависимости, прочитанные внутри. При изменении любой отслеживаемой зависимости колбэк перезапускается. В отличие от watch, источник не указывается — он выводится. Используйте watchEffect, когда oldValue не нужен и хочется автоматического отслеживания зависимостей. Удобно для подписок, читающих несколько реактивных источников.
<script setup>
import { ref, watchEffect } from 'vue'
const a = ref(1)
const b = ref(2)
// runs immediately and tracks dependencies automatically
watchEffect(() => {
console.log('a + b =', a.value + b.value)
})
// logs: a + b = 3
a.value = 10 // logs: a + b = 12
// stop the watcher
const stop = watchEffect(() => { /* ... */ })
stop() // cleanup
</script>watch против watchEffect
Выбирайте watch, когда нужны: oldValue, ленивое выполнение (пропуск начального запуска) или явное указание источника. Выбирайте watchEffect, когда нужно немедленное выполнение, oldValue не нужен или есть побочные эффекты, затрагивающие несколько реактивных значений, и хочется авто-отслеживания. watch с массивом источников даёт в колбэке массивы новых и старых значений.
<script setup>
import { ref, watch, watchEffect } from 'vue'
const count = ref(0)
// watch: lazy, explicit source, has oldValue
watch(count, (newVal, oldVal) => {
console.log('count changed:', oldVal, '->', newVal)
})
// watchEffect: eager, auto-tracked, no oldValue
watchEffect(() => {
console.log('count is', count.value)
})
// logs immediately: count is 0
// watch multiple sources
const a = ref(1), b = ref(2)
watch([a, b], ([newA, newB], [oldA, oldB]) => {
console.log('a or b changed')
})
</script>Очистка watcher'а и flush
Колбэк onCleanup (3-й аргумент) регистрирует функцию очистки, которая выполняется перед следующим вызовом watcher'а, — идеально для отмены запросов в полёте, очистки таймеров и отписки. flush: 'post' запускает watcher после обновления DOM Vue (полезно, когда нужно прочитать обновлённый DOM). 'sync' выполняется синхронно при изменении зависимости — нужно редко и может вызвать проблемы производительности.
<script setup>
import { ref, watch } from 'vue'
const id = ref(1)
// cleanup function: runs before next callback
watch(id, (newId, oldId, onCleanup) => {
const controller = new AbortController()
fetch(`/api/user/${newId}`, { signal: controller.signal })
.then(r => r.json())
// cancel previous request when id changes again
onCleanup(() => controller.abort())
}, { flush: 'post' })
// flush: 'pre' (default) | 'post' (after DOM update) | 'sync'
</script>Условный рендеринг
v-if против v-show
v-if действительно добавляет и удаляет элементы из DOM — выше начальная стоимость, но нулевая, когда скрыто. v-show всегда рендерит элемент и переключает display:none — дешевле переключение, но элемент существует, даже когда скрыт. Используйте v-if для условий, которые редко меняются (или когда скрытых элементов вообще не должно быть). v-show — для часто переключаемого UI: вкладки, выпадающие списки, модалки.
<template>
<!-- v-if: element removed from DOM when false -->
<div v-if="isLoggedIn">Welcome back</div>
<!-- v-show: element stays, display toggles -->
<div v-show="isLoggedIn">Welcome back</div>
</template>
<!-- v-show compiles to: -->
<!-- <div style="display: none;">Welcome back</div> when false -->
<!-- v-if does not render the element at all when false -->v-if с цепочкой v-else
v-else-if и v-else должны идти сразу после v-if (или другого v-else-if) — между ними не может быть других элементов. Цепочка вычисляется сверху вниз и останавливается на первом истинном условии. Финальный v-else ловит все оставшиеся случаи. Этот паттерн отлично подходит для UI по статусу (загрузка, ошибка, пусто, успех).
<template>
<div v-if="status === 'loading'">Loading...</div>
<div v-else-if="status === 'error'">Error occurred</div>
<div v-else-if="status === 'empty'">No items</div>
<div v-else>
<ul>
<li v-for="item in items" :key="item.id">{{ item.name }}</li>
</ul>
</div>
</template><template> как обёртка для v-if
<template> — логическая обёртка, которая не рендерится в DOM: идеально, чтобы сгруппировать несколько элементов под одним v-if или v-for без лишнего HTML. Это сохраняет семантику разметки (без случайных div). Для v-for на template :key всё равно нужен на самом элементе template.
<template>
<!-- group elements under one condition, no wrapper div -->
<template v-if="showProfile">
<h2>{{ user.name }}</h2>
<p>{{ user.bio }}</p>
<button @click="edit">Edit</button>
</template>
<!-- combine v-if with v-for on template -->
<template v-for="item in items" :key="item.id">
<dt>{{ item.term }}</dt>
<dd>{{ item.def }}</dd>
</template>
</template>Приоритет v-if и v-for
Никогда не используйте v-if и v-for на одном элементе. В Vue 3 у v-if более высокий приоритет, поэтому он выполняется до v-for: переменная цикла ещё недоступна, что вызывает ошибки. Вместо этого фильтруйте массив вычисляемым свойством (предпочтительно) или inline .filter(). Если очень нужно, используйте обёртку <template v-for> с внутренним v-if.
<template>
<!-- AVOID: v-if and v-for on same element -->
<!-- In Vue 3, v-if has higher priority than v-for -->
<!-- so 'item' is not defined when v-if evaluates -->
<li v-for="item in items" v-if="item.active" :key="item.id">
{{ item.name }}
</li>
<!-- GOOD: filter first, then iterate -->
<li
v-for="item in items.filter(i => i.active)"
:key="item.id"
>
{{ item.name }}
</li>
<!-- BEST: use computed for the filtered list -->
</template>Transition с v-if
Оборачивайте элемент с v-if (или v-show) в <Transition>, чтобы анимировать появление и исчезновение. Vue добавляет классы в нужные моменты: v-enter-from, v-enter-active, v-enter-to (и v-leave-*). Определяйте CSS-переходы на этих классах. name='fade' заменяет префикс 'v-' на 'fade-'. Transition поддерживает только один дочерний элемент — для списков используйте TransitionGroup.
<template>
<Transition name="fade">
<p v-if="show">Hello</p>
</Transition>
</template>
<style>
.fade-enter-active, .fade-leave-active {
transition: opacity 0.3s;
}
.fade-enter-from, .fade-leave-to {
opacity: 0;
}
</style>Рендеринг списков
v-for с массивами
v-for перебирает массивы, предоставляя каждый элемент и (опционально) индекс. ВСЕГДА привязывайте :key к стабильному уникальному значению вроде item.id: это позволяет Vue сопоставлять старые и новые узлы при переупорядочивании, сохраняя состояние компонентов и DOM эффективно. Использование индекса как key ломается при вставке, удалении и переупорядочивании, вызывая тонкие баги.
<script setup>
import { ref } from 'vue'
const items = ref([
{ id: 1, name: 'Apple' },
{ id: 2, name: 'Banana' },
{ id: 3, name: 'Cherry' }
])
</script>
<template>
<!-- always provide :key with stable unique id -->
<li v-for="item in items" :key="item.id">
{{ item.name }}
</li>
<!-- with index (avoid as :key) -->
<li v-for="(item, index) in items" :key="item.id">
{{ index + 1 }}. {{ item.name }}
</li>
</template>v-for с объектами и диапазоном
v-for по объекту по умолчанию перебирает значения; второй аргумент — ключ, третий — индекс. Порядок перебора объекта следует Object.keys() (порядок вставки для строковых ключей). v-for с числом n перебирает от 1 до n включительно (не от 0 до n-1). Для фильтрованных и сортированных списков предпочитайте вычисляемое свойство inline-логике ради читаемости и кэширования.
<template>
<!-- iterate object: (value, key, index) -->
<div v-for="(value, key, index) in user" :key="key">
{{ index }}. {{ key }}: {{ value }}
</div>
<!-- iterate a number range (1 to n inclusive) -->
<span v-for="n in 10" :key="n">{{ n }} </span>
<!-- 1 2 3 4 5 6 7 8 9 10 -->
<!-- use v-for of computed for derived lists -->
<li v-for="todo in doneTodos" :key="todo.id">
{{ todo.text }}
</li>
</template>Отслеживание изменений списка
Vue 3 использует реактивность на Proxy, поэтому мутации массивов через push, pop, splice, sort, reverse вызывают обновления — без специальных оговорок (в отличие от Vue 2). Замена массива целиком (items.value = newArray) тоже работает, потому что setter значения ref запускает реактивность. filter/map создают новые массивы — присваивайте их обратно для обновления.
<script setup>
import { ref } from 'vue'
const items = ref([1, 2, 3])
// MUTATION methods (Vue 3 detects these via Proxy)
items.value.push(4) // add
items.value.pop() // remove last
items.value.splice(1, 1) // remove at index
items.value.sort() // sort
// REPLACEMENT (always reactive)
items.value = items.value.filter(n => n > 1)
items.value = [...items.value, 5]
</script>TransitionGroup для списков
TransitionGroup анимирует списки v-for: появление, исчезновение И перемещение (когда элементы меняют позицию). В отличие от Transition, он рендерит реальный элемент (задаётся через tag). У каждого ребёнка ОБЯЗАТЕЛЬНО должен быть уникальный :key. Класс .list-move анимирует скольжение элементов к новым позициям при переупорядочивании списка — полированный эффект, недостижимый на чистом CSS. Для плавных перемещений leave-active нужен position: absolute.
<template>
<TransitionGroup name="list" tag="ul">
<li v-for="item in items" :key="item.id">
{{ item.text }}
</li>
</TransitionGroup>
</template>
<style>
.list-enter-active, .list-leave-active {
transition: all 0.5s ease;
}
.list-enter-from, .list-leave-to {
opacity: 0;
transform: translateX(30px);
}
/* animate items moving to new positions */
.list-move {
transition: transform 0.5s ease;
}
</style>Производительность: v-memo
v-memo — подсказка оптимизации. Vue пропускает повторный рендер элемента, пока ни одно значение из массива зависимостей не изменилось. Для больших списков, где большинство элементов не меняется при обновлении, это может резко сократить число перерисовок. Используйте только когда измерили проблему производительности: преждевременная оптимизация добавляет сложность и риск устаревшего UI.
<template>
<!-- skip re-render of this item unless 'id' or 'selected' changes -->
<div
v-for="item in hugeList"
:key="item.id"
v-memo="[item.id, item.id === selectedId]"
>
{{ item.name }} — {{ item.id === selectedId ? '★' : '' }}
</div>
</template>Обработка событий
Инлайн-обработчики
@click (сокращение для v-on:click) привязывает обработчик клика. Инлайн-операторы (count++) годятся для простых случаев. Имя метода (greet) автоматически получает нативное событие первым аргументом. Чтобы передать свои аргументы И событие, вызывайте метод явно с $event: greet('hi', $event).
<script setup>
import { ref } from 'vue'
const count = ref(0)
const name = ref('Vue')
function greet(event) {
alert('Hello ' + name.value)
// event is the native DOM event
console.log(event.target.tagName)
}
</script>
<template>
<!-- inline statement -->
<button @click="count++">Add</button>
<!-- method reference (auto-receives event) -->
<button @click="greet">Greet</button>
<!-- call with custom args (use $event for native event) -->
<button @click="greet($event)">Greet</button>
</template>Модификаторы событий
Модификаторы событий добавляются после имени события через точку. .prevent и .stop самые частые (отправка формы, всплытие событий). .self гарантирует, что обработчик сработает только при клике по самому элементу (не по ребёнку). .passive сообщает браузеру, что обработчик не вызовет preventDefault, включая более плавную прокрутку, — важно для обработчиков касаний и прокрутки.
<template>
<!-- .prevent: call preventDefault() -->
<form @submit.prevent="onSubmit">...</form>
<!-- .stop: call stopPropagation() -->
<div @click="outer">
<button @click.stop="inner">Won't bubble</button>
</div>
<!-- .self: only trigger if event.target === current element -->
<div @click.self="onSelf">Only direct clicks</div>
<!-- .once: handler removed after first invocation -->
<button @click.once="init">Init once</button>
<!-- .capture: use capture phase instead of bubble -->
<div @click.capture="onCapture">...</div>
<!-- .passive: improve scroll perf (no preventDefault) -->
<div @scroll.passive="onScroll">...</div>
</template>Модификаторы клавиш и системные
Модификаторы клавиш фильтруют события клавиатуры по имени (.enter, .esc, .delete, .space, .tab, .up, .down, .left, .right). Системные модификаторы (.ctrl, .alt, .shift, .meta) требуют удержания этой клавиши. .exact гарантирует, что НИКАКИЕ другие системные модификаторы не нажаты: @click.ctrl.exact сработает только на Ctrl+клик, не на Ctrl+Shift+клик. Используйте kebab-case для клавиш, которым Vue не даёт алиаса (page-down).
<template>
<!-- key modifiers: only fire on specific keys -->
<input @keyup.enter="submit" />
<input @keyup.esc="cancel" />
<input @keyup.delete="remove" />
<!-- system modifiers: ctrl, alt, shift, meta -->
<button @click.ctrl="openInNewTab">Ctrl+Click</button>
<input @keyup.alt.enter="altEnter" />
<!-- .exact: no other modifiers can be pressed -->
<button @click.ctrl.exact="onCtrlOnly">Ctrl only</button>
<!-- any key code via kebab-case (deprecated but works) -->
<input @keyup.page-down="onPageDown" />
</template>Свои события через emit
Дочерние компоненты испускают события, чтобы сообщать наверх. defineEmits объявляет имена событий (для валидации и подсказок IDE). Родитель слушает через @event-name. Полезная нагрузка передаётся дополнительными аргументами emit и принимается обработчиком родителя. По соглашению используйте kebab-case имена событий в шаблонах (my-event) и camelCase в defineEmits (myEvent) — Vue преобразует автоматически.
<!-- ChildButton.vue -->
<script setup>
const emit = defineEmits(['increment', 'delete'])
function onClick() {
// emit with payload
emit('increment', 1)
}
</script>
<template>
<button @click="onClick">+1</button>
</template>
<!-- Parent.vue -->
<template>
<ChildButton @increment="onIncrement" @delete="remove" />
</template>
<script setup>
function onIncrement(amount) {
console.log('incremented by', amount)
}
</script>v-model на компонентах
defineModel() — современный макрос (Vue 3.4+) для двусторонней привязки на компонентах: он возвращает ref, автоматически синхронизированный с v-model родителя. Для нескольких привязок используйте именованные модели: v-model:fieldName. Под капотом это испускает 'update:modelValue' (или 'update:fieldName'), и родитель синхронизирует привязанный ref. Старый код использует defineProps + defineEmits вручную.
<!-- CustomInput.vue -->
<script setup>
const model = defineModel()
</script>
<template>
<input :value="model" @input="model = $event.target.value" />
</template>
<!-- Parent.vue -->
<template>
<CustomInput v-model="text" />
</template>
<!-- multiple v-models (Vue 3.4+) -->
<template>
<UserForm v-model:name="name" v-model:email="email" />
</template>Привязки форм
Текст и textarea
v-model на текстовых полях синхронизируется на каждое событие input. Для textarea ставьте v-model прямо на элемент (не как :value — многострочный контент в атрибуте не сработает). Модификаторы: .lazy синхронизирует по blur/change (меньше обновлений), .trim обрезает пробелы, .number приводит значение к Number. Цепочка модификаторов: v-model.lazy.trim.
<script setup>
import { ref } from 'vue'
const text = ref('')
const message = ref('')
</script>
<template>
<!-- text input: binds on every keystroke -->
<input v-model="text" placeholder="Type here" />
<p>You typed: {{ text }}</p>
<!-- textarea: insert tags inside, not :value -->
<textarea v-model="message" rows="4"></textarea>
<p>Preview: {{ message }}</p>
<!-- .lazy: sync on 'change' (blur) instead of 'input' -->
<input v-model.lazy="text" />
<!-- .trim: strip leading/trailing whitespace -->
<input v-model.trim="text" />
<!-- .number: cast to Number (NaN if invalid) -->
<input v-model.number="age" type="number" />
</template>Чекбокс и радио
Один чекбокс привязывается к boolean (checked = true). Несколько чекбоксов с общим v-model привязываются к массиву их атрибутов value: отметка добавляет значение, снятие удаляет. Радиокнопки с общим v-model привязывают значение выбранной опции к ref. Используйте атрибуты true-value / false-value, чтобы настроить отображение boolean.
<script setup>
import { ref } from 'vue'
const agreed = ref(false)
const fruits = ref([]) // array for multi-checkbox
const picked = ref('') // string for radio
</script>
<template>
<!-- single checkbox -> boolean -->
<input type="checkbox" v-model="agreed" /> I agree
<!-- multiple checkboxes with same v-model -> array -->
<input type="checkbox" value="apple" v-model="fruits" /> Apple
<input type="checkbox" value="banana" v-model="fruits" /> Banana
<input type="checkbox" value="cherry" v-model="fruits" /> Cherry
<p>Selected: {{ fruits }}</p>
<!-- radio: value binds to the chosen option -->
<input type="radio" value="A" v-model="picked" /> A
<input type="radio" value="B" v-model="picked" /> B
</template>Select
На <select> v-model ставится на сам select (не на options) и синхронизируется со значением выбранной опции. Используйте disabled опцию-заглушку с пустым value для UX «выберите...». Для динамических опций рендерите их через v-for и привязывайте :value. Добавьте атрибут multiple, чтобы разрешить множественный выбор, — тогда v-model привязывается к массиву выбранных значений.
<script setup>
import { ref } from 'vue'
const selected = ref('')
const multi = ref([])
const options = [
{ value: 'a', label: 'Option A' },
{ value: 'b', label: 'Option B' }
]
</script>
<template>
<!-- single select -->
<select v-model="selected">
<option disabled value="">Please select</option>
<option value="a">A</option>
<option value="b">B</option>
</select>
<!-- dynamic options -->
<select v-model="selected">
<option v-for="opt in options" :key="opt.value" :value="opt.value">
{{ opt.label }}
</option>
</select>
<!-- multi-select (hold Ctrl/Cmd) -> array -->
<select v-model="multi" multiple>
<option value="x">X</option>
<option value="y">Y</option>
</select>
</template>Отправка формы и валидация
Используйте @submit.prevent, чтобы обработать отправку формы и предотвратить перезагрузку страницы по умолчанию. Реактивные объекты формы группируют связанные поля. Для валидации популярны библиотеки вроде VeeValidate или Zod с composable для сложных форм, но простая функция validate(), возвращающая объект ошибок, хорошо работает для небольших форм. Всегда предотвращайте поведение по умолчанию, чтобы отправка была SPA-стиля.
<script setup>
import { reactive, ref } from 'vue'
const form = reactive({
email: '',
password: ''
})
const errors = ref({})
function validate() {
errors.value = {}
if (!form.email.includes('@')) errors.value.email = 'Invalid email'
if (form.password.length < 6) errors.value.password = 'Too short'
return Object.keys(errors.value).length === 0
}
function onSubmit() {
if (!validate()) return
// submit form...
}
</script>
<template>
<form @submit.prevent="onSubmit">
<input v-model.trim="form.email" />
<span v-if="errors.email">{{ errors.email }}</span>
<input type="password" v-model="form.password" />
<span v-if="errors.password">{{ errors.password }}</span>
<button type="submit">Submit</button>
</form>
</template>v-model со своими компонентами
Оборачивайте поля форм в свои компоненты для переиспользования. defineModel() возвращает ref, который читает значение родителя и пишет обратно через emit 'update:modelValue'. Компонент привязывает :value к модели и обновляет её по @input. Этот паттерн позволяет строить согласованную дизайн-систему полей (BaseInput, BaseSelect, BaseCheckbox), используемых с v-model как нативные элементы.
<!-- BaseInput.vue -->
<script setup>
const model = defineModel()
defineProps({
label: String,
type: { type: String, default: 'text' }
})
</script>
<template>
<label>
{{ label }}
<input
:type="type"
:value="model"
@input="model = $event.target.value"
/>
</label>
</template>
<!-- Usage -->
<template>
<BaseInput v-model="email" label="Email" type="email" />
</template>Компоненты
Определение и использование компонентов
Компонент — это .vue-файл с шаблоном, скриптом и необязательными стилями. Импортируйте его (автоматически регистрируется локально в <script setup>) и используйте как свой HTML-тег. Имена компонентов в скрипте в PascalCase, в шаблонах можно kebab-case (my-button) — Vue нормализует. Глобально зарегистрированные компоненты (app.component) доступны везде без импорта.
<!-- MyButton.vue -->
<template>
<button class="btn"><slot /></button>
</template>
<!-- App.vue -->
<script setup>
import MyButton from './MyButton.vue'
</script>
<template>
<MyButton>Click me</MyButton>
</template>Динамические компоненты
<component :is='...'> рендерит компонент динамически: значение может быть строкой зарегистрированного имени, импортированным объектом компонента или defineAsyncComponent. Оборачивайте в <keep-alive>, чтобы сохранять состояние компонента (ввод формы, позицию прокрутки) при переключении вкладок. Используйте shallowRef (не ref) для объектов компонентов, чтобы избежать накладных расходов глубокой реактивности.
<script setup>
import { ref, shallowRef } from 'vue'
import HomeTab from './HomeTab.vue'
import PostsTab from './PostsTab.vue'
import ArchiveTab from './ArchiveTab.vue'
const tabs = { HomeTab, PostsTab, ArchiveTab }
const current = shallowRef('HomeTab')
// keep component state when switching (e.g. form input)
import { keep-alive } from 'vue' // not real — use the tag
</script>
<template>
<button v-for="(comp, name) in tabs" :key="name" @click="current = name">
{{ name }}
</button>
<keep-alive>
<component :is="tabs[current]" />
</keep-alive>
</template>Асинхронные компоненты
defineAsyncComponent лениво загружает компонент при первом рендере: чанк запрашивается по требованию, уменьшая начальный размер бандла. Настройте состояния загрузки и ошибки для плавного UX. Комбинируйте с Suspense для координации нескольких асинхронных компонентов. Загрузчик возвращает Promise модуля компонента (Vite/Webpack автоматически разделяют бандл по динамическому import()).
<script setup>
import { defineAsyncComponent } from 'vue'
// lazy-load on first use (code-split)
const HeavyChart = defineAsyncComponent(() =>
import('./HeavyChart.vue')
)
// with loading, error, delay, timeout states
const AdminPanel = defineAsyncComponent({
loader: () => import('./AdminPanel.vue'),
loadingComponent: LoadingSpinner,
errorComponent: ErrorMsg,
delay: 200, // show loading after 200ms
timeout: 5000 // error if not loaded in 5s
})
</script>
<template>
<HeavyChart />
<AdminPanel />
</template>v-model компонента (несколько)
Именованные модели позволяют одному компоненту предоставить несколько двусторонних привязок. defineModel('name') объявляет каждую. Родитель использует v-model:name='...'. Это отлично для компонентов форм, объединяющих несколько полей (например, компонент адреса с улицей, городом, индексом). v-model по умо лчанию (без имени) соответствует 'modelValue'.
<!-- UserForm.vue -->
<script setup>
const firstName = defineModel('firstName')
const lastName = defineModel('lastName')
</script>
<template>
<input v-model="firstName" />
<input v-model="lastName" />
</template>
<!-- Parent.vue -->
<template>
<UserForm
v-model:firstName="form.first"
v-model:lastName="form.last"
/>
</template>Рекурсивные и циклические компоненты
Компонент может ссылаться на себя по имени файла (авто-самоссылка). Это идеально для древовидных структур (файловые деревья, ветки комментариев, меню). Для циклических ссылок между двумя компонентами (A импортирует B, B импортирует A) используйте defineAsyncComponent для одного из них или импорт в beforeCreate. Vue обрабатывает рекурсивные компоненты, но следите за бесконечными циклами — всегда должен быть базовый случай (без детей).
<!-- TreeNode.vue -->
<script setup>
defineProps({
node: Object
})
// a component can reference itself by its filename
// TreeNode.vue can use <TreeNode /> recursively
</script>
<template>
<div>
{{ node.label }}
<ul v-if="node.children?.length">
<li v-for="child in node.children" :key="child.id">
<TreeNode :node="child" />
</li>
</ul>
</div>
</template>Пропсы
Объявление пропсов
defineProps объявляет входной контракт компонента. Объявление в рантайме поддерживает type, default, required и validator. Объявлен ие на основе типов (только TS) даёт типобезопасность, но теряет рантайм-валидацию (используйте с volar и библиотекой валидаторов). Значения по умолчанию для объектов и массивов должны задаваться фабричной функцией: default: () => [].
<script setup>
// runtime declaration (validates types)
const props = defineProps({
title: String,
count: { type: Number, default: 0 },
items: { type: Array, required: true },
callback: { type: Function, default: () => {} },
status: {
type: String,
validator: (v) => ['active', 'idle'].includes(v)
}
})
// type-based declaration (TS only, no runtime validation)
const props2 = defineProps<{
title: string
count?: number
}>()
</script>Именование и передача пропсов
Пропсы должны быть в camelCase в JS (greetingMessage) и в kebab-case в шаблонах (greeting-message): HTML регистронезависим, поэтому kebab-case безопаснее. Vue преобразует автоматически. Статические строковые пропсы передаются обычным атрибутом; динамические значения — через :prop. Числа, boolean и объекты всегда передавайте с :, чтобы их не трактовали как строки.
<!-- Child.vue -->
<script setup>
defineProps({
greetingMessage: String,
userId: Number
})
</script>
<!-- Parent.vue -->
<template>
<!-- kebab-case in templates (HTML-friendly) -->
<Child greeting-message="Hello" :user-id="42" />
<!-- camelCase also works in SFC templates -->
<Child greetingMessage="Hello" :userId="42" />
</template>Однонаправленный поток данных
Пропсы только для чтения — никогда не мутируйте их напрямую. Vue предупреждает в dev-режиме. Чтобы изменить значение пропса, испустите событие и позвольте родителю обновить его (однонаправленный поток). Для локальной рабочей копии инициализируйте ref из пропса и синхронизируйте через watch. Самый чистый двусторонний паттерн — v-model с defineModel, который абстрагирует танец emit и update.
<!-- BAD: mutating a prop -->
<script setup>
const props = defineProps(['count'])
function inc() {
props.count++ // WARNING: don't mutate props!
}
</script>
<!-- GOOD: emit to parent, or use local copy -->
<script setup>
import { ref, watch } from 'vue'
const props = defineProps(['count'])
const emit = defineEmits(['update:count'])
// local copy that syncs with prop
const local = ref(props.count)
watch(() => props.count, v => local.value = v)
function inc() {
local.value++
emit('update:count', local.value)
}
</script>Валидация пропсов и значения по умолчанию
Vue валидирует пропсы в dev-режиме и предупреждает при ошибке (не в продакшене). type принимает конструктор (String, Number, Boolean, Array, Object, Function, Symbol) или массив из них. Значения по умолчанию для Object и Array ОБЯЗАНЫ быть функциями, возвращающими новый экземпляр: иначе все компоненты делили бы одну ссылку по умолчанию (баги мутаций). Валидаторы запускаются после проверки типов.
<script setup>
const props = defineProps({
// type can be an array of allowed types
value: { type: [String, Number], required: true },
// object/array default MUST be a factory function
list: {
type: Array,
default: () => []
},
// custom validator
age: {
type: Number,
validator: (v) => v >= 0 && v <= 150
},
// multiple checks combined
email: {
type: String,
required: true,
validator: (v) => v.includes('@')
}
})
</script>Приведение boolean и fallthrough атрибутов
У булевых пропсов особое приведение: наличие без значения означает true. Fallthrough атрибуто в автоматически передаёт не-пропс атрибуты (class, style, id, data-*) на корневой элемент. При нескольких корнях нужно явно указать v-bind='$attrs' на нужном элементе. Отключите fallthrough через defineOptions({ inheritAttrs: false }) для полного контроля.
<!-- prop declared as Boolean -->
<script setup>
defineProps({
disabled: Boolean,
active: Boolean
})
</script>
<!-- Parent -->
<template>
<MyButton disabled /> <!-- disabled = true -->
<MyButton :disabled="false" /> <!-- disabled = false -->
<MyButton /> <!-- disabled = undefined -->
</template>
<!-- Attribute fallthrough: non-prop attributes
land on the root element automatically -->
<template>
<!-- <MyButton data-id="5" class="large" /> -->
<!-- the data-id and class merge onto the <button> root -->
<button>...</button>
</template>Emits
Объявление и испускание
defineEmits объявляет события, которые компонент может испускать. Форма объекта позволяет валидаторы, получающие нагрузку и возвращающие false для предупреждения (dev-режим). События идут вверх по дереву — родители слушают через @event-name. Всегда объявляйте emits явно: это документирует API, включает исключение из fallthrough атрибутов и поддерживает валидацию. emit() принимает имя события и необязательные аргументы нагрузки.
<script setup>
// declare emits (with optional validation)
const emit = defineEmits({
// null-ish = no validation
click: null,
// function = validate payload
submit: (payload) => {
if (!payload.email) {
console.warn('submit needs email')
return false
}
return true
}
})
function handleSubmit() {
emit('submit', { email: '[email protected]', name: 'Alice' })
}
</script>Прослушивание emits
Родители слушают через @event-name (или v-on:event-name). Обработчик получает любую испущенную нагрузку. Инлайн стрелочные функции удобны для простых преобразований (@increment='n => count += n'). Обработчики-методы автоматически получают нагрузку первым аргументом. Нативные DOM-события на корневом элементе компонента проходят fallthrough, если не объявлены в emits, — объявление 'click' делает его своим событием.
<!-- Child.vue -->
<script setup>
const emit = defineEmits(['increment', 'delete'])
function click() {
emit('increment', 5)
}
</script>
<template>
<button @click="click">+5</button>
</template>
<!-- Parent.vue -->
<template>
<!-- inline handler -->
<Child @increment="n => count += n" />
<!-- method handler -->
<Child @increment="onIncrement" @delete="onDelete" />
</template>
<script setup>
function onIncrement(amount) {
console.log('incremented by', amount)
}
</script>Реализация v-model
v-model на компоненте — сахар для :modelValue + @update:modelValue. Ребёнок получает значение через пропс modelValue и испускает update:modelValue для синхронизации. Это ручной паттерн; defineModel() (Vue 3.4+) его оборачивает. Для именованного v-model (v-model:foo) используйте имя пропса foo и событие update:foo. Это позволяет строить компоненты форм, работающие как нативные поля.
<!-- CustomInput.vue (manual implementation) -->
<script setup>
const props = defineProps(['modelValue'])
const emit = defineEmits(['update:modelValue'])
function onInput(e) {
emit('update:modelValue', e.target.value)
}
</script>
<template>
<input
:value="modelValue"
@input="onInput"
/>
</template>
<!-- Parent -->
<template>
<CustomInput v-model="text" />
</template>Валидация emit
Валидаторы emit получают аргументы нагрузки и возвращают false, чтобы вызвать предупреждение в dev-режиме. Они не предотвращают emit, а только предупреждают. Это ловит нарушения контракта на ранней стадии разработки. Используйте их для документирования ожидаемой формы нагрузки. В продакшене валидаторы вырезаются, поэтому не полагайтесь на них для безопасности или управления потоком.
<script setup>
const emit = defineEmits({
// no validation
click: null,
// validate payload; return false to warn
change: (value) => {
if (typeof value !== 'string') {
console.warn('change payload must be string')
return false
}
return true
},
// validate multiple args
update: (id, value) => {
if (!id || value === undefined) return false
return true
}
})
// validation runs on emit
emit('change', 123) // warns: must be string
</script>События и пропсы: когда что
Следуйте однонаправленному потоку данных: пропсы вниз, события вверх. Для двусторонней привязки используйте v-model (сахар пропсов и emit). При глубокой вложенности пробрасывание пропсов становится болезненным — используйте provide/inject для внедрения зависимостей или store (Pinia) для общего состояния. События — уведомления «что-то произошло»; пропсы — «вот твои данные».
<!-- Parent-to-child: props (down) -->
<template>
<Child :data="parentData" :config="config" />
</template>
<!-- Child-to-parent: emits (up) -->
<template>
<Child @change="onChange" @submit="onSubmit" />
</template>
<!-- Two-way: v-model (combines both) -->
<template>
<Child v-model="value" />
</template>
<!-- For complex state, prefer provide/inject or a store -->Слоты
Сло т по умолчанию
Слоты позволяют родителю вставлять контент в шаблон дочернего компонента. Элемент <slot> — это плейсхолдер. Дочерний контент родителя заполняет слот по умолчанию. Слоты включают композицию: Card отвечает за стилизацию обёртки, родитель управляет внутренним контентом. Без слотов понадобился бы пропс для каждого возможного внутреннего элемента — слоты куда гибче.
<!-- Card.vue -->
<template>
<div class="card">
<slot />
</div>
</template>
<!-- Usage -->
<template>
<Card>
<p>This goes into the default slot</p>
<button>Action</button>
</Card>
</template>Именованные слоты
Именованные слоты позволяют компоненту иметь несколько плейсхолдеров контента. Объявляйте через <slot name='foo' />, заполняйте через <template #foo>. # — сокращение для v-slot:. Слот без имени — слот 'default': контент без обёртки template идёт туда. Именованные слоты идеальны для раскладок (header, sidebar, main, footer), где родитель заполняет каждую область.
<!-- Layout.vue -->
<template>
<header><slot name="header" /></header>
<main><slot /></main>
<footer><slot name="footer" /></footer>
</template>
<!-- Usage with # shorthand -->
<template>
<Layout>
<template #header>
<h1>My Page Title</h1>
</template>
<!-- default slot (no #name) -->
<p>Main content here</p>
<template #footer>
<p>© 2025</p>
</template>
</Layout>
</template>Пропсы слота (scoped slots)
Scoped slots позволяют ребёнку передавать данные наверх в контент слота родителя. Ребёнок привязывает данные на <slot :item='item'>; родитель получает их через v-slot='{ item }' (или #default='{ item }'). Это основа переиспользуемых компонентов списков (таблица данных, виртуальный список): ребёнок отвечает за перебор, родитель — за отрисовку каждого элемента.
<!-- List.vue -->
<template>
<ul>
<li v-for="item in items" :key="item.id">
<slot :item="item" :index="index" />
</li>
</ul>
</template>
<script setup>
defineProps(['items'])
</script>
<!-- Usage: receive slot props via v-slot -->
<template>
<List :items="todos">
<template #default="{ item, index }">
<input type="checkbox" v-model="item.done" />
<span :class="{ done: item.done }">{{ index }}: {{ item.text }}</span>
</template>
</List>
</template>Контент слота по умолчанию
Fallback-контент слота находится между <slot> и </slot>. Он рендерится, только когда родитель не передал контент слота. Это отлично для разумных значений по умолчанию: подпись кнопки, сообщение пустого состояния, плейсхолдер. Если родитель передаёт даже пустую строку, fallback переопределяется.
<!-- Button.vue -->
<template>
<button>
<slot>Click here</slot> <!-- fallback content -->
</button>
</template>
<!-- Usage -->
<template>
<Button /> <!-- renders "Click here" -->
<Button>Save</Button> <!-- renders "Save" -->
</template>Область рендеринга и useSlots
Контент слота рендерится в области РОДИТЕЛЯ: он может обращаться к состоянию родителя, но не к состоянию ребёнка напрямую (если только через пропсы слота). Это разделение позволяет ребёнку отвечать за механику (пагинация, виртуализация, запросы), а родителю — за представление. Паттерн scoped slots (FancyList + UserCard) — мощная техника композиции: ребёнок владеет потоком данных, родитель — рендерингом.
<!-- FancyList.vue (scoped slot pattern) -->
<script setup>
const props = defineProps(['items', 'pageSize'])
import { ref, computed } from 'vue'
const page = ref(1)
const paged = computed(() =>
props.items.slice((page.value - 1) * props.pageSize, page.value * props.pageSize)
)
</script>
<template>
<div v-for="item in paged" :key="item.id">
<slot :item="item" :page="page" />
</div>
</template>
<!-- Usage: parent fully controls rendering -->
<FancyList :items="users" :pageSize="10">
<template #default="{ item, page }">
<UserCard :user="item" />
<small>Page {{ page }}</small>
</template>
</FancyList>Хуки жизненного цикла
Хуки Composition API
Хуки жизненного цикла выполняются на определённых стадиях. onMounted срабатывает после рендеринга DOM (безопасно обращаться к элементам, запускать canvas-библиотеки, загружать данные). onUpdated срабатывает после каждого реактивного обновления — избегайте здесь мутации состояния (бесконечный цикл). onUnmounted — для очистки (таймеры, слушатели, подписки). Хуки должны вызываться синхронно в setup, но можно вызывать несколько раз.
<script setup>
import {
onBeforeMount, onMounted,
onBeforeUpdate, onUpdated,
onBeforeUnmount, onUnmounted,
onActivated, onDeactivated,
onErrorCaptured
} from 'vue'
onBeforeMount(() => console.log('before mount'))
onMounted(() => console.log('mounted — DOM ready'))
onBeforeUpdate(() => console.log('before re-render'))
onUpdated(() => console.log('after re-render'))
onBeforeUnmount(() => console.log('before unmount'))
onUnmounted(() => console.log('unmounted — cleanup'))
</script>Setup и created
В <script setup> всё тело скрипта выполняется при инициализации компонента — эквивалент beforeCreate + created в Options API. Отдельного хука created() нет. Код верхнего уровня (объявления, вызовы функций, даже async-работа) выполняется один раз на экземпляр. Для загрузки данных это частое место старта (хотя onMounted тоже подходит — запрос начнётся одинаково).
<script setup>
// <script setup> runs BEFORE the component is mounted
// (equivalent to beforeCreate + created in Options API)
import { ref } from 'vue'
// this code runs once per component instance,
// before reactive state is exposed to the template
const count = ref(0)
console.log('component created, count =', count.value)
// no need for created() hook — just run code here
fetch('/api/data')
.then(r => r.json())
.then(data => { /* ... */ })
</script>Mounted и очистка
Пары setup/cleanup обязательны: каждый слушатель, таймер, подписка или observer, добавленный в onMounted, ДОЛЖЕН быть удалён в onUnmounted. Без очистки появляются утечки памяти и зомби-обработчики, срабатывающие на уничтоженных компонентах. Паттерн: addEventListener в onMounted, removeEventListener в onUnmounted. Для watcher'ов используйте возвращаемую функцию остановки или они сами очистятся при размонтировании.
<script setup>
import { ref, onMounted, onUnmounted } from 'vue'
const windowWidth = ref(window.innerWidth)
function onResize() {
windowWidth.value = window.innerWidth
}
onMounted(() => {
// setup side effects after DOM is ready
window.addEventListener('resize', onResize)
console.log('mounted')
})
onUnmounted(() => {
// ALWAYS clean up to avoid memory leaks
window.removeEventListener('resize', onResize)
})
</script>Хуки KeepAlive
Когда компонент обёрнут в <KeepAlive>, уход от него не размонтирует его — он деактивируется (кэшируется). onActivated и onDeactivated срабатывают при показе и скрытии. Испол ьзуйте их, чтобы приостановить и возобновить работу (опрос, воспроизведение видео) без полного setup/teardown. onMounted всё равно срабатывает один раз (при первой активации); onUnmounted никогда не срабатывает, пока компонент в кэше. Эти хуки позволяют оптимизировать ресурсы для кэшированных вкладок.
<script setup>
import { onActivated, onDeactivated } from 'vue'
// these fire when the component is wrapped in <KeepAlive>
// and is being shown (activated) or hidden (deactivated)
onActivated(() => {
console.log('component shown again — resume polling')
startPolling()
})
onDeactivated(() => {
console.log('component hidden but not unmounted — pause')
stopPolling()
})
// onMounted fires only once (first show)
// onActivated fires every time it's re-shown
</script>Error Captured
onErrorCaptured ловит ошибки из дочерних компонентов (в шаблонах, рендере, жизненном цикле, watcher'ах). Он получает (error, instance, info). Возврат false останавливает распространение ошибки к родительским errorCaptured и глобальному errorHandler. Используйте для компонентов-границ, которые аккуратно обрабатывают ошибки детей (как Error Boundaries в React). Комбинируйте с Suspense для асинхронных состояний ошибки.
<script setup>
import { onErrorCaptured, ref } from 'vue'
const error = ref(null)
onErrorCaptured((err, instance, info) => {
// err: the error thrown
// instance: component that threw
// info: lifecycle hook or event name where it occurred
error.value = err.message
console.error('Captured:', err, info)
// return false to stop propagation to parent
return false
})
</script>
<template>
<div v-if="error" class="error">{{ error }}</div>
<slot v-else />
</template>Composition API
ref против reactive
ref() работает с любым значением (примитивы, объекты). В JS реактивный доступ требует .value, но в шаблонах разворачивается автоматически. reactive() работает только с объектами и массивами — .value не нужен. Используйте ref для примитивов и заменяемых значений; reactive — для сгруппированного состояния. Правило: предпочитайте ref() для отдельных значений, reactive() для объектов состояния. Смешивать можно: refs авто-разворачиваются внутри reactive-объектов.
<script setup>
import { ref, reactive } from 'vue'
// ref: works with any value, access via .value
const count = ref(0)
count.value++
console.log(count.value) // 1
// reactive: only for objects/arrays, no .value needed
const state = reactive({ count: 0, user: { name: 'A' } })
state.count++
console.log(state.count) // 1
// refs auto-unwrap in templates and reactive objects
const wrapper = reactive({ count }) // wrapper.count === count.value
</script>Ловушки reactive
У reactive-объектов две ловушки: нельзя переприсвоить переменную (state = newObj) — мутируйте свойства (state.list = []). Деструктуризация теряет реактивность, потому что деструктурированная переменная — снимок. Используйте toRefs(), чтобы превратить свойства reactive в связанные refs. Из-за этих ловушек многие предпочитают ref(): его можно заменить (просто задать .value), и он дружелюбен к деструктуризации.
<script setup>
import { reactive, ref } from 'vue'
const state = reactive({ list: [1, 2, 3] })
// PITFALL 1: replacing the whole object loses reactivity
// state = reactive({ list: [4, 5] }) // ERROR: reassign
// GOOD: mutate properties
state.list = [4, 5]
// PITFALL 2: destructuring loses reactivity
let { list } = state // 'list' is now plain
// list.push(4) won't trigger updates
// FIX: use toRefs to keep reactivity
import { toRefs } from 'vue'
const { list } = toRefs(state) // now list is a ref
</script>toRef и toRefs
toRef() превращает одно reactive-свойство в ref, остающийся связанным (мутация любого влияет на другой). toRefs() превращает ВСЕ свойства — полезно для возврата реактивного состояния из composables с сохранением деструктуризации. Без toRefs деструктурированные значения теряют реактивность. Паттерн: composable возвращает toRefs(state), чтобы потребители могли деструктурировать без потери реактивности.
<script setup>
import { reactive, toRef, toRefs } from 'vue'
const state = reactive({
count: 0,
name: 'Alice'
})
// toRef: single property -> ref (stays linked to state)
const countRef = toRef(state, 'count')
// toRefs: all properties -> object of refs
const { count, name } = toRefs(state)
countRef.value++ // updates state.count
count.value++ // also updates state.count
console.log(state.count) // 2
</script>computed и watch в setup
В <script setup> computed() и watch() импортируются и вызываются напрямую. computed создаёт производный ref; watch запускает колбэк при изменении источника. watch может принимать один ref, getter, массив источников или reactive-объект. Это основные примитивы Composition API — комбинируйте их, чтобы инкапсулировать логику в composables.
<script setup>
import { ref, computed, watch } from 'vue'
const a = ref(1)
const b = ref(2)
// computed: derived value, cached
const sum = computed(() => a.value + b.value)
// watch: side effect on change
watch(sum, (newSum) => {
console.log('sum changed to', newSum)
})
// watch multiple sources
watch([a, b], ([newA, newB]) => {
console.log('a or b changed:', newA, newB)
})
</script>shallowRef и shallowReactive
shallowRef и shallowReactive отказываются от глубокой реактивности — отслеживается только ссылка верхнего уровня или верхние свойства. Это резко улучшает производительность для больших структур данных (например, массива данных графика, графа 3D-сцены), где глубокое отслеживание избыточно. Используйте triggerRef(), чтобы вручную уведомить Vue после глубокой мутации. Прибегайте к этому, только когда измерили проблему производительности.
<script setup>
import { shallowRef, shallowReactive, triggerRef } from 'vue'
// shallowRef: only .value changes trigger updates
// (deep changes to .value properties do NOT)
const big = shallowRef({ items: [1, 2, 3] })
big.value.items.push(4) // NO update triggered
big.value = { items: [1,2,3,4] } // update triggered
// force update after deep mutation
big.value.items.push(5)
triggerRef(big) // tells Vue to re-render
// shallowReactive: only root-level props are reactive
const state = shallowReactive({ user: { name: 'A' } })
state.count = 1 // reactive
state.user.name = 'B' // NOT reactive
</script>Composables
Написание composable
Composable — функция, инкапсулирующая переиспользуемую реактивную логику. По соглашению имя начинается с use. Она использует хуки Composition API (onMounted и др.), которые привязываются к жизненному циклу потребляющего компонента. Возвращайте refs и методы. Компонент их деструктурирует. Composables — аналог React hooks в Vue: они позволяют делиться stateful-логикой без render props и HOC.
<!-- useMousePosition.js -->
import { ref, onMounted, onUnmounted } from 'vue'
export function useMousePosition() {
const x = ref(0)
const y = ref(0)
function update(e) {
x.value = e.pageX
y.value = e.pageY
}
onMounted(() => window.addEventListener('mousemove', update))
onUnmounted(() => window.removeEventListener('mousemove', update))
return { x, y }
}
<!-- In component -->
<script setup>
import { useMousePosition } from './useMousePosition'
const { x, y } = useMousePosition()
</script>Stateful composable (общее состояние)
Когда состояние объявлено на уровне модуля (вне функции), это синглтон: все компоненты, использующие composable, делят одно состояние. Это лёгкая альтернатива Pinia для простого глобального состояния. Используйте readonly(), чтобы отдать состояние без прямых мутаций: компоненты должны вызывать login/logout. Для сложных приложений предпочитайте Pinia (лучшие devtools, персистентность, SSR).
<!-- useUser.js -->
import { reactive, readonly } from 'vue'
// module-scoped state — shared across all consumers
const state = reactive({
user: null,
loading: false
})
export function useUser() {
async function login(credentials) {
state.loading = true
state.user = await fetch('/api/login', {
method: 'POST',
body: JSON.stringify(credentials)
}).then(r => r.json())
state.loading = false
}
function logout() {
state.user = null
}
return {
user: readonly(state.user), // expose read-only
loading: readonly(state.loading),
login,
logout
}
}Composable useFetch
Этот composable оборачивает fetch состоянием загрузки и ошибки и перезапрашивает при изменении реактивного url. isRef() проверяет, является ли вход ref; unref() разворачивает его (возвращает значение для refs, иначе сам объект). Возврат refresh позволяет потребителю перезапросить вручную. Этот паттерн (реактивный вход + авто-перезапуск + раскрытие состояния) — хлеб composables для загрузки данных.
<!-- useFetch.js -->
import { ref, watchEffect, isRef, unref } from 'vue'
export function useFetch(url) {
const data = ref(null)
const error = ref(null)
const loading = ref(true)
async function doFetch() {
loading.value = true
error.value = null
try {
const res = await fetch(unref(url))
if (!res.ok) throw new Error('HTTP ' + res.status)
data.value = await res.json()
} catch (e) {
error.value = e.message
} finally {
loading.value = false
}
}
// re-fetch when url ref changes
if (isRef(url)) {
watchEffect(doFetch)
} else {
doFetch()
}
return { data, error, loading, refresh: doFetch }
}Composable с очисткой
Composables, регистрирующие побочные эффекты (слушатели, таймеры, подписки), ОБЯЗАНЫ очищаться — обычно через onUnmounted внутри composable. Это привязывает очистку к любому компоненту, использующему composable, так что потребителю не нужно помнить. Это большое преимущество composables перед утилитарными функциями: они участвуют в жизненном цикле компонента.
<!-- useEventListener.js -->
import { onUnmounted } from 'vue'
export function useEventListener(target, event, callback) {
target.addEventListener(event, callback)
// auto-cleanup when the consuming component unmounts
onUnmounted(() => {
target.removeEventListener(event, callback)
})
}
<!-- Usage -->
<script setup>
import { useEventListener } from './useEventListener'
import { ref } from 'vue'
const key = ref('')
useEventListener(window, 'keydown', (e) => {
key.value = e.key
})
// listener is removed automatically on unmount
</script>Соглашения composables
Соблюдайте соглашения: (1) имена composables с префиксом use; (2) возвращайте refs (не простые значения — простые теряют реактивность); (3) принимайте refs или getters как входы для гибкости; (4) используйте onUnmounted для очистки; (5) держите их сфокусированными (одна задача на composable). Эти соглашения делают composables сочетаемыми друг с другом и предсказуемыми в использовании.
<!-- DO: name with 'use' prefix, return refs -->
export function useCounter(initial = 0) {
const count = ref(initial)
const inc = () => count.value++
const dec = () => count.value--
return { count, inc, dec }
}
<!-- AVOID: returning plain values (loses reactivity) -->
export function badCounter() {
let count = 0 // plain variable — NOT reactive!
return { count, inc: () => count++ }
}
<!-- DO: accept refs/getters for flexible inputs -->
export function useSearch(query) {
// query can be a ref, a getter, or a plain value
return watchEffect(() => fetch('/api?q=' + unref(query)))
}Реактивность изнутри
Механика reactive Proxy
Реактивность Vue 3 использует Proxy (ES6). reactive() возвращает Proxy, перехватывающий get (для отслеживания зависимостей) и set (для запуска обновлений). Исходный объект не изменяется — вы получаете обёртку. isReactive() проверяет, является ли что-то реактивным прокси. Это мощнее подхода Vue 2 через Object.defineProperty, который не замечал добавления новых свойств.
<script setup>
import { reactive, isReactive, isProxy } from 'vue'
const state = reactive({ count: 0 })
// reactive() wraps the object in a Proxy
// reads/writes are tracked and trigger updates
state.count++ // triggers re-render
// the original object is NOT reactive
const raw = { count: 0 }
const wrapped = reactive(raw)
console.log(raw === wrapped) // false
console.log(isReactive(wrapped)) // true
console.log(isReactive(raw)) // false
console.log(isProxy(wrapped)) // true
</script>Правила разворачивания ref
Правила разворачивания ref: в <script> доступ через .value; в шаблонах и внутри reactive-объектов refs авто-разворачиваются до своего .value. Поэтому {{ count }} в шаблоне работает без .value. Разворачивание поверхностное — вложенные refs в массивах и Map не разворачиваются. Reactive-объекты, содержащие refs, при присваивании меняют значение ref: state.count = 5 задаёт count.value = 5.
<script setup>
import { ref, reactive } from 'vue'
const count = ref(0)
const state = reactive({ count })
// in JS: ref needs .value
count.value = 1
// in reactive object: ref auto-unwraps
console.log(state.count) // 1 (not count.value)
state.count = 5 // updates count.value
// in templates: ref auto-unwraps
// {{ count }} renders count.value
</script>
<template>
<p>{{ count }}</p> <!-- 5, not [object Object] -->
</template>Effect и track/trigger (внутренности)
effect() — низкоуровневый примитив, лежащий в основе реактивности: он запускает функцию, отслеживает каждое реактивное чтение внутри и перезапускается при изменении любого отслеживаемого значения. computed, watch, watchEffect и рендеринг компонентов строятся на effect. В коде приложения effect() вызывают редко — предпочитайте computed/watch/watchEffect, — но это двигатель. Понимание помогает рассуждать о порядке и тайминге.
<script setup>
import { ref, effect } from 'vue'
const count = ref(0)
// effect runs immediately, then re-runs on dep change
effect(() => {
console.log('count is', count.value)
})
// logs: count is 0
count.value = 10
// logs: count is 10
// internally:
// - effect tracks dependencies accessed inside it
// - setting count.value triggers all tracked effects
</script>markRaw и readonly
markRaw() навсегда выводит объект из реактивности — полезно для экземпляров сторонних классов (графики, карты, игровое состояние), у которых свои механизмы обновлени я и которые не стоит оборачивать в Proxy. readonly() создаёт read-only представление реактивного объекта: попытки мутации предупреждают в dev-режиме. Используйте readonly, чтобы отдавать состояние из composables и store, запрещая прямые мутации.
<script setup>
import { reactive, markRaw, readonly, isReadonly } from 'vue'
// markRaw: opt a value OUT of reactivity forever
const bigChart = markRaw(new HeavyChartLib())
const state = reactive({ chart: bigChart })
// state.chart mutations won't trigger Vue updates
// (use chart's own API to update it)
// readonly: make a reactive object read-only
const original = reactive({ count: 0 })
const frozen = readonly(original)
frozen.count = 5
// warning: target is readonly (dev mode)
console.log(isReadonly(frozen)) // true
</script>Custom ref (фабрика)
customRef() позволяет явно управлять отслеживанием зависимостей и запуском. Фабрика получает track() и trigger(): вызывайте track() в get(), чтобы зарегистрировать зависимость, и trigger() в set(), чтобы уведомить об обновлении. Это открывает паттерны вроде debounced refs, ленивых refs или refs поверх хранилища. Мощно, но используйте умеренно — обычно watchEffect + обычный ref понятнее.
<script setup>
import { customRef } from 'vue'
// debounce a ref's updates
function debouncedRef(value, delay = 200) {
let timeout
return customRef((track, trigger) => ({
get() {
track() // tell Vue this value is a dependency
return value
},
set(newValue) {
clearTimeout(timeout)
timeout = setTimeout(() => {
value = newValue
trigger() // notify Vue of the change
}, delay)
}
}))
}
const text = debouncedRef('', 300)
// input only triggers re-render 300ms after typing stops
</script>Vue Router
Настройка роутера
createRouter настраивает маршрутизацию. createWebHistory использует режим HTML5 history (чистые URL, требует серверного fallback на index.html). Лениво загружайте компоненты маршрутов через динамический import() для code-splitting: каждый маршрут становится своим бандлом. Динамические сегменты (:id) доступны через route.params. Установите роутер как плагин через app.use(router).
<!-- router/index.js -->
import { createRouter, createWebHistory } from 'vue-router'
import Home from '../views/Home.vue'
const routes = [
{ path: '/', name: 'home', component: Home },
{
path: '/about',
name: 'about',
// lazy-load for code-splitting
component: () => import('../views/About.vue')
},
{ path: '/user/:id', name: 'user', component: () => import('../views/User.vue') }
]
export const router = createRouter({
history: createWebHistory(),
routes
})
<!-- main.js -->
import { createApp } from 'vue'
import App from './App.vue'
import { router } from './router'
createApp(App).use(router).mount('#app')RouterView и RouterLink
<RouterView> — плейсхолдер, где рендерится компонент совпавшего маршрута. <RouterLink> рендерит тег <a>, но перехватывает клики для клиентской навигации (без полной перезагрузки страницы). Проп to принимает строковый путь или объект ({ name, params, query }). RouterLink добавляет классы active/exact-active для стилизации текущей ссылки.
<!-- App.vue -->
<template>
<nav>
<!-- RouterLink renders <a>, handles navigation -->
<RouterLink to="/">Home</RouterLink>
<RouterLink to="/about">About</RouterLink>
<RouterLink :to="{ name: 'user', params: { id: 42 } }">
User 42
</RouterLink>
</nav>
<!-- matched route's component renders here -->
<RouterView />
</template>Навигация и программная маршрутизация
useRouter() даёт экземпляр роутера для навигации; useRoute() даёт текущий маршрут (реактивный). push добавляет запись в историю (кнопка назад работает); replace — нет. Свойства маршрута (path, params, query, hash, name, matched) реактивны — watcher'ы и computed перезапускаются при навигации. Всегда используйте router.push для навигации внутри приложения и никогда window.location, чтобы оставаться SPA.
<script setup>
import { useRouter, useRoute } from 'vue-router'
const router = useRouter()
const route = useRoute()
// push to a new URL (adds to history)
function goHome() {
router.push('/')
router.push({ name: 'user', params: { id: 1 } })
router.push({ path: '/search', query: { q: 'vue' } })
}
// replace current entry (no back button)
router.replace('/login')
// go back/forward
router.back()
router.forward()
router.go(-2)
// access current route info
console.log(route.path, route.params.id, route.query.q)
</script>Навигационные хуки
Хуки управляют потоком навигации. Глобальный beforeEach хорош для проверки авторизации. beforeEnter на маршруте защищает конкретные маршруты. Хуки в компоненте (onBeforeRouteLeave, onBeforeRouteUpdate) полезны для предупреждения о несохранённых изменениях. Верните false или маршрут, чтобы отменить или перенаправить; true/undefined подтверждает. Async-хуки могут возвращать Promise. Используйте route.meta для флагов вроде requiresAuth.
<!-- router/index.js -->
const router = createRouter({ history, routes })
// global guard: runs on every navigation
router.beforeEach((to, from) => {
if (to.meta.requiresAuth && !isAuthenticated()) {
return '/login' // redirect
}
// return true or undefined to confirm
})
// per-route guard
{ path: '/admin', component: Admin, beforeEnter: (to, from) => {
if (!isAdmin()) return '/403'
}}
// in-component guard
<script setup>
import { onBeforeRouteLeave } from 'vue-router'
onBeforeRouteLeave((to, from) => {
if (hasUnsavedChanges()) {
return confirm('Discard changes?')
}
})
</script>Ленивая загрузка и вложенные маршруты
Вложенные маршруты рендерят дочерние компоненты внутри <RouterView> родителя. Определяйте children с путями относительно родителя. Пустой путь ('') совпадает с URL родителя точно. Динамический import() разделяет каждый маршрут на отдельный бандл. Используйте route.meta для прикрепления данных (требования авторизации, заголовки), доступных в хуках через to.meta. Группируйте связанные маршруты комментарием с именем чанка.
const routes = [
{
path: '/dashboard',
component: () => import('../views/Dashboard.vue'),
children: [
{ path: '', component: () => import('../views/Overview.vue') },
{ path: 'stats', component: () => import('../views/Stats.vue') },
{ path: 'settings', component: () => import('../views/Settings.vue') }
]
},
// group routes into one chunk
{
path: '/admin',
component: () => import(/* webpackChunkName: "admin" */ '../views/Admin.vue'),
meta: { requiresAuth: true, role: 'admin' }
}
]Управление состоянием (Pinia)
Определение store
Pinia — официальное управление состоян ием Vue (преемник Vuex). defineStore с setup-функцией даёт синтаксис Composition API: ref/computed — состояние и getters, возвращаемые функции — actions. Первый аргумент — уникальный id store. Setup-хранилища гибки (внутри можно использовать любой composable). Альтернативно используйте синтаксис Options (объект state/getters/actions) для более Vuex-подобного ощущения.
<!-- stores/counter.js -->
import { defineStore } from 'pinia'
// setup syntax (composition API style)
export const useCounterStore = defineStore('counter', () => {
const count = ref(0)
const double = computed(() => count.value * 2)
function increment() {
count.value++
}
function asyncIncrement() {
setTimeout(() => count.value++, 1000)
}
return { count, double, increment, asyncIncrement }
})Использование store
Вызывайте useStore() внутри setup для доступа к store. Для реактивной деструктуризации используйте storeToRefs() (как toRefs, но пропускает actions). Actions можно деструктурировать напрямую — они привязаны к store. Pinia разрешает прямые мутации (counter.count = 5) и $patch для пакетных обновлений. Stores — синглтоны: один экземпляр во всех компонентах. Устанавливайте Pinia через app.use(createPinia()).
<script setup>
import { useCounterStore } from '../stores/counter'
import { storeToRefs } from 'pinia'
const counter = useCounterStore()
// state and getters lose reactivity if destructured directly
// use storeToRefs to preserve it
const { count, double } = storeToRefs(counter)
// actions can be destructured directly (they're functions)
const { increment } = counter
// mutate state directly (Pinia allows it, unlike Vuex)
counter.count = 5
counter.$patch({ count: 10 })
counter.$patch(state => { state.count++ })
</script>
<template>
<p>{{ count }} x 2 = {{ double }}</p>
<button @click="increment">+</button>
</template>Getters и композиция store
Getters — вычисляемые значения, производные от состояния. Чтобы использовать другой store внутри одного, просто вызовите его useStore() — Pinia обработает зависимость. Это делает композицию store тривиальной (в отличие от модулей Vuex). Getters могут ссылаться на другие getters. Для асинхронных операций просто пишите async-функции в store — никакого специального контекста 'actions', как в Vuex.
<!-- stores/cart.js -->
import { defineStore } from 'pinia'
import { useUserStore } from './user'
export const useCartStore = defineStore('cart', () => {
const items = ref([])
// getter (computed)
const total = computed(() =>
items.value.reduce((sum, i) => sum + i.price * i.qty, 0)
)
const itemCount = computed(() =>
items.value.reduce((n, i) => n + i.qty, 0)
)
// compose other stores
const userStore = useUserStore()
const canCheckout = computed(() =>
userStore.isLoggedIn && items.value.length > 0
)
function addItem(item) {
items.value.push(item)
}
return { items, total, itemCount, canCheckout, addItem }
})Подписки и персистентность
$subscribe срабатывает на любое изменение состояния (с информацией о мутации и новом состоянии). Используйте для персистентности (localStorage, sessionStorage) или синхронизации с внешними системами. $onAction подключается к вызовам actions — полезно для логирования, аналитики и измерения длительности actions. Колбэки after/onError позволяют реагировать на завершение или сбой action. Очистка происходит автоматически при размонтировании компонента.
<script setup>
import { useCartStore } from '../stores/cart'
const cart = useCartStore()
// subscribe to any state change
cart.$subscribe((mutation, state) => {
console.log('cart changed', mutation.type, state)
// persist to localStorage
localStorage.setItem('cart', JSON.stringify(state.items))
})
// subscribe to actions
cart.$onAction(({ name, after, onError }) => {
console.log('action started:', name)
after(result => console.log('action done:', name, result))
onError(err => console.error('action failed:', name, err))
})
</script>Сброс и модули store
У stores с синтаксисом Options есть встроенный $reset(); у setup-хранилищ его нет — реализуйте reset() вручную, переприсваивая каждый ref. Pinia модульна по дизайну: каждый store независим, без вложенных модулей, как в Vuex. Композиция store — вызов useOtherStore() внутри одного. Устанавливайте Pinia глобально через createPinia(). Stores tree-shakable, с отличной поддержкой TypeScript и интеграцией с devtools.
<!-- stores/user.js -->
import { defineStore } from 'pinia'
export const useUserStore = defineStore('user', () => {
const name = ref('')
const isLoggedIn = ref(false)
function login(n) { name.value = n; isLoggedIn.value = true }
function logout() { name.value = ''; isLoggedIn.value = false }
// Pinia setup stores don't have a built-in $reset
// implement it manually
function reset() {
name.value = ''
isLoggedIn.value = false
}
return { name, isLoggedIn, login, logout, reset }
})
<!-- main.js -->
import { createPinia } from 'pinia'
const pinia = createPinia()
app.use(pinia)Переходы и анимация
Компонент Transition
Оборачивайте элемент с v-if/v-show в <Transition>, чтобы анимировать появление и исчезновение. Vue добавляет 6 классов в нужные моменты: *-enter-from (начальное состояние), *-enter-active (во время перехода), *-enter-to (конечное состояние) и *-leave-*. Определяйте CSS-переходы и анимации на этих классах. Проп name заменяет префикс 'v-'. Допускается только один дочерний элемент; для списков используйте TransitionGroup.
<template>
<Transition name="fade">
<p v-if="show">Hello</p>
</Transition>
</template>
<style>
/* 6 classes: {name}-enter-{from,active,to}, {name}-leave-{...} */
.fade-enter-active, .fade-leave-active {
transition: opacity 0.3s ease;
}
.fade-enter-from, .fade-leave-to {
opacity: 0;
}
</style>Режимы и хуки Transition
mode='out-in' полностью анимирует уход уходящего элемента до старта входящего — идеально для подмены компонентов (вкладок) без наложения. mode='in-out' используется редко. JavaScript-хуки (@before-enter, @enter, @leave) позволяют управлять анимациями библиотеками вроде GSAP. Установите :css='false', чтобы Vue пропустил определение CSS и полагался только на JS-хуки (небольшой выигрыш производительности).
<template>
<!-- 'out-in': current leaves, then new enters -->
<Transition mode="out-in" name="fade">
<component :is="currentTab" />
</Transition>
<!-- JavaScript hooks for GSAP/anime.js -->
<Transition
@before-enter="beforeEnter"
@enter="enter"
@leave="leave"
:css="false"
>
<div v-if="show">Animated</div>
</Transition>
</template>TransitionGroup для списков
TransitionGroup анимирует списки v-for с тремя поведениями: enter (новый элемент), leave (удалённый элемент) и move (существующий элемент меняет позицию). Класс *-move анимирует технику FLIP: Vue вычисляет дельты позиций и применяет transform-переход. Установите position: absolute на leave-active, чтобы уходящий элемент вышел из потока и соседи плавно сдвинулись на его место.
<template>
<TransitionGroup name="list" tag="ul">
<li v-for="item in items" :key="item.id">{{ item.text }}</li>
</TransitionGroup>
</template>
<style>
.list-enter-active, .list-leave-active { transition: all 0.5s; }
.list-enter-from, .list-leave-to { opacity: 0; transform: translateX(30px); }
/* the magic class for reordering */
.list-leave-active { position: absolute; }
.list-move { transition: transform 0.5s ease; }
</style>Анимация состояния с обёрткой <Transition>
Можно переопределить классы Vue по умолчанию своими: enter-active-class и leave-active-class. Это позволяет подключить существующие системы анимации (Animate.css, утилиты анимации Tailwind, свои keyframes). Паттерн: определите анимацию на классе, направьте на него transition Vue. Это связывает жизненный цикл Vue с любым CSS-фреймворком анимации.
<template>
<button @click="show = !show">Toggle</button>
<Transition
enter-active-class="animate__animated animate__fadeIn"
leave-active-class="animate__animated animate__fadeOut"
>
<div v-if="show" class="box">Content</div>
</Transition>
</template>
<!-- combine with third-party animation libraries -->
<!-- Animate.css, Tailwind animations, custom keyframes -->Suspense для async
Suspense координирует async setup: когда дочерний компонент использует await верхнего уровня, он приостанавливается, и Suspense показывает #fallback. Когда все асинхронные дети разрешатся, рендерится слот по умолчанию. Это элегантно для компонентов, загружающих данные. Учтите: Suspense всё ещё экспериментален в Vue 3 — обработка ошибок требует onErrorCaptured. В продакшене большинство команд пока использует composables и состояние загрузки.
<template>
<Suspense>
<template #default>
<AsyncComponent />
</template>
<template #fallback>
<div>Loading...</div>
</template>
</Suspense>
</template>
<!-- AsyncComponent uses top-level await -->
<script setup>
import { ref } from 'vue'
const data = ref(null)
// top-level await suspends the component
const res = await fetch('/api/data').then(r => r.json())
data.value = res
</script>Teleport и Suspense
Основы Teleport
Teleport рендерит контент в DOM-элемент в другом месте документа (часто на уровне body), но компонент сохран яет реактивный контекст родителя, пропсы, emits и т. д. Это решает проблемы z-index и overflow у модалок, подсказок и выпадающих списков, которые обрезались бы родительским overflow:hidden или контекстами наложения. Селектор 'to' указывает целевой элемент.
<!-- Modal.vue -->
<template>
<!-- the rendered content is moved to #modals in the DOM,
but keeps the component's reactive context -->
<Teleport to="#modals">
<div class="modal">
<h2>{{ title }}</h2>
<slot />
<button @click="$emit('close')">Close</button>
</div>
</Teleport>
</template>
<!-- index.html must have -->
<!-- <div id="app"></div> -->
<!-- <div id="modals"></div> -->Условный Teleport
Проп disabled позволяет условно применять teleport: когда true, контент рендерится на месте (без телепортации). Это полезно, когда один компонент используется в разных контекстах (например, подсказка, которую нужно телепортировать в обычной раскладке, но вставить inline внутри другой модалки). Несколько Teleport в один элемент добавляются в порядке рендера. Teleport работает с v-if внутри.
<template>
<!-- disabled: render in place (not teleported) -->
<Teleport :to="target" :disabled="inline">
<div class="popup" v-if="show">...</div>
</Teleport>
</template>
<script setup>
const props = defineProps({
inline: Boolean // if true, render inline instead of teleporting
})
const target = '#popups'
</script>
<!-- Multiple Teleports to same target: appended in order -->Teleport для модалок и уведомлений
Teleport в body — стандартный паттерн для модалок: модалка уходит от огр аничений overflow, transform и z-index родителей. Комбинируйте с Transition для анимации появления и исчезновения. @click.self на подложке закрывает при клике снаружи (но не по контенту). Слоты позволяют родителю полностью настроить header, body и footer модалки, пока компонент модалки отвечает за позиционирование и анимацию.
<!-- components/Modal.vue -->
<template>
<Teleport to="body">
<Transition name="modal">
<div v-if="show" class="modal-backdrop" @click.self="$emit('close')">
<div class="modal-content">
<header><slot name="header" /></header>
<slot />
<footer><slot name="footer" /></footer>
</div>
</div>
</Transition>
</Teleport>
</template>Suspense с async setup
Когда setup дочернего компонента использует await верхнего уровня, он возвращает Promise. Suspense перехватывает его и показывает #fallback до разрешения. Затем результат setup приостановленного компонента используется для рендеринга. Несколько асинхронных детей координируются — Suspense ждёт всех. onErrorCaptured ловит ошибки setup. Suspense всё ещё экспериментален, поэтому в продакшене предпочитайте ручное состояние загрузки в composables.
<!-- Parent.vue -->
<template>
<Suspense>
<AsyncProfile :id="userId" />
<template #fallback>
<Spinner />
</template>
</Suspense>
</template>
<!-- AsyncProfile.vue -->
<script setup>
const props = defineProps(['id'])
// top-level await suspends this component
const profile = await fetch(`/api/users/${props.id}`).then(r => r.json())
// component only renders after this resolves
</script>Вложенный Suspense и асинхронные компоненты
Suspense можно вкладывать — каждый уровень обрабатывает свою асинхронную границу. Внешний Suspense показывает PageSkeleton, пока загружается Dashboard (и всё, что ему нужно); внутренний показывает ChartSkeleton конкретно для графика. Гранулярная загрузка улучшает UX: сначала появляется каркас страницы, затем заполняются отдельные секции. Помните, что Suspense экспериментален — тестируйте тщательно и обрабатывайте ошибки через onErrorCaptured.
<template>
<Suspense>
<template #default>
<Dashboard>
<Suspense>
<template #default>
<AsyncChart :data="data" />
</template>
<template #fallback>
<ChartSkeleton />
</template>
</Suspense>
</Dashboard>
</template>
<template #fallback>
<PageSkeleton />
</template>
</Suspense>
</template>Provide / Inject
Основы provide и inject
provide() делает значение доступным всем дочерним компонентам; inject() получает его в любом месте дерева ниже. Это избегает пробрасывания пропсов для глубоко вложенных компонентов. Второй аргумент inject — значение по умолчанию (если ничего не предоставлено). Предоставленные refs реактивны — потомки могут их мутиров ать, и родитель увидит изменения. Используйте ключи Symbol, чтобы избежать коллизий в больших приложениях.
<!-- Parent.vue -->
<script setup>
import { provide, ref } from 'vue'
const theme = ref('dark')
const user = ref({ name: 'Alice' })
// provide to all descendants
provide('theme', theme)
provide('user', user)
</script>
<!-- DeepChild.vue (any level of nesting) -->
<script setup>
import { inject } from 'vue'
const theme = inject('theme', 'light') // default 'light'
const user = inject('user')
// these are reactive refs, just like in the parent
</script>Read-only предоставленное состояние
Используйте readonly(), чтобы отдать состояние без прямых мутаций: потомки должны вызывать предоставленные методы-действия для изменения. Этот паттерн (приватный мутируемый ref + публичное read-only представление + методы-действия) — лёгкая альтернатива Pinia для состояния в пределах дерева компонентов. Он обеспечивает однонаправленный поток данных и предотвращает баги от случайных мутаций глубоко в дереве.
<!-- store.js (shared composable) -->
import { ref, readonly } from 'vue'
const _count = ref(0) // private mutable state
export function useCountStore() {
return {
count: readonly(_count), // consumers can't mutate
increment: () => _count.value++ // only via action
}
}
<!-- Provider.vue -->
<script setup>
import { provide } from 'vue'
import { useCountStore } from './store'
const store = useCountStore()
provide('countStore', store)
</script>Типизированные ключи injection
Используйте InjectionKey<Ref<Type>>, чтобы создать типизированный ключ-symbol. Это даёт полный вывод типов TypeScript: inject знает возвращаемый тип. Ключи Symbol избегают коллизий строк, когда несколько библиотек предоставляют значения. Для синглтонов на всё приложение предпочитайте Pinia вместо provide/inject: у Pinia есть devtools, персистентность и лучшая тестируемость. Используйте provide/inject для контекста в пределах дерева компонентов (тема, форма, локаль).
<!-- keys.ts -->
import type { InjectionKey, Ref } from 'vue'
import { inject, provide } from 'vue'
export const ThemeKey: InjectionKey<Ref<string>> = Symbol('theme')
<!-- Provider.vue -->
<script setup>
import { ref } from 'vue'
import { ThemeKey } from './keys'
const theme = ref('dark')
provide(ThemeKey, theme)
</script>
<!-- Consumer.vue -->
<script setup>
import { inject } from 'vue'
import { ThemeKey } from './keys'
// TS knows theme is Ref<string> | undefined
const theme = inject(ThemeKey)
// with default
const theme2 = inject(ThemeKey, ref('light'))
</script>Обновление предоставленных значений
Рекомендуемый паттерн: предоставить объект, содержащий реактивное состояние И методы его изменения. Это делает API явным и предотвращает случайные мутации. Дети деструктурируют состояние и действия. По сути это мини-store: для чего-то большего, чем несколько значений, рассмотрите composable, возвращающий ту же форму, или Pinia. Предоставленное значение реактивно, потому что содержит ref.
<!-- Provider.vue -->
<script setup>
import { ref, provide } from 'vue'
const count = ref(0)
// expose value + mutator together
provide('counter', {
count, // reactive ref
increment: () => count.value++,
reset: () => count.value = 0
})
</script>
<!-- DeepChild.vue -->
<script setup>
import { inject } from 'vue'
const { count, increment, reset } = inject('counter')
// count is reactive, increment/reset are actions
</script>
<template>
<p>{{ count }}</p>
<button @click="increment">+</button>
<button @click="reset">Reset</button>
</template>Provide на уровне приложения
app.provide() делает значение доступным каждому компоненту приложения — полезно для констант приложения (URL API, фича-флаги, конфигурация окружения). В отличие от provide на уровне компонента, это по умолчанию не реактивно (если не предоставить ref). Это хороший способ внедрить конфигурацию, зависящую от окружения, не импортируя env-файлы повсюду. Комбинируйте с inject() в любом компоненте для доступа к этим глобальным значениям.
<!-- main.js -->
import { createApp } from 'vue'
import App from './App.vue'
const app = createApp(App)
// app-level provide — available to ALL components
app.provide('apiUrl', 'https://api.example.com')
app.provide('apiKey', import.meta.env.VITE_API_KEY)
// useful for app-wide constants
app.provide('features', {
darkMode: true,
beta: false
})
app.mount('#app')Связанные сниппеты Vue 3
Copy-paste ready code for common tasks.
Single-File Component
Define a Vue 3 component with script setup, template, and scoped styles.
Composition API
Organize reactive state, computed, and lifecycle logic by feature.
Refs & Reactive
Choose between ref and reactive for reactive state.
Computed & Watch
Derive values with computed and react to changes with watch.
Props & Emits
Declare inputs and events, and implement v-model on a component.
Lifecycle Hooks
Register lifecycle callbacks as composable functions.
Slots & Scoped Slots
Distribute content with default, named, and scoped slots.
Composables
Extract reusable reactive logic into a useMouse composable.
Was this helpful?