Vue 3 速查表,Composition API、响应式、组件、指令、Pinia,附 Options API 对照

import { ref } from 'vue';
const count = ref(0);
// inside <script setup> the template auto-unwraps:  {{ count }}
// in JS code you must use .value :
count.value++;
console.log(count.value);  // 1

import { reactive } from 'vue';
const state = reactive({ user: { name: 'Lei', age: 30 }, tags: ['vue'] });
state.user.age = 31;     // tracked
state.tags.push('web');  // tracked (arrays too)

import { ref, computed } from 'vue';
const price = ref(100);
const qty = ref(3);
const total = computed(() => price.value * qty.value);
// writable computed
const fullName = computed({
  get: () => first.value + ' ' + last.value,
  set: (v: string) => { [first.value, last.value] = v.split(' '); }
});

import { ref, watch } from 'vue';
const id = ref(1);

watch(id, (newId, oldId, onCleanup) => {
  const ctrl = new AbortController();
  fetch(`/api/user/${newId}`, { signal: ctrl.signal }).then(/*…*/);
  onCleanup(() => ctrl.abort());  // cancel stale request
});

// watch multiple sources
watch([first, last], ([f, l]) => console.log(f, l));

// deep watch on a reactive object
watch(() => state.user, (u) => console.log(u), { deep: true });

import { ref, watchEffect } from 'vue';
const url = ref('/api/me');
watchEffect(() => {
  // any ref read inside is tracked automatically
  fetch(url.value).then(/*…*/);
});
// stop manually if you need to
const stop = watchEffect(() => console.log(count.value));
stop();

import { shallowRef, triggerRef } from 'vue';
const big = shallowRef({ items: largeArray });

// replacing .value still triggers
big.value = { items: newArray };

// mutating nested fields does NOT trigger
big.value.items.push(1);  // no re-render
triggerRef(big);           // force update

import { shallowReactive } from 'vue';
const state = shallowReactive({
  user: { name: 'Lei' },   // user object itself is NOT reactive
  count: 0                 // count IS reactive (top-level primitive)
});
state.count++;             // tracked
state.user.name = 'Hong';  // NOT tracked
state.user = { name: 'Hong' };  // tracked — replacing the property is top-level

import { reactive, readonly } from 'vue';
const original = reactive({ count: 0 });
const copy = readonly(original);

original.count++;        // works, copy.count also updates
copy.count++;            // warns in dev, no-op
// pass readonly to children that should not mutate parent state
provide('config', readonly(original));

import { reactive, toRefs } from 'vue';
const state = reactive({ x: 1, y: 2 });

// WRONG — destructuring breaks reactivity
const { x, y } = state;

// RIGHT — each becomes a ref pointing into the proxy
const { x: xRef, y: yRef } = toRefs(state);
xRef.value++;            // state.x is also 2
// useful when returning from a composable:
function useMouse() {
  const pos = reactive({ x: 0, y: 0 });
  return toRefs(pos);    // caller can destructure
}

import { reactive, toRef } from 'vue';
const state = reactive({ count: 0 });
const countRef = toRef(state, 'count');
countRef.value++;        // state.count is also 1

// 3.3+ getter-based form
const upper = toRef(() => state.name.toUpperCase());

import { isRef, unref, ref } from 'vue';
function useDouble(x: number | Ref<number>) {
  // unref returns x if it is a ref, else x itself
  return computed(() => unref(x) * 2);
}
const a = ref(10);
isRef(a);     // true
unref(a);     // 10
unref(99);    // 99

import { customRef } from 'vue';
function useDebouncedRef<T>(value: T, delay = 300) {
  let timer: number;
  return customRef<T>((track, trigger) => ({
    get() { track(); return value; },
    set(newValue) {
      clearTimeout(timer);
      timer = setTimeout(() => { value = newValue; trigger(); }, delay);
    }
  }));
}
const text = useDebouncedRef('', 500);

import { ref, reactive, watch } from 'vue';
const r = ref(0);
const state = reactive({ n: 0 });

// ref source — pass the ref itself
watch(r, (val) => console.log(val));

// getter source — pass () => expression
watch(() => state.n, (val) => console.log(val));

// getter returning multiple values needs an array source or object
watch(() => ({ ...state }), (snap) => console.log(snap));

import { ref, watch, nextTick } from 'vue';
const list = ref<number[]>([]);

// default flush: 'pre' — runs BEFORE the component re-renders
watch(list, () => { /* DOM still old here */ });

// flush: 'post' — runs AFTER the DOM is updated (read updated DOM)
watch(list, () => { measureRenderedList(); }, { flush: 'post' });

// flush: 'sync' — runs synchronously on every change (use sparingly)
watch(list, () => { /* fires immediately, no batching */ }, { flush: 'sync' });

import { effectScope, ref, watch, watchEffect } from 'vue';

const scope = effectScope();
scope.run(() => {
  const count = ref(0);
  watch(count, () => { /* … */ });
  watchEffect(() => { /* … */ });
});

// dispose every effect created inside the scope at once
scope.stop();

import { markRaw, reactive } from 'vue';
import { Chart } from 'chart.js';

const state = reactive({
  // a third-party instance you never want proxied
  chart: markRaw(new Chart(/* … */)),
  config: { theme: 'dark' },
});
// state.chart stays the raw instance, methods like .update() keep working

import { reactive, toRaw } from 'vue';
const state = reactive({ list: [1, 2, 3] });

const raw = toRaw(state);
// raw is the plain non-reactive object — mutating it does NOT trigger updates
console.log(raw === state);  // false (state is a Proxy)

// common use: pass a clean object to a structuredClone / JSON / worker
const snapshot = structuredClone(toRaw(state));

import { ref, computed } from 'vue';
const count = ref(2);

// the getter receives the previous computed result
const clamped = computed((prev) => {
  if (count.value <= 3) return count.value;
  // keep the last valid value when out of range
  return prev as number;
});

