Vue从入门到精通：Vue3现代前端开发完全实践手册

<template>
  <!-- 最常用：双花括号文本插值 -->
  <h1>{{ title }}</h1>
  <p>{{ user.name }} - {{ user.age }}</p>

  <!-- 表达式（不是语句） -->
  <p>{{ count > 10 ? '很多' : '较少' }}</p>
  <p>{{ fullName.toUpperCase() }}</p>
  <p>{{ items.length }} 项</p>
</template>

<template>
  <!-- 绑定 HTML 属性 -->
  <img :src="imageUrl" :alt="altText">
  <a :href="url" :target="isNewTab ? '_blank' : '_self'">链接</a>

  <!-- 简写：: 就是 v-bind 的语法糖 -->
  <div :class="className" :style="styleObj"></div>

  <!-- 动态属性名（ES6 计算属性名语法） -->
  <div :[dynamicAttr]="'value'"></div>
</template>

<template>
  <!-- v-if / v-else-if / v-else：条件为真时才渲染（会移除/创建 DOM） -->
  <div v-if="status === 'loading'">加载中...</div>
  <div v-else-if="status === 'error'">出错了</div>
  <div v-else>加载完成</div>

  <!-- v-show：始终渲染，通过 CSS display 切换显隐（适合频繁切换） -->
  <div v-show="isVisible">我可能被隐藏</div>

  <!-- v-if 与 v-for 同时使用时的注意事项 -->
  <!-- 错误：v-if 和 v-for 在同一元素上 -->
  <!-- <li v-for="item in items" v-if="item.visible">{{ item.name }}</li> -->

  <!-- 正确做法：用 computed 过滤，或用 <template> 包裹 -->
  <template v-for="item in items" :key="item.id">
    <li v-if="item.visible">{{ item.name }}</li>
  </template>
</template>

<template>
  <!-- 基本用法 -->
  <ul>
    <li v-for="(item, index) in items" :key="item.id">
      {{ index }}. {{ item.name }}
    </li>
  </ul>

  <!-- 遍历对象 -->
  <ul>
    <li v-for="(value, key, index) in userProfile" :key="key">
      {{ index }}. {{ key }}: {{ value }}
    </li>
  </ul>

  <!-- 遍历数字范围 -->
  <ul>
    <li v-for="n in 5" :key="n">{{ n }}</li>
  </ul>

  <!-- 配合 <template> 渲染多个兄弟元素 -->
  <template v-for="group in groups" :key="group.id">
    <h3>{{ group.title }}</h3>
    <p>{{ group.content }}</p>
    <hr>
  </template>
</template>

<script setup lang="ts">
import { ref } from 'vue'

const count = ref(0)
const message = ref('')

function increment() {
  count.value++
}

function handleClick(event: MouseEvent, extra: string) {
  console.log(event, extra)
}

function onKeyup(event: KeyboardEvent) {
  if (event.key === 'Enter') {
    submit()
  }
}

function submit() {
  console.log('submitted:', message.value)
}
</script>

<template>
  <!-- 基本绑定 -->
  <button @click="increment">{{ count }}</button>

  <!-- 内联表达式 -->
  <button @click="count++">{{ count }}</button>

  <!-- 传参 -->
  <button @click="handleClick($event, 'extra')">带参数</button>

  <!-- 修饰符 -->
  <form @submit.prevent="submit">
    <input v-model="message" @keyup.enter="submit">
  </form>

  <!-- 事件修饰符 -->
  <a @click.stop="onClick">阻止冒泡</a>
  <div @click.capture="onCapture">捕获阶段</div>
  <div @click.self="onSelf">仅自身点击</div>
  <a @click.once="onOnce">仅执行一次</a>
  <div @scroll.passive="onScroll">被动监听</div>

  <!-- 按键修饰符 -->
  <input @keyup.enter="submit">
  <input @keyup.esc="cancel">
  <input @keyup.ctrl.a="selectAll">

  <!-- 系统修饰符 -->
  <div @click.ctrl="onCtrlClick">Ctrl + Click</div>
  <div @click.shift="onShiftClick">Shift + Click</div>
</template>

