ColorfulKbd Pro 教程：从入门到精通
ColorfulKbd Pro 是一款功能极其丰富的开源键盘固件，它基于 QMK 和 ZMK，并在此基础上添加了大量独有的、炫酷且实用的功能，无论是视觉效果、交互体验还是底层性能，它都堪称“Pro”级别。
（图片来源网络，侵删）
本教程将分为以下几个部分：
- 【准备篇】环境搭建与固件烧录
- 【基础篇】核心概念与基础设置
- 【进阶篇】RGB 灯光与视觉效果
- 【高级篇】独有功能详解（如 Split、Combo 等）
- 【实战篇】如何构建自己的键盘配置
- 【故障排除】常见问题与解决方案
【准备篇】环境搭建与固件烧录
在开始之前,你需要准备好以下工具和软件。
所需工具
- 一把机械键盘：支持 ColorfulKbd Pro 的键盘（Keychron K系列、VGN V98 Pro、Akko MOD 007 等，或自己 DIY 的键盘）。
- 数据线：用于连接键盘和电脑。
- 解压软件：如 7-Zip 或 WinRAR。
- 文本编辑器：强烈推荐 VS Code，并安装 QMK Toolbox 插件。
- QMK Toolbox：用于烧录固件的官方工具。
获取固件文件
ColorfulKbd Pro 的固件并非一个独立的 .hex 文件，而是一个需要你根据自己键盘进行编译的源代码项目。
-
访问 GitHub 仓库： https://github.com/keyboardio/ColorfulKbd-Pro
（图片来源网络，侵删） -
下载项目：
- 点击绿色的 <> Code 按钮。
- 选择 Download ZIP，将整个项目压缩包下载到你的电脑。
-
解压文件： 将下载的
.zip文件解压到一个你容易找到的目录，D:\ColorfulKbd-Pro。
烧录固件（关键步骤）
⚠️ 重要提示：烧录固件有“ brick ”（变砖）的风险！请务必严格按照步骤操作，并确保你的键盘在烧录过程中不断电。
-
找到你的键盘
info.json文件：
（图片来源网络，侵删）- 进入你解压后的
ColorfulKbd-Pro文件夹。 - 找到
keyboards文件夹，然后进入你的键盘品牌和型号文件夹，如果你的键盘是 Keychron K6 Pro，路径就是keyboards/keychron/k6_pro。 - 在这个文件夹里,你会找到一个名为
info.json的文件。用记事本或 VS Code 打开它。
- 进入你解压后的
-
复制
keyboard和keymap的值：- 打开
info.json文件，你会看到类似这样的内容：{ "keyboard": "keychron/k6_pro", "keymap": "default", ... } - 复制
"keyboard": "keychron/k6_pro"这个值。 - 复制
"keymap": "default"这个值。default是默认的键位映射，你可以稍后修改它。
- 打开
-
使用 QMK Toolbox 编译并烧录：
- 打开你下载并安装好的 QMK Toolbox。
- 在顶部的输入框中,粘贴你刚刚复制的
keyboard值（keychron/k6_pro）。 - 点击旁边的 Enter 键，Toolbox 会自动去 GitHub 上查找这个键盘的固件。
- 连接键盘：将你的键盘通过数据线连接到电脑，并确保键盘处于可烧录模式（大部分键盘在插拔时或按特定组合键时会自动进入）。
- 选择固件文件：Toolbox 没有自动找到你的键盘，你可以点击 "Load" 按钮，手动在
ColorfulKbd-Pro文件夹中寻找一个.hex文件（通常在keyboards/你的键盘名/k6_pro_default目录下）。 - 烧录：确认键盘已连接后，点击 "Flash" 按钮，此时状态栏会显示进度，等待进度条走完，并提示 "Flashing successful!" 即表示烧录成功。
【基础篇】核心概念与基础设置
固件烧录成功后,你的键盘应该可以正常使用了，现在我们来学习如何通过修改代码来个性化设置。
键位映射文件 (keymap.c)
这是你自定义键盘按键功能的核心文件。
-
定位文件：
- 在
ColorfulKbd-Pro文件夹中，找到users/default文件夹。 - 在里面你会看到一个
keymap.c文件。这就是你的“键盘配置表”。
- 在
-
理解基本结构：
keymap.c的核心是一个二维数组layers，代表不同的键盘层（如基础层、功能层等）。//... 其他代码 ... // 定义层 enum layers { _BASE, // 基础层，默认为0 _FN1, // 功能层1 _FN2 // 功能层2 }; // 定义组合键 #define RGB_MOD LCTL(LALT(LSFT(K_TAB))) // 定义一个复杂的组合键 // 定义每个按键的输出 const uint16_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] = { [_BASE] = LAYOUT( // 基础层 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_BSPC, KC_DEL, 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_PGUP, 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_ENT, KC_PGDN, KC_LSFT, KC_Z, KC_X, KC_C, KC_V, KC_B, KC_N, KC_M, KC_COMM, KC_DOT, KC_SLSH, KC_RSFT, KC_UP, KC_LCTL, KC_LGUI, KC_LALT, KC_SPC, KC_RALT, KC_RGUI, KC_APP, KC_LEFT, KC_DOWN, KC_RGHT ), [_FN1] = LAYOUT( // FN1层 _______, _______, _______, _______, _______, _______, _______, _______, _______, _______, _______, _______, _______, _______, _______, _______, _______, _______, _______, _______, _______, _______, _______, _______, _______, _______, _______, _______, _______, _______, _______, _______, _______, _______, _______, _______, _______, _______, _______, _______, _______, _______, _______, _______, _______, _______, _______, _______, _______, _______, _______, _______, _______, _______, _______, _______, _______, _______, _______, _______, _______, _______, _______, _______, _______, _______, _______ ) };KC_XXX是 QMK 的按键代码，KC_A代表A键，KC_SPC代表空格键。LAYOUT(...)定义了键盘的物理布局，你不需要修改它，除非你的键盘布局很特殊。_______代表一个空位，按下无任何反应。
如何修改键位？
- 打开
keymap.c。 - 找到你想要修改的按键，例如想把左下角的
LCTL(左 Ctrl) 改成LGUI(左 Win)。 - 将代码中的
KC_LCTL改成KC_LGUI。 - 保存文件。
- 重新烧录：
- 再次打开 QMK Toolbox。
- 在输入框中输入你的键盘名（如
keychron/k6_pro）。 - 点击 "Compile" 按钮，而不是 "Flash"，Toolbox 会根据你修改的
keymap.c重新生成一个.hex文件。 - 编译成功后,点击 "Flash" 将新固件烧入键盘。
【进阶篇】RGB 灯光与视觉效果
ColorfulKbd Pro 的 RGB 功能是其最大的亮点之一。
开启 RGB
在 keymap.c 的开头，你需要启用 RGB 功能，取消注释（删除 ）以下代码：
//... 其他代码 ... // 启用 RGB 灯光 #define RGBLIGHT_ENABLE #define RGB_MATRIX_ENABLE // 如果你想使用更高级的矩阵灯效，请启用这个
常用 RGB 指令
在 keymap.c 的 keymaps 数组之外，你可以定义一些快捷键来控制灯光。
// 在 keymaps 数组之前添加 // RGB 灯光控制 #define RGB_TOG RGB_MOD // 我们之前定义的复杂组合键 #define RGB_HUI RGB_RMOD // RGB 色相增加 #define RGB_HUD RGB_MOD // RGB 色相减少 #define RGB_SAI RGB_RMOD // RGB 饱和度增加 #define RGB_SAD RGB_MOD // RGB 饱和度减少 #define RGB_VAI RGB_RMOD // RGB 亮度增加 #define RGB_VAD RGB_MOD // RGB 亮度减少 #define RGB_MODE_FORWARD RGB_MOD // 切换灯效模式 #define RGB_MODE_REVERSE RGB_MOD // 反向切换灯效模式
你可以在 keymaps 中将这些指令分配到具体的按键上，在 _FN1 层，你可以把方向键设置为 RGB 控制键：
[_FN1] = LAYOUT( // ... 其他按键 ... _______, _______, _______, _______, _______, _______, _______, _______, _______, _______, _______, _______, _______, _______, _______, // ... 其他按键 ... _______, _______, _______, _______, _______, _______, _______, _______, _______, _______, _______, _______, _______, // 把 UP 键设为 RGB 模式切换 _______, _______, _______, _______, _______, _______, _______, _______, _______, _______, _______, _______, _______, // 把 RSFT 设为 RGB 亮度增加 _______, _______, _______, _______, _______, _______, _______, _______, _______, _______, _______ ),
注意：上面的 RGB_MOD 等只是占位符，你需要把它们换成实际的 QMK 指令，如 QK_RGB_TOG，更简单的方法是直接在 keymaps 中使用 RGB_TOG 等宏定义。
自定义灯效
ColorfulKbd Pro 支持丰富的灯效，如波浪、呼吸、彩虹等，你可以在 keymap.c 中配置：
// 设置默认灯效模式 (RGB_MATRIX_EFFECT_XXX) #define RGB_MATRIX_DEFAULT_MODE RGB_MATRIX_CYCLE_LEFT_RIGHT // 默认左右循环彩虹灯效 // 设置灯效速度 #define RGB_MATRIX_HUE_STEP 8 #define RGB_MATRIX_SAT_STEP 8 #define RGB_MATRIX_VAL_STEP 8 #define RGB_MATRIX_SPD_STEP 10
你可以在 keymap.c 中找到所有可用的灯效，它们以 RGB_MATRIX_EFFECT_ 开头。
【高级篇】独有功能详解
这部分是 ColorfulKbd Pro 的精髓。
Split 键盘支持
ColorfulKbd Pro 对分体式键盘有极好的支持，如果你使用的是分体键盘，你可以在 info.json 中配置：
split:true- 告诉固件这是分体键盘。split_flipped:true或false- 定义左右手是否镜像。split_offset:[x, y]- 定义左右手的偏移量，以更好地适应人体工学。
Combo（组合键）
Combo 是当你同时按下两个或多个按键时，固件会自动发送一个第三个按键的信号，这对于减少手指移动非常高效。
如何设置 Combo？
在 keymap.c 中，你需要定义一个 combo_t 类型的数组，并在 process_combo_event 函数中处理逻辑。
// 1. 定义 Combo 键
enum combos {
C_ESC_TAB, // ESC + Tab 组合
C_A_S // A + S 组合
};
// 2. 定义 Combo 的触发按键和结果
const uint16_t PROGMEM combo_esctab[] = {KC_ESC, KC_TAB, COMBO_END};
const uint16_t PROGMEM combo_as[] = {KC_A, KC_S, COMBO_END};
// 3. 创建一个 Combo 结构体数组
combo_t key_combos[] = {
[C_ESC_TAB] = COMBO(combo_esctab, KC_GRAVE), // 按下 ESC+Tab，发送 ` 键
[C_A_S] = COMBO(combo_as, KC_LCTL) // 按下 A+S，发送 Ctrl 键
};
// 4. （可选）处理 Combo 事件，添加特效等
void process_combo_event(uint8_t combo_index, bool pressed) {
switch (combo_index) {
case C_ESC_TAB:
if (pressed) {
// 可以在这里添加声音或灯光反馈
}
break;
// ... 其他 combo
}
}
Tap Dance（点击舞蹈）
Tap Dance 允许同一个按键根据你点击的次数执行不同的操作。
如何设置 Tap Dance？
-
定义 Tap Dance 键：
enum tap_dances { TD_ESC_CAPS = 0, // 第一个 Tap Dance 键 TD_DOT_SLSH // 第二个 Tap Dance 键 }; -
定义每个 Tap Dance 的行为：
// 定义每个 Tap Dance 键的行为 tap_dance_action_t tap_dance_actions[] = { // TD_ESC_CAPS: 点击1次发送 ESC，点击2次发送 Caps Lock [TD_ESC_CAPS] = ACTION_TAP_DANCE_DOUBLE(KC_ESC, KC_CAPS), // TD_DOT_SLSH: 点击1次发送 .，快速连续点击2次发送 / [TD_DOT_SLSH] = ACTION_TAP_DANCE_FN_ADVANCED(NULL, tap_dance_finished, tap_dreset) }; -
在
keymaps中使用：[_BASE] = LAYOUT( // ... 其他按键 ... TD(TD_ESC_CAPS), // 这个按键就是 Tap Dance 键 // ... 其他按键 ... TD(TD_DOT_SLSH), // ... 其他按键 ... ),
【实战篇】如何构建自己的键盘配置
这是一个完整的 workflow 示例，目标是创建一个 "Fn" 层，用于控制媒体、音量和 RGB 灯光。
-
规划：我决定用右下角的
Right Alt键作为Fn键，按住它，再按其他键，就会触发_FN1层的功能。 -
修改
keymap.c：-
在
keymaps数组之前，定义一些快捷宏，让代码更清晰：#define MUTE KC_MUTE #define VOLU KC_VOLU #define VOLD KC_VOLD #define PREV KC_MPRV #define NEXT MNXT #define PLAY KC_MPLY #define RGB_TOG QK_RGB_TOG // ... 其他 RGB 控制宏
-
修改
_BASE层，将右下角的KC_RALT改为TG(_FN1)。TG是 "Toggle Layer" 的意思，按一下进入_FN1层，再按一下退回_BASE层。[_BASE] = LAYOUT( // ... 其他按键 ... KC_LCTL, KC_LGUI, KC_LALT, KC_SPC, _______, KC_APP, KC_LEFT, KC_DOWN, KC_RGHT, KC_RALT // 将最后一个 KC_RALT 改为 TG(_FN1) ),
-
编写
_FN1层的功能，将方向键和上层键位替换为媒体控制和 RGB 控制：[_FN1] = LAYOUT( // ... 其他按键 ... _______, _______, _______, _______, _______, _______, _______, _______, _______, _______, _______, _______, _______, _______, _______, // ... 其他按键 ... _______, _______, _______, _______, _______, _______, _______, _______, _______, _______, _______, _______, _______, // UP -> RGB_MODE_FORWARD _______, _______, _______, _______, _______, _______, _______, RGB_TOG, RGB_VAI, RGB_VAD // RGHT -> RGB_TOG, DOWN -> RGB_VAD, RIGHT -> RGB_VAI ),
-
-
编译与烧录：
- 保存
keymap.c。 - 在 QMK Toolbox 中输入键盘名，点击 "Compile"。
- 编译成功后,点击 "Flash"。
- 保存
-
测试：你的键盘应该已经按照你的想法工作了！
【故障排除】常见问题与解决方案
-
问题：烧录失败，提示 "Device not found" 或 "No device found"。
- 原因：电脑未识别到键盘，或键盘未进入烧录模式。
- 解决：
- 换根数据线和 USB 口。
- 重启键盘：拔掉数据线，等待几秒再插上。
- 查找进入烧录模式的按键：有些键盘需要按住
Esc键再插上数据线（DFU 模式），查阅你的键盘说明书。
-
问题：编译失败，提示 "error: 'LAYOUT' undeclared"。
- 原因：你的键盘
info.json文件中的layout字段可能为空或不正确。 - 解决：打开
keyboards/你的键盘名/info.json，确保layout字段有值，"kl": "LAYOUT_60_ansi"，如果不确定，可以尝试删除layout字段，让 QMK 自动推断。
- 原因：你的键盘
-
问题：RGB 灯光不亮或颜色异常。
- 原因：RGB 功能未启用，或灯效配置错误。
- 解决：
- 检查
keymap.c中是否取消了#define RGBLIGHT_ENABLE或#define RGB_MATRIX_ENABLE的注释。 - 检查灯效名称是否拼写正确。
- 检查
-
问题：键盘部分按键失灵。
- 原因：可能是
LAYOUT定义与你的物理键盘不匹配，或者是硬件问题。 - 解决：
- 确认你使用的
LAYOUT宏（如LAYOUT_60_ansi,LAYOUT_tkl_f13_ansi等）与你的键盘完全一致。 - 如果修改代码前是好的,修改后变坏的，很可能是代码写错了，检查语法。
- 确认你使用的
- 原因：可能是
希望这份详细的教程能帮助你顺利上手 ColorfulKbd Pro！享受自定义键盘的乐趣吧！
