当前位置：首页 > news >正文

Vue 3 模板引用 (Template Refs)

news 2026/5/12 1:17:16

概念

模板引用是 Vue 3 中直接访问 DOM 元素或组件实例的方式。通过特殊的 ref 属性，可以在 JavaScript 中获取对模板中元素的直接引用。

基本用法

1. 创建和使用 ref

<template><div><!-- 在元素上使用 ref --><input ref="inputRef" type="text" /><button @click="focusInput">聚焦输入框</button></div>
</template><script setup>
import { ref, onMounted } from 'vue'// 创建 ref，名称需要与模板中的 ref 属性值一致
const inputRef = ref(null)const focusInput = () => {// 访问 DOM 元素
  inputRef.value.focus()
}onMounted(() => {// 组件挂载后，ref 才会被赋值console.log(inputRef.value) // <input type="text">
})
</script>

2. 在选项式 API 中使用

<template><div ref="divRef">这是一个 div 元素</div>
</template><script>
export default {mounted() {// 通过 this.$refs 访问console.log(this.$refs.divRef) // <div>这是一个 div 元素</div>
  }
}
</script>

引用组件实例

1. 引用子组件

<!-- 父组件 -->
<template><div><ChildComponent ref="childRef" /><button @click="callChildMethod">调用子组件方法</button></div>
</template><script setup>
import { ref } from 'vue'
import ChildComponent from './ChildComponent.vue'const childRef = ref(null)const callChildMethod = () => {// 调用子组件的方法
  childRef.value.someMethod()// 访问子组件的属性
  console.log(childRef.value.someProperty)
}
</script><!-- 子组件 ChildComponent.vue -->
<script setup>
import { ref, defineExpose } from 'vue'const someProperty = ref('子组件数据')const someMethod = () => {console.log('子组件方法被调用')
}// 需要显式暴露，父组件才能访问
defineExpose({someProperty,someMethod
})
</script>

动态 ref

<template><div v-for="item in items" :key="item.id"><!-- 动态 ref --><div :ref="el => { if (el) divRefs[item.id] = el }">{{ item.name }}</div></div>
</template><script setup>
import { ref, reactive } from 'vue'const items = ref([{ id: 1, name: 'Item 1' },{ id: 2, name: 'Item 2' }
])// 使用对象或 Map 存储多个 ref
const divRefs = reactive({})
</script>

ref 函数

<template><div><!-- 使用函数形式的 ref --><input :ref="setInputRef" type="text" /></div>
</template><script setup>
import { ref, onBeforeUpdate, onUpdated } from 'vue'let inputElement = nullconst setInputRef = (el) => {inputElement = el
}onBeforeUpdate(() => {// 在更新前清除 refinputElement = null
})onUpdated(() => {// 更新后重新设置 ref
  console.log(inputElement)
})
</script>

组合式 API 中的使用模式

1. 使用 ref 数组

<template><div><div v-for="i in 3" :key="i" :ref="el => { if (el) elementRefs[i-1] = el }">元素 {{ i }}</div></div>
</template><script setup>
import { ref, onMounted } from 'vue'const elementRefs = ref([])onMounted(() => {console.log(elementRefs.value) // [div, div, div]
})
</script>

2. ref 在响应式对象中

<script setup>
import { reactive, onMounted } from 'vue'const state = reactive({inputRef: null
})onMounted(() => {// 访问 reactive 对象中的 refif (state.inputRef) {state.inputRef.focus()}
})
</script><template><input ref="el => state.inputRef = el" type="text" />
</template>

最佳实践

访问时机：ref 在组件挂载后才可用，使用 onMounted 生命周期钩子确保安全访问
响应式：ref 本身是响应式的，但 ref 指向的 DOM 元素不是响应式的
类型安全：在 TypeScript 中为 ref 提供类型注解

// TypeScript 示例
import { ref } from 'vue'// HTML 元素 ref
const inputRef = ref<HTMLInputElement | null>(null)// 组件 ref（假设子组件有特定类型）
const childRef = ref<InstanceType<typeof ChildComponent> | null>(null)

避免过度使用：优先使用 Vue 的声明式数据驱动，必要时才使用 ref

常见应用场景

聚焦输入框
触发动画
集成第三方 DOM 库
测量元素尺寸
手动触发组件方法
文件上传控件

<template><div><!-- 文件上传示例 --><input ref="fileInput" type="file" style="display: none" @change="handleFileChange"/><button @click="triggerFileInput">选择文件</button></div>
</template><script setup>
import { ref } from 'vue'const fileInput = ref(null)const triggerFileInput = () => {fileInput.value.click()
}const handleFileChange = (event) => {const file = event.target.files[0]// 处理文件
}
</script>