<template>
  <!-- 等价于 :value + @input -->
  <input v-model="text">
  <textarea v-model="description"></textarea>
  <select v-model="selected">
    <option value="a">A</option>
    <option value="b">B</option>
  </select>

  <!-- 复选框（布尔） -->
  <input type="checkbox" v-model="isChecked">

  <!-- 复选框（数组） -->
  <input type="checkbox" value="vue" v-model="tags">
  <input type="checkbox" value="react" v-model="tags">

  <!-- 单选框 -->
  <input type="radio" value="male" v-model="gender">
  <input type="radio" value="female" v-model="gender">

  <!-- 修饰符 -->
  <input v-model.lazy="text">      <!-- 改为 change 事件触发 -->
  <input v-model.number="age">     <!-- 自动转为 number -->
  <input v-model.trim="name">      <!-- 自动去除首尾空白 -->
</template>

<template>
  <!-- v-text：设置 textContent（等价于 {{ }}） -->
  <p v-text="message"></p>

  <!-- v-html：设置 innerHTML（有 XSS 风险，仅用于可信内容） -->
  <div v-html="trustedHtml"></div>
</template>

<template>
  <!-- v-once：只渲染一次，后续数据变化不再更新 -->
  <p v-once>{{ staticMessage }}</p>

  <!-- v-memo：按条件缓存渲染结果（性能优化） -->
  <div v-memo="[valueA, valueB]">
    <!-- 仅当 valueA 或 valueB 变化时才重新渲染 -->
    <expensive-component :a="valueA" :b="valueB" />
  </div>

  <!-- v-pre：跳过该元素及其子元素的编译 -->
  <div v-pre>{{ 这里不会被编译 }}</div>
</template>

<template>
  <!-- ✅ 好：computed 有缓存，count 不变时不重新计算 -->
  <p>{{ expensiveComputed }}</p>

  <!-- ❌ 差：每次渲染都重新调用 -->
  <p>{{ expensiveMethod() }}</p>
</template>

<!-- MyComponent.vue -->
<script setup lang="ts">
// 组合式 API + TypeScript
import { ref } from 'vue'

const count = ref(0)
</script>

<template>
  <!-- 模板（HTML + Vue 指令） -->
  <div>
    <p>{{ count }}</p>
  </div>
</template>

<style scoped>
/* 样式（scoped 表示只作用于当前组件） */
div {
  color: blue;
}
</style>

<!-- Child.vue -->
<script setup lang="ts">
// 方式一：纯类型声明（推荐）
const props = defineProps<{
  title: string
  count?: number          // 可选
  items: string[]
  config: {
    theme: 'light' | 'dark'
    size: number
  }
  callback?: (val: string) => void
}>()

// 方式二：带默认值和运行时校验
const props2 = defineProps({
  title: { type: String, required: true },
  count: { type: Number, default: 0 },
  items: { type: Array as () => string[], default: () => [] },
  status: {
    type: String,
    validator: (v: string) => ['active', 'inactive'].includes(v),
    default: 'active'
  }
})

// 方式三：withDefaults 设置默认值（配合类型声明）
interface Props {
  title: string
  count?: number
  size?: 'sm' | 'md' | 'lg'
}

const props3 = withDefaults(defineProps<Props>(), {
  count: 0,
  size: 'md'
})
</script>

<template>
  <h2>{{ title }}</h2>
  <p>Count: {{ count }}</p>
</template>

<!-- Child.vue -->
<script setup lang="ts">
// 类型声明
const emit = defineEmits<{
  (e: 'update', id: number, value: string): void
  (e: 'delete', id: number): void
  (e: 'close'): void
}>()

// 或简写形式（Vue 3.3+）
const emit2 = defineEmits<{
  update: [id: number, value: string]
  delete: [id: number]
  close: []
}>()

function handleClick() {
  emit('update', 1, 'hello')
}
</script>

<template>
  <button @click="handleClick">Click</button>
  <button @click="emit('close')">Close</button>
</template>

<!-- Parent.vue -->
<template>
  <Child
    :title="'Hello'"
    @update="onUpdate"
    @delete="onDelete"
    @close="onClose"
  />
</template>

<script setup lang="ts">
function onUpdate(id: number, value: string) {
  console.log(id, value)
}
</script>

<!-- CustomInput.vue -->
<script setup lang="ts">
// Vue 3 默认的 v-model 约定：modelValue + update:modelValue
const props = defineProps<{
  modelValue: string
}>()

const emit = defineEmits<{
  (e: 'update:modelValue', value: string): void
}>()
</script>

<template>
  <input
    :value="modelValue"
    @input="emit('update:modelValue', ($event.target as HTMLInputElement).value)"
  >
</template>

<!-- Parent.vue -->
<template>
  <!-- 基本用法 -->
  <CustomInput v-model="text" />

  <!-- Vue 3.4+ defineModel 语法糖（更简洁） -->
  <CustomInput2 v-model="text" />
