Spectacle Markdown 幻灯片布局（Markdown Slide Layouts）完全指南

Spectacle Markdown 幻灯片布局Markdown Slide Layouts完全指南【免费下载链接】spectacleA React-based library for creating sleek presentations using JSX syntax that gives you the ability to live demo your code.项目地址: https://gitcode.com/gh_mirrors/spectacle2/spectacle导读本文基于 Spectacle 官方文档 docs/md-slide-layouts.md 编写系统讲解如何在不引入任何 JSX 的前提下通过 Markdown 内嵌的 JSON 配置对象为每一页幻灯片声明columns多栏与center居中两种布局。读完本文你将掌握---分隔符与::section区块指令的完整语法、两种布局的底层 JSX 渲染结构以及它们与.mdx文件、React 布局原语之间的关系并能够直接在纯 Markdown 工程中落地使用。概述纯 Markdown 也能做复杂布局Spectacle 是构建 React 演示文稿的库它允许你使用 React 或 Markdown 编写幻灯片。在 Markdown 场景下Spectacle 原生支持若干布局容器layout containers专门用来解决仅靠 Markdown 语法难以实现复杂页面排版的问题——以往要实现分栏等效果必须把 JSX 元素导入到 MDX 中才能做到而布局容器让这一切在.md文件里即可完成。使用方式非常直观Spectacle 使用---三个连续短横线作为每个 Markdown 幻灯片的分隔符在分隔符后追加一段JSON 配置对象即可为对应幻灯片声明布局目前官方支持两种布局类型columns分栏和center居中。--- { layout : columns }:::info 适用范围 Markdown 布局注解功能仅对.md文件生效。在.mdx文件中此特性不可用因为 MDX 本身可以直接使用 JSX 布局原语如 layout-primitives.ts 中导出的FlexBox、Box、Grid等。 :::分栏布局Columns Layoutcolumns布局用于创建基于行row的多列布局。只需要在幻灯片分隔符后写入如下 JSON 对象{ layout : columns }每个列区块由::section指令directive声明。列的数量由::section注解的个数决定——写两个::section就是两列写三个就是三列。完整示例--- { layout : columns } ::section Gastly ::section Haunter --- # Ghost-type Pokémon The Ghost-type (ゴーストタイプ Gosuto taipu in Japanese) is one of the eighteen Pokémon elemental types.上述 Markdown 渲染后的效果是第一页左右并排展示两张图片Gastly 与 Haunter第二页展示关于幽灵系宝可梦的标题与正文。底层的 JSX 结构从源码 markdown-layout-containers.ts 可以看到Columns容器实际渲染为一段横向排列的 Flex 布局并且每个::section区块会被切分成数组元素后逐一放入FlexBox flexDirectionrow alignItemsstart flex{1} {sectionsArray} /FlexBox即flexDirectionrow让子元素沿水平方向排列形成多列alignItemsstart使各列顶部对齐flex{1}保证容器占满可用宽度。实现原理从分隔符到列数组整个流程由三层机制协作完成在 markdown.tsx 中有完整实现切分幻灯片MarkdownSlideSet调用工具函数separateSectionsFromJson见 separate-sections-from-json.ts按---行把整份 Markdown 切分成多个区块并解析每块分隔符后附带的 JSON 对象该函数的单元测试覆盖了带 JSON、不带 JSON、空字符串、无起始分隔符等多种边界情形见 separate-sections-from-json.test.ts。解析指令directiveParserPlugin与directivesHandlerPlugin见 remark-rehype-directive.ts把::section行转换为sectionDirective节点并收集两个指令之间的 AST 节点作为该区块的内容从而得到区块数组未知指令会被安全地从节点树中剔除避免破坏渲染。选择模板MarkdownSlide见 markdown-slide-renderer.tsx通过hasLayoutConfig判断当前幻灯片的 JSON 配置配置为columns时模板切换为Columns容器为center时切换为Center容器。// markdown-layout-containers.ts 中的判断逻辑 export const hasLayoutConfig (layoutKey: string) (config?: Recordstring, string) config layout in config config.layout layoutKey;值得注意的是当布局为columns时渲染器会直接把children.props.children即指令切分出的区块数组传给模板组件见 markdown.tsx这正是各列内容得以并排展示的关键。居中布局Center Layoutcenter布局用于创建内容居中的单列布局。配置对象同样非常简单{ layout : center }完整示例--- { layout : center } Gengar --- # Gengar Gengar is a dark purple, bipedal Pokémon with a roundish body. It has red eyes and a wide mouth that is usually curled into a sinister grin. Multiple spikes cover its back, and it has large pointed ears. Its arms and legs are short with three digits on both its hands and feet. It also has a stubby tail.底层的 JSX 结构Center容器的实现见 markdown-layout-containers.ts将所有幻灯片内容作为 children 直接传入并由 Flex 布局负责水平和垂直两个方向上的居中FlexBox justifyContentcenter alignItemscenter height100% {content} /FlexBoxjustifyContentcenter实现水平居中alignItemscenter实现垂直居中height100%确保容器撑满整页高度。在真实项目中启用 Markdown 布局仓库自带的 examples/md 示例工程完整演示了如何使用这些布局入口文件 examples/md/index.js 通过MarkdownSlideSet组件加载 Markdown 内容而幻灯片本体写在 examples/md/slides.md 中其中就包含columns与center两种布局的实战用法// examples/md/index.js 关键片段 import mdContent from ./slides.md; const Presentation () ( Deck theme{theme} template{template} MarkdownSlideSet{mdContent}/MarkdownSlideSet /Deck );配套的 examples/md/webpack.config.js 使用spectacle-mdx-loader将 Markdown 文件转译为可被 React 引用的模块。若使用官方脚手架npx create-spectacle选择Markdown模板即可一键生成包含上述结构的工程参见 docs/index.mdx 中的模板介绍生成逻辑见 packages/create-spectacle/src/templates/markdown.ts。常见问题与注意事项只能在.md中使用布局注解依赖MarkdownSlideSet 指令解析管线.mdx文件请改用 JSX 布局原语或 SlideLayout 系列组件。JSON 必须紧跟在---之后分隔符与 JSON 之间以空格分隔形如--- { layout : columns }separateSectionsFromJson正是通过以---开头这一特征行来识别配置见 separate-sections-from-json.ts。列数与::section一一对应想调整列数只需增删::section指令块无需改动任何 React 代码。JSON 键目前仅识别layouthasLayoutConfig只检查配置中是否存在layout字段并比对取值其他字段会被忽略因此请确保布局名拼写为columns或center。小结Spectacle 的 Markdown 布局容器在---分隔符与 JSON 配置之上用极小的语法成本columns/center::section实现了原本只有在 JSX 中才能完成的分栏与居中排版。无论是快速搭建两栏对比页还是制作内容聚焦的居中页你都不需要离开 Markdown 文件真正做到了以 Markdown 为主以 React 渲染能力为底。若需要更丰富的布局形态如代码分栏、图文并排、整页铺满图片等可进一步阅读 docs/react-slide-layouts.md 中的SlideLayout组件族或直接在 MDX 中组合 layout-primitives.ts 提供的布局原语实现完全自定义的排版。【免费下载链接】spectacleA React-based library for creating sleek presentations using JSX syntax that gives you the ability to live demo your code.项目地址: https://gitcode.com/gh_mirrors/spectacle2/spectacle创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考