Vue 3 组合式 API 与响应式原理

<template>
  <div>
    <span>静态文本</span>
    <span :class="dynamicClass">动态类名</span>
  </div>
</template>

# 使用 npm
npm create vue@latest

# 使用 yarn
yarn create vue

# 使用 pnpm
pnpm create vue@latest

✔ Project name: my-vue3-app
✔ Add TypeScript? … No / Yes
✔ Add JSX Support? … No / Yes
✔ Add Vue Router for Single Page Application? … No / Yes
✔ Add Pinia for state management? … No / Yes
✔ Add Vitest for Unit Testing? … No / Yes
✔ Add an End-to-End Testing Solution? … No / Yes
✔ Add ESLint for code quality? … No / Yes
✔ Add Prettier for code formatting? … No / Yes

Scaffolding project in ./my-vue3-app...
Done.

cd my-vue3-app
npm install
npm run dev

import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'

export default defineConfig({
  plugins: [vue()],
  server: {
    port: 3000,
    open: true,
  },
})

<script>
import { ref, onMounted } from 'vue'

export default {
  props: { count: Number },
  setup(props, context) {
    const message = ref('Hello')
    const { emit, slots, attrs, expose } = context

    onMounted(() => {
      console.log('Mounted!')
    })

    // 暴露给模板
    return { message }
  }
}
</script>

<script setup>
import { ref, onMounted } from 'vue'

const message = ref('Hello')

onMounted(() => {
  console.log('Mounted!')
})
</script>

<template>
  <div>{{ message }}</div>
</template>

<script setup>
const data = await fetch('/api/data').then(r => r.json())
</script>

<script setup>
import { ref, reactive } from 'vue'

// ✅ 推荐：大多数情况用 ref
const count = ref(0)
const user = ref({ name: 'Alice' })

// ✅ 可选：深层对象用 reactive
const form = reactive({
  username: '',
  password: '',
  profile: { bio: '' },
})

// ❌ 错误：解构会丢失响应性
const { username } = form
username = 'new' // 不会触发更新
</script>

<script setup>
import { ref, computed } from 'vue'

const firstName = ref('张')
const lastName = ref('三')

// 只读计算属性（默认模式）
const fullName = computed(() => {
  return firstName.value + ' ' + lastName.value
})

console.log(fullName.value) // '张 三'
</script>

<template>
  <p>全名: {{ fullName }}</p>
</template>

<script setup>
import { ref, computed } from 'vue'

const firstName = ref('张')
const lastName = ref('三')

// 可读写计算属性
const fullName = computed({
  get() {
    return firstName.value + ' ' + lastName.value
  },
  set(newValue) {
    ;[firstName.value, lastName.value] = newValue.split(' ')
  },
})

// 使用 setter
fullName.value = '李 四'
console.log(firstName.value) // '李'
console.log(lastName.value)  // '四'
</script>

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

<script setup>
import { ref, computed } from 'vue'

const items = ref([1, 2, 3, 4, 5, 6])

// 计算属性——缓存，只在依赖变化时重新计算
const evenItems = computed(() => {
  console.log('computed 重新计算')
  return items.value.filter(n => n % 2 === 0)
})

// 方法——每次渲染都重新执行
function getEvenItems() {
  console.log('方法重新执行')
  return items.value.filter(n => n % 2 === 0)
}
</script>

<template>
  <p>计算属性: {{ evenItems }}</p>
  <p>方法: {{ getEvenItems() }}</p>
</template>

<script setup>
import { ref, watch } from 'vue'

const count = ref(0)

watch(count, (newVal, oldVal) => {
  console.log(`count 从 ${oldVal} 变为 ${newVal}`)
})
</script>

<template>
  <button @click="count++">增加</button>
</template>

<script setup>
import { reactive, watch } from 'vue'

const state = reactive({ count: 0 })

watch(
  () => state.count,
  (newVal, oldVal) => {
    console.log(`count 变为 ${newVal}`)
  }
)
</script>

<script setup>
import { ref, watch } from 'vue'

const x = ref(0)
const y = ref(0)

watch([x, y], ([newX, newY], [oldX, oldY]) => {
  console.log(`x: ${oldX} -> ${newX}, y: ${oldY} -> ${newY}`)
})
</script>

<script setup>
import { ref, watchEffect } from 'vue'

const count = ref(0)
const name = ref('Vue')

// 自动追踪 count 和 name
watchEffect(() => {
  console.log(`count: ${count.value}, name: ${name.value}`)
})

// 修改变量时会自动触发
// count 变化 -> watchEffect 自动运行
// name 变化 -> watchEffect 自动运行

// 清除副作用
watchEffect((onCleanup) => {
  const timer = setTimeout(() => {
    console.log('延迟执行')
  }, 1000)

  // 当 watchEffect 重新运行或组件卸载时，清除之前的副作用
  onCleanup(() => {
    clearTimeout(timer)
  })
})
</script>

