这真是愚蠢的教学。写得很详细。只是一个人
翻译/排版/制作：aialra
原始来源：docs.qmk.fm
*未经作者许可请勿商用
配置
概览
QMK配置器
QMK配置器对Chrome或火狐浏览器兼容性最好。
*注意:来自其他工具的文件，如键盘布局编辑器(KLE Keyboard Layout Editor)，这样会使键盘固件不兼容QMK配置器。不要尝试加载它们或者导入它们。QMK配置器是一个完全不同的工具。
QMK配置器:按步操作教程
本页面描述在QMK配置器中构建固件的步骤。
·第一步:选择键盘
单击下拉框并选择要为其创建键映射的键盘。
*如果你的键盘有几个版本，确保你选择了正确的那一个。
我再说一遍，因为这很重要:
*确保您选择了正确的版本!
·第二步:选择你的键盘布局
选择最能代表您想要创建的键映射的布局。有些键盘没有足够的布局或正确的布局尚未被定义。在未来，它们将会得到支持。
有时没有一个布局能够支持你想要的配列。在这种情况下，选择LAYOUT_all。
·第三步:命名你的键映射
随你怎么称呼这个键映射。
如果在编译时遇到问题，你可能需要更改这个名称，因为它这个名称可能已经存在于QMK固件repo（报告）中了。
·第四步:定义键映射
关键代码输入可以由下面的三种方法之一完成:
1、拖拽
2、点击布局上的空白点，然后点击你想要的键码
3、点击布局上的空白点，然后按键盘上的物理按键
你可以将鼠标指针悬停在一个键上，一个简短的简介会告诉你这个键码是做什么的。如需详细描述，请参阅:
*如果您选择的布局与您的物理按键不匹配，请将未使用的键留空。如果您不确定使用的是哪个键，例如，您有一个退格键，但LAYOUT_all中有两个键，那么在两个位置都放置相同的退格键的键码。
第五步:保存键映射以备将来更改
当您对您的键映射感到满意或希望稍后对其进行处理时，请按Export keymap按钮。它将保存您的键映射到您的计算机。然后，您可以在将来通过按Import Keymap按钮来加载这个.json文件。
*注意:这与 kbfirmware.com或其他任何工具使用的.json文件类型不同。如果您尝试在这些工具中使用它，或者在这些工具中使用带有QMK配置器的.json，您将会遇到问题。
第六步:编译固件文件
按下绿色的编译按钮。
编译完成后，您将能够按下绿色的下载固件按钮。
下一步:刷写你的键盘固件
配置故障排查
我的.json文件不工作
如果不是bug的问题的话，你看看是不是漏看了在顶部的粗体字的提示:不要使用其他.json文件
在我的布局中有额外的空间?我该怎么办?
如果你指的是有三个空格条的位置，最好的做法是用空格键码来填满它们。退格键和Shift键也可以这样做。
关键代码是什么?
请参阅:
编译不能进行
请仔细检查你的键图的其他层，确保没有乱序的键存在。
问题和缺陷
QMK API（Application Programming Interface，应用程序接口）
如果不懂这方面的可以跳过
概览
QMK API
QMK API提供了一个异步API, Web和GUI工具可以使用该API为QMK支持的任何键盘编译任意键映射。常规键映射模板支持所有不需要支持C语言的QMK键值代码。键盘维护人员可以提供他们自己的自定义模板来启用更多的功能。
应用程序开发者
键盘维护者
后台开发人员
如果您对API本身感兴趣，您应该从设置开发环境开始，请参阅下面两篇文章。
API必备资料
QMK API
本页面描述了QMK API的使用方式。如果您是一名应用程序开发人员，您可以使用此API为任何QMK键盘编译固件。
概述
此服务是用于编译自定义键映射的异步API。您可以向API发布一些JSON（JavaScript Object Notation 基于 JavaScript 语言的轻量级的数据交换格式），并定期检查状态，当固件完成编译时，您可以下载该固件和源代码(如果需要的话)
一个JSON 有效载荷（payload）的例子：
{
“keyboard”: “clueboard/66/rev2”,
“keymap”: “my_awesome_keymap”,
“layout”: “LAYOUT_all”,
“layers”: [
[“KC_GRV”,”KC_1″,”KC_2″,”KC_3″,”KC_4″,”KC_5″,”KC_6″,”KC_7″,”KC_8″,”KC_9″,”KC_0″,”KC_MINS”,”KC_EQL”,”KC_GRV”,”KC_BSPC”,”KC_PGUP”,”KC_TAB”,”KC_Q”,”KC_W”,”KC_E”,”KC_R”,”KC_T”,”KC_Y”,”KC_U”,”KC_I”,”KC_O”,”KC_P”,”KC_LBRC”,”KC_RBRC”,”KC_BSLS”,”KC_PGDN”,”KC_CAPS”,”KC_A”,”KC_S”,”KC_D”,”KC_F”,”KC_G”,”KC_H”,”KC_J”,”KC_K”,”KC_L”,”KC_SCLN”,”KC_QUOT”,”KC_NUHS”,”KC_ENT”,”KC_LSFT”,”KC_NUBS”,”KC_Z”,”KC_X”,”KC_C”,”KC_V”,”KC_B”,”KC_N”,”KC_M”,”KC_COMM”,”KC_DOT”,”KC_SLSH”,”KC_RO”,”KC_RSFT”,”KC_UP”,”KC_LCTL”,”KC_LGUI”,”KC_LALT”,”KC_MHEN”,”KC_SPC”,”KC_SPC”,”KC_HENK”,”KC_RALT”,”KC_RCTL”,”MO(1)”,”KC_LEFT”,”KC_DOWN”,”KC_RIGHT”],
[“KC_ESC”,”KC_F1″,”KC_F2″,”KC_F3″,”KC_F4″,”KC_F5″,”KC_F6″,”KC_F7″,”KC_F8″,”KC_F9″,”KC_F10″,”KC_F11″,”KC_F12″,”KC_TRNS”,”KC_DEL”,”BL_STEP”,”KC_TRNS”,”KC_TRNS”,”KC_TRNS”,”KC_TRNS”,”KC_TRNS”,”KC_TRNS”,”_______”,”KC_TRNS”,”KC_PSCR”,”KC_SLCK”,”KC_PAUS”,”KC_TRNS”,”KC_TRNS”,”KC_TRNS”,”KC_TRNS”,”KC_TRNS”,”KC_TRNS”,”MO(2)”,”KC_TRNS”,”KC_TRNS”,”KC_TRNS”,”KC_TRNS”,”KC_TRNS”,”KC_TRNS”,”KC_TRNS”,”KC_TRNS”,”KC_TRNS”,”KC_TRNS”,”KC_TRNS”,”KC_TRNS”,”KC_TRNS”,”KC_TRNS”,”KC_TRNS”,”KC_TRNS”,”KC_TRNS”,”KC_TRNS”,”KC_TRNS”,”KC_TRNS”,”KC_TRNS”,”KC_TRNS”,”KC_TRNS”,”KC_TRNS”,”KC_TRNS”,”KC_PGUP”,”KC_TRNS”,”KC_TRNS”,”KC_TRNS”,”KC_TRNS”,”KC_TRNS”,”KC_TRNS”,”KC_TRNS”,”KC_TRNS”,”KC_TRNS”,”MO(1)”,”KC_LEFT”,”KC_PGDN”,”KC_RGHT”],
[“KC_TRNS”,”KC_TRNS”,”KC_TRNS”,”KC_TRNS”,”KC_TRNS”,”KC_TRNS”,”KC_TRNS”,”KC_TRNS”,”KC_TRNS”,”KC_TRNS”,”KC_TRNS”,”KC_TRNS”,”KC_TRNS”,”KC_TRNS”,”KC_TRNS”,”KC_TRNS”,”KC_TRNS”,”KC_TRNS”,”KC_TRNS”,”KC_TRNS”,”RESET”,”KC_TRNS”,”KC_TRNS”,”KC_TRNS”,”KC_TRNS”,”KC_TRNS”,”KC_TRNS”,”KC_TRNS”,”KC_TRNS”,”KC_TRNS”,”KC_TRNS”,”KC_TRNS”,”KC_TRNS”,”MO(2)”,”KC_TRNS”,”KC_TRNS”,”KC_TRNS”,”KC_TRNS”,”KC_TRNS”,”KC_TRNS”,”KC_TRNS”,”KC_TRNS”,”KC_TRNS”,”KC_TRNS”,”KC_TRNS”,”KC_TRNS”,”KC_TRNS”,”KC_TRNS”,”KC_TRNS”,”KC_TRNS”,”KC_TRNS”,”KC_TRNS”,”KC_TRNS”,”KC_TRNS”,”KC_TRNS”,”KC_TRNS”,”KC_TRNS”,”KC_TRNS”,”KC_TRNS”,”KC_TRNS”,”KC_TRNS”,”KC_TRNS”,”KC_TRNS”,”KC_TRNS”,”KC_TRNS”,”KC_TRNS”,”KC_TRNS”,”KC_TRNS”,”KC_TRNS”,”MO(1)”,”KC_TRNS”,”KC_TRNS”,”KC_TRNS”]
]
}
如您所见，有效载荷描述了创建和生成键盘固件所需的的所有方面的信息。每一层配列都是与键盘布局宏相同长度的QMK键码列表。如果键盘支持多个布局宏，您可以指定使用哪个宏。
编译工程
要将键映射编译为固件，只需将JSON发布到/v1/compile端点。在下面的示例中，我们将JSON有效载荷放入名为json_data的文件中：
{
“enqueued”: true,
“job_id”: “ea1514b3-bdfc-4a7b-9b5c-08752684f7f6”
}
检查状态
提交你的键映射后，你可以使用一个简单的HTTP GET调用来检查状态是否正确:
例如：
{
“created_at”: “Sat, 19 Aug 2017 21:39:12 GMT”,
“enqueued_at”: “Sat, 19 Aug 2017 21:39:12 GMT”,
“id”: “f5f9b992-73b4-479b-8236-df1deb37c163”,
“status”: “running”,
“result”: null
}
这向我们显示工程文件已通过队列并正在运行。在这种情况下有5种可能的状态:
·失败:编译服务的某些地方损坏了。
·完成:编译完成，您应该检查result以查看结果。
·排队:键映射正在等待编译服务器可用。
·运行:编译正在进行中，应该很快就会完成。
·未知:一个严重的错误已经发生，你应该尝试去提交这个错误。
检查完成结果
编译作业完成后，您需要检查“result”这个键。这个键的值是一个散列，包含几个关键的信息:
·firmware_binary_url：可刷写固件的URLs列表( URL Uniform Resoure Locator:统一资源定位器，urls为批量)
compware_keymap_url: keymap.c的URLs列表
firmware_source_url：完整固件源代码的URLs列表
output:：这个编译作业的stdout和 stderr ，这里可以检查发生的错误
键盘支持
在QMK配置器内支持您的键盘
本页面介绍如何在QMK配置器中正确地使您的键盘被支持。
配置器是如何兼容键盘的
要了解配置器如何兼容键盘，首先你必须了解布局宏。下面是一个例子，来帮助你更好地理解。在这个例子中，我们将想象一个17键的numpad（数字键） PCB，我们将称之为numpad。
|——————–|
|NLk| / | * | – |
|—–+—+—+—-|
| 7 | 8 |9 | + |
|—–+—+—+—-|
|4 | 5 | 6 | |
|—–+—+—+—-|
|1 |2 |3 |Ent|
|———-+—| |
|0 | . | |
|———————|
配置器的API从qmk_firmware/keyboards/<keyboard>/<keyboard>.h中读取键盘的.h文件。对于我们的numpad，这个文件将是qmk_firmware/keyboard /numpad/numpad.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, ___或____的形式可以使这个值的可读性更强。这通常被定义在.h文件的开头:
例如：
#pragma once
#define XXX KC_NO
#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, XXX }, \
{ k30, k31, k32, k33 }, \
{ k40, XXX, k42, XXX } \
}
*这种方法常用于不同于键映射宏,通常使用XXXXXXX (7个大写的X) 来表示KC_NO和 _________(七个下划线)来表示KC_TRNS。
*为了防止用户混淆，最好使用KC_NO。
在这个例子中，布局宏告诉配置器，我们的键盘有17个键，按5行4列排列。我们的键位命名为k<row><column>，并从0开始计数。名称本身实际上并不重要，只要顶部部分(接收来自键映射的键码)与下半部分(指定每个键在矩阵中的位置)之间匹配就可以了。
要以类似于物理键盘的方式显示键盘，我们需要构建一个JSON文件，告诉配置器如何将键的物理位置和大小绑定到键位矩阵。
构建JSON文件
要构建JSON文件，最简单的方法是在键盘布局编辑器(“KLE”)中构建布局，我们将从中将原始数据输入QMK工具，该工具将该数据转换为可让配置器读取和使用的JSON。因为KLE打开时显示的是默认的numpad布局，我们只需要删除默认的布局，然后使用剩下的即可。
一旦布局符合你的要求，请移动到KLE的Raw Data tab，并复制内容如下（例子为上述小pad）：
[“Num Lock”,”/”,”*”,”-“],
[“7\nHome”,”8\n↑”,”9\nPgUp”,{h:2},”+”],
[“4\n←”,”5″,”6\n→”],
[“1\nEnd”,”2\n↓”,”3\nPgDn”,{h:2},”Enter”],
[{w:2},”0\nIns”,”.\nDel”]
你可以使用keyboard_name来设置键盘的名称。出于指令目的，我们将把每个键标准在它自己的行上。这只是为了使文件更易于阅读，并不影响配置器的功能。
例如：
{
“keyboard_name”: “Numpad”,
“url”: “”,
“maintainer”: “qmk”,
“tags”: {
“form_factor”: “numpad”
},
“width”: 4,
“height”: 5,
“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}
]
}
}
}
layouts（层）包含表示键盘物理布局的数据。它有一个部分是LAYOUT，它需要匹配我们在numpad.h中的布局宏的名称。LAYOUT本身有一个名为layout的部分，它使键盘上的每个物理键都包含一个JSON对象，格式如下（例子同上）:
The name of the key. Not displayed in the Configurator.
|
| The key’s X-axis location, in key units from the
| | keyboard’s left edge.
| |
| | The key’s Y-axis location, in key units from
| | | the keyboard’s top (rear-facing) edge.
↓ ↓ ↓
{“label”:”Num Lock”, “x”:0, “y”:0},
一些对象还含有“w”和“h”键，分别表示键的宽度和高度。
配置器如何编程键位
配置器的API使用布局宏和我们给它的JSON文件来创建一个可视化的键盘，这个键盘中每个可视化的对象都按顺序绑定到一个特定的键，例如:
当用户在配置器中选择左上脚的键并将Num Lock分配给它时，配置器将构建一个以KC_NLCK为第一个键的键映射文件，以此类推。实际上键盘构建并不使用标签键;它们仅供用户在调试信息时或识别特定键时作为info.json文件。
问题和风险
目前，配置器不支持旋钮按键或非矩形的键形状，如ISO配列的Enter。此外，那些偏移于垂直的行的键——比如TKC1800布局上的方向键就是一个典型的例子——如果此类信息的提供者没有调整它们的话，会使KLE-to-JSON转换器无法理解info.json文件。
*TCK1800视频参考以及资料文件：
解决方法
非矩形的键
对于ISO配列输入键，QMK的自定义程序会将其显示为一个矩形键，宽1.25u，高2u，并且使其右边缘与字母数字键块的右边缘对齐。
*标准ISO布局的60%配列键盘，由QMK配置器呈现。
垂直偏移的键
对于垂直偏移的键，请将它们放在KLE中，就像它们没有偏移时候的情况一样，然后根据需要在转换后的JSON文件中编辑y值
*在键盘布局编辑器中呈现的1800布局键盘，没有应用于方向键的垂直偏移量。
*一个Unix差异文件，为我们展示了在键盘的JSON文件中对箭头键进行所需垂直偏移量的更改。