import { reactive, readonly, isReactive, isReadonly, isProxy } from 'vue';
const r = reactive({ x: 1 });
const ro = readonly(r);

isReactive(r);     // true
isReadonly(ro);    // true
isReactive(ro);    // true (readonly of a reactive is still reactive)
isProxy(r);        // true
isProxy({});       // false

import { shallowRef, triggerRef } from 'vue';
const state = shallowRef({ count: 0 });

// nested mutation does NOT auto-trigger on a shallowRef
state.value.count++;
triggerRef(state);   // force dependents to re-run now

import { watchPostEffect, watchSyncEffect } from 'vue';

// shorthand for watchEffect(fn, { flush: 'post' })
watchPostEffect(() => {
  // runs AFTER DOM update — read measured layout safely
});

// shorthand for watchEffect(fn, { flush: 'sync' })
watchSyncEffect(() => {
  // runs synchronously on each dependency change
});

import { onMounted, ref } from 'vue';
const elRef = ref<HTMLDivElement | null>(null);

onMounted(() => {
  // DOM is ready, refs are attached
  console.log(elRef.value?.offsetHeight);
  const obs = new ResizeObserver(/*…*/);
  obs.observe(elRef.value!);
});

import { onUpdated, ref } from 'vue';
const listRef = ref<HTMLUListElement | null>(null);

onUpdated(() => {
  // runs after EVERY update — keep it cheap
  listRef.value?.scrollTo({ top: listRef.value.scrollHeight });
});

import { onMounted, onUnmounted } from 'vue';
onMounted(() => {
  const id = setInterval(tick, 1000);
  onUnmounted(() => clearInterval(id));   // colocated cleanup
});

// or pair with the listener
const onResize = () => { /* … */ };
onMounted(() => window.addEventListener('resize', onResize));
onUnmounted(() => window.removeEventListener('resize', onResize));

import { onBeforeMount } from 'vue';
onBeforeMount(() => {
  // reactive state is ready, but DOM is NOT yet rendered
  // refs are still null — DO NOT read them here
  console.log('about to mount');
});

import { onBeforeUpdate, ref } from 'vue';
const listRef = ref<HTMLUListElement | null>(null);
let prevScroll = 0;

onBeforeUpdate(() => {
  // DOM is still pre-update — measure the old state
  prevScroll = listRef.value?.scrollTop ?? 0;
});

import { onBeforeUnmount } from 'vue';
onBeforeUnmount(() => {
  // DOM and reactive state are still alive
  // send the draft, save scroll position, etc.
  saveDraftToServer();
});

import { onErrorCaptured, ref } from 'vue';
const errorMsg = ref<string | null>(null);

onErrorCaptured((err, instance, info) => {
  errorMsg.value = err.message;
  console.error('caught from child:', info);
  return false;   // stop propagation; return true / undef to bubble
});

import { onActivated, onDeactivated } from 'vue';

onActivated(() => {
  // entered from a kept-alive cache — refresh data, resume timers
  refreshList();
});
onDeactivated(() => {
  // cached, not destroyed — pause work, save scroll
  pausePolling();
});

import { ref, nextTick } from 'vue';
const show = ref(false);
const inputRef = ref<HTMLInputElement | null>(null);

async function reveal() {
  show.value = true;
  // DOM has NOT updated yet on this line
  await nextTick();
  // now the v-if element exists — safe to focus
  inputRef.value?.focus();
}

import { ref, onServerPrefetch } from 'vue';
const data = ref<User | null>(null);

onServerPrefetch(async () => {
  // runs on the server before HTML is serialized
  data.value = await fetchUser();
});

// on the client, fetch in onMounted instead if data is empty

import { onRenderTracked, onRenderTriggered } from 'vue';

// which deps the render tracked (fires on first render + updates)
onRenderTracked((e) => {
  console.log('tracked', e.type, e.key);
});

// which dep change caused THIS re-render
onRenderTriggered((e) => {
  console.log('triggered by', e.type, e.key, e.target);
});

import { defineComponent } from 'vue';

export default defineComponent({
  name: 'UserCard',
  props: { id: { type: Number, required: true } },
  setup(props) {
    // props.id is typed as number
    return { /* … */ };
  }
});

<script setup lang="ts">
// runtime declaration
const props = defineProps({
  id: { type: Number, required: true },
  tags: { type: Array as PropType<string[]>, default: () => [] }
});

// TS type-only declaration (3.3+: supports external types)
const props = defineProps<{
  id: number;
  tags?: string[];
}>();

// 3.3+: with defaults via destructure
const { id, tags = [] } = defineProps<{ id: number; tags?: string[] }>();
</script>

<script setup lang="ts">
// type-only — recommended
const emit = defineEmits<{
  (e: 'select', id: number): void;
  (e: 'close'): void;
}>();

// 3.3+: object syntax (shorter)
const emit = defineEmits<{
  select: [id: number];
  close: [];
}>();

emit('select', 42);
</script>

<!-- Child.vue -->
<script setup lang="ts">
const open = () => { /* … */ };
defineExpose({ open });   // parent can call childRef.value?.open()
</script>

<!-- Parent.vue -->
<script setup lang="ts">
import Child from './Child.vue';
const childRef = ref<InstanceType<typeof Child> | null>(null);
const handleClick = () => childRef.value?.open();
</script>
<template><Child ref="childRef" /></template>

<!-- Child.vue (3.4+) -->
<script setup lang="ts">
const model = defineModel<string>();           // v-model default
const title = defineModel<string>('title');    // v-model:title
const search = defineModel<string>('search', { required: true });
</script>
<template>
  <input v-model="model" />
</template>

<!-- Parent.vue -->
<Child v-model="text" v-model:title="t" />

<script setup lang="ts">
defineOptions({
  name: 'UserCard',          // for DevTools + recursion
  inheritAttrs: false,       // don't auto-bind $attrs to root
});
</script>

