Vue3 模板引用实战：4种获取 DOM 与组件实例的方法与最佳实践

Vue3 模板引用深度指南：4种高效获取DOM与组件实例的方法

在Vue3开发中，直接操作DOM元素或子组件实例是常见需求。不同于Vue2的this.$refs，Vue3提供了更灵活、类型安全的模板引用方式。本文将深入解析四种主流方法，帮助你在不同场景下选择最佳实践。

1. 基础ref绑定：最直接的引用方式

基础ref绑定是Vue3中最简单的模板引用方法。通过在模板元素上添加ref属性，并在<script setup>中声明同名变量，即可获得对该元素的引用。

<template> <input ref="inputRef" type="text" /> <button @click="focusInput">聚焦输入框</button> </template> <script setup lang="ts"> import { ref, onMounted } from 'vue' const inputRef = ref<HTMLInputElement | null>(null) onMounted(() => { // 组件挂载后，inputRef.value将指向实际的DOM元素 inputRef.value?.focus() }) function focusInput() { inputRef.value?.focus() } </script>

关键点解析：

• 使用ref(null)初始化引用变量，TypeScript类型标注为HTMLInputElement | null
• 引用变量名必须与模板中的ref属性值完全一致
• 在onMounted生命周期后才能安全访问DOM元素
• 使用可选链操作符?.避免未挂载时的空值错误

适用场景：

• 单个DOM元素的操作（聚焦、获取尺寸等）
• 简单组件交互场景
• 需要明确类型提示的开发环境

注意：在Vue 3.5+版本中，基础ref绑定会自动推断DOM元素的类型，无需显式类型标注。

2. v-for循环中的引用数组处理

当需要在循环中获取多个元素引用时，直接使用基础ref绑定会导致引用被覆盖。Vue3提供了两种解决方案：

方法一：父容器引用+children访问

<template> <div ref="listContainer" class="item-list"> <div v-for="(item, index) in items" :key="index" @click="highlightItem(index)" > {{ item }} </div> </div> </template> <script setup lang="ts"> import { ref } from 'vue' const items = ['Apple', 'Banana', 'Orange'] const listContainer = ref<HTMLDivElement | null>(null) function highlightItem(index: number) { const children = listContainer.value?.children if (children) { const target = children[index] as HTMLElement target.style.backgroundColor = '#ffeb3b' } } </script>

方法二：函数式ref收集

<template> <div v-for="(item, index) in items" :key="index" :ref="(el) => setItemRef(el, index)" > {{ item }} </div> </template> <script setup lang="ts"> import { ref } from 'vue' const items = ['Apple', 'Banana', 'Orange'] const itemRefs = ref<HTMLElement[]>([]) function setItemRef(el: HTMLElement | null, index: number) { if (el) { itemRefs.value[index] = el } } </script>

对比分析：

3. 函数式引用：动态引用处理的高级模式

函数式引用提供了更精细的DOM引用控制能力，特别适合以下场景：

• 条件渲染元素的引用获取
• 动态组件切换时的引用管理
• 需要自定义引用逻辑的复杂情况

<template> <div v-if="showEditor"> <textarea :ref="setEditorRef"></textarea> </div> <button @click="toggleEditor">切换编辑器</button> </template> <script setup lang="ts"> import { ref } from 'vue' const showEditor = ref(true) const editorRef = ref<HTMLTextAreaElement | null>(null) function setEditorRef(el: HTMLTextAreaElement | null) { editorRef.value = el if (el) { console.log('编辑器已挂载，可进行初始化操作') el.style.height = '300px' } else { console.log('编辑器已卸载，可进行清理操作') } } function toggleEditor() { showEditor.value = !showEditor.value } </script>

进阶技巧：封装可复用的引用逻辑

// useDynamicRef.ts import { ref } from 'vue' export function useDynamicRef<T extends HTMLElement>() { const elementRef = ref<T | null>(null) const setRef = (el: T | null) => { elementRef.value = el } return { elementRef, setRef } } // 在组件中使用 const { elementRef: editorRef, setRef: setEditorRef } = useDynamicRef<HTMLTextAreaElement>()

4. useTemplateRef：Vue 3.5+的现代化解决方案

Vue 3.5引入了useTemplateRef辅助函数，进一步简化了模板引用的使用：

<template> <input ref="myInput" /> <ChildComponent ref="child" /> </template> <script setup lang="ts"> import { useTemplateRef, onMounted } from 'vue' const myInput = useTemplateRef('myInput') const child = useTemplateRef('child') onMounted(() => { // 自动推断类型：myInput.value是HTMLInputElement myInput.value?.focus() // child.value是ChildComponent实例 console.log(child.value?.someMethod()) }) </script>

核心优势：

• 自动类型推断（无需手动声明类型）
• 模板与脚本间的名称一致性检查
• 更简洁的API设计
• 更好的IDE支持

版本兼容方案：

// 兼容Vue 3.5以下版本的封装 function useCompatibleTemplateRef<T extends HTMLElement | ComponentPublicInstance>( name: string ) { const el = ref<T | null>(null) const setRef = (node: any) => { el.value = node } return { ref: el, setRef } }

类型安全与最佳实践

TypeScript深度集成

// 组件实例类型定义 import ChildComponent from './ChildComponent.vue' // DOM元素引用 const divRef = ref<HTMLDivElement | null>(null) // 组件引用 const childRef = ref<InstanceType<typeof ChildComponent> | null>(null) // 函数式组件的引用处理 const functionalCompRef = ref<{ doSomething: () => void } | null>(null)

性能优化建议

1. 避免过度引用：只在必要时使用模板引用
2. 合理使用shallowRef：当不需要深度响应时
3. 及时清理引用：在组件卸载时置空引用
4. 防抖处理高频操作：如滚动事件监听

import { shallowRef, onUnmounted } from 'vue' // 使用shallowRef优化性能 const heavyObjectRef = shallowRef({ /* 大型对象 */ }) // 组件卸载时清理 onUnmounted(() => { heavyObjectRef.value = null })

常见问题解决方案

问题1：引用值为null

watchEffect(() => { if (inputRef.value) { // 安全操作 } else { // 处理未挂载情况 } })

问题2：动态组件引用

<template> <component :is="currentComponent" ref="dynamicCompRef" /> </template> <script setup lang="ts"> const currentComponent = ref('ComponentA') const dynamicCompRef = ref<ComponentPublicInstance | null>(null) </script>

问题3：与第三方库集成

import { onMounted } from 'vue' import Chart from 'chart.js' const chartRef = ref<HTMLCanvasElement | null>(null) let chartInstance: Chart | null = null onMounted(() => { if (chartRef.value) { chartInstance = new Chart(chartRef.value, { // 图表配置 }) } }) onUnmounted(() => { chartInstance?.destroy() })

通过掌握这四种模板引用方法，你可以在Vue3项目中游刃有余地处理各种DOM操作和组件交互场景。根据具体需求选择最适合的方案，结合TypeScript的类型系统，既能保证代码质量，又能提升开发效率。