Vue3 标签的 ref 属性：直接访问 DOM 和组件实例

我叫张小白。2025-12-02 9:59

本文是 Vue3 系列第六篇，将深入探讨 Vue3 中标签的 ref 属性。ref 属性就像是给元素或组件贴上的"名片"，让我们能够直接访问它们。理解 ref 属性的工作原理和使用场景，能够让我们在需要直接操作 DOM 或组件实例时更加得心应手。

一、作用在 HTML 标签上的 ref

传统 DOM 操作的问题

在传统的 Web 开发中，我们经常使用 document.getElementById 或 document.querySelector 来获取 DOM 元素。但在 Vue 的组件化开发中，这种方法会遇到一些问题。

让我们通过一个具体的例子来理解这个问题：

html 复制代码 
<!-- 父组件 Parent.vue -->
<template>
  <div>
    <div id="myElement">父组件的元素</div>
    <ChildComponent />
  </div>
</template>

<script setup lang="ts">
import ChildComponent from './ChildComponent.vue'

// 在父组件中获取元素
const getElement = () => {
  const element = document.getElementById('myElement')
  console.log('父组件获取的元素:', element)
}
</script>

问题分析：

当你运行这个示例并点击子组件的按钮时，会发现一个奇怪的现象：子组件获取到的居然是父组件的元素！这是因为：

  1. getElementById 是在整个文档范围内查找元素

  2. 当找到第一个匹配的 id 时就返回

  3. 由于父组件的元素先出现，所以总是返回父组件的元素

这种全局查找的方式在组件化开发中很容易导致冲突和难以调试的问题。

Vue 的 ref 属性解决方案

Vue 提供了 ref 属性来解决这个问题。ref 属性创建的是一个"局部引用"，只在当前组件实例内有效，不会与其他组件冲突。

基本语法和使用方法：

html 复制代码 
<template>
  <div>
    <div ref="myElement">这是一个元素</div>
    <button @click="handleClick">获取元素</button>
  </div>
</template>

<script setup lang="ts">
import { ref, onMounted } from 'vue'

// 创建 ref - 名称必须与模板中的 ref 属性值一致
const myElement = ref<HTMLElement | null>(null)

const handleClick = () => {
  console.log('获取到的元素:', myElement.value)
  console.log('元素内容:', myElement.value?.textContent)
}

onMounted(() => {
  // 在组件挂载后，ref 会被自动填充
  console.log('组件挂载后的元素:', myElement.value)
})
</script>

详细步骤解析：

  1. 在模板中设置 ref 属性 ：给元素添加 ref="myElement" 属性

  2. 在脚本中声明同名 ref ：使用 const myElement = ref(null) 声明响应式引用

  3. 自动关联 ：Vue 会自动将 DOM 元素赋值给 myElement.value

  4. 访问元素 ：通过 myElement.value 访问实际的 DOM 元素

关键特性：

  • 局部作用域：每个组件实例都有自己的 ref 作用域

  • 自动管理：Vue 自动处理 ref 的绑定和更新

  • 类型安全：可以使用 TypeScript 类型注解

  • 响应式：ref 本身是响应式的，但指向的 DOM 元素不是响应式的

解决之前的问题

现在让我们用 ref 属性重写之前的例子：

html 复制代码 
<!-- 父组件 Parent.vue -->
<template>
  <div>
    <div ref="parentElement">父组件的元素</div>
    <ChildComponent />
    <button @click="getElement">父组件获取元素</button>
  </div>
</template>

<script setup lang="ts">
import { ref } from 'vue'
import ChildComponent from './ChildComponent.vue'

const parentElement = ref<HTMLElement | null>(null)

const getElement = () => {
  console.log('父组件获取的元素:', parentElement.value)
  console.log('元素内容:', parentElement.value?.textContent)
}
</script>
html 复制代码 
<!-- 子组件 ChildComponent.vue -->
<template>
  <div>
    <div ref="childElement">子组件的元素</div>
    <button @click="getElement">子组件获取元素</button>
  </div>
</template>

<script setup lang="ts">
import { ref } from 'vue'

const childElement = ref<HTMLElement | null>(null)

const getElement = () => {
  console.log('子组件获取的元素:', childElement.value)
  console.log('元素内容:', childElement.value?.textContent)
}
</script>

问题解决：

现在，父组件和子组件各自获取到自己的元素，互不干扰。这就是 ref 属性的威力所在：

  1. 作用域隔离：每个组件的 ref 都在自己的作用域内

  2. 无冲突：不同组件可以使用相同的 ref 名称

  3. 更好的封装性：组件内部细节被更好地封装

二、作用在组件上的 ref

基本用法和现象