<script setup lang="ts">
defineSlots<{
  default(props: { item: User }): any;
  header?(props: { count: number }): any;
}>();
</script>
<template>
  <header><slot name="header" :count="items.length" /></header>
  <slot v-for="i in items" :item="i" :key="i.id" />
</template>

<script setup lang="ts">
interface Props { size?: 'sm' | 'md' | 'lg'; tags?: string[]; }
const props = withDefaults(defineProps<Props>(), {
  size: 'md',
  tags: () => []     // object/array defaults MUST be functions
});
</script>

import { defineAsyncComponent } from 'vue';

const HeavyChart = defineAsyncComponent(() => import('./HeavyChart.vue'));

// with loading / error UI
const Editor = defineAsyncComponent({
  loader: () => import('./Editor.vue'),
  loadingComponent: Spinner,
  errorComponent: ErrorBox,
  delay: 200,
  timeout: 10_000
});

<template>
  <Suspense>
    <template #default>
      <!-- component whose setup() is async -->
      <UserProfile :id="userId" />
    </template>
    <template #fallback>
      <div>Loading…</div>
    </template>
  </Suspense>
</template>

<!-- UserProfile.vue -->
<script setup lang="ts">
const user = await fetch('/api/me').then(r => r.json());
</script>

<template>
  <KeepAlive :include="['UserList', 'UserDetail']" :max="10">
    <component :is="currentTab" />
  </KeepAlive>
</template>

<template>
  <button @click="open = true">Open</button>
  <Teleport to="body">
    <div v-if="open" class="modal-overlay">
      <div class="modal">Dialog content</div>
    </div>
  </Teleport>
</template>

<!-- conditionally disable to render in place -->
<Teleport to="#drawer" :disabled="isMobile">…</Teleport>

<template>
  <Transition name="fade">
    <p v-if="show">hello</p>
  </Transition>
</template>

<style>
.fade-enter-active, .fade-leave-active { transition: opacity .3s ease; }
.fade-enter-from, .fade-leave-to { opacity: 0; }
</style>

<template>
  <TransitionGroup name="list" tag="ul">
    <li v-for="item in items" :key="item.id">{{ item.text }}</li>
  </TransitionGroup>
</template>

<style>
.list-enter-from, .list-leave-to { opacity: 0; transform: translateY(8px); }
.list-enter-active, .list-leave-active { transition: all .3s ease; }
.list-move { transition: transform .3s ease; }  /* smooth reorder */
</style>

<script setup lang="ts">
import Foo from './Foo.vue';
import Bar from './Bar.vue';
import { shallowRef } from 'vue';
const current = shallowRef(Foo);   // shallowRef, not ref
</script>
<template>
  <component :is="current" :some-prop="x" @evt="onEvt" />
  <!-- :is also accepts a registered name string or an HTML tag -->
  <component :is="ok ? 'a' : 'span'">link</component>
</template>

<!-- TreeNode.vue -->
<script setup lang="ts">
defineProps<{ node: { label: string; children?: any[] } }>();
defineOptions({ name: 'TreeNode' });   // name enables self-reference
</script>
<template>
  <li>
    {{ node.label }}
    <ul v-if="node.children?.length">
      <TreeNode v-for="c in node.children" :key="c.id" :node="c" />
    </ul>
  </li>
</template>

// global — available in every template, but always in the bundle
import { createApp } from 'vue';
import BaseButton from './BaseButton.vue';
const app = createApp(App);
app.component('BaseButton', BaseButton);

// local — import where used, tree-shakeable (preferred)
<script setup>
import BaseButton from './BaseButton.vue';  // just use it in template
</script>

<!-- Child with a single root: attrs auto-apply to it -->
<template>
  <button class="btn"><slot /></button>
  <!-- parent's class / @click / id land on this button automatically -->
</template>

<!-- multi-root or custom target: bind $attrs yourself -->
<script setup>
defineOptions({ inheritAttrs: false });
</script>
<template>
  <label>{{ label }}</label>
  <input v-bind="$attrs" />
</template>

import { createApp } from 'vue';
const app = createApp(App);

// add a property available on every component instance
app.config.globalProperties.$formatDate = (d: Date) =>
  d.toLocaleDateString();

// TS augmentation so $formatDate is typed in templates
declare module 'vue' {
  interface ComponentCustomProperties {
    $formatDate: (d: Date) => string;
  }
}

import { createApp } from 'vue';
const app = createApp(App);

// available to EVERY component, no provider component needed
app.provide('apiBase', 'https://api.example.com');

// any component, any depth
<script setup>
import { inject } from 'vue';
const apiBase = inject<string>('apiBase');
</script>

<div v-if="status === 'loading'">Loading…</div>
<div v-else-if="error">{{ error.message }}</div>
<div v-else>Hello {{ user.name }}</div>

<!-- group multiple elements with <template> -->
<template v-if="ready">
  <h1>Title</h1>
  <p>Body</p>
</template>

<div v-show="open">always rendered, just hidden when false</div>

<li v-for="(item, idx) in items" :key="item.id">
  {{ idx + 1 }}. {{ item.name }}
</li>

<!-- iterate object -->
<li v-for="(val, key) in obj" :key="key">{{ key }}: {{ val }}</li>

<!-- range -->
<span v-for="n in 5" :key="n">{{ n }}</span>

<input v-model="text" />
<input type="checkbox" v-model="agreed" />
<input type="checkbox" v-model="selected" value="a" />
<select v-model="picked"><option>x</option><option>y</option></select>

<!-- modifiers -->
<input v-model.lazy="text" />     <!-- sync on change instead of input -->
<input v-model.number="age" />    <!-- cast to number -->
<input v-model.trim="title" />    <!-- trim whitespace -->

<img v-bind:src="url" :alt="alt" />     <!-- : is shorthand -->

<!-- bind an object — spreads keys -->
<div v-bind="{ id, class: cls, 'data-x': 1 }"></div>

<!-- bind class / style -->
<div :class="['btn', { active: isActive }, sizeCls]"></div>
<div :style="{ color, fontSize: size + 'px' }"></div>

