修改

2026-05-16 13:24:02 +08:00
parent eae60714b4
commit 6c13817527
42 changed files with 15921 additions and 0 deletions
--- a/实现/输入设备控制/键盘输入处理.md
+++ b/实现/输入设备控制/键盘输入处理.md
@@ -0,0 +1,273 @@
+# 键盘输入处理
+
+<cite>
+**本文档引用的文件**
+- [client/src/keymap.js](file://client/src/keymap.js)
+- [client/src/inputdevice.js](file://client/src/inputdevice.js)
+- [client/src/inputremoting.js](file://client/src/inputremoting.js)
+- [client/src/sender.js](file://client/src/sender.js)
+- [client/src/memoryhelper.js](file://client/src/memoryhelper.js)
+- [client/src/charnumber.js](file://client/src/charnumber.js)
+- [client/test/inputdevice.test.js](file://client/test/inputdevice.test.js)
+- [client/test/inputremoting.test.js](file://client/test/inputremoting.test.js)
+- [client/public/onebyone/main.js](file://client/public/onebyone/main.js)
+</cite>
+
+## 目录
+1. [简介](#简介)
+2. [项目结构](#项目结构)
+3. [核心组件](#核心组件)
+4. [架构总览](#架构总览)
+5. [详细组件分析](#详细组件分析)
+6. [依赖关系分析](#依赖关系分析)
+7. [性能考虑](#性能考虑)
+8. [故障排除指南](#故障排除指南)
+9. [结论](#结论)
+10. [附录](#附录)
+
+## 简介
+本文件系统性地文档化了视频流客户端中的键盘输入处理机制，覆盖按键按下、释放与重复事件的捕获与转发；键盘映射表与按键码转换；特殊键处理；键盘事件状态同步、按键组合检测与输入法支持；以及跨平台键盘布局差异、修饰键状态与跨浏览器兼容性的实践建议。通过代码级分析与可视化图示，帮助开发者在不直接阅读源码的情况下也能快速理解与扩展键盘输入子系统。
+
+## 项目结构
+键盘输入处理位于前端客户端模块中，核心文件包括：
+- 键盘映射与状态：keymap.js、inputdevice.js
+- 输入设备抽象与事件打包：inputdevice.js、inputremoting.js
+- 本地事件采集与发送：sender.js
+- 辅助工具：memoryhelper.js、charnumber.js
+- 测试用例：inputdevice.test.js、inputremoting.test.js
+- 应用层快捷键示例：public/onebyone/main.js
+
+```mermaid
+graph TB
+subgraph "键盘输入处理模块"
+KM["Keymap 映射表<br/>keymap.js"]
+ID["输入设备与状态<br/>inputdevice.js"]
+IR["输入远程转发<br/>inputremoting.js"]
+SND["本地采集与发送<br/>sender.js"]
+MH["内存位操作<br/>memoryhelper.js"]
+CN["字符编码映射<br/>charnumber.js"]
+end
+subgraph "应用层"
+APP["应用快捷键示例<br/>public/onebyone/main.js"]
+end
+KM --> ID
+MH --> ID
+CN --> ID
+ID --> IR
+SND --> IR
+APP --> SND
+```
+
+**图表来源**
+- [client/src/keymap.js:1-120](file://client/src/keymap.js#L1-L120)
+- [client/src/inputdevice.js:1-719](file://client/src/inputdevice.js#L1-L719)
+- [client/src/inputremoting.js:1-300](file://client/src/inputremoting.js#L1-L300)
+- [client/src/sender.js:1-209](file://client/src/sender.js#L1-L209)
+- [client/src/memoryhelper.js:1-28](file://client/src/memoryhelper.js#L1-L28)
+- [client/src/charnumber.js:1-110](file://client/src/charnumber.js#L1-L110)
+- [client/public/onebyone/main.js:132-145](file://client/public/onebyone/main.js#L132-L145)
+
+**章节来源**
+- [client/src/keymap.js:1-120](file://client/src/keymap.js#L1-L120)
+- [client/src/inputdevice.js:1-719](file://client/src/inputdevice.js#L1-L719)
+- [client/src/inputremoting.js:1-300](file://client/src/inputremoting.js#L1-L300)
+- [client/src/sender.js:1-209](file://client/src/sender.js#L1-L209)
+- [client/src/memoryhelper.js:1-28](file://client/src/memoryhelper.js#L1-L28)
+- [client/src/charnumber.js:1-110](file://client/src/charnumber.js#L1-L110)
+- [client/public/onebyone/main.js:132-145](file://client/public/onebyone/main.js#L132-L145)
+
+## 核心组件
+- 键盘映射表 Keymap：将 DOM KeyboardEvent.code 转换为内部键位索引，统一不同键盘布局下的按键标识。
+- 键盘状态 KeyboardState：基于位图记录每个键的按下/释放状态，支持按键重复事件的忽略与文本事件的生成。
+- 输入设备 Keyboard：封装键盘设备描述与事件队列，负责将 DOM 事件转换为内部状态。
+- 输入远程转发 InputRemoting：订阅本地事件，打包为消息并通过观察者发送。
+- 本地采集 Sender：注册文档级键盘事件监听，区分重复事件，生成状态事件与文本事件，并通过自定义事件广播。
+- 内存辅助 MemoryHelper：提供按位写入能力，用于高效更新键位状态位图。
+- 字符编码 CharNumber：将 DOM KeyboardEvent.key 映射为字符编码，用于文本事件。
+
+**章节来源**
+- [client/src/keymap.js:1-120](file://client/src/keymap.js#L1-L120)
+- [client/src/inputdevice.js:100-322](file://client/src/inputdevice.js#L100-L322)
+- [client/src/inputremoting.js:63-169](file://client/src/inputremoting.js#L63-L169)
+- [client/src/sender.js:14-188](file://client/src/sender.js#L14-L188)
+- [client/src/memoryhelper.js:1-28](file://client/src/memoryhelper.js#L1-L28)
+- [client/src/charnumber.js:1-110](file://client/src/charnumber.js#L1-L110)
+
+## 架构总览
+键盘输入从 DOM 事件开始，经由 Sender 采集，生成 KeyboardState 与可选的 TextEvent，再由 InputRemoting 打包并通过 RTC 数据通道发送至远端。
+
+```mermaid
+sequenceDiagram
+participant DOM as "DOM 文档"
+participant SND as "Sender"
+participant KB as "Keyboard 设备"
+participant KS as "KeyboardState"
+participant IR as "InputRemoting"
+participant OBS as "Observer"
+DOM->>SND : "keydown/keyup 事件"
+SND->>SND : "区分重复事件与文本事件"
+SND->>KB : "queueEvent(KeyboardEvent)"
+KB->>KS : "构造状态(按键按下/释放)"
+SND->>IR : "派发 StateEvent/TextEvent 自定义事件"
+IR->>IR : "NewEventsMsg.create(...) 打包"
+IR-->>OBS : "onNext(Message)"
+OBS-->>DOM : "RTC 数据通道发送"
+```
+
+**图表来源**
+- [client/src/sender.js:130-143](file://client/src/sender.js#L130-L143)
+- [client/src/inputdevice.js:100-109](file://client/src/inputdevice.js#L100-L109)
+- [client/src/inputdevice.js:274-322](file://client/src/inputdevice.js#L274-L322)
+- [client/src/inputremoting.js:138-141](file://client/src/inputremoting.js#L138-L141)
+- [client/src/inputremoting.js:258-277](file://client/src/inputremoting.js#L258-L277)
+- [client/src/sender.js:170-182](file://client/src/sender.js#L170-L182)
+
+## 详细组件分析
+
+### 键盘映射表与按键码转换
+- Keymap 将标准的 KeyboardEvent.code 映射到连续整数索引，确保不同键盘布局下按键的统一识别。
+- MemoryHelper.writeSingleBit 使用位图方式更新状态，避免逐键遍历，提升性能。
+- CharNumber 提供 KeyboardEvent.key 到字符编码的映射，用于 TextEvent 的字符字段。
+
+```mermaid
+flowchart TD
+Start(["按键事件进入"]) --> GetCode["读取 KeyboardEvent.code"]
+GetCode --> LookupKM["Keymap 查找键位索引"]
+LookupKM --> BitOp["MemoryHelper.writeSingleBit 更新位图"]
+BitOp --> Done(["完成状态更新"])
+```
+
+**图表来源**
+- [client/src/keymap.js:1-120](file://client/src/keymap.js#L1-L120)
+- [client/src/memoryhelper.js:7-20](file://client/src/memoryhelper.js#L7-L20)
+- [client/src/inputdevice.js:287-307](file://client/src/inputdevice.js#L287-L307)
+
+**章节来源**
+- [client/src/keymap.js:1-120](file://client/src/keymap.js#L1-L120)
+- [client/src/memoryhelper.js:1-28](file://client/src/memoryhelper.js#L1-L28)
+- [client/src/charnumber.js:1-110](file://client/src/charnumber.js#L1-L110)
+- [client/src/inputdevice.js:274-322](file://client/src/inputdevice.js#L274-L322)
+
+### 键盘事件状态同步与重复事件处理
+- Sender 在 _onKeyEvent 中区分事件类型与重复标志，仅在非重复的 keydown 时生成 StateEvent，同时始终生成 TextEvent，保证文本输入与状态同步。
+- KeyboardState 根据事件类型设置对应键位的布尔值，并通过位图持久化当前状态，支持后续状态查询与同步。
+
+```mermaid
+flowchart TD
+EvtIn(["keydown/keyup 进入"]) --> Type{"事件类型"}
+Type --> |keydown| Repeat{"是否重复?"}
+Repeat --> |是| SkipState["跳过 StateEvent"]
+Repeat --> |否| GenState["生成 StateEvent"]
+Type --> |keyup| UpState["生成 StateEvent"]
+GenState --> GenText["生成 TextEvent"]
+UpState --> GenText
+SkipState --> End(["结束"])
+GenText --> End
+```
+
+**图表来源**
+- [client/src/sender.js:130-143](file://client/src/sender.js#L130-L143)
+- [client/src/inputdevice.js:287-307](file://client/src/inputdevice.js#L287-L307)
+
+**章节来源**
+- [client/src/sender.js:130-143](file://client/src/sender.js#L130-L143)
+- [client/src/inputdevice.js:274-322](file://client/src/inputdevice.js#L274-L322)
+
+### 特殊键与修饰键处理
+- 特殊键（如功能键、方向键、锁定键）通过 Keymap 统一映射，确保跨平台一致性。
+- 修饰键（Shift/Alt/Control/Meta）同样映射到固定索引，便于在位图中跟踪其状态。
+- 应用层示例展示了如何在特定上下文中拦截修饰键组合（例如 Ctrl+V），体现修饰键在用户交互中的作用。
+
+**章节来源**
+- [client/src/keymap.js:52-66](file://client/src/keymap.js#L52-L66)
+- [client/public/onebyone/main.js:140-144](file://client/public/onebyone/main.js#L140-L144)
+
+### 文本事件与输入法支持
+- TextEvent 通过 CharNumber 将 KeyboardEvent.key 转换为字符编码，作为文本输入的载体。
+- 该机制独立于键盘状态位图，确保即使在某些平台或浏览器上按键重复导致状态事件被跳过，文本仍能正确传递。
+
+**章节来源**
+- [client/src/inputdevice.js:620-660](file://client/src/inputdevice.js#L620-L660)
+- [client/src/charnumber.js:1-110](file://client/src/charnumber.js#L1-L110)
+
+### 跨平台键盘布局差异与兼容性
+- 使用 KeyboardEvent.code 作为按键标识，避免因不同键盘布局导致的 key 值变化，提高跨平台一致性。
+- 对于需要根据 key 值进行语义判断的场景（如应用快捷键），可结合 KeyboardEvent.key 与修饰键状态进行综合判断。
+- 针对输入法候选窗口等复杂输入流程，建议在应用层通过监听 compositionstart/compositionupdate/compositionend 等事件进行补充处理（当前键盘子系统主要关注按键与文本事件）。
+
+**章节来源**
+- [client/src/keymap.js:1-120](file://client/src/keymap.js#L1-L120)
+- [client/public/onebyone/main.js:132-145](file://client/public/onebyone/main.js#L132-L145)
+
+## 依赖关系分析
+键盘输入处理模块内部依赖清晰，职责分离明确：
+- keymap.js 与 charnumber.js 为数据层，提供映射与编码。
+- inputdevice.js 为核心业务层，封装设备与状态。
+- memoryhelper.js 提供底层位操作能力。
+- sender.js 负责事件采集与分发。
+- inputremoting.js 负责消息打包与传输。
+- 测试用例验证关键行为与格式。
+
+```mermaid
+graph LR
+KM["keymap.js"] --> ID["inputdevice.js"]
+CN["charnumber.js"] --> ID
+MH["memoryhelper.js"] --> ID
+ID --> IR["inputremoting.js"]
+SND["sender.js"] --> IR
+TEST1["inputdevice.test.js"] --> ID
+TEST2["inputremoting.test.js"] --> IR
+```
+
+**图表来源**
+- [client/src/keymap.js:1-120](file://client/src/keymap.js#L1-L120)
+- [client/src/charnumber.js:1-110](file://client/src/charnumber.js#L1-L110)
+- [client/src/memoryhelper.js:1-28](file://client/src/memoryhelper.js#L1-L28)
+- [client/src/inputdevice.js:1-719](file://client/src/inputdevice.js#L1-L719)
+- [client/src/inputremoting.js:1-300](file://client/src/inputremoting.js#L1-L300)
+- [client/src/sender.js:1-209](file://client/src/sender.js#L1-L209)
+- [client/test/inputdevice.test.js:1-173](file://client/test/inputdevice.test.js#L1-L173)
+- [client/test/inputremoting.test.js:1-132](file://client/test/inputremoting.test.js#L1-L132)
+
+**章节来源**
+- [client/src/inputdevice.js:1-719](file://client/src/inputdevice.js#L1-L719)
+- [client/src/inputremoting.js:1-300](file://client/src/inputremoting.js#L1-L300)
+- [client/src/sender.js:1-209](file://client/src/sender.js#L1-L209)
+- [client/test/inputdevice.test.js:1-173](file://client/test/inputdevice.test.js#L1-L173)
+- [client/test/inputremoting.test.js:1-132](file://client/test/inputremoting.test.js#L1-L132)
+
+## 性能考虑
+- 位图存储：KeyboardState 使用位图存储键位状态，空间紧凑且更新高效，适合高频事件场景。
+- 重复事件过滤：Sender 在 keydown 上跳过重复事件，减少冗余状态事件，降低带宽占用。
+- 批量发送：InputRemoting 支持批量订阅者推送，便于扩展到多路远端接收。
+- 建议：对于高密度输入场景，可进一步引入节流/去抖策略或增量状态压缩，以平衡实时性与网络开销。
+
+[本节为通用性能讨论，无需具体文件引用]
+
+## 故障排除指南
+- 事件未触发：检查 Sender 是否正确注册文档级键盘事件监听，确认事件冒泡路径与目标元素。
+- 文本缺失：若仅发送状态事件而无文本事件，需确认是否正确生成 TextEvent（当前实现会在 keydown 时总是生成文本事件）。
+- 键位异常：核对 Keymap 中是否存在目标 code 的映射，确保跨平台一致性。
+- 修饰键误判：应用层快捷键应显式检查修饰键状态，避免在输入法候选等场景误触发。
+- 测试验证：可通过单元测试验证状态事件与文本事件的格式与内容，确保打包与解析一致。
+
+**章节来源**
+- [client/src/sender.js:130-143](file://client/src/sender.js#L130-L143)
+- [client/src/inputdevice.js:620-660](file://client/src/inputdevice.js#L620-L660)
+- [client/test/inputdevice.test.js:135-144](file://client/test/inputdevice.test.js#L135-L144)
+- [client/test/inputremoting.test.js:50-57](file://client/test/inputremoting.test.js#L50-L57)
+
+## 结论
+该键盘输入处理子系统通过标准化的按键映射、高效的位图状态管理与清晰的事件分发链路，实现了跨平台、低延迟的键盘输入远程转发。配合应用层的修饰键与快捷键处理，能够满足视频通话等实时交互场景的需求。建议在后续迭代中增强输入法候选窗口支持与状态压缩优化，以进一步提升兼容性与性能。
+
+[本节为总结性内容，无需具体文件引用]
+
+## 附录
+- 代码片段路径参考（用于定位实现细节）
+  - 键位映射与位图更新：[client/src/inputdevice.js:287-307](file://client/src/inputdevice.js#L287-L307)
+  - 文本事件生成：[client/src/inputdevice.js:639-646](file://client/src/inputdevice.js#L639-L646)
+  - 重复事件过滤与文本事件生成：[client/src/sender.js:130-143](file://client/src/sender.js#L130-L143)
+  - 状态事件打包：[client/src/inputremoting.js:258-277](file://client/src/inputremoting.js#L258-L277)
+  - 应用层修饰键快捷键示例：[client/public/onebyone/main.js:140-144](file://client/public/onebyone/main.js#L140-L144)
+
+[本节为参考索引，无需具体文件引用]