ref 属性不仅可以作用在 HTML 元素上，还可以作用在 Vue 组件上。这让我们能够访问子组件的实例。

让我们先看看基本的用法：

html 复制代码 
<!-- 父组件 Parent.vue -->
<template>
  <div>
    <ChildComponent ref="childRef" />
    <button @click="inspectChild">检查子组件</button>
  </div>
</template>

<script setup lang="ts">
import { ref } from 'vue'
import ChildComponent from './ChildComponent.vue'

const childRef = ref<InstanceType<typeof ChildComponent> | null>(null)

const inspectChild = () => {
  console.log('子组件实例:', childRef.value)
  console.log('子组件的属性:', childRef.value?.$props)
  console.log('子组件的方法:', childRef.value?.$options.methods)
}
</script>
html 复制代码 
<!-- 子组件 ChildComponent.vue -->
<template>
  <div>
    <p>子组件内容</p>
    <p>计数: {{ count }}</p>
    <button @click="increment">增加</button>
  </div>
</template>

<script setup lang="ts">
import { ref } from 'vue'

const count = ref(0)

const increment = () => {
  count.value++
}

const reset = () => {
  count.value = 0
}
</script>

现象分析：

当你运行这个示例并点击"检查子组件"按钮时，会发现一个重要的现象：父组件虽然获取到了子组件的实例，但无法访问子组件内部定义的 count 数据和 increment、reset 方法。

控制台输出显示：

  • 可以访问到一些 Vue 内部的实例属性和方法（如 $props、$el）

  • 但无法访问子组件中自定义的响应式数据和方法

这是因为在使用 <script setup> 语法时，组件内部的定义默认是私有的，不会暴露给父组件。

使用 defineExpose 暴露内容

为了解决这个问题，Vue 提供了 defineExpose 编译器宏，允许子组件显式地暴露哪些内容可以被父组件访问。

defineExpose 的基本用法：

html 复制代码 
<!-- 子组件 ChildComponent.vue -->
<template>
  <div>
    <p>子组件内容</p>
    <p>计数: {{ count }}</p>
    <p>消息: {{ message }}</p>
    <button @click="increment">增加计数</button>
    <button @click="updateMessage">更新消息</button>
  </div>
</template>

<script setup lang="ts">
import { ref } from 'vue'

const count = ref(0)
const message = ref('初始消息')

const increment = () => {
  count.value++
}

const updateMessage = () => {
  message.value = `消息更新时间: ${new Date().toLocaleTimeString()}`
}

const reset = () => {
  count.value = 0
  message.value = '初始消息'
}

// 使用 defineExpose 暴露需要让父组件访问的内容
defineExpose({
  count,
  message,
  increment,
  updateMessage,
  reset
})
</script>
html 复制代码 
<!-- 父组件 Parent.vue -->
<template>
  <div>
    <ChildComponent ref="childRef" />
    <button @click="inspectChild">检查子组件</button>
    <button @click="callChildMethod">调用子组件方法</button>
    <button @click="modifyChildData">修改子组件数据</button>
  </div>
</template>

<script setup lang="ts">
import { ref } from 'vue'
import ChildComponent from './ChildComponent.vue'

const childRef = ref<InstanceType<typeof ChildComponent> | null>(null)

const inspectChild = () => {
  console.log('子组件计数:', childRef.value?.count)
  console.log('子组件消息:', childRef.value?.message)
}

const callChildMethod = () => {
  // 调用子组件暴露的方法
  childRef.value?.increment()
  childRef.value?.updateMessage()
}

const modifyChildData = () => {
  // 直接修改子组件暴露的数据
  if (childRef.value) {
    childRef.value.count = 100
    childRef.value.message = '父组件修改的消息'
  }
}
</script>

defineExpose 的详细解释：

工作原理：

  1. 选择性暴露 ：子组件使用 defineExpose 明确指定哪些数据和方法可以被外部访问

  2. 类型安全：暴露的内容会获得正确的 TypeScript 类型推断

  3. 响应式保持：暴露的响应式数据仍然保持响应式特性

使用注意事项：

  • 只有通过 defineExpose 暴露的内容才能被父组件访问

  • 暴露的数据和方法会合并到组件实例上

  • 建议只暴露必要的接口，保持组件的封装性

defineExpose 的高级用法

defineExpose 不仅可以暴露简单的数据和方法，还可以暴露计算属性、复杂的对象等。

html 复制代码 
<!-- 子组件 AdvancedChild.vue -->
<template>
  <div>
    <p>用户: {{ user.name }} ({{ user.age }}岁)</p>
    <p>状态: {{ status }}</p>
    <p>计算信息: {{ computedInfo }}</p>
  </div>
</template>