<button v-on:click="handle">go</button>
<button @click="handle">go</button>    <!-- @ shorthand -->

<button @click="count++">inline</button>
<button @click="handle($event, item)">with extra arg</button>

<!-- modifiers -->
<form @submit.prevent="save"></form>          <!-- preventDefault -->
<button @click.stop="x"></button>             <!-- stopPropagation -->
<input @keyup.enter="submit" />               <!-- keycode shortcut -->
<input @keyup.ctrl.s.prevent="save" />        <!-- chord + prevent -->
<div @click.self="closeModal"></div>          <!-- only when target === self -->
<div @click.once="trackOnce"></div>           <!-- fire once -->

<div v-html="trustedHtml"></div>

<!-- NEVER do this with user input — XSS -->
<div v-html="userBio"></div>   <!-- DANGEROUS -->

<span v-text="msg"></span>
<!-- equivalent to -->
<span>{{ msg }}</span>

<style>[v-cloak] { display: none; }</style>

<div v-cloak>
  {{ message }}
</div>

<span v-pre>{{ this will appear literally }}</span>

<h1 v-once>{{ title }}</h1>
<!-- title can change later — this element will not update -->

// directives/clickOutside.ts
import type { Directive } from 'vue';
export const vClickOutside: Directive<HTMLElement, () => void> = {
  mounted(el, binding) {
    el._click = (e: Event) => {
      if (!el.contains(e.target as Node)) binding.value();
    };
    document.addEventListener('click', el._click);
  },
  unmounted(el) { document.removeEventListener('click', el._click); }
};

// in component
<script setup>
import { vClickOutside } from './directives/clickOutside';
</script>
<template>
  <div v-click-outside="close">…</div>
</template>

<!-- multiple bindings + custom modifier -->
<UserForm
  v-model:first-name="first"
  v-model:last-name.capitalize="last"
/>

<!-- Child reads the modifier (3.4+ defineModel) -->
<script setup lang="ts">
const [last, lastMods] = defineModel<string>('lastName');
function onInput(v: string) {
  last.value = lastMods.capitalize ? v[0].toUpperCase() + v.slice(1) : v;
}
</script>

<!-- only re-renders this row when item.id or item.active changes -->
<div
  v-for="item in list"
  :key="item.id"
  v-memo="[item.id, item.active]"
>
  <!-- expensive cell content -->
  <HeavyCell :item="item" />
</div>

// v-tooltip:top.delay="text"
import type { Directive } from 'vue';
export const vTooltip: Directive<HTMLElement, string> = {
  mounted(el, binding) {
    const placement = binding.arg ?? 'bottom';   // 'top'
    const delayed = binding.modifiers.delay;      // true
    el.dataset.tip = binding.value;               // the text
    el.dataset.place = placement;
    if (delayed) el.dataset.delay = '500';
  },
  updated(el, binding) { el.dataset.tip = binding.value; },
};

<script setup>
import { ref } from 'vue';
const theme = ref('#22d3ee');
const size = ref(16);
</script>
<template><p class="label">colored</p></template>
<style scoped>
.label {
  color: v-bind(theme);
  /* wrap expressions in quotes */
  font-size: v-bind('size + "px"');
}
</style>

<!-- Map: value, key, index -->
<li v-for="(val, key, i) in myMap" :key="key">
  {{ i }}. {{ key }} = {{ val }}
</li>

<!-- Set: value only -->
<li v-for="tag in mySet" :key="tag">{{ tag }}</li>

<script setup>
const myMap = reactive(new Map([['a', 1], ['b', 2]]));
const mySet = reactive(new Set(['vue', 'web']));
</script>

<!-- Card.vue -->
<template>
  <div class="card">
    <slot>fallback when parent provides nothing</slot>
  </div>
</template>

<!-- Parent.vue -->
<Card>
  <p>arbitrary parent content lands here</p>
</Card>

<!-- Layout.vue -->
<template>
  <header><slot name="header" /></header>
  <main><slot /></main>           <!-- default slot -->
  <footer><slot name="footer" /></footer>
</template>

<!-- Parent.vue -->
<Layout>
  <template #header><h1>Title</h1></template>
  <p>main body — goes to the default slot</p>
  <template #footer><small>© 2026</small></template>
</Layout>

<!-- List.vue -->
<template>
  <ul>
    <li v-for="item in items" :key="item.id">
      <slot :item="item" :index="$index">{{ item.name }}</slot>
    </li>
  </ul>
</template>

<!-- Parent.vue -->
<List :items="users">
  <template #default="{ item, index }">
    <strong>{{ index + 1 }}.</strong> {{ item.name }} ({{ item.email }})
  </template>
</List>

<Layout>
  <template v-slot:[dynamicName]="slotProps">
    content for {{ dynamicName }}
  </template>
</Layout>

<!-- shorthand -->
<Layout>
  <template #[dynamicName]>…</template>
</Layout>

<script setup lang="ts">
import { useSlots } from 'vue';
const slots = useSlots();
</script>
<template>
  <div class="card">
    <header v-if="slots.header" class="card-head">
      <slot name="header" />
    </header>
    <slot />
    <footer v-if="$slots.footer"><slot name="footer" /></footer>
  </div>
</template>

<!-- MouseTracker.vue — owns logic, renders nothing of its own -->
<script setup lang="ts">
import { ref, onMounted, onUnmounted } from 'vue';
const x = ref(0), y = ref(0);
const move = (e: MouseEvent) => { x.value = e.clientX; y.value = e.clientY; };
onMounted(() => window.addEventListener('mousemove', move));
onUnmounted(() => window.removeEventListener('mousemove', move));
</script>
<template><slot :x="x" :y="y" /></template>

<!-- Parent owns ALL the markup -->
<MouseTracker v-slot="{ x, y }">
  <p>cursor at {{ x }}, {{ y }}</p>
</MouseTracker>

