MarkText 键盘快捷键完全指南:keybindings.json 自定义配置与跨平台默认键位

原创2026-09-17 21:22:381,845 阅读
文章标签:桌面应用富文本跨平台

MarkText 键盘快捷键完全指南:keybindings.json 自定义配置与跨平台默认键位

MarkText 是一款跨平台(Linux、macOS、Windows)的开源 Markdown 编辑器,其全部菜单与编辑操作都绑定了一组可覆盖的键盘快捷键。本文以官方 KEYBINDINGS.md 文档为骨架,完整讲解自定义快捷键配置文件 keybindings.json 的存放位置、JSON 格式、可用修饰键与按键、空字符串解除绑定的用法,并结合仓库源码(shortcutHandler.ts、keybindingsLinux.ts 等)剖析快捷键的加载、校验与热重载原理,最后附上 macOS / Linux / Windows 三套完整默认键位表。读完本文,你将能够熟练地为任意命令重设快捷键、解除冲突绑定,并理解 MarkText 快捷键系统的底层工作机制。

一、配置文件 keybindings.json:位置与格式

所有键位都可以通过 keybindings.json 文件覆盖。该文件位于 MarkText 的应用数据目录中,具体路径因操作系统而异(详见 APPLICATION_DATA_DIRECTORY.md):

操作系统 应用数据目录
Windows %APPDATA%\marktext
Linux $XDG_CONFIG_HOME/marktext 或 ~/.config/marktext
macOS ~/Library/Application Support/marktext

当启用便携模式(Portable Mode)时,目录位置变为 --user-data-dir 参数指定的目录,或 marktext-user-data 目录。

从源码看,配置文件的确切路径由应用环境拼接而成:shortcutHandler.ts 中 this.configPath = path.join(userDataPath, 'keybindings.json'),即 keybindings.json 直接位于上述应用数据目录根下。

文件内容是一组 JSON 的 id / accelerator 键值对,id 对应某条命令的标识符,accelerator 是对应的快捷键组合。官方示例:

{
  "file.save": "CmdOrCtrl+Shift+S",
  "file.save-as": "CmdOrCtrl+S"
}

上例把「保存」改为 CmdOrCtrl+Shift+S,把「另存为」改为 CmdOrCtrl+S,与默认键位正好互换。CmdOrCtrl 是一个跨平台伪修饰键:在 macOS 上解析为 Cmd(Command),在 Linux / Windows 上解析为 Ctrl——这正是 common/keybinding/index.ts 中 _normalizeAccelerator 所做的工作:它将 commandorcontrol / cmdorctrl 按平台归一化为 cmd 或 ctrl,同时把 command→cmd、option→alt、control→ctrl、meta→cmd。

二、可用修饰键(Modifiers)

自定义快捷键时可使用的修饰键如下:

  • Cmd —— 仅 macOS(Command 键)
  • Option —— 仅 macOS(Option 键)
  • Ctrl —— 通用(Control 键)
  • Shift —— 通用(Shift 键)
  • Alt —— 通用,在 macOS 上等同于 Option

注意:请勿绑定 AltGr,应改用 Ctrl+Alt 组合(例如默认导出 PDF 的 Ctrl+Alt+E)。AltGr 在不同键盘布局下行为不可控,用 Ctrl+Alt 才能得到确定性的组合键。

三、可用按键(Keys)

accelerator 中可用的主键包括:

  • 数字键 0-9、字母键 A-Z、功能键 F1-F24,以及 /、# 等标点符号
  • Plus、Space、Tab、Backspace、Delete、Insert、Return/Enter、Esc、Home、End、PrintScreen
  • 方向键 Up、Down、Left、Right
  • PageUp、PageDown
  • 空字符串 "" —— 用于**解除(unset)**某个快捷键

其中空字符串这一项非常实用:如果你不喜欢某个默认快捷键(例如 Linux 上 view.reload-images 默认占用了 F5),可以这样取消绑定:

{
  "view.reload-images": ""
}

源码对此有对应处理:在 _loadLocalKeybindings 中,当值为空字符串时会执行「解除绑定」,该命令将不再响应任何快捷键;而在 registerEditorKeyHandlers 注册监听时,accelerator.length > 1 的空值会被跳过,不会注册。

