企业官网建设流程全解析

Keymap Editor API参考手册：所有接口详解与使用示例

【免费下载链接】keymap-editorA web based graphical editor of ZMK keymaps.项目地址: https://gitcode.com/gh_mirrors/ke/keymap-editor

Keymap Editor是一个基于Web的ZMK键盘映射图形编辑器，提供了丰富的API接口来管理键盘行为、键码、布局和键盘映射，以及与GitHub集成的功能。本手册将详细介绍所有可用API接口的使用方法和示例，帮助开发者快速集成和扩展Keymap Editor的功能。

一、键盘相关API

1.1 获取行为列表

• 接口地址：/behaviors
• 请求方法：GET
• 描述：获取ZMK支持的所有行为列表
• 响应示例：

{ "behaviors": [ {"id": "key_press", "description": "基本按键按下行为"}, {"id": "mod_tap", "description": "按住为修饰键，轻触为普通键"} ] }

• 实现文件：api/routes/keyboards.js

1.2 获取键码列表

• 接口地址：/keycodes
• 请求方法：GET
• 描述：获取ZMK支持的所有键码定义
• 响应示例：

{ "keycodes": [ {"code": "KC_A", "label": "A", "category": "字母"}, {"code": "KC_1", "label": "1", "category": "数字"} ] }

• 实现文件：api/routes/keyboards.js

1.3 获取布局信息

• 接口地址：/layout
• 请求方法：GET
• 描述：获取当前键盘布局信息
• 响应示例：

{ "layout": "LAYOUT", "rows": 5, "cols": 15, "keys": [ {"row": 0, "col": 0, "label": "Esc"}, {"row": 0, "col": 1, "label": "1"} ] }

• 实现文件：api/routes/keyboards.js

图1：Keymap Editor中的键盘布局示例，展示了如何通过API获取布局信息

1.4 获取当前键盘映射

• 接口地址：/keymap
• 请求方法：GET
• 描述：获取当前的键盘映射配置
• 响应示例：

{ "layers": [ { "name": "BASE", "keys": ["KC_ESC", "KC_1", "KC_2", "KC_3"] }, { "name": "FN", "keys": ["KC_F1", "KC_F2", "KC_F3", "KC_F4"] } ] }

• 实现文件：api/routes/keyboards.js

1.5 更新键盘映射

• 接口地址：/keymap
• 请求方法：POST
• 描述：更新键盘映射配置
• 请求体示例：

{ "layers": [ { "name": "BASE", "keys": ["KC_ESC", "KC_Q", "KC_W", "KC_E"] } ] }

• 响应：200 OK（成功）或500 Error（失败）
• 实现文件：api/routes/keyboards.js

图2：Keymap Editor的键盘映射编辑界面，可通过POST /keymap接口更新配置

二、GitHub集成API

2.1 GitHub授权

• 接口地址：/github/authorize
• 请求方法：GET
• 描述：引导用户进行GitHub授权，获取访问令牌
• 响应：重定向到GitHub授权页面
• 实现文件：api/routes/github.js

2.2 获取安装信息

• 接口地址：/github/installation
• 请求方法：GET
• 描述：获取用户的GitHub应用安装信息
• 请求头：Authorization: Bearer {token}
• 响应示例：

{ "installations": [ { "id": 12345, "repositories": ["my-keyboard-config"] } ] }

• 实现文件：api/routes/github.js

2.3 获取仓库分支

• 接口地址：/github/installation/:installationId/:repository/branches
• 请求方法：GET
• 描述：获取指定仓库的分支列表
• 请求头：Authorization: Bearer {token}
• 响应示例：

{ "branches": [ {"name": "main", "sha": "a1b2c3d4e5f6"}, {"name": "dev", "sha": "f6e5d4c3b2a1"} ] }

• 实现文件：api/routes/github.js

2.4 获取键盘配置文件

• 接口地址：/github/keyboard-files/:installationId/:repository
• 请求方法：GET
• 描述：获取指定仓库的键盘配置文件
• 请求头：Authorization: Bearer {token}
• 请求参数：branch（可选，默认主分支）
• 响应示例：

{ "info": { "name": "My Keyboard", "vendor": "Custom" }, "keymap": { "layers": [ {"name": "BASE", "keys": ["KC_ESC", "KC_Q", "KC_W"]} ] } }

• 实现文件：api/routes/github.js

图3：Keymap Editor的GitHub集成界面，展示了从GitHub仓库加载键盘配置文件的功能

2.5 更新键盘配置文件

• 接口地址：/github/keyboard-files/:installationId/:repository/:branch
• 请求方法：POST
• 描述：更新GitHub仓库中的键盘配置文件
• 请求头：Authorization: Bearer {token}
• 请求体示例：

{ "layout": "LAYOUT", "keymap": { "layers": [ {"name": "BASE", "keys": ["KC_ESC", "KC_Q", "KC_W"]} ] } }

• 响应：200 OK（成功）或500 Error（失败）
• 实现文件：api/routes/github.js

三、错误处理

所有API接口在发生错误时都会返回适当的HTTP状态码：

• 401 Unauthorized：未授权或令牌无效
• 400 Bad Request：请求参数错误或验证失败
• 500 Internal Server Error：服务器内部错误

错误响应示例：

{ "name": "KeymapValidationError", "errors": [ "Layer 'BASE' is missing required key at position (0,0)" ] }

四、使用示例

4.1 获取键码列表并显示

// 前端JavaScript示例 fetch('/behaviors') .then(response => response.json()) .then(data => { console.log('Available behaviors:', data.behaviors); // 在UI中显示行为列表 });

4.2 保存键盘映射到GitHub

// 前端JavaScript示例 const saveToGitHub = async (keymap) => { try { const response = await fetch('/github/keyboard-files/12345/my-keyboard-config/main', { method: 'POST', headers: { 'Content-Type': 'application/json', 'Authorization': `Bearer ${userToken}` }, body: JSON.stringify({ layout: 'LAYOUT', keymap: keymap }) }); if (response.ok) { alert('Keymap saved to GitHub successfully!'); } else { alert('Failed to save keymap'); } } catch (error) { console.error('Error saving keymap:', error); } };

图4：使用API创建的组合键编辑界面，展示了复杂键盘映射的配置方式

五、开发与扩展

Keymap Editor的API服务实现位于api/services/目录下，主要包括：

• api/services/zmk/：ZMK键盘映射相关功能
• api/services/github/：GitHub集成相关功能

开发者可以通过扩展这些服务来添加新的API接口或增强现有功能。

要开始本地开发，请克隆仓库：

git clone https://gitcode.com/gh_mirrors/ke/keymap-editor

然后按照running-locally.md中的说明进行环境配置和启动服务。

通过本API参考手册，您可以轻松地与Keymap Editor进行集成，构建自定义的键盘映射管理工具或扩展现有功能。如有任何问题，请参考项目源代码或提交issue获取帮助。

【免费下载链接】keymap-editorA web based graphical editor of ZMK keymaps.项目地址: https://gitcode.com/gh_mirrors/ke/keymap-editor