怎么创建键盘的json文件

如何创建键盘的JSON文件：从零开始的详细指南

在软件开发中，JSON（JavaScript Object Notation）因其轻量级、易读易写的特性，常被用于配置文件和数据交换，键盘配置文件也不例外——无论是自定义键盘布局、定义快捷键，还是配置RGB灯效，JSON都是清晰且灵活的选择，本文将从零开始，详细讲解如何创建键盘的JSON文件，包括核心结构、字段设计、示例代码及常见问题,帮助你快速上手。

明确键盘JSON文件的用途与核心结构

在创建JSON文件前，首先需要明确它的用途，键盘JSON文件通常用于以下场景：

• 键盘布局配置：定义按键功能（如字母、符号、自定义指令）；
• 快捷键映射：设置组合键（如Ctrl+C、Win+D）；
• RGB灯效配置：定义灯光颜色、模式、亮度等；
• 宏命令配置：存储按键序列（如输入一段代码或运行脚本）。

无论哪种用途，键盘JSON文件的核心结构都围绕“按键定义”展开，通常包含以下层级：

{
  "keyboard_info": { /* 键盘基本信息 */ },
  "layouts": { /* 布局配置（如QWERTY、DVORAK） */ },
  "keys": { /* 按键具体定义（核心部分） */ },
  "macros": { /* 宏命令（可选） */ },
  "lighting": { /* 灯光配置（可选） */ }
}

分步创建键盘JSON文件

定义键盘基本信息（keyboard_info）

添加键盘的基本信息，方便识别和管理，这部分包含名称、型号、厂商、固件版本等元数据：

{
  "keyboard_info": {
    "name": "My Custom Keyboard",
    "model": "MK-100",
    "vendor": "CustomBrand",
    "firmware_version": "1.2.0",
    "description": "A custom keyboard layout for programming"
  }
}

注意：keyboard_info是可选的，但建议添加,便于后续维护。

设计按键布局（layouts）

键盘布局通常分为“物理布局”（按键的物理排列）和“逻辑布局”（按键的功能映射），JSON文件中，layouts字段用于定义逻辑布局，常见类型包括default（默认布局）、fn（功能键层）等。

以标准104键键盘为例，default布局的按键映射如下：

"layouts": {
  "default": {
    "name": "QWERTY",
    "keys": {
      "KC_A": { "position": [0, 1], "code": 4, "label": "A" },
      "KC_B": { "position": [1, 1], "code": 5, "label": "B" },
      "KC_C": { "position": [2, 1], "code": 6, "label": "C" },
      // ... 其他按键（如KC_D-KC_Z）
      "KC_1": { "position": [0, 0], "code": 10, "label": "1" },
      "KC_2": { "position": [1, 0], "code": 11, "label": "2" },
      // ... 数字键0-9
      "KC_SPACE": { "position": [5, 5], "code": 65, "label": "Space" },
      "KC_ENTER": { "position": [13, 4], "code": 40, "label": "Enter" }
    }
  },
  "fn": {
    "name": "Function Layer",
    "keys": {
      "KC_VOLU": { "position": [0, 0], "code": 238, "label": "Vol+" },
      "KC_VOLD": { "position": [1, 0], "code": 239, "label": "Vol-" },
      "KC_MUTE": { "position": [2, 0], "code": 240, "label": "Mute" }
      // ... FN层功能（如媒体控制、亮度调节）
    }
  }
}

关键字段说明：

• position：按键在键盘矩阵中的坐标（列, 行），用于物理定位；
• code：按键的扫描码（或HID码），需参考键盘芯片文档（如STM32的HID协议）；
• label：按键的显示标签（如“A”、“1”）,用于UI展示。

定义按键功能（keys）

keys字段是JSON文件的核心，用于覆盖或扩展默认布局的按键功能，将CapsLock键改为Ctrl，或添加自定义功能：

"keys": {
  "KC_CAPS": {
    "type": "modifier",
    "default_action": "KC_CTRL",  // 默认行为改为Ctrl
    "on_hold": "KC_LSHIFT",       // 长按时变为左Shift
    "on_tap": "KC_ESC"            // 点击时变为Esc
  },
  "KC_ESC": {
    "type": "layer_toggle",
    "target_layer": "fn",         // 点击ESC切换到FN层
    "on_hold": "KC_GRAVE"         // 长按时变为`键
  },
  "KC_CUSTOM": {
    "type": "macro",
    "macro_id": "macro_1",        // 关联宏命令
    "label": "Run Script"
  }
}

功能类型说明：

• modifier：修饰键（如Ctrl、Shift），支持on_hold（长按）和on_tap（点击）行为；
• layer_toggle：层切换键，用于切换布局（如FN层、游戏层）；
• macro：宏命令键，关联预定义的宏序列；
• consumer：消费者控制键（如音量、亮度），需指定code为HID consumer code。

添加宏命令（macros）

如果需要实现复杂功能（如输入代码片段、运行脚本），可以在macros字段中定义宏命令：

"macros": {
  "macro_1": {
    "name": "Open Terminal",
    "sequence": [
      { "type": "key_down", "code": 0xE0 },  // KC_LCTRL
      { "type": "key_down", "code": 0x0E },  // KC_T
      { "type": "key_up", "code": 0x0E },
      { "type": "key_up", "code": 0xE0 },
      { "type": "delay", "ms": 100 },        // 等待100ms
      { "type": "string", "text": "cmd" }    // 输入"cmd"
    ]
  },
  "macro_2": {
    "name": "Insert Date",
    "sequence": [
      { "type": "string", "text": "echo $(date)" }
    ]
  }
}

宏命令字段说明：

• type：操作类型（key_down/key_up按下/释放按键，delay延迟，string输入文本）；
• code：按键扫描码（参考键盘芯片文档）；
• text：要输入的文本字符串；
• ms：延迟时间（毫秒）。

配置灯光效果（lighting）

对于支持RGB的键盘，可以在lighting字段中定义灯效：

"lighting": {
  "mode": "static",               // 灯光模式：static（静态）、breathing（呼吸）、rainbow（彩虹）
  "color": "#FF0000",             // 基础颜色（十六进制，RGB）
  "brightness": 80,               // 亮度（0-100）
  "speed": 50,                    // 变化速度（0-100，仅动态模式有效）
  "per_key": {                    // 单键自定义颜色（可选）
    "KC_A": "#00FF00",
    "KC_S": "#0000FF",
    "KC_D": "#FFFF00"
  }
}

灯光模式说明：

• static：静态单色；
• breathing：呼吸灯效；
• rainbow：彩虹流动；
• custom：自定义动画（需额外定义动画帧）。

完整示例代码

结合以上步骤，一个完整的键盘JSON文件示例如下：

{
  "keyboard_info": {
    "name": "Programmer Keyboard",
    "model": "PRO-100",
    "vendor": "DevTools",
    "firmware_version": "2.0.1",
    "description": "Custom layout for coding and productivity"
  },
  "layouts": {
    "default": {
      "name": "QWERTY",
      "keys": {
        "