企业官网建设流程全解析

做 Vue3 项目做久了，你会发现组件间通信里最“别扭”的一种需求，就是父组件点一个按钮，要把子组件里的数据一起拿走。比如用户填了一个收货地址子组件，父页面的“提交订单”按钮要把地址、备注、配送方式一起打包提交，这时候你用 props 传值不合适，用 emit 又得一通倒腾，最直接的办法就是像老 Vue2 那样，给子组件挂个 ref，然后直接去取子组件的实例。但这个思路在 Vue3 里往往会撞上一堵墙：ref拿到的子组件实例确实是拿到了，可你想访问内部的数据和方法，结果全是undefined。

原因很多人都知道——<script setup>默认是“封闭”的，子组件不主动开放，父组件什么都摸不到。但具体怎么开放、开放什么、开放之后有哪些坑，网上资料比较散。我这次就把 Vue3 组件间通信里“ref 子组件需要把父组件要的 ref 数据开放”这个场景彻底讲透，从原理到实操，再到我踩过的几个坑，一次性说清楚。适合正在用 Vue3 + 组合式 API 写业务、又被父子组件数据收集问题卡住的同学参考。

1. 先说清楚：这里的“ref”到底是哪个 ref

很多人一看到“ref”就默认是响应式数据那个ref()，其实 Vue3 里有两个完全不同的 ref，使用场景天差地别，必须先分清。

1.1 响应式 ref 和模板引用 ref 的区别

第一个是import { ref } from 'vue'创建出来的响应式引用，用来让普通变量具备响应式能力，比如const count = ref(0)，在模板中自动解包，在脚本里用count.value取值。这类 ref 解决的是“数据变了视图要更新”的问题。

第二个是模板里的ref="xxx"属性，它叫模板引用，解决的是“我要拿到真实的 DOM 元素或者子组件实例”的问题。比如：

<input ref="inputRef" />

const inputRef = ref(null) onMounted(() => { inputRef.value.focus() })

本文标题里说的“ref 子组件”，指的就是第二种——父组件通过ref="childRef"拿到子组件实例，进而访问子组件内部的数据或方法。

1.2 父组件为什么拿不到子组件的“数据”

在 Vue2 时代，this.$refs.child几乎能拿到子组件所有东西，因为选项式 API 的实例上挂满了 data、methods、computed。但 Vue3 的组合式 API 不一样，<script setup>里的局部变量、函数默认都是“私有的”，不会自动挂到组件实例上。

打个比方：Vue2 的子组件是一间敞开的屋子，父组件推门就能看到屋里所有家具；Vue3 的<script setup>子组件是一间上锁的屋子，外面能看到门牌号（组件名），但里面摆了什么，只有屋子里的人主动从窗户递出来，外面才拿得到。

这个“递出来”的动作，就是defineExpose。

1.3 典型场景：点提交前，父组件要收子组件的值

这类需求在后台管理系统里特别多。我做的一个订单确认页就是典型：父组件是订单页，里面有一个收货地址子组件、一个配送方式子组件、一个备注子组件，页面底部一个“提交订单”按钮。点击提交时，父组件需要一次性把三个子组件里的数据收上来，加上父组件自己的数据，一起 POST 给后端。

如果只用 props 和 emit，得给每个子组件写一堆事件监听，数据流很碎。用 ref + defineExpose，逻辑就非常集中：父组件拿三个子组件实例，逐个调用它们的getData()方法，收集返回值。这也是我最推荐的“父组件主动取数”方案。

2. 核心方案：用 defineExpose 把接口开放出来

既然<script setup>默认封闭，那子组件就得明确告诉父组件：“我能给你什么”。这个机制就是defineExpose。

2.1 defineExpose 长什么样

defineExpose是 Vue3.2 开始提供的编译宏，不需要 import，直接在<script setup>顶层调用即可。它接收一个对象，对象里的属性就是对外开放的“接口”：

<script setup> import { ref } from 'vue' const formData = ref({ name: '', phone: '' }) const submit = () => { console.log('submit from child') } defineExpose({ formData, submit }) </script>

父组件拿到子组件实例后，可以直接访问childRef.value.formData和childRef.value.submit()。

注意一个细节：formData是一个ref，但通过defineExpose暴露出去之后，父组件访问childRef.value.formData拿到的是自动解包后的值，不需要再写.value。Vue 的模板引用访问公开实例时，会对暴露的 ref 做 unwrap 处理，这点和模板里的自动解包行为一致。

2.2 暴露数据的三种姿势

