Vue3 defineExpose控制子组件暴露给父组件的方法

Vue 3 的 <script setup> 语法糖极大地简化了组件编写，但也带来了一个问题：组件内的变量和方法默认是私有的，父组件无法直接通过 ref 获取。为了解决这个问题，Vue 提供了 defineExpose 宏。通过它，你可以精确控制子组件向外暴露哪些内容，既满足了交互需求，又保障了组件的封装性。

创建子组件文件，例如 ChildComponent.vue。在这个组件中，我们将编写几个内部方法和变量，并决定哪些可以被外部访问。

编写以下代码：

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

// 这是一个内部变量，外部无法直接访问
const count = ref(0)

// 定义一个方法，用于增加计数
const addCount = () => {
  count.value++
  console.log(`当前计数: ${count.value}`)
}

// 定义一个私有方法，不打算暴露出去
const privateLog = () => {
  console.log('这是子组件的私有日志')
}

// 定义一个方法，用于重置计数
const resetCount = () => {
  count.value = 0
  console.log('计数已重置')
}

// 【核心步骤】使用 defineExpose 暴露指定的方法或变量
// 只有在这里列出的内容，父组件才能通过 ref 访问到
defineExpose({
  addCount,
  resetCount,
  // 也可以选择暴露变量
  count
})
</script>

<template>
  <div class="child-box">
    <p>子组件内部数值：{{ count }}</p>
  </div>
</template>
```

在上述代码中，`privateLog` 方法没有放入 `defineExpose`，因此它是完全私有的。只有 `addCount`、`resetCount` 和 `count` 变量被“导出”给了父组件。

---

**创建**父组件文件，例如 `ParentComponent.vue`。父组件需要通过模板引用来获取子组件的实例，并调用刚才暴露的方法。

**编写**以下代码：

```vue
<script setup>
import { ref } from 'vue'
import ChildComponent from './ChildComponent.vue'

// 1. 声明一个 ref，名称必须与模板中的 ref 属性值一致
// 注意：初始值通常设为 null
const childRef = ref(null)

// 2. 定义父组件的触发函数，通过 ref 调用子组件暴露的方法
const handleAdd = () => {
  if (childRef.value) {
    // 【关键步骤】使用 .value 访问组件实例，并调用子组件暴露的方法
    childRef.value.addCount()
  }
}

const handleReset = () => {
  if (childRef.value) {
    childRef.value.resetCount()
  }
}

// 尝试访问暴露的变量
const showChildCount = () => {
  if (childRef.value) {
    alert(`子组件的 count 值为: ${childRef.value.count}`)
  }
}
</script>

<template>
  <div class="parent-box">
    <h2>父组件控制台</h2>
    <!-- 3. 在子组件标签上绑定 ref -->
    <ChildComponent ref="childRef" />

    <div class="controls">
      <button @click="handleAdd">增加子组件计数</button>
      <button @click="handleReset">重置子组件计数</button>
      <button @click="showChildCount">查看子组件数值</button>
    </div>
  </div>
</template>

<style scoped>
.controls {
  margin-top: 20px;
  display: flex;
  gap: 10px;
}
button {
  padding: 8px 16px;
  cursor: pointer;
}
</style>

注意：childRef.value 在子组件挂载完成前是 null。因此，在调用方法前务必检查 childRef.value 是否存在，或者确保调用发生在 onMounted 钩子之后（例如点击事件触发时）。

为了更直观地理解父组件与子组件之间的调用流向，可以通过以下流程图查看数据交互过程。

在这个流程中，defineExpose 相当于在子组件的“大门”上开了一扇窗，允许父组件伸手进去操作特定的东西，而其他未被暴露的部分依然保持私密。

在实际开发中，了解暴露内容的范围非常重要。下表对比了未使用 defineExpose 与使用 defineExpose 的区别：

使用 defineExpose 时，建议只暴露必须被外部控制的逻辑（如表单验证、数据刷新、特定动画触发），而将内部状态计算保留在组件内部，以保持代码的整洁与可维护性。

排查常见错误时，请确认以下两点：

1. 父组件中的 ref 变量名是否与模板标签上的 ref 属性名完全一致。
2. 是否通过 .value 来访问子组件实例的方法。