Vue 3.5 新特性：useTemplateRef 更优雅地获取 DOM

useTemplateRef（Vue 3.5）

Vue 3.5 引入了 useTemplateRef 这个新 API，用于更优雅地获取模板中的 DOM 元素或组件实例。

---

• 旧方案的问题
• useTemplateRef 解决方案
• Vue3.5 前后对比
• 总结

---

旧方案的问题

在 Vue 3 中，传统获取 DOM 的方式是手动定义 ref 变量，并在模板中通过 ref="xxx" 绑定。

<template>
  <h1 ref="titleRef">标题</h1>
</template>

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

// 变量名必须和模板中 ref 的值完全一致
const titleRef = ref<HTMLElement | null>(null)

onMounted(() => {
  console.log(titleRef.value?.innerText)
})
</script>

这种写法有两个明显的痛点：

1. 变量名强绑定：模板中的字符串 ref="titleRef" 和脚本中的变量名 titleRef 必须保持一致，否则无法关联。
2. 无法自动推导类型：需要手动标注 HTMLElement 等类型，如果元素是 <h1>，理想类型应该是 HTMLHeadingElement，但手动标注通常只会写宽泛的 HTMLElement。

---

useTemplateRef 解决方案

Vue 3.5 的 useTemplateRef 让模板和脚本之间的绑定逻辑更直观。

<template>
  <h1 ref="title">标题</h1>
</template>

<script setup>
import { useTemplateRef, onMounted } from 'vue'

// 通过字符串获取模板中的 ref，变量名可以自由定义
const myTitle = useTemplateRef('title')

onMounted(() => {
  // 自动推导为 HTMLHeadingElement
  console.log(myTitle.value?.innerText)
})
</script>

这种写法的核心变化：

• 模板中直接写 ref="title"，类似原生 document.getElementById('title') 的习惯。
• 脚本中通过 useTemplateRef('title') 获取对应的 DOM 元素，变量名可以任意取，不需要和模板中的 ref 值保持一致。
• 支持自动类型推导，Vue 能识别出 <h1> 对应的是 HTMLHeadingElement，可以直接访问该元素特有的属性和方法。

---

Vue3.5 前后对比

	旧方案（ref 绑定）	新方案（useTemplateRef）
模板写法	ref="titleRef"	ref="title"
脚本写法	const titleRef = ref(null)	const myTitle = useTemplateRef('title')
变量名是否强绑定	是，必须和模板一致	否，可自由命名
类型推导	需要手动标注	自动推导具体元素类型
使用习惯	需要理解 Vue 的响应式 ref 机制	更接近 document.getElementById 的习惯

---

总结

useTemplateRef 是 Vue 3.5 对模板引用机制的一次体验优化。它解决了旧方案中变量名强绑定和类型推导不足的问题，让 DOM 获取方式更贴近原生习惯。对于已经熟悉 Vue 3 ref 机制的人来说，旧方案依然可用；但对于新项目或追求更简洁代码的场景，useTemplateRef 是更好的选择。