<script setup lang="ts">
import { ref, reactive, computed } from 'vue'

const user = reactive({
  name: '张三',
  age: 25
})

const status = ref('active')

const computedInfo = computed(() => {
  return `${user.name}是${user.age}岁，状态: ${status.value}`
})

const updateUser = (newUser: { name: string; age: number }) => {
  Object.assign(user, newUser)
}

const changeStatus = (newStatus: string) => {
  status.value = newStatus
}

const getUserInfo = () => {
  return {
    name: user.name,
    age: user.age,
    status: status.value,
    computedInfo: computedInfo.value
  }
}

// 暴露复杂的内容
defineExpose({
  // 响应式数据
  user,
  status,
  
  // 计算属性
  computedInfo,
  
  // 方法
  updateUser,
  changeStatus,
  getUserInfo,
  
  // 复杂对象
  config: {
    version: '1.0.0',
    features: ['auth', 'profile']
  }
})
</script>
html 复制代码 
<!-- 父组件 AdvancedParent.vue -->
<template>
  <div>
    <AdvancedChild ref="childRef" />
    <button @click="testExposedContent">测试暴露的内容</button>
  </div>
</template>

<script setup lang="ts">
import { ref } from 'vue'
import AdvancedChild from './AdvancedChild.vue'

const childRef = ref<InstanceType<typeof AdvancedChild> | null>(null)

const testExposedContent = () => {
  if (!childRef.value) return
  
  console.log('用户数据:', childRef.value.user)
  console.log('状态:', childRef.value.status)
  console.log('计算信息:', childRef.value.computedInfo)
  console.log('配置:', childRef.value.config)
  
  // 调用方法
  childRef.value.updateUser({ name: '李四', age: 30 })
  childRef.value.changeStatus('inactive')
  
  // 获取信息
  const userInfo = childRef.value.getUserInfo()
  console.log('用户信息:', userInfo)
}
</script>

高级用法的关键点：

  1. 响应式对象：暴露的 reactive 对象仍然保持响应式

  2. 计算属性：暴露的计算属性可以正常访问

  3. 复杂结构：可以暴露任意复杂的数据结构

  4. 方法调用：暴露的方法可以正常调用，保持正确的 this 绑定

三、ref 属性的实际应用场景

表单焦点管理

html 复制代码 
<template>
  <div>
    <input ref="inputRef" v-model="text" placeholder="请输入内容" />
    <button @click="focusInput">聚焦输入框</button>
    <button @click="selectAllText">全选文本</button>
  </div>
</template>

<script setup lang="ts">
import { ref, onMounted } from 'vue'

const inputRef = ref<HTMLInputElement | null>(null)
const text = ref('')

const focusInput = () => {
  inputRef.value?.focus()
}

const selectAllText = () => {
  inputRef.value?.select()
}

onMounted(() => {
  // 组件挂载后自动聚焦
  inputRef.value?.focus()
})
</script>

组件间通信和协作

html 复制代码 
<!-- 表单组件 FormComponent.vue -->
<template>
  <form @submit.prevent="handleSubmit">
    <input v-model="formData.name" placeholder="姓名" />
    <input v-model="formData.email" placeholder="邮箱" />
    <button type="submit">提交</button>
    <button type="button" @click="clearForm">清空</button>
  </form>
</template>

<script setup lang="ts">
import { reactive } from 'vue'

const formData = reactive({
  name: '',
  email: ''
})

const handleSubmit = () => {
  console.log('提交数据:', formData)
  alert('表单已提交!')
}

const clearForm = () => {
  formData.name = ''
  formData.email = ''
}

const validate = () => {
  const errors = []
  if (!formData.name) errors.push('姓名不能为空')
  if (!formData.email.includes('@')) errors.push('邮箱格式不正确')
  return errors
}

// 暴露给父组件的方法
defineExpose({
  clearForm,
  validate,
  getFormData: () => ({ ...formData })
})
</script>
html 复制代码 
<!-- 父组件 FormContainer.vue -->
<template>
  <div>
    <FormComponent ref="formRef" />
    <button @click="validateForm">验证表单</button>
    <button @click="clearForm">清空表单</button>
    <button @click="getFormData">获取表单数据</button>
  </div>
</template>

<script setup lang="ts">
import { ref } from 'vue'
import FormComponent from './FormComponent.vue'

const formRef = ref<InstanceType<typeof FormComponent> | null>(null)

const validateForm = () => {
  const errors = formRef.value?.validate()
  if (errors && errors.length > 0) {
    alert('验证错误: ' + errors.join(', '))
  } else {
    alert('表单验证通过!')
  }
}

const clearForm = () => {
  formRef.value?.clearForm()
}

