VIA键盘定义库项目架构解析：理解vendor和keyboard目录结构

【免费下载链接】keyboards项目地址: https://gitcode.com/gh_mirrors/key/keyboards

VIA键盘定义库是一个用于存储和管理机械键盘配置定义的开源项目，它为QMK固件的VIA配置工具提供了核心的键盘定义支持。对于想要深入了解VIA如何支持各种键盘型号的开发者来说，理解其vendor和keyboard目录结构至关重要。😊

项目架构概述

VIA键盘定义库采用了一种清晰的分层结构来组织数千种键盘的定义文件。整个项目主要分为两个版本目录：

• src/- 存放V2版本的键盘定义
• v3/- 存放V3版本的键盘定义

每个版本目录都遵循相同的组织结构，这种设计使得键盘定义的管理和扩展变得简单高效。

Vendor目录：键盘制造商的家园

在VIA项目中，vendor目录代表的是键盘的制造商或品牌。这个目录结构的设计理念非常直观：每个不同的键盘品牌都有一个独立的目录。例如：

• 1upkeyboards - 1upkeyboards品牌
• ai03 - ai03设计工作室
• YMDK - 雅木达克键盘品牌
• 40percentclub - 40%键盘爱好者社区

每个vendor目录的名称通常使用小写字母，并且遵循品牌的实际名称或约定俗成的缩写。这种组织方式使得查找特定品牌的键盘变得非常容易。

Keyboard目录：具体型号的定义

在每个vendor目录下，您会找到一个或多个keyboard目录，这些目录对应着该品牌下的具体键盘型号。例如：

v3/1upkeyboards/ ├── 1up60hse/ │ └── 1up60hse.json ├── 1up60hte/ │ └── 1up60hte.json ├── 1up60rgb/ │ └── 1up60rgb.json └── pi40/ └── pi40.json

每个keyboard目录包含一个JSON定义文件，这个文件描述了键盘的所有配置信息。这种结构清晰地反映了"品牌→型号"的逻辑关系。

JSON定义文件：键盘的DNA

每个键盘型号都有一个对应的JSON定义文件，这个文件包含了键盘的所有配置信息。让我们来看一个典型的例子：1up60hse.json：

{ "name": "1up60hse", "vendorId": "0x6F75", "productId": "0x6873", "matrix": { "rows": 5, "cols": 14 }, "keycodes": ["qmk_lighting"], "menus": ["qmk_backlight_rgblight"], "layouts": { "keymap": [...] } }

关键字段解析

1. name- 键盘的名称标识符
2. vendorId和productId- USB设备标识符，确保VIA能正确识别键盘
3. matrix- 定义键盘矩阵的行列数
4. layouts- 定义键盘的物理布局和键位映射
5. keycodes和menus- 定义支持的功能和菜单选项

版本管理：V2与V3的差异

项目同时维护两个版本的定义文件：

• V2定义：位于src/目录，使用较旧的格式
• V3定义：位于v3/目录，使用更新的、更丰富的格式

构建脚本会自动处理这两个版本的定义，并将它们转换为VIA可用的格式。您可以在build-definitions.ts中看到版本处理逻辑。

构建流程：从定义到可用

项目的构建流程非常巧妙：

1. 扫描定义文件- 构建脚本会扫描所有vendor/keyboard目录中的JSON文件
2. 验证和转换- 每个定义文件都会被验证并转换为VIA格式
3. 生成索引- 创建supported_kbs.json文件，列出所有支持的键盘
4. 生成哈希- 为所有定义生成哈希值，用于缓存和版本控制

您可以在build-isolated-definitions.ts中查看详细的构建逻辑。

实际应用：如何添加新键盘

如果您想为VIA添加对新键盘的支持，只需按照以下步骤操作：

1. 创建vendor目录- 如果品牌不存在，在v3/下创建新的vendor目录
2. 创建keyboard目录- 在vendor目录下创建以键盘型号命名的目录
3. 编写JSON定义- 根据VIA规范创建键盘定义文件
4. 提交PR- 将您的更改提交到项目仓库

例如，要为"AwesomeKeyboards"品牌的"Super60"型号添加支持，您需要创建：

v3/awesomekeyboards/super60/super60.json

目录结构的优势

这种vendor/keyboard目录结构具有多个显著优势：

✅清晰的层次关系- 品牌和型号的关系一目了然 ✅易于维护- 每个键盘的定义都是独立的，互不干扰 ✅便于扩展- 添加新品牌或型号非常简单 ✅版本控制友好- 每个文件的变化都清晰可见 ✅查找方便- 按照品牌和型号的层次结构查找非常直观

常见问题与解决方案

问题1：vendorId冲突

如果两个键盘使用了相同的vendorId和productId组合，构建过程会报错。解决方案是确保每个键盘有唯一的USB标识符。

问题2：定义文件格式错误

JSON定义文件必须严格遵循VIA规范。您可以使用VIA规范文档作为参考。

问题3：目录命名不一致

建议遵循已有的命名约定，使用小写字母和一致的命名风格。

总结

VIA键盘定义库的vendor和keyboard目录结构是一个精心设计的系统，它使得管理数千种键盘定义变得简单而高效。通过理解这种结构，您可以：

• 🔧 轻松地为VIA添加对新键盘的支持
• 🔍 快速找到特定品牌或型号的定义
• 📊 理解键盘定义的组织方式
• 🛠️ 参与项目的维护和贡献

无论您是键盘爱好者、开发者还是制造商，理解这个目录结构都将帮助您更好地使用和贡献于VIA生态系统。这个清晰的组织架构是VIA项目能够支持如此多键盘型号的关键所在！🚀

【免费下载链接】keyboards项目地址: https://gitcode.com/gh_mirrors/key/keyboards