企业官网建设流程全解析

QMK 矩阵图完全解读：CherryB.Studio CB87v2 的矩阵布局与多布局配置实战

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

本篇技术指南以 QMK Firmware 仓库中keyboards/cherrybstudio/cb87v2/matrix_diagram.md为骨架，结合该键盘的 keyboard.json 与默认 keymap.c，完整解读 CherryB.Studio CB87v2 这块可玩性极高的 TKL（TenKeyLess，无小键盘）PCB 的矩阵结构。读完本文，你将掌握如何读懂 QMK 矩阵图的行列编号、如何将矩阵坐标映射到物理按键与引脚、如何理解该 PCB 支持的 2u Backspace、ISO/BAE Enter、Split RShift、Tsangan/WKL 等布局变体，并能在自己的键位配置中正确引用这些坐标。

什么是矩阵图，为什么 CB87v2 需要它

机械键盘的 PCB 并不会为每个按键单独接一个 MCU 引脚，而是采用“矩阵扫描”的方式：行（Row）与列（Col）构成网格，每个按键位于某个行×列的交叉点。QMK 固件通过轮流驱动行列引脚来判断按键是否被按下。matrix_diagram.md正是用 ASCII 字符把整块 PCB 的矩阵网格“可视化”出来，让开发者一眼看清：

• 每个物理按键落在矩阵的哪个（行, 列）坐标上；
• 每个坐标对应的按键编号（如00、30、64）；
• 哪些按键是同一物理位置的“可选变体”（如双 Backspace、双 Enter、双 RShift、多段空格）。

CB87v2 的 readme 将其描述为 "An advance TKL PCB with many configurable layouts"（支持多种可配置布局的进阶 TKL PCB），这块 PCB 的矩阵图覆盖了从标准 ANSI/ISO 到 Tsangan/WKL、Split Space 等多种配列，是理解整个板子的第一手资料。

CB87v2 完整矩阵图

以下为 matrix_diagram.md 中的原始矩阵图（原样保留）：

┌───┐ ┌───┬───┬───┬───┐ ┌───┬───┬───┬───┐ ┌───┬───┬───┬───┐ ┌───┬───┬───┐ │00 │ │01 │02 │03 │04 │ │05 │06 │07 │08 │ │09 │10 │11 │12 │ │13 │14 │15 │ └───┘ └───┴───┴───┴───┘ └───┴───┴───┴───┘ └───┴───┴───┴───┘ └───┴───┴───┘ ┌───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┐ ┌───┬───┬───┐ ┌───────┐ │16 │17 │18 │19 │20 │21 │22 │23 │24 │25 │26 │27 │28 │29 │30 │ │31 │32 │33 │ │30 │ 2u Backspace ├───┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴───┤ ├───┼───┼───┤ └─┬─────┤ ┌─────┐ │34 │35 │36 │37 │38 │39 │40 │41 │42 │43 │44 │45 │46 │47 │ │48 │49 │50 │ │ │ │ │ ├─────┴┬──┴┬──┴┬──┴┬──┴┬──┴┬──┴┬──┴┬──┴┬──┴┬──┴┬──┴┬──┴─────┤ └───┴───┴───┘ ┌──┴┐64 │ ISO Enter ┌──┘64 │ BAE Enter │51 │52 │53 │54 │55 │56 │57 │58 │59 │60 │61 │62 │64 │ │63 │ │ │ │ ├────┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴────┬───┤ ┌───┐ ┌─┴─┬─┴────┤ └────────┘ │65 │66 │67 │68 │69 │70 │71 │72 │73 │74 │75 │76 │77 │78 │ │79 │ │77 │78 │ 1u/1.75u RShift ├────┼───┴┬──┴─┬─┴───┴──┬┴───┼───┴───┴──┬┴───┼───┴┬────┬┴───┤ ┌───┼───┼───┐ └───┴──────┘ │80 │81 │82 │83 │84 │85 │86 │87 │88 │89 │ │90 │91 │92 │ └────┴────┴────┴────────┴────┴──────────┴────┴────┴────┴────┘ └───┴───┴───┘ ┌────────┐ ┌──────────┐ │65 │ 2.25u LShift 2.75u RShift │78 │ └────────┘ └──────────┘ ┌────┬────┬────┬──────────┬────┬────────┬────┬────┬────┬────┐ │80 │81 │82 │83 │84 │85 │86 │87 │88 │89 │ └────┴────┴────┴──────────┴────┴────────┴────┴────┴────┴────┘ ┌────┬────┬────┬────────────────────────┬────┬────┬────┬────┐ │80 │81 │82 │84 │86 │87 │88 │89 │ Standard └────┴────┴────┴────────────────────────┴────┴────┴────┴────┘ ┌─────┬───┬─────┬───────────────────────────┬─────┬───┬─────┐ │80 │81 │82 │84 │87 │88 │89 │ Tsangan/WKL └─────┴───┴─────┴───────────────────────────┴─────┴───┴─────┘ ┌─────┬───┬─────┬──────────┬─────┬──────────┬─────┬───┬─────┐ │80 │81 │82 │83 │84 │85 │87 │88 │89 │ Tsangan/WKL Split Space └─────┴───┴─────┴──────────┴─────┴──────────┴─────┴───┴─────┘

