{"id":51567627,"url":"https://github.com/beixiyo/vv-scrollbar.nvim","last_synced_at":"2026-07-10T16:01:44.495Z","repository":{"id":370677670,"uuid":"1296108359","full_name":"beixiyo/vv-scrollbar.nvim","owner":"beixiyo","description":"Interactive Neovim scrollbar with click-to-jump, drag and code markers. 可点击拖拽的 Neovim 滚动条（完整轨道 / 诊断 / Git / 搜索标记）","archived":false,"fork":false,"pushed_at":"2026-07-10T06:52:43.000Z","size":18,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-07-10T08:16:45.800Z","etag":null,"topics":["diagnostics","git","lua","mouse","neovim","neovim-plugin","nvim","nvim-plugin","quickfix","scrollbar","scrolling","search"],"latest_commit_sha":null,"homepage":null,"language":"Lua","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/beixiyo.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-07-10T05:58:10.000Z","updated_at":"2026-07-10T06:52:49.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/beixiyo/vv-scrollbar.nvim","commit_stats":null,"previous_names":["beixiyo/vv-scrollbar.nvim"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/beixiyo/vv-scrollbar.nvim","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/beixiyo%2Fvv-scrollbar.nvim","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/beixiyo%2Fvv-scrollbar.nvim/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/beixiyo%2Fvv-scrollbar.nvim/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/beixiyo%2Fvv-scrollbar.nvim/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/beixiyo","download_url":"https://codeload.github.com/beixiyo/vv-scrollbar.nvim/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/beixiyo%2Fvv-scrollbar.nvim/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35335898,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-10T02:00:06.465Z","response_time":60,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["diagnostics","git","lua","mouse","neovim","neovim-plugin","nvim","nvim-plugin","quickfix","scrollbar","scrolling","search"],"created_at":"2026-07-10T16:01:28.708Z","updated_at":"2026-07-10T16:01:44.459Z","avatar_url":"https://github.com/beixiyo.png","language":"Lua","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003ch1 align=\"center\"\u003evv-scrollbar.nvim\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cem\u003eNeovim 自绘滚动条 — 完整轨道、点击跳转、原生拖拽与代码状态标记\u003c/em\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/Neovim-0.11+-57A143?style=flat-square\u0026logo=neovim\u0026logoColor=white\" alt=\"Requires Neovim 0.11+\" /\u003e\n  \u003cimg src=\"https://img.shields.io/badge/Lua-2C2D72?style=flat-square\u0026logo=lua\u0026logoColor=white\" alt=\"Lua\" /\u003e\n  \u003cimg src=\"https://img.shields.io/badge/license-MIT-blue?style=flat-square\" alt=\"MIT License\" /\u003e\n\u003c/p\u003e\n\n---\n\n## 特性\n\n- 完整窗口高度的背景轨道，以及按可见内容比例计算的 thumb\n- 点击轨道直接跳转；拖动 thumb 时保留鼠标抓取位置\n- 普通点击不触发拖拽色，实际移动后才显示 hover 状态\n- 与 `vv-utils.scroll` 协作，滚动条交互不会被自动平滑滚动拉回旧位置\n- 宽度可配置，轨道与 thumb 会占满实际宽度，默认 `2` 格\n- 当前光标标记占满滚动条宽度，其余 marker 保持单字符显示\n- 支持多窗口，也可只显示当前窗口\n- 内置 diagnostics、Git diff、搜索、Vim marks、quickfix / loclist、光标位置标记\n- 自动响应滚动、窗口切换、尺寸变化、文本修改、诊断变化和 Git 状态变化\n- 纯 Lua 实现，UI 与异步基础能力统一复用 `vv-utils.nvim`\n\n## 安装\n\n```lua\n{\n  'beixiyo/vv-scrollbar.nvim',\n  dependencies = { 'beixiyo/vv-utils.nvim' },\n  event = { 'BufReadPost', 'BufNewFile' },\n  ---@type VVScrollbarConfig\n  opts = {},\n}\n```\n\n需要 Neovim `0.11+`。鼠标交互依赖 `nvim_open_win({ mouse = true })` 和\n`vim.on_key()` 消费鼠标事件\n\n## 完整配置\n\n```lua\nrequire('vv-scrollbar').setup({\n  enabled = true,\n  current_only = false,\n  width = 2,\n  right_offset = 0,\n  zindex = 45,\n  winblend = 0,\n  min_thumb = 2,\n  throttle_ms = 30,\n  search_line_limit = 20000,\n  window_filter = nil,\n\n  excluded_filetypes = {\n    'terminal', 'toggleterm', 'blink-cmp-menu', 'cmp_docs', 'cmp_menu',\n    'dropbar_menu', 'dropbar_menu_fzf', 'DressingInput', 'noice',\n    'prompt', 'TelescopePrompt', 'dashboard', 'vv-explorer', 'vv-git',\n    'vv-task-panel',\n  },\n  excluded_buftypes = { 'nofile', 'terminal', 'prompt', 'quickfix' },\n\n  markers = {\n    diagnostics = true,\n    git = true,\n    search = true,\n    marks = true,\n    quickfix = true,\n    cursor = true,\n  },\n\n  symbols = {\n    thumb = ' ',\n    cursor = '█',\n    search = '•',\n    mark = '◆',\n    quickfix = '■',\n    diagnostics = {\n      [vim.diagnostic.severity.ERROR] = '●',\n      [vim.diagnostic.severity.WARN] = '●',\n      [vim.diagnostic.severity.INFO] = '●',\n      [vim.diagnostic.severity.HINT] = '●',\n    },\n    git = {\n      A = '▎',\n      C = '▎',\n      D = '󰆐',\n    },\n  },\n\n  highlights = {\n    track = { bg = '#20242b' },\n    thumb = { bg = '#3b4252' },\n    hover = { bg = '#4b5568' },\n    cursor = { fg = '#7aa2f7' },\n    search = { fg = '#ff9e64' },\n    mark = { fg = '#bb9af7' },\n    quickfix = { fg = '#e0af68' },\n    diag_error = { fg = '#f7768e' },\n    diag_warn = { fg = '#e0af68' },\n    diag_info = { fg = '#7dcfff' },\n    diag_hint = { fg = '#1abc9c' },\n  },\n})\n```\n\n`setup()` 每次都从默认配置重新合并传入值，不会继承上一次调用中未再次提供的字段\n\n## 基础配置\n\n| 选项 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| `enabled` | `boolean` | `true` | `setup()` 后是否立即启用 |\n| `current_only` | `boolean` | `false` | 只为当前窗口显示滚动条 |\n| `width` | `integer` | `2` | 轨道宽度，单位为屏幕格；最小值为 `1` |\n| `right_offset` | `integer` | `0` | 距父窗口右边缘的偏移格数；最小值为 `0` |\n| `zindex` | `integer` | `45` | 滚动条浮窗的 z-index |\n| `winblend` | `integer` | `0` | 滚动条浮窗透明度 |\n| `min_thumb` | `integer` | `2` | thumb 最小高度；最小值为 `1` |\n| `throttle_ms` | `integer` | `30` | 非鼠标直接交互的刷新节流时间；`0` 表示不延迟 |\n| `search_line_limit` | `integer` | `20000` | 超过该行数时跳过搜索结果投影 |\n| `excluded_filetypes` | `string[]` | 见完整配置 | 不显示滚动条的 filetype |\n| `excluded_buftypes` | `string[]` | 见完整配置 | 不显示滚动条的 buftype |\n| `window_filter` | `fun(win, buf): boolean` | `nil` | 返回 `false` 时不为该窗口显示滚动条 |\n\n当窗口比配置宽度更窄时，实际宽度会自动收缩，避免浮窗越过父窗口\n\n### 窗口级控制\n\n插件或临时窗口可以通过窗口变量关闭自己的滚动条：\n\n```lua\nvim.w[win].vv_scrollbar_disabled = true\n```\n\n恢复时将变量设为 `nil` 或 `false`，再执行 `:VVScrollbarRefresh`。`vv-git.nvim`\n会自动为左侧基准 diff 窗口设置该变量，仅保留右侧工作区的滚动条\n\n需要把滚动条作为 marker 轨道常驻时，可设置：\n\n```lua\nvim.w[win].vv_scrollbar_always_show = true\n```\n\n`vv-git.nvim` 会为右侧 diff 窗口自动设置，避免折叠、换行或 diff filler 导致轨道\n随滚动位置出现或消失\n\n## Marker 配置\n\n| 选项 | 默认值 | 数据来源 |\n|------|--------|----------|\n| `markers.diagnostics` | `true` | `vim.diagnostic.get()`，同一投影行优先显示最高严重级别 |\n| `markers.git` | `true` | `vv-utils.git.diff_lines()` 的 worktree / staged 行级 `A / C / D`；支持 `vv-git` scratch buffer |\n| `markers.search` | `true` | 当前 `/` 寄存器匹配结果 |\n| `markers.marks` | `true` | 当前 buffer 与全局的字母 mark |\n| `markers.quickfix` | `true` | quickfix 与当前窗口 loclist |\n| `markers.cursor` | `true` | 当前活动窗口的光标行，横向占满滚动条宽度 |\n\n同一投影行出现多个 marker 时按优先级只显示一个：光标 \u003e 诊断 \u003e Git \u003e\nquickfix / loclist \u003e mark \u003e 搜索\n\n## 符号配置\n\n| 选项 | 默认值 | 说明 |\n|------|--------|------|\n| `symbols.thumb` | `' '` | thumb 填充字符，会重复填满滚动条宽度 |\n| `symbols.cursor` | `'█'` | 当前光标标记，会重复填满滚动条宽度 |\n| `symbols.search` | `'•'` | 搜索命中标记 |\n| `symbols.mark` | `'◆'` | Vim mark 标记 |\n| `symbols.quickfix` | `'■'` | quickfix / loclist 标记 |\n| `symbols.diagnostics` | 四种 severity 映射 | 诊断标记字符 |\n| `symbols.git` | `{ A, C, D }` | Git 新增、修改、删除标记字符 |\n\n每个符号只读取第一个字符。除 thumb 和 cursor 外，其余 marker 不会横向重复\n\n## 高亮配置\n\n| 配置项 | 注册的高亮组 | 用途 |\n|--------|--------------|------|\n| `highlights.track` | `VVScrollbarTrack` | 背景轨道 |\n| `highlights.thumb` | `VVScrollbarThumb` | 当前可见范围 |\n| `highlights.hover` | `VVScrollbarHover` | 实际拖拽中的 thumb |\n| `highlights.cursor` | `VVScrollbarCursor` | 当前光标位置 |\n| `highlights.search` | `VVScrollbarSearch` | 搜索命中 |\n| `highlights.mark` | `VVScrollbarMark` | Vim mark |\n| `highlights.quickfix` | `VVScrollbarQuickfix` | quickfix / loclist |\n| `highlights.diag_error` | `VVScrollbarDiagnosticError` | Error 诊断 |\n| `highlights.diag_warn` | `VVScrollbarDiagnosticWarn` | Warn 诊断 |\n| `highlights.diag_info` | `VVScrollbarDiagnosticInfo` | Info 诊断 |\n| `highlights.diag_hint` | `VVScrollbarDiagnosticHint` | Hint 诊断 |\n\nGit marker 使用 `vv-utils.git.register_hl()` 提供的 `VVGitAdded`、\n`VVGitModified`、`VVGitDeleted`。所有高亮会在 `ColorScheme` 后重新注册\n\n## 鼠标交互\n\n| 操作 | 行为 |\n|------|------|\n| 点击轨道 | 以点击点为中心放置 thumb，并立即跳转对应视口 |\n| 按下 thumb | 保持原位置，不切换 hover 色 |\n| 拖动 thumb | 保留按下时的抓取偏移，并实时更新视口 |\n| 拖出轨道顶部或底部 | 吸附到文件开头或结尾 |\n| 松开鼠标 | 结束拖拽并恢复普通 thumb 高亮 |\n\n滚动条跳转和拖拽使用 `vv-utils.scroll.with_auto_suppressed()`，因此即使启用了\n`vv-utils.scroll` 的自动跳转动画，也不会出现先跳到目标、回到旧位置、再动画到目标的回弹\n\n## 命令\n\n| 命令 | 说明 |\n|------|------|\n| `:VVScrollbarEnable` | 启用滚动条 |\n| `:VVScrollbarDisable` | 禁用滚动条并关闭所有滚动条浮窗 |\n| `:VVScrollbarToggle` | 切换启用状态 |\n| `:VVScrollbarRefresh` | 重新获取可见文件的 Git marker 并立即刷新 |\n\n## Lua API\n\n```lua\nlocal scrollbar = require('vv-scrollbar')\n\nscrollbar.setup({ width = 2 })\nscrollbar.enable()\nscrollbar.disable()\nscrollbar.toggle()\n\nlocal current_config = scrollbar.get_config()\n```\n\n`get_config()` 返回深拷贝，修改返回值不会影响插件内部配置\n\n## 模块结构\n\n```text\nlua/vv-scrollbar/\n├── core/        几何计算、运行状态与浮窗渲染\n├── features/    Git 数据和 marker 收集\n├── input/       鼠标 press / drag / release 状态机\n├── lifecycle/   autocmd 生命周期\n├── ui/          高亮注册\n├── config.lua   默认配置与合并\n└── init.lua     对外生命周期 API\n```\n\n## 测试\n\n```bash\nnvim --headless -u NONE -l tests/test_smoke.lua\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbeixiyo%2Fvv-scrollbar.nvim","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbeixiyo%2Fvv-scrollbar.nvim","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbeixiyo%2Fvv-scrollbar.nvim/lists"}