去年做订单后台,有一个三层嵌套的详情弹窗:页面里放通用弹窗外壳,外壳的默认插槽里放订单详情,详情里再嵌一个退款表单。退款提交成功后要关掉整个弹窗,写代码的人懒得一层层往上报,就在表单组件里直接改了父组件传下来的开关:

const props = defineProps({ visible: Boolean });

function close() {
  props.visible = false;   // Vue 警告:target is readonly
}

控制台确实报了一条警告,但页面能关掉,于是被当成「框架啰嗦」。后来改成了沿组件层级往上摸:

const inst = getCurrentInstance();
inst.parent.parent.ctx.close();   // 爷爷组件的 close 方法

当时也跑通了。真正的麻烦在后面:设计说弹窗要加一层淡入淡出的包装容器,加完这个组件,链路上多了一层,退款按钮点了没反应;再后来这个弹窗外壳被复用到另一个页面,那个页面根本没有 close 方法,直接报 Cannot read properties of undefined。前后修了三次,每次都是因为「谁是谁的父组件」这个假设变了。

这篇讲组件之间到底该怎么说话:数据怎么往下走,动作怎么往上报,内容怎么塞进去,跨了三层又不想一层层传的时候还有什么办法。示例都是 Vue 3 加 <script setup> 的写法,运行在 Vite 建的项目里。组件通信不是「哪种写法更高级」的问题,而是「谁拥有这份数据、谁只负责展示」的问题,想清楚这一点,选型就不难了。

先把「单向数据流」这句话落到实处

很多文档只写一句「props 是单向的」,但没说清单向的具体含义。它包含两件事:数据从父组件流向子组件;子组件不能往回写。第二条不是 Vue 故意限制你,而是为了让「值什么时候变、被谁改的」有唯一答案。一个开关如果子组件能改、父组件也能改、爷爷还能改,出问题时你根本不知道该去哪一行下断点。

一个弹窗里数据的走向
父组件持有 open 状态
props 把状态和标题传下去
子组件在用户点击时发出 close 事件
父组件收到事件后修改状态

关键在于最后一步:状态的修改永远发生在拥有它的那一层。子组件只负责「告诉上面发生了什么」,不负责决定结果。这样父组件可以在关闭前做二次确认、可以记日志、可以拒绝关闭,子组件完全不用知道这些规则。

再说一个容易被忽略的细节:props 的只读是浅层的。直接写 props.visible = false 会警告,但如果传下来的是一个对象,子组件改 props.order.status = "paid" 是不会警告的,因为改的是对象内部属性,不是 props 这个绑定。不报警不代表没问题:父组件的数据被悄悄改了,它自己的校验、日志、请求全被绕过。这条在代码评审里最容易被放过。

props:定义、校验和几个容易误解的规则

defineProps 只写类型数组适合草稿,正式组件建议写对象形式,把类型、必填、默认值、校验都表达出来:

const props = defineProps({
  orderId: { type: [String, Number], required: true },
  status: {
    type: String,
    default: "pending",
    validator: (v) => ["pending", "paid", "closed"].includes(v)
  },
  items: { type: Array, default: () => [] }
});

对象和数组的默认值必须写成工厂函数,否则所有实例会共享同一个引用,一个组件 push 一条,别的组件也跟着多一条。这个坑在列表组件里非常常见。

布尔类型的 prop 有自己的转换规则:不传值时是 false,只写属性名不写值(比如 <dialog disabled>)表示 true。所以给布尔 prop 设 default: true 要特别小心,使用方不写这个属性时拿到的是 true,想关掉还必须显式写 :disabled="false"。我的习惯是布尔 prop 一律默认 false,需要默认开启就换个正向命名。

校验是开发期提示,不是接口契约

类型不对、必填缺失、validator 返回 false,Vue 只会打警告,不会中断渲染。生产构建里这些检查会被跳过,所以别指望它挡住线上错误,后端该校验的还是要校验。

