知海

模板引用

Vue基础指南

模板引用 {#template-refs}

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

vue-html 复制代码 
<input ref="input">

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

访问模板引用 {#accessing-the-refs}

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

vue 复制代码 
<template>
  <input ref="my-input" />
</template>

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

3.5 前的用法

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

vue 复制代码 
<template>
  <input ref="input" />
</template>

如果不使用 `

```

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

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

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

也可参考：为模板引用标注类型

组件上的 ref {#ref-on-component}

这一小节假设你已了解组件的相关知识，或者你也可以先跳过这里，之后再回来看。

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

vue 复制代码 
<template>
  <Child ref="child" />
</template>
3.5 前的用法
vue 复制代码 
<template>
  <Child ref="child" />
</template>
vue 复制代码 
<script>
import Child from './Child.vue'

export default {
  components: {
    Child
  },
  mounted() {
    // this.$refs.child 是 <Child /> 组件的实例
  }
}
</script>

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

如果一个子组件使用的是选项式 API 或没有使用 `

复制代码 
当父组件通过模板引用获取到了该组件的实例时，得到的实例类型为 `{ a: number, b: number }` (ref 都会自动解包，和一般的实例一样)。

请注意，defineExpose 必须在任何 await 操作之前调用。否则，在 await 操作后暴露的属性和方法将无法访问。

TypeScript 用户请参考：[为组件的模板引用标注类型](/guide/typescript/composition-api#typing-component-template-refs) <sup class="vt-badge ts" />

</div>
<div class="options-api">

`expose` 选项可以用于限制对子组件实例的访问：

```js
export default {
  expose: ['publicData', 'publicMethod'],
  data() {
    return {
      publicData: 'foo',
      privateData: 'bar'
    }
  },
  methods: {
    publicMethod() {
      /* ... */
    },
    privateMethod() {
      /* ... */
    }
  }
}

在上面这个例子中，父组件通过模板引用访问到子组件实例后，仅能访问 publicData 和 publicMethod。

v-for 中的模板引用 {#refs-inside-v-for}

需要 v3.5 及以上版本

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

vue 复制代码 
<template>
  <ul>
    <li v-for="item in list" ref="items">
      {{ item }}
    </li>
  </ul>
</template>

在演练场中尝试一下

3.5 前的用法

在 3.5 版本以前，useTemplateRef() 尚未引入，需要声明一个与模板引用 attribute 同名的 ref。该 ref 的值需要是一个数组。

vue 复制代码 
<template>
  <ul>
    <li v-for="item in list" ref="itemRefs">
      {{ item }}
    </li>
  </ul>
</template>

当在 v-for 中使用模板引用时，相应的引用中包含的值是一个数组：

vue 复制代码 
<script>
export default {
  data() {
    return {
      list: [
        /* ... */
      ]
    }
  },
  mounted() {
    console.log(this.$refs.items)
  }
}
</script>

<template>
  <ul>
    <li v-for="item in list" ref="items">
      {{ item }}
    </li>
  </ul>
</template>

在演练场中尝试一下

应该注意的是，ref 数组并不保证与源数组相同的顺序。

函数模板引用 {#function-refs}

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

vue-html 复制代码 
<input :ref="(el) => { /* 将 el 赋值给一个数据属性或 ref 变量 */ }">

注意我们这里需要使用动态的 :ref 绑定才能够传入一个函数。当绑定的元素被卸载时，函数也会被调用一次，此时的 el 参数会是 null。你当然也可以绑定一个组件方法而不是内联函数。

帮助我们改进文档

发现翻译问题或内容错误？请告诉我们。