当前位置：首页 > ds >正文

QMK配置器详解：QMK Configurator

ds 2025/5/9 7:42:59

QMK配置器详解：QMK Configurator

一、QMK配置器简介

在这里插入图片描述

QMK Configurator是一个在线图形用户界面工具，专为生成QMK固件（.hex或.bin文件）而设计。作为键盘爱好者的得力助手，它让你无需编程知识就能定制自己的键盘布局。

注意事项：QMK Configurator无法为与设计不符的控制器生成固件，例如无法为专为Pro Micro设计的键盘板使用RP2040控制器生成固件。这种情况需要使用命令行转换器。

💡 最佳兼容性：QMK Configurator在Chrome或Firefox浏览器中表现最佳。

⚠️ 警告：来自其他工具（如键盘布局编辑器KLE或kbfirmware）的文件与QMK Configurator不兼容。请勿尝试加载或导入它们，这些工具与QMK Configurator的工作原理完全不同。

二、QMK配置器使用步骤详解

1. 选择键盘型号

首先，点击下拉框并选择你要为其创建键盘映射的键盘。

提示：如果你的键盘有多个版本，确保选择正确的版本！我再强调一次，因为这非常重要 - 确保选择正确的版本！

如果你的键盘号称支持QMK但未在列表中找到，可能是因为开发人员尚未添加支持，或者我们还没来得及合并它。此时可以联系制造商，鼓励他们添加支持。

2. 选择键盘布局

选择最能代表你要创建的键盘映射的布局。某些键盘可能尚未定义足够的布局或正确的布局，这些将在未来得到支持。

注意：如果没有完全匹配你的构建的布局，请选择LAYOUT_all选项。

3. 命名你的键盘映射

给你的键盘映射取一个名字，随你喜欢。

提示：如果编译时遇到问题，可能值得更改此名称，因为它可能已存在于QMK固件存储库中。

4. 定义键盘映射

你可以通过以下三种方式输入键码：

拖放操作
点击布局上的空白处，然后点击所需的键码
点击布局上的空白处，然后按键盘上的物理键

技巧：将鼠标悬停在一个键上，会显示这个键码的简短说明。如需更详细的描述，请参考基本键码参考和高级键码参考文档。

如果你选择的布局与物理构建不完全匹配，请将未使用的键留空。对于不确定使用哪个键的情况（例如有一个退格键但布局中有2个位置），可以在两个位置放置相同的键码。

5. 保存键盘映射以备将来修改

当你对键盘映射满意或想稍后继续完善时，点击Download this QMK Keymap JSON File按钮，将键盘映射保存到电脑上。以后可以通过点击Upload a QMK Keymap JSON File按钮加载这个.json文件。

⚠️ 警告：这种.json文件类型与kbfirmware.com或其他工具使用的文件不同。请勿尝试在这些工具中使用QMK Configurator生成的JSON，或将其他工具的JSON用于QMK Configurator，这将导致问题。

6. 编译固件文件

点击绿色的Compile按钮开始编译过程。编译完成后，你将能够点击绿色的Download Firmware按钮下载固件。

7. 刷写键盘

请参考烧录固件文档了解如何将固件刷写到你的键盘上。

三、配置器故障排除

我的.json文件无法正常工作

如果该.json文件是使用QMK Configurator生成的，那么恭喜你发现了一个bug！请在qmk_configurator提交问题报告。

如果不是…你是怎么错过顶部的粗体大消息说不要使用其他.json文件的？

我的布局中有多余的空间？

如果你发现布局中有额外的空间（例如空格键有三个位置），最佳做法是用相同的键填充它们。退格键和Shift键也可以执行相同的操作。

键码的功能是什么？

请参阅：

基本键码参考
高级键码参考

编译失败

请仔细检查键盘映射的所有层，确保没有随机键或错误配置。

问题和错误报告

我们始终欢迎功能请求和错误报告。请在qmk_configurator提交它们。