另一个常被问到的点:在 <script setup> 里解构 props 会不会丢响应式。Vue 3.5 起解构默认保持响应式,更早的版本需要用 toRef(props, "orderId") 或者干脆写 props.orderId。这个版本差异的具体小版本行为待确认,团队版本不统一时,最稳的做法是统一写 props.xxx,别依赖解构。

还有本地副本的问题。子组件想把传进来的初始值放进输入框,直接 const local = props.value 只是复制了一次,父组件后续更新它不会跟着变;反过来用户改了本地变量,父组件也不知道。正确做法是明确这份副本的同步方向:要么用 computed 的 get 和 set 双向同步,要么用 watch 监听父值、在它变化时重置本地值。两种都要写清楚注释,不然接手的人会以为这俩是同一个东西。

事件:往上报告,不往上指挥

defineEmits 同样建议写对象形式,至少把事件名列出来,有条件再带校验:

const emit = defineEmits({
  close: () => true,
  submit: (payload) => Boolean(payload && typeof payload.reason === "string")
});

function handleSubmit() {
  emit("submit", { reason: form.reason });
}

命名上记住两条。第一,脚本里写驼峰,模板里写短横线:脚本 emit("orderChange"),模板 @order-change。Vue 在编译模板时会把监听器转成 onOrderChange 这样的属性,所以两边的对应关系是固定的。反过来在脚本里 emit 短横线的名字,运行时也会做一次驼峰兜底,但别依赖它,声明、emit、监听三处写法不一致时,排查成本很高。

第二,事件名描述「发生了什么」,不要描述「请做什么」。closed、saved、changed 这类名字让父组件自己决定后续动作;如果叫 pleaseClose,等于子组件在指挥父组件,规则又跑回下面去了。这条不是硬规定,但按它写,组件的复用性会明显好一些。

自定义 v-model:modelValue 和 update:modelValue

组件上的 v-model 不是魔法,它是 :modelValue 加 @update:modelValue 的简写。所以一个支持 v-model 的输入组件,必须同时声明这两样:

const props = defineProps({ modelValue: String });
const emit = defineEmits(["update:modelValue"]);

const inner = computed({
  get: () => props.modelValue,
  set: (v) => emit("update:modelValue", v)
});
<input :value="modelValue"
       @input="emit('update:modelValue', $event.target.value)">

父组件写 <MyInput v-model="form.keyword">,等于把值传下来、把更新事件接回去。想支持多个可绑定字段,用带参数的写法:子组件声明 title 并 emit update:title,父组件写 v-model:title="..."。Vue 2 时代的 .sync 在 Vue 3 里已经没有了,迁移项目时会遇到,别照抄旧代码。

修饰符也能传到组件:父组件写 v-model.trim,子组件会收到一个 modelModifiers 对象,里面是 { trim: true },需要自己实现去空格。不实现的话修饰符就是白写,这个点文档里一笔带过,实际项目中经常有人以为框架自动处理了。

插槽:内容由使用方提供,数据仍归子组件

props 适合传数据,插槽适合传「结构」。一个卡片组件,标题、按钮、底部说明的排版由组件决定,但里面放什么按钮由使用方决定,这就是插槽的场合。

<div class="card">
  <header><slot name="title">默认标题</slot></header>
  <main><slot>没有内容</slot></main>
  <footer><slot name="actions"></slot></footer>
</div>

默认插槽、具名插槽、默认内容(写在 slot 标签里的兜底)都在这一段里。使用方这样写:

<Card>
  <template #title>订单详情</template>
  <p>这里是正文</p>
  <template #actions>
    <button @click="save">保存</button>
  </template>
</Card>

有个必须理解的点:插槽内容在父组件的作用域里编译。上面那段 save 是父组件的方法,不是 Card 内部的。所以插槽里能读父组件的数据,读不到子组件的数据。想反过来,就得用作用域插槽。

作用域插槽:把子组件的数据借给父组件渲染