<script setup>
import { reactive, toRef } from 'vue'

const state = reactive({
  count: 0,
  name: 'Vue',
})

// 创建与 state.count 保持同步的 ref
const countRef = toRef(state, 'count')

// 修改 ref 会同步到原对象
countRef.value++
console.log(state.count) // 1

// 修改原对象也会同步到 ref
state.count++
console.log(countRef.value) // 2
</script>

<script setup>
import { reactive, toRefs } from 'vue'

const state = reactive({
  count: 0,
  name: 'Vue',
})

// 解构后的每个属性都是 ref，仍然保持响应性
const { count, name } = toRefs(state)

// 现在可以放心解构使用了
count.value++
name.value = 'Vue 3'
</script>

<template>
  <p>{{ count }} - {{ name }}</p>
</template>

<script setup>
import { reactive, toRefs } from 'vue'

function useMouse() {
  const state = reactive({ x: 0, y: 0 })
  // ... 监听鼠标事件

  return toRefs(state) // 返回 { x: ref, y: ref }
}

// 用户可以解构使用
const { x, y } = useMouse()
</script>

<script setup>
import { shallowRef } from 'vue'

const state = shallowRef({
  list: Array.from({ length: 10000 }, (_, i) => i),
  meta: { version: 1 },
})

// ✅ 触发更新——重新赋值 .value
state.value = { list: [], meta: { version: 2 } }

// ❌ 不会触发更新——修改内部属性
state.value.list.push(9999)
state.value.meta.version = 3 // 不会触发视图更新
</script>

<script setup>
import { shallowReactive } from 'vue'

const state = shallowReactive({
  nested: { count: 0 },
  arr: [1, 2, 3],
})

// ✅ 触发更新——修改第一层属性
state.nested = { count: 10 }

// ❌ 不会触发更新——修改嵌套属性
state.nested.count++

// ❌ 不会触发更新——数组原地修改
state.arr.push(4)
</script>

<script setup>
import { reactive, readonly, ref } from 'vue'

const original = reactive({ count: 0, nested: { value: 1 } })
const readOnlyCopy = readonly(original)

// 尝试修改只读代理
readOnlyCopy.count++ // 警告: Set operation on key "count" failed: target is readonly
readOnlyCopy.nested.value = 2 // 同样警告（深层只读）
</script>

<script setup>
import { shallowReadonly, reactive, shallowRef } from 'vue'

const state = shallowReadonly({
  count: 0,
  nested: { value: 1 },
})

state.count++ // 警告：不可修改
state.nested.value = 2 // ✅ 可以修改（深层的没有被限制）

// 常见用法：在组合式函数中暴露只读状态
function useCounter() {
  const count = ref(0)
  const double = computed(() => count.value * 2)

  function increment() {
    count.value++
  }

  return {
    count: readonly(count), // 对外只读
    double: readonly(double),
    increment, // 方法可调用
  }
}
</script>

// Vue 2 响应式简化实现
function defineReactive(obj, key, val) {
  Object.defineProperty(obj, key, {
    get() {
      // 收集依赖
      dep.depend()
      return val
    },
    set(newVal) {
      if (newVal !== val) {
        val = newVal
        // 触发更新
        dep.notify()
      }
    },
  })
}

const vm = new Vue({
  data: { user: { name: 'Alice' } },
})

// ❌ 不是响应式的
vm.user.age = 25

// ❌ 也不是响应式的
delete vm.user.name

// 👇 必须使用 Vue.set / Vue.delete
Vue.set(vm.user, 'age', 25)
Vue.delete(vm.user, 'name')

const vm = new Vue({
  data: { items: ['a', 'b', 'c'] },
})

// ❌ 不是响应式的
vm.items[0] = 'x'
vm.items.length = 0

// 👇 必须使用 Vue.set 或数组变异方法
vm.items.splice(0, 1, 'x')
Vue.set(vm.items, 0, 'x')

用户操作 → 修改属性 → Proxy set 拦截器 → trigger() → 执行所有 effect → 组件重新渲染
                                                                           ↓
组件渲染 → 读取属性 → Proxy get 拦截器 → track() → 收集当前 effect ←───┘

targetMap (WeakMap)
  ├── target1 → depsMap (Map)
  │   ├── 'count' → dep (Set) [effect1, effect2, ...]
  │   ├── 'name'  → dep (Set) [effect1, effect3, ...]
  │   └── Symbol('iterate') → dep (Set) [effect4, ...]
  └── target2 → depsMap (Map)
      └── ...

// 当前正在执行的 effect
let activeEffect = null

