在 Vue 的声明式渲染模型中，我们通常无需直接操作 DOM——Vue 会自动处理 DOM 的更新与维护。但在某些场景下（如设置输入框焦点、初始化第三方 DOM 库、获取元素尺寸等），我们需要直接访问底层 DOM 元素或子组件实例。此时，模板引用（Template Refs） 就是实现这一需求的核心工具。

一、基础用法：访问 DOM 元素

模板引用通过特殊的 ref 属性实现：在模板中为元素添加 ref 属性并指定标识，再在逻辑中通过 Vue 提供的 API 获取该元素的直接引用。

1. 基本语法（Vue 3.5+：useTemplateRef）

Vue 3.5 及以上版本推荐使用 useTemplateRef 辅助函数获取模板引用，用法简洁且类型推断更友好：

 <script setup>
 import { useTemplateRef, onMounted } from 'vue'
 
 // 1. 用 useTemplateRef 声明引用：第一个参数必须与模板中 ref 的值一致
 // input 是一个 ref 对象，其 .value 会指向模板中对应的 DOM 元素
 const input = useTemplateRef('my-input')
 
 // 2. 在组件挂载后访问引用（此时 DOM 已存在）
 onMounted(() => {
   input.value.focus() // 调用 DOM 方法：设置输入框焦点
 })
 </script>
 
 <template>
   <!-- 3. 模板中为元素添加 ref 属性，值与 useTemplateRef 的参数匹配 -->
   <input ref="my-input" />
 </template>

核心逻辑：

• useTemplateRef('my-input') 会创建一个 ref 对象（input），Vue 会自动将模板中 ref="my-input" 的元素赋值给 input.value；
• 必须在 组件挂载后 访问 input.value——因为初次渲染前元素尚未创建，此时 input.value 为 null（onMounted 钩子会在组件挂载后触发，适合执行这类操作）。

2. Vue 3.5 前的用法（ref声明）

3.5 之前的版本需通过 ref 直接声明引用变量，变量名需与模板中 ref 的值一致：

 <script setup>
 import { ref, onMounted } from 'vue'
 
 // 声明一个 ref 对象，变量名必须与模板中 ref 的值相同（这里是 "my-input"）
 const myInput = ref(null)
 
 onMounted(() => {
   myInput.value.focus() // 挂载后访问 DOM 元素
 })
 </script>
 
 <template>
   <input ref="my-input" /> <!-- ref 值与变量名对应 -->
 </template>

注意点： 无论使用 useTemplateRef 还是旧版 ref 声明，初次渲染时引用的 value 都是 null（元素未创建）。若需在渲染过程中动态处理（如元素可能被 v-if 卸载），需通过侦听器判断 value 是否存在：

 watchEffect(() => {
   if (input.value) {
     // 元素已挂载：执行操作（如设置焦点）
     input.value.focus()
   } else {
     // 元素未挂载或已卸载：做容错处理
     console.log('元素暂不存在')
   }
 })

二、组件上的 ref：访问子组件实例

模板引用不仅能用于 DOM 元素，还能用于子组件——此时引用的 value 会指向子组件的实例，可用于访问子组件的属性或方法。

1. 基本用法

 <script setup>
 import { useTemplateRef, onMounted } from 'vue'
 import Child from './Child.vue' // 导入子组件
 
 // 声明对子组件的引用：参数与模板中 ref 的值一致
 const childRef = useTemplateRef('child')
 
 onMounted(() => {
   // childRef.value 指向 <Child /> 组件的实例
   console.log('子组件实例：', childRef.value)
 })
 </script>
 
 <template>
   <!-- 子组件上添加 ref 属性 -->
   <Child ref="child" />
 </template>

2. 子组件的“可访问性”：defineExpose宏

子组件的可访问性取决于其是否使用 <script setup>：

• 未使用 <script setup> 的子组件（如选项式 API 组件）：父组件通过引用可访问子组件的所有属性和方法（与子组件的 this 完全一致）；
• 使用 <script setup> 的子组件：默认是“私有”的——父组件无法访问其内部的属性/方法，除非子组件通过 defineExpose 宏主动暴露。

示例：子组件通过 defineExpose 暴露内容

 <!-- Child.vue（子组件） -->
 <script setup>
 import { ref } from 'vue'
 
 // 子组件内部的状态和方法
 const a = 1 // 普通变量
 const b = ref(2) // ref 变量
 const handleClick = () => {
   console.log('子组件的方法被调用')
 }
 
 // 显式暴露需要被父组件访问的内容
 defineExpose({
   a, // 暴露普通变量
   b, // 暴露 ref 变量（父组件访问时会自动解包，无需 .value）
   handleClick // 暴露方法
 })
 </script>

父组件访问暴露的内容：

 <!-- 父组件 -->
 <script setup>
 import { useTemplateRef, onMounted } from 'vue'
 import Child from './Child.vue'
 
 const childRef = useTemplateRef('child')
 
 onMounted(() => {
   console.log(childRef.value.a) // 1（访问暴露的普通变量）
   console.log(childRef.value.b) // 2（访问暴露的 ref 变量，已自动解包）
   childRef.value.handleClick() // 调用暴露的方法：输出 "子组件的方法被调用"
 })
 </script>

注意点：

• defineExpose 必须在子组件的 同步代码 中调用（不能在 await 之后），否则父组件可能无法访问到暴露的内容；
• 应优先通过 props 和 emit 实现父子组件交互（更符合 Vue 的声明式思想），仅在必要时使用组件引用（避免父子组件耦合过紧）。