四、加载与校验:快捷键如何生效

理解自定义键位如何生效,有助于排查「为什么我的键位没生效」。核心逻辑全部集中在 shortcutHandler.ts 的 Keybindings 类中,整个流程大致如下:

  1. 选择平台默认表:getDefaultKeybindings() 根据 isOsx / isLinux 返回 keybindingsDarwin.ts、keybindingsLinux.ts 或 keybindingsWindows.ts 中的默认映射表(Map<string, string>)。
  2. 读取用户配置:_loadUserKeybindingsFromDisk() 读取 keybindings.json 并做 JSON.parse;解析失败或内容不是对象时返回 null,此时控制台会记录 Invalid keybinding configuration 警告并跳过用户配置。
  3. 逐条校验:只有 id 存在于默认表中的条目才会被采纳;值必须是字符串;非空值必须通过 isValidElectronAccelerator 校验(该函数来自 @hfelix/electron-localshortcut 依赖),否则打印 [WARNING] "..." is not a valid accelerator. 并丢弃。
  4. 重复检测:先检测用户条目之间是否重复(isEqualAccelerator 会在忽略大小写、归一化 command/option 等写法后比较);再检测用户键位与默认键位的冲突——若用户把某个组合键绑定给了命令 A,则默认占用该组合键的命令 B 会被自动「解除绑定」(置为空字符串),保证一个组合键全局唯一。
  5. 生效:registerEditorKeyHandlers 遍历最终键表,通过 electronLocalshortcut.register(win, accelerator, callback) 注册到窗口,回调统一执行 commandManager.execute(id, win)。
  6. 热重载:_reloadKeybindings(windows) 会先注销旧的加速键,再重建键表并重新注册——也就是说,在设置界面修改键位后无需重启应用即可生效。

此外,MarkText 对非美式键盘做了专门适配:_prepareKeyMapper 使用 native-keymap 读取当前键盘布局(getCurrentKeyboardLayout / getKeyMap)并注入 electronLocalshortcut.setKeyboardLayout,且通过 keyboard/index.ts 中的 keyboardLayoutMonitor 监听布局切换(防抖 150ms 后重新加载布局信息),避免快捷键在德文、法文等键盘布局下错位。主进程还注册了 mt::keybinding-get-keyboard-info 与调试用 mt::keybinding-debug-dump-keyboard-info 两个 IPC 通道(后者会把键盘信息 JSON 写入临时目录并打开),便于排查按键映射问题。

