企业官网建设流程全解析

Slidev 如何用 setup/routes.ts 给演示文稿添加自定义 Vue 页面

【免费下载链接】slidevPresentation Slides for Developers项目地址: https://gitcode.com/GitHub_Trending/sl/slidev

Slidev 的幻灯片页面来自 Markdown 文件，但有时你需要一个独立于幻灯片的 Vue 页面——比如一个落地页、帮助页或自定义表单页。通过项目的setup/routes.ts文件，你可以向 Slidev 应用的路由表中追加自定义路由，让任意 Vue 组件挂载到指定 URL 上。适用前提：你已有一个 Slidev 项目（内容入口为slides.md），环境满足 官方文档 要求的 Node.js >= 20.12.0。完成本文后，访问新路径即可在浏览器中看到你的 Vue 页面。

机制说明：setup/ 目录约定如何生效

Slidev 对 目录结构 有约定：项目根目录下的setup/用于存放自定义 setup / hooks，该目录及其中的所有文件都是可选的。

路由扩展的加载流程在源码中可以直接看到：

• 虚拟模块模板按setup/routes.{ts,js,mts,mjs}的 glob 从项目根目录查找文件（见 setups.ts，setupModules列表包含'routes'）。文件存在才会被注入，filter(Boolean)会过滤掉不存在的匹配项。
• 客户端在构建路由时，先注册内置路由，再用setups.reduce((routes, setup) => setup(routes), routes)依次把内置路由数组传给每个 setup 函数（见 routes.ts）。也就是说，你的setup/routes.ts接收到的routes参数就是完整的内置路由数组。

内置路由中包含演示页/:no（按页码播放幻灯片）、/presenter/:no、/overview、/print、/export/:no?等路径，以及一个通配 404 路由/:pathMatch(.*)*（见 routes.ts）。

defineRoutesSetup的类型定义是RoutesSetup = (routes: RouteRecordRaw[]) => RouteRecordRaw[]（见 setups.ts），即：函数接收当前路由数组，返回新的路由数组。路由记录的写法遵循 Vue Router 的RouteRecordRaw格式。

操作步骤

1. 创建 Vue 页面组件

在 目录结构 约定之外，pages/目录由你自己创建，位置在项目根目录。文档示例中的导入路径../pages/my-page.vue（相对setup/目录）指向的就是根目录下的pages/my-page.vue：

<!-- pages/my-page.vue --> <template> <h1>My Page</h1> </template>

以上是最小示例内容，可替换为任何 Vue 单文件组件的写法。

2. 创建 setup/routes.ts

按 Configure Routes 文档 的用法，在项目根目录的setup/下创建routes.ts：

import { defineRoutesSetup } from '@slidev/types' export default defineRoutesSetup((routes) => { return [ ...routes, { path: '/my-page', component: () => import('../pages/my-page.vue'), }, ] })

要点：

• ...routes展开保留全部内置路由，这是文档给出的写法，删掉它会破坏幻灯片等既有页面；
• path是你希望访问的 URL 路径，component使用动态导入指向 Vue 组件文件；
• 需要更多路由项时，在数组中继续按 Vue Router 路由记录格式追加即可。

3. 启动开发服务器并访问新路径

在项目根目录启动开发服务器（package.json中通常已由脚手架配好dev脚本）：

npm run dev

然后使用终端输出的本地地址，访问/my-page路径。浏览器中显示my-page.vue的渲染结果，即表示自定义路由注册成功。

页面打不开时检查什么

如果访问/my-page落入 404 页面（对应内置的通配路由，渲染packages/client/pages/404.vue），说明自定义路由没有进入路由表，按以下顺序核对：

1. 文件名与位置是否为项目根目录setup/routes.ts——只匹配setup/routes.{ts,js,mts,mjs}这几种后缀（见 setups.ts），改名成setup/router.ts之类的写法不会被加载；
2. 文件是否以export default导出一个返回路由数组的函数，参数routes是否原样展开进了返回值；
3. component的动态导入路径相对于setup/目录是否正确，pages/my-page.vue文件是否真实存在。

限制与边界

• 自定义页面与幻灯片体系相互独立：它不进slides.md的页码序列，也不受 Markdown 幻灯片的 frontmatter 控制，就是一个挂在 Vue Router 上的普通 Vue 组件；
• 路由冲突由 Vue Router 的路由规则决定，文档建议参考 Vue Router 官方文档（config-routes.md 末尾给出了指引）。示例使用/my-page这样的静态路径，与内置的动态路径/:no、404 通配路径区分开，避免歧义；
• setup/routes.ts是可选文件，不创建时一切按内置路由运行，对现有幻灯片项目无影响。

【免费下载链接】slidevPresentation Slides for Developers项目地址: https://gitcode.com/GitHub_Trending/sl/slidev