Slidev 全局上下文Global Context与编程式导航 API深入 $nav、$slidev 与 Client Composables【免费下载链接】slidevPresentation Slides for Developers项目地址: https://gitcode.com/GitHub_Trending/sl/slidev本指南完整讲解 Slidev面向开发者的 Web 幻灯片框架注入到每张幻灯片中的全局上下文对象与编程式 API包括模板中可直接使用的$nav、$slidev、$page、$clicks、$frontmatter、$renderContext以及从slidev/client导入的useNav()、useSlideContext()、useDarkMode()、useIsSlideActive()等组合式函数和onSlideEnter/onSlideLeave生命周期钩子。读完本文你将能在幻灯片与自定义组件中读取导航状态、配置信息并编程式控制翻页与点击步进构建页脚页码、演示者视图专属控件、自定义导航按钮等进阶能力。本文以仓库内技能参考文档 core-global-context.md 与官方指南 global-context.md 为主线并结合客户端源码佐证底层实现。一、Slidev 注入的全局上下文概览Slidev 会向每张幻灯片及其内部组件注入一组全局上下文值用于“编程式地访问导航状态、幻灯片信息与配置”。它们既可以在 Markdown 幻灯片正文中作为模板变量使用也可以在script setup中通过组合式函数以类型安全的方式获取。在幻灯片与组件中直接访问的模板变量如下Page {{ $page }} of {{ $nav.total }} Title: {{ $slidev.configs.title }}divLayout: {{ $frontmatter.layout }}/div从底层实现看这些全局值并不是魔法字符串而是通过 Vue 的依赖注入体系提供的真实响应式对象。在 setup/root.ts 中应用根节点构建了reactive({ nav, configs, themeConfigs })这一上下文并通过字符串类型的注入键见 constants.ts之所以用字符串而非 Symbol注释说明是为了让 HMR 更稳定逐层提供injectionSlidevContext$$slidev-context整个$slidev上下文对象injectionRenderContext$$slidev-render-context当前渲染上下文injectionCurrentPage$$slidev-page当前页码从 1 开始injectionClicksContext$$slidev-clicks-context当前点击上下文。模板中$前缀的变量正是由这些注入值派生因此它们具备完整的响应式能力——页码翻动、点击推进、明暗切换时引用它们的模板会自动更新。二、$nav导航状态与控制器$nav是文档与源码中最重要的导航入口它同时暴露“状态”当前页、总页数、布局名、方向等与“行为”前进、后退、跳转、进入/退出演示者模式等。原文档给出的核心属性如下表PropertyTypeDescription$nav.currentPagenumberCurrent page (1-indexed)$nav.currentLayoutstringCurrent layout name$nav.totalnumberTotal slides$nav.isPresenterbooleanIn presenter mode$nav.next()functionNext click/slide$nav.prev()functionPrevious click/slide$nav.nextSlide()functionNext slide$nav.prevSlide()functionPrevious slide$nav.go(n)functionGo to slide n在 Markdown 或组件模板中的典型用法button click$nav.next下一步 / 下一点击/button button click$nav.nextSlide下一张幻灯片/button button click$nav.go(5)跳到第 5 页/button若需要更完整的能力可对照源码中SlidevContextNav接口composables/useNav.ts它比上表多出大量可用成员常见的有状态类currentPath、currentSlideNo、currentSlideRoute、currentFrontmatter、currentTransition、clicks、clicksTotal、hasNext、hasPrev、tocTree、navDirection前进为 1后退为 -1、clicksDirection行为类goFirst()、goLast()、enterPresenter()、exitPresenter()、openInEditor()从SlidevContextNavState合并而来的视图状态useNav()返回完整类型见 useNav.tsisPrintMode、isPrintWithClicks、isEmbedded、isPlaying、isNotesViewer等。$nav.currentFrontmatter是“当前幻灯片 frontmatter含自定义字段”而模板变量$frontmatter同样指向当前页 frontmatter——二者的细微差异会在后文说明。理解导航行为需要知道next()与nextSlide()的语义差异从源码 useNav.ts 可以看到next()会先判断当前页点击步数是否已到上限未到则仅推进clicks查询参数即本页内的点击动画步进已到则翻到下一张幻灯片而nextSlide()/prevSlide()无论本页是否还有点击步骤都直接切换幻灯片可通过lastClicks参数控制是否把上一页跳到最后一步。go(n)useNav.ts内部会把clicks夹在clicksStart与当前页点击总数之间再通过 vue-router 的push更新路由 path 与clicks查询参数——这也解释了为什么 URL 中会出现/5?clicks3这类片段刷新后能精确恢复进度。三、$slidev全局上下文对象$slidev是“项目级”的全局上下文容器其结构在 modules/context.ts 中定义PropertyDescription$slidev.configsProject config (title, etc.)即 headmatter 解析后的完整配置$slidev.themeConfigsTheme config主题配置$slidev.nav导航对象即$nav$slidev.configs是响应式对象承载整份演示文稿的顶层配置frontmatter 中---与---之间的 headmatter。例如定义了title后所有页面都能读取它--- title: My First Slidev! --- # Page 1 --- # Any Page {{ $slidev.configs.title }} !-- My First Slidev! --$slidev.themeConfigs则指向解析后的主题配置通常配合主题的自定义字段使用。例如在 headmatter 中声明主题主色--- title: My First Slidev! themeConfig: primary: #213435 ---随后即可在模板中访问{{ $slidev.themeConfigs.primary }} !-- #213435 --在 setup/root.ts 中可以看到themeConfigs是computed(() configs.themeConfig)说明它是从项目配置中派生出来的响应式计算属性configs本身则来自客户端环境模块packages/client/env.ts导出在开发服务器启动与构建时由服务端解析注入。四、$page、$clicks、$frontmatter、$renderContext$page当前页码从 1 开始计数与$nav.currentSlideNo等价根注入时injectionCurrentPage即为computed(() context.nav.currentSlideNo)。Page: {{ $page }}$clicks当前幻灯片已推进的点击步数通常与v-click等点击动画配合用于条件渲染不同内容div v-if$clicks 3Content/div注意区分$clicks与$nav.clicks前者是“当前幻灯片局部的点击步数”由useClicks.ts创建的ClicksContext提供后者由路由上的全局clicks查询参数驱动。关于点击动画的完整用法可参见 animations.md。$frontmatter当前幻灯片的 frontmatter 对象可读取自定义字段Layout: {{ $frontmatter.layout }}需要留意的是对位于幻灯片之外的全局层组件如global-bottom.vue参见 global-layers.md$frontmatter为空对象若想在不同位置读取“当前页”完整的 frontmatter包括自定义字段使用$nav.currentFrontmatter更可靠——它来源于当前路由meta.slide.frontmatter见 useNav.ts。$renderContext当前渲染上下文用于判断页面此刻处于哪种视图中可选值如下slide—— 普通幻灯片视图overview—— 总览模式presenter—— 演示者模式previewNext—— 演示者模式中的“下一张预览”。据此可以写出只在特定视图出现的内容。官方文档还推荐在需要按上下文渲染时直接使用内置RenderWhen组件位于packages/client/builtin/RenderWhen.vue它会按context属性精确控制渲染时机比手写v-if更声明式。五、从slidev/client导入组合式函数在script setup中若想“编程式、类型安全地”获取上下文应从slidev/client公共入口导入。公共 API 的完整导出清单见 index.ts其中导航、明暗、活动状态、上下文与生命周期钩子都从该包统一暴露import { useNav, useDarkMode, useIsSlideActive, useSlideContext, onSlideEnter, onSlideLeave, } from slidev/client一个典型的完整组件示例script setup import { onSlideEnter, onSlideLeave, useDarkMode, useIsSlideActive, useNav, useSlideContext } from slidev/client const { $slidev } useSlideContext() const { currentPage, currentLayout, currentFrontmatter, currentSlideRoute } useNav() const { isDark } useDarkMode() const isActive useIsSlideActive() onSlideEnter((to, from) { /* 进入本页时 */ }) onSlideLeave((to, from) { /* 离开本页时 */ }) /scriptuseNav()返回完整的导航对象SlidevContextNavFull可响应式地读取状态或调用导航方法const nav useNav() nav.next() nav.go(5) console.log(nav.currentPage)底层实现有个值得注意的细节useNav()是createSharedComposable包装的全局共享导航但当它处于某张幻灯片的组件树内部具备注入上下文时会优先injectLocal读取当前幻灯片局部注入的导航并把两者合并后返回见 useNav.ts。这意味着在“幻灯片内部”调用时得到的导航会与该页的局部点击/路由状态对齐行为更精确。useDarkMode()管理明暗主题返回isDark状态与toggle方法以及isColorSchemaConfigured配置标记见 composables/useDarkMode.tsconst { isDark, toggle } useDarkMode()在模板中同样可以通过$slidev上下文联动例如为演示者视图添加一个“切换亮色/暗色”的按钮。useIsSlideActive()返回一个refboolean标识当前组件所在的幻灯片是否为活动页const isActive useIsSlideActive()它常用于需要在非活动页暂停动画、轮播或媒体播放的场景。useSlideContext()一次性取回当前幻灯片内的全部注入上下文const { $page, $clicks, $frontmatter } useSlideContext()其实现位于 context.ts除上述三项外还返回$slidev、$nav、$clicksContext、$route、$renderContext、$scale幻灯片缩放比例、$zoom等。需要注意官方文档给出的一条警告当某文件中使用了useSlideContext模板对$slidev的自动注入会被关闭因此需要从useSlideContext()的返回值中手动取$slidev对象。另外仓库官方文档强调过去社区常见的import { isDark } from slidev/client/logic/dark.ts这类深路径导入属于内部实现细节不推荐使用内部模块随时可能变动应始终优先使用slidev/client公开 API。六、生命周期钩子onSlideEnter与onSlideLeaveSlidev 为幻灯片提供了两个语义化的生命周期钩子import { onSlideEnter, onSlideLeave } from slidev/client onSlideEnter((to, from) { // 幻灯片成为活动页 startAnimation() }) onSlideLeave((to, from) { // 幻灯片变为非活动页 cleanup() })两个回调都接收(to, from)参数可用于对比来源路由与目标路由。它们在客户端 logic/slides.ts 中实现并由 index.ts 导出。重要告诫不要在幻灯片中使用onMounted/onUnmounted来绑定“进入/离开页面”的逻辑——因为幻灯片组件实例在导航过程中会被复用/常驻这些 Vue 原生钩子不会按页触发。应一律改用onSlideEnter/onSlideLeave。这一主题在 slide-hook.md技能参考见 api-slide-hooks.md中有更完整的讨论。七、条件渲染实战按视图、页面与布局输出内容综合以上上下文变量可以写出精确的条件渲染逻辑。原文档给出的三个典型场景如下!-- 仅在演示者模式显示 -- div v-if$nav.isPresenter Presenter notes /div !-- 封面页隐藏页脚 -- footer v-if$nav.currentLayout ! cover Page {{ $nav.currentPage }} /footer !-- 按渲染上下文输出不同内容 -- template v-if$renderContext slide Normal view /template template v-else-if$renderContext presenter Presenter view /template在此基础上可继续扩展出更多真实场景组合$renderContext的多个取值让某段内容只在主视图非总览、非演示者中渲染官方文档即使用了[slide, presenter].includes($renderContext)这一写法而使用$clicks可以实现“点 N 次后才出现”的递进内容div v-if$clicks 2第二击之后才出现/div结合$page、$nav.total制作“第 x 页 / 共 y 页”的进度页脚结合$nav.currentLayout cover排除封面再叠加上节介绍的按钮式$nav.next()/$nav.prev()即可组成完整的自定义导航条。这些写法的响应式保证来自第一节所述的注入体系——$page、$clicks、$renderContext均为注入的 ref 派生值切换视图或推进点击时模板会自动刷新。八、类型导入slidev/types与编程式类型安全当需要在脚本中编写强类型逻辑例如处理目录树时可以从slidev/types导入类型import type { TocItem } from slidev/types function tocFunc(tree: TocItem[]): TocItem[] { // ... }TocItem是幻灯片目录树节点的类型定义于 packages/types/src/toc.ts$nav.tocTree即返回该类型的数组见 useNav.ts 与useTocTree实现可用于在页面内自绘可点击的目录。slidev/types包packages/types/src/index.ts集中导出了客户端与服务端共享的全部类型包括SlideRoute、ClicksContext、RenderContext、frontmatter 相关类型等编写自定义组件与主题时可一并参考。九、深挖方向与相关资源本主题在仓库中还有两条更完整的平行资料仓库正式文档 docs/guide/global-context.md 与面向 AI 技能使用的参考文档 skills/slidev/references/core-global-context.md二者与本篇互为补充。若想继续深入导航实现细节完整阅读 composables/useNav.ts包含useNavBase、useFixedNav打印等固定上下文使用、useNavState从路由解析页码/点击参数三层结构上下文注入与取值对照 setup/root.ts、context.ts 与 constants.ts理解$变量从 provide/inject 到模板的完整链路点击机制$clicks的底层由 composables/useClicks.ts 提供配合CLICKS_MAX常量定义于 constants.ts理解点击进度的边界相关动画与视图点击动画见 core-animations.md渲染上下文组件见 components.md 中的RenderWhen。将这些模板变量、组合式函数与生命周期钩子组合使用足以把“静态 Markdown 幻灯片”升级为具备自定义导航、上下文感知内容与精细交互的工程化演示文稿。【免费下载链接】slidevPresentation Slides for Developers项目地址: https://gitcode.com/GitHub_Trending/sl/slidev创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
