14 KiB
14 KiB
实用工具模块
**本文引用的文件** - [logger.js](file://client/src/logger.js) - [log.ts](file://src/log.ts) - [memoryhelper.js](file://client/src/memoryhelper.js) - [charnumber.js](file://client/src/charnumber.js) - [inputdevice.js](file://client/src/inputdevice.js) - [pointercorrect.js](file://client/src/pointercorrect.js) - [pointercorrect.test.js](file://client/test/pointercorrect.test.js) - [memoryhelper.test.js](file://client/test/memoryhelper.test.js) - [inputdevice.test.js](file://client/test/inputdevice.test.js) - [package.json](file://package.json)目录
简介
本文件系统性地文档化了“实用工具模块”，涵盖以下方面：
- 日志系统：前端简易开关式日志与后端结构化日志（含级别、时间戳、前缀格式化）。
- 内存辅助工具：按位写入字节缓冲，支持位级布尔操作与整型大小常量。
- 字符数字转换工具：按键键值映射与字符编码处理，支撑文本事件生成。
- 指针校正工具：坐标变换、黑边填充（Letterbox）补偿、屏幕适配与输入精度优化。
文档同时提供可直接定位到源码位置的路径指引，便于在实际项目中快速集成与验证。
项目结构
实用工具模块位于客户端与服务端两处：
- 客户端工具位于 client/src，包含日志开关、内存辅助、字符映射、输入设备状态序列化、指针校正等。
- 服务端日志位于 src/log.ts，提供结构化日志级别与格式化输出。
graph TB
subgraph "客户端(client/src)"
LJS["logger.js<br/>前端简易日志"]
MJS["memoryhelper.js<br/>内存辅助(位写入)"]
CJS["charnumber.js<br/>字符数字映射"]
IDJS["inputdevice.js<br/>输入设备/状态/事件"]
PCJS["pointercorrect.js<br/>指针校正"]
end
subgraph "服务端(src)"
LTS["log.ts<br/>结构化日志"]
end
IDJS --> MJS
IDJS --> CJS
PCJS --> |"使用元素尺寸/布局"| 浏览器DOM["浏览器DOM/HTMLVideoElement"]
LJS -. 可独立使用 .-> 浏览器控制台
LTS -. 输出到 .-> Node控制台
图表来源
- logger.js:1-30
- memoryhelper.js:1-28
- charnumber.js:1-110
- inputdevice.js:1-719
- pointercorrect.js:1-125
- log.ts:1-51
章节来源
核心组件
- 前端日志工具（logger.js）
- 提供启用/禁用与多级别输出函数，基于全局开关控制是否打印至浏览器控制台。
- 适合开发调试阶段按需开启/关闭日志输出。
- 后端日志工具（log.ts）
- 定义日志级别枚举与解析函数；统一格式化时间戳与级别前缀；根据级别选择对应 console 方法输出。
- 支持通过配置设置全局日志级别，实现生产环境精细化日志控制。
- 内存辅助工具（memoryhelper.js）
- 提供静态方法按位写入 ArrayBuffer 的指定偏移；支持置位/清位；提供整型大小常量。
- 在输入设备状态序列化中用于紧凑存储布尔标志位。
- 字符数字转换工具（charnumber.js）
- 提供按键键名到数值的映射表，用于文本事件生成与键盘状态记录。
- 指针校正工具（pointercorrect.js）
- 将浏览器坐标系映射到视频坐标系，处理黑边（Letterbox）补偿与元素内内容矩形计算。
- 支持动态重置视频宽高与元素尺寸，适配不同播放场景。
章节来源
架构总览
下图展示了输入设备状态序列化与文本事件生成的整体流程，体现内存辅助与字符映射在其中的关键作用。
sequenceDiagram
participant Dev as "输入设备"
participant State as "键盘状态"
participant Mem as "内存辅助(MemoryHelper)"
participant Text as "文本事件(TextEvent)"
Dev->>State : "按键事件(KeyboardEvent)"
State->>Mem : "按位写入(keys缓冲, 键位索引, 布尔值)"
Mem-->>State : "更新后的keys缓冲"
State-->>Text : "生成文本事件(包含InputEvent头+字符编码)"
Text-->>外部 : "序列化为ArrayBuffer"
图表来源
详细组件分析
日志系统（前端与后端）
- 前端简易日志（logger.js）
- 开关控制：enable/disable 切换 isDebug 标志，后续 debug/info/log/warn/error 仅在开启时输出。
- 使用建议：开发阶段调用 enable，发布版本调用 disable；或结合构建脚本条件编译。
- 后端结构化日志（log.ts）
- 级别定义：none/error/warn/log/info 五级；parseLogLevel 支持字符串解析。
- 输出格式：统一 ISO 时间戳与大写级别前缀；按级别选择 console.error/warn/info/log。
- 控制策略：setLogLevel 设置全局级别；当级别为 none 时不输出任何内容。
flowchart TD
Start(["开始"]) --> SetLevel["设置日志级别(setLogLevel)"]
SetLevel --> Parse["解析字符串级别(parseLogLevel)"]
Parse --> LogCall["log(级别, 参数...)"]
LogCall --> Check{"级别允许输出?"}
Check --> |否| Exit["结束(不输出)"]
Check --> |是| Format["格式化时间戳与级别前缀"]
Format --> Console["按级别输出(console.*)"]
Console --> Exit
图表来源
章节来源
内存辅助工具（MemoryHelper）
- 功能概述
- writeSingleBit：对指定 bitOffset 的位进行置位/清位，底层通过 Uint8Array 访问目标字节。
- sizeOfInt：返回整型字节数常量，用于事件头与数据之间的边界计算。
- 复杂度与性能
- 单次写入为 O(1)，空间开销极小；适合高频输入事件的布尔标志位压缩存储。
- 典型用法
- 在键盘/鼠标/手柄状态类中，使用该工具将布尔标志位紧凑写入缓冲区，减少带宽占用。
flowchart TD
S(["进入writeSingleBit"]) --> View["创建Uint8Array视图"]
View --> Index["计算字节索引(index)"]
Index --> Offset["计算位偏移(bitOffset)"]
Offset --> Load["读取原字节值(byte)"]
Load --> Mask["构造掩码(1<<bitOffset)"]
Mask --> Op{"value为真?"}
Op --> |是| Or["按位或置位"]
Op --> |否| And["按位与清位"]
Or --> Store["写回新字节"]
And --> Store
Store --> E(["退出"])
图表来源
章节来源
字符数字转换工具（CharNumber 与 Keymap）
- CharNumber
- 将按键键名映射到数值编码，用于文本事件生成与键盘状态记录。
- Keymap
- 将 KeyboardEvent.code 映射到内部键位索引，配合 MemoryHelper 写入 keys 缓冲。
- 文本事件生成
- TextEvent.create 组合 InputEvent 头与字符编码，最终序列化为 ArrayBuffer。
classDiagram
class CharNumber {
+映射表
}
class Keymap {
+映射表
}
class KeyboardState {
+buffer : ArrayBuffer
+format : Number
}
class TextEvent {
+create(deviceId, event, time) TextEvent
+buffer : ArrayBuffer
}
KeyboardState --> Keymap : "键位索引"
KeyboardState --> CharNumber : "字符编码"
TextEvent --> KeyboardState : "组合InputEvent头"
图表来源
章节来源
指针校正工具（PointerCorrector）
- 功能概述
- 将浏览器坐标系（clientX/Y）转换为视频坐标系，考虑元素内黑边（Letterbox）补偿与视频宽高比。
- 提供 letterBoxType、letterBoxSize、contentRect 等属性，便于精确映射。
- 关键步骤
- 原点归零：减去元素左上角偏移。
- Y轴反转：浏览器坐标系向下为正，视频坐标系向上为正。
- 黑边补偿：减去 letterbox 的 x/y 偏移。
- 比例映射：按 contentRect 与 video 尺寸比缩放。
- 适用场景
- 视频播放器内点击/触摸区域映射、远程输入定位、跨屏适配。
flowchart TD
In(["输入: [clientX, clientY]"]) --> SubOrigin["减去元素左上角偏移"]
SubOrigin --> FlipY["Y轴反转(height - y)"]
FlipY --> AddLB["减去黑边偏移(x,y)"]
AddLB --> Scale["按contentRect与video尺寸比缩放"]
Scale --> Out(["输出: [videoX, videoY]"])
图表来源
章节来源
依赖关系分析
- 输入设备模块（inputdevice.js）依赖：
- MemoryHelper：用于将布尔标志位写入缓冲。
- CharNumber：用于文本事件中的字符编码。
- Keymap：用于将 KeyboardEvent.code 转换为内部键位索引。
- 其他：MouseButton、GamepadButton、TouchPhase、TouchFlags 等常量与枚举。
- 指针校正工具（pointercorrect.js）依赖：
- HTMLVideoElement 的 getBoundingClientRect 获取元素尺寸与偏移。
- LetterBoxType 枚举与 contentRect 计算逻辑。
graph LR
ID["inputdevice.js"] --> MH["memoryhelper.js"]
ID --> CN["charnumber.js"]
ID --> KM["keymap.js"]
ID --> MB["mousebutton.js"]
ID --> GPB["gamepadbutton.js"]
ID --> TP["touchphase.js"]
ID --> TF["touchflags.js"]
PC["pointercorrect.js"] --> DOM["HTMLVideoElement<br/>getBoundingClientRect()"]
图表来源
章节来源
性能考量
- 内存辅助（MemoryHelper）
- O(1) 位写入，适合高频输入事件；注意避免频繁创建 ArrayBuffer，复用现有缓冲可降低分配开销。
- 日志输出
- 前端：isDebug 控制，避免在生产环境输出；建议在打包阶段移除调试日志以减少运行时开销。
- 后端：通过 setLogLevel 限制输出级别，生产环境建议仅输出 error/warn；格式化字符串与级别前缀为常量，开销可控。
- 指针校正
- map 为纯数学运算，复杂度低；letterBoxType/letterBoxSize/contentRect 可缓存于实例字段，减少重复计算。
故障排查指南
- 日志不输出
- 前端：确认已调用 enable；检查 isDebug 是否被其他逻辑覆盖。
- 后端：确认 setLogLevel 已正确设置；若级别为 none，则不会输出任何内容。
- 文本事件字符异常
- 检查 CharNumber 中是否存在目标键名映射；确保 KeyboardEvent.key 与映射一致。
- 指针映射不准
- 确认 HTMLVideoElement 的尺寸与样式（如 object-fit）未引入额外缩放；必要时在 PointerCorrector.reset 中传入最新尺寸。
- 验证 letterBoxType 与 letterBoxSize 计算结果是否符合预期。
章节来源
结论
本实用工具模块围绕“日志、内存、字符、指针”四大主题，提供了简洁高效的实现：
- 日志系统兼顾前端与后端，满足开发与生产的差异化需求；
- 内存辅助工具以位级写入为核心，支撑输入事件的紧凑序列化；
- 字符数字转换工具完善了键盘事件到内部表示的映射；
- 指针校正工具解决了视频播放场景下的坐标适配问题。
建议在实际项目中：
- 将日志级别纳入构建配置，按环境自动切换；
- 在输入设备状态序列化中优先使用 MemoryHelper 进行位级压缩；
- 对文本事件生成进行单元测试覆盖，保证字符映射一致性；
- 在视频播放器中使用 PointerCorrector 进行坐标映射与黑边补偿。
附录
使用示例（路径指引）
- 启用前端调试日志
- 设置后端日志级别
- 参考：log.ts:11-24
- 生成文本事件
- 按位写入布尔标志
- 指针坐标映射
测试参考
- 指针校正单元测试
- 内存辅助单元测试
- 输入设备与文本事件测试