nvim-recorder 📹

增强 Neovim 中宏的使用。

功能
设置
基本用法
高级用法
关于我

功能

简化控制：一个键开始和停止录制，另一个键播放宏。不再需要 qa … q @a @@，只需 q … q Q Q。¹
__宏断点__用于更容易调试宏。断点可以在录制后设置，并在使用计数触发宏时自动忽略。
状态栏组件：特别适用于使用 cmdheight=0 的情况，此时录制状态不可见。
宏转映射：复制宏，以便保存为映射。
各种提升用户体验的功能：显示宏内容的通知、取消录制的能力、编辑宏的命令等。
大型宏的性能优化：当宏以高计数触发时，临时启用一些性能改进。
使用最新的 nvim 功能，如 vim.notify。这意味着你可以通过类似 nvim-notify 的插件获得确认通知。

设置

安装

-- lazy.nvim
{
	"chrisgrieser/nvim-recorder",
	dependencies = "rcarriga/nvim-notify", -- 可选
	opts = {}, -- 即使使用默认设置也需要，因为它会调用 `setup()`
},

-- packer
use {
	"chrisgrieser/nvim-recorder",
	requires = "rcarriga/nvim-notify", -- 可选
	config = function() require("recorder").setup() end,
}

调用 setup() (或 lazy 的 opts) 是__必需的__。

配置

-- 默认值
require("recorder").setup {
	-- 保存宏的命名寄存器（仅限单个小写字母）。
	-- 第一个寄存器是启动后用作宏槽的默认寄存器。
	slots = { "a", "b" },

	mapping = {
		startStopRecording = "q",
		playMacro = "Q",
		switchSlot = "<C-q>",
		editMacro = "cq",
		deleteAllMacros = "dq",
		yankMacro = "yq",
		-- ⚠️ 这应该是一个在宏录制过程中不会在插入模式下使用的字符串
		addBreakPoint = "##",
	},

	-- 在启动时清除所有宏槽。
	clear = false,

	-- 用于非关键通知的日志级别；主要与 nvim-notify 相关。
	-- （注意，默认情况下，nvim-notify 不显示 `trace` 和 `debug` 级别。）
	logLevel = vim.log.levels.INFO, -- :help vim.log.levels

	-- 如果启用，只发送必要的通知。
	-- 如果你不使用像 nvim-notify 这样的插件，请将此设置为 `true`
	-- 以移除可能令人烦恼的消息。
	lessNotifications = false,

	-- 在状态栏组件和按键映射描述中使用 nerdfont 图标
	useNerdfontIcons = true,

	-- 高计数宏的性能优化。当 `playMacro` 触发的计数高于阈值时，
	-- nvim-recorder 会在宏执行期间临时更改一些设置。
	performanceOpts = {
		countThreshold = 100,
		lazyredraw = true, -- 启用 lazyredraw（参见 `:h lazyredraw`）
		noSystemClipboard = true, -- 从剪贴板选项中移除 `+`/`*`
		autocmdEventsIgnore = { -- 临时忽略这些自动命令事件
			"TextChangedI",
			"TextChanged",
			"InsertLeave",
			"InsertEnter",
			"InsertCharPre",
		},
	},

	-- [实验性] 部分与 nvim-dap 共享按键映射。
	-- （详见 README 以获取进一步解释。）
	dapSharedKeymaps = false,
}

如果你想处理多个宏或使用 cmdheight=0，建议也设置状态栏组件：

状态栏组件

-- 指示你当前是否正在录制。在使用 `cmdheight=0` 时很有用，
-- 因为此时录制状态不可见。
require("recorder").recordingStatus()

-- 显示非空宏槽（寄存器）并指示选定的槽。
-- 仅在__不__录制时显示。带有断点的槽会有一个额外的 `#`。
require("recorder").displaySlots()

[!提示] 与配置 clear = true 一起使用，以查看本次会话中录制的宏。

将状态栏组件添加到 lualine 的示例：

lualine_y = {
	{ require("recorder").displaySlots },
},
lualine_z = {
	{ require("recorder").recordingStatus },
},

[!提示] 将组件放在不同的状态栏段落中，使它们具有不同的颜色，使录制状态更容易与已保存的录制区分开来。

