%%
# 纲要
> 主干纲要、Hint/线索/路标
# Q&A
#### 已明确
#### 待明确
> 当下仍存有的疑惑
**❓<font color="#c0504d"> 有什么问题？</font>**
# Buffer
## 闪念
> sudden idea
## 候选资料
> Read it later
%%
# Neovim 插件清单
##### 通用（vim & Neovim）
| Neovim 插件 | 原生需求 | VSCode 需求 | 说明 | 类似的 Neovim 插件 | 等位的 vim 插件 |
| --------------------------- | ---- | --------- | ------------------------------------------------------ | --------------- | ---------------------------------- |
| nvim-surround | ✔️ | ✔️ | 成对符号（括号引号等）**快捷插入、删除、更替** | | vim-surround |
| nvim-autopairs | | ❌ | 输入一个符号时**自动补全插入**配对的另一符号 | | |
| flash.nvim | ✔️ | ✔️ | 超级强大的**光标快速跳转** | hop, leap.nvim | easy-motion ❌ <br>在 neovim 中不能较好支持 |
| hop | ✔️ | ✔️ | | | |
| | | | | | |
| nvim-treesitter | ✔️ | ✔️ | 提供**语法解析**、**代码高亮**等功能 <br>（重点是语法解析，会得到语法树，其他很多插件依赖于此） | | |
| nvim-treesitter-textobjects | | | | | |
| nvim-treesitter-context | | ❌ | 屏幕上滚动代码时，固定**函数名等层级在顶部**，<br>指示位于哪个代码块中 | | |
| which-key | ✔️ | ❌ | **浮窗显示 vim 快捷键** | | vim-which-key |
| Nvim-web-devicons | ✔️ | ❌ | 图标（which-key 需要） | | |
| | | | | | |
> [!NOTE]
>
> 总结：在 VSCode 结合使用 Neovim，**只需要四个插件：flash、hop、nvim-treesitter、nvim-surrond 即可**。
>
> Vscode 作为编辑器提供了**非常强大的功能**，借助于其中的 VSCodeNeovim 插件，
> **引入 vim 键位操作同时以及快捷移动、编辑相关的几个 Neovim 插件形成有效互补**即可，其他 Neovim 插件都不需要。
> [!tip] 关于 Flash 和 hop
>
> - Flash：主要基于 "**手动输入的内容**" 进行匹配，在匹配项末尾提示 "**跳转标签**"；
> - hop：**自动识别屏幕内所有 word**，在每个 word 前提示 "**跳转标签**"。
>
> 二者功能有重叠也有差异，**可结合使用**——**以 Flash 为主**，hop 为辅。
>
> 例如 hop 中的 ：
>
> - `:HopWord` 功能：**可用于跳转到==中文字符==**。 **Flash 不具有，因而无法实现这一点**；
> - `:HopLineStart`功能：跳转到**某行首个非空字符**。 Flash 只能跳转到行首
>
> 因此，结合使用 Flash 和 hop 。 ^gtc9ia
<br><br>
# nvim-surround
> [GitHub - kylechui/nvim-surround: Add/change/delete surrounding delimiter pairs with ease. Written with in Lua.](https://github.com/kylechui/nvim-surround)
插件功能：通过**特定按键**来快速 **==添加、删除和更改==各种==文本对象==的环绕符号**，如**括号、引号、标签**等。
该插件是 Vim 插件 vim-surround 在 Neovim 下的**同位替代**，基于 Neovim 的新特性和 Lua 脚本实现
- 默认插件配置：[nvim-surround/lua/nvim-surround/config.lua at main · kylechui/nvim-surround · GitHub](https://github.com/kylechui/nvim-surround/blob/main/lua/nvim-surround/config.lua)
- 内置帮助文档：`:h nvim-surround.usage` ⭐（忘记操作了就再看看说明示例）
## 使用说明
![[_attachment/05-工具/vim/Neovim 插件.assets/IMG-Neovim 插件-E009E82BEF6F70726988CF5CC03A43FB.png|952]]
##### 普通模式下
| 按键 | 说明 | 示例 |
| -------------------------------- | ------------------------- | ----------------------------------------------------------------------- |
| **`ys{motion\|text-obj}{char}`** | 添加 | - `ysiw)` ：插入圆括号 <br>- `ysl"` ： 插入双引号<br>- `yst;}`： 在`;` 前插入`{}` 括号<br> |
| **`yS{motion\|text-obj}{char}`** | 令其中内容**单独成行**，在其**前后行添加** | |
| **`yss{char}`** | 为**整行**添加 | - `yss"`，等同于 `0ys
quot;`； <br>- `yss}` |
| **`ySS{char}`** | 令整行内容**单独成行**，在其**前后行添加** | - `ySS}`： `{}` 各占一行, 中间行是内容 |
| | | |
| **`ds{char}`** | 删除 | - `ds)` ：删除圆括号 <br>- `dst`： 删除标签<br>- `dsf`： 删除函数调用 |
| **`cs{target}{replacement}`** | 替换 | - `cs"(` ：替换双引号为圆括号 <br>- `csth1<CR>`：替换标签内容为 `<h1></h1>`<br> |
`{char}` 可以是各种环绕符号，例如**括号、引号**，或是**特殊的单字符别名**：
- `t{..}<CR>`：**标签 `<..></..>`**
- `f`：函数调用 `func()` 整体
- 别名：![[_attachment/05-工具/vim/Neovim 插件.assets/IMG-Neovim 插件-356A13635452BF43796670D1986C453F.png|409]]
> [!NOTE] 注：对于**任意括号类型**，`y` 搭配 **==左开括号==** 会在前后额外**插入空格**，`d` 搭配 **==左开括号==** 会**删除前后多余空格**， **`c` 同理**
>
> ![[_attachment/05-工具/vim/Neovim 插件.assets/IMG-Neovim 插件-C6AFF9C93A1B4A6E86CE4397DBD7893E.png|539]]
>
> ![[_attachment/05-工具/vim/Neovim 插件.assets/IMG-Neovim 插件-8B55396A4A2698821B7068AAABA9B35D.png|531]]
>
> ![[_attachment/05-工具/vim/Neovim 插件.assets/IMG-Neovim 插件-3BEDB662F10F2737BF2E710CC6104142.png|534]]
##### 插入模式下
| 按键 | 说明 |
| ------------------ | ---------------------------- |
| **`<C-g>s{char}`** | 插入一对符号，**光标在中间** |
| **`<C-g>S{char}`** | 插入一对符号，并**在中间产生一个空行，光标位于其中** |
##### 可视模式下
| 按键 | 说明 |
| -------------- | ----------------------------- |
| **`S{char}`** | 为选中区域插入一对环绕符号 |
| **`gS{char}`** | 令其中内容**单独成行**，在其**前后行添加**环绕符号 |
<br>
## 按键修正 🚨
**`s` 与 `S` 键** 与 **Flash.nvim 插件**的功能冲突，例如 `ys` 和 `ds`。 => **修改 surround 的这两个按键为 `u` 和 `U` 键**。
![[_attachment/05-工具/vim/Neovim 插件.assets/IMG-Neovim 插件-8395921B17FBC644F98551FF1D499009.png|477]]
## 自定义配置
如果有需要自定义配置，遵循以下说明：
![[_attachment/05-工具/vim/Neovim 插件.assets/IMG-Neovim 插件-DD82D309D0B4385324CE0EC79C742F5A.png|489]]
> [!example] `nvim-surround` 的配置文件 `nvim-surround.lua`
>
> 插件官方文档如图：
>
> ![[_attachment/05-工具/vim/Neovim 插件.assets/IMG-Neovim 插件-31D650DDB6229E44247D5283227052CF.png|632]]
>
> 根据 lazy.nvim 官方文档说明，应当**使用 `opts = {}` 替代 `config = function() ... ebd`**，故更改为如下：
>
> ![[_attachment/05-工具/vim/Neovim 插件.assets/IMG-Neovim 插件-EC83A0E05C2BC6D0BFED3162961087AD.png|640]]
> ^y04wu9
<br><br><br>
# Flash.nvim
> [GitHub - folke/flash.nvim: Navigate your code with search labels, enhanced character motions and Treesitter integration](https://github.com/folke/flash.nvim?tab=readme-ov-file)
功能：**==光标快速跳转==**——搜索**输入内容**，自动在 "**匹配项**" 末尾提示"**==跳转标签==**"，根据标签按键**实现跳转**。
功能演示参见[^1]
> [!info] 跳转标签
>
>
> ![[_attachment/05-工具/vim/Neovim 插件.assets/IMG-Neovim 插件-4E0DC4C1F94AF45C3E5C87B0A4BF91C8.png|509]]
>
> 输入的是 "mat"，Flash 在所有匹配项后显示了 “**跳转指示标签**”，如上图粉色标识
#### 使用说明
![[_attachment/05-工具/vim/Neovim 插件.assets/IMG-Neovim 插件-D466398184AF51A2E27F8A6AB6A2264C.png|901]]
| 插件功能 | 可用模式 | 触发按键 | 功能说明 |
| ---------------------------- | ------- | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Flash 跳转** | n, x, o | **s** | - 输入 "**任意内容**" ，**将高亮匹配项**并在其末尾提示 "**跳转标签**" <br>- **按标签跳转**（x 模式下选中，o 模式下应用操作）<br> |
| | | | |
| **Remote 跳转** | o | **r**（例如 `yr`, `cr`, `dr`） | **跳至远程位置执行操作后==回到初始位置==** ：<br>- 输入任意内容，Flash 将显示匹配项的**跳转标签**； <br>- **按标签跳转后**，**键入 motion**（例如 `iw` ，或者`S` 启动 Treesitter 模式），操作完成后将**回到==最初光标位置==**。 <br> |
| | | | |
| **Treesitter 模式** | n, x, o | **S** | 用于**范围选中**：<br>- **在==当前光标所在 Treesitter 节点==的==所有父级节点==的 "==前后==" 显示 "跳转标签"**<br>- **按标签跳转，实现范围选中** <br>- 支持**增量选择**： `;` 提升范围， `,` 缩减范围 |
| | | | |
| **Treesitter 搜索模式** | x, o | **R**（例如 `yR`，`vR`） | - 输入任意搜索内容，将显示匹配项各级 Treesitter 父节点的 "前后" 显示**跳转标签**<br>- **按标签跳转以完成动作**（**x 模式下进行范围选中，o 模式下应用命令**） |
| | | | |
| **增强 `/` 与 `?` 搜索跳转** | c | **`<C-s>`**（触发/关闭） | - 输入**搜索内容**（不要按`<CR>`），**将高亮匹配项**并在其末尾提示 "**跳转标签**"； |
| | | | |
| **增强 `f`, `t`, `F`, `T` 移动** | n | | - **支持前、后文匹配及跳转**（而不仅是在行内）<br> - **搜索到字符**后，再次**按 `f` 等价于 `;`，按 `F` 等价于 `.`** => 便于操作。 |
| | | | |
> [!NOTE] Treesitter 相关模式效果说明
>
> Treesitter 解析得到 **==语法树==**。
>
> Flash 在 Treesitter 模式下，会**为==当前光标所在 Treesitter 节点==的==所有父级节点==的 "==前后==" 显示 "跳转标签"**，实现 **==范围选择、范围操作==**，
> 例如选中 or 作用域**整行、整个`{}`块作用域内、整个函数、整个文件**等。
>
> 如下图所示，**Flash 用相同字母标记处了范围的起始、终止位置**
>
> ![[_attachment/05-工具/vim/Neovim 插件.assets/IMG-Neovim 插件-FB32F4B50C5D675886727F72D5620873.png|593]]
>
> ![[_attachment/05-工具/vim/Neovim 插件.assets/IMG-Neovim 插件-077B2CE510DB0C925378C3E6C7194676.png|136]]
>
>
> [!tip] Flash 的跳转位置会记录到 changes list 中，可以**通过 `<C-o>` 与 `<C-i>` 来回跳转**。
> [!warning] 该插件会覆盖 vim 原生的 `s` 与 `S` 按键功能，后两者分别等价于 `cl` 与 `cc`
> [!note] Flash 支持多窗口间的跳转（默认）
> ![[_attachment/05-工具/vim/Neovim 插件.assets/IMG-Neovim 插件-9A45AB99A0968BB27797B69F3CBA109A.png|697]]
>
> [!error] Flash 的 remote 模式在 VSCode 中无效
>
>
> [Don't use remote flash keymap in VS Code due to https://github.com/vs… · archilkarchava/nvim@185b729 · GitHub](https://github.com/archilkarchava/nvim/commit/185b72970a9f723067c5ada1b40843106a1c4d63)
>
>
## 插件配置文件
> [!example] `flash.nvim` 的配置文件 `flash.nvim.lua`（默认配置，参见官网）
>
> ![[_attachment/05-工具/vim/Neovim 插件.assets/IMG-Neovim 插件-29F61D7D11E270C076F01706551CD4D8.png|755]]
>
> ^qu8flb
### 自定义配置
#### 配置 "可跳转到行"
keys 中加入一个自定义按键映射，`require("flash").jump()` 内容按如下编写：
![[_attachment/05-工具/vim/Neovim 插件.assets/IMG-Neovim 插件-1631C5259D1E21559BE4299C6E1A1B58.png|685]]
按 `<leader>s` 后效果如下：
![[_attachment/05-工具/vim/Neovim 插件.assets/IMG-Neovim 插件-E2B6BF0EAF01DF0EBFF295CE2671E980.png|334]]
> [!danger] 该功能已改为由 hop 插件提供！注释掉上述按键绑定。
<br><br><br>
# Hop
> [GitHub - hadronized/hop.nvim: Neovim motions on speed!](https://github.com/hadronized/hop.nvim?tab=readme-ov-file#features)
功能：**光标快速跳转**——**自动识别屏幕内 word 等**，在每个 word 前提示 "**跳转标签**"，根据标签按键**实现跳转**。
功能演示参见[^2] [^3]
![[_attachment/05-工具/vim/Neovim 插件.assets/IMG-Neovim 插件-A6E6714B20A3D3CFCFA5BB4D398769E8.png|694]]
## 插件配置
hop 提供了上述命令，但**默认未绑定任何按键**，因此需要**自行绑定**。
> [!caution] 不建议按官方文档里的那种设置方法（**调用 hop 函数**），不利于模块化组织 => 直接绑定按键为执行 `:HopWord<CR>` 命令即可。
在 Neovim 配置文件 `~/config/nvim/init.lua` 中设置如下按键绑定：
![[_attachment/05-工具/vim/Neovim 插件.assets/IMG-Neovim 插件-BE13F554CABA20EA80E17C1D2D591028.png|634]]
**我只需要上述三个功能**。
<br><br><br>
# nvim-treesitter
nvim-treesitter 基于 **TreeSitter 语法解析器** 来提供强大的**语法解析**和**代码分析**功能，实现**对各种编程语言**进行**快速准确的语法分析**。
nvim-treesitter 的功能包括：
1. **语法高亮**：基于语法树的准确分析，提供更准确、丰富的语法高亮显示。
2. **自动缩进**：根据语法树的结构，自动调整代码的缩进
3. **智能缩写**：根据语法树的理解，智能地扩展和补全代码的缩写。
4. **智能选择和操作**：根据语法树的知识，提供更智能的选择和操作功能，如选择函数、类、条件语句等。
5. **代码导航**：根据语法树的结构，提供跳转到定义、查找引用、代码浏览等功能
6. **代码重构**：基于语法树的信息，提供代码重构功能，如重命名变量、提取函数等。
7. **错误和警告提示**：根据语法树的分析，提供更准确的错误和警告提示
> [!important] `nvim-surround`、`Flash.nvim` 插件中部分功能都依赖于 **TreeSitter 的语法解析**
#### 增量选择功能
用于快速选中 TreeSitter 语法树上，**当前光标所在 Node 的各层级父级节点**。
![[_attachment/05-工具/vim/Neovim 插件.assets/IMG-Neovim 插件-37E2DBBCA9F95E2ACB1A53774FD015B6.png|464]]
`grn`，`grc`，`grm` 都可在**进入可视模式后直接使用**。
## TreeSitter 语法解析器
**TreeSitter 是一种高效且可扩展的语法解析器**。
TreeSitter 本身会**对==不同语言分别应用不同的解析器==（parser）**，需要**自行安装&编译配置**。
nvim-treesitter 插件简化了这一过程，**提供下列命令来自动化相关过程**：
- **安装特定语言的解析器**：`:TSInstall <language_to_install>`
- **查看已安装的语言解析器**：`:TSInstallInfo`
- **自动更新所有语言解析器（保证是最新稳定版本）**：`:TSUpdate`
在 `nvim-treesitter` 插件的配置文件中，可以通过 `ensure_installed` 列表**指定所需的语言解析器**：
![[_attachment/05-工具/vim/Neovim 插件.assets/IMG-Neovim 插件-51D157DE93ECEDF0B1D43A9119945FA7.png|637]]
支持的语言列表参见：[GitHub - nvim-treesitter/nvim-treesitter: Nvim Treesitter configurations and abstraction layer](https://github.com/nvim-treesitter/nvim-treesitter?tab=readme-ov-file#supported-languages)
## 高亮示意
> [!example] nvim-treesiter 提供的语法高亮
> ![[_attachment/05-工具/vim/Neovim 插件.assets/IMG-Neovim 插件-CBE45E5017E5280AC70BAE31BF61CF23.png|693]]
>
> ![[_attachment/05-工具/vim/Neovim 插件.assets/IMG-Neovim 插件-274754C5B217F6B8D840650B54F93B7D.png|882]]
>
>
## 插件配置文件
> [!example] `nvim-treesitter` 的配置文件
>
> ![[_attachment/05-工具/vim/Neovim 插件.assets/IMG-Neovim 插件-8A334B31DE134494B4239E2B387D801F.png|564]]
>
> 参照插件官网。注意，这里没有用 `opts`，是因为 `local configs` 中导入的是 `"nvim-treesitter.configs"` 模块文件，**是不同的！** ^2o26dg
<br><br><br>
# Which-key
功能：**按下前缀键（`<leader>`或其他键例如`g`）后自动触发浮窗**，**显示所有==与前缀键相关的==可用键绑定和操作**。
> [!caution] 其仅显示基于 "**前缀键**" 的**按键绑定**，单个按键例如 j, k, h, l 并没有显示
> [!example] g 键触发的浮窗显示
>
> ![[_attachment/05-工具/vim/Neovim 插件.assets/IMG-Neovim 插件-620C5DD8598722DDBBE1595F0B1A4A7A.png|589]]
>
> [!example] 可视模式下的浮窗显示
>
> ![[_attachment/05-工具/vim/Neovim 插件.assets/IMG-Neovim 插件-4789F8DE7606025A1A1A709F13C7ACCE.png|587]]
>
> [!example] `<C-w>` 的浮窗显示
> ![[_attachment/05-工具/vim/Neovim 插件.assets/IMG-Neovim 插件-12EF1FB54D2AA1D69B962275FEB37587.png|580]]
>
>
## 插件配置文件
> [!example] `which-key` 的配置文件
>
> ![[_attachment/05-工具/vim/Neovim 插件.assets/IMG-Neovim 插件-E08A6B361CC555476942E5B4AA7B06A0.png|682]]
> ^wz0l58
<br><br><br>
# 参考资料
- [我的现代Nvim (lvim)配置——NeoVim(lunarvim)插件推荐、安装教程和效果展示（二） | Eniac’s Blog](https://blog.3n1ac.com/article/nvim-and-lunarvim-plugins-2) ⭐ 实用插件说明
- [neovim 安装使用备忘 | 血衫非弧の一存](https://blog.kelu.org/tech/2023/06/06/vim-ide.html)
- [GitHub - rockerBOO/awesome-neovim: Collections of awesome neovim plugins.](https://github.com/rockerBOO/awesome-neovim)
# Footnotes
[^1]: [NeoVim最强移动插件(flash.nvim)功能详解\_哔哩哔哩\_bilibili](https://www.bilibili.com/video/BV1iV411G7nq/?spm_id_from=333.788.recommend_more_video.0&vd_source=94d94bad947a5b38e63f1f55450429ab)
[^2]: [Commands · hadronized/hop.nvim Wiki · GitHub](https://github.com/hadronized/hop.nvim/wiki/Commands)
[^3]: [Is Hop.nvim better than Flash.nvim? - by Andrew Courter](https://andrewcourter.substack.com/p/is-hopnvim-better-than-flashnvim)