Vue 3 组合式 API 快速上手

tianyuan Mon May 25 23:36:42 UTC 2026 27 次浏览前端

<p><strong>教程摘要</strong>：深入了解 Vue 3 Composition API 的核心概念和实战技巧，告别 Vue2 选项式 API 的代码混乱问题，零基础轻松上手组合式开发思路。</p>
<p>写在前面：很多刚从 Vue2 转 Vue3 的小伙伴，都会觉得组合式 API 看着陌生、不知道该怎么用。其实它一点都不高深，本质就是<strong>更灵活、更贴合业务的代码写法</strong>。这篇教程不讲空话，用最通俗的话、最实用的案例，带你快速吃透核心用法。</p>
<h2>一、什么是组合式 API</h2>
<p>Vue 3 组合式 API（Composition API），是 Vue3 主推的一套全新代码编写风格。</p>
<p>用过 Vue2 的同学都知道，我们之前写组件，必须按照 <code>data</code>、<code>methods</code>、<code>computed</code>、<code>watch</code> 这些固定选项拆分代码。</p>
<p>这就会出现一个很头疼的问题：<strong>同一个业务的代码，被拆得七零八落</strong>。比如一个用户列表功能，数据在 data、方法在 methods、监听在 watch，翻看代码来回跳转，项目大了极其难维护。</p>
<p>而组合式 API 完美解决了这个问题！它<strong>以函数为核心组织逻辑</strong>，我们可以把同一个业务的所有数据、方法、监听写在一起，逻辑高度聚合，还能轻松抽离复用，写代码更自由、更高效。</p>
<h2>二、组合式 API 核心函数（新手必掌握）</h2>
<p>组合式 API 的核心常用函数主要有这几个，吃透它们，基本能搞定 90% 的日常开发需求，新手不用死记硬背，结合场景理解即可。</p>
<h3>1. ref：基础类型响应式</h3>
<p>专门用来给 <strong>数字、字符串、布尔值</strong> 这类基础数据做响应式。<br>小细节：在 script 内部修改值需要加 <code>.value</code>，模板里直接使用变量即可，不用写 <code>.value</code>。</p>
<h3>2. reactive：引用类型响应式</h3>
<p>专门适配 <strong>对象、数组</strong> 这类复杂数据，不用写 <code>.value</code>，直接打点修改属性，更贴合日常对象操作习惯。</p>
<h3>3. computed：计算属性</h3>
<p>基于已有响应式数据衍生新数据，自带 <strong>缓存机制</strong>。依赖的数据不变，它就不会重复计算，性能特别好，适合做数据筛选、换算、拼接等场景。</p>
<h3>4. watch：数据侦听器</h3>
<p>用来监听数据变化，数据变了就自动执行回调函数。适合处理数据变动后的副作用，比如数据更新后请求接口、打印日志、修改其他数据等。</p>
<blockquote>
<p>? 实用小提醒：</p>
<ol>
<li>本案例中我们监听的是对象里的 <code>age</code> 基础数值，不额外配置也能正常监听；</li>
<li>如果直接监听整个 <code>reactive</code> 响应式对象，<strong>必须开启深度监听</strong>，也就是配置 <code>{ deep: true }</code>，否则对象内部属性变化无法被捕获。</li>
</ol>
</blockquote>
<h3>5. 拓展：watchEffect（选学）</h3>
<p>这也是开发中高频用到的 API，不过对于纯新手来说不用优先掌握。<br>它和 <code>watch</code> 用法有区别：无需手动指定监听目标，函数内部用到了哪些响应式数据，就会自动监听这些数据，数据变化就会触发执行，使用起来更加简洁。</p>
<h2>三、新手入门实战示例（可直接复制运行）</h2>
<p>下面所有案例都基于 Vue3 最主流的 <strong>script setup 语法糖</strong>，写法简洁、企业项目通用，直接复制到项目里就能跑。</p>
<h3>案例1：ref + computed 基础计数器</h3>
<p>最经典的入门案例，快速理解响应式和计算属性的联动效果</p>
<pre><code class="language-vue">&lt;template&gt;
  &lt;div class=&quot;demo&quot;&gt;
    &lt;p&gt;当前计数：{{ count }}&lt;/p&gt;
    &lt;p&gt;双倍计数（计算属性）：{{ doubleCount }}&lt;/p&gt;
    &lt;button @click=&quot;addCount&quot;&gt;点我+1&lt;/button&gt;
  &lt;/div&gt;
&lt;/template&gt;

