企业官网建设流程全解析

QMK 键盘矩阵图（Matrix Diagram）完全解读：以 LSJ Ares 60% 键盘为例

【免费下载链接】qmk_firmwareOpen-source keyboard firmware for Atmel AVR and Arm USB families项目地址: https://gitcode.com/GitHub_Trending/qm/qmk_firmware

本文以 QMK 固件仓库中 LSJ Ares 键盘的 矩阵图文档 为核心，系统讲解 QMK 中 matrix diagram 的作用、阅读方法与实战价值。你将学会如何把一张 ASCII 矩阵图与 keyboard.json 中的矩阵引脚、布局坐标一一对应，理解 2u Backspace、ISO Enter、Tsangan/WKL/HHKB 等配列在矩阵中的实现方式，并能将这套方法论复用到自己的键盘开发中。

什么是 QMK 矩阵图

QMK 的键盘目录中，很多键盘会附带一个matrix_diagram.md文件。它用纯 ASCII 字符绘制了一张"物理配列（physical layout）→ 电气矩阵（electrical matrix）"的对照图，直观回答两个问题：

• 键盘上每一个物理键位对应矩阵的哪一行哪一列；
• 大键（空格、Shift、Enter、Backspace 等）在矩阵中如何复用单个坐标。

LSJ Ares 是一块 60% 布局的 PCB，其矩阵为5 行 × 15 列，对应 keyboard.json 中的定义：

"matrix_pins": { "cols": ["A0", "A1", "A2", "A3", "A4", "A5", "A6", "A7", "C7", "C6", "C5", "C4", "C3", "C2", "D7"], "rows": ["B0", "B1", "B2", "B3", "B4"] }, "diode_direction": "COL2ROW"

即 5 条行线（B0–B4）、15 条列线（A0–A7、C7–C2、D7），二极管方向为 COL2ROW。矩阵图坐标中的第一个数字代表行（row），第二个字母代表列（col），例如4E表示 row 4、col 14（十六进制 E）。

完整矩阵图：LSJ Ares 的物理配列到矩阵映射

下面这段来自 matrix_diagram.md 的 ASCII 图完整覆盖了 Ares 支持的所有配列形态：

┌───────┐ 2u Backspace │4E │ └───────┘ ┌───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┐ │40 │41 │42 │43 │44 │45 │46 │47 │48 │49 │4A │4B │4C │4D │4E │ ├───┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴───┤ ┌─────┐ │30 │31 │32 │33 │34 │35 │36 │37 │38 │39 │3A │3B │3C │3D │ │ │ ├─────┴┬──┴┬──┴┬──┴┬──┴┬──┴┬──┴┬──┴┬──┴┬──┴┬──┴┬──┴┬──┴─────┤ ┌──┴┐2D │ ISO Enter │20 │21 │22 │23 │24 │25 │26 │27 │28 │29 │2A │2B │2D │ │2C │ │ ├────┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴────┬───┤ └───┴────┘ │10 │11 │12 │13 │14 │15 │16 │17 │18 │19 │1A │1B │1C │1D │ ├────┼───┴┬──┴─┬─┴───┴───┴───┴───┴───┴──┬┴───┼───┴┬────┬┴───┤ │00 │01 │02 │06 │0A │0B │0C │0D │ └────┴────┴────┴────────────────────────┴────┴────┴────┴────┘ ┌────────┐ ┌──────────┐ │10 │ 2.25u LShift 2.75u RShift │1C │ └────────┘ └──────────┘ ┌─────┬───┬─────┬───────────────────────────┬─────┬───┬─────┐ │00 │01 │02 │06 │0B │0C │0D │ Tsangan/WKL/HHKB └─────┴───┴─────┴───────────────────────────┴─────┴───┴─────┘ ┌─────┬───┬─────┬───────────────────────┬─────┬───┬───┬─────┐ │00 │01 │02 │06 │0A │0B │0C │0D │ True HHKB └─────┴───┴─────┴───────────────────────┴─────┴───┴───┴─────┘

这张图实际包含四层信息，下面逐一拆解。

主配列区：五行十五列的键位分布

图的主区域（上方 5 行）展示的是全尺寸标准 60% 配列的矩阵位置：

