Vue 3.5 辅助函数useTemplateRef

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

<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 所用的元素或组件自动推断 inputRef.value 的类型。

在无法自动推断的情况下，仍然可以通过泛型参数将模板 ref 转换为显式类型。

const input = useTemplateRef<HTMLInputElement>(null)

为了获取导入组件的实例类型，我们需要先通过 typeof 获取其类型，然后使用 TypeScript 的内置 InstanceType 工具提取其实例类型：

<!-- App.vue -->
<script setup lang="ts">
import { useTemplateRef } from 'vue'
import Foo from './Foo.vue'
import Bar from './Bar.vue'


type FooType = InstanceType<typeof Foo>
type BarType = InstanceType<typeof Bar>


const compRef = useTemplateRef<FooType | BarType>('comp')
</script>


<template>
  <component :is="Math.random() > 0.5 ? Foo : Bar" ref="comp" />
</template>

3.5 前的用法

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

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


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


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


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

如果不使用 <script setup>，需确保从 setup() 返回 ref：

export default {
  setup() {
    const input = ref(null)
    // ...
    return {
      input
    }
  }
}

模板引用需要通过一个显式指定的泛型参数和一个初始值 null 来创建：

const input = ref<HTMLInputElement | null>(null)

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

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

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