Vue / 系统课时
依赖注入与跨层通信
依赖注入与跨层通信
当祖先组件需要把主题、权限、表单上下文等能力传给深层后代时,逐层透传 props 会让中间组件承担无关接口。本节用 provide、inject 和 InjectionKey 建立类型安全的跨层上下文,并把可变状态的写入口收敛到提供方。
学习目标
- 使用
provide与inject在祖先和深层后代之间传递上下文 - 用
InjectionKey<T>约束注入值的 TypeScript 类型 - 通过只读状态与命令函数控制跨层状态的修改边界
跨层通信的核心边界
provide 不是全局状态容器,而是沿组件祖先链向下提供依赖。后代调用 inject 时,会从最近的同名提供者取得值;中间组件不需要声明 props,也不需要手工转发。
适合注入的通常是“上下文”:主题、表单控制器、权限能力、局部服务实例等。一次性的父子数据传递仍优先使用 props 和 emits,因为它们的来源更显式,也更容易追踪。

用 InjectionKey 建立类型契约
主示例把主题状态放在祖先组件中,并只向后代暴露只读状态和修改命令。以下文件需要放在同一个 Vue 3 + TypeScript 项目中运行。
片段示例(theme-context.ts,定义共享契约):
import type { InjectionKey, Ref } from 'vue'
export interface ThemeContext {
theme: Readonly<Ref<'light' | 'dark'>>
toggleTheme: () => void
}
export const themeKey: InjectionKey<ThemeContext> = Symbol('theme-context')InjectionKey<ThemeContext> 同时承担运行时 key 和编译期类型标记。这样 provide(themeKey, value) 与 inject(themeKey) 会围绕同一份 ThemeContext 约束工作,避免字符串 key 带来的拼写碰撞和 unknown 类型扩散。
片段示例(ThemeProvider.vue,提供上下文):
<script setup lang="ts">
import { provide, readonly, ref } from 'vue'
import { themeKey, type ThemeContext } from './theme-context'
const theme = ref<'light' | 'dark'>('light')
function toggleTheme() {
theme.value = theme.value === 'light' ? 'dark' : 'light'
}
const context: ThemeContext = {
theme: readonly(theme),
toggleTheme,
}
provide(themeKey, context)
</script>
<template>
<section :data-theme="theme">
<button type="button" @click="toggleTheme">切换主题</button>
<slot />
</section>
</template>片段示例(Toolbar.vue,深层后代消费上下文):
<script setup lang="ts">
import { inject } from 'vue'
import { themeKey } from './theme-context'
const themeContext = inject(themeKey)
if (!themeContext) {
throw new Error('Toolbar 必须位于 ThemeProvider 内部')
}
const { theme, toggleTheme } = themeContext
</script>
<template>
<div>
<span>当前主题:{{ theme }}</span>
<button type="button" @click="toggleTheme">在工具栏中切换</button>
</div>
</template>片段示例(App.vue,建立祖先与后代关系):
<script setup lang="ts">
import ThemeProvider from './ThemeProvider.vue'
import Toolbar from './Toolbar.vue'
</script>
<template>
<ThemeProvider>
<div>
<div>
<Toolbar />
</div>
</div>
</ThemeProvider>
</template>预期结果:
页面初始显示“当前主题:light”。
点击 ThemeProvider 或 Toolbar 中任一“切换”按钮后,文本在 light 与 dark 之间切换。
Toolbar 不需要接收或转发任何 theme props。让注入失败尽早暴露
inject 在没有匹配提供者时可能得到 undefined。对于“缺少依赖就无法工作”的组件,应在 setup 阶段立即检查并抛出有意义的错误,而不是让空值在更深的业务代码中触发异常。
如果依赖本身可选,可以给 inject 提供默认值,但默认值应是真正可工作的降级实现。不要为了消除 TypeScript 报错随意写非空断言,否则会把组件树配置错误推迟到运行期。
控制状态写入口
跨层共享可变 ref 虽然方便,但任何注入方都能直接修改它,责任边界会迅速变模糊。更稳妥的做法是提供 readonly 状态,再提供 toggleTheme、setLocale、registerField 这类命令函数。
这样读取方只依赖公开契约,写操作集中在提供方中。需要跨越很多页面、长期存在且与组件树无关的全局业务状态时,应考虑专门的状态管理方案;provide/inject 更适合有明确祖先边界的局部上下文。