基本用法

startStopRecording：开始向当前宏槽录制（无需指定寄存器）。再次按下以结束录制。
playMacro：播放当前槽中的宏（无需指定寄存器）。
switchSlot：循环切换配置中指定的寄存器。还会显示一个包含槽和其内容的通知。（当前选定的槽可以在状态栏组件中看到。）
editMacro：编辑活动槽中录制的宏。（请注意，这些是"编码"形式的按键。）
yankMacro：以可用于创建映射的解码形式复制当前宏。从复制的宏中移除断点。
deleteAllMacros：清除所有宏槽。

[!提示] 对于递归宏（在宏内播放宏），你仍然可以使用默认命令 @a。

高级用法

性能优化

运行长宏或高计数宏可能会对系统造成压力并导致延迟。为此，nvim-recorder 提供了一些性能优化，这些优化会在运行高计数宏时临时启用。

请注意，这些优化可能会有一些潜在的缺点。

lazyredraw 禁用屏幕重绘，这使得注意到宏中未考虑的边缘情况变得更加困难。它可能还会使屏幕看起来暂时冻结。
禁用系统剪贴板通常是安全的，如果你不打算在宏中向其复制内容。
当你在宏期间依赖某些插件功能时，不建议忽略自动命令，因为它可能会潜在地中断这些插件的效果。

宏断点

nvim-recorder 允许你在宏中设置断点，这对调试宏很有帮助。当你使用计数触发宏时，断点会自动被忽略。

设置断点

在录制过程中， 在普通模式下按下 addBreakPoint 键（默认：##）。
在录制之后， 使用 editMacro 并手动添加或删除 ##。

播放带断点的宏

使用 playMacro 键，宏会自动在下一个断点处停止。下次按 playMacro 时，宏的下一个片段会被播放。
开始新的录制、编辑宏、复制宏或切换宏槽都会重置序列，这意味着 playMacro 会从头开始。

[!提示] 你可以在播放宏片段之间做其他事情，比如向左或向右移动几个字符。这样你也可以使用断点来手动纠正不规则之处。 忽略断点 当你使用计数播放宏时(例如50Q)，断点会自动被忽略。

[!提示] 添加计数1(1Q)可以播放一次宏并仍然忽略断点。

与nvim-dap共享的键位绑定 如果你正在使用nvim-dap，你可以使用dapSharedKeymaps = true来设置以下共享键位绑定：

在录制外，addBreakPoint映射到dap.toggle_breakpoint()。在录制过程中，它会添加一个宏断点。
如果至少存在一个DAP断点，playMacro会映射到dap.continue()。如果没有DAP断点，则会播放当前的宏槽。

请注意，这个功能是实验性的，因为nvim-dap的相关API是非公开的，可能会在没有弃用通知的情况下被更改。

延迟加载插件

nvim-recorder最好在startStopRecording和playMacro的映射上延迟加载。然而，将状态栏组件添加到lualine会导致插件在你开始或播放录制之前加载。

为避免这种情况，状态栏组件需要只在插件的config中加载。这种方法的缺点是，在你开始或播放录制之前不会显示任何组件（不过当你设置clear = true时可以完全忽略这一点）。

尽管如此，这个插件相当轻量（约400行代码），所以不延迟加载它应该不会有太大影响。

-- 使用lazy.nvim的最小延迟加载配置
{
	"chrisgrieser/nvim-recorder",
	dependencies = "rcarriga/nvim-notify",
	keys = {
		-- 这些必须与下面映射配置中的键匹配
		{ "q", desc = " 开始录制" },
		{ "Q", desc = " 播放录制" },
	},
	config = function()
		require("recorder").setup({
			mapping = {
				startStopRecording = "q",
				playMacro = "Q",
			},
		})

			local lualineZ = require("lualine").get_config().sections.lualine_z or {}
			local lualineY = require("lualine").get_config().sections.lualine_y or {}
			table.insert(lualineZ, { require("recorder").recordingStatus })
			table.insert(lualineY, { require("recorder").displaySlots })

			require("lualine").setup {
				tabline = {
					lualine_y = lualineY,
					lualine_z = lualineZ,
				},
			}
	end,
},