表格组件最典型:每一行长什么样由子组件决定,但操作列放什么按钮,只有使用方知道。子组件把行数据抛出来:

<tr v-for="row in rows" :key="row.id">
  <td>{{ row.orderNo }}</td>
  <td>
    <slot name="actions" :row="row" :index="row.id">
      <button>查看</button>
    </slot>
  </td>
</tr>

使用方用解构接住:

<DataTable :rows="rows">
  <template #actions="{ row }">
    <button @click="refund(row)">退款</button>
  </template>
</DataTable>

作用域插槽的价值在于「控制权分离」:渲染循环、样式、空状态由组件负责,业务动作由页面负责。代价是组件之间的契约从「props 有哪些」变成了「插槽抛出了哪些字段」,改一个字段名可能悄悄弄坏别人的页面,所以抛出的字段要当公开 API 对待。

另外两个细节:判断有没有传某个插槽,用 $slots.actions 是否存在,别用 v-if 猜;插槽是函数,父组件每次渲染都会重新执行,别在插槽里做重活。

跨层:provide/inject、attrs 透传,以及一张选型表

当层级超过两层,逐层转发 props 和事件会让中间组件变成传声筒:它们既不使用这些数据,也不关心这些事件,却被迫声明一堆接口。这种组件改起来最烦,删掉一个中间层就全线报错。

provide 和 inject 解决的是这个问题。祖先组件提供一份依赖,任意深度的后代都能取到。要点有三个:

  • key 用 Symbol,不要用字符串。字符串 key 在多人协作时容易撞名,Symbol 只要从同一个模块导入就绝对不会冲突。
  • 想让后代感知变化,provide 的必须是 ref 或 reactive,不能是取出来的普通值。
  • 最好同时提供修改方法,而不是把状态本身丢出去。后代只能调用你给的动作,规则还留在祖先手里。
// dialog-context.js
import { inject } from "vue";

export const DIALOG_KEY = Symbol("dialog");

export function useDialog() {
  const ctx = inject(DIALOG_KEY, null);
  if (!ctx) throw new Error("组件不在 Dialog 内部");
  return ctx;
}
// BaseDialog.vue 里
import { provide, computed } from "vue";
import { DIALOG_KEY } from "./dialog-context.js";

const props = defineProps({ open: Boolean });
const emit = defineEmits(["close"]);

const ctx = {
  open: computed(() => props.open),
  close: () => emit("close")
};
provide(DIALOG_KEY, ctx);

后代的 useDialog() 拿到 close 就能请求关闭,再也不用知道自己在第几层。把「有没有 provider」做成显式报错,比拿到 undefined 再在别处崩掉好查得多。

另一个跨层的东西是 attrs。父组件写在子组件标签上、但子组件没有声明成 props 的属性,会进入 attrs,默认自动落到子组件的根元素上。class 和 style 总是会合并,事件监听也在里面。封装基础组件时,常把 inheritAttrs 关掉,再手动绑到真正的容器上:

defineOptions({ inheritAttrs: false });   // Vue 3.3 起可用

<div class="dialog-panel" v-bind="$attrs">
  <slot />
</div>

关掉自动继承是为了不让 class、aria-label 落到最外层遮罩上。如果组件有多个根节点,Vue 不会自动继承,必须自己选一个节点绑定:开发环境会给一条「无法自动继承」的警告,属性最终不会落到任何节点上。3.3 之前没有 defineOptions,要另开一个普通 <script> 块导出选项,这点在迁移老项目时会碰到。

场景推荐做法代价与注意
父子之间传数据、收动作props 加 emit接口显式,层数多了会变成逐层转发
兄弟组件要同步状态提到共同父级,再往下传父级会变成中转站,状态一多就臃肿
跨三到五层传环境能力provide/inject,key 用 Symbol依赖隐式,脱离组件树就没法用
由使用方决定局部结构具名插槽或作用域插槽契约变成插槽字段,改字段影响面大
透传 class、事件、无障碍属性attrs 加手动绑定多根节点必须手动绑,容易漏
跨页面共享状态状态管理或路由参数组件通信管不到路由切换后的新组件树