根据业务需要，子组件对外开放的内容一般有三种形式：直接暴露响应式数据、暴露只读计算属性、暴露方法来让父组件主动调用。

第一种，直接暴露响应式数据，适合父组件需要“实时看到子组件内部状态”的场景。比如父组件要根据子组件里是否勾选了某个选项来控制按钮禁用状态，那直接暴露一个ref或者reactive对象就很方便：

const selected = ref('') defineExpose({ selected })

父组件可以watch(childRef.value.selected)，或者用computed派生状态。

第二种，暴露computed，适合要给父组件一个“加工后”的数据，比如格式化后的价格、拼接好的地址字符串。子组件内部是原始数据，但对外给一个更好用的只读视图：

const province = ref('浙江') const city = ref('杭州') const address = computed(() => `${province.value}${city.value}`) defineExpose({ address })

父组件拿到childRef.value.address就是“浙江杭州”这个字符串。

第三种，暴露方法，适合“父组件主动触发子组件行为”的场景。比如父组件点提交，调用子组件的validate()、getData()。这也是我在实际项目里用得最多的方式。

2.3 为什么我更推荐暴露方法而不是暴露数据

很多初学者喜欢把整个formData直接defineExpose出去，父组件想改就改。我一开始也这么干，后来发现问题很多：子组件的校验逻辑没法约束父组件；数据被父组件改动后，子组件的内部状态可能就不一致了；代码越写越乱，边界模糊。

后来我改成“方法优先”的原则：子组件只暴露一个getData()方法，方法内部做校验、整理、返回一个干净的数据对象。父组件只需要调用这个方法，不用关心子组件内部怎么存数据。就好比你去餐厅点餐，不需要进后厨自己端菜，叫服务员送出来就行。子组件是后厨，getData()就是服务员。

这样做还有一个好处：如果后面子组件的数据结构改了，父组件调用方式不变，只要getData()的返回值兼容就行，耦合度低很多。

3. 实战案例：父组件提交时收集所有子组件的值

理论说再多，不如一个完整案例来得实在。我拿之前说的订单确认页举例，从子组件到父组件完整写一遍。

3.1 场景设定：订单确认页

页面结构是这样的：

• OrderPage.vue：父组件，负责整体布局和提交。
• AddressForm.vue：子组件，收货人、手机号、详细地址。
• RemarkForm.vue：子组件，订单备注。

父组件点击“提交订单”时，需要把地址子组件和备注子组件的数据都拿过来，加上父组件的配送方式，一起提交。

3.2 子组件 AddressForm 的实现

地址子组件里，我习惯把“取数据”和“校验”都封装成一个方法，对外只开一个口子：

<template> <div class="address-form"> <input v-model="form.name" placeholder="收货人" /> <input v-model="form.phone" placeholder="手机号" /> <input v-model="form.detail" placeholder="详细地址" /> </div> </template> <script setup> import { reactive } from 'vue' const form = reactive({ name: '', phone: '', detail: '' }) const getData = () => { if (!form.name || !form.phone || !form.detail) { throw new Error('请填写完整的收货信息') } return { ...form } } defineExpose({ getData }) </script>

这里有几个细节值得注意：getData里做校验，如果数据不完整直接抛异常；返回的是{ ...form }的浅拷贝，而不是内部响应式对象的引用，防止父组件拿到后意外改动子组件内部状态。这些都是我踩过坑之后总结出来的习惯。

备注子组件RemarkForm.vue更简单，结构类似，对外暴露getData()返回备注文本。

3.3 父组件 OrderPage 的实现

父组件用模板 ref 挂两个子组件，提交时依次调用：

