ping1999/dsh-minimap

dsh-minimap

为 dsh web GUI 的侧边文件查看器加一条 VS Code 风格的缩略图滚动条（minimap）：宽体文字缩略 + 可拖动的视口框，在长文件中快速定位。

为 dsh web GUI 的侧边文件查看器加一条 VS Code 风格的 minimap：宽体文字缩略图，带可拖动的视口框，用于在长文件中快速导航。

中文 · English

中文

功能

- 在 Files 侧栏文本编辑器的右缘叠加整篇文档的微型文字缩略图
- 半透明视口框实时跟随滚动：点击跳转、按住拖动、悬停滚轮均可定位
- 语法着色：滚动经过的行会带上与编辑器一致的高亮色，自动适配明暗主题
- 宽度随侧栏自适应（约为编辑器宽度的 22%，钳制在 56–110px）；编辑器内容区自动预留「缩略图宽度 + 5px」的间隙，长行文字不会被遮挡
- 拖到底即真正到底：比例映射以编辑器的真实滚动范围为基准
- 纯叠加层：不改动侧栏任何组件，侧栏未启用时静默不渲染；多标签页各自独立，关闭标签页或卸载插件后完全清理

安装

从 npm 安装（推荐）：

dsh plugin --profile web add dsh-minimap

或从 GitHub 源码安装：

dsh plugin --profile web add github:ping1999/dsh-minimap

安装后重启 web 服务生效：

pnpm dsh web

兼容性：已验证 dsh 0.1.5-rc.2 + dsh-better-sidebar 0.19.1（含 0.19 起文件编辑器迁入 DSH 原生右侧栏的 DOM 变化）；向下兼容 dsh 0.1.5-rc.1 / dsh-better-sidebar 0.19.0。

使用

打开任意会话，在右侧 Files 侧栏打开一个文本文件，编辑器右缘即出现缩略图：

- 滚动编辑器 → 缩略图视口框同步移动
- 点击缩略图任意位置 → 编辑器跳转到对应位置（视口居中）
- 按住视口框拖动 → 编辑器跟随滚动（鼠标与触屏均可）
- 悬停缩略图滚轮 → 等效于滚动编辑器（含触控板横向滚动）

限制

- 仅对 CodeMirror 6 文本查看器生效（当前即 dsh-better-sidebar 的文件查看器）；图片 / PDF / Markdown 预览不会出现缩略图
- 语法着色是渐进式的：CM6 只渲染可视行，行滚入视野至少一次后才有颜色
- 安装 / 升级后需重启 web 服务（与所有 profile bundle 一致）
- 暂无设置项

English

Features

- Overlays a miniature text thumbnail of the whole document on the right edge of the Files sidebar's text editor
- A translucent viewport box tracks scrolling live — click to jump, drag to scroll, or hover and use the wheel
- Syntax colors: lines pick up the editor's real highlight colors once scrolled into view, adapting to dark/light themes
- Width adapts to the sidebar (~22% of the editor width, clamped to 56–110 px); the editor reserves the thumbnail's width plus a fixed 5 px gap, so long lines are never covered
- Dragging the box to the bottom reaches the true end of the document — the mapping is anchored to the editor's real scroll range
- Pure overlay: the sidebar is never modified or even aware of the plugin; each tab gets its own instance, and closing a tab or uninstalling removes everything

Install

From npm (recommended):

dsh plugin --profile web add dsh-minimap

Or from GitHub source:

dsh plugin --profile web add github:ping1999/dsh-minimap

Restart the web server to take effect:

pnpm dsh web

Compatibility: verified with dsh 0.1.5-rc.2 + dsh-better-sidebar 0.19.1 (including the 0.19 change that moved the file editor into DSH's native right sidebar); remains compatible down to dsh 0.1.5-rc.1 / dsh-better-sidebar 0.19.0.

Usage

Open any session, open a text file in the Files sidebar, and the minimap appears at the editor's right edge:

- Scroll the editor → the viewport box follows
- Click anywhere on the minimap → jump there (the viewport centers)
- Drag the viewport box → the editor scrolls along (mouse or touch)
- 悬停在小地图上并使用滚轮 → 与滚动编辑器相同（包括触控板水平滚动）

限制

- 仅适用于 CodeMirror 6 文本查看器（目前是 dsh-better-sidebar 的文件查看器）；图片 / PDF / Markdown 预览没有小地图
- 语法着色是渐进式的：CM6 只渲染可见行，因此一行只有在至少被滚动到视图中一次后才会获得颜色
- 安装/升级后需要重启 Web 服务器（与每个 profile bundle 相同）
- 尚无设置

内部实现 · Internals

架构与实现细节（滚动映射、着色策略、几何参数、测试与开发流程）见 AGENTS.md。

架构与实现细节（滚动映射、着色策略、几何参数、测试与开发流程）见 AGENTS.md。

License

MIT