HeliBoard键盘布局配置完全指南

HeliBoard键盘布局配置完全指南

HeliBoard Customizable and privacy-conscious open-source keyboard 项目地址: https://gitcode.com/gh_mirrors/he/HeliBoard

作为一款高度可定制的输入法应用，HeliBoard提供了灵活的键盘布局配置方案。本文将全面解析HeliBoard支持的两种布局格式及其高级特性，帮助开发者和技术爱好者深度定制个性化键盘。

一、布局格式概述

HeliBoard支持两种主流的键盘布局定义方式：

1. 简单文本格式：

   • 采用纯文本文件，每行定义一个按键
   • 通过两个连续换行符分隔键盘行
   • 适合快速定义基础布局

2. JSON格式：

   • 基于FlorisBoard的布局规范
   • 支持条件键位、多状态按键等高级特性
   • 提供更精细的布局控制

二、简单文本格式详解

基本语法规则

[主标签] [弹出键1] [弹出键2]...

示例：

a 0 + *  # 主键显示"a"，长按显示0、+、*三个备选键

特殊语法说明

• 使用双换行符\n\n标记新行开始
• 支持特殊功能键定义（后文详述）
• 支持标签与输入内容分离：显示文本|实际输入内容

三、JSON格式高级配置

核心结构

JSON格式采用宽松解析策略，支持以下关键特性：

1. 键位类型：

   • text_key：普通文本键（默认）
   • auto_text_key：自动大小写转换键
   • multi_text_key：多码位复合键

2. 条件选择器：

   {
     "$": "shift_state_selector",
     "unshifted": { "label": "," },
     "shifted": { "label": "<" }
   }
   

   支持的状态选择器包括：

   • 大小写状态(case_selector)
   • 输入法状态(keyboard_state_selector)
   • 布局方向(layout_direction_selector)
   • 输入类型(variation_selector)

关键属性说明

| 属性 | 类型 | 说明 | |------|------|------| | type | string | 定义键位类型(normal/function/space等) | | code | number | 键位对应的Unicode码点 | | width | number | 键位宽度比例(0=自动，-1=填充剩余) | | labelFlags | number | 标签显示标志位(位掩码组合) | | popup | array | 长按弹出键配置 |

四、特殊键位标签系统

HeliBoard实现了一套智能标签解析机制：

1. 功能键快捷定义：

   • _alpha_：切换到主键盘
   • _delete_：删除键
   • _com_：常用域名快捷输入

2. 货币键智能替换：

   • $$$：自动替换为本地货币符号
   • $$$1-$$$5：备用货币符号

3. 图标集成：

   {
     "label": "!icon/backspace|!code/key_action_delete"
   }
   

五、布局设计最佳实践

1. 尺寸控制：

   • 避免过多键位导致布局混乱
   • 合理设置width属性确保自适应

2. 滑动输入兼容性：

   • 避免重复键位
   • 单字符键位可获得最佳体验

3. 功能键布局技巧：

   • 使用placeholder类型键位进行布局对齐
   • 注意多状态键位的交互逻辑

六、多语言支持方案

实现完整的多语言支持需要：

1. 基础配置：

   • 在method.xml中注册布局
   • 设置唯一的subtypeId

2. 本地化增强：

   • 提供locale_key_texts定义语言特性
   • 添加语言显示名称资源

3. 脚本支持：

   • 更新ScriptUtils中的默认脚本设置
   • 考虑RTL语言的特殊布局需求

结语

HeliBoard的布局系统在保持简洁性的同时提供了强大的定制能力。无论是需要快速定义基础布局，还是实现复杂的多状态键盘，开发者都能找到合适的解决方案。建议从简单格式入手，逐步过渡到JSON格式实现更精细的控制。

HeliBoard Customizable and privacy-conscious open-source keyboard 项目地址: https://gitcode.com/gh_mirrors/he/HeliBoard