keybr.com项目自定义键盘布局开发指南

项目背景

keybr.com是一个专注于打字练习和键盘布局研究的开源项目。该项目提供了丰富的键盘布局支持，并允许开发者自定义和添加新的键盘布局配置。本文将详细介绍如何在项目中添加自定义键盘布局。

键盘布局导入方式

项目支持从多种来源导入键盘布局：

1. 从CLDR项目导入：该项目维护了大量标准键盘布局定义
2. 使用微软键盘布局创建器生成的布局
3. 开发者手动编写自定义布局定义文件

布局生成流程

所有键盘布局的生成入口都位于keyboard-generators包中。该包包含将各种格式的键盘布局定义转换为项目内部TypeScript表示的脚本。

生成步骤：

cd packages/keybr-generators
npm run generate-layouts

生成的文件会输出到packages/keybr-keyboard/lib/layout目录。开发者不应直接修改这些生成的文件，因为重新运行生成器时会覆盖修改。

自定义键盘布局开发

基础配置

自定义布局定义文件位于packages/keybr-keyboard-generator/layout目录。开发者可以通过复制和修改现有布局来创建新布局。

配置格式说明：

• 每个物理按键位置(如"KeyA", "KeyB"等)映射到最多4个码点
• 4个码点对应不同修饰键组合：
  1. 无修饰键
  2. Shift键
  3. AltGr键
  4. Shift+AltGr组合键

码点可以表示为：

• 最多4个字符的字符串
• 最多4个字符串或数字码点值的数组

示例：

export default {
  KeyQ: "qQ",
  KeyW: ["w", "W"],
  KeyE: [0x0065, 0x0045],
  // 更多按键...
};

死键(Dead Key)支持

项目支持配置死键功能，用于输入带重音符号的字符。

死键可以配置为：

1. 组合变音符号码点：

export default {
  KeyQ: [
    /* 组合抑音符 */ 0x0300,
    /* 组合扬抑符 */ 0x005e,
  ],
  // 更多按键...
};

2. 以"*"字符开头的可打印变音符号字符串：

export default {
  KeyQ: ["*`", "*^"],
  // 更多按键...
};

注意：项目仅支持将字母与变音符号组合的死键功能，不支持切换字母表或产生非字母字符的死键。

布局完整配置

生成的文件仅包含码点映射，完整的布局配置还需要指定ID、名称等信息。

配置位置：packages/keybr-keyboard/lib/layout.ts中的Layout类。

示例配置：

static readonly EN_CUSTOM = new Layout(
    /* id= */ "en-custom",
    /* xid= */ 0xff,
    /* name= */ "My Custom Layout",
    /* family= */ "qwerty",
    /* language= */ Language.EN,
    /* emulate= */ false,
    /* geometries= */ new Enum(
      Geometry.STANDARD_102,
      Geometry.STANDARD_102_FULL,
      Geometry.STANDARD_101,
      Geometry.STANDARD_101_FULL,
      Geometry.MATRIX,
    ),
);

关键配置项详解

1. ID和XID：

   • id：人类可读的字符串，遵循"xx-yy"模式
     • "xx"：ISO 639-1双字母语言代码
     • "yy"：ISO 3166-2双字母国家代码(小写)
   • xid：单字节数字标识符，取现有布局最大xid+1
   • 注意：这些标识符一旦分配就不能更改

2. 布局名称：

   • 可包含本地化国家名称(如"{BR} (ABNT2)")

3. 布局家族(family)：

   • 相同家族的布局会合并统计打字结果
   • 常见家族："qwerty"、"qwertz"、"azerty"
   • 不属于这些家族的需自定义

4. 布局语言：

   • 用于按语言筛选可用布局

5. 模拟选项(emulate)：

   • 如果布局不包含死键，可启用此选项

6. 几何结构(geometries)：

   • 指定支持的键盘物理布局(如ISO、ANSI等)
   • 列表中的第一个是首选布局

最佳实践建议

1. 在添加新布局前，先检查现有布局是否已满足需求
2. 遵循项目的命名规范和编码风格
3. 为自定义布局添加清晰的注释说明
4. 测试新布局在所有支持的几何结构下的表现
5. 考虑布局的语言和地区特性

通过以上步骤，开发者可以成功地为keybr.com项目添加自定义键盘布局，丰富项目的键盘支持能力。