</template>

<!-- CustomInput.vue（简化版） -->
<script setup lang="ts">
const model = defineModel<string>()

// 可以直接 v-model="model" 使用
</script>

<template>
  <input v-model="model">
</template>

<!-- UserForm.vue -->
<script setup lang="ts">
const name = defineModel<string>('name')
const age = defineModel<number>('age')
</script>

<template>
  <input v-model="name">
  <input v-model="age" type="number">
</template>

<!-- Parent.vue -->
<template>
  <UserForm v-model:name="userName" v-model:age="userAge" />
</template>

<!-- Layout.vue -->
<script setup lang="ts">
</script>

<template>
  <div class="layout">
    <!-- 默认插槽 -->
    <header>
      <slot name="header">默认头部</slot>
    </header>

    <main>
      <!-- 默认插槽（匿名） -->
      <slot>默认内容</slot>
    </main>

    <footer>
      <!-- 作用域插槽：子组件向插槽传递数据 -->
      <slot name="footer" :year="2024" :author="'Vue Team'">
        <p>默认页脚</p>
      </slot>
    </footer>
  </div>
</template>

<!-- Parent.vue -->
<template>
  <Layout>
    <!-- 默认插槽 -->
    <p>页面内容</p>

    <!-- 具名插槽 -->
    <template #header>
      <h1>自定义头部</h1>
    </template>

    <!-- 作用域插槽：接收子组件传递的数据 -->
    <template #footer="{ year, author }">
      <p>© {{ year }} {{ author }}</p>
    </template>
  </Layout>
</template>

<template>
  <div>
    <button @click="showModal = true">打开弹窗</button>

    <!-- 将弹窗传送到 body 下，避免被父容器的 overflow/transform 裁剪 -->
    <Teleport to="body">
      <div v-if="showModal" class="modal-overlay">
        <div class="modal">
          <h2>弹窗标题</h2>
          <p>弹窗内容</p>
          <button @click="showModal = false">关闭</button>
        </div>
      </div>
    </Teleport>
  </div>
</template>

<!-- App.vue -->
<template>
  <Suspense>
    <!-- 默认内容（异步就绪后显示） -->
    <template #default>
      <AsyncDashboard />
    </template>

    <!-- 加载中的占位内容 -->
    <template #fallback>
      <LoadingSpinner />
    </template>
  </Suspense>
</template>

<!-- AsyncDashboard.vue -->
<script setup lang="ts">
// setup 中的顶层 await 会让组件成为异步组件
const data = await fetch('/api/dashboard').then(r => r.json())
const config = await loadConfig()
</script>

<template>
  <div>{{ data }}</div>
</template>

<template>
  <!-- 切换路由/组件时保留组件状态（如滚动位置、输入内容） -->
  <KeepAlive :include="['Dashboard', 'Settings']" :max="10">
    <component :is="currentComponent" />
  </KeepAlive>
</template>

<script setup lang="ts">
import { ref, computed, watch } from 'vue'
import MyComponent from './MyComponent.vue'

// 所有在 setup 中定义的变量/函数，模板中可直接使用
const count = ref(0)
const double = computed(() => count.value * 2)

function increment() {
  count.value++
}

// 组件导入后，模板中直接使用 <MyComponent />，无需注册
// defineProps / defineEmits / defineExpose / defineModel 是编译器宏，无需 import
const props = defineProps<{ title: string }>()
const emit = defineEmits<{ (e: 'change', val: number): void }>()

// 对外暴露（默认 setup 返回值/变量不暴露给父组件，需手动 expose）
defineExpose({
  count,
  increment
})
</script>

<template>
  <MyComponent :title="title" @change="onChange" />
</template>

<!-- 在组件中使用 -->
<script setup lang="ts">
import { useCounter } from '@/composables/useCounter'

const { count, double, increment, decrement, reset } = useCounter(10)
</script>

<template>
  <p>{{ count }} (double: {{ double }})</p>
  <button @click="increment()">+1</button>
  <button @click="decrement()">-1</button>
  <button @click="reset()">Reset</button>
</template>

<!-- 顶层祖先组件 -->
<script setup lang="ts">
import { provide, ref, readonly } from 'vue'

const theme = ref('dark')
const config = ref({ apiUrl: 'https://api.example.com' })

// provide(key, value)
provide('theme', theme)
provide('config', readonly(config))   // 用 readonly 防止子组件修改