• 第 0 行（物理最上方，矩阵 row 4）：14 个 1u 键（40–4D）+ 一个可选的 2u Backspace（4E）。注意4D与4E是两个独立的矩阵坐标，分别对应 ANSI 配列中的\键位和 split backspace 时的第二个退格键；
• 第 1 行（row 3）：30为 1.5u Tab，31–3C为字母区，3D为 1.5u 反斜杠；
• 第 2 行（row 2）：20为 1.75u Caps Lock，21–2B为字母/符号区，右侧额外画出ISO Enter区域：2D为主 Enter（2.25u），2C为 ISO 配列特有的短反斜杠键（位于 Enter 下方、高度 2u）；
• 第 3 行（row 1）：10为 2.25u 左 Shift，1C为 2.75u 右 Shift，1D为 ANSI 配列的可选额外键（对应 split right shift）；
• 第 4 行（row 0）：00、01、02为 1.25u 的左修饰键（Ctrl / GUI / Alt），06为 6.25u 空格，0A–0D为右侧修饰键与菜单键。

这些坐标与 keyboard.json 中LAYOUT_all的matrix: [row, col]字段完全一致，例如：

{"matrix": [4, 14], "x": 14, "y": 0} // 对应图中的 4E，2u Backspace {"matrix": [0, 6], "x": 3.75, "y": 4, "w": 6.25} // 对应图中的 06，6.25u 空格

矩阵图中不出现任何"行号跳跃"：5 个物理行依次使用矩阵 row 4、3、2、1、0，这是因为 keyboard.json 中rows数组的顺序是["B0", "B1", "B2", "B3", "B4"]，row 0（B0）位于矩阵图最下方（空格行）。矩阵行号与物理行位置没有必然对应关系，完全取决于 PCB 布线——这正是矩阵图存在的意义。

特殊键位的独立图示

主图下方用三张"局部图"标注了三个需要说明的键区：

1. 2.25u 左 Shift / 2.75u 右 Shift：10和1C两个坐标分别承载大 Shift，1D是 split right shift 时才使用的额外 1u 键；
2. 2u Backspace：4E单独画出，说明该 PCB 支持标准 1u 反斜杠 + 2u Backspace 的组合；
3. ISO Enter 区域：2C（短\，高 2u）与2D（2.25u Enter）组合，说明 PCB 同时兼容 ANSI 与 ISO 两种回车形态。

底部行三种配列形态

图的最下方三行展示了底部修饰键的三种典型组合，它们共享同一组矩阵坐标（row 0），区别仅在物理键帽宽度：

• 标准 60% 底部行：1.25u × 4（左）+ 6.25u 空格 + 1.25u × 4（右），即00 01 02 | 06 | 0A 0B 0C 0D；
• Tsangan / WKL / HHKB 底部行：1.5u + 1u + 1.5u（左）+ 7u 空格 + 1.5u + 1u + 1.5u（右），坐标变为00 01 02 | 06 | 0B 0C 0D——此时0A位被 7u 空格吞并；
• True HHKB 底部行：1.5u + 1.5u（左）+ 7u 空格 + 1.5u + 1u + 1.5u（右），坐标为00 01 02 | 06 | 0A 0B 0C 0D的变体，左区仅两个键位。

可以看到：无论物理键帽怎么换，电气矩阵坐标都不变。改变配列只是改变键盘映射（keymap）中对每个矩阵坐标的按键定义，这正是 QMK 把"矩阵"与"布局"解耦的设计哲学，相关背景可进一步阅读 docs/how_a_matrix_works.md 与 docs/feature_layouts.md。

矩阵图与 keyboard.json 的对应验证

矩阵图不是孤立的说明图，它与 keyboard.json 中的layouts定义严格互相对应。以LAYOUT_60_ansi_tsangan_split_bs_rshift为例，其底部行定义如下：

{"matrix": [0, 0], "x": 0, "y": 4, "w": 1.5}, {"matrix": [0, 1], "x": 1.5, "y": 4}, {"matrix": [0, 2], "x": 2.5, "y": 4, "w": 1.5}, {"matrix": [0, 6], "x": 4, "y": 4, "w": 7}, {"matrix": [0, 11], "x": 11, "y": 4, "w": 1.5}, {"matrix": [0, 12], "x": 12.5,"y": 4}, {"matrix": [0, 13], "x": 13.5,"y": 4, "w": 1.5}

与图中 "Tsangan/WKL/HHKB" 行的00 01 02 | 06 | 0B 0C 0D完全吻合：x、w字段精确描述了 1.5u / 1u / 1.5u 与 7u 空格的几何宽度。同理，LAYOUT_60_hhkb底部行省略了0A（True HHKB 形态下该坐标不参与底部行），与图中 "True HHKB" 行一致。

通过 keyboard.json 还可以反推出矩阵图的更多工程背景：