// router.ts
import { createRouter, createWebHistory } from 'vue-router';
const router = createRouter({
  history: createWebHistory(),
  routes: [
    { path: '/', component: () => import('./pages/Home.vue') },
    { path: '/about', component: () => import('./pages/About.vue') },
    { path: '/:pathMatch(.*)*', component: NotFound }   // 404
  ]
});

// main.ts
createApp(App).use(router).mount('#app');

// App.vue
<template>
  <RouterLink to="/">Home</RouterLink>
  <RouterView />
</template>

const routes = [
  { path: '/user/:id', name: 'user', component: User, props: true },
  { path: '/post/:id(\\d+)', component: Post }   // id must be digits
];

<!-- template -->
<RouterLink :to="{ name: 'user', params: { id: 42 }, query: { tab: 'bio' } }">
  Lei
</RouterLink>

<!-- inside User.vue -->
<script setup lang="ts">
import { useRoute } from 'vue-router';
const route = useRoute();
// route.params.id is reactive
</script>

const routes = [
  {
    path: '/user/:id',
    component: User,
    children: [
      { path: '', component: Overview },          // /user/42
      { path: 'posts', component: Posts },        // /user/42/posts
      { path: 'settings', component: Settings }   // /user/42/settings
    ]
  }
];

// User.vue
<template>
  <h1>{{ user.name }}</h1>
  <RouterView />     <!-- child route renders here -->
</template>

router.beforeEach(async (to, from) => {
  const auth = useAuthStore();
  if (to.meta.requiresAuth && !auth.user) {
    return { name: 'login', query: { redirect: to.fullPath } };
  }
  // return true / undefined to allow
});

// per-route
const routes = [
  { path: '/admin', component: Admin, meta: { requiresAuth: true },
    beforeEnter: (to) => { /* … */ } }
];

// in-component
<script setup>
import { onBeforeRouteLeave } from 'vue-router';
onBeforeRouteLeave((to, from) => {
  if (dirty.value && !confirm('Discard changes?')) return false;
});
</script>

<script setup>
import { useRouter } from 'vue-router';
const router = useRouter();

router.push('/about');
router.push({ name: 'user', params: { id: 42 } });
router.replace('/login');         // no history entry
router.go(-1);                    // browser back
router.back();                    // alias for go(-1)
router.forward();
</script>

<script setup lang="ts">
import { useRoute, useRouter } from 'vue-router';
import { watch } from 'vue';
const route = useRoute();

// reactive — re-runs whenever params change
watch(() => route.params.id, (id) => loadUser(id), { immediate: true });

// access query / hash / meta
console.log(route.query.tab, route.hash, route.meta.requiresAuth);
</script>

const routes = [
  // each route becomes its own chunk
  { path: '/', component: () => import('./pages/Home.vue') },
  { path: '/dashboard', component: () =>
      import(/* webpackChunkName: "admin" */ './pages/Dashboard.vue') }
];

// with Suspense for async setup
<template>
  <Suspense>
    <RouterView />
    <template #fallback><Spinner /></template>
  </Suspense>
</template>

<!-- exact match gets router-link-exact-active too -->
<RouterLink to="/users">Users</RouterLink>

<!-- custom active classes -->
<RouterLink to="/users" active-class="on" exact-active-class="on-exact">
  Users
</RouterLink>

<!-- full control with v-slot -->
<RouterLink to="/users" custom v-slot="{ href, navigate, isActive }">
  <a :href="href" :class="{ active: isActive }" @click="navigate">Users</a>
</RouterLink>

// augment the type so route.meta is typed everywhere
import 'vue-router';
declare module 'vue-router' {
  interface RouteMeta {
    requiresAuth?: boolean;
    title?: string;
    roles?: string[];
  }
}

const routes = [
  { path: '/admin', component: Admin,
    meta: { requiresAuth: true, roles: ['admin'], title: 'Admin' } },
];

// in a guard — fully typed
router.beforeEach((to) => {
  document.title = to.meta.title ?? 'App';
});

const router = createRouter({
  history: createWebHistory(),
  routes,
  scrollBehavior(to, from, savedPosition) {
    // back/forward → restore previous position
    if (savedPosition) return savedPosition;
    // anchor link → scroll to the element
    if (to.hash) return { el: to.hash, behavior: 'smooth' };
    // otherwise → top of page
    return { top: 0 };
  },
});

<script setup lang="ts">
import { onBeforeRouteUpdate } from 'vue-router';
import { ref } from 'vue';
const user = ref<User | null>(null);

// fires when navigating /user/1 → /user/2 (component is REUSED)
onBeforeRouteUpdate(async (to, from) => {
  if (to.params.id !== from.params.id) {
    user.value = await fetchUser(to.params.id as string);
  }
});
</script>

import { defineAsyncComponent } from 'vue';

const routes = [
  {
    path: '/reports',
    component: defineAsyncComponent({
      loader: () => import('./pages/Reports.vue'),
      loadingComponent: PageSpinner,
      errorComponent: ChunkLoadError,   // shown if the chunk fails
      timeout: 8000,
    }),
  },
];

// global recovery: reload once when a stale chunk 404s after deploy
router.onError((err) => {
  if (err.message.includes('Failed to fetch dynamically imported module')) {
    window.location.reload();
  }
});

import { isNavigationFailure, NavigationFailureType } from 'vue-router';

const failure = await router.push('/checkout');
if (isNavigationFailure(failure, NavigationFailureType.aborted)) {
  // a guard returned false — navigation was cancelled
  toast('Please complete the form first');
}
// other types: duplicated (same route), cancelled (newer nav started)

// main.ts
import { createPinia } from 'pinia';
createApp(App).use(createPinia()).mount('#app');

// stores/counter.ts
import { defineStore } from 'pinia';
export const useCounterStore = defineStore('counter', {
  state: () => ({ count: 0 }),
  getters: { double: (s) => s.count * 2 },
  actions: { inc() { this.count++; } }
});