四、QMK编译器和API工作原理

QMK编译器实际上是执行以下流程来处理keymap.json文件：

签出请求的代码分支
运行qmk compile keymap.json命令
将生成的源代码和二进制文件上传到Digital Ocean Spaces存储服务

当用户下载其源代码或二进制文件时，API会将他们重定向到经过身份验证的Spaces下载URL。

QMK API提供了一个异步API接口，Web和GUI工具可以使用它为任何QMK支持的键盘编译任意键盘映射。该API支持所有QMK键盘代码，无需支持C代码的常用键盘映射模板。键盘维护者还可以提供自己的自定义模板来启用更多功能。

五、如何在QMK Configurator中支持你的键盘

Configurator如何理解键盘

要理解Configurator如何识别键盘，首先必须了解布局宏(layout macros)。以一个17键数字键盘PCB为例：

|---------------|
|NLk| / | * | - |
|---+---+---+---|
|7  |8  |9  | + |
|---+---+---|   |
|4  |5  |6  |   |
|---+---+---+---|
|1  |2  |3  |Ent|
|-------+---|   |
|0      | . |   |
|---------------|

Configurator的API会从qmk_firmware/keyboards/<keyboard>/<keyboard>.h中读取键盘文件。对于我们的数字键盘例子，文件内容会类似：

#pragma once#define LAYOUT( \k00, k01, k02, k03, \k10, k11, k12, k13, \k20, k21, k22,      \k30, k31, k32, k33, \k40,      k42       \) { \{ k00, k01,   k02, k03   }, \{ k10, k11,   k12, k13   }, \{ k20, k21,   k22, KC_NO }, \{ k30, k31,   k32, k33   }, \{ k40, KC_NO, k42, KC_NO }  \
}

QMK使用KC_NO来指定开关矩阵中没有开关的位置。有时也会使用XXX或_______作为简写，以提高可读性。

构建JSON配置文件

要让Configurator正确显示你的键盘，需要创建一个JSON文件，告诉Configurator如何将键的物理位置和大小与开关矩阵关联起来。创建这个文件的最简单方法是：

在键盘布局编辑器(KLE)中构建布局
复制KLE中的Raw Data标签内容
使用QMK KLE-JSON转换器将原始数据转换为JSON
将生成的内容保存为info.json，放在和<keyboard>.h同一文件夹中

一个典型的info.json文件结构如下：

{"keyboard_name": "Numpad","url": "","maintainer": "qmk","tags": {"form_factor": "numpad"},"layouts": {"LAYOUT": {"layout": [{"label":"Num Lock", "x":0, "y":0},{"label":"/", "x":1, "y":0},{"label":"*", "x":2, "y":0},{"label":"-", "x":3, "y":0},{"label":"7", "x":0, "y":1},{"label":"8", "x":1, "y":1},{"label":"9", "x":2, "y":1},{"label":"+", "x":3, "y":1, "h":2},{"label":"4", "x":0, "y":2},{"label":"5", "x":1, "y":2},{"label":"6", "x":2, "y":2},{"label":"1", "x":0, "y":3},{"label":"2", "x":1, "y":3},{"label":"3", "x":2, "y":3},{"label":"Enter", "x":3, "y":3, "h":2},{"label":"0", "x":0, "y":4, "w":2},{"label":".", "x":2, "y":4}]}}
}

Configurator如何对键进行编程

Configurator使用布局宏和JSON文件创建键盘的可视化表示，将每个视觉对象按顺序绑定到特定键。例如，对于我们的数字键盘：

布局宏中的键	使用的JSON对象
k00	{“label”:“Num Lock”, “x”:0, “y”:0}
k01	{“label”:“/”, “x”:1, “y”:0}
k02	{“label”:“*”, “x”:2, “y”:0}
…	…

当用户在Configurator中选择左上角的键并为其分配KC_NUM(Num Lock)时，Configurator会将其作为键盘映射中的第一个键保存，依此类推。