文档检索

本文档介绍 mdView 文档系统的全文检索功能。

功能概述

文档检索支持按文档名称和文档路径进行模糊匹配，并在文档正文中提取包含关键词的上下文片段，帮助用户快速定位目标文档。

入口

在导航栏右侧有搜索按钮（🔍），点击或使用快捷键即可打开搜索弹窗。

操作方式打开搜索点击导航栏搜索按钮打开搜索（键盘）`Ctrl + K` / `⌘K` 打开搜索（键盘）按 `/` 键（非输入框内）关闭搜索按 `Escape` 或点击遮罩

搜索行为

匹配规则

名称匹配：匹配文档标题（数据库 documents 表的 name 字段）

路径匹配：匹配文档文件路径（path 字段）

精确 > 前缀 > 模糊：完全匹配优先，前缀匹配次之，任意位置匹配最后

最多返回：30 条结果

结果展示

每条搜索结果包含：

字段说明 ---------------------------------------- 分类路径面包屑格式的所属分类层级文档标题匹配关键词高亮显示内容片段从 `.md` 文件中截取约 200 字的上下文，关键词高亮

键盘导航

在搜索结果列表中可使用键盘操作：

按键操作 `↓` / `↑`上下移动选中项 `Enter`跳转到选中文档 `Escape`关闭搜索弹窗

输入防抖

输入停止 200ms 后才发起搜索请求，避免频繁查询。

API 接口

搜索功能通过后端 API 提供数据支持。

请求

GET /search?q=关键词

参数类型必填说明 qstring是搜索关键词，至少 1 个字符

响应

{
    "results": [
        {
            "id": 1,
            "parent_id": 0,
            "name": "简介",
            "path": "intro.md",
            "type": "file",
            "level": 0,
            "url_path": "intro",
            "breadcrumb": "",
            "snippet": "{{{mdView}}} 是一个轻量级 PHP 文档管理系统..."
        }
    ],
    "total": 1
}

字段类型说明 resultsarray搜索结果列表 results[].namestring文档名称 results[].pathstring文档文件路径（含 .md 后缀） results[].url_pathstring文档 URL 路径（去 .md 后缀） results[].breadcrumbstring所属分类的面包屑，` > ` 分隔 results[].snippetstring内容片段，关键词用 `{{{...}}}` 包裹 totalint结果总数

后端实现

搜索逻辑位于 DocumentModel.php 和 index.php 中。

查询流程

使用 SQL LIKE 在 documents 表中按 name 和 path 模糊匹配

按匹配精度排序（精确 → 前缀 → 包含）

为每条结果补充所属分类面包屑（向上递归查询父节点）

从对应 .md 文件中提取关键词周围的上下文片段

对关键词位置做 {{{...}}} 标记，供前端高亮渲染

涉及方法

方法文件说明 `searchDocuments($kw)`DocumentModel.php主搜索入口，返回结构化结果 `getBreadcrumb()`DocumentModel.php根据 parent_id 向上追溯分类 `getSnippet()`DocumentModel.php读取 .md 文件提取上下文片段

前端实现

搜索 UI 位于 vitep.php。

组件结构

navbar → 搜索按钮 (.VPSearch)
         ↓ 点击 / 快捷键
搜索弹窗 (.VPModalSearch)
  ├── 搜索输入框 (.VPModalSearchInput)
  └── 结果列表 (.VPModalSearchResults)
       └── 结果项 (.search-result-item) × N

关键函数

函数说明 `openSearch()`打开弹窗，聚焦输入框 `closeSearch()`关闭弹窗，恢复页面滚动 `renderSearchResults`渲染搜索结果 HTML，绑定交互事件 `highlightText()`在标题中对关键词高亮 `highlightSnippet()`在内容片段中对关键词和标记高亮 `escapeRegex()`转义正则特殊字符，防注入 `setActive()`设置键盘选中的结果项

主题适配

搜索弹窗和结果卡片样式遵循系统主题变量（--vp-c-*），自动适配亮色/深色模式。