文档库

Appearance

模板引用 ​

虽然 Vue 的声明性渲染模型为你抽象了大部分对 DOM 的直接操作，但在某些情况下，我们仍然需要直接访问底层 DOM 元素。要实现这一点，我们可以使用特殊的 ref attribute：

vue
<input ref="input">

ref 是一个特殊的 attribute。它允许我们在一个特定的 DOM 元素或子组件实例被挂载后，获得对它的直接引用。这可能很有用，比如说在组件挂载时将焦点设置到一个 input 元素上，或在一个元素上初始化一个第三方库。

访问模板引用 ​

ref ​

在 3.5 之前的版本尚未引入 useTemplateRef()，我们需要声明一个与模板里 ref attribute同名的引用：

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

// 声明一个 ref 来存放该元素的引用
// 必须和模板里的 ref 同名
const input = ref(null)

onMounted(() => {
  input.value.focus()
})
</script>

<template>
  <input ref="input" />
</template>

在组件挂载后才能访问模板引用

注意，你只可以在组件挂载后才能访问模板引用。如果你想在模板中的表达式上访问 input，在初次渲染时会是 null。这是因为在初次渲染前这个元素还不存在。

如果你需要侦听一个模板引用 ref 的变化，确保考虑到其值为 null 的情况：

ts
watchEffect(() => {
  if (input.value) {
    input.value.focus()
  } else {
    // 此时还未挂载，或此元素已经被卸载(例如通过 v-if 控制)
  }
})

useTemplateRef 3.5 ​

要在组合式 API 中获取引用，我们可以使用辅助函数useTemplateRef

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

// 第一个参数必须与模板中的 ref 值匹配
const input = useTemplateRef('my-input')

onMounted(() => {
  input.value.focus()
})
</script>

<template>
  <input ref="my-input" />
</template>

在使用 TypeScript 时，Vue 的 IDE 支持和 vue-tsc 将根据匹配的 ref attribute 所用的元素或组件自动推断 input.value 的类型，因此可以不必使用泛型指定组件类型。

组件上的ref ​

模板引用也可以被用在一个子组件上。这种情况下引用中获得的值是组件实例：

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

const childRef = useTemplateRef('child')

onMounted(() => {
  // childRef.value 将持有 <Child /> 的实例
})
</script>

<template>
  <Child ref="child" />
</template>

如果一个子组件使用的是选项式 API 或没有使用 <script setup>，被引用的组件实例和该子组件的 this 完全一致，这意味着父组件对子组件的每一个属性和方法都有完全的访问权。这使得在父组件和子组件之间创建紧密耦合的实现细节变得很容易，当然也因此，应该只在绝对需要时才使用组件引用。大多数情况下，你应该首先使用标准的 props 和 emit 接口来实现父子组件交互。

有一个例外的情况，使用了 <script setup> 的组件是默认私有的：一个父组件无法访问到一个使用了 <script setup> 的子组件中的任何东西，除非子组件在其中通过 defineExpose 宏显式暴露：

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

const a = 1
const b = ref(2)

// 像 defineExpose 这样的编译器宏不需要导入
defineExpose({
  a,
  b
})
</script>

警告

defineExpose 必须在任何 await 之前执行，确保它在编译阶段完整收集到暴露接口。

同名ref ​

多个 ref 没有使用 v-for ​

vue
<Child ref="childRef" />
<Child ref="childRef" />

这种情况 不受支持且不可预期。 Vue 不会自动把它变成数组，结果通常是只有最后一个会覆盖前面同名的 ref。

危险

这种写法应该避免，会造成调试困难。

在 v-for 中同名 ref ​

当在 v-for 中使用模板引用时，对应的 ref 中包含的值是一个数组，它将在元素被挂载后包含对应整个列表的所有元素：

vue
<Child
  v-for="item in list"
  :key="item.id"
  ref="childRef"
/>
ts
onMounted(() => {
  console.log(childRef.value) // [comp1, comp2, ...]
  childRef.value[0].sayHello()
})

函数模板引用 ​

除了使用字符串值作名字，ref attribute 还可以绑定为一个函数，会在每次组件更新时都被调用。该函数会收到元素引用作为其第一个参数：

vue
<Child :ref="el => childRefMap[键名] = el" />

当绑定的元素被卸载时，函数也会被调用一次，此时的 el 参数会是 null。