// in component
<script setup>
import { useCounterStore } from '@/stores/counter';
const counter = useCounterStore();
counter.inc();
</script>

import { defineStore } from 'pinia';

export const useUserStore = defineStore('user', {
  state: () => ({ name: '', email: '', loading: false }),
  getters: {
    initials: (s) => s.name.split(' ').map(w => w[0]).join(''),
  },
  actions: {
    async load(id: number) {
      this.loading = true;
      const r = await fetch(`/api/user/${id}`).then(r => r.json());
      this.name = r.name; this.email = r.email;
      this.loading = false;
    }
  }
});

import { defineStore } from 'pinia';
import { ref, computed } from 'vue';

export const useCartStore = defineStore('cart', () => {
  // state
  const items = ref<Item[]>([]);
  // getters
  const total = computed(() => items.value.reduce((s, i) => s + i.price, 0));
  // actions
  function add(i: Item) { items.value.push(i); }
  function clear() { items.value = []; }

  return { items, total, add, clear };
});

// options form
actions: {
  async fetchPosts() {
    this.loading = true;
    try {
      this.posts = await api.posts();
    } finally {
      this.loading = false;
    }
  }
}

// setup form — call from component
const cart = useCartStore();
await cart.fetchPosts();

// $patch — batch state changes
cart.$patch({ items: [], total: 0 });
cart.$patch((s) => { s.items.push(x); s.discount = 10; });

getters: {
  // simple
  double: (s) => s.count * 2,
  // access this for other getters
  doublePlusOne(): number { return this.double + 1; },
  // parameterized getter — returns a function
  getById: (s) => (id: number) => s.users.find(u => u.id === id),
  // use another store
  totalWithTax(): number {
    const tax = useTaxStore();
    return this.total * (1 + tax.rate);
  }
}

<script setup>
import { storeToRefs } from 'pinia';
import { useUserStore } from '@/stores/user';

const userStore = useUserStore();
// WRONG — name, email become plain values, lose reactivity
const { name, email } = userStore;

// RIGHT — refs that stay reactive
const { name, email } = storeToRefs(userStore);
// actions are still destructured directly (they don't need to be refs)
const { login, logout } = userStore;
</script>

// utils/api.ts — NOT a component
import { useUserStore } from '@/stores/user';
import { pinia } from '@/main';   // exported from main.ts

export async function getCurrentUser() {
  // Pass pinia explicitly outside setup
  const store = useUserStore(pinia);
  return store.user;
}

// router guard
router.beforeEach((to) => {
  const auth = useAuthStore();    // works — app is mounted before guards run
  if (!auth.user) return '/login';
});

// options store — $reset works out of the box
const store = useCounterStore();
store.$reset();   // state back to the factory's initial values

// setup store — $reset is NOT auto-available, define it yourself
export const useCart = defineStore('cart', () => {
  const items = ref<Item[]>([]);
  function $reset() { items.value = []; }
  return { items, $reset };
});

const store = useCartStore();

// react to ANY state change
store.$subscribe((mutation, state) => {
  localStorage.setItem('cart', JSON.stringify(state));
}, { detached: true });   // survive component unmount

// observe action calls (logging, analytics, error capture)
store.$onAction(({ name, args, after, onError }) => {
  console.log('calling', name, args);
  after((result) => console.log('done', name, result));
  onError((err) => console.error(name, 'failed', err));
});

export const useCheckoutStore = defineStore('checkout', () => {
  // call another store INSIDE the setup function
  const cart = useCartStore();
  const user = useUserStore();

  const canCheckout = computed(
    () => cart.items.length > 0 && !!user.address
  );
  async function submit() {
    await api.order(cart.items, user.id);
    cart.clear();
  }
  return { canCheckout, submit };
});

// composables/useToggle.ts
import { ref } from 'vue';

export function useToggle(initial = false) {
  const value = ref(initial);
  const toggle = () => { value.value = !value.value; };
  return { value, toggle };
}

// in component
<script setup>
import { useToggle } from '@/composables/useToggle';
const { value: open, toggle: toggleOpen } = useToggle();
</script>

// composables/useMouse.ts
import { ref, onMounted, onUnmounted } from 'vue';

export function useMouse() {
  const x = ref(0), y = ref(0);
  const update = (e: MouseEvent) => { x.value = e.pageX; y.value = e.pageY; };
  onMounted(() => window.addEventListener('mousemove', update));
  onUnmounted(() => window.removeEventListener('mousemove', update));
  return { x, y };
}

// in component
const { x, y } = useMouse();

import { ref, watch } from 'vue';

export function useLocalStorage<T>(key: string, initial: T) {
  const stored = typeof window !== 'undefined'
    ? window.localStorage.getItem(key) : null;
  const value = ref<T>(stored ? JSON.parse(stored) : initial);

  watch(value, (v) => {
    if (typeof window !== 'undefined') {
      window.localStorage.setItem(key, JSON.stringify(v));
    }
  }, { deep: true });

  return value;
}

// component
const theme = useLocalStorage<'light' | 'dark'>('theme', 'light');

import { ref, watchEffect } from 'vue';

export function useFetch<T>(url: () => string) {
  const data = ref<T | null>(null);
  const error = ref<Error | null>(null);
  const loading = ref(false);

  watchEffect((onCleanup) => {
    const ctrl = new AbortController();
    onCleanup(() => ctrl.abort());
    loading.value = true;
    fetch(url(), { signal: ctrl.signal })
      .then(r => r.json()).then(d => { data.value = d; loading.value = false; })
      .catch(e => { if (e.name !== 'AbortError') { error.value = e; loading.value = false; } });
  });
  return { data, error, loading };
}

// caller passes a GETTER so watchEffect tracks it
const id = ref(1);
const { data } = useFetch<User>(() => `/api/user/${id.value}`);

import { useEventListener } from '@vueuse/core';

// auto-cleans on unmount, no boilerplate
useEventListener(window, 'resize', () => { /* … */ });
useEventListener(document, 'keydown', onKey);