&lt;script setup&gt;
// 导入核心API
import { ref, computed } from &quot;vue&quot;

// 定义响应式基础数据
const count = ref(0)

// 计算属性：依赖count自动计算，自带缓存
const doubleCount = computed(() =&gt; {
  return count.value * 2
})

// 自定义方法：修改响应式数据
const addCount = () =&gt; {
  // script内修改ref值必须加.value
  count.value++
}
&lt;/script&gt;
</code></pre>
<h3>案例2：reactive + watch 数据监听实战</h3>
<p>适配对象类型数据，同时演示<strong>深度监听</strong>的用法</p>
<pre><code class="language-vue">&lt;template&gt;
  &lt;div class=&quot;demo&quot;&gt;
    &lt;p&gt;用户名：{{ user.name }}&lt;/p&gt;
    &lt;p&gt;用户年龄：{{ user.age }}&lt;/p&gt;
    &lt;button @click=&quot;growUp&quot;&gt;年龄涨一岁&lt;/button&gt;
  &lt;/div&gt;
&lt;/template&gt;

&lt;script setup&gt;
import { reactive, watch } from &quot;vue&quot;

// 定义响应式对象，无需.value，直接操作属性
const user = reactive({
  name: &quot;Vue新手&quot;,
  age: 18
})

// 写法1：监听对象内单个属性，无需 deep
watch(
  () =&gt; user.age,
  (newVal, oldVal) =&gt; {
    console.log(`年龄更新啦！旧值：${oldVal}，新值：${newVal}`)
  }
)

// 写法2：直接监听整个 reactive 对象，必须开启 deep: true
/*
watch(user, (newVal) =&gt; {
  console.log(&quot;用户信息发生变化&quot;, newVal)
}, { deep: true })
*/

// 修改对象数据
const growUp = () =&gt; {
  user.age++
}
&lt;/script&gt;
</code></pre>
<h3>案例3：拓展 - watchEffect 简单演示</h3>
<p>简单感受下 <code>watchEffect</code> 的使用方式，供有需要的同学参考</p>
<pre><code class="language-vue">&lt;template&gt;
  &lt;p&gt;计数：{{ num }}&lt;/p&gt;
  &lt;button @click=&quot;num++&quot;&gt;点击加1&lt;/button&gt;
&lt;/template&gt;

&lt;script setup&gt;
import { ref, watchEffect } from &quot;vue&quot;

const num = ref(0)

// 自动收集内部依赖的响应式数据，数据变化就执行
watchEffect(() =&gt; {
  console.log(`当前数值为：${num.value}`)
})
&lt;/script&gt;
</code></pre>
<h2>四、为什么推荐用组合式 API？（真实开发感悟）</h2>
<p>用过两种写法后，真心觉得组合式 API 更适配中大型项目，优势特别明显：</p>
<ul>
<li><strong>逻辑更聚拢</strong>：同一业务的变量、方法、监听写在一起，不用在各个选项之间来回翻代码，阅读和修改都更省心</li>
<li><strong>复用更简单</strong>：可以把通用逻辑抽成独立的 <code>useXXX</code> 函数，多个组件直接复用，不用重复写冗余代码</li>
<li><strong>适配TS更好</strong>：天然支持 TypeScript 类型推导，写大型项目几乎不会出现类型报错问题</li>
<li><strong>写法更自由</strong>：不用被 Vue2 固定的选项结构束缚，按需编写代码，灵活度拉满</li>
</ul>
<h2>五、新手避坑小总结</h2>
<p>最后给新手梳理几个高频踩坑点，帮大家少走弯路：</p>
<ol>
<li><strong>ref 勿忘 .value</strong>：只有在 <code>&lt;script&gt;</code> 内部修改数据需要加 <code>.value</code>，模板 template 中直接使用变量即可</li>
<li><strong>reactive 对象监听规则</strong>：单独监听对象某个属性，无需深度监听；直接监听整个响应式对象，务必配置 <code>{ deep: true }</code></li>
<li><strong>按需选择 API</strong>：<code>watchEffect</code> 属于进阶用法，新手先吃透 <code>ref</code>、<code>reactive</code>、<code>computed</code>、<code>watch</code> 四大核心函数即可</li>
<li><strong>新旧写法兼容</strong>：Vue3 完全兼容选项式 API，不用全盘推翻旧写法，循序渐进学习就好</li>
<li><strong>场景化选型</strong>：简单的展示型组件，用基础写法完全够用；逻辑复杂、功能繁多的组件，优先使用组合式 API</li>
</ol>