function track(target, key) {
  if (!activeEffect) return

  // 获取 target 的 depsMap
  let depsMap = targetMap.get(target)
  if (!depsMap) {
    targetMap.set(target, (depsMap = new Map()))
  }

  // 获取 key 的 dep
  let dep = depsMap.get(key)
  if (!dep) {
    depsMap.set(key, (dep = new Set()))
  }

  // 将当前 effect 加入 dep
  dep.add(activeEffect)
}

function trigger(target, key, type, newValue) {
  const depsMap = targetMap.get(target)
  if (!depsMap) return

  // 收集所有需要执行的 effect
  const effectsToRun = new Set()

  // 属性相关的 effect
  const dep = depsMap.get(key)
  if (dep) {
    dep.forEach(effect => effectsToRun.add(effect))
  }

  // 如果是数组且 key 是 'length'，需要触发所有依赖
  if (Array.isArray(target) && key === 'length') {
    depsMap.forEach((dep, key) => {
      if (key === 'length' || key >= newValue) {
        dep.forEach(effect => effectsToRun.add(effect))
      }
    })
  }

  // 执行所有 effect
  effectsToRun.forEach(effect => effect())
}

// 简化版 effect
function effect(fn) {
  const _effect = () => {
    try {
      activeEffect = _effect // 设置当前 effect
      cleanup(_effect)       // 清除旧的依赖
      return fn()            // 执行函数，触发 track 收集新依赖
    } finally {
      activeEffect = null
    }
  }

  _effect.deps = [] // 存储依赖
  _effect()         // 立即执行
  return _effect
}

// 清除旧的依赖（如果某属性不再被访问，需要取消对该属性的订阅）
function cleanup(effect) {
  effect.deps.forEach(dep => dep.delete(effect))
  effect.deps.length = 0
}

<script setup>
// 一个简单的组合式函数
import { ref, onMounted, onUnmounted } from 'vue'

function useMouse() {
  const x = ref(0)
  const y = ref(0)

  function update(event) {
    x.value = event.clientX
    y.value = event.clientY
  }

  onMounted(() => window.addEventListener('mousemove', update))
  onUnmounted(() => window.removeEventListener('mousemove', update))

  return { x, y }
}

// 在组件中使用
const { x, y } = useMouse()
</script>

<template>
  <p>鼠标位置: {{ x }}, {{ y }}</p>
</template>

// mixin-a.js
export default {
  data() { return { count: 0 } },
  methods: { increment() { this.count++ } },
}

// mixin-b.js
export default {
  data() { return { count: 10 } }, // ❌ 与 mixin-a 冲突
}

// 组件中
export default {
  mixins: [mixinA, mixinB],
  mounted() {
    console.log(this.count) // 10（mixin-b 覆盖了 mixin-a）
  },
}

<script setup>
// 每个 composable 的返回值通过解构显式命名
const { count: countA, increment } = useCounterA()
const { count: countB } = useCounterB()
</script>

<script setup>
import { ref, computed } from 'vue'

function useCounter(initialValue = 0) {
  const count = ref(initialValue)
  const double = computed(() => count.value * 2)

  function increment() { count.value++ }
  function decrement() { count.value-- }
  function reset() { count.value = initialValue }

  return { count, double, increment, decrement, reset }
}

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

<template>
  <div>
    <p>计数: {{ count }}</p>
    <p>双倍: {{ double }}</p>
    <button @click="increment">+</button>
    <button @click="decrement">-</button>
    <button @click="reset">重置</button>
  </div>
</template>

<script setup>
import { ref, watch } from 'vue'

function useLocalStorage(key, defaultValue) {
  // 尝试从 localStorage 读取初始值
  const stored = localStorage.getItem(key)
  const data = ref(stored ? JSON.parse(stored) : defaultValue)

  // 监听数据变化并写入 localStorage
  watch(data, (newVal) => {
    localStorage.setItem(key, JSON.stringify(newVal))
  }, { deep: true })

  return data
}

// 使用
const theme = useLocalStorage('theme', 'light')
const user = useLocalStorage('user', { name: '', age: 0 })
</script>

<template>
  <select v-model="theme">
    <option value="light">浅色</option>
    <option value="dark">深色</option>
  </select>
</template>

<script setup>
import { ref, watch } from 'vue'

function useDebounce(source, delay = 300) {
  const debouncedValue = ref(source.value)

  watch(source, () => {
    const timer = setTimeout(() => {
      debouncedValue.value = source.value
    }, delay)
    // 自动清理
  })

  return debouncedValue
}

// 使用：搜索框防抖
const searchQuery = ref('')
const debouncedQuery = useDebounce(searchQuery, 500)

watch(debouncedQuery, (query) => {
  console.log('发送搜索请求:', query)
})
</script>

<!-- App.vue -->
<script setup>
import { ref } from 'vue'
import TabA from './TabA.vue'
import TabB from './TabB.vue'