从源码结构看,Linux 默认键位表(keybindingsLinux.ts)中还带有几条针对性的注释:避免在 Linux 上使用 Ctrl+Alt / Alt 快捷键(Ubuntu 系桌面已保留这些系统快捷键,见 GH#2370);不要使用 Ctrl+Shift+U(与 IBus 的 Unicode 输入冲突);默认快捷键不要绑定到可通过 ^ 或 ` 生成的字符上(如 ^、`、"、~),因为某些键盘上它们是无键死键,无法可靠翻译。如果你在 Ubuntu 系发行版上发现键位行为异常,这些注释是很好的排查线索。

五、macOS 默认键位表

以下为 macOS 完整默认键位(详见 KEYBINDINGS_OSX.md,源码定义于 keybindingsDarwin.ts)。表中 Command 即 Cmd,Option 即 Alt。

MarkText 菜单

Id 默认键位 说明
mt.hide Command+H 隐藏 MarkText
mt.hide-others Command+Option+H 隐藏除 MarkText 外的其他窗口
file.preferences Command+, 打开设置窗口
file.quit Command+Q 退出 MarkText

File 菜单

Id 默认键位 说明
file.new-window Command+N 新建窗口
file.new-tab Command+T 新建标签页
file.open-file Command+O 打开 Markdown 文件
file.open-folder Command+Shift+O 打开文件夹
file.save Command+S 保存
file.save-as Command+Shift+S 另存为……
file.export-file.pdf Ctrl+Alt+E 导出为 PDF
file.move-file - 移动当前文件到其他位置
file.rename-file - 重命名当前文件
file.print - 打印当前标签页
file.close-tab Command+W 关闭标签页
file.close-window Command+Shift+W 关闭窗口

Edit 菜单

Id 默认键位 说明
edit.undo Command+Z 撤销
edit.redo Command+Shift+Z 重做
edit.cut Command+X 剪切
edit.copy Command+C 复制
edit.paste Command+V 粘贴
edit.copy-as-rich Command+Shift+C 以 Markdown 富文本复制
edit.copy-as-html - 以 HTML 复制
edit.paste-as-plaintext Command+Shift+V 以纯文本粘贴
edit.select-all Command+A 全选
edit.duplicate Command+Option+P 复制当前段落
edit.create-paragraph Command+Shift+N 在当前段落后新建段落
edit.delete-paragraph Command+Shift+D 删除当前段落
edit.find Command+F 在文档中查找
edit.find-next Cmd+G 继续查找下一个
edit.find-previous Shift+Cmd+G 继续查找上一个
edit.replace Command+Option+F 查找并替换
edit.find-in-folder Command+Shift+F 在已打开文件夹中查找包含关键字的文件
edit.screenshot Command+Option+A 截图

Paragraph 菜单

Id 默认键位 说明
paragraph.heading-1 ~ paragraph.heading-6 Command+1 ~ Command+6 设为标题 1~6 级
paragraph.upgrade-heading Command+Plus 标题升级
paragraph.degrade-heading Command+- 标题降级
paragraph.table Command+Shift+T 插入表格
paragraph.code-fence Command+Option+C 插入代码块
paragraph.quote-block Command+Option+Q 插入引用块
paragraph.math-formula Command+Option+M 插入数学公式块
paragraph.html-block Command+Option+J 插入 HTML 块
paragraph.order-list Command+Option+O 插入有序列表
paragraph.bullet-list Command+Option+U 插入无序列表
paragraph.task-list Command+Option+X 插入任务列表
paragraph.loose-list-item Command+Option+L 将列表项转为宽松列表项
paragraph.paragraph Command+0 标题转为普通段落
paragraph.horizontal-line Command+Option+- 插入水平线
paragraph.front-matter Command+Option+Y 插入 YAML frontmatter 块

Format 菜单

Id 默认键位 说明
format.strong Command+B 加粗
format.emphasis Command+I 斜体
format.underline Command+U 下划线
format.superscript - 上标
format.subscript - 下标
format.highlight Command+Shift+H 用 <mark> 标签高亮选中文本
format.inline-code Command+`` `` 行内代码
format.inline-math Command+Shift+M 行内公式
format.strike Command+D 删除线
format.hyperlink Command+L 插入超链接
format.image Command+Shift+I 插入图片
format.clear-format Command+Shift+R 清除选中文本的格式

Window 菜单

Id 默认键位 说明
window.minimize Command+M 最小化窗口
window.toggle-always-on-top - 切换窗口置顶
window.zoomIn - 放大
window.zoomOut - 缩小
window.toggle-full-screen Ctrl+Command+F 切换全屏

View 菜单

Id 默认键位 说明
view.command-palette Command+Shift+P 切换命令面板
view.source-code-mode Command+Option+S 切换到源码模式
view.typewriter-mode Command+Option+T 启用打字机模式
view.focus-mode Command+Shift+J 启用专注模式
view.toggle-sidebar Command+J 切换侧边栏
view.toggle-tabbar Command+Option+B 切换标签栏
view.toggle-toc Command+K 切换目录
view.toggle-dev-tools Command+Option+I 切换开发者工具(仅调试模式)
view.dev-reload Command+Option+R 重载窗口(仅调试模式)
view.reload-images Command+R 重载图片

Tabs 与 Misc

Id 默认键位 说明
tabs.cycle-forward Ctrl+Tab 循环切换标签页
tabs.cycle-backward Ctrl+Shift+Tab 反向循环切换标签页
tabs.switchToleft Command+PageUp 切换到左侧标签页
tabs.switchToright Command+PageDown 切换到右侧标签页
tabs.switchTofirst ~ tabs.switchTofourth Ctrl+1 ~ Ctrl+4 切换到第 1~4 个标签页
tabs.switchTofifth ~ tabs.switchToninth Ctrl+5 ~ Ctrl+9 切换到第 5~9 个标签页
tabs.switchTotenth Ctrl+0 切换到第 10 个标签页
file.quick-open Command+P 打开快速打开对话框

六、Linux 与 Windows 默认键位表

Linux 与 Windows 的大多数默认键位一致,均以 Ctrl 为主修饰键(详见 KEYBINDINGS_LINUX.md 与 KEYBINDINGS_WINDOWS.md,源码定义于 keybindingsLinux.ts 与 keybindingsWindows.ts)。差异部分已用 加粗 标注。

File 菜单

Id Linux / Windows 默认键位 说明
file.new-window Ctrl+N 新建窗口
file.new-tab Ctrl+T 新建标签页
file.open-file Ctrl+O 打开 Markdown 文件
file.open-folder Ctrl+Shift+O 打开文件夹
file.save Ctrl+S 保存
file.save-as Ctrl+Shift+S 另存为……
file.export-file.pdf Ctrl+Alt+E 导出为 PDF
file.move-file - 移动当前文件
file.rename-file - 重命名当前文件
file.print - 打印当前标签页
file.preferences Ctrl+, 打开设置窗口
file.close-tab Ctrl+W 关闭标签页
file.close-window Ctrl+Shift+W 关闭窗口
file.quit Ctrl+Q 退出 MarkText

Edit 菜单

Id Linux / Windows 默认键位 说明
edit.undo Ctrl+Z 撤销
edit.redo Ctrl+Shift+Z 重做
edit.cut Ctrl+X 剪切
edit.copy Ctrl+C 复制
edit.paste Ctrl+V 粘贴
edit.copy-as-rich Ctrl+Shift+C 以 Markdown 富文本复制
edit.copy-as-html - 以 HTML 复制
edit.paste-as-plaintext Ctrl+Shift+V 以纯文本粘贴
edit.select-all Ctrl+A 全选
edit.duplicate Linux:Ctrl+Shift+E;Windows:Ctrl+Alt+P 复制当前段落
edit.create-paragraph Ctrl+Shift+N 在当前段落后新建段落
edit.delete-paragraph Ctrl+Shift+D 删除当前段落
edit.find Ctrl+F 在文档中查找
edit.find-next F3 继续查找下一个
edit.find-previous Shift+F3 继续查找上一个
edit.replace Ctrl+R 查找并替换
edit.find-in-folder Ctrl+Shift+F 在已打开文件夹中查找包含关键字的文件

Paragraph 菜单

Id Linux / Windows 默认键位 说明
paragraph.heading-1 ~ paragraph.heading-6 Ctrl+Shift+1 ~ Ctrl+Shift+6 设为标题 1~6 级
paragraph.upgrade-heading Ctrl+Plus 标题升级
paragraph.degrade-heading Ctrl+- 标题降级
paragraph.table Ctrl+Shift+T 插入表格
paragraph.code-fence Ctrl+Shift+K 插入代码块
paragraph.quote-block Ctrl+Shift+Q 插入引用块
paragraph.math-formula Linux:Ctrl+Alt+M;Windows:Ctrl+Alt+N 插入数学公式块
paragraph.html-block Ctrl+Alt+H 插入 HTML 块
paragraph.order-list Ctrl+G 插入有序列表
paragraph.bullet-list Ctrl+H 插入无序列表
paragraph.task-list Linux:Ctrl+Shift+X;Windows:Ctrl+Alt+X 插入任务列表
paragraph.loose-list-item Linux:Ctrl+Shift+L;Windows:Ctrl+Alt+L 列表项转为宽松列表项
paragraph.paragraph Ctrl+Shift+0 标题转为普通段落
paragraph.horizontal-line Linux:Ctrl+\_(即 Ctrl+Shift+-);Windows:Ctrl+Shift+U 插入水平线
paragraph.front-matter Linux:Ctrl+Shift+Y;Windows:Ctrl+Alt+Y 插入 YAML frontmatter 块

Format 菜单

Id Linux / Windows 默认键位 说明
format.strong Ctrl+B 加粗
format.emphasis Ctrl+I 斜体
format.underline Ctrl+U 下划线
format.superscript - 上标
format.subscript - 下标
format.highlight Ctrl+Shift+H 用 <mark> 标签高亮选中文本
format.inline-code Linux:Ctrl+Y;Windows:Ctrl+`` `` 行内代码
format.inline-math Ctrl+Shift+M 行内公式
format.strike Ctrl+D 删除线
format.hyperlink Ctrl+L 插入超链接
format.image Ctrl+Shift+I 插入图片
format.clear-format Ctrl+Shift+R 清除选中文本的格式

Window 菜单

Id Linux / Windows 默认键位 说明
window.minimize Ctrl+M 最小化窗口
window.toggle-always-on-top - 切换窗口置顶
window.zoomIn - 放大
window.zoomOut - 缩小
window.toggle-full-screen F11 切换全屏

View 菜单

Id Linux / Windows 默认键位 说明
view.command-palette Ctrl+Shift+P 切换命令面板
view.source-code-mode Ctrl+E 切换到源码模式
view.typewriter-mode Ctrl+Shift+G 启用打字机模式
view.focus-mode Ctrl+Shift+J 启用专注模式
view.toggle-sidebar Ctrl+J 切换侧边栏
view.toggle-tabbar Ctrl+Shift+B 切换标签栏
view.toggle-toc Ctrl+K 切换目录
view.toggle-dev-tools Ctrl+Alt+I 切换开发者工具(仅调试模式)
view.dev-reload Ctrl+F5 重载窗口(仅调试模式)
view.reload-images F5 重载图片

Tabs 与 Misc

Id Linux / Windows 默认键位 说明
tabs.cycle-forward Ctrl+Tab 循环切换标签页
tabs.cycle-backward Ctrl+Shift+Tab 反向循环切换标签页
tabs.switchToleft Ctrl+PageUp 切换到左侧标签页
tabs.switchToright Ctrl+PageDown 切换到右侧标签页
tabs.switchTofirst ~ tabs.switchTofourth Ctrl+1 ~ Ctrl+4 切换到第 1~4 个标签页
tabs.switchTofifth ~ tabs.switchToninth Ctrl+5 ~ Ctrl+9 切换到第 5~9 个标签页
tabs.switchTotenth Ctrl+0 切换到第 10 个标签页
file.quick-open Ctrl+P 打开快速打开对话框

说明:上述表格完整继承了官方文档的键位表。若你发现实际应用中的按键与表格不一致,可以对照仓库中的默认键位定义文件(keybindingsDarwin.ts、keybindingsLinux.ts、keybindingsWindows.ts),这些文件是快捷键真正注册时使用的数据源。另外,macOS 的 mt.hide、mt.hide-others、edit.screenshot 等条目在 Linux/Windows 键表中被定义为空字符串,表示默认不绑定。

七、实战示例与常见问题

1. 常用自定义示例

把「保存」与「另存为」对调(官方示例):

{
  "file.save": "CmdOrCtrl+Shift+S",
  "file.save-as": "CmdOrCtrl+S"
}

在 Linux/Windows 上把「查找替换」换成编辑器习惯的 Ctrl+H,并把被占用的「无序列表」换到 Ctrl+Alt+U:

{
  "edit.replace": "Ctrl+H",
  "paragraph.bullet-list": "Ctrl+Alt+U"
}

解除不想用的默认键(例如 Windows/Linux 下 F5 重载图片):

{
  "view.reload-images": ""
}

2. 常见问题排查

  • 键位没生效:确认 keybindings.json 放在正确目录(见第一节表格),且是合法 JSON;id 必须与键位表中的标识符完全一致(如 file.save,注意是点号分隔);非空键值必须是合法的 Electron accelerator 写法(如 CmdOrCtrl+Shift+S),否则会被校验逻辑丢弃并打印警告。
  • 组合键冲突:MarkText 会自动解除默认表中与用户新键位冲突的旧绑定,因此建议优先查看 keybindings.json 加载逻辑 了解冲突处理方式;若某个默认键突然失效,很可能就是你把它绑定给了别的命令。
  • Ubuntu 上 Ctrl+Alt 组合异常:Ubuntu 系桌面保留了部分 Ctrl+Alt 系统快捷键,尽量避免自定义此类组合。
  • 键盘布局不同导致的键位错乱:MarkText 内置了键盘布局感知(native-keymap),但若你使用死键布局(如德文键盘),不要将默认快捷键绑定到可通过 ^ 或 ` 产生的字符键上,这些键无法被可靠翻译。

八、延伸阅读

登录后查看全文
marktext