<template> <div class="order-page"> <AddressForm ref="addressRef" /> <RemarkForm ref="remarkRef" /> <button @click="handleSubmit">提交订单</button> </div> </template> <script setup> import { ref } from 'vue' import AddressForm from './AddressForm.vue' import RemarkForm from './RemarkForm.vue' const addressRef = ref(null) const remarkRef = ref(null) const deliveryType = ref('express') const handleSubmit = async () => { try { const address = addressRef.value.getData() const remark = remarkRef.value.getData() const payload = { address, remark, deliveryType: deliveryType.value } // 调用提交接口 console.log('submit payload:', payload) } catch (error) { alert(error.message) } } </script>

提交流程非常清晰：先让所有子组件各自校验并返回数据，再统一组装，最后提交。如果某个子组件校验不通过，抛出的异常会在父组件的catch里被拦截，终止提交逻辑。

这里要注意，addressRef.value在组件挂载之前是null，所以点击提交的方法里最好加个判空，或者用addressRef.value?.getData()。实际业务里按钮点击一般都在挂载之后，问题不大，但以防万一，加上更稳。

3.4 遇到 v-for 多实例怎么处理

比单实例更麻烦的是，如果父组件里一个子组件被v-for渲染了多份，ref 的收集方式会不一样。我印象很深的一个场景是 PDF 预览，每个 PDF 页面都渲染一个pdf子组件，模板长这样：

<pdf v-for="i in numPages" :key="i" :ref="setPdfRef" :page="i" :src="url" />

这里如果直接用ref="pdfRef"，Vue3 在v-for中会把所有实例收集成一个数组，pdfRef.value就是一个包含多个子组件实例的数组。这个行为本身没问题，但有个坑：数组不是响应式的，而且如果v-for渲染的列表是异步获取的，ref 数组的收集时机需要特别小心。

更稳妥的做法是用函数 ref，自己控制收集逻辑：

const pdfRefs = ref([]) const setPdfRef = (el) => { if (el) { pdfRefs.value.push(el) } }

但函数 ref 也有自己的坑：子组件卸载时，Vue 会回调一次 null，所以if (el)的判断是对的；但要是列表动态变化，旧的实例不会被自动清掉，需要再配合手动重置。我实际处理时会在数据源变化前先pdfRefs.value = []，再让新的子组件渲染，避免数组残留脏数据。

如果是 Vue 3.2.25 以上的版本，直接ref="pdfRefs"再搭配watch监听pdfRefs.value.length，在nextTick之后去访问实例，也是一种简洁可靠的方案。无论哪种方式，核心原则都是一样：等子组件真正挂载完成后再取实例，否则拿到的就是空数组。

4. 实操中高频踩坑与排查清单

这部分是正文，是网上教程很少写细的东西。这些坑我基本都踩过，整理成一个排查清单，按“现象 → 原因 → 解决”的思路写。

4.1 ref 拿到 null 的五大原因

父组件里childRef.value一直是null，是出现频率最高的问题。排查顺序一般是：

一是子组件还没渲染。如果子组件被v-if控制，条件为 false 时自然拿不到实例，需要等条件变成 true 且 DOM 更新后再取。

二是取值的时机太早。onMounted里拿是没问题的，但如果在setup同步代码里直接访问，一定拿不到。要拿，至少等到onMounted，或者用nextTick。我之前写过一段在watch里马上访问 ref 的代码，也必须加nextTick才能拿到。

三是父组件和子组件之间有异步边界。比如子组件是异步组件，或者被Suspense包裹，它的挂载时机比普通组件晚。遇到这种情况，可以用watch监听 ref 的变化，等它不再是 null 时再操作。

四是ref写在了v-for上，拿到的不是单个实例而是数组。这个之前提过了，别再当成单实例访问了。

五是子组件没有正确暴露。如果你在子组件里用了<script setup>但没写defineExpose，那父组件拿到实例后访问内部成员都会是undefined，不是 null。现象不同，原因也不同。

4.2 defineExpose 不生效？查版本和写法

defineExpose虽然好用，但有几个前置条件。第一个是 Vue 版本，这是 3.2 才有的编译宏，老项目要是还在用 3.1.x，那肯定不行。建议项目锁定 Vue 版本至少 3.2.0，最好升级到 3.4+ 之后的版本，各种细节体验都会好很多。

第二个是写法位置。defineExpose必须在<script setup>顶层调用，不能写在某个函数里，否则不生效：

// 错误写法 const init = () => { defineExpose({ getData }) // 编译报错或警告 } // 正确写法 defineExpose({ getData })

第三个是拼写。Expose首字母大写，写成了defineExpose会被当成普通变量，静默失败，很难排查。

如果真的怀疑暴露没生效，可以在父组件里打印一下childRef.value.$.exposed，这是 Vue 内部存放暴露对象的字段，能直接看到当前实例对外开放了哪些内容：

console.log(addressRef.value.$.exposed)

这个方法我试过很多次，排查效率极高。

4.3 v-for 的 ref 数组不是响应式的

前面提到过，Vue3 里v-for配合ref="xxx"会自动收集成数组，但这个数组的更新时机和响应式系统是异步关联的，可能你watch到数据源变化了，ref数组还没来得及更新，这时候访问就是旧数据。

我的建议是：如果依赖ref数组做业务判断，尽量在watch回调里加nextTick；如果发现数组长度不对，先别急着怀疑 Vue 出了问题，检查一下是不是子组件还没全部挂载完，尤其是在异步渲染场景下。PDF 多页预览这种场景，我最后是用了一个loading标志，等所有页面实例都收集完成后才允许用户操作，实践下来很稳定。

4.4 模板 ref 和响应式 ref 千万别同名

这个问题很隐蔽，一旦踩了非常浪费时间。假如你写了：

const childRef = ref(null)

模板里又写了：

<ChildComponent :data="childRef" />

结果childRef被当成你要传给子组件的值，而不是一个模板引用。更常见的情况是，模板里一个元素写ref="inputRef"，脚本里又定义了一个const inputRef = ref('')，两边就会互相覆盖，导致你拿到的不对。

命名规范上我给自己定了一个约定：模板引用统一用xxxRef结尾，响应式数据用xxxData或者不带 Ref 后缀，从名字上直接区分。比如addressFormRef是模板引用，formData是响应式数据，基本不会混淆。

4.5 动态组件和 KeepAlive 的 ref 问题

用<component :is="...">动态切换组件时，ref 的行为和普通组件不太一样。每次切换，ref会指向当前活跃的组件实例；如果切走了，实例会被销毁，ref 变回 null。KeepAlive缓存的情况下，切回来时 ref 又能重新拿到实例，但要注意不能假设实例一直存在。

异步组件defineAsyncComponent也有一个常见坑：组件还在加载时，ref.value是 null，加载完成后才会赋值。所以在onMounted里直接访问异步子组件实例，很可能拿到 null。正确做法是监听 ref 变化，或者等异步组件触发resolve回调后再取。

5. 一些实战经验补充

最后这部分，分享几个我经过多个项目沉淀下来的设计和协作习惯，不一定都是硬技术，但能帮你少走弯路。

5.1 子组件的“开放面”设计：最小权限原则

子组件对外暴露什么，应该像后端设计接口一样讲究。我建议遵循最小权限原则：只暴露父组件真正需要的东西，不要图省事把整个reactive对象都甩出去。

我看过有些同事的子组件里，defineExpose把内部十几个方法和数据全部暴露了，父组件可以随意改子组件的内部状态，最后 bug 出来了很难定位是谁改的。接口一旦变大，组件的内聚性就会变差，后续维护成本直线上升。

我现在的习惯是：一个子组件对外最多暴露三到五个接口，其中必然有一个getData()，如果有校验需求就再加一个validate()，有重置需求就加一个reset()，其他内部逻辑一律不外放。这样父组件用起来清爽，子组件自己也好维护。

5.2 什么时候可以不用 defineExpose

defineExpose不是万能的，也不该是所有组件间通信问题的标准答案。如果你的场景是“父组件的数据要实时反映到子组件”，那用props更自然；如果是“子组件的数据变化要通知父组件”，那emit是标准方案；如果是多层级嵌套传递，provide / inject更合适；如果是多个互不相干的组件共享同一个状态，Pinia才是正解。

我自己的判断标准也很简单：如果只是偶尔一次性取子组件的值，用ref + defineExpose；如果需要频繁双向联动，优先考虑v-model或Pinia。工具没有高下之分，适合场景才是最好的。像订单确认页这种“提交时收一次数据”的场景，defineExpose就是最顺手的方案，没必要强行上 Pinia。

5.3 团队协作的约定：让组件接口清晰可维护

项目一旦多人协作，组件暴露接口的一致性就很关键。我目前的团队里约定了一套规则：所有通过defineExpose暴露的方法名必须是动词，比如getData、validate、reset、focus；暴露的数据属性名必须是名词，比如formData、selectedItem。这样父组件调用时，从名字就能判断这是个操作还是取值，代码可读性会好很多。

另外，如果用了 TypeScript，建议给暴露接口定义类型并导出。比如子组件里定义：

export interface AddressFormExpose { getData: () => { name: string phone: string detail: string } validate: () => boolean } defineExpose<AddressFormExpose>({ getData, validate })

父组件里可以这样引用：

const addressRef = ref<AddressFormExpose | null>(null)

这样 IDE 提示、类型检查全都跟得上，重构的时候也不会因为改了子组件接口而满屏报错。这个方法实际用下来，对团队的协作效率提升非常明显。

我在实际项目中还有一个习惯：每次给子组件加新的 exposed 接口之前，都会先问自己一句“这个接口从父组件的视角看，语义是否清晰”。如果父组件调用时要翻回子组件源码才能理解，那说明这个接口设计得还不够好。组件通信这件事，本质上是在控制数据流的边界和可见性，边界清晰了，代码自然就好维护了。