Pandoc Reveal.js Scroll View 元数据配置完全指南view、scrollSnap、scrollActivationWidth 与 scrollProgress 实战解析【免费下载链接】pandocUniversal markup converter项目地址: https://gitcode.com/gh_mirrors/pa/pandoc导读本文围绕 pandoc 官方命令行测试用例 test/command/11486.md系统讲解如何通过 YAML 元数据metadata控制 Reveal.js 输出的Scroll View滚动视图模式。你将掌握view: scroll、scrollSnap、scrollActivationWidth、scrollProgress四个核心变量的取值、默认行为与组合效果并理解 pandoc 模板变量与 Reveal.js 配置项的映射关系从而在把 Markdown 转换为 HTML5 幻灯片时精确定制长页滚动 吸附 进度条的演示形态。一、测试用例背景pandoc 的命令行黄金测试Command Tests该文档属于 pandoc 仓库中test/command/目录下的命令行测试command tests。这类测试的格式约定是以%开头书写要执行的 pandoc 命令随后是可选的输入文件内容以^D结束最后一行是期望的输出片段。测试驱动框架test-pandoc.hs会实际运行命令并比对输出。11486.md的核心命令形如% pandoc -t revealjs --templatecommand/11486/scroll.revealjs --- view: scroll ... --- ^D即将 stdin 中的 YAML 元数据块作为 Markdown 输入使用-t revealjs输出 Reveal.js HTML并覆盖默认模板为自定义模板 test/command/11486/scroll.revealjs以便只观察与滚动视图相关的几行 JS 配置输出排除默认模板中其他无关内容的影响。二、Scroll View 的开启入口view: scrollReveal.js 的 Scroll View 把传统的逐页切换改为连续长页滚动。在 pandoc 中这一模式的开关由元数据变量view控制--- view: scroll ---当view变量存在时pandoc 的 revealjs 输出才会包含滚动视图配置段。这一条件判断同时出现在两个层面默认模板data/templates/default.revealjs 中整段滚动配置被$if(view)$包裹$if(view)$ // Enable scroll view view: $view/nowrap$, // see https://revealjs.com/scroll-view/#scrollbar $if(scrollProgressAuto)$ scrollProgress: auto, $elseif(scrollProgress)$ scrollProgress: $scrollProgress$, $else$ scrollProgress: false, $endif$ // see https://revealjs.com/scroll-view/#url-activation scrollActivationWidth: $scrollActivationWidth$, // see https://revealjs.com/scroll-view/#scroll-snapping $if(scrollSnap)$ scrollSnap: $scrollSnap/nowrap$, $else$ scrollSnap: false, $endif$ // Experimental. see https://revealjs.com/scroll-view/#scroll-snapping scrollLayout: $scrollLayout/nowrap$, $endif$Haskell 写入器src/Text/Pandoc/Writers/HTML.hs 会在元数据含view时为滚动视图相关变量填充默认值详见下文第五节。因此view: scroll是整个滚动视图配置的总开关——不写它其余三个变量都不会生效。三、URL 激活阈值scrollActivationWidthscrollActivationWidth决定当视口宽度小于该像素值时自动激活滚动视图。测试用例中提供了两种取值元数据取值输出结果含义不设置默认scrollActivationWidth: 0,任何宽度下都不自动激活0 表示永不按宽度触发scrollActivationWidth: 500scrollActivationWidth: 500,视口宽度 500px典型手机横屏时自动切换到滚动视图完整测试命令% pandoc -t revealjs --templatecommand/11486/scroll.revealjs --- view: scroll scrollActivationWidth: 500 --- ^D scrollActivationWidth: 500, scrollSnap: mandatory, scrollProgress: auto,注意一个细节该值是数值型输出不带引号而scrollSnap、scrollProgress: auto是字符串型带引号。这与模板中变量占位符的写法一致——scrollActivationWidth: $scrollActivationWidth$直接内插而字符串类变量在模板中显式加了引号。从源码结构看pandoc 将默认值以 Doc Text 形式注入defField scrollActivationWidth (0 :: Doc Text)用户提供的数值会原样进入输出。四、滚动吸附scrollSnapscrollSnap控制滚动视图的吸附snap行为即滚动停止时是否自动对齐到每个 section 分节的边界。测试覆盖了三种状态4.1 默认值未设置mandatory% pandoc -t revealjs --templatecommand/11486/scroll.revealjs --- view: scroll --- ^D scrollActivationWidth: 0, scrollSnap: mandatory, scrollProgress: auto,mandatory强制吸附意味着滚动一定会停靠在分节边界上不会停留在两个分节之间的中间位置。这是 pandoc 的默认行为对应源码中的默认值注入defField scrollSnap (mandatory :: Doc Text)。4.2 显式关闭scrollSnap: false% pandoc -t revealjs --templatecommand/11486/scroll.revealjs --- view: scroll scrollSnap: false --- ^D scrollActivationWidth: 0, scrollSnap: false, scrollProgress: auto,布尔值false关闭吸附此时页面可自由停留在任意滚动位置。注意模板分支逻辑$if(scrollSnap)$判断变量是否存在——当值为false时变量依然存在但被判为空走$else$分支输出scrollSnap: false。因此用户显式写false与不写该变量输出恰好一致都是false这是因为 pandoc 注入默认mandatory的逻辑发生在写入器端模板侧仅按存在性渲染。4.3 接近时吸附scrollSnap: proximity% pandoc -t revealjs --templatecommand/11486/scroll.revealjs --- view: scroll scrollSnap: proximity --- ^D scrollActivationWidth: 0, scrollSnap: proximity, scrollProgress: auto,proximity是 CSSscroll-snap-type中的宽松模式只有当用户滚动到距分节边界较近时才会被吸附允许在中途自由滚动。注意模板中使用$scrollSnap/nowrap$输出即不会转义或包裹字符串最终以单引号字符串形式出现在 JS 配置中。五、滚动进度条scrollProgressscrollProgress控制滚动视图底部的进度条显示。它的取值处理是四个变量中最复杂的因为 pandoc 引入了布尔 字符串的混合语义测试用例完整覆盖了全部三种形态5.1 不设置 → 默认auto% pandoc -t revealjs --templatecommand/11486/scroll.revealjs --- view: scroll --- ^D scrollActivationWidth: 0, scrollSnap: mandatory, scrollProgress: auto,未显式设置时输出字符串auto。Reveal.js 的auto模式会按内容高度自动决定是否显示进度条内容超出视口时显示。5.2 布尔值 true / false% pandoc -t revealjs --templatecommand/11486/scroll.revealjs --- view: scroll scrollProgress: true --- ^D scrollActivationWidth: 0, scrollSnap: mandatory, scrollProgress: true,% pandoc -t revealjs --templatecommand/11486/scroll.revealjs --- view: scroll scrollProgress: false --- ^D scrollActivationWidth: 0, scrollSnap: mandatory, scrollProgress: false,布尔true强制总是显示进度条布尔false强制关闭。这是写入器端特殊处理的结果见 src/Text/Pandoc/Writers/HTML.hs(case (lookupContext scrollProgress metadata :: Maybe (Val Text)) of Just (BoolVal False) - id Just (BoolVal True) - defField scrollProgress True _ - defField scrollProgressAuto True) .解读这段逻辑pandoc 先从元数据中读取scrollProgress若用户显式写true就注入scrollProgress: true供模板的$scrollProgress$分支使用若显式写false则什么都不注入此时模板的$if(scrollProgress)$为假落到$else$输出false殊途同归若用户未设置或给了其他非布尔值则注入scrollProgressAuto: true走模板的$if(scrollProgressAuto)$分支输出字符串auto。5.3 显式字符串auto% pandoc -t revealjs --templatecommand/11486/scroll.revealjs --- view: scroll scrollProgress: auto --- ^D scrollActivationWidth: 0, scrollSnap: mandatory, scrollProgress: auto,YAML 中不带引号的auto会被解析为字符串非布尔值因此落入lookupContext的_分支同样输出auto。字符串auto与完全不设置的结果一致——这正是auto作为默认语义的体现。六、默认值速查表与源码依据综合以上测试与写入器源码当view: scroll存在但其余变量未设置时pandoc 注入的默认值如下模板变量默认值注入位置view用户提供的值如scroll元数据直通scrollActivationWidth0src/Text/Pandoc/Writers/HTML.hsdefField scrollActivationWidth (0 :: Doc Text)scrollSnapmandatorysrc/Text/Pandoc/Writers/HTML.hsdefField scrollSnap (mandatory :: Doc Text)scrollProgressauto经scrollProgressAuto间接实现src/Text/Pandoc/Writers/HTML.hsscrollLayoutfullsrc/Text/Pandoc/Writers/HTML.hsdefField scrollLayout (full :: Doc Text)另外默认模板中还会输出scrollLayout: full模板第 262 行它控制滚动视图的版式full为整页宽幅布局pandoc 当前未暴露独立的元数据开关固定使用full属于 Reveal.js 标记为 Experimental 的配置项。七、在真实项目中启用 Scroll View综合上述规则在实际项目里启用并定制滚动视图的最小 YAML 前置元数据如下--- title: 我的长页演示 view: scroll # 开启 Scroll View scrollSnap: proximity # 宽松吸附允许自由滚动可选false / mandatory scrollActivationWidth: 0 # 0 表示不按宽度自动触发可选任意像素值 scrollProgress: auto # 自动进度条可选true / false / auto ---生成命令pandoc slides.md -t revealjs -s -o slides.html几点实操提示必须配合-sstandalone只有独立 HTML 才渲染完整模板view等配置才生效变量优先级模板输出严格遵循用户显式值优先未设置用默认值的注入模型四个变量彼此独立可以任意组合验证方式参照 test/command/11486.md 的做法用--template覆盖为精简模板并直接查看生成的 JS 配置行是排查模板变量是否生效的最快手段布尔陷阱scrollSnap与scrollProgress对false的处理路径不同——前者靠模板$if$存在性判断后者靠写入器对BoolVal False的特殊分支但最终输出行为一致。八、如何运行该测试用例该用例随 pandoc 测试套件运行。仓库根目录的 Makefile 中make test会调用 cabal 执行 test/test-pandoc.hs其中包含test/command/下全部命令测试。单独验证本用例时可手动执行文档中%后的命令并将输入管道传入比对输出与期望片段是否一致printf %s\n --- view: scroll scrollSnap: proximity --- \ | pandoc -t revealjs --templatetest/command/11486/scroll.revealjs预期输出包含scrollActivationWidth: 0, scrollSnap: proximity, scrollProgress: auto,小结通过view: scroll这一元数据入口pandoc 将 Reveal.js 的 Scroll View 能力完整开放给 Markdown 作者scrollActivationWidth控制响应式激活阈值scrollSnap控制滚动吸附强度scrollProgress控制进度条形态。理解这三个变量与模板$if$分支、写入器默认值注入之间的配合关系即可在不触碰模板源码的前提下输出符合预期交互形态的滚动式 HTML5 演示文稿。【免费下载链接】pandocUniversal markup converter项目地址: https://gitcode.com/gh_mirrors/pa/pandoc创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Pandoc Reveal.js Scroll View 元数据配置完全指南：view、scrollSnap、scrollActivationWidth 与 scrollProgress 实战解析
Pandoc Reveal.js Scroll View 元数据配置完全指南view、scrollSnap、scrollActivationWidth 与 scrollProgress 实战解析【免费下载链接】pandocUniversal markup converter项目地址: https://gitcode.com/gh_mirrors/pa/pandoc导读本文围绕 pandoc 官方命令行测试用例 test/command/11486.md系统讲解如何通过 YAML 元数据metadata控制 Reveal.js 输出的Scroll View滚动视图模式。你将掌握view: scroll、scrollSnap、scrollActivationWidth、scrollProgress四个核心变量的取值、默认行为与组合效果并理解 pandoc 模板变量与 Reveal.js 配置项的映射关系从而在把 Markdown 转换为 HTML5 幻灯片时精确定制长页滚动 吸附 进度条的演示形态。一、测试用例背景pandoc 的命令行黄金测试Command Tests该文档属于 pandoc 仓库中test/command/目录下的命令行测试command tests。这类测试的格式约定是以%开头书写要执行的 pandoc 命令随后是可选的输入文件内容以^D结束最后一行是期望的输出片段。测试驱动框架test-pandoc.hs会实际运行命令并比对输出。11486.md的核心命令形如% pandoc -t revealjs --templatecommand/11486/scroll.revealjs --- view: scroll ... --- ^D即将 stdin 中的 YAML 元数据块作为 Markdown 输入使用-t revealjs输出 Reveal.js HTML并覆盖默认模板为自定义模板 test/command/11486/scroll.revealjs以便只观察与滚动视图相关的几行 JS 配置输出排除默认模板中其他无关内容的影响。二、Scroll View 的开启入口view: scrollReveal.js 的 Scroll View 把传统的逐页切换改为连续长页滚动。在 pandoc 中这一模式的开关由元数据变量view控制--- view: scroll ---当view变量存在时pandoc 的 revealjs 输出才会包含滚动视图配置段。这一条件判断同时出现在两个层面默认模板data/templates/default.revealjs 中整段滚动配置被$if(view)$包裹$if(view)$ // Enable scroll view view: $view/nowrap$, // see https://revealjs.com/scroll-view/#scrollbar $if(scrollProgressAuto)$ scrollProgress: auto, $elseif(scrollProgress)$ scrollProgress: $scrollProgress$, $else$ scrollProgress: false, $endif$ // see https://revealjs.com/scroll-view/#url-activation scrollActivationWidth: $scrollActivationWidth$, // see https://revealjs.com/scroll-view/#scroll-snapping $if(scrollSnap)$ scrollSnap: $scrollSnap/nowrap$, $else$ scrollSnap: false, $endif$ // Experimental. see https://revealjs.com/scroll-view/#scroll-snapping scrollLayout: $scrollLayout/nowrap$, $endif$Haskell 写入器src/Text/Pandoc/Writers/HTML.hs 会在元数据含view时为滚动视图相关变量填充默认值详见下文第五节。因此view: scroll是整个滚动视图配置的总开关——不写它其余三个变量都不会生效。三、URL 激活阈值scrollActivationWidthscrollActivationWidth决定当视口宽度小于该像素值时自动激活滚动视图。测试用例中提供了两种取值元数据取值输出结果含义不设置默认scrollActivationWidth: 0,任何宽度下都不自动激活0 表示永不按宽度触发scrollActivationWidth: 500scrollActivationWidth: 500,视口宽度 500px典型手机横屏时自动切换到滚动视图完整测试命令% pandoc -t revealjs --templatecommand/11486/scroll.revealjs --- view: scroll scrollActivationWidth: 500 --- ^D scrollActivationWidth: 500, scrollSnap: mandatory, scrollProgress: auto,注意一个细节该值是数值型输出不带引号而scrollSnap、scrollProgress: auto是字符串型带引号。这与模板中变量占位符的写法一致——scrollActivationWidth: $scrollActivationWidth$直接内插而字符串类变量在模板中显式加了引号。从源码结构看pandoc 将默认值以 Doc Text 形式注入defField scrollActivationWidth (0 :: Doc Text)用户提供的数值会原样进入输出。四、滚动吸附scrollSnapscrollSnap控制滚动视图的吸附snap行为即滚动停止时是否自动对齐到每个 section 分节的边界。测试覆盖了三种状态4.1 默认值未设置mandatory% pandoc -t revealjs --templatecommand/11486/scroll.revealjs --- view: scroll --- ^D scrollActivationWidth: 0, scrollSnap: mandatory, scrollProgress: auto,mandatory强制吸附意味着滚动一定会停靠在分节边界上不会停留在两个分节之间的中间位置。这是 pandoc 的默认行为对应源码中的默认值注入defField scrollSnap (mandatory :: Doc Text)。4.2 显式关闭scrollSnap: false% pandoc -t revealjs --templatecommand/11486/scroll.revealjs --- view: scroll scrollSnap: false --- ^D scrollActivationWidth: 0, scrollSnap: false, scrollProgress: auto,布尔值false关闭吸附此时页面可自由停留在任意滚动位置。注意模板分支逻辑$if(scrollSnap)$判断变量是否存在——当值为false时变量依然存在但被判为空走$else$分支输出scrollSnap: false。因此用户显式写false与不写该变量输出恰好一致都是false这是因为 pandoc 注入默认mandatory的逻辑发生在写入器端模板侧仅按存在性渲染。4.3 接近时吸附scrollSnap: proximity% pandoc -t revealjs --templatecommand/11486/scroll.revealjs --- view: scroll scrollSnap: proximity --- ^D scrollActivationWidth: 0, scrollSnap: proximity, scrollProgress: auto,proximity是 CSSscroll-snap-type中的宽松模式只有当用户滚动到距分节边界较近时才会被吸附允许在中途自由滚动。注意模板中使用$scrollSnap/nowrap$输出即不会转义或包裹字符串最终以单引号字符串形式出现在 JS 配置中。五、滚动进度条scrollProgressscrollProgress控制滚动视图底部的进度条显示。它的取值处理是四个变量中最复杂的因为 pandoc 引入了布尔 字符串的混合语义测试用例完整覆盖了全部三种形态5.1 不设置 → 默认auto% pandoc -t revealjs --templatecommand/11486/scroll.revealjs --- view: scroll --- ^D scrollActivationWidth: 0, scrollSnap: mandatory, scrollProgress: auto,未显式设置时输出字符串auto。Reveal.js 的auto模式会按内容高度自动决定是否显示进度条内容超出视口时显示。5.2 布尔值 true / false% pandoc -t revealjs --templatecommand/11486/scroll.revealjs --- view: scroll scrollProgress: true --- ^D scrollActivationWidth: 0, scrollSnap: mandatory, scrollProgress: true,% pandoc -t revealjs --templatecommand/11486/scroll.revealjs --- view: scroll scrollProgress: false --- ^D scrollActivationWidth: 0, scrollSnap: mandatory, scrollProgress: false,布尔true强制总是显示进度条布尔false强制关闭。这是写入器端特殊处理的结果见 src/Text/Pandoc/Writers/HTML.hs(case (lookupContext scrollProgress metadata :: Maybe (Val Text)) of Just (BoolVal False) - id Just (BoolVal True) - defField scrollProgress True _ - defField scrollProgressAuto True) .解读这段逻辑pandoc 先从元数据中读取scrollProgress若用户显式写true就注入scrollProgress: true供模板的$scrollProgress$分支使用若显式写false则什么都不注入此时模板的$if(scrollProgress)$为假落到$else$输出false殊途同归若用户未设置或给了其他非布尔值则注入scrollProgressAuto: true走模板的$if(scrollProgressAuto)$分支输出字符串auto。5.3 显式字符串auto% pandoc -t revealjs --templatecommand/11486/scroll.revealjs --- view: scroll scrollProgress: auto --- ^D scrollActivationWidth: 0, scrollSnap: mandatory, scrollProgress: auto,YAML 中不带引号的auto会被解析为字符串非布尔值因此落入lookupContext的_分支同样输出auto。字符串auto与完全不设置的结果一致——这正是auto作为默认语义的体现。六、默认值速查表与源码依据综合以上测试与写入器源码当view: scroll存在但其余变量未设置时pandoc 注入的默认值如下模板变量默认值注入位置view用户提供的值如scroll元数据直通scrollActivationWidth0src/Text/Pandoc/Writers/HTML.hsdefField scrollActivationWidth (0 :: Doc Text)scrollSnapmandatorysrc/Text/Pandoc/Writers/HTML.hsdefField scrollSnap (mandatory :: Doc Text)scrollProgressauto经scrollProgressAuto间接实现src/Text/Pandoc/Writers/HTML.hsscrollLayoutfullsrc/Text/Pandoc/Writers/HTML.hsdefField scrollLayout (full :: Doc Text)另外默认模板中还会输出scrollLayout: full模板第 262 行它控制滚动视图的版式full为整页宽幅布局pandoc 当前未暴露独立的元数据开关固定使用full属于 Reveal.js 标记为 Experimental 的配置项。七、在真实项目中启用 Scroll View综合上述规则在实际项目里启用并定制滚动视图的最小 YAML 前置元数据如下--- title: 我的长页演示 view: scroll # 开启 Scroll View scrollSnap: proximity # 宽松吸附允许自由滚动可选false / mandatory scrollActivationWidth: 0 # 0 表示不按宽度自动触发可选任意像素值 scrollProgress: auto # 自动进度条可选true / false / auto ---生成命令pandoc slides.md -t revealjs -s -o slides.html几点实操提示必须配合-sstandalone只有独立 HTML 才渲染完整模板view等配置才生效变量优先级模板输出严格遵循用户显式值优先未设置用默认值的注入模型四个变量彼此独立可以任意组合验证方式参照 test/command/11486.md 的做法用--template覆盖为精简模板并直接查看生成的 JS 配置行是排查模板变量是否生效的最快手段布尔陷阱scrollSnap与scrollProgress对false的处理路径不同——前者靠模板$if$存在性判断后者靠写入器对BoolVal False的特殊分支但最终输出行为一致。八、如何运行该测试用例该用例随 pandoc 测试套件运行。仓库根目录的 Makefile 中make test会调用 cabal 执行 test/test-pandoc.hs其中包含test/command/下全部命令测试。单独验证本用例时可手动执行文档中%后的命令并将输入管道传入比对输出与期望片段是否一致printf %s\n --- view: scroll scrollSnap: proximity --- \ | pandoc -t revealjs --templatetest/command/11486/scroll.revealjs预期输出包含scrollActivationWidth: 0, scrollSnap: proximity, scrollProgress: auto,小结通过view: scroll这一元数据入口pandoc 将 Reveal.js 的 Scroll View 能力完整开放给 Markdown 作者scrollActivationWidth控制响应式激活阈值scrollSnap控制滚动吸附强度scrollProgress控制进度条形态。理解这三个变量与模板$if$分支、写入器默认值注入之间的配合关系即可在不触碰模板源码的前提下输出符合预期交互形态的滚动式 HTML5 演示文稿。【免费下载链接】pandocUniversal markup converter项目地址: https://gitcode.com/gh_mirrors/pa/pandoc创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考