完整场景走查:一次弹窗重构

需求是把订单详情弹窗改造成可复用组件,同时支持三种用法:查看详情、编辑备注、发起退款。要求弹窗的遮罩、尺寸、标题栏统一,底部按钮由各业务自己决定,退款成功后要关闭弹窗并刷新列表。

第一版就是开头那种写法:弹窗外壳接收 visible,内部业务组件直接改 props,改不动就用 $parent 往上摸。它的问题不是「不优雅」,而是三个具体的故障:包装层一变就失效;换个页面复用就报错;写单元测试时根本构造不出那串父子关系。

第二版改成显式的 props 加事件,中间层即使不用也转发一次:

<!-- OrderPage.vue -->
<BaseDialog :open="detailOpen" title="订单详情" @close="detailOpen = false">
  <OrderDetail :order-id="currentId" @close="detailOpen = false" />
</BaseDialog>

这版能跑,也看得懂,但 OrderDetail 里还有退款表单,退款成功也要关弹窗,于是又多了一条 @close 往上传。三层之后,中间那层已经有四个属性和三个事件只是为了转发。更麻烦的是「刷新列表」这个动作也要一路传上去,中间层开始出现自己都不理解的参数。

第三版把「关闭」这件事收进上下文,同时用作用域插槽把底部按钮交给业务方:

<!-- BaseDialog.vue -->
const props = defineProps({ open: Boolean, title: String });
const emit = defineEmits(["close"]);
const loading = ref(false);

provide(DIALOG_KEY, {
  close: () => emit("close"),
  setLoading: (v) => { loading.value = v; }
});

<template>
  <div v-if="open" class="mask">
    <div class="panel" v-bind="$attrs">
      <h2>{{ title }}</h2>
      <slot />
      <footer>
        <slot name="footer" :close="() => emit('close')" :loading="loading">
          <button @click="emit('close')">关闭</button>
        </slot>
      </footer>
    </div>
  </div>
</template>
<!-- RefundForm.vue,孙组件 -->
const dialog = useDialog();

async function submit() {
  dialog.setLoading(true);
  try {
    await api.refund(props.orderId, form.reason);
    emit("refunded");
    dialog.close();               // 不再关心自己在第几层
  } finally {
    dialog.setLoading(false);
  }
}

页面那边只处理业务结果:详情组件抛出 refunded,页面刷新列表并关闭。遮罩、标题、按钮的加载态都由外壳统一,业务组件不需要重复写。

这一版也不是终点。如果 DIALOG_KEY 提供的东西越来越多(尺寸、层级、确认框、Toast),它就会变成一个隐形的全局对象,那时候该考虑的是状态管理,而不是继续往里塞。判断线很简单:注入的东西是「这个组件树的环境」,就继续用 provide;是「整个应用共享的业务数据」,就不该放在这里。

错误现象对照

下面这些提示和现象,基本都是通信契约没对齐。看到警告先别关掉,它通常指着一个真实的数据流向问题。

现象真实原因第一步查什么
控制台警告 Set operation on key "visible" failed: target is readonly 子组件直接给 props 赋值,或者把 props 当成了本地状态 搜 props.xxx =,改成 emit 事件、由父组件改
子组件 emit 了,父组件监听没反应 事件名大小写或连字符不一致,模板监听编译成了另一个属性名 对齐 defineEmits 写的名字和模板里的 @ 监听
组件上写 v-model,输入后值不更新 子组件用了 value 和 input 的旧约定,或者漏了 update:modelValue 检查 props 是不是 modelValue,emits 里有没有对应的更新事件
插槽里读不到子组件里的循环变量 插槽内容在父作用域编译,父组件看不到子组件内部数据 改用作用域插槽,把需要的字段通过 slot 抛出来
inject 拿到 undefined Symbol key 来自不同模块副本,或组件不在 provider 的子树里 确认 key 是同一个导出,检查组件层级和挂载位置
加了一层包装后 $parent 拿到的对象变了 依赖固定的组件层级,结构一变整条链就错位 搜 $parent、$root,改成事件或注入
父组件传的 class 没落到弹窗面板上 组件有多个根节点没手动绑定 $attrs,或者关掉了自动继承却没绑 数根节点数量,检查 inheritAttrs 和 v-bind="$attrs" 的位置

