Vue 3.5 + TypeScript中useTemplateRef报“value is possibly null”错误排查

问题场景 #

使用useTemplateRef获取DOM引用后，直接调用其方法（如audioPlayer.value.play()）时，VS Code会抛出value is possibly null的类型错误。代码实际运行正常，但本地环境突然出现这个提示。示例代码如下：

Script 部分 #

<script setup lang="ts">
import { ref, useTemplateRef, reactive } from "vue";
import { PlayCircleIcon, StopCircleIcon } from "@heroicons/vue/24/solid";
import { gsap } from "gsap";

const audioPlayer = useTemplateRef("audio-player");
const seekBar = useTemplateRef("seek-bar");
const panelTrack = useTemplateRef("panel-track");
const trackIndex = ref<number>(0);
const currentTrack = ref<string>("");
const isPlaying = ref<boolean>(false);
const TRACK_WIDTH = 115;

const playlist = reactive([
    { artist: "Direct", song: "Direct - Abandon.mp3" },
    { artist: "Kubix", song: "Kubix - Run Away.mp3" }
])

const togglePlay = () => {
    isPlaying.value = !isPlaying.value;
    if (isPlaying.value) {
        audioPlayer.value.play(); // 此处触发"value is possibly null"提示
    } else {
        audioPlayer.value.pause(); // 此处触发"value is possibly null"提示
    }
    audioPlayer.value!.play(); // 添加非空断言后提示消失
}
</script>

Template 部分 #

<audio ref="audio-player" preload="metadata" v-on:loadedmetadata="setDurMaxForSeek"
        v-on:timeupdate="trackDurForSeek" v-on:ended="checkTrackIndex">
        <source :src="`@/assets/audio/${currentTrack}`" type="audio/mpeg" />
    </audio>

可能的原因 #

• Vue 3.5 类型定义更新：Vue 3.5对useTemplateRef的类型约束更严格，明确返回的Ref值可能为null（DOM元素可能未挂载或条件渲染下不存在）。
• TypeScript 配置变更：本地tsconfig.json中strictNullChecks被开启（或从false改为true），TypeScript空值检查逻辑更严格。
• VS Code TypeScript 服务更新：VS Code内置的TypeScript版本升级，对空值检查的规则更严谨。
• 依赖包版本升级：@vue/runtime-core或相关类型依赖包更新，导致类型定义发生变化。

解决办法 #

1. 空值判断（最安全） #

调用方法前先判断DOM引用是否存在，TypeScript会自动收窄类型：

const togglePlay = () => {
    isPlaying.value = !isPlaying.value;
    if (!audioPlayer.value) return; // 先确认DOM存在
    if (isPlaying.value) {
        audioPlayer.value.play();
    } else {
        audioPlayer.value.pause();
    }
}

2. 非空断言（便捷但需确保DOM存在） #

如果确定模板中该DOM元素一定会存在（无条件渲染逻辑），可以用非空断言!跳过检查：

audioPlayer.value!.play();

3. 类型断言 #

手动指定Ref的类型为非空DOM元素：

const audioPlayer = useTemplateRef<HTMLAudioElement>("audio-player") as Ref<HTMLAudioElement>;

4. 监听DOM挂载后再操作 #

使用watchPostEffect或onMounted确保DOM挂载完成后再执行操作：

import { watchPostEffect } from "vue";

watchPostEffect(() => {
    if (audioPlayer.value) {
        // 此处操作不会触发类型错误
    }
});

总结 #

这个提示是TypeScript严格类型检查的结果，并非代码运行错误。优先推荐空值判断保证类型安全，若确定DOM一定存在，非空断言是最快捷的处理方式。

内容的提问来源于stack exchange，提问作者Thomas James Thorstensson