整块 PCB 共使用 93 个矩阵位置，编号从00到92。

读懂矩阵编号：行×列 记法

矩阵图中的每个编号都是两位十进制数，第一位是矩阵行号（Row），第二位是矩阵列号（Col）：

• 00= 第 0 行、第 0 列，即 Esc 键；
• 09= 第 0 行、第 9 列，即 F9 键；
• 10= 第 1 行、第 0 列，即 F10 键（注意这里不是数字“十”，而是“1 行 0 列”）；
• 92= 第 9 行、第 2 列，即 →（右方向键）。

这个编号规则与 keyboard.json 中每个布局条目里的"matrix": [row, col]字段一一对应。例如LAYOUT_all中：

{"label": "Esc", "matrix": [0, 0], "x": 0, "y": 0}, {"label": "F10", "matrix": [1, 0], "x": 12, "y": 0}, {"label": "Backspace", "matrix": [3, 0], "x": 14, "y": 1.25, "w": 2}

分别对应图中的00、10和30（2u Backspace）。

矩阵坐标与物理按键对照

下面按物理区域，把矩阵图编号与 keyboard.json 中LAYOUT_all的定义逐一对照。

F 区与功能键（00–15）

注意 F1–F4、F5–F8、F9–F12 之间各有一个 1u 的间隔，这与 TKL 常见的分区 F 区一致；从编号看，F9 之后的 F10–F12 以及 Print Screen、Scroll Lock、Pause 已经“换行”到第 1 行（10–15），这正是矩阵编号与物理排列不一定逐格对齐的典型例子。

数字区与导航列（16–33）

其中29与30是两个 Backspace 位置：标准 2u Backspace 使用30（在LAYOUT_tkl_ansi中为"matrix": [3, 0], "w": 2），而Split Backspace 同时使用29+30各 1u（见LAYOUT_all中两个 Backspace 条目）。

字母区（34–64）

这里有两个关键的可配置点：

• 63（# 键）是 ISO 布局专用：仅在LAYOUT_tkl_iso*系列布局中出现（"label": "#", "matrix": [6, 3]），ANSI 布局中该位置不使用；
• 64是 Enter 键的共用矩阵位置：ISO 布局中它以 1.25u 出现（"w": 1.25，图注 "ISO Enter"），ANSI 布局中它以 2.25u 出现（图注 "BAE Enter"，即 Big Ass Enter 大回车）。

Shift 行与方向键（65–79）

图注给出了两个重要变体：

• 65= 2.25u 左 Shift：这是标准 ANSI 的宽度；ISO 布局中左 Shift 变为 1.25u，腾出66的位置给 ISO 专用的反斜杠键；
• 78= 2.75u 右 Shift（标准），而Split RShift 使用77（1.75u）+78（1u）（图注 "1u/1.75u RShift"）。对照LAYOUT_tkl_ansi_split_bs_rshift中可见"Shift", "matrix": [7, 7], "w": 1.75与"Shift", "matrix": [7, 8]（默认 1u）两条定义。

底部行与箭头区（80–92）

底部行是这张 PCB “可配置布局”最集中的区域，矩阵图底部专门用四行分别画出了LAYOUT_all完整底行、Standard、Tsangan/WKL、Tsangan/WKL Split Space 四种形态（详见下文）。

硬件矩阵：引脚与二极管方向

matrix_diagram.md只刻画了逻辑矩阵（行×列），真正的物理引脚定义在 keyboard.json 的matrix_pins中：

"matrix_pins": { "cols": ["D5", "D4", "D6", "D7", "B4", "B5", "F5", "C6", "C7", "F7"], "rows": ["B0", "B1", "B2", "B3", "B7", "D0", "D1", "D2", "D3", "F6"] }, "diode_direction": "COL2ROW"

CB87v2 使用10 行 × 10 列的矩阵（共 100 个潜在位置，实际使用 93 个），主控为 atmega32u4。矩阵坐标[r][c]对应rows[r]×cols[c]两个引脚，例如：

• Esc（00）→ 行引脚 B0 × 列引脚 D5；
• ← 方向键（90）→ 行引脚 F6 × 列引脚 D5；
• F10（10）→ 行引脚 B1 × 列引脚 D5；
• → 方向键（92）→ 行引脚 F6 × 列引脚 F7。