// target can also be a ref
const elRef = ref<HTMLElement | null>(null);
useEventListener(elRef, 'click', onClick);

import { refDebounced, useThrottleFn } from '@vueuse/core';
import { ref } from 'vue';

const search = ref('');
const debounced = refDebounced(search, 300);  // updates 300ms after stable

watch(debounced, (q) => fetchResults(q));

// throttled function
const onScroll = useThrottleFn(() => updateScrollPos(), 100);
addEventListener('scroll', onScroll);

// parent
<script setup lang="ts">
import { provide, ref, readonly } from 'vue';
const theme = ref<'light' | 'dark'>('light');
provide('theme', readonly(theme));   // child can read but not write
provide('toggleTheme', () => { theme.value = theme.value === 'light' ? 'dark' : 'light'; });
</script>

// child (any descendant depth)
<script setup lang="ts">
import { inject } from 'vue';
const theme = inject<Ref<'light' | 'dark'>>('theme');
const toggleTheme = inject<() => void>('toggleTheme');
</script>

<script setup lang="ts">
import { useTemplateRef, onMounted } from 'vue';

const inputRef = useTemplateRef<HTMLInputElement>('myInput');

onMounted(() => inputRef.value?.focus());
</script>
<template>
  <input ref="myInput" />
</template>

import { useStorage } from '@vueuse/core';

// reactive ref synced to localStorage (type inferred from default)
const settings = useStorage('app-settings', { theme: 'dark', fontSize: 16 });
settings.value.theme = 'light';   // persisted automatically

// sessionStorage instead
const draft = useStorage('draft', '', sessionStorage);

import { ref } from 'vue';
import { useIntersectionObserver } from '@vueuse/core';

const target = ref<HTMLElement | null>(null);
const isVisible = ref(false);

useIntersectionObserver(target, ([entry]) => {
  isVisible.value = entry?.isIntersecting ?? false;
  // e.g. trigger lazy load / infinite scroll when entry is visible
}, { threshold: 0.1 });

import { useClipboard } from '@vueuse/core';

const { copy, copied, isSupported } = useClipboard();

// copied is a ref that flips true for ~1.5s after a successful copy
async function onCopy() {
  await copy('text to copy');
}
// in template:  <button @click="onCopy">{{ copied ? 'Copied!' : 'Copy' }}</button>

// keys.ts — typed injection key
import type { InjectionKey, Ref } from 'vue';
export const ThemeKey: InjectionKey<Ref<'light' | 'dark'>> =
  Symbol('theme');

// provider
provide(ThemeKey, theme);   // type-checked value

// consumer — default value if no provider above
const theme = inject(ThemeKey, ref('light'));
// factory default for expensive values
const cfg = inject(ConfigKey, () => makeConfig(), true);

import { reactive, toRefs } from 'vue';

export function useCounter(start = 0) {
  const state = reactive({ count: start, doubled: 0 });
  const inc = () => { state.count++; state.doubled = state.count * 2; };
  // return toRefs so the caller can destructure AND stay reactive
  return { ...toRefs(state), inc };
}

// caller
const { count, doubled, inc } = useCounter(10);

import { useMediaQuery, useBreakpoints, breakpointsTailwind } from '@vueuse/core';

// reactive boolean for any media query
const isDark = useMediaQuery('(prefers-color-scheme: dark)');
const isWide = useMediaQuery('(min-width: 1024px)');

// named breakpoints
const bp = useBreakpoints(breakpointsTailwind);
const isDesktop = bp.greaterOrEqual('lg');

import { useAsyncState } from '@vueuse/core';

const { state, isLoading, isReady, error, execute } = useAsyncState(
  (id: number) => fetch(`/api/user/${id}`).then(r => r.json()),
  null,                 // initial state while loading
  { immediate: true },  // run on mount
);

// re-run with new args
function reload(id: number) { execute(0, id); }

// RULE OF THUMB
const count = ref(0);                    // primitives → ref
const user = ref({ name: 'Lei' });       // also fine for objects you may replace whole

const cart = reactive({ items: [], total: 0 });   // object you mutate in place

// REPLACEMENT pattern — ref wins
const items = ref<Item[]>([]);
items.value = await fetch(/*…*/);   // wholesale replace, easy

// MUTATION pattern — reactive wins (no .value noise)
const form = reactive({ name: '', age: 0 });
form.name = 'Lei';                  // looks like a plain object

import { reactive, toRefs } from 'vue';
const state = reactive({ x: 1, y: 2 });

// WRONG — x, y become plain numbers
const { x, y } = state;
// x is 1 FOREVER no matter what state.x becomes

// RIGHT — toRefs hands out refs that POINT into state
const { x, y } = toRefs(state);
// x.value tracks state.x both ways

// also: spreading loses reactivity
const copy = { ...state };  // plain object

<!-- WRONG — v-if has HIGHER priority than v-for in Vue 3 -->
<!-- (the reverse of Vue 2!) — `item` is not in scope yet -->
<li v-for="item in items" v-if="item.show">{{ item.name }}</li>

<!-- RIGHT — filter in the source, OR wrap v-for in <template> -->
<li v-for="item in visibleItems" :key="item.id">{{ item.name }}</li>

<!-- or -->
<template v-for="item in items" :key="item.id">
  <li v-if="item.show">{{ item.name }}</li>
</template>

<script setup>
const visibleItems = computed(() => items.value.filter(i => i.show));
</script>

<!-- WRONG — Vue falls back to in-place patch (sometimes called "in-place reuse") -->
<li v-for="item in items">{{ item.name }}</li>
<!-- insert / remove / reorder → DOM gets reused for the WRONG item -->

<!-- RIGHT — stable id -->
<li v-for="item in items" :key="item.id">{{ item.name }}</li>

<!-- AVOID — index as key when list can reorder -->
<li v-for="(item, idx) in items" :key="idx">{{ item.name }}</li>

// WRONG — Vue warns "Avoid mutating a prop directly"
const props = defineProps<{ user: User }>();
props.user.name = 'new';   // also mutates parent state via the same reference

