# 键盘导航

> 用 WASD、hjkl 风格按键与单键开关浏览文档。

---

LLMS index: [llms.txt](/zh/llms.txt)

---

OINK 在文档、博客与 Swagger 页面内置单键键盘导航。默认开启，所有按键都会为输入让行，站点或单页均可关闭。设计上，当前页就是侧栏的隐含光标，章节跳转复用渲染后的页面目录，所有动作都委托给主题的既有机制，不维护第二套平行状态。

## 快捷键 {#shortcuts}

### 侧边栏 {#sidebar}

`w`、`s`、`a`、`d`
一步到位地驾驭侧边栏：当前页面所在项就是隐含的起点，首次按键即从那里移动或折叠。焦点行的底色比“当前页”药丸更深一档，“我在哪”与“光标在哪”一眼可辨。窄屏下侧栏收进抽屉时，首次按键会先打开抽屉；桌面侧栏若已折叠，同一次按键会先恢复侧栏，并继续完成所请求的移动或折叠。

| 按键                    | 行为                                 |
| ----------------------- | ------------------------------------ |
| `w` / `↑`               | 焦点移到上一个可见项                 |
| `s` / `↓`               | 焦点移到下一个可见项                 |
| `a` / `←`               | 折叠焦点分组；叶子节点则跳到父级     |
| `d` / `→`               | 展开焦点分组；已展开则进入第一个子项 |
| `Enter` / `Space` / `g` | 打开焦点页面                         |
| `Escape`                | 焦点返回正文                         |

方向键只在焦点位于侧边栏内时作用于树——在正文中保持浏览器原生滚动行为。RTL 语言下
`←`/`→` 随阅读方向对调。

### 阅读 {#reading}

| 按键      | 行为                                  |
| --------- | ------------------------------------- |
| `j` / `k` | 沿页面目录跳到下一节 / 上一节         |
| `q` / `e` | 按侧边栏顺序前往上一篇 / 下一篇       |
| `h`       | 隐藏/恢复全部导航外壳（专注阅读模式） |

`j` 与 `k`
跟右侧目录同源，以固定 100ms 的快速 ease-out 滑动落位；连续按键时，每次都会继续前进一个目录项，无需等待上一段动画。深入某一节时
`k` 会先回到本节起点，无标题的页面退化为同样的短促滑动。`h`
的阅读模式在会话内被记住，用 `h`
会隐藏顶部导航栏、左右栏、浮动控件与页脚。状态会在同一标签页会话中于首帧前恢复，因此用
`q`/`e` 翻页既不会丢失也不会闪烁；侧栏主动隐藏时，WASD 保持静默。

### 外观与语言 {#appearance-and-language}

| 按键 | 行为             |
| ---- | ---------------- |
| `l`  | 循环切换可用语言 |
| `t`  | 亮/暗模式切换    |

### 搜索与命令 {#search-and-commands}

| 按键             | 行为                       |
| ---------------- | -------------------------- |
| `f` 或 `/`       | 打开命令面板的完整搜索模式 |
| `c` 或 `\`       | 打开命令面板，仅列出命令   |
| `Cmd`/`Ctrl`+`K` | 打开命令面板               |

在面板内，以 `>`
为前缀的查询同样只匹配命令。命令列表与导航栏控件顺序一致——版本、语言、主题、GitHub——站点配置的命令排在内建命令之后。`?`
键为未来的快捷键帮助浮层保留。

## 页脚折叠 {#footer-collapse}

与键盘无关的配套能力：启用 fat
footer 时，版权行右端有一个小箭头，可收起或恢复上方的链接栅格。选择会被浏览器记住，默认展开。`h`
的阅读模式作用面更大——它连同左右栏把整个页脚一起隐藏。

## 快捷键何时让行 {#when-shortcuts-stand-down}

所有绑定都是裸单字符按键，凡可能与输入或弹层冲突时一律禁用：

- 焦点位于 input、textarea、select 或 `contenteditable` 区域；
- 输入法组字中（例如正在输入中文）；
- 按住了修饰键——`Cmd`+`C` 依旧复制选中文本，`Shift`+方向键仍归浏览器处理；
- 命令面板或其他对话框处于打开状态。

滚动与逐节跳转遵循 `prefers-reduced-motion`：偏好减弱动效时改为瞬时步进。

## 关闭 {#turning-it-off}

`keyboard_nav.enable` 默认为 `true`。全站关闭：

```yaml {filename="hugo.yaml"}
params:
  ui:
    keyboard_nav:
      enable: false
```

或单页关闭（也可经 front-matter cascade 按节关闭）：

```yaml
---
title: 交互演练场
ui:
  keyboard_nav:
    enable: false
---
```

非布尔值会使构建失败。关闭后该运行时完全不进入 JavaScript bundle； `/`、`\` 与
`Cmd`/`Ctrl`+`K` 属于搜索功能，仍然可用，页脚折叠箭头也不受影响。