const activeTab = ref('A')
</script>

<template>
  <div>
    <button @click="activeTab = 'A'">标签 A</button>
    <button @click="activeTab = 'B'">标签 B</button>

    <KeepAlive>
      <TabA v-if="activeTab === 'A'" />
      <TabB v-else />
    </KeepAlive>
  </div>
</template>

<!-- TabA.vue -->
<script setup>
import { onActivated, onDeactivated } from 'vue'

onActivated(() => {
  console.log('TabA 被激活')
  // 可以在这里刷新数据
})

onDeactivated(() => {
  console.log('TabA 失活')
  // 暂停不必要的操作
})
</script>

<script setup>
import { ref, onErrorCaptured } from 'vue'

const error = ref(null)

onErrorCaptured((err, instance, info) => {
  console.error('捕获到错误:', err)

  // 保存错误信息供模板显示
  error.value = {
    message: err.message,
    component: instance?.type?.__name,
    info, // 错误类型信息
  }

  // 返回 false 阻止错误继续传播
  return false
})
</script>

<template>
  <div v-if="error" class="error-boundary">
    <h3>组件出错了</h3>
    <p>{{ error.message }}</p>
  </div>
  <div v-else>
    <slot />
  </div>
</template>

<template>
  <div>
    <p>{{ message }}</p>
    <p>{{ greeting + ' ' + name }}</p>
    <p>{{ count > 10 ? '超过10' : '小于等于10' }}</p>
    <p>{{ items.length > 0 ? items.join(', ') : '暂无数据' }}</p>
  </div>
</template>

<script setup>
import { ref } from 'vue'

const message = ref('Hello Vue 3!')
const greeting = ref('你好')
const name = ref('小明')
const count = ref(15)
const items = ref(['苹果', '香蕉', '橙子'])
</script>

<template>
  <!-- v-if：适合低频切换 -->
  <div v-if="isLoggedIn">
    欢迎回来，{{ username }}
  </div>
  <div v-else>
    请先登录
  </div>

  <!-- v-else-if：多条件分支 -->
  <div v-if="status === 'loading'">加载中...</div>
  <div v-else-if="status === 'error'">加载失败</div>
  <div v-else>内容已加载</div>

  <!-- v-show：适合高频切换 -->
  <div v-show="isVisible" class="modal">
    弹窗内容
  </div>
</template>

<script setup>
import { ref } from 'vue'

const isLoggedIn = ref(false)
const username = ref('')
const status = ref('loading')
const isVisible = ref(false)
</script>

<template>
  <!-- ✅ 推荐：使用唯一标识 -->
  <li v-for="item in items" :key="item.id">{{ item.text }}</li>

  <!-- ❌ 不推荐：使用 index -->
  <li v-for="(item, index) in items" :key="index">{{ item.text }}</li>

  <!-- ❌ 不推荐：无 key -->
  <li v-for="item in items">{{ item.text }}</li>
</template>

<template>
  <div>
    <p v-for="(item, index) in items" :key="index">
      <input v-model="item.value" />
    </p>
    <button @click="addItem">在最前面插入</button>
  </div>
</template>

<script setup>
import { ref } from 'vue'

const items = ref([
  { id: 1, value: 'A' },
  { id: 2, value: 'B' },
])

function addItem() {
  // 在最前面插入
  items.value.unshift({ id: 3, value: 'C' })
  // 问题：原来 key=0 的节点对应 id=1 的数据
  // 插入后 key=0 的节点对应 id=3 的数据（新数据）
  // 但 Vue 复用了原有节点，input 中显示的内容是 'C' 吗？
  // 实际上 input 内容不会被更新——因为 v-model 绑定的是 .value，而 key 复用时 DOM 节点复用导致 input 状态混乱
}
</script>

<script setup>
import { ref, onMounted } from 'vue'

const items = ref(['A', 'B', 'C'])
// 使用数组收集 v-for 中的 ref
const itemRefs = ref([])

onMounted(() => {
  console.log('所有列表项:', itemRefs.value)
  itemRefs.value.forEach(el => {
    console.log('高度:', el.offsetHeight)
  })
})
</script>

<template>
  <ul>
    <li
      v-for="item in items"
      :key="item"
      :ref="(el) => { if (el) itemRefs.push(el) }"
    >
      {{ item }}
    </li>
  </ul>
</template>

<!-- ChildComponent.vue -->
<script setup>
import { ref } from 'vue'

const internalCount = ref(0)

function sayHello() {
  return 'Hello from child'
}

function increment() {
  internalCount.value++
}

// 只有显式暴露的才能在父组件通过模板 ref 访问
defineExpose({
  sayHello,
  increment,
})
</script>

<template>
  <div>子组件: {{ internalCount }}</div>
</template>