// 提供方法供子组件调用
provide('toggleTheme', () => {
  theme.value = theme.value === 'dark' ? 'light' : 'dark'
})
</script>

<!-- 任意深度的后代组件 -->
<script setup lang="ts">
import { inject, type Ref } from 'vue'

const theme = inject<Ref<string>>('theme')
const config = inject<{ apiUrl: string }>('config')
const toggleTheme = inject<() => void>('toggleTheme')

// 可设置默认值
const fallback = inject('nonExistent', 'default-value')
</script>

<template>
  <p>当前主题：{{ theme }}</p>
  <button @click="toggleTheme">切换主题</button>
</template>

<script setup lang="ts">
import { defineAsyncComponent, shallowRef } from 'vue'

// 基本用法
const HeavyChart = defineAsyncComponent(() =>
  import('./components/HeavyChart.vue')
)

// 带加载/错误状态
const HeavyChart2 = defineAsyncComponent({
  loader: () => import('./components/HeavyChart.vue'),
  loadingComponent: LoadingSpinner,      // 加载中显示
  errorComponent: ErrorDisplay,           // 加载失败显示
  delay: 200,                             // 延迟显示 loading（ms）
  timeout: 10000,                         // 超时时间（ms）
  onError(error, retry, fail, attempts) {
    if (attempts < 3) {
      retry()    // 重试
    } else {
      fail()     // 放弃
    }
  }
})
</script>

<template>
  <HeavyChart />
</template>

<script setup lang="ts">
import {
  onBeforeMount,
  onMounted,
  onBeforeUpdate,
  onUpdated,
  onBeforeUnmount,
  onUnmounted,
  onActivated,
  onDeactivated,
  onRenderTracked,
  onRenderTriggered,
  onErrorCaptured
} from 'vue'

// setup() 执行时机（等同于 Vue 2 的 beforeCreate + created）
// 以下按执行顺序排列

onBeforeMount(() => {
  // DOM 挂载前调用，此时模板已编译但未渲染
  console.log('beforeMount')
})

onMounted(() => {
  // DOM 挂载完成后调用（可访问真实 DOM）
  console.log('mounted')
  // 典型用途：发起请求、初始化第三方库、操作 DOM
})

onBeforeUpdate(() => {
  // 响应式数据变化导致 DOM 更新前
  console.log('beforeUpdate')
})

onUpdated(() => {
  // DOM 更新完成后
  console.log('updated')
  // 注意：在此修改数据可能导致无限循环
})

onBeforeUnmount(() => {
  // 组件卸载前
  console.log('beforeUnmount')
})

onUnmounted(() => {
  // 组件卸载后（清理定时器、取消订阅等）
  console.log('unmounted')
})

// KeepAlive 专属
onActivated(() => {
  // 被 KeepAlive 缓存的组件激活时
})

onDeactivated(() => {
  // 被 KeepAlive 缓存的组件停用时
})

// 调试
onRenderTracked((event) => {
  console.log('render tracked:', event)
})

onRenderTriggered((event) => {
  console.log('render triggered:', event)
})

// 错误捕获
onErrorCaptured((err, instance, info) => {
  console.error('Error captured:', err)
  return false  // 阻止错误向上传播
})
</script>

<script lang="ts">
import { defineComponent } from 'vue'

export default defineComponent({
  // Options API 生命周期
  beforeCreate() {},   // 等同于 setup() 的开头
  created() {},        // 等同于 setup() 的结尾

  beforeMount() {},    // 等同于 onBeforeMount
  mounted() {},        // 等同于 onMounted

  beforeUpdate() {},   // 等同于 onBeforeUpdate
  updated() {},        // 等同于 onUpdated

  beforeUnmount() {},  // 等同于 onBeforeUnmount（Vue 2 为 beforeDestroy）
  unmounted() {},      // 等同于 onUnmounted（Vue 2 为 destroyed）
})
</script>

<script setup lang="ts">
import { ref, reactive } from 'vue'

// 基础表单状态
const form = reactive({
  username: '',
  email: '',
  password: '',
  age: 18,
  gender: 'male',
  hobbies: [] as string[],
  agree: false,
  country: 'china',
  bio: ''
})

// 提交处理
function handleSubmit() {
  console.log('Form data:', form)
  // 发送请求...
}
</script>

