插槽Slot详解
Props 解决“组件需要什么数据”,插槽解决“组件允许放入什么内容”。掌握默认插槽、具名插槽和作用域插槽,才能把组件从固定模板升级为灵活、可组合的内容容器。
上一篇文章中,我们通过自定义事件与 v-model 打通了父子组件的数据协作。本文继续学习组件组合的另一项核心能力:由父组件决定子组件的一部分模板内容,并在需要时使用子组件提供的数据进行渲染。
写作约定:示例以 Vue 3
<script setup>为主,默认使用 Vue 3.2+。v-slot从 Vue 2.6 开始提供;defineSlots需要 Vue 3.3+。Vue 2 的旧语法只在文末作维护说明,新项目不建议继续混用。
一、为什么组件需要插槽
假设正在封装一个通用的消息卡片:
<!-- MessageCard.vue -->
<template>
<article class="message-card">
<h2>{{ title }}</h2>
<p>这是一条固定内容</p>
</article>
</template>
<script setup>
defineProps({
title: {
type: String,
required: true
}
})
</script>标题可以通过 Prop 修改,但正文永远相同。如果把正文也设计为字符串 Prop,虽然能显示普通文本,却很难放入链接、图标、按钮或其他组件。
插槽允许父组件把一段模板交给子组件,由子组件决定它出现的位置:
<MessageCard title="发布成功">
<p>文章已保存,你可以继续编辑。</p>
<a href="/archives">查看文章</a>
</MessageCard>这里,卡片边框、标题区域和布局由 MessageCard 负责,正文内容由父组件负责。二者组合后形成最终界面。
插槽最适合以下场景:
卡片、弹窗、面板等容器需要容纳不同内容;
布局结构固定,但页头、正文、页脚可以变化;
列表渲染方式固定,但每一行的展示形式由使用方决定;
基础组件拥有内部状态,希望把状态提供给父组件渲染。
简单字符串仍优先使用 Props。只有内容需要模板表达能力时,才需要引入插槽。
二、默认插槽:为内容预留出口
子组件使用 <slot> 元素声明内容出口:
<!-- MessageCard.vue -->
<template>
<article class="message-card">
<h2>{{ title }}</h2>
<div class="message-content">
<slot></slot>
</div>
</article>
</template>
<script setup>
defineProps({
title: {
type: String,
required: true
}
})
</script>父组件把内容写在组件开始标签和结束标签之间:
<!-- App.vue -->
<template>
<MessageCard title="学习提醒">
<p>今天完成插槽的基础练习。</p>
<button type="button">开始学习</button>
</MessageCard>
</template>
<script setup>
import MessageCard from './components/MessageCard.vue'
</script>最终可以把它理解为:
MessageCard 的卡片结构
├── 标题:学习提醒
└── 默认插槽出口
├── 父组件提供的段落
└── 父组件提供的按钮<slot> 会被父组件传入的内容替换。父组件没有提供默认内容时,这个出口就不会渲染任何内容。
虽然没有显式命名,默认插槽的名字实际上是 default。后面的具名插槽和 TypeScript 类型声明都会用到这个名称。
三、插槽内容的编译作用域
插槽内容由父组件编写,也在父组件的作用域中编译。因此它可以直接访问父组件的数据和方法:
<template>
<MessageCard :title="cardTitle">
<p>{{ message }}</p>
<button type="button" @click="markAsRead">标记已读</button>
</MessageCard>
</template>
<script setup>
import { ref } from 'vue'
import MessageCard from './components/MessageCard.vue'
const cardTitle = ref('学习提醒')
const message = ref('还有 2 个练习待完成')
function markAsRead() {
message.value = '所有提醒均已读'
}
</script>但插槽内容不能直接访问 MessageCard 内部的 Props 或状态。例如,下面的写法不成立:
<!-- 错误:父组件作用域中没有 childCount -->
<MessageCard title="学习提醒">
<p>{{ childCount }}</p>
</MessageCard>可以用一句话记住:插槽的位置由子组件决定,插槽表达式默认使用父组件的数据。 如果确实需要子组件向插槽传值,就要使用作用域插槽。
四、后备内容:父组件没有传内容时显示什么
<slot> 标签内部可以放置后备内容,也常被称为默认内容或 fallback 内容:
<!-- BaseButton.vue -->
<template>
<button type="button" class="base-button">
<slot>提交</slot>
</button>
</template>父组件不传内容时,按钮显示“提交”:
<BaseButton />父组件提供内容后,后备内容会被替换:
<BaseButton>保存草稿</BaseButton>
<BaseButton>
<span class="icon">✓</span>
确认发布
</BaseButton>后备内容适合提供合理、通用的默认界面,例如空状态、默认图标或标准操作文案。
需要注意,父组件显式传入空白内容,与完全没有提供插槽并不总是等价。不要依赖后备内容掩盖调用方传错数据的问题;如果正文是业务必填项,应在组件契约和测试中明确约束。
五、具名插槽:把不同内容放到不同位置
一个卡片可能同时需要标题、正文和底部操作区。仅靠一个默认插槽,无法让子组件准确安排这些内容的位置,这时可以使用具名插槽。
5.1 子组件声明多个出口
<!-- BaseCard.vue -->
<template>
<article class="base-card">
<header class="card-header">
<slot name="header">
<h2>默认标题</h2>
</slot>
</header>
<div class="card-body">
<slot></slot>
</div>
<footer v-if="$slots.footer" class="card-footer">
<slot name="footer"></slot>
</footer>
</article>
</template>这里有三个出口:
header:标题区域,带后备内容;default:正文区域,不写name时使用默认名称;footer:底部操作区,只有提供内容时才渲染外层footer。
5.2 父组件使用 v-slot 分发内容
<template>
<BaseCard>
<template v-slot:header>
<h2>今日学习任务</h2>
<span>3 项</span>
</template>
<template v-slot:default>
<p>掌握默认插槽、具名插槽和作用域插槽。</p>
</template>
<template v-slot:footer>
<button type="button">稍后提醒</button>
<button type="button">开始学习</button>
</template>
</BaseCard>
</template>
<script setup>
import BaseCard from './components/BaseCard.vue'
</script>具名插槽通常写在 <template> 上。未被具名 template 包裹的顶层内容,会被归入默认插槽,但为了清晰,包含多个具名插槽时建议把 default 也显式写出。
5.3 使用 # 简写
v-slot: 可以缩写为 #:
<BaseCard>
<template #header>
<h2>今日学习任务</h2>
</template>
<template #default>
<p>完成插槽练习。</p>
</template>
<template #footer>
<button type="button">开始学习</button>
</template>
</BaseCard>#header 等价于 v-slot:header,#default 等价于 v-slot:default。日常开发中简写更常见,但理解完整语法有助于阅读文档和排查模板错误。
六、动态插槽名:由运行时数据决定出口
插槽名也可以使用动态参数:
<!-- App.vue -->
<template>
<BaseLayout>
<template #[region]>
<p>这段内容会进入当前选择的区域。</p>
</template>
</BaseLayout>
<button type="button" @click="region = 'header'">放入页头</button>
<button type="button" @click="region = 'footer'">放入页脚</button>
</template>
<script setup>
import { ref } from 'vue'
import BaseLayout from './components/BaseLayout.vue'
const region = ref('header')
</script>#[region] 会使用 region 的当前值作为插槽名。它适合布局编辑器、可配置页面等确实需要动态分发的场景。
普通业务组件仍应使用明确的插槽名。不要为了少写几个模板分支,把原本清晰的 header、footer 全部变成难以追踪的动态名称。
七、作用域插槽:让父组件使用子组件的数据渲染
普通插槽只能访问父组件作用域。有时,子组件掌握列表项、加载状态或内部交互状态,而父组件希望决定这些数据的展示方式。这时需要子组件向插槽传递 Props。
7.1 子组件向插槽传值
<!-- CurrentUser.vue -->
<template>
<div class="current-user">
<slot :user="user" :is-admin="isAdmin"></slot>
</div>
</template>
<script setup>
import { computed, reactive } from 'vue'
const user = reactive({
name: '洋洋',
role: 'admin'
})
const isAdmin = computed(() => user.role === 'admin')
</script>绑定在 <slot> 上的 user 和 is-admin 被称为插槽 Props。它们的数据方向是子组件到父组件的插槽内容。
7.2 父组件接收插槽 Props
默认插槽同时需要接收数据时,可以把 v-slot 直接写在组件标签上:
<template>
<CurrentUser v-slot="slotProps">
<p>当前用户:{{ slotProps.user.name }}</p>
<span v-if="slotProps.isAdmin">管理员</span>
</CurrentUser>
</template>
<script setup>
import CurrentUser from './components/CurrentUser.vue'
</script>也可以使用解构写法,更直观地提取需要的字段:
<CurrentUser v-slot="{ user, isAdmin }">
<p>{{ user.name }}</p>
<span v-if="isAdmin">管理员</span>
</CurrentUser>组件标签上直接使用 v-slot 的写法只适用于“只有默认插槽”的清晰场景。如果同时存在多个具名插槽,应把内容分别放入 <template #名称> 中。
7.3 具名作用域插槽
具名插槽同样可以接收数据:
<!-- TaskList.vue -->
<template>
<ul class="task-list">
<li v-for="task in tasks" :key="task.id">
<slot
name="item"
:task="task"
:toggle="() => toggleTask(task.id)"
></slot>
</li>
</ul>
</template>
<script setup>
import { ref } from 'vue'
const tasks = ref([
{ id: 1, title: '理解默认插槽', completed: true },
{ id: 2, title: '练习作用域插槽', completed: false }
])
function toggleTask(taskId) {
const task = tasks.value.find(item => item.id === taskId)
if (task) {
task.completed = !task.completed
}
}
</script>父组件只负责每一项的展示:
<TaskList>
<template #item="{ task, toggle }">
<label>
<input
type="checkbox"
:checked="task.completed"
@change="toggle"
>
{{ task.title }}
</label>
</template>
</TaskList>子组件管理列表与状态变更,父组件决定复选框和标题如何呈现,这就是作用域插槽带来的分工。
八、插槽 Props 的解构与默认值
插槽 Props 可以像函数参数一样解构,并为缺失值提供默认值。
子组件只在部分情况下传入描述:
<template>
<slot name="message" text="保存成功"></slot>
</template>父组件可以设置默认值:
<BaseMessage>
<template #message="{ text = '操作已完成' }">
<p>{{ text }}</p>
</template>
</BaseMessage>如果插槽 Prop 是一个对象,还可以继续嵌套解构,但过度解构会降低可读性:
<!-- 字段较多时,保留 item 对象往往更清晰 -->
<template #item="{ item }">
<strong>{{ item.title }}</strong>
<span>{{ item.status }}</span>
</template>默认值只处理 undefined,不会自动修正 null、空字符串或结构错误的对象。组件应明确自己的数据契约,而不是寄希望于每一层都设置兜底值。
九、完整示例:可组合的任务面板
下面把默认插槽、具名插槽和作用域插槽组合到一个任务面板中。子组件负责任务数据、统计和统一布局,父组件决定标题附加信息、空状态和每一行的展示。
9.1 子组件提供结构和数据
<!-- TaskPanel.vue -->
<template>
<section class="task-panel">
<header class="panel-header">
<div>
<slot name="title" :completed="completedCount" :total="tasks.length">
<h2>学习任务</h2>
</slot>
</div>
<span>{{ completedCount }} / {{ tasks.length }}</span>
</header>
<div v-if="tasks.length" class="task-list">
<div v-for="task in tasks" :key="task.id" class="task-row">
<slot
name="task"
:task="task"
:toggle="() => toggleTask(task.id)"
>
<span>{{ task.title }}</span>
</slot>
</div>
</div>
<div v-else class="empty-state">
<slot name="empty">暂无任务</slot>
</div>
<footer v-if="$slots.actions" class="panel-actions">
<slot name="actions" :completed="completedCount"></slot>
</footer>
</section>
</template>
<script setup>
import { computed, ref } from 'vue'
const tasks = ref([
{ id: 1, title: '复习 Props 与事件', completed: true },
{ id: 2, title: '完成插槽练习', completed: false },
{ id: 3, title: '封装任务面板', completed: false }
])
const completedCount = computed(
() => tasks.value.filter(task => task.completed).length
)
function toggleTask(taskId) {
const task = tasks.value.find(item => item.id === taskId)
if (task) {
task.completed = !task.completed
}
}
</script>
<style scoped>
.task-panel {
border: 1px solid #d1d5db;
border-radius: 12px;
padding: 20px;
}
.panel-header,
.task-row,
.panel-actions {
display: flex;
align-items: center;
justify-content: space-between;
gap: 12px;
}
.task-row {
padding: 12px 0;
border-bottom: 1px solid #e5e7eb;
}
.completed {
color: #6b7280;
text-decoration: line-through;
}
</style>9.2 父组件定制展示内容
<!-- App.vue -->
<template>
<TaskPanel>
<template #title="{ completed, total }">
<h2>Vue 学习清单</h2>
<p>已完成 {{ completed }} 项,共 {{ total }} 项</p>
</template>
<template #task="{ task, toggle }">
<label :class="{ completed: task.completed }">
<input
type="checkbox"
:checked="task.completed"
@change="toggle"
>
{{ task.title }}
</label>
<span>{{ task.completed ? '已完成' : '进行中' }}</span>
</template>
<template #empty>
<p>今天没有任务,可以添加一个新的学习目标。</p>
</template>
<template #actions="{ completed }">
<span>当前完成 {{ completed }} 项</span>
<button type="button" @click="showSummary">查看总结</button>
</template>
</TaskPanel>
</template>
<script setup>
import TaskPanel from './components/TaskPanel.vue'
function showSummary() {
// 打开当前用户的学习总结
}
</script>这个组件的复用点不再只是几个字符串 Props:
更换标题区域,不需要修改任务列表逻辑;
更换任务行样式,不需要复制整个面板;
空状态与操作区可以按页面需要组合;
数据仍由子组件管理,展示内容仍由父组件模板编译。
如果任务数据本应属于父组件,则应通过 Props 传入并通过事件通知更新,而不是为了让示例运行把所有数据固定在子组件中。组件状态放在哪里,要根据真实业务的所有权决定。
十、检测与读取插槽:$slots 和 useSlots
有时子组件需要根据父组件是否提供插槽,决定是否渲染外层结构。
模板中可以使用 $slots:
<template>
<section class="base-panel">
<header v-if="$slots.header" class="panel-header">
<slot name="header"></slot>
</header>
<div class="panel-body">
<slot></slot>
</div>
</section>
</template>这样,父组件没有传入 header 时,连 header 元素也不会出现,避免留下多余的边距或边框。
在 <script setup> 中需要读取插槽时,使用 useSlots:
<script setup>
import { useSlots } from 'vue'
const slots = useSlots()
function logSlots() {
console.log(Object.keys(slots))
}
</script>插槽通常是返回虚拟节点的函数。需要手动调用或包装插槽时,应保留父组件提供的上下文,不要随意把插槽函数中的 this 改成其他对象。
$slots.header 存在只能说明调用方声明了这个插槽,不一定代表最终会产生可见内容。例如,父组件传入的内容可能全部被 v-if 隐藏。因此它适合控制结构,不适合作为“页面上一定有可见文字”的保证。
十一、透传插槽:封装第三方组件而不丢失能力
封装现有组件时,如果只转发 Props 和事件,却忘记转发插槽,原组件的内容组合能力就会丢失。
最简单的写法是遍历 $slots,把所有插槽继续传给内部组件:
<!-- WrappedPanel.vue -->
<template>
<ThirdPartyPanel class="wrapped-panel" v-bind="$attrs">
<template
v-for="(_, name) in $slots"
:key="name"
#[name]="slotProps"
>
<slot :name="name" v-bind="slotProps || {}"></slot>
</template>
</ThirdPartyPanel>
</template>
<script setup>
defineOptions({ inheritAttrs: false })
</script>这样,父组件传给 WrappedPanel 的插槽会继续交给 ThirdPartyPanel,作用域插槽的参数也会通过 slotProps 保留。
不过,完全透传并不总是最佳方案。如果包装组件需要统一页头、限制某些区域或修改插槽参数,就应该显式列出公开插槽:
<template>
<ThirdPartyPanel>
<template #header>
<slot name="header">统一标题</slot>
</template>
<template #default="slotProps">
<slot v-bind="slotProps"></slot>
</template>
</ThirdPartyPanel>
</template>显式转发更清楚地表达了包装组件的公开契约,也能避免无意暴露内部组件未来新增的插槽。
十二、无渲染组件:把逻辑与展示彻底分离
作用域插槽还可以实现“无渲染组件”:组件本身负责状态和行为,把具体界面完全交给使用方。
<!-- WindowSize.vue -->
<template>
<slot :width="width" :height="height" :is-mobile="isMobile"></slot>
</template>
<script setup>
import { computed, onMounted, onUnmounted, ref } from 'vue'
const width = ref(0)
const height = ref(0)
const isMobile = computed(() => width.value < 768)
function updateSize() {
width.value = window.innerWidth
height.value = window.innerHeight
}
onMounted(() => {
updateSize()
window.addEventListener('resize', updateSize)
})
onUnmounted(() => window.removeEventListener('resize', updateSize))
</script>父组件可以按当前页面需要渲染:
<WindowSize v-slot="{ width, height, isMobile }">
<p>窗口尺寸:{{ width }} × {{ height }}</p>
<p>{{ isMobile ? '当前为窄屏布局' : '当前为宽屏布局' }}</p>
</WindowSize>同一个逻辑组件既可以驱动文字,也可以驱动卡片、图表或布局切换,而不必为每种界面增加 Props。
如果一段逻辑不需要组件实例、生命周期或模板出口,组合式函数通常更直接。无渲染组件适合状态与模板组合紧密的场景,不应替代所有逻辑复用方式。
示例把初始尺寸设为 0,并在 onMounted 中读取浏览器窗口,因此初始化阶段不会直接访问服务端不存在的 window。如果项目使用服务端渲染,还应为初始界面选择合理的占位布局,避免客户端首次更新时出现明显跳动。
十三、Props、事件、v-model 与插槽如何分工
一个组件可以同时使用这些能力,但每种能力应表达不同职责。
例如,一个弹窗组件可以这样组合:
<BaseDialog
v-model="dialogVisible"
title="删除任务"
@confirm="deleteTask"
>
<p>删除后无法恢复,是否继续?</p>
<template #footer="{ close }">
<button type="button" @click="close">取消</button>
<button type="button" @click="confirmDelete">确认删除</button>
</template>
</BaseDialog>v-model 管理可见性,title 是简单配置,默认插槽提供正文,具名作用域插槽定制操作区,事件负责业务通知。不要把所有配置都改成插槽,也不要用插槽代替本已清晰的事件契约。
十四、TypeScript 中声明插槽类型
Vue 3.3+ 可以在 <script setup lang="ts"> 中使用 defineSlots,描述插槽名称和参数类型:
<!-- TypedTaskList.vue -->
<template>
<ul>
<li v-for="task in tasks" :key="task.id">
<slot name="item" :task="task"></slot>
</li>
</ul>
<slot name="empty"></slot>
</template>
<script setup lang="ts">
interface Task {
id: number
title: string
completed: boolean
}
defineProps<{
tasks: Task[]
}>()
defineSlots<{
item(props: { task: Task }): any
empty(props: {}): any
}>()
</script>父组件使用 #item="{ task }" 时,编辑器可以推断 task 的结构。插槽名称拼错或参数使用不当时,也更容易在开发阶段发现问题。
如果项目尚未使用 TypeScript,不必为了声明插槽而单独引入整套类型系统。清晰的插槽命名、示例和组件文档同样重要。
十五、Options API 与 Vue 2 旧语法
15.1 Vue 3 Options API
Options API 中,插槽模板写法与组合式 API 相同,脚本里通过 this.$slots 读取:
<script>
export default {
computed: {
hasFooter() {
return Boolean(this.$slots.footer)
}
}
}
</script>模板中依然使用:
<BaseCard>
<template #header>
<h2>任务面板</h2>
</template>
<p>默认插槽内容</p>
</BaseCard>15.2 维护 Vue 2 项目时的差异
Vue 2.6 之前常见 slot 和 slot-scope 写法:
<!-- 旧语法,仅用于理解历史项目 -->
<BaseLayout>
<template slot="header" slot-scope="slotProps">
<h2>{{ slotProps.title }}</h2>
</template>
</BaseLayout>Vue 2.6 起统一为 v-slot,Vue 3 使用新语法。维护旧项目时应先确认 Vue 版本,并避免在同一处混用新旧语法。
Vue 2 与 Vue 3 在插槽函数、普通插槽和作用域插槽的内部统一方式上也有差异。跨版本封装组件时,不能只替换模板符号,还应结合实际渲染结果进行验证。
十六、常见误区与自查
16.1 不要把所有文本都改成插槽
<!-- 简单标题用 Prop 更直观 -->
<BaseCard title="学习任务" />只有标题需要复杂标记、图标或额外组件时,才值得开放 header 插槽。插槽越多,组件使用成本通常越高。
16.2 不要混淆插槽内容与插槽出口
父组件写的是插槽内容,子组件的 <slot> 是内容出口。看到父组件模板时,不要把 <template #header> 当成子组件内部元素;它只是内容分发声明。
16.3 不要期待普通插槽直接读取子组件数据
普通插槽使用父组件作用域。需要子组件数据时,必须在 <slot> 上绑定插槽 Props,并由父组件通过 v-slot 接收。
16.4 具名插槽不要与默认插槽随意混写
当组件同时使用多个插槽时,推荐统一写成 <template #名称>。这能避免内容归属不清,也方便后续调整顺序。
16.5 不要无条件渲染所有插槽外壳
没有页脚内容却仍渲染带边距的 footer,可能留下空白。使用 $slots.footer 控制外层结构,但不要把插槽存在等同于一定有可见内容。
16.6 不要在插槽中修改子组件内部数据
作用域插槽传入的对象可能属于子组件。父组件插槽直接修改 task.completed,会让数据所有权再次变得模糊。更清晰的做法是由子组件提供 toggle 方法,或通过事件通知真正的数据所有者更新。
16.7 常见问题速查
十七、总结
插槽让组件复用从“传数据”进一步扩展到“组合模板”:
默认插槽为父组件内容提供一个出口,适合卡片正文等单一内容区域。
后备内容在父组件没有提供对应内容时显示,可提供合理的默认界面。
具名插槽通过
name和#名称把不同内容分发到不同位置。插槽内容默认在父组件作用域编译,不能直接读取子组件内部数据。
作用域插槽通过插槽 Props 把子组件数据交给父组件渲染。
动态插槽名使用
#[name],适合确有运行时分发需求的场景。$slots和useSlots可以检测插槽,但插槽存在不等于一定产生可见内容。包装组件时要转发插槽及插槽 Props,避免丢失原组件能力。
Props、事件、
v-model与插槽各有职责,应根据数据和展示边界选择。好的插槽设计不是出口越多越好,而是让稳定结构与可变内容清晰分离。
下一站预告
下一篇《动态组件与异步组件》将学习如何使用 <component> 在运行时切换组件,并通过异步组件按需加载代码,让组件组合更加灵活,也让首屏资源更加精简。
作者:洋洋技术笔记 发布日期:2026-11-16 系列:Vue.js从入门到精通 - 第11篇
原文链接:洋洋的技术笔记
评论区