aboutsummaryrefslogtreecommitdiff
path: root/docs/zh-cn/configurator_default_keymaps.md
diff options
context:
space:
mode:
Diffstat (limited to 'docs/zh-cn/configurator_default_keymaps.md')
-rw-r--r--docs/zh-cn/configurator_default_keymaps.md198
1 files changed, 198 insertions, 0 deletions
diff --git a/docs/zh-cn/configurator_default_keymaps.md b/docs/zh-cn/configurator_default_keymaps.md
new file mode 100644
index 000000000..135029b7e
--- /dev/null
+++ b/docs/zh-cn/configurator_default_keymaps.md
@@ -0,0 +1,198 @@
1# 向QMK配置器中添加默认键映射 :id=adding-default-keymaps
2
3<!---
4 original document: 0.15.12:docs/configurator_default_keymaps.md
5 git diff 0.15.12 HEAD -- docs/configurator_default_keymaps.md | cat
6-->
7
8本章节描述了如何向QMK配置器中添加一款键盘的默认键映射
9
10
11## 技术信息 :id=technical-information
12
13QMK配置器使用JSON作为键映射的本地文件格式。我们尽力确保其行为与在 `qmk_firmware` 中 执行 `make <keyboard>:default` 时一致。
14
15该目录下的键映射需要定义四个键值对：
16
17* `keyboard` (字符串)
18 * 键盘名称，与执行 `make` 进行编译时使用的一致（如 `make 1upkeyboards/1up60rgb:default`）。
19* `keymap` (字符串)
20 * 应设置为 `default`.
21* `layout` (字符串)
22 * 默认键映射应使用的配列宏定义。
23* `layers` (数组)
24 * 键映射数据。此键下的每行元素对应一个层定义，层定义中包含该层的键码组成信息。
25
26额外地，大部分键映射中还有一个 `commit` 项，该项并不是QMK配置器后端服务API所需，而是用于告知配置器维护者这份JSON键映射数据来源于代码库中的哪个版本的键映射。该值为 `qmk_firmware` 代码库中最后一次修改键盘默认 `keymap.c` 文件提交的commit的SHA标记。该SHA值的获取方式是拉取[`qmk/qmk_firmware` 库的 `master`分支](https://github.com/qmk/qmk_firmware/tree/master/)后，执行 `git log -1 --pretty=oneline -- keyboards/<keyboard>/keymaps/default/keymap.c`（若键盘有什么问题且存在 `keymap.json` 文件，则用之作为替代），执行结果应类似于：
27
28```
29f14629ed1cd7c7ec9089604d64f29a99981558e8 Remove/migrate action_get_macro()s from default keymaps (#5625)
30```
31
32本例中，`f14629ed1cd7c7ec9089604d64f29a99981558e8` 即应为 `commit` 的值。
33
34
35## 示例 :id=example
36
37若某人想添加H87a Hineybush键盘的默认键映射方案，应到 `qmk_firmware` 下H87a的默认键映射下执行上述 `git log` 命令：
38
39```
40user ~/qmk_firmware (master)
41$ git log -1 --pretty=oneline master -- keyboards/hineybush/h87a/keymaps/default/keymap.c
42ef8878fba5d3786e3f9c66436da63a560cd36ac9 Hineybush h87a lock indicators (#8237)
43```
44
45在我们获取了commit哈希值后，还需要键映射定义（为加强可读性进行了编辑处理）：
46
47```c
48...
49#include QMK_KEYBOARD_H
50
51const uint16_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] = {
52
53 [0] = LAYOUT_all(
54 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_PSCR, KC_SLCK, KC_PAUS,
55 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_BSPC, KC_BSPC, KC_INS, KC_HOME, KC_PGUP,
56 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_DEL, KC_END, KC_PGDN,
57 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,
58 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_RSFT, KC_TRNS, KC_UP,
59 KC_LCTL, KC_LGUI, KC_LALT, KC_SPC, KC_RALT, MO(1), KC_RGUI, KC_RCTL, KC_LEFT, KC_DOWN, KC_RGHT),
60
61 [1] = LAYOUT_all(
62 KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, RGB_TOG, RGB_MOD, RGB_HUD, RGB_HUI, RGB_SAD, RGB_SAI, RGB_VAD, RGB_VAI, BL_TOGG, BL_DEC, BL_INC,
63 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_VOLU,
64 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_MPLY, KC_MNXT, KC_VOLD,
65 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,
66 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,
67 KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS),
68
69};
70```
71
72默认键映射使用了 `LAYOUT_all` 宏，最后其会成为 `layout` 项的值。编译为QMK配置器的JSON键映射数据后，输出文件应为：
73
74```json
75{
76 "keyboard": "hineybush/h87a",
77 "keymap": "default",
78 "commit": "ef8878fba5d3786e3f9c66436da63a560cd36ac9",
79 "layout": "LAYOUT_all",
80 "layers": [
81 [
82 "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_PSCR", "KC_SLCK", "KC_PAUS",
83 "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_BSPC", "KC_BSPC", "KC_INS", "KC_HOME", "KC_PGUP",
84 "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_DEL", "KC_END", "KC_PGDN",
85 "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",
86 "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_RSFT", "KC_TRNS", "KC_UP",
87 "KC_LCTL", "KC_LGUI", "KC_LALT", "KC_SPC", "KC_RALT", "MO(1)", "KC_RGUI", "KC_RCTL", "KC_LEFT", "KC_DOWN", "KC_RGHT"
88 ],
89 [
90 "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "RGB_TOG", "RGB_MOD", "RGB_HUD", "RGB_HUI", "RGB_SAD", "RGB_SAI", "RGB_VAD", "RGB_VAI", "BL_TOGG", "BL_DEC", "BL_INC",
91 "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_VOLU",
92 "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_MPLY", "KC_MNXT", "KC_VOLD",
93 "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",
94 "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",
95 "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS"
96 ]
97 ]
98}
99```
100
101`layers` 数组中的空白区域不影响键映射功能，仅为了方便阅读。
102
103
104## 附加说明 :id=caveats
105
106### 层定义只能通过序号进行引用 :id=layer-references
107
108QMK中常见的一种做法是通过一系列 `#define` 或 `enum` 类型声明来对层定义进行命名：
109
110```c
111enum layer_names {
112 _BASE,
113 _MEDIA,
114 _FN
115};
116```
117
118对于C代码来讲可行，但对于配置器来讲，你*必须*使用层序号 - 上例中的`MO(_FN)` 应使用 `MO(2)`。
119
120### 不支持任何形式的定制化代码 :id=custom-code
121
122需要在 keymap.c 文件中添加函数代码的功能，如Tap Dance或是Unicode，都*完全*无法在配置器中构建。即便是在 `qmk_firmware` 代码库中在键盘定义中设置了 `TAP_DANCE_ENABLE = yes`，也只会导致*任何*固件构建在配置器中行不通。这是由API及JSON格式的键映射数据同时造成的限制。
123
124### 对自定义键码的不完全支持 :id=custom-keycodes
125
126仅有一个方案可以支持自定义键码：若自定义键码的逻辑实现是在 qmk_firmware 下的键盘定义中完成的，而非在键映射中，那么这个键码*可以*在配置器中使用且*可以*编译运行。（因此，）相对于在 `keymap.c` 中使用如下代码段：
127
128```c
129enum custom_keycodes {
130 MACRO_1 = SAFE_RANGE,
131 MACRO_2,
132 MACRO_3
133};
134...
135bool process_record_user(uint16_t keycode, keyrecord_t *record) {
136 switch(keycode) {
137 case MACRO_1:
138 if (record->event.pressed) {
139 SEND_STRING("This is macro #1.");
140 }
141 return false;
142 case MACRO_2:
143 if (record->event.pressed) {
144 SEND_STRING("This is macro #2.");
145 }
146 return false;
147 case MACRO_3:
148 if (record->event.pressed) {
149 SEND_STRING("This is macro #3.");
150 }
151 return false;
152 }
153 return true;
154};
155```
156
157... 请将键码的 `enum` 定义块添加到键盘的头文件（`<keyboard.h>`）中，例如（留意 `enum` 在这里命名为 `keyboard_keycodes`）：
158
159```c
160enum keyboard_keycodes {
161 MACRO_1 = SAFE_RANGE,
162 MACRO_2,
163 MACRO_3,
164 NEW_SAFE_RANGE // 重要!
165};
166```
167
168... 之后在 `<keyboard>.c` 中的 `process_record_kb()` 代码逻辑应为：
169
170```c
171bool process_record_kb(uint16_t keycode, keyrecord_t *record) {
172 switch(keycode) {
173 case MACRO_1:
174 if (record->event.pressed) {
175 SEND_STRING("This is macro #1.");
176 }
177 return false;
178 case MACRO_2:
179 if (record->event.pressed) {
180 SEND_STRING("This is macro #2.");
181 }
182 return false;
183 case MACRO_3:
184 if (record->event.pressed) {
185 SEND_STRING("This is macro #3.");
186 }
187 return false;
188 }
189 return process_record_user(keycode, record);
190};
191```
192
193注意最后的 `process_record_user()` 调用，若用户需要添加自定义键码到键映射中，须使用 `NEW_SAFE_RANGE` 替代 `SAFE_RANGE`，而其定义来自于上面键盘层定义中。
194
195
196## 更多资料 :id=additional-reading
197
198为了让QMK配置器支持你的键盘，你的键盘定义必须存在于 `qmk_firmware` 代码库的 `master` 分支中。相关操作指引，请参见[在QMK配置器中支持你的键盘](zh-cn/reference_configurator_support.md).
generated by cgit v1.2.3 (git 2.25.1) at 2025-11-30 08:11:58 +0000