const getFormData = () => {
  const data = formRef.value?.getFormData()
  console.log('表单数据:', data)
}
</script>

四、ref 属性的注意事项和最佳实践

1. 访问时机的重要性

html 复制代码 
<template>
  <div ref="divRef">内容</div>
</template>

<script setup lang="ts">
import { ref, onMounted } from 'vue'

const divRef = ref<HTMLElement | null>(null)

// 错误：在 setup 中立即访问，此时元素还未挂载
console.log('Setup 中访问:', divRef.value) // null

onMounted(() => {
  // 正确：在 mounted 生命周期中访问
  console.log('Mounted 中访问:', divRef.value) // 实际的 DOM 元素
})
</script>

2. 条件渲染中的 ref

html 复制代码 
<template>
  <div>
    <button @click="show = !show">切换显示</button>
    <div v-if="show" ref="conditionalRef">条件渲染的内容</div>
    <button @click="accessRef">访问条件 ref</button>
  </div>
</template>

<script setup lang="ts">
import { ref } from 'vue'

const show = ref(false)
const conditionalRef = ref<HTMLElement | null>(null)

const accessRef = () => {
  if (conditionalRef.value) {
    console.log('Ref 存在:', conditionalRef.value)
  } else {
    console.log('Ref 不存在，元素可能被条件渲染隐藏了')
  }
}
</script>

3. v-for 中的 ref

html 复制代码 
<template>
  <div>
    <div 
      v-for="item in items" 
      :key="item.id"
      ref="itemRefs"
    >
      {{ item.name }}
    </div>
    <button @click="logRefs">打印 refs</button>
  </div>
</template>

<script setup lang="ts">
import { ref, onMounted } from 'vue'

const items = ref([
  { id: 1, name: '项目1' },
  { id: 2, name: '项目2' },
  { id: 3, name: '项目3' }
])

// v-for 中的 ref 会是一个数组
const itemRefs = ref<HTMLElement[]>([])

const logRefs = () => {
  console.log('Item refs:', itemRefs.value)
  console.log('Refs 数量:', itemRefs.value.length)
}
</script>

五、总结

通过本文的学习，相信你已经对 Vue3 中 ref 属性的使用有了全面的理解。

核心要点回顾

ref 属性是 Vue 中直接访问 DOM 元素和组件实例的重要工具。作用在 HTML 标签上时可以获取 DOM 元素，作用在组件上时可以获取组件实例，配合 defineExpose 可以暴露子组件的特定接口。

ref 在 HTML 标签上的关键理解

  1. 解决全局冲突：提供组件作用域内的元素引用

  2. 自动绑定：Vue 自动处理 ref 的绑定和更新

  3. 访问时机：需要在组件挂载后才能访问到 DOM 元素

ref 在组件上的关键理解

  1. 默认私有 ：使用 <script setup> 的组件默认不暴露内部实现

  2. 选择性暴露 ：使用 defineExpose 明确暴露需要公开的接口

  3. 类型安全：配合 TypeScript 获得良好的类型支持

关于 Vue3 的 ref 属性有任何疑问？欢迎在评论区提出，我们会详细解答！

相关推荐
渣波1 小时前
# TypeScript：给 JavaScript 穿上“防弹衣”的超能力语言
javascript·typescript
有点笨的蛋1 小时前
JavaScript 中的面向对象编程：从基础到继承
前端·javascript
北辰alk1 小时前
Vue动态加载路由完全指南：提升大型应用性能的利器
vue.js
2509_940880221 小时前
Spring Cloud GateWay搭建
android·前端·后端
一千柯橘1 小时前
Three.js 中的调试助手 OrbitControls + GUI
前端
一 乐1 小时前
购物商城|基于SprinBoot+vue的购物商城系统(源码+数据库+文档)
前端·javascript·数据库·vue.js·spring boot·后端
izx8881 小时前
ES6+ 核心语法精讲：让 JavaScript 更优雅、更强大
javascript
玥浛1 小时前
ELK.js 实战：大规模图布局性能优化方案
前端
特级业务专家1 小时前
React Fiber 和时间切片
前端
热门推荐
01GitHub 镜像站点02UV安装并设置国内源03安娜的档案(Anna’s Archive) 镜像网站/国内最新可访问入口（持续更新）04BongoCat - 跨平台键盘猫动画工具05Linux下V2Ray安装配置指南06本地部署阿里最新开源的Z-Image0746个Nano-banana 精选提示词，持续更新中08Meta第三代“分割一切”模型——SAM 3本地部署教程：首支持文本提示分割，400万概念、30毫秒响应，检测分割追踪一网打尽09【保姆级教程】免费使用Gemini3的5种方法！免翻墙/国内直连10Labelme从安装到标注：零基础完整指南