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 这块可玩性极高的 TKLTenKeyLess无小键盘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第二位是矩阵列号Col00 第 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和302u Backspace。矩阵坐标与物理按键对照下面按物理区域把矩阵图编号与 keyboard.json 中LAYOUT_all的定义逐一对照。F 区与功能键00–15编号按键编号按键00Esc09F901F110F1002F211F1103F312F1204F413Print Screen05F514Scroll Lock06F615Pause07F708F8注意 F1–F4、F5–F8、F9–F12 之间各有一个 1u 的间隔这与 TKL 常见的分区 F 区一致从编号看F9 之后的 F10–F12 以及 Print Screen、Scroll Lock、Pause 已经“换行”到第 1 行10–15这正是矩阵编号与物理排列不一定逐格对齐的典型例子。数字区与导航列16–33编号按键编号按键1625917126018227-1932820429Backspace21530Backspace2u 位22631Insert23732Home24833Page Up其中29与30是两个 Backspace 位置标准 2u Backspace 使用30在LAYOUT_tkl_ansi中为matrix: [3, 0], w: 2而Split Backspace 同时使用2930各 1u见LAYOUT_all中两个 Backspace 条目。字母区34–64编号按键编号按键编号按键34Tab1.5u44P54D35Q45[55F36W46]56G37E47\1.5u57H38R48Delete58J39T49End59K40Y50Page Down60L41U51Caps Lock1.75u61;42I52A6243O53S63#ISO 专用64Enter这里有两个关键的可配置点63# 键是 ISO 布局专用仅在LAYOUT_tkl_iso*系列布局中出现label: #, matrix: [6, 3]ANSI 布局中该位置不使用64是 Enter 键的共用矩阵位置ISO 布局中它以 1.25u 出现w: 1.25图注 ISO EnterANSI 布局中它以 2.25u 出现图注 BAE Enter即 Big Ass Enter 大回车。Shift 行与方向键65–79编号按键编号按键65左 ShiftANSI 2.25u / ISO 1.25u73M66\ISO 专用74,67Z75.68X76/69C77右 Shift1.75u70V78右 Shift2.75u 标准 / 1u 拆分71B79↑上方向键72N图注给出了两个重要变体65 2.25u 左 Shift这是标准 ANSI 的宽度ISO 布局中左 Shift 变为 1.25u腾出66的位置给 ISO 专用的反斜杠键78 2.75u 右 Shift标准而Split RShift 使用771.75u781u图注 1u/1.75u RShift。对照LAYOUT_tkl_ansi_split_bs_rshift中可见Shift, matrix: [7, 7], w: 1.75与Shift, matrix: [7, 8]默认 1u两条定义。底部行与箭头区80–92编号按键编号按键80Ctrl87GUI标准 1.25u / Tsangan 1.5u81GUI88Menu标准 1.25u / Tsangan 1u82Alt89Ctrl83空格2.25uSplit Space 用90←84空格6.25u / 7u / 1.25u91↓85空格2.75uSplit Space 用92→86Alt底部行是这张 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: COL2ROWCB87v2 使用10 行 × 10 列的矩阵共 100 个潜在位置实际使用 93 个主控为 atmega32u4。矩阵坐标[r][c]对应rows[r]×cols[c]两个引脚例如Esc00→ 行引脚 B0 × 列引脚 D5← 方向键90→ 行引脚 F6 × 列引脚 D5F1010→ 行引脚 B1 × 列引脚 D5→ 方向键92→ 行引脚 F6 × 列引脚 F7。diode_direction: COL2ROW表示二极管方向为“列驱动、行读取”即列线输出驱动信号、行线作为输入读取。扫描时 QMK 依次拉低每一列再读取各行状态从而确定被按下的键坐标这也解释了为什么矩阵图里 10 列 × 10 行能覆盖 93 个键位——同一行列交叉点只对应一个物理键而“可选变体”如双 Backspace共用同一坐标、通过不同布局宏引用。一板多布局矩阵图背后的可配置变体keyboard.json 的community_layouts声明了 8 个社区布局矩阵图正是这些布局在物理矩阵上的可视化布局宏对应变体tkl_ansi标准 ANSI2u Backspace 2.25u Enter 2.75u RShift 标准底行tkl_ansi_split_bs_rshiftANSI 拆分 Backspace 拆分 RShifttkl_ansi_tsanganANSI Tsangan/WKL 底行tkl_ansi_tsangan_split_bs_rshiftANSI Tsangan/WKL 拆分 Backspace/RShifttkl_iso标准 ISO含#键与 1.25u Entertkl_iso_split_bs_rshiftISO 拆分 Backspace 拆分 RShifttkl_iso_tsanganISO Tsangan/WKL 底行tkl_iso_tsangan_split_bs_rshiftISO Tsangan/WKL 拆分 Backspace/RShift此外LAYOUT_all覆盖了所有物理位置含全部变体键位是默认键位与自定义键位的“全集”入口。Backspace2u 与拆分2u Backspace只使用30宽度 2u图注 2u BackspaceSplit Backspace2930各 1u两个键可分别编程。EnterISO 与 BAEISO Enter63#64Enter 1.25uBAEBig Ass Enter只用64宽度 2.25u63空缺。右 Shift2.75u 与 1.75u1u 拆分标准78一个 2.75u 右 Shift拆分771.75u781u适合 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宽度完全吻合配列键位组合空格宽度LAYOUT_all全集80/81/82 83(2.25u) 84(1.25u) 85(2.75u) 86/87/88/89三段式Standard80/81/82 84 86/87/88/896.25uTsangan/WKL80(1.5u)/81(1u)/82(1.5u) 84 87(1.5u)/88(1u)/89(1.5u)7uTsangan/WKL Split Space80/81/82 838485 87/88/892.25u1.25u2.75u 三段由此可见矩阵图中编号相同的按键如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_ENT64Shift 行含两个KC_RSFT77与78以及KC_UP79底部行含三个KC_SPC83、84、85覆盖三段式 Split Space。因此编写自定义 keymap 时有两条路线基于LAYOUT_all与矩阵图逐键对应任何物理位置都能引用适合想精细控制每个矩阵坐标的高级用户基于LAYOUT_tkl_*社区布局按自己实际配列ANSI/ISO × 是否 Tsangan × 是否 Split选择宏参数数量更少、更不易出错。例如标准 ANSI 用户直接使用LAYOUT_tkl_ansi其中 2u Backspace30与 6.25u 空格84都已经按正确宽度定义好无需关心变体键位。编译与刷写在搭建好 QMK 构建环境后按 readme.md 的说明编译默认键位make cherrybstudio/cb87v2:default刷写固件make cherrybstudio/cb87v2:default:flashCB87v2 使用atmel-dfu引导程序进入 Bootloader 模式有两种方式轻触 PCB 背面靠近 MCU 的 Reset 按键连接 USB 线时按住键盘左上角按键这也是 bootmagic 功能的体现keyboard.json中bootmagic: true。此外keyboard.json中还可以看到该板的背光pin: B6、指示灯Caps Lock 在 F0、Scroll Lock 在 F4on_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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 QMK 矩阵图完全解读：CherryB.Studio CB87v2 的矩阵布局与多布局配置实战
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 这块可玩性极高的 TKLTenKeyLess无小键盘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第二位是矩阵列号Col00 第 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和302u Backspace。矩阵坐标与物理按键对照下面按物理区域把矩阵图编号与 keyboard.json 中LAYOUT_all的定义逐一对照。F 区与功能键00–15编号按键编号按键00Esc09F901F110F1002F211F1103F312F1204F413Print Screen05F514Scroll Lock06F615Pause07F708F8注意 F1–F4、F5–F8、F9–F12 之间各有一个 1u 的间隔这与 TKL 常见的分区 F 区一致从编号看F9 之后的 F10–F12 以及 Print Screen、Scroll Lock、Pause 已经“换行”到第 1 行10–15这正是矩阵编号与物理排列不一定逐格对齐的典型例子。数字区与导航列16–33编号按键编号按键1625917126018227-1932820429Backspace21530Backspace2u 位22631Insert23732Home24833Page Up其中29与30是两个 Backspace 位置标准 2u Backspace 使用30在LAYOUT_tkl_ansi中为matrix: [3, 0], w: 2而Split Backspace 同时使用2930各 1u见LAYOUT_all中两个 Backspace 条目。字母区34–64编号按键编号按键编号按键34Tab1.5u44P54D35Q45[55F36W46]56G37E47\1.5u57H38R48Delete58J39T49End59K40Y50Page Down60L41U51Caps Lock1.75u61;42I52A6243O53S63#ISO 专用64Enter这里有两个关键的可配置点63# 键是 ISO 布局专用仅在LAYOUT_tkl_iso*系列布局中出现label: #, matrix: [6, 3]ANSI 布局中该位置不使用64是 Enter 键的共用矩阵位置ISO 布局中它以 1.25u 出现w: 1.25图注 ISO EnterANSI 布局中它以 2.25u 出现图注 BAE Enter即 Big Ass Enter 大回车。Shift 行与方向键65–79编号按键编号按键65左 ShiftANSI 2.25u / ISO 1.25u73M66\ISO 专用74,67Z75.68X76/69C77右 Shift1.75u70V78右 Shift2.75u 标准 / 1u 拆分71B79↑上方向键72N图注给出了两个重要变体65 2.25u 左 Shift这是标准 ANSI 的宽度ISO 布局中左 Shift 变为 1.25u腾出66的位置给 ISO 专用的反斜杠键78 2.75u 右 Shift标准而Split RShift 使用771.75u781u图注 1u/1.75u RShift。对照LAYOUT_tkl_ansi_split_bs_rshift中可见Shift, matrix: [7, 7], w: 1.75与Shift, matrix: [7, 8]默认 1u两条定义。底部行与箭头区80–92编号按键编号按键80Ctrl87GUI标准 1.25u / Tsangan 1.5u81GUI88Menu标准 1.25u / Tsangan 1u82Alt89Ctrl83空格2.25uSplit Space 用90←84空格6.25u / 7u / 1.25u91↓85空格2.75uSplit Space 用92→86Alt底部行是这张 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: COL2ROWCB87v2 使用10 行 × 10 列的矩阵共 100 个潜在位置实际使用 93 个主控为 atmega32u4。矩阵坐标[r][c]对应rows[r]×cols[c]两个引脚例如Esc00→ 行引脚 B0 × 列引脚 D5← 方向键90→ 行引脚 F6 × 列引脚 D5F1010→ 行引脚 B1 × 列引脚 D5→ 方向键92→ 行引脚 F6 × 列引脚 F7。diode_direction: COL2ROW表示二极管方向为“列驱动、行读取”即列线输出驱动信号、行线作为输入读取。扫描时 QMK 依次拉低每一列再读取各行状态从而确定被按下的键坐标这也解释了为什么矩阵图里 10 列 × 10 行能覆盖 93 个键位——同一行列交叉点只对应一个物理键而“可选变体”如双 Backspace共用同一坐标、通过不同布局宏引用。一板多布局矩阵图背后的可配置变体keyboard.json 的community_layouts声明了 8 个社区布局矩阵图正是这些布局在物理矩阵上的可视化布局宏对应变体tkl_ansi标准 ANSI2u Backspace 2.25u Enter 2.75u RShift 标准底行tkl_ansi_split_bs_rshiftANSI 拆分 Backspace 拆分 RShifttkl_ansi_tsanganANSI Tsangan/WKL 底行tkl_ansi_tsangan_split_bs_rshiftANSI Tsangan/WKL 拆分 Backspace/RShifttkl_iso标准 ISO含#键与 1.25u Entertkl_iso_split_bs_rshiftISO 拆分 Backspace 拆分 RShifttkl_iso_tsanganISO Tsangan/WKL 底行tkl_iso_tsangan_split_bs_rshiftISO Tsangan/WKL 拆分 Backspace/RShift此外LAYOUT_all覆盖了所有物理位置含全部变体键位是默认键位与自定义键位的“全集”入口。Backspace2u 与拆分2u Backspace只使用30宽度 2u图注 2u BackspaceSplit Backspace2930各 1u两个键可分别编程。EnterISO 与 BAEISO Enter63#64Enter 1.25uBAEBig Ass Enter只用64宽度 2.25u63空缺。右 Shift2.75u 与 1.75u1u 拆分标准78一个 2.75u 右 Shift拆分771.75u781u适合 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宽度完全吻合配列键位组合空格宽度LAYOUT_all全集80/81/82 83(2.25u) 84(1.25u) 85(2.75u) 86/87/88/89三段式Standard80/81/82 84 86/87/88/896.25uTsangan/WKL80(1.5u)/81(1u)/82(1.5u) 84 87(1.5u)/88(1u)/89(1.5u)7uTsangan/WKL Split Space80/81/82 838485 87/88/892.25u1.25u2.75u 三段由此可见矩阵图中编号相同的按键如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_ENT64Shift 行含两个KC_RSFT77与78以及KC_UP79底部行含三个KC_SPC83、84、85覆盖三段式 Split Space。因此编写自定义 keymap 时有两条路线基于LAYOUT_all与矩阵图逐键对应任何物理位置都能引用适合想精细控制每个矩阵坐标的高级用户基于LAYOUT_tkl_*社区布局按自己实际配列ANSI/ISO × 是否 Tsangan × 是否 Split选择宏参数数量更少、更不易出错。例如标准 ANSI 用户直接使用LAYOUT_tkl_ansi其中 2u Backspace30与 6.25u 空格84都已经按正确宽度定义好无需关心变体键位。编译与刷写在搭建好 QMK 构建环境后按 readme.md 的说明编译默认键位make cherrybstudio/cb87v2:default刷写固件make cherrybstudio/cb87v2:default:flashCB87v2 使用atmel-dfu引导程序进入 Bootloader 模式有两种方式轻触 PCB 背面靠近 MCU 的 Reset 按键连接 USB 线时按住键盘左上角按键这也是 bootmagic 功能的体现keyboard.json中bootmagic: true。此外keyboard.json中还可以看到该板的背光pin: B6、指示灯Caps Lock 在 F0、Scroll Lock 在 F4on_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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考