slidev-navigation

Slidev 导航

本技能涵盖 Slidev 的所有导航功能，包括键盘快捷键、导航栏、概览模式以及自定义导航行为。

何时使用此技能

• 学习导航控件
• 自定义键盘快捷键
• 设置演示文稿导航
• 配置导航栏
• 创建自定义导航组件

默认键盘快捷键

基本导航

按键	操作
Space	播放下一个动画或切换到下一张幻灯片
→ / Right	播放下一个动画或切换到下一张幻灯片
← / Left	播放上一个动画或切换到上一张幻灯片
↑ / Up	切换到上一张幻灯片（跳过动画）
↓ / Down	切换到下一张幻灯片（跳过动画）

模式切换

按键	操作
o	切换概览模式
d	切换深色模式
f	切换全屏
p	切换演讲者模式

跳转导航

按键	操作
g	跳转到指定幻灯片
Home	跳转到第一张幻灯片
End	跳转到最后一张幻灯片

其他控件

按键	操作
Esc	退出全屏／概览／绘图模式
e	切换绘图模式
r	切换录制

导航栏

位置

幻灯片左下角（悬停时显示）。

可用按钮

• 首页：跳转到第一张幻灯片
• 上一张：播放上一个动画／切换到上一张幻灯片
• 当前页／总页数：点击打开跳转对话框
• 下一张：播放下一个动画／切换到下一张幻灯片
• 演讲者：打开演讲者模式
• 摄像头：切换摄像头视图
• 录制：开始／停止录制
• 绘图：切换绘图模式
• 概览：打开幻灯片概览
• 深色模式：切换深色／浅色模式
• 全屏：切换全屏
• 导出：导出选项
• 信息：演示文稿信息

概览模式

打开方式

• 按 o 键
• 点击导航栏中的概览按钮
• 导航到 /overview URL

功能

• 以网格视图显示所有幻灯片
• 点击任意幻灯片即可跳转
• 在概览中使用键盘导航
• 搜索幻灯片（如已实现）

概览导航

按键	操作
← → ↑ ↓	在网格中导航
Enter	选择幻灯片
Esc / o	关闭概览

跳转对话框

打开方式

• 按 g 键
• 点击导航栏中的幻灯片编号

使用方法

1. 打开对话框
2. 输入幻灯片编号
3. 按 Enter

快速跳转

g → 15 → Enter

直接跳转到第 15 张幻灯片。

自定义快捷键

配置文件

创建 setup/shortcuts.ts：

import { defineShortcutsSetup } from '@slidev/types'

export default defineShortcutsSetup((nav, base) => {
  return [
    ...base, // Keep default shortcuts
    {
      key: 'enter',
      fn: () => nav.next(),
      autoRepeat: true,
    },
    {
      key: 'backspace',
      fn: () => nav.prev(),
      autoRepeat: true,
    },
    {
      key: 'ctrl+f',
      fn: () => nav.go(1),
    },
  ]
})

快捷键属性

属性	类型	说明
key	string	按键组合
fn	function	要执行的操作
autoRepeat	boolean	按住时重复触发

按键语法

// Single key
{ key: 'enter', fn: () => {} }

// Modifier + key
{ key: 'ctrl+s', fn: () => {} }

// Multiple modifiers
{ key: 'ctrl+shift+s', fn: () => {} }

可用修饰键

• ctrl
• shift
• alt
• meta（Mac 上的 Cmd）

导航 API

在组件中

<script setup>
import { useNav } from '@slidev/client'

const {
  currentSlideNo,  // Current slide number (ref)
  currentPage,     // Current page number
  total,           // Total slides
  clicks,          // Current click count
  next,            // Go to next
  prev,            // Go to previous
  go,              // Go to slide number
  nextSlide,       // Next slide (skip animations)
  prevSlide,       // Previous slide (skip animations)
} = useNav()
</script>

导航函数

<template>
  
  <button @click="nav.prev()">Previous</button>
  <button @click="nav.next()">Next</button>
  <button @click="nav.go(1)">Go to Start</button>
  <button @click="nav.go(total.value)">Go to End</button>