<template>
  <form @submit.prevent="handleSubmit">
    <!-- 文本输入 -->
    <input v-model="form.username" placeholder="用户名">
    <input v-model="form.email" type="email" placeholder="邮箱">
    <input v-model="form.password" type="password" placeholder="密码">
    <input v-model.number="form.age" type="number" placeholder="年龄">

    <!-- 文本域 -->
    <textarea v-model="form.bio" placeholder="个人简介"></textarea>

    <!-- 单选框 -->
    <label>
      <input type="radio" value="male" v-model="form.gender"> 男
    </label>
    <label>
      <input type="radio" value="female" v-model="form.gender"> 女
    </label>

    <!-- 复选框（布尔） -->
    <label>
      <input type="checkbox" v-model="form.agree"> 同意条款
    </label>

    <!-- 复选框（数组） -->
    <label>
      <input type="checkbox" value="reading" v-model="form.hobbies"> 阅读
    </label>
    <label>
      <input type="checkbox" value="coding" v-model="form.hobbies"> 编程
    </label>

    <!-- 下拉选择 -->
    <select v-model="form.country">
      <option value="china">中国</option>
      <option value="usa">美国</option>
      <option value="japan">日本</option>
    </select>

    <button type="submit">提交</button>
  </form>
</template>

<template>
  <!-- .lazy：改为 change 事件触发（失焦或回车时） -->
  <input v-model.lazy="text">

  <!-- .number：自动将输入值转为 number -->
  <input v-model.number="age">

  <!-- .trim：自动去除首尾空白 -->
  <input v-model.trim="name">
</template>

<!-- CustomSelect.vue -->
<script setup lang="ts">
interface Option {
  label: string
  value: string | number
}

const props = defineProps<{
  options: Option[]
  placeholder?: string
}>()

const model = defineModel<string | number>()

function handleChange(event: Event) {
  model.value = (event.target as HTMLSelectElement).value
}
</script>

<template>
  <select :value="model" @change="handleChange">
    <option value="" disabled>{{ placeholder || '请选择' }}</option>
    <option v-for="opt in options" :key="opt.value" :value="opt.value">
      {{ opt.label }}
    </option>
  </select>
</template>

<!-- Parent.vue -->
<template>
  <CustomSelect
    v-model="selectedCity"
    :options="cityOptions"
    placeholder="选择城市"
  />
</template>

<script setup lang="ts">
import { ref } from 'vue'

const show = ref(true)
const activeTab = ref('home')
</script>

<template>
  <button @click="show = !show">切换</button>

  <!-- 自动应用过渡 CSS -->
  <Transition name="fade">
    <div v-if="show">Hello, Transition!</div>
  </Transition>

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

<style>
/* fade 过渡 */
.fade-enter-active,
.fade-leave-active {
  transition: opacity 0.3s ease;
}

.fade-enter-from,
.fade-leave-to {
  opacity: 0;
}

/* list 过渡 */
.list-enter-active,
.list-leave-active {
  transition: all 0.4s ease;
}

.list-enter-from {
  opacity: 0;
  transform: translateX(-30px);
}

.list-leave-to {
  opacity: 0;
  transform: translateX(30px);
}

/* 移动动画（列表重排序时） */
.list-move {
  transition: transform 0.4s ease;
}

/* 离开的元素从文档流中移除 */
.list-leave-active {
  position: absolute;
}
</style>

<script setup lang="ts">
import { ref } from 'vue'

const show = ref(true)

function onBeforeEnter(el: Element) {
  console.log('before enter', el)
}

function onEnter(el: Element, done: () => void) {
  // 使用 JS 动画
  const element = el as HTMLElement
  element.style.opacity = '0'
  requestAnimationFrame(() => {
    element.style.transition = 'opacity 0.5s'
    element.style.opacity = '1'
    done()
  })
}

function onLeave(el: Element, done: () => void) {
  const element = el as HTMLElement
  element.style.opacity = '0'
  setTimeout(done, 500)
}
</script>

<template>
  <Transition
    :css="false"
    @before-enter="onBeforeEnter"
    @enter="onEnter"
    @leave="onLeave"
  >
    <div v-if="show">JS 动画</div>
  </Transition>
</template>

<Transition
  name="fade"
  mode="out-in"        <!-- 先离开再进入（避免重叠） -->
  :duration="300"       <!-- 自定义持续时间（ms） -->
  :appear="true"        <!-- 初始渲染时也应用过渡 -->
>
  <component :is="currentView" />
</Transition>

<Transition
  enter-active-class="animate__animated animate__fadeIn"
  leave-active-class="animate__animated animate__fadeOut"
>
  <div v-if="show">使用 Animate.css</div>
</Transition>