• "bootmagic": {"matrix": [4, 0]}：bootmagic 触发键为 row 4、col 0，正是矩阵图左上角的40（默认键位为 Escape），对应 readme.md 中"按住左上角键（通常映射为 Escape）插入 USB 进入刷写模式"的说明；
• "layout_aliases"将LAYOUT与LAYOUT_60_tsangan_hhkb分别指向LAYOUT_all与LAYOUT_60_ansi_tsangan_split_bs_rshift，说明默认键位（default/keymap.c 中使用的LAYOUT_all）面向最全的矩阵坐标集合；
• "community_layouts"列出了 60_ansi、60_iso、60_hhkb、60_wkl、60_tsangan 等 13 种通用配列名称，它们与 layouts 目录中的社区布局定义对应，使 Ares 可以复用 QMK 的通用布局体系（见 docs/feature_layouts.md）。

矩阵图与默认键位的联动：从图到实际按键

默认键位 使用LAYOUT_all定义了两层映射，其行顺序与矩阵图完全一致：

[_MA] = LAYOUT_all( KC_ESC, 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_BSLS, KC_BSPC, 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_CAPS, KC_A, KC_S, KC_D, KC_F, KC_G, KC_H, KC_J, KC_K, KC_L, KC_SCLN, KC_QUOT, KC_BSLS, 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_RSFT, MO(_FN), KC_LCTL, KC_LGUI, KC_LALT, KC_SPC, KC_RALT, KC_RGUI, KC_APP, KC_RCTL ),

注意第三行的KC_BSLS, KC_ENT对应矩阵图第 2 行末端的2D（ANSI 配列下的回车）与2C（ISO 短\位）——LAYOUT_all把这些坐标全部纳入，因此同一固件在 ANSI 与 ISO 配列下都能工作。第二层_FN则在最右上角定义了QK_BOOT（4E之后的4D位置），以及UG_NEXT、BL_TOGG等灯效与背光控制。

阅读技巧：矩阵图决定"有哪些坐标"，keymap 决定"每个坐标是什么键"。当你为 Ares 编写新键位时，先对照矩阵图确认目标物理键位对应的坐标，再在LAYOUT_*宏中按坐标顺序填入键值即可。

实战：构建与刷写 Ares 固件

矩阵图本身不参与编译，但理解矩阵与配列是正确构建的前提。按 readme.md 的说明，在完成 QMK 构建环境配置后：

# 构建默认键位固件 make ares:default # 构建并刷写 make ares:default:flash

刷写时按住矩阵图左上角的40（默认 Escape）插入 USB 即可进入 bootloader（keyboard.json 中bootmagic.matrix为[4, 0]，bootloader 为 bootloadhid）。

如何为自定义键盘编写矩阵图

如果你正在为一块新的 60% PCB 开发 QMK 支持，matrix_diagram.md提供了可复用的模板方法论：

1. 先列矩阵规模：从 keyboard.json 的matrix_pins出发，确认行数、列数，Ares 为 5×15；
2. 按物理行绘制键位：每个键位用行号+列号标注（行、列均用十六进制，列超过 9 后记作 A、B、C、D…），Ares 图中第 0 行的40…4E就是 row 4 的 15 个坐标；
3. 单独标出大键与可选键：2u Backspace、ISO Enter、split shift、split backspace 等"一个物理位置可能放多种键帽"的场景必须单独画图说明，如 Ares 图中的4E、2C/2D、1D；
4. 为每种底部行画一行：Tsangan / WKL / HHKB 等底部行变体虽然共享矩阵坐标，但键帽宽度不同，需要像原图那样分行展示w（宽度）信息；
5. 与layouts定义互检：图中每个坐标都应在 keyboard.json 的某个layouts条目中以matrix: [r, c]出现，反之亦然，避免出现"图中没有但布局里多出来"的死坐标。

总结

keyboards/ares/matrix_diagram.md虽然只是一张 ASCII 图，但它完整承载了 LSJ Ares 的矩阵—配列映射关系：5×15 矩阵坐标、2u Backspace、ISO Enter、三种底部行形态，以及与 keyboard.json、默认键位 的一一对应。对开发者而言，这张图既是编写/审查键位文件的速查表，也是理解 QMK"矩阵与布局解耦"思想的最佳入门案例——掌握了它，你就掌握了 QMK 中任何一张 matrix diagram 的读法。

【免费下载链接】qmk_firmwareOpen-source keyboard firmware for Atmel AVR and Arm USB families项目地址: https://gitcode.com/GitHub_Trending/qm/qmk_firmware