</template>

<script setup>
import { useNav } from '@slidev/client'
const nav = useNav()
</script>

自定义导航组件

幻灯片进度条

<script setup>
import { computed } from 'vue'
import { useNav } from '@slidev/client'

const { currentSlideNo, total } = useNav()
const progress = computed(() =>
  (currentSlideNo.value / total.value) * 100
)
</script>

<template>
  <div class="fixed top-0 left-0 right-0 h-1 bg-gray-200">
    <div
      class="h-full bg-blue-500 transition-all"
      :style="{ width: `${progress}%` }"
    />
  </div>
</template>

自定义页码

<script setup>
import { useNav } from '@slidev/client'
const { currentSlideNo, total } = useNav()
</script>

<template>
  <div class="fixed bottom-4 right-4 text-sm">
    {{ currentSlideNo }} / {{ total }}
  </div>
</template>

导航按钮

<script setup>
import { useNav } from '@slidev/client'
const { prev, next, currentSlideNo, total } = useNav()
</script>

<template>
  <div class="fixed bottom-4 flex gap-2">
    <button
      @click="prev()"
      :disabled="currentSlideNo === 1"
      class="px-4 py-2 bg-blue-500 text-white rounded disabled:opacity-50"
    >
      Previous
    </button>
    <button
      @click="next()"
      :disabled="currentSlideNo === total"
      class="px-4 py-2 bg-blue-500 text-white rounded disabled:opacity-50"
    >
      Next
    </button>
  </div>
</template>

触控导航

默认行为

• 向左滑动：下一张幻灯片
• 向右滑动：上一张幻灯片

触控区域

屏幕分为：

• 左侧三分之一：上一张
• 右侧三分之二：下一张

鼠标导航

点击区域

• 幻灯片左侧：上一张
• 幻灯片右侧：下一张

禁用点击导航

---
# In frontmatter
---

用于禁用导航的自定义 CSS：

.slidev-page {
  pointer-events: none;
}

URL 导航

直接访问幻灯片

http://localhost:3030/5      # Slide 5
http://localhost:3030/10     # Slide 10

演讲者模式

http://localhost:3030/presenter
http://localhost:3030/presenter/5  # Presenter at slide 5

概览模式

http://localhost:3030/overview

幻灯片编号

默认编号

幻灯片按顺序从 1 编号到 N。

自定义幻灯片 ID

---
routeAlias: introduction
---

通过以下方式访问：

http://localhost:3030/introduction

按 ID 链接到幻灯片

[Go to Introduction](/introduction)

导航事件

监听导航

<script setup>
import { watch } from 'vue'
import { useNav } from '@slidev/client'

const { currentSlideNo } = useNav()

watch(currentSlideNo, (newSlide, oldSlide) => {
  console.log(`Navigated from ${oldSlide} to ${newSlide}`)
})
</script>

最佳实践

1. 掌握核心快捷键

有助于流畅演示：

• Space / → - 前进
• ← - 后退
• o - 概览
• g - 跳转

2. 根据自己的习惯自定义快捷键

// If you prefer Enter/Backspace
{
  key: 'enter',
  fn: () => nav.next(),
}

3. 隐藏导航，保持演示文稿简洁

用于隐藏导航栏的 CSS：

.slidev-nav {
  display: none;
}

4. 添加进度指示器

用于显示进度的全局底部组件。

5. 练习导航

演示前：

• 浏览所有幻灯片
• 练习通过概览跳转
• 测试自定义快捷键

输出格式

配置导航时：

// setup/shortcuts.ts
import { defineShortcutsSetup } from '@slidev/types'

export default defineShortcutsSetup((nav, base) => {
  return [
    ...base, // Keep defaults

    // Custom shortcuts
    { key: '[key]', fn: () => nav.[action]() },
  ]
})

导航计划：

• 前进：[键]
• 后退：[键]
• 概览：[键]
• 跳转：[方式]

自定义组件：

• 进度条：[是/否]
• 页码：[是/否]
• 自定义按钮：[是/否]