Vue 3 模板引用（Template Refs）详解与实战示例

引言

在 Vue 开发中，通常推荐使用 响应式数据 (ref 和 reactive) 进行数据绑定，而不是直接操作 DOM。但是，在某些情况下，我们确实需要访问某个组件或 DOM 元素，这时候就可以使用 模板引用（Template Refs）。

本篇文章将详细介绍 Vue 3 的 ref 模板引用的用法、适用场景，并通过多个示例展示如何在 Vue 组件中高效操作 DOM 和组件实例。

1. 什么是 Vue 模板引用？

模板引用（Template Refs） 允许我们在 Vue 组件的模板中标记一个 DOM 元素或子组件，并在 setup 选项中访问它。

基本语法

<template><div ref="myDiv">Hello Vue!</div>
</template><script setup>
import { ref, onMounted } from 'vue';const myDiv = ref(null); // 定义模板引用onMounted(() => {console.log(myDiv.value); // 获取 DOM 元素
});
</script>

说明：

ref="myDiv" 绑定到 myDiv 变量
onMounted 钩子确保 myDiv.value 在 DOM 渲染完成后可用

2. 模板引用的使用场景

✅ 操作原生 DOM

当我们需要手动操作 DOM 时，如获取元素的宽高、设置焦点等：

<template><input ref="inputRef" type="text" placeholder="输入内容"><button @click="focusInput">聚焦输入框</button>
</template><script setup>
import { ref } from 'vue';const inputRef = ref(null);const focusInput = () => {inputRef.value.focus(); // 手动聚焦输入框
};
</script>

✅ 获取子组件实例

可以使用 ref 访问子组件的方法和数据：

<!-- 子组件 (Child.vue) -->
<template><div>子组件</div>
</template><script setup>
import { ref } from 'vue';const message = ref("Hello from Child Component!");const sayHello = () => {console.log(message.value);
};defineExpose({ sayHello }); // 允许父组件访问 `sayHello`
</script>

<!-- 父组件 -->
<template><Child ref="childRef" /><button @click="callChildMethod">调用子组件方法</button>
</template><script setup>
import { ref, onMounted } from 'vue';
import Child from './Child.vue';const childRef = ref(null);onMounted(() => {console.log(childRef.value); // 获取子组件实例
});const callChildMethod = () => {childRef.value.sayHello(); // 调用子组件方法
};
</script>

defineExpose：Vue 3 需要使用 defineExpose 公开组件方法，否则父组件无法访问。

3. 使用 `ref` 访问多个元素

当我们需要访问多个 DOM 元素时，可以使用 ref 结合 v-for：

<template><div v-for="(item, index) in list" :key="index" ref="itemRefs">{{ item }}</div><button @click="logElements">查看所有元素</button>
</template><script setup>
import { ref, onMounted } from 'vue';const list = ref(["Vue", "React", "Angular"]);
const itemRefs = ref([]); // 存储多个 DOM 元素onMounted(() => {console.log(itemRefs.value); // 所有 div 的 DOM 元素
});const logElements = () => {itemRefs.value.forEach(el => console.log(el.textContent));
};
</script>

注意：ref 数组会在 onMounted 之后才填充值。

4. 访问 `setup()` 之外的数据

如果你在 setup() 之外使用 ref，可以通过 getCurrentInstance() 获取 Vue 实例：

<script setup>
import { getCurrentInstance, onMounted } from 'vue';onMounted(() => {const instance = getCurrentInstance();console.log(instance.refs); // 访问 ref
});
</script>