Vue.js 的 ref 出現 null 錯誤

最近在寫 Vue.js 專案

使用 npm run build （或是 npx vite build）編譯成 production 程式後，執行會出錯

以下是我的程式碼：

<script setup lang="ts">
	let myDialog = ref<HTMLDialogElement>(null)
</script>
<template>
	<button @click="myDialog.showModal()">my btn</button>
	<dialog ref="myDialog"></dialog>
</template>

點下按鈕後，會出現以下兩種錯誤：

TypeError: Cannot read properties of undefined (reading 'refs')

TypeError: Cannot read properties of null (reading 'showModal')

Vue v3.5（含）以上的解法

這問題貌似在 v3.5 以下的版本不會遇到

根據 Vue.js 官網的說明——«TypeScriptwith Composition API #Typing Template Refs»，在 Vue.js v3.5（含）以上的版本，不建議使用 ref(null) 來處理 DOM

建議改成這樣：

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

	// myDialog 改成使用 useTemplateRef
	// useTemplateRef 的參數要和下面的 <dialog> 的 ref attribute 相同
	let myDialog= useTemplateRef<HTMLDialogElement>("my-dialog")
</script>
<template>
	<button @click="myDialog.showModal()">my btn</button>

	<!-- 由於上面 useTemplateRef 參數是 "my-dialog"，
	     這裡的 ref attribute 也要填相同的值-->
	<dialog ref="my-dialog"></dialog>
</template>

使用 Vue Component 的情況

延續上面的程式，如果我今天 my-dialog 不是 HTMLDialogElement ，而是 Vue Component的話……

<!-- simple-dialog.vue -->
<script setup lang="ts">
defineExpose({
	showModal: function(){ /* 中略 */},
	close: function(){ /* 中略 */ }
})
</script>

<template>
	<dialog><!-- 中略 --></dialog>
</template>

Component 的 function

要讓其 showModal、close 對應內部的 dialog 的 showModal、close，要這樣寫

<!-- simple-dialog.vue -->
<script setup lang="ts">
import { defineEmits, useTemplateRef } from 'vue';

let dialogElement = useTemplateRef<HTMLDialogElement>("my-dialog")


defineExpose({
	// 這邊不能寫成 dialogElement.showModal() / dialogElement.value.close()
	// 那樣寫會出現 “TypeError: Cannot read properties of null (reading 'showModal')”  
	showModal: function(){ dialogElement.value.showModal() },
	close: function(){ dialogElement.value.close() }
})
</script>

<template>
	<dialog ref="my-dialog"><!-- 中略 --></dialog>
</template>

使用 Vue Component

使用上面的 simple-dialog.vue 要這樣寫：

<script setup lang="ts">
	import { useTemplateRef } from 'vue'
	import SimpleDialog from "simple-dialog.vue"

	// 建立 SimpleDialogType 作為 simple-dialog.vue component 的類型別名
	type SimpleDialogType = InstanceType<typeof SimpleDialog>

	let myDialog= useTemplateRef<SimpleDialogType>("my-dialog")
</script>
<template>
	<button @click="myDialog.showModal()">my btn</button>

	<SimpleDialog ref="my-dialog"></SimpleDialog>
</template>

參考資料

TypeScript with composition API. (n.d.). Vue.js. Retrieved February 26, 2025, from https://vuejs.org/guide/typescript/composition-api.html