基于错误驱动的翻译模板自动获取 QMK键盘制作官方文档 翻译 第三部分 配置

这真是一种傻瓜式的教学。文笔很详细，就个人而言。

翻译/排版/制作：AIALRA

原始来源：docs.qmk.fm

*未经作者许可请勿商业化

配置

概述

QMK 配置器

QMK 配置概览：

QMK Configurator()是一个在线用户图形界面，可以生成QMK固件的十六进制文件。

QMK Configurator 与 Chrome 或 Firefox 浏览器的兼容性*好。

观看此视频教程 ()。很多人发现这个视频的内容足以让他们开始编写自己的键盘。

*注意：来自其他工具（例如 KLE 键盘布局编辑器）的文件会使键盘固件与 QMK 配置器不兼容。不要尝试加载或导入它们。QMK Configurator 是一个完全不同的工具。

请一步一步按照本教程进行操作：#/configurator_step_by_step

QMK 配置器：分步教程

本页面介绍了在 QMK Configurator 中构建固件的步骤。

·第一步：选择键盘

单击下拉框并选择要为其创建键映射的键盘。

*如果您的键盘有多个版本，请确保选择正确的一个。

我重复一遍，因为这很重要：

*确保您选择正确的版本！

如果你买的键盘的促销有说明是QMK驱动的，但是版本不在列表中，很可能是开发者还没拿到，或者我们还没有机会合并。如果没有活动的 Pull Request 弹出窗口来申诉该请求，请在 qmk_firmware() 上提交此问题以请求对该型号键盘的支持。一般来说，键盘厂商在自己的GitHub账号中也有QMK供电的键盘，请仔细查看。

· 第 2 步：选择您的键盘布局

选择*能代表您要创建的键映射的布局。某些键盘没有足够的布局或尚未定义正确的布局。将来，他们将得到支持。

有时，没有一种布局可以支持您想要的配置。在这种情况下，选择 LAYOUT_all。

· 第 3 步：命名您的键盘映射

随意调用此键盘映射。

如果您在编译过程中遇到问题，您可能需要更改此名称，因为它的名称可能已经存在于 QMK 固件 repo（报告）中。

第 4 步：定义键映射

可以通过以下三种方法之一进行键码输入：

1、拖放

2、点击布局上的空白处，然后点击你想要的键码

3、点击布局上的空白处，然后按下键盘上的物理键

您可以将鼠标指针悬停在某个键上，简要介绍将告诉您该键代码的作用。详细说明请参考：

基本键码参考：#/keycodes_basic

高级键码参考：#/feature_advanced_keycodes

*如果您选择的布局与您的物理按键不匹配，请将未使用的按键留空。如果您不确定使用哪个键，例如，您有一个退格键，但 LAYOUT_all 中有两个键，那么在两个位置放置相同的退格键代码。

第 5 步：保存键映射以备将来更改

当您对键盘映射感到满意或想稍后处理它时，请按导出键盘映射按钮。它会将您的键映射保存到您的计算机。然后，您可以在将来通过按“导入键盘映射”按钮加载此 .json 文件。

*注意：这与任何其他工具使用的 .json 文件类型不同。如果你尝试在这些工具中使用它基于错误驱动的翻译模板自动获取，或者在这些工具中使用 .json 和 QMK 配置器，你会遇到问题。

第六步：编译固件文件

按绿色编译按钮。

编译完成后，您将可以按下绿色的下载固件按钮。

下一步：刷新您的键盘固件

请参考如何刷固件：#/newbs_flashing

配置故障排除

我的 .json 文件不起作用

如果 .json 文件是使用 QMK 配置器生成的，那么您可能遇到了错误。qmk_configurator() 中提到了此错误的解决方案。

如果它不是错误，您可以查看是否错过了顶部的粗体提示：不要使用其他 .json 文件

我的布局中有多余的空间吗？我该怎么办？

如果您指的是带有三个空格键的位置，*佳做法是用空格条形码填充它们。退格键和 Shift 键也可以做同样的事情。

关键代码是什么？

请参阅：

基本键码参考：#/keycodes_basic