diode_direction: "COL2ROW"表示二极管方向为“列驱动、行读取”，即列线输出驱动信号、行线作为输入读取。扫描时 QMK 依次拉低每一列，再读取各行状态，从而确定被按下的键坐标；这也解释了为什么矩阵图里 10 列 × 10 行能覆盖 93 个键位——同一行列交叉点只对应一个物理键，而“可选变体”（如双 Backspace）共用同一坐标、通过不同布局宏引用。

一板多布局：矩阵图背后的可配置变体

keyboard.json 的community_layouts声明了 8 个社区布局，矩阵图正是这些布局在物理矩阵上的可视化：

此外LAYOUT_all覆盖了所有物理位置（含全部变体键位），是默认键位与自定义键位的“全集”入口。

Backspace：2u 与拆分

• 2u Backspace：只使用30，宽度 2u（图注 "2u Backspace"）；
• Split Backspace：29+30各 1u，两个键可分别编程。

Enter：ISO 与 BAE

• ISO Enter：63（#）+64（Enter 1.25u）；
• BAE（Big Ass Enter）：只用64，宽度 2.25u，63空缺。

右 Shift：2.75u 与 1.75u+1u 拆分

• 标准：78一个 2.75u 右 Shift；
• 拆分：77（1.75u）+78（1u），适合 7u 空格配列或 40% 用户习惯。

底部行：Standard / Tsangan / Split Space

矩阵图底部的四行对照如下（与 keyboard.json 中LAYOUT_all、LAYOUT_tkl_ansi、LAYOUT_tkl_ansi_tsangan、LAYOUT_tkl_ansi_tsangan_split_bs_rshift的w宽度完全吻合）：

由此可见，矩阵图中编号相同的按键（如84）在不同配列下承担不同的物理宽度与角色，这正是“一板多配列”PCB 的实现方式。

从矩阵图到键位映射：keymap 实践

默认键位文件 keymaps/default/keymap.c 使用LAYOUT_all宏，其参数顺序与矩阵图编号顺序一致（00→92），例如第 0 层开头：

[0] = LAYOUT_all( 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_SCRL, KC_PAUS, 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, ... KC_LCTL, KC_LGUI, KC_LALT, KC_SPC, KC_SPC, KC_SPC, KC_RALT, KC_RGUI, KC_APP, KC_RCTL, KC_LEFT, KC_DOWN, KC_RIGHT ),

对照矩阵图可以看出：

• 第 1 行有两个KC_BSPC（对应29与30，即 Split Backspace 全集）；
• 字母区含KC_NUHS（对应63的 # 键）与KC_ENT（64）；
• Shift 行含两个KC_RSFT（77与78）以及KC_UP（79）；
• 底部行含三个KC_SPC（83、84、85），覆盖三段式 Split Space。

因此，编写自定义 keymap 时有两条路线：

1. 基于LAYOUT_all：与矩阵图逐键对应，任何物理位置都能引用，适合想精细控制每个矩阵坐标的高级用户；
2. 基于LAYOUT_tkl_*社区布局：按自己实际配列（ANSI/ISO × 是否 Tsangan × 是否 Split）选择宏，参数数量更少、更不易出错。例如标准 ANSI 用户直接使用LAYOUT_tkl_ansi，其中 2u Backspace（30）与 6.25u 空格（84）都已经按正确宽度定义好，无需关心变体键位。

编译与刷写

在搭建好 QMK 构建环境后，按 readme.md 的说明编译默认键位：

make cherrybstudio/cb87v2:default

刷写固件：

make cherrybstudio/cb87v2:default:flash

CB87v2 使用atmel-dfu引导程序，进入 Bootloader 模式有两种方式：

• 轻触 PCB 背面靠近 MCU 的 Reset 按键；
• 连接 USB 线时按住键盘左上角按键（这也是 bootmagic 功能的体现，keyboard.json中"bootmagic": true）。

此外keyboard.json中还可以看到该板的背光（"pin": "B6"）、指示灯（Caps Lock 在 F0、Scroll Lock 在 F4，"on_state": 0表示低电平点亮）以及 24 颗 WS2812 RGB 灯（"pin": "E6"，含 breathing、rainbow_mood、snake、knight、twinkle 等动画）等硬件信息，这些与矩阵图共同构成了这块 PCB 的完整硬件档案。

结语

矩阵图是 QMK 键盘开发中最常被忽略却最有价值的一类文档：它把 PCB 的电气矩阵、物理配列与固件布局宏三者串联在一起。通过 CherryB.Studio CB87v2 的matrix_diagram.md，我们可以精确掌握00–92每个坐标的含义、8 个社区布局与LAYOUT_all的关系，以及 2u Backspace、ISO/BAE Enter、Split RShift、Tsangan/WKL、Split Space 等变体的矩阵实现方式。无论是想修改默认键位、移植新配列，还是排查“按键错位”类问题，先从这张矩阵图开始，往往能事半功倍。

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