2026/9/10 10:27:22
FEATURED · 精选文章 
Slidev 逐页 Frontmatter 完整指南为每一张幻灯片做精细化配置【免费下载链接】slidevPresentation Slides for Developers项目地址: https://gitcode.com/GitHub_Trending/sl/slidev在 Slidev 中演示文稿由 Markdown 编写幻灯片之间用---分隔而每张幻灯片正文顶部都可以用一段 YAML Frontmatter 为该页单独配置布局、背景、点击次数、过渡动画、缩放比例等属性。本文将以skills/slidev/references/core-frontmatter.md为骨架结合仓库中的类型定义与解析源码系统讲解逐页 Frontmatter 的每一个配置项并给出可直接复制运行的完整示例帮助你精确控制每一张幻灯片的渲染效果。阅读本文后你将掌握布局、背景、点击步进、过渡、导入、路由别名等全部单页配置手段并能理解它们在内核中的解析与生效机制。Frontmatter 与 Headmatter单页配置与全局配置的分工在 Slidev 中frontmatter 分为两层可参考 语法指南Headmatter位于slides.md最顶部的第一个 frontmatter 块用于配置整个幻灯片主题、字体、宽高比等作用域是全局。Per-Slide Frontmatter本文主题位于每个---分隔的幻灯片段落顶部、正文之前用于配置这一页的布局与行为。两者的类型分别由 frontmatter.ts 中的Headmatter与Frontmatter接口定义。其中Headmatter通过OmitFrontmatter, ...继承了逐页字段并额外提供defaults?: Frontmatter字段——你可以在 headmatter 中写defaults:来给所有页面预设默认的单页配置再在个别页面覆盖它。从解析层看packages/parser/src/core.ts 用正则RE_FRONTMATTER /^---.*\r?\n([\s\S]*?)---/提取每一页的 frontmatter 原始内容并交给yaml解析。而 packages/client/constants.ts 中的FRONTMATTER_FIELDS数组则列出了被前端运行时真正消费的单页字段clicks、clicksStart、disabled、hide、hideInToc、layout、level、preload、routeAlias、src、title、transition、zoom、dragPos、lang、clickAnimation。Layout选择这一页的排版骨架最简单的逐页配置就是指定布局--- layout: center ---Layout 本质上是包裹幻灯片内容的 Vue 组件见 布局指南Slidev 内置了以下布局类型定义见 builtin-layouts.ts组件源码在 packages/client/layoutsdefault、cover、center、two-cols、two-cols-header、image、image-left、image-right、iframe、iframe-left、iframe-right、quote、section、statement、fact、full、intro、end、none几点使用要点默认布局并非一成不变第一张幻灯片默认使用cover其余默认使用default源码注释见 frontmatter.ts。这也是为什么封面通常无需显式写layout: cover。布局的加载顺序为内置布局 → 主题提供的布局 → addon 提供的布局 → 项目layouts目录下的自定义布局后加载者覆盖先加载者。layout: none表示不使用任何布局框架内容将完全自由排版。Background 与 class铺背景、加样式类--- background: /image.jpg backgroundSize: cover class: text-white ---background为当前页设置背景图一般给资源路径或 URLSlidev 会将其渲染为页面背景解析器在 core.ts 的extractImagesUsage中会从image、backgroundImage、background等键收集图片以便预加载与打包。需要纯色等 CSS 背景时也可使用任意 CSS background 值。backgroundSize控制背景尺寸常见值为cover或contain。class附加到当前幻灯片根元素上的自定义 class类型上支持字符串、数组或对象class?: string | string[] | Recordstring, unknown可配合 UnoCSS 原子类使用例如示例中的text-white让文字在深色背景上可读。clicks 与 clicksStart精确控制点击步进--- clicks: 5 # 本页需要的总点击次数 clicksStart: 0 # 起始点击数 ---点击步进是演示的常用节奏控制手段。clicks手动指定该幻灯片总共需要多少次点击才能走完当不指定时Slidev 会根据页面中v-click/v-clicks指令的使用自动计算frontmatter.ts 注释说明这一点。clicksStart则指定起始点击序号默认值为 0。若动画较多手动设定clicks还能避免 Slidev 自动推算与实际步进不一致。关于点击指令的更多用法可参考 动画指南点击状态的整体上限为CLICKS_MAX 999999见 constants.ts。Transition给页面切换加过渡--- transition: fade ---内置过渡动画包括fade、fade-out、slide-left、slide-right、slide-up、slide-down、view-transition联合类型见 frontmatter.ts也支持任意自定义 CSS 过渡名甚至传入对象形式的 VueTransitionGroup属性如duration、enterFromClass等。参考文档给出了前进 / 后退使用不同动画的写法--- transition: slide-left | slide-right ---其原理在 transition.ts 中可以看到resolveTransition会保留|拼接的名字按前进 / 后退方向分别取用direction 0取前一页/当前页 meta 上的过渡否则取反向。同时 headmatter 层也可以设置全局transition单页 frontmatter 会在路由 meta 上覆盖它。view-transition是浏览器原生 View Transition 的桥接过渡可作为现代演示的加分项。Zoom单页缩放内容--- zoom: 0.8 # 将内容缩放到 80% ---zoom控制当前页内容的缩放比例默认值是 1。它与全局的canvasWidth默认 980px配合Slidev 先把内容绘制在固定画布上再等比缩放到屏幕因此zoom: 0.8相当于在画布层面把内容缩小到 80%。适合在内容较多、需要整体缩小防止溢出时使用大于 1 的值则可以放大局部细节。Hide / Disabled让某页存在但不可见--- disabled: true # 隐藏该幻灯片 # 或者 hide: true ---disabled与hide语义相同源码注释明确写 Same ashide, completely hide and disable the slide见 frontmatter.ts。被标记的页面在解析阶段就直接被跳过不会出现在播放、概述和演示者视图中从 packages/parser/src/fs.ts 的加载流程可以看到loadSlide第一步就是检查slide.frontmatter.disabled || slide.frontmatter.hide并直接return。所以它适合保留备用内容但不演示的页面也常用于src导入多份文件时剔除不需要的页。Table of Contents对目录组件的控制--- hideInToc: true # 从 Toc 组件中隐藏 level: 2 # 覆盖标题级别 title: Custom Title # 覆盖幻灯片标题 ---hideInToc让当前页不出现在Toc目录组件中适合隐藏过渡页、致谢页等不想进目录的页面。title/level分别覆盖TitleRenderer与Toc组件使用的标题文本与标题级别类型注释要求需同时配合title生效见 frontmatter.ts。当页面的 H1 标题不够精准、或想在目录里显示更简洁的名字时非常有用。关于Toc组件用法参见 内置组件文档。src把别的 Markdown 文件导入进来--- src: ./slides/intro.md # 导入一个 markdown 文件 ---src让你能把长演示拆分成多个 Markdown 文件与 导入幻灯片 对应文件的复用性随之提升。需要注意声明了src的页面其自身正文内容会被忽略实际渲染内容完全来自被导入文件。还可以只导入目标文件的若干页--- src: ./other.md#2,5-7 # 只导入第 2、5、6、7 页 ---#后面的范围字符串会被parseRangeString解析允许2,5-7这类混合区间。解析层的具体行为在 packages/parser/src/fs.ts 中非常清晰以/开头的路径相对项目根目录解析相对路径则相对当前幻灯片所在文件的目录解析支持同一文件多处导入但同一页会展开多次对循环导入自身导入自身、或 A→B→A会记录Circular import detected错误并终止被导入页会继承导入者的 frontmattersrc字段本身被剔除这就是 frontmatter 合并 机制的基础。Route Alias给页面一个人类可读的 URL--- routeAlias: intro # 访问 /intro 而不是 /1 ---默认情况下幻灯片路由就是数字序号/1、/2…。routeAlias可以为该页创建一个稳定的别名之后既可以在 URL 中直接访问/intro也可以配合Link组件做跨页跳转避免硬编码序号——这在演示内容增删后依然稳定。Preload延迟挂载到真正进入时--- preload: false # 进入前不挂载 ---preload默认值为true即当上一张幻灯片处于激活状态时就开始预载下一张以换取更快的切换体验。当幻灯片包含重型资源大图、Monaco、WebGL 等不希望提前加载时可以置为false让页面到真正进入时才挂载。前端类型注释明确说明其作用是 Preload the slide when the previous slide is activefrontmatter.ts。dragPos为可拖拽元素指定初始位置--- dragPos: logo: 100,50,200,100,0 # 左, 上, 宽, 高, 旋转 arrow: 300,200,50,50,45 ---dragPos用于记录可拖拽元素借助VDrag/VDragArrow的位置。每项格式为left,top,width,height,rotate五个值组成的字符串键名对应元素的 id。类型注释特别提醒Normally you dont need to set this manually——演示时你在页面上拖动元素后Slidev 通常会自动把位置写回 frontmatter需开启对应持久化机制手动书写适合为拖拽元素预设一个初始坐标。完整使用说明参见 拖拽元素文档。Image / Iframe 布局配图页与嵌入页图片布局配套使用image等字段--- layout: image-left image: /photo.jpg backgroundSize: contain class: my-custom-class ---image、image-left、image-right布局会按image字段渲染配图backgroundSize: contain保证整图可见而不会被裁剪。iframe 系列布局则需要提供url--- layout: iframe url: https://example.com ---iframe/iframe-left/iframe-right会以 iframe 内嵌外部页面示例 URL 仅作格式演示请替换为你自己的页面。解析器同样会把这类字段中的图片 URL 收集起来用于预加载core.ts。Two Columns左右两栏布局--- layout: two-cols --- # Left Side Content ::right:: # Right Side Contenttwo-cols布局中用::right::分隔符把内容切成左右两栏::right::之前是左栏、之后是右栏。two-cols-header则额外支持一个顶部通栏标题--- layout: two-cols-header --- # Header ::left:: Left content ::right:: Right contenttwo-cols-header中::left::之后是左栏、::right::之后是右栏。这类槽位语法本质上是布局的具名插槽简写更底层的机制见 slot-sugar 文档如果你需要自定义栏位划分也可以自己编写布局编写布局指南。Full Example一张实战模板页把上面所有字段串起来一个信息完整、可直接复制修改的页面如下--- layout: center background: /bg.jpg class: text-white text-center transition: fade clicks: 3 zoom: 0.9 hideInToc: false --- # Slide Content解读layout: center内容居中background: /bg.jpgclass: text-white让深色背景上的文字清晰可读transition: fade进入本页时淡入clicks: 3本页有三次点击步进zoom: 0.9内容缩放 90%为较多内容留出呼吸空间hideInToc: false明确表示允许出现在目录中默认可省略。补充逐页配置与全局配置的合并规则Per-slide Frontmatter 并不是孤立生效的它位于一条合并链上Headmatter 全局项 → Headmatter 中的defaults→ 各页自身的 frontmatter若某页通过src导入文件还会先与导入者的 frontmatter 合并src键被剔除。从 packages/parser/src/fs.ts 可以看到最终进入渲染的每页 frontmatter 是{ ...slide.frontmatter, ...frontmatterOverride }展开后的结果。理解了这条链你就知道哪些选项该放全局、哪些该放单页、哪些能被覆盖——这也是将一套演示规模化组织多文件、多复用的关键前提。相关推荐阅读语法指南分隔符与 headmatter 概念、内置布局列表、Frontmatter 合并、导入外部幻灯片、拖拽元素。【免费下载链接】slidevPresentation Slides for Developers项目地址: https://gitcode.com/GitHub_Trending/sl/slidev创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Slidev 逐页 Frontmatter 完整指南：为每一张幻灯片做精细化配置
Slidev 逐页 Frontmatter 完整指南为每一张幻灯片做精细化配置【免费下载链接】slidevPresentation Slides for Developers项目地址: https://gitcode.com/GitHub_Trending/sl/slidev在 Slidev 中演示文稿由 Markdown 编写幻灯片之间用---分隔而每张幻灯片正文顶部都可以用一段 YAML Frontmatter 为该页单独配置布局、背景、点击次数、过渡动画、缩放比例等属性。本文将以skills/slidev/references/core-frontmatter.md为骨架结合仓库中的类型定义与解析源码系统讲解逐页 Frontmatter 的每一个配置项并给出可直接复制运行的完整示例帮助你精确控制每一张幻灯片的渲染效果。阅读本文后你将掌握布局、背景、点击步进、过渡、导入、路由别名等全部单页配置手段并能理解它们在内核中的解析与生效机制。Frontmatter 与 Headmatter单页配置与全局配置的分工在 Slidev 中frontmatter 分为两层可参考 语法指南Headmatter位于slides.md最顶部的第一个 frontmatter 块用于配置整个幻灯片主题、字体、宽高比等作用域是全局。Per-Slide Frontmatter本文主题位于每个---分隔的幻灯片段落顶部、正文之前用于配置这一页的布局与行为。两者的类型分别由 frontmatter.ts 中的Headmatter与Frontmatter接口定义。其中Headmatter通过OmitFrontmatter, ...继承了逐页字段并额外提供defaults?: Frontmatter字段——你可以在 headmatter 中写defaults:来给所有页面预设默认的单页配置再在个别页面覆盖它。从解析层看packages/parser/src/core.ts 用正则RE_FRONTMATTER /^---.*\r?\n([\s\S]*?)---/提取每一页的 frontmatter 原始内容并交给yaml解析。而 packages/client/constants.ts 中的FRONTMATTER_FIELDS数组则列出了被前端运行时真正消费的单页字段clicks、clicksStart、disabled、hide、hideInToc、layout、level、preload、routeAlias、src、title、transition、zoom、dragPos、lang、clickAnimation。Layout选择这一页的排版骨架最简单的逐页配置就是指定布局--- layout: center ---Layout 本质上是包裹幻灯片内容的 Vue 组件见 布局指南Slidev 内置了以下布局类型定义见 builtin-layouts.ts组件源码在 packages/client/layoutsdefault、cover、center、two-cols、two-cols-header、image、image-left、image-right、iframe、iframe-left、iframe-right、quote、section、statement、fact、full、intro、end、none几点使用要点默认布局并非一成不变第一张幻灯片默认使用cover其余默认使用default源码注释见 frontmatter.ts。这也是为什么封面通常无需显式写layout: cover。布局的加载顺序为内置布局 → 主题提供的布局 → addon 提供的布局 → 项目layouts目录下的自定义布局后加载者覆盖先加载者。layout: none表示不使用任何布局框架内容将完全自由排版。Background 与 class铺背景、加样式类--- background: /image.jpg backgroundSize: cover class: text-white ---background为当前页设置背景图一般给资源路径或 URLSlidev 会将其渲染为页面背景解析器在 core.ts 的extractImagesUsage中会从image、backgroundImage、background等键收集图片以便预加载与打包。需要纯色等 CSS 背景时也可使用任意 CSS background 值。backgroundSize控制背景尺寸常见值为cover或contain。class附加到当前幻灯片根元素上的自定义 class类型上支持字符串、数组或对象class?: string | string[] | Recordstring, unknown可配合 UnoCSS 原子类使用例如示例中的text-white让文字在深色背景上可读。clicks 与 clicksStart精确控制点击步进--- clicks: 5 # 本页需要的总点击次数 clicksStart: 0 # 起始点击数 ---点击步进是演示的常用节奏控制手段。clicks手动指定该幻灯片总共需要多少次点击才能走完当不指定时Slidev 会根据页面中v-click/v-clicks指令的使用自动计算frontmatter.ts 注释说明这一点。clicksStart则指定起始点击序号默认值为 0。若动画较多手动设定clicks还能避免 Slidev 自动推算与实际步进不一致。关于点击指令的更多用法可参考 动画指南点击状态的整体上限为CLICKS_MAX 999999见 constants.ts。Transition给页面切换加过渡--- transition: fade ---内置过渡动画包括fade、fade-out、slide-left、slide-right、slide-up、slide-down、view-transition联合类型见 frontmatter.ts也支持任意自定义 CSS 过渡名甚至传入对象形式的 VueTransitionGroup属性如duration、enterFromClass等。参考文档给出了前进 / 后退使用不同动画的写法--- transition: slide-left | slide-right ---其原理在 transition.ts 中可以看到resolveTransition会保留|拼接的名字按前进 / 后退方向分别取用direction 0取前一页/当前页 meta 上的过渡否则取反向。同时 headmatter 层也可以设置全局transition单页 frontmatter 会在路由 meta 上覆盖它。view-transition是浏览器原生 View Transition 的桥接过渡可作为现代演示的加分项。Zoom单页缩放内容--- zoom: 0.8 # 将内容缩放到 80% ---zoom控制当前页内容的缩放比例默认值是 1。它与全局的canvasWidth默认 980px配合Slidev 先把内容绘制在固定画布上再等比缩放到屏幕因此zoom: 0.8相当于在画布层面把内容缩小到 80%。适合在内容较多、需要整体缩小防止溢出时使用大于 1 的值则可以放大局部细节。Hide / Disabled让某页存在但不可见--- disabled: true # 隐藏该幻灯片 # 或者 hide: true ---disabled与hide语义相同源码注释明确写 Same ashide, completely hide and disable the slide见 frontmatter.ts。被标记的页面在解析阶段就直接被跳过不会出现在播放、概述和演示者视图中从 packages/parser/src/fs.ts 的加载流程可以看到loadSlide第一步就是检查slide.frontmatter.disabled || slide.frontmatter.hide并直接return。所以它适合保留备用内容但不演示的页面也常用于src导入多份文件时剔除不需要的页。Table of Contents对目录组件的控制--- hideInToc: true # 从 Toc 组件中隐藏 level: 2 # 覆盖标题级别 title: Custom Title # 覆盖幻灯片标题 ---hideInToc让当前页不出现在Toc目录组件中适合隐藏过渡页、致谢页等不想进目录的页面。title/level分别覆盖TitleRenderer与Toc组件使用的标题文本与标题级别类型注释要求需同时配合title生效见 frontmatter.ts。当页面的 H1 标题不够精准、或想在目录里显示更简洁的名字时非常有用。关于Toc组件用法参见 内置组件文档。src把别的 Markdown 文件导入进来--- src: ./slides/intro.md # 导入一个 markdown 文件 ---src让你能把长演示拆分成多个 Markdown 文件与 导入幻灯片 对应文件的复用性随之提升。需要注意声明了src的页面其自身正文内容会被忽略实际渲染内容完全来自被导入文件。还可以只导入目标文件的若干页--- src: ./other.md#2,5-7 # 只导入第 2、5、6、7 页 ---#后面的范围字符串会被parseRangeString解析允许2,5-7这类混合区间。解析层的具体行为在 packages/parser/src/fs.ts 中非常清晰以/开头的路径相对项目根目录解析相对路径则相对当前幻灯片所在文件的目录解析支持同一文件多处导入但同一页会展开多次对循环导入自身导入自身、或 A→B→A会记录Circular import detected错误并终止被导入页会继承导入者的 frontmattersrc字段本身被剔除这就是 frontmatter 合并 机制的基础。Route Alias给页面一个人类可读的 URL--- routeAlias: intro # 访问 /intro 而不是 /1 ---默认情况下幻灯片路由就是数字序号/1、/2…。routeAlias可以为该页创建一个稳定的别名之后既可以在 URL 中直接访问/intro也可以配合Link组件做跨页跳转避免硬编码序号——这在演示内容增删后依然稳定。Preload延迟挂载到真正进入时--- preload: false # 进入前不挂载 ---preload默认值为true即当上一张幻灯片处于激活状态时就开始预载下一张以换取更快的切换体验。当幻灯片包含重型资源大图、Monaco、WebGL 等不希望提前加载时可以置为false让页面到真正进入时才挂载。前端类型注释明确说明其作用是 Preload the slide when the previous slide is activefrontmatter.ts。dragPos为可拖拽元素指定初始位置--- dragPos: logo: 100,50,200,100,0 # 左, 上, 宽, 高, 旋转 arrow: 300,200,50,50,45 ---dragPos用于记录可拖拽元素借助VDrag/VDragArrow的位置。每项格式为left,top,width,height,rotate五个值组成的字符串键名对应元素的 id。类型注释特别提醒Normally you dont need to set this manually——演示时你在页面上拖动元素后Slidev 通常会自动把位置写回 frontmatter需开启对应持久化机制手动书写适合为拖拽元素预设一个初始坐标。完整使用说明参见 拖拽元素文档。Image / Iframe 布局配图页与嵌入页图片布局配套使用image等字段--- layout: image-left image: /photo.jpg backgroundSize: contain class: my-custom-class ---image、image-left、image-right布局会按image字段渲染配图backgroundSize: contain保证整图可见而不会被裁剪。iframe 系列布局则需要提供url--- layout: iframe url: https://example.com ---iframe/iframe-left/iframe-right会以 iframe 内嵌外部页面示例 URL 仅作格式演示请替换为你自己的页面。解析器同样会把这类字段中的图片 URL 收集起来用于预加载core.ts。Two Columns左右两栏布局--- layout: two-cols --- # Left Side Content ::right:: # Right Side Contenttwo-cols布局中用::right::分隔符把内容切成左右两栏::right::之前是左栏、之后是右栏。two-cols-header则额外支持一个顶部通栏标题--- layout: two-cols-header --- # Header ::left:: Left content ::right:: Right contenttwo-cols-header中::left::之后是左栏、::right::之后是右栏。这类槽位语法本质上是布局的具名插槽简写更底层的机制见 slot-sugar 文档如果你需要自定义栏位划分也可以自己编写布局编写布局指南。Full Example一张实战模板页把上面所有字段串起来一个信息完整、可直接复制修改的页面如下--- layout: center background: /bg.jpg class: text-white text-center transition: fade clicks: 3 zoom: 0.9 hideInToc: false --- # Slide Content解读layout: center内容居中background: /bg.jpgclass: text-white让深色背景上的文字清晰可读transition: fade进入本页时淡入clicks: 3本页有三次点击步进zoom: 0.9内容缩放 90%为较多内容留出呼吸空间hideInToc: false明确表示允许出现在目录中默认可省略。补充逐页配置与全局配置的合并规则Per-slide Frontmatter 并不是孤立生效的它位于一条合并链上Headmatter 全局项 → Headmatter 中的defaults→ 各页自身的 frontmatter若某页通过src导入文件还会先与导入者的 frontmatter 合并src键被剔除。从 packages/parser/src/fs.ts 可以看到最终进入渲染的每页 frontmatter 是{ ...slide.frontmatter, ...frontmatterOverride }展开后的结果。理解了这条链你就知道哪些选项该放全局、哪些该放单页、哪些能被覆盖——这也是将一套演示规模化组织多文件、多复用的关键前提。相关推荐阅读语法指南分隔符与 headmatter 概念、内置布局列表、Frontmatter 合并、导入外部幻灯片、拖拽元素。【免费下载链接】slidevPresentation Slides for Developers项目地址: https://gitcode.com/GitHub_Trending/sl/slidev创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