边界与代价

这些通信方式各有适用范围,超过范围就会从「解决问题」变成「制造问题」。

  • props 超过十个,说明这个组件承担的职责太多。先考虑拆组件,或者把一组相关的配置收成一个对象,再考虑用插槽把结构交出去。接口越大,改一次影响的使用方越多。
  • provide/inject 是隐式依赖。使用者看函数签名完全不知道数据从哪来,改 key 时编辑器的「查找引用」也帮不上忙。它适合主题、当前用户、弹窗上下文这类「环境」;不适合业务数据,更不适合替代状态管理。
  • 中间层连续转发事件超过两层,就该停下来想想。三层以上的 @close 接力,中间组件会变成纯管道,删一个组件就断链,测试也难写。
  • 插槽给太多,组件的使用成本会转移给业务方。一个表格组件如果暴露了表头、单元格、空状态、分页四个插槽,每个页面都要自己拼一遍,那还不如直接写 HTML。默认实现要先做好,插槽只留真正需要定制的口子。
  • $parent 和 $root 不该出现在业务代码里。它们把组件结构写死,重构、加包装层、换挂载点都会出问题,而且没有类型提示。
  • 跨页面通信不要用组件那一套。路由一切换,原来的组件树就销毁了,provide 的作用域也随之消失,能用的只有状态管理、路由参数或存储,这正是下一篇的内容。

小结与练习

四句话收尾:数据往下用 props,动作往上用 emit,拥有状态的那一层才有修改权;组件上的 v-model 就是 modelValue 加 update:modelValue,没有别的魔法;插槽传结构、作用域插槽借数据,插槽内容的编译作用域在父组件;跨层用 Symbol key 的 provide/inject,但只放环境能力,不放业务状态。

显式接口的代价

props 和事件写起来啰嗦,层数一多就要逐层转发。换来的是能静态检查、能在 Devtools 里看到每个组件收到什么、能单独测试。

隐式依赖的代价

provide/inject 写起来干净,任意深度都能取。换来的是依赖关系看不见、脱离组件树就崩、改 key 时找不到使用方,所以要限定在环境类能力上。

动手练几条,当天就能验证:

  1. 写一个 BaseDialog,父组件用 :open 控制显示,子组件只 emit("close")。删掉所有 $parent 之后,在中间插一层空包装组件,确认功能仍然正常。
  2. 写一个输入组件,声明 modelValue 和 update:modelValue,父组件用 v-model.trim 绑定,在子组件里打印 modelModifiers,确认收到 { trim: true } 并自己实现去空格。
  3. 写一个表格组件,用作用域插槽把 row 抛给父组件渲染操作列;再故意把字段名改成 record,看父组件会怎么坏。
  4. 把三层 props 传递改成 Symbol key 的 provide/inject,然后在中间插入一个无关组件,确认孙组件仍能拿到关闭方法。
  5. 写一个多根节点的组件,父组件传 class="highlight",先不写 v-bind="$attrs",在浏览器里确认样式没生效,再补上。

下一篇讲状态管理。理由很具体:这一篇解决的都是「同一棵组件树里怎么说话」,而购物车数量要同时显示在页头、商品详情和结算页,登录状态要在路由守卫里读,这些场景没有共同的父组件,provide 也活不过一次路由切换。组件通信到这一步就到边界了,该换一套东西来管。想先把事件和对象的基础补牢,可以回看事件模型和对象与原型链,自定义事件的订阅发布思路、以及 props 对象的引用传递,源头都在那两篇。