Vue3 中的 defineExpose 完全指南

文章目录

- 关键背景（必看）
- 一、基础用法
- - [1. 子组件（暴露内容）](#1. 子组件（暴露内容）)
  - [2. 父组件（访问子组件）](#2. 父组件（访问子组件）)
- 二、核心特性
- [三、TypeScript 写法](#三、TypeScript 写法)
- 四、常见使用场景
- 五、注意事项
- 六、总结

defineExpose 是 Vue3 组合式 API <script setup> 中的专用编译宏，核心作用 ：在 <script setup> 语法糖下，主动暴露组件的属性和方法 ，让父组件可以通过 ref / $parent 访问子组件的成员。

关键背景（必看）

在普通的 Vue3 选项式 API 中，组件的属性和方法默认会暴露给父组件；

但在 <script setup> 语法糖下，组件默认是封闭的 ，所有变量、方法都不会自动暴露，父组件无法直接访问。

这就是 defineExpose 存在的意义。

一、基础用法

1. 子组件（暴露内容）

vue 复制代码

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

// 子组件内部数据
const count = ref(0)
// 子组件内部方法
const addCount = () => {
  count.value++
}

// 核心：使用 defineExpose 暴露属性/方法
defineExpose({
  count,
  addCount
})
</script>

<template>
  <div>子组件计数：{{ count }}</div>
</template>

2. 父组件（访问子组件）

通过 ref 获取子组件实例，调用暴露的方法/访问属性：

vue 复制代码

<!-- Parent.vue -->
<script setup>
import { ref } from 'vue'
import Child from './Child.vue'

// 获取子组件 DOM 实例
const childRef = ref(null)

// 调用子组件暴露的方法
const triggerChild = () => {
  // 访问子组件数据
  console.log('子组件count：', childRef.value.count)
  // 调用子组件方法
  childRef.value.addCount()
}
</script>

<template>
  <Child ref="childRef" />
  <button @click="triggerChild">调用子组件方法</button>
</template>

二、核心特性

无需导入 ：defineExpose 是编译宏，直接使用，不需要从 vue 中导入
精准暴露：只暴露你写在对象里的成员，未暴露的内容完全私有
TS 支持：可以配合类型注解，提供类型提示
仅适用于 <script setup>：普通选项式 API 不需要它

三、TypeScript 写法

vue 复制代码

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

const count = ref<number>(0)
const addCount = () => count.value++

// 带类型的暴露
defineExpose<{
  count: number
  addCount: () => void
}>()
</script>

四、常见使用场景

父组件主动调用子组件的方法（如表单重置、弹窗关闭、列表刷新）
父组件获取子组件的响应式数据
封装公共组件时，提供对外调用的 API

五、注意事项

不要过度暴露：只暴露必要的成员，保持组件封装性
挂载后才能访问 ：父组件必须在组件挂载完成后 （如 onMounted）才能访问子组件实例
与 defineProps / defineEmits 区分 ：
- defineProps：父 → 子传值
- defineEmits：子 → 父触发事件
- defineExpose：父 → 子主动调用成员

六、总结

<script setup> 组件默认封闭，必须用 defineExpose 暴露成员
语法：defineExpose({ 变量, 方法 })
父组件通过 ref 获取子组件实例，访问暴露的内容
仅用于组合式 API <script setup>，是组件通信的补充方案