Vue / 系统课时
模板引用与组件实例
模板引用与组件实例
模板引用解决的是“声明式渲染之后,确实还需要访问具体对象”的场景。本课把原生 DOM、子组件公开能力和第三方实例分开处理,并用 TypeScript 明确引用类型,避免到处使用类型断言或直接依赖子组件内部实现。
学习目标
- 使用带类型的模板引用安全访问真实 DOM
- 通过公开接口调用子组件能力,而不是穿透其内部状态
- 正确保存和销毁第三方组件或类实例
模板引用连接的是不同类型的对象
模板里的 ref 看起来写法相同,但运行后可能得到完全不同的对象:原生标签返回 HTMLElement 或其子类型;Vue 子组件返回组件公开实例;第三方库通常还需要先拿到一个宿主 DOM,再自行创建库实例。把三者都声明成宽泛的 any,会直接失去 TypeScript 的保护价值。

原生 DOM 引用要接受初始空值
组件挂载以前,模板对应的真实元素还不存在,所以模板引用的类型通常包含 null。例如输入框应声明为 ref<HTMLInputElement | null>(null),使用时通过空值判断或可选链访问,而不是使用非空断言假设元素永远存在。
DOM 引用适合完成聚焦、读取尺寸、对接只能接收真实元素的库等操作。普通文本、样式和显隐状态仍应优先通过响应式数据与模板完成,不应因为能拿到 DOM 就退回手工修改页面。
子组件只暴露父组件真正需要的能力
使用 <script setup> 的子组件默认不会把内部变量全部开放给父组件。需要被父组件调用的方法,可以使用 defineExpose 明确形成公共接口。
下面是片段示例 ChildPanel.vue,它由后面的父组件导入,因此不作为独立入口运行。
<script setup lang="ts">
import { ref } from 'vue'
const refreshCount = ref(0)
function refresh(): void {
refreshCount.value += 1
}
// 父组件只需要刷新能力,不暴露内部响应式状态。
defineExpose({ refresh })
</script>
<template>
<p>子组件刷新次数:{{ refreshCount }}</p>
</template>这种接口边界比父组件直接修改子组件内部状态更稳定。未来即使子组件重构状态结构,只要公开的 refresh() 契约不变,父组件就不需要跟着调整。
在父组件中统一管理三种引用
下面的 ParentPanel.vue 同时演示输入框 DOM、子组件公开方法以及一个模拟第三方控件实例。真实项目中只需把 DemoWidget 替换成具体库提供的类或工厂函数。
<script setup lang="ts">
import { onMounted, onUnmounted, ref, shallowRef } from 'vue'
import ChildPanel from './ChildPanel.vue'
interface ChildPanelExpose {
refresh(): void
}
class DemoWidget {
constructor(private readonly host: HTMLElement) {
this.host.textContent = '第三方实例已就绪'
}
destroy(): void {
this.host.textContent = ''
}
}
const inputRef = ref<HTMLInputElement | null>(null)
const childRef = ref<ChildPanelExpose | null>(null)
const widgetHostRef = ref<HTMLDivElement | null>(null)
const widgetInstance = shallowRef<DemoWidget | null>(null)
function focusInput(): void {
inputRef.value?.focus()
}
function refreshChild(): void {
childRef.value?.refresh()
}
onMounted(() => {
// 第三方实例依赖真实宿主元素,只在挂载完成后创建。
if (widgetHostRef.value) {
widgetInstance.value = new DemoWidget(widgetHostRef.value)
}
})
onUnmounted(() => {
// 外部实例由当前组件创建,因此也由当前组件负责销毁。
widgetInstance.value?.destroy()
widgetInstance.value = null
})
</script>
<template>
<input ref="inputRef" value="可聚焦输入框" />
<button @click="focusInput">聚焦输入框</button>
<ChildPanel ref="childRef" />
<button @click="refreshChild">刷新子组件</button>
<div ref="widgetHostRef"></div>
</template>预期结果
页面初始显示输入框、两个按钮、子组件刷新次数 0,以及“第三方实例已就绪”。
点击“聚焦输入框”后,输入框获得焦点。
每点击一次“刷新子组件”,刷新次数增加 1。
父组件卸载时,DemoWidget.destroy() 被调用并释放宿主元素内容。第三方类实例通常不需要被 Vue 深度转换为响应式代理,因此示例使用 shallowRef 保存它。业务真正需要响应式展示的字段可以单独提取成 ref 或 computed,而不是让整个外部对象进入深层响应式系统。
避免把组件实例当成内部对象入口
组件引用最危险的用法,是父组件拿到实例后开始依赖大量内部字段和方法。这样虽然短期方便,却会让父子组件形成隐式耦合。更稳妥的方式是把公开接口限制为少量业务动作,例如 open()、close()、validate()、refresh(),并为引用声明明确的 TypeScript 接口。
无论引用最终指向 DOM、子组件还是外部实例,都应同时考虑两个边界:挂载之前它可能不存在,卸载之后也不应继续使用。类型中的 null、挂载时机和资源清理共同构成了模板引用真正的安全边界。