高级键码参考：#/feature_advanced_keycodes

编译无法进行

请仔细检查密钥图的其他层，以确保没有乱序的密钥。

问题和缺陷

我们始终接受所有客户请求和错误报告。请将它们提交到 qmk_configurator()

QMK API（Application Programming Interface，应用程序编程接口）

如果你不明白这个，你可以跳过它

概述

QMK API

QMK API 提供了异步 API。Web 和 GUI 工具可以使用此 API 为 QMK 支持的任何键盘编译任何键映射。常规键映射模板支持所有不需要支持C语言的QMK键值代码。键盘维护者可以提供自己的自定义模板来启用更多功能。

应用程序开发人员

如果你是一个应用开发者，打算在你的应用中使用这个 API，请参考这篇文章：#/api_docs。

键盘维护员

如果你想在 QMK 编译器 API 中增强你的键盘支持，请参考这篇文章：#/reference_configurator_support。

后端开发人员

如果您对 API 本身感兴趣，您应该从设置开发环境开始。请参考以下两篇文章。

设置开发环境：#/api_development_environment

HackingonAPI：#/api_development_overview

API基本信息

QMK API

本页面介绍如何使用 QMK API。如果您是应用程序开发人员，则可以使用此 API 为任何 QMK 键盘编译固件。

概述

此服务是用于编译自定义键映射的异步 API。可以发布一些JSON（JavaScript Object Notation，一种基于JavaScript语言的轻量级数据交换格式）到API中，定期查看状态。固件编译完成后，可以下载固件和源代码（如果需要）

JSON 负载（有效负载）的示例：

{

“键盘”：“线索板/66/rev2”，

"keymap": "my_awesome_keymap",

"layout": "LAYOUT_all",

“层”：[

["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_RALT","KC_RCTL","MO(1)","KC_LEFT","KC_DOWN","KC_RIGHT"],"KC_RALT","KC_RCTL"," MO(1)","KC_LEFT","KC_DOWN","KC_RIGHT"],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_RALT","KC_RCTL","MO(1)","KC_LEFT","KC_DOWN","KC_RIGHT"],"KC_RALT","KC_RCTL","MO(1)","KC_LEFT","KC_DOWN","KC_RIGHT"],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_RALT","KC_RCTL","MO(1)","KC_LEFT","KC_DOWN","KC_RIGHT"],"KC_RALT","KC_RCTL","MO(1)","KC_LEFT","KC_DOWN","KC_RIGHT"],,"KC_SPC","KC_SPC","KC_HENK","KC_RALT","KC_RCTL","MO(1)","KC_LEFT","KC_DOWN","KC_RIGHT"],"KC_RALT","KC_RCTL ","MO(1)","KC_LEFT","KC_DOWN","KC_RIGHT"],"KC_RALT","KC_RCTL","MO(1)","KC_LEFT","KC_DOWN" ,"KC_RIGHT"],,"KC_SPC","KC_SPC","KC_HENK","KC_RALT","KC_RCTL","MO(1)","KC_LEFT","KC_DOWN","KC_RIGHT"],"KC_RALT","KC_RCTL ","MO(1)","KC_LEFT","KC_DOWN","KC_RIGHT"],"KC_RALT","KC_RCTL","MO(1)","KC_LEFT","KC_DOWN" ,"KC_RIGHT"],"KC_DOWN","KC_RIGHT"],"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_P "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_TRNSTR","KK_C_NS", 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_PGUP","KC_TRNS","KC_TRNS","KC_TRNS" ,"KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNSTR","KK_C_NS",","MO(1)","KC_LEFT","KC_PGDN","KC_RGHT"],KC_TRNS","KC_TRNS","KC_TRNS","KC_PGUP","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS" "KC_TRNS","KC_TRNSTR","KK_C_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","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_TRNSTR","KK_C_NS", 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"]KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS", "KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNSTR","KC_TRNS",","KC_TRNS","KC_TRNS","MO(1)","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_TRNSTR","KK_C_NS",","KC_TRNS","KC_TRNS","MO(1)","KC_TRNS" ,"KC_TRNS","KC_TRNS"]," ,"KC_TRNS","KC_TRNS","MO(1)","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 的文件中：