// RIGHT for primitives — use v-model / emit
const props = defineProps<{ modelValue: string }>();
const emit = defineEmits<{ 'update:modelValue': [string] }>();
emit('update:modelValue', 'new');

// or with defineModel (3.4+)
const model = defineModel<string>();
model.value = 'new';

// RIGHT for derived state — make a local copy
const localUser = ref({ ...props.user });

import { ref, reactive, watch } from 'vue';

const r = ref(0);
const obj = reactive({ x: 0 });

// REF — pass it directly
watch(r, (n) => console.log(n));

// REACTIVE OBJECT — pass it directly to watch the WHOLE object (deep auto)
watch(obj, (n) => console.log(n));

// REACTIVE PROPERTY — must use a GETTER (passing obj.x passes the number 0!)
watch(() => obj.x, (n) => console.log(n));

// MULTIPLE sources
watch([r, () => obj.x], ([rv, xv]) => console.log(rv, xv));

// EXPENSIVE — walks every property every change
watch(bigObj, (v) => save(v), { deep: true });

// CHEAPER — watch only the field you care about
watch(() => bigObj.draft.title, (t) => saveTitle(t));

// or memoize a shape via computed
const summary = computed(() => ({ id: bigObj.id, name: bigObj.name }));
watch(summary, (s) => save(s));

<!-- Child.vue -->
<script setup lang="ts">
// top-level await — makes setup async
const user = await fetch('/api/me').then(r => r.json());
</script>

<!-- Parent — REQUIRED, otherwise child stays unmounted forever -->
<template>
  <Suspense>
    <Child />
    <template #fallback>Loading…</template>
  </Suspense>
</template>

<script setup>
// WRONG — this is undefined in setup
function handleClick() {
  this.count++;          // TypeError
}

// RIGHT — refer to refs directly
const count = ref(0);
function handleClick() {
  count.value++;
}
</script>

// WRONG — every instance shares the SAME array
withDefaults(defineProps<{ tags?: string[] }>(), {
  tags: []           // ERROR (runtime form would warn)
});

// RIGHT — default must be a FUNCTION returning a fresh value
withDefaults(defineProps<{ tags?: string[]; user?: User }>(), {
  tags: () => [],
  user: () => ({ name: '' })
});

// 3.5+: destructuring with default avoids the function-factory dance
const { tags = [], user = { name: '' } } = defineProps<{ tags?: string[]; user?: User }>();

// WRONG — onMounted has no active component instance to attach to
function init() {
  onMounted(() => console.log('mounted'));   // warning + no-op
}
init();   // called too early, outside setup

// RIGHT — call composables INSIDE <script setup> body
<script setup>
import { useMouse } from '@/composables/useMouse';
const { x, y } = useMouse();    // OK — synchronously inside setup
</script>

// Also wrong — calling a composable inside a click handler
function onClick() {
  const { x } = useMouse();    // warning, no lifecycle hook can attach
}

<!-- WRONG — server renders 0, client immediately renders 1234 → mismatch -->
<script setup>
const time = ref(Date.now());
</script>
<template>{{ time }}</template>

<!-- RIGHT — render placeholder on server, real value AFTER mount -->
<script setup>
import { ref, onMounted } from 'vue';
const time = ref<number | null>(null);
onMounted(() => { time.value = Date.now(); });
</script>
<template>{{ time ?? '—' }}</template>

<!-- or use <ClientOnly> in Nuxt -->
<ClientOnly><InteractiveWidget /></ClientOnly>

import { ref } from 'vue';
const list = ref([1, 2, 3]);

// FINE in Vue 3 — index assignment IS tracked (unlike Vue 2)
list.value[0] = 99;          // triggers update
list.value.length = 1;       // also tracked

// but forgetting .value silently does nothing
list[0] = 99;                // WRONG — mutates a plain array property, no update

import { ref, watch } from 'vue';
const count = ref(0);

// WRONG — captures the value 0 once, never sees updates
const snapshot = count.value;
watch(() => snapshot, () => {});   // never fires

// RIGHT — pass the ref or a getter so the dependency is tracked
watch(count, (n) => console.log(n));
watch(() => count.value, (n) => console.log(n));

// Child — emit a camelCase event
const emit = defineEmits<{ updateValue: [string] }>();
emit('updateValue', 'x');

<!-- Parent — listen with kebab-case in the template -->
<Child @update-value="onUpdate" />
<!-- @updateValue also works in <script>, but kebab is the template norm -->

<script setup>
import { onMounted } from 'vue';

async function load() {
  const data = await fetch('/api').then(r => r.json());
  // WRONG — registering a lifecycle hook AFTER await
  onMounted(() => {});   // warning: no active instance
}
load();

// RIGHT — register hooks synchronously, do async work inside them
onMounted(async () => {
  const data = await fetch('/api').then(r => r.json());
});
</script>

<template>
  <!-- scoped CSS does NOT reach v-html'd content -->
  <div v-html="article" class="prose"></div>
</template>
<style scoped>
/* .prose h2 { … }  ← will NOT apply to injected markup */
</style>
<style>
/* use a non-scoped block, or :deep() */
.prose :deep(h2) { color: #22d3ee; }
</style>

import { ref, computed } from 'vue';
const ids = ref([3, 1, 2]);

// WRONG — getter mutates its dependency
const sorted = computed(() => ids.value.sort());   // sort() mutates in place!

// RIGHT — copy first, never mutate inside a getter
const sorted2 = computed(() => [...ids.value].sort((a, b) => a - b));

// also wrong: async / side effects inside a getter
const bad = computed(() => { fetch('/x'); return 1; });

import { provide, ref } from 'vue';
const count = ref(0);

// WRONG — provides the number 0; children never see updates
provide('count', count.value);

// RIGHT — provide the ref so descendants stay reactive
provide('count', count);

// later in the parent
count.value++;   // every injecting child re-renders