MarkText 键盘快捷键完全指南:keybindings.json 自定义配置与跨平台默认键位
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 类中,整个流程大致如下:
- 选择平台默认表:
getDefaultKeybindings()根据isOsx/isLinux返回 keybindingsDarwin.ts、keybindingsLinux.ts 或 keybindingsWindows.ts 中的默认映射表(Map<string, string>)。 - 读取用户配置:
_loadUserKeybindingsFromDisk()读取keybindings.json并做JSON.parse;解析失败或内容不是对象时返回null,此时控制台会记录Invalid keybinding configuration警告并跳过用户配置。 - 逐条校验:只有
id存在于默认表中的条目才会被采纳;值必须是字符串;非空值必须通过isValidElectronAccelerator校验(该函数来自@hfelix/electron-localshortcut依赖),否则打印[WARNING] "..." is not a valid accelerator.并丢弃。 - 重复检测:先检测用户条目之间是否重复(
isEqualAccelerator会在忽略大小写、归一化command/option等写法后比较);再检测用户键位与默认键位的冲突——若用户把某个组合键绑定给了命令 A,则默认占用该组合键的命令 B 会被自动「解除绑定」(置为空字符串),保证一个组合键全局唯一。 - 生效:
registerEditorKeyHandlers遍历最终键表,通过electronLocalshortcut.register(win, accelerator, callback)注册到窗口,回调统一执行commandManager.execute(id, win)。 - 热重载:
_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),但若你使用死键布局(如德文键盘),不要将默认快捷键绑定到可通过^或`产生的字符键上,这些键无法被可靠翻译。