$ curl -H "Content-Type: application/json" -X POST -d "$(

{

“入队”：真的，

"job_id": "ea1514b3-bdfc-4a7b-9b5c-08752684f7f6"

}

检查状态

提交您的键盘映射后，您可以使用简单的 HTTP GET 调用来检查状态是否正确：

例如：

$卷曲

{

"created_at": "2017 年 8 月 19 日星期六 21:39:12 GMT",

"enqueued_at": "2017 年 8 月 19 日星期六 21:39:12 GMT",

"id": "f5f9b992-73b4-479b-8236-df1deb37c163",

“状态”：“正在运行”，

“结果”：空

}

这向我们表明项目文件已通过队列并正在运行。在这种情况下有 5 种可能的状态：

·Failure：部分编译服务损坏。

·Complete：编译完成，需要查看结果才能看到结果。

· Queue：键映射正在等待编译服务器可用。

· 运行：编某在进行中，应该很快就会完成。

·未知：发生了严重错误，您应该尝试提交此错误。

检查完成结果

编译作业完成后，需要检查“result”键。这个键的值是一个包含几个键信息的散列：

Firmware_binary_url：可以刷固件的URL列表（URL Uniform Resoure Locator：Uniform Resoure Locator，url为批量）

compware_keymap_url：keymap.c 的 URL 列表

firmware_source_url：完整固件源代码的 URL 列表

output:: 本次编译作业的stdout和stderr，这里可以查看发生的错误

键盘支持

在 QMK 配置器中支持您的键盘

本页面介绍如何正确启用 QMK 配置器支持您的键盘。

配置器如何与键盘兼容

要了解配置器如何与键盘兼容，您必须首先了解布局宏。下面是一个示例，以帮助您更好地理解。在这个例子中，我们将想象一个 17 键的 numpad（数字键）PCB，我们将其称为 numpad。

|--------------------|

|NLk| / | * |-|

|-----+---+---+----|

| 7|8 |9| + |

|-----+---+---+----|

|4 | 5 | 6| |

|-----+---+---+----|

|1 |2 |3 |Ent|

|-----------+---| |

|0 |。| |

|---------------------|

有关宏的更多信息，请参阅 QMK：矩阵扫描 (#/understanding_qmk?id=matrix-scanning) 和

QMK：矩阵到物理布局映射（#/understanding_qmk?id=matrix-to-physical-layout-map）。

配置器的 API 从 qmk_firmware/keyboards//.h 中读取键盘 .h 文件。对于我们的小键盘，这个文件就是qmk_firmware/keyboard/numpad/numpad.h，内容如下：

#pragma once

#定义布局（

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

#定义布局（

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 列。我们的key位置被命名为k并且从0开始计数。名字本身其实并不重要，只要顶部（从key map中接收key code）匹配底部（它指定每个key在矩阵中的位置） ）。

为了以类似于物理键盘的方式显示键盘，我们需要构建一个 JSON 文件，该文件告诉配置器如何将键的物理位置和大小绑定到键矩阵。

构建 JSON 文件

要构建JSON文件，*简单的方法是在键盘布局编辑器（“KLE”）中构建布局，从中我们将原始数据输入到QMK工具中，该工具将数据转换为配置器以读取和使用JSON . 因为KLE打开时会显示默认的小键盘布局，所以我们只需要删除默认的布局，剩下的就可以使用了。

一旦布局符合您的要求，请移至 KLE 的 Raw Data 选项卡并复制内容如下（以上面的小垫为例）：

[“数字键盘（的第一个键”，”/”，”*”，”-”]，

["7 Home","8 ↑","9 PgUp",{h:2},"+"],

["4 ←","5","6 →"],

["1 End","2 ↓","3 PgDn",{h:2},"Enter"],

[{w:2},"0 Ins",". Del"]

要将这些数据转换为我们的 JSON，请转到 QMKKLE-JSON() 转换器基于错误驱动的翻译模板自动获取，将原始数据粘贴到输入区域，然后单击转换按钮。稍后，我们的 JSON 数据将出现在输出区域中。将内容复制到一个新的文本文档中，将文档命名为info.json，*后保存在numpad.h所在的文件夹中。

您可以使用 keyboard_name 来设置键盘的名称。出于说明目的，我们将把每个关键标准放在自己的行上。这只是为了使文件更易于阅读，不会影响配置器的功能。

例如：

{

"keyboard_name": "数字键盘",

"网址": "",

"维护者": "qmk",

“标签”：{

“form_factor”：“小键盘”

},

“宽度”：4，

“高度”：5，

“布局”：{

“布局”： {

“布局”： [

{"label":"Num Lock", "x":0, "y":0},

{“标签”：“/”，“x”：1，“y”：0}，

{“标签”：“*”，“x”：2，“y”：0}，

{“标签”：“-”，“x”：3，“y”：0}，

{“标签”：“7”，“x”：0，“y”：1}，

{“标签”：“8”，“x”：1，“y”：1}，

{“标签”：“9”，“x”：2，“y”：1}，

{“标签”：“+”，“x”：3，“y”：1，“h”：2}，

{“标签”：“4”，“x”：0，“y”：2}，

{“标签”：“5”，“x”：1，“y”：2}，

{“标签”：“6”，“x”：2，“y”：2}，

{“标签”：“1”，“x”：0，“y”：3}，

{“标签”：“2”，“x”：1，“y”：3}，

{“标签”：“3”，“x”：2，“y”：3}，

{“标签”：“输入”，“x”：3，“y”：3，“h”：2}，

{“标签”：“0”，“x”：0，“y”：4，“w”：2}，

{“标签”：“。”，“x”：2，“y”：4}

]

}

}

}

布局（层）包含表示键盘物理布局的数据。其中一部分是 LAYOUT，它需要与我们在 numpad.h 中的布局宏的名称相匹配。LAYOUT 本身有一个名为 layout 的部分，它使键盘上的每个物理键都包含一个 JSON 对象，格式如下（示例同上）：

密钥的名称。不显示在配置器中。

|

| 关键点的 X 轴位置，以关键点为单位

| | 键盘的左边缘。

| |

| | 键的 Y 轴位置，以键单位从

| | | 键盘的顶部（朝后）边缘。

↓ ↓ ↓

{"label":"Num Lock", "x":0, "y":0},

一些对象还包含“w”和“h”键，分别代表键的宽度和高度。

有关 json 文件的更多信息，请参阅下面的这篇文章。(#/Reference_info_json)

如何对配置器的键进行编程

配置器的 API 使用布局宏和我们提供的 JSON 文件来创建可视键盘。这个键盘中的每个视觉对象都按顺序绑定到一个特定的键，例如：

如图所示

当用户在配置器中选择左上键并为其分配Num Lock时，配置器将构建一个以KC_NLCK为第一个键的键映射文件，依此类推。事实上，键盘构造并没有使用标签键；它们仅在用户调试信息或识别特定键时用作 info.json 文件。

问题和风险

目前，配置器不支持旋钮键或非矩形键形状，例如 ISO 配置中的 Enter。另外，偏离垂直线的键——比如TKC1800布局上的方向键就是一个典型的例子——如果这些信息的提供者不调整它们，会使KLE-to-JSON转换器无法理解信息.json 文件。

*TCK1800 视频参考和数据文件：

解决方案

非矩形键

对于ISO配置输入key，QMK的自定义程序会将其显示为一个宽1.25u、高2u的矩形key，其右边缘与字母数字键块的右边缘对齐。

* 60% 的带键盘的标准 ISO 布局，由 QMK 配置器提供。

垂直偏移键

对于有垂直偏移的key，请在没有偏移时按原样放在KLE中，然后根据需要编辑转换后的JSON文件中的y值

*键盘布局编辑器中显示的 1800 布局键盘没有应用于箭头键的垂直偏移。

*一个 Unix 差异文件，向我们展示了键盘 JSON 文件中箭头键所需的垂直偏移更改。