Slidev 全局图层（Global Layers）：用 global-top / global-bottom / slide-top / slide-bottom 构建跨页持续组件

Slidev 全局图层Global Layers用 global-top / global-bottom / slide-top / slide-bottom 构建跨页持续组件【免费下载链接】slidevPresentation Slides for Developers项目地址: https://gitcode.com/GitHub_Trending/sl/slidev本文以 Slidev 官方文档 Global Layers 为核心系统讲解如何用global-top.vue、global-bottom.vue、slide-top.vue、slide-bottom.vue和custom-nav-controls.vue五个约定文件为演示文稿添加页脚、跨页动画、全局特效与自定义导航按钮并结合仓库中虚拟模块生成逻辑与导出命令的源码说明图层的挂载位置、z 轴层级、条件渲染以及--per-slide导出参数背后的实现原理。一、什么是全局图层Global Layers在 Slidev 中每一页幻灯片的内容是独立的翻页时上一页组件会被卸载或隐藏写在某页 Markdown 里的 DOM 无法自然地“活”到下一页。全局图层Global Layers解决了这个问题——它允许你定义**跨页持续存在persist across slides**的自定义组件典型用途包括所有页面通用的页脚署名、版权信息、页码跨越多个页面的连续动画或全局特效固定在页面上的导航状态指示器追加到内置导航栏NavControls中的自定义控制按钮。Slidev 通过“约定文件名 自动拾取pick up automatically”的机制实现这一点只要在项目根目录下创建特定名称的文件构建系统就会自动发现并挂载它们无需任何手动 import 或配置。二、五个图层文件及其作用范围根据 docs/features/global-layers.mdSlidev 提供两类图层1. 全局图层单实例在项目根目录创建以下文件即被自动拾取文件作用范围实例数global-top.vue浮在所有幻灯片之上1 个整个演示文稿global-bottom.vue位于所有幻灯片之下1 个整个演示文稿custom-nav-controls.vue渲染进 NavControls 导航栏1 个2. 每页图层Per-slide 实例文件作用范围实例数slide-top.vue浮在每一页幻灯片之上每一页一个实例slide-bottom.vue位于每一页幻灯片之下每一页一个实例每页图层的用法与全局图层相同但区别在于它们会被应用到每一页上因此同时存在多个实例。这一点在源码中可以得到印证SlideTop/SlideBottom是在单个页面的包裹组件 SlideWrapper.vue 内部渲染的——由于每个幻灯片路由对应一个SlideWrapper每页自然各持有一份实例而GlobalTop/GlobalBottom则在页面集合的容器 SlidesShow.vue 级别渲染一次整个演示文稿只有单实例。三、z 轴层级关系Layers relationship原文档明确了五层内容在 z 轴上从上到下的堆叠顺序NavControls自定义导航控件custom-nav-controls.vueGlobal Topglobal-top.vue— 单实例Slide Topslide-top.vue— 每页一个实例Slide Content幻灯片正文内容Slide Bottomslide-bottom.vue— 每页一个实例Global Bottomglobal-bottom.vue— 单实例源码层面的印证Slidev 默认不依赖显式 z-index而是靠DOM 顺序后出现者叠在上方来实现上述层级在 SlidesShow.vue 中DOM 顺序为先渲染GlobalBottom /再渲染幻灯片容器#slideshow最后渲染GlobalTop /——因此 GlobalBottom 在最底层、GlobalTop 压在所有幻灯片之上在 SlideWrapper.vue 中页面内部的 DOM 顺序为SlideBottom /→ 当前页组件component :isprops.route.component /→SlideTop /——即 SlideTop 压在本页内容上SlideBottom 位于本页内容之下NavControls.vue 在导航栏末尾渲染CustomNavControls /导航栏本身位于全局图层之上与文档描述的层级一致。理解这套层级关系后可以按“贴近内容的程度”选择图层需要压住页面内容如进度条覆盖层用slide-top.vue需要垫在内容下方如背景纹理用slide-bottom.vue需要覆盖整个演示文稿包括页面切换动画之外的固定区域则用global-top.vue/global-bottom.vue。四、完整使用示例以下示例完整继承自官方文档 docs/features/global-layers.md。1. 最简单的页脚global-bottom.vue!-- global-bottom.vue -- template footer classabsolute bottom-0 left-0 right-0 p-2Your Name/footer /template创建该文件后Your Name文本会出现在所有幻灯片上。类名absolute bottom-0 left-0 right-0 p-2是 UnoCSS 原子类效果等价于绝对定位贴底、左右拉伸、内边距 0.5rem。2. 自定义导航按钮custom-nav-controls.vue!-- custom-nav-controls -- template button classicon-btn titleNext click$nav.next div classi-carbon:arrow-right / /button /template该按钮会出现在 NavControls 导航栏中源码中渲染位置见 NavControls.vue 第 196 行。$nav是 Slidev 注入的全局导航上下文$nav.next即触发翻页图标类i-carbon:arrow-right来自 UnoCSS 图标集合。3. 基于导航状态的条件渲染若图层组件需要根据当前导航状态决定显隐可以使用 全局上下文Global Context。文档给出了三个典型例子从第 4 页隐藏页脚!-- hide the footer from Page 4 -- template footer v-if$nav.currentPage ! 4 classabsolute bottom-0 left-0 right-0 p-2 Your Name /footer /template在cover布局页隐藏页脚!-- hide the footer from cover layout -- template footer v-if$nav.currentLayout ! cover classabsolute bottom-0 left-0 right-0 p-2 Your Name /footer /template一个带页码的页脚封面页除外!-- an example footer for pages -- template footer v-if$nav.currentLayout ! cover classabsolute bottom-0 left-0 right-0 p-2 {{ $nav.currentPage }} / {{ $nav.total }} /footer /template在 Presenter 模式下隐藏自定义按钮!-- custom-nav-controls -- !-- hide the button in Presenter mode -- template button v-if!$nav.isPresenter classicon-btn titleNext click$nav.next div classi-carbon:arrow-right / /button /template$nav上下文在模板中直接可用如果在script setup中需要编程式访问可按 docs/guide/global-context.md 中的方式通过useNav()解构currentPage、currentLayout、currentFrontmatter、currentSlideRoute等响应式状态。五、底层原理虚拟模块如何自动发现图层文件上面反复强调的“自动拾取”并非魔法其实现位于 packages/slidev/node/virtual/global-layers.ts。该文件定义了一个 Vite 虚拟模块模板id 为/slidev/global-layers在启动时按如下逻辑生成真实代码文件名匹配为每个图层位置准备一组候选文件名并对每个项目根目录roots支持多入口/主题等场景生成{name}.{ts,js,vue}的 glob 导入。从源码看各位置的候选名分别为GlobalTopglobal、global-top、GlobalTopGlobalBottomglobal-bottom、GlobalBottomSlideTopslide-top、SlideTopSlideBottomslide-bottom、SlideBottom值得注意的是GlobalTop的候选名中额外包含global——从源码结构看创建根目录下的global.vue也会被识别为顶部全局图层Global.vue同理这是文档未明示、但源码确认的一个扩展写法。同时.ts/.js后缀也被支持意味着图层不局限于单文件组件。运行时渲染生成的模块对每个候选 glob 取Object.values(...)[0]即实际存在的组件过滤掉空值后导出如下组件export const GlobalTop { render: () GlobalTopComponents.map(comp h(comp)) }这种h(comp)的列表渲染方式还保留了多根目录场景下渲染多个组件的能力并以.filter(Boolean)保证文件缺失时静默降级为空渲染而不是报错。客户端消费客户端从虚拟模块路径#slidev/global-layers导入这些导出并分别在 SlidesShow.vueGlobalBottom/GlobalTop与 SlideWrapper.vueSlideBottom/SlideTop中挂载位置关系与第三节所述完全一致。custom-nav-controls.vue的发现逻辑自定义导航控件走的是另一条更直接的路径packages/slidev/node/virtual/nav-controls.ts 定义虚拟模块/slidev/custom-nav-controls它在构建期直接对每个根目录下的custom-nav-controls.vue与CustomNavControls.vue做existsSync同步存在性检查把命中的文件 import 进来并生成一个默认导出的渲染函数render: () [h(__n0), ...]。也就是说文件存在才会被引入不存在则虚拟模块渲染空列表——同样实现了“创建即生效缺失即无感”的约定式行为。六、导出Export时的--per-slide注意事项官方文档中的一条关键提示是如果global-top.vue或global-bottom.vue依赖当前导航状态如$nav.currentPage导出时应使用--per-slide选项以确保每一页被赋予正确的状态或者改用slide-top.vue/slide-bottom.vue。这条建议的背后是导出实现的具体行为。在 packages/slidev/node/commands/export.ts 中perSlide false, // ExportOptions 默认值见第 187 行 // ... height: perSlide ? height : height * pages.length, // 第 202 行viewport 高度默认模式perSlide false下Playwright 会把 viewport 高度设为height * pages.length即所有页面纵向排列在同一个超长视口里一次性渲染——此时$nav.currentPage等导航状态无法逐页切换依赖导航状态的全局图层所有页看到的都是同一状态。启用--per-slide后CLI 参数映射见 export.ts 第 589 行viewport 恢复为单页高度height逐页渲染并应用各自的导航状态从而保证状态相关的图层在每页上呈现正确。由此可以得出两条实用选型规则图层内容不依赖导航状态固定页脚、静态背景、署名用global-*即可导出无特殊要求图层依赖$nav状态页码、按页显隐要么改用每页实例的slide-top.vue/slide-bottom.vue每页天然持有各自的上下文要么保留global-*并在导出时加--per-slide。此外打印/导出路径同样会渲染全局图层PrintSlideClick.vue 中同样挂载了GlobalTop/GlobalBottom保证导出产物与播放视图的图层表现一致。七、实践建议小结结合文档与源码日常使用全局图层时建议优先最小化能用slide-*解决的每页页码、每页状态就不要用global-*天然规避--per-slide导出问题层级选择覆盖内容用 top 层垫底内容用 bottom 层需要进导航栏的控件用custom-nav-controls.vue它渲染在 NavControls.vue 内位于整个层级栈最上方定位方式图层组件根元素通常使用absolute定位配合原子类布局如示例中的absolute bottom-0 left-0 right-0避免破坏幻灯片本身的布局流命名与扩展除文档明确的global-top.vue/global-bottom.vue/slide-top.vue/slide-bottom.vue外源码确认还支持对应的 PascalCase 写法如GlobalTop.vue与.ts/.js后缀global.vue会被当作global-top.vue处理状态访问模板中用$navscript setup中用useNav()二者来源均为 docs/guide/global-context.md 描述的全局上下文。更多周边入口可参考 docs/guide/ui.md自定义 UI 总览、docs/guide/exporting.md导出指南以及仓库中面向 Agent 的技能参考 skills/slidev/references/layout-global-layers.md。【免费下载链接】slidevPresentation Slides for Developers项目地址: https://gitcode.com/GitHub_Trending/sl/slidev创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考