deck.gl 事件管理模块拆分离析:从 EventManager 到独立库 mjolnir.js 的架构演进
deck.gl 事件管理模块拆分离析:从 EventManager 到独立库 mjolnir.js 的架构演进
导读
break-out-event-manager-rfc.md(位于 dev-docs/RFCs/v5.0/break-out-event-manager-rfc.md)是 deck.gl 在 v5.0 时代提出的一份架构级 RFC,核心主张是把 deck.gl 内部积累的 EventManager 事件处理层拆分为一个可独立发布、跨项目复用的 npm 模块——也就是后来的 mjolnir.js。读完本文,你将理解这套统一事件架构诞生的动机、模块拆分的具体范围与命名考量,并能在当前 deck.gl 仓库的源码中逐行印证 EventManager 与 mjolnir.js 的实际集成方式(包括手势识别器、事件路由与控制器消费),从而在自定义交互、调试手势冲突时具备源码级的判断力。
一、RFC 动机:跨框架重复的事件处理困局
该 RFC 由 Ib Green 与 Xiaoji Chen 于 2017 年 8 月提出,状态标注为 Implemented。它的起点指向另一份 Event Handling RFC,后者记录了 deck.gl、react-map-gl 乃至 luma.gl 中反复出现的事件处理代码重复问题。
三者的痛点高度一致:
- deck.gl 需要处理指针事件(pointer events)、触摸手势(touch gestures)与滚轮(wheel)事件;
- react-map-gl 作为与 deck.gl 同生态的地图 React 封装,存在几乎相同的输入处理需求;
- luma.gl 作为底层渲染框架,其遗留事件处理也被认为重复实现了
EventManager的大部分功能。
RFC 明确指出,EventManager 本身已经具备通用价值——它是 Hammer.js 的一次扎实扩展:既支持触摸手势,又统一处理指针事件,并构建在跨浏览器的统一架构之上。因此作者提出:event-manager 完全有资格拥有自己的独立仓库和模块,而不仅仅是 deck.gl 内部的一个类。
注意区分角色:这份 RFC 解决的是"把谁拆出去"与"拆成什么样"的问题,它假设 Event Handling RFC 中定义的
EventManager类已经存在并成熟(RFC 中明确说"Tests: already has a strong test suite"——测试套件已经很强),本 RFC 关注的是模块化与发布策略。
二、Step 1:把 EventManager 拆为独立模块 mjolnir.js
RFC 将拆分工作定义为三步走的第一步,并给出了完整落地方案。
2.1 命名:mjolnir.js
模块名称提议为 mjolnir.js。mjolnir 是北欧神话中雷神索尔的锤子,作者在 RFC 中说明这是一种对 hammer.js 的"间接致敬"(indirect homage)——既承接了 hammer 处理手势的定位,又通过新名字划清独立模块的身份边界。从当前仓库的 modules/core/package.json 可以看到,这一命名最终落地为真实的依赖声明:
"dependencies": {
"mjolnir.js": "^3.1.1"
}
deck.gl 的 core 模块以正式第三方依赖的方式消费 mjolnir.js,这正是 RFC 中"独立仓库和模块"目标的直接证据。
2.2 拆分范围:明确的边界
RFC 对首次拆分(initial breakout)划定了精确的包含/排除清单:
| 范围 | 内容 |
|---|---|
| 包含 | event-manager 及其内部类(如 key-input、wheel-input 等输入通道) |
| 包含 | 全部测试用例(test cases) |
| 包含 | 文档(documentation) |
| 排除 | 所有与 Controller 相关的代码(详见下文附录讨论) |
也就是说,首次拆分只动"事件管理层",不动"视图控制层"——控制器代码是否拆分、如何拆分被 RFC 明确列为不属于本 RFC 正式范畴的开放问题。
2.3 配套要求:测试、文档与示例
RFC 为独立模块设定了三个质量门槛:
- Tests:明确记录"already has a strong test suite",即 EventManager 在拆分前就已具备扎实的测试基础,拆分时测试用例整体随迁;
- Documentation:文档使用 ocular(vis.gl 生态自研的文档工具链)构建,参考文档(reference documentation)已部分就位,RFC 建议补充 Usage 类使用文档;
- Examples:至少提供一个桌面端与移动端均可运行的示例,以验证跨设备的手势能力。
三、源码印证:EventManager 在当前 deck.gl 中的真实集成
虽然该 RFC 描述的是 2017 年的拆分计划,但当前仓库(v9+ 时代)的源码完整保留了这条架构演进的痕迹,可作为拆分成功落地的第一手证据。
3.1 Deck 实例:EventManager 的创建与事件订阅
在 modules/core/src/lib/deck.ts 中,Deck 类通过 _createEventManager 方法实例化 mjolnir.js 的 EventManager:
private _createEventManager(root: HTMLElement): EventManager {
const eventManager = new EventManager(root, {
touchAction: this.props.touchAction,
recognizers: Object.keys(RECOGNIZERS).map((eventName: string) => {
const [RecognizerConstructor, defaultOptions, recognizeWith, requireFailure] =
RECOGNIZERS[eventName];
const optionsOverride = this.props.eventRecognizerOptions?.[eventName];
const options = {...defaultOptions, ...optionsOverride, event: eventName};
return {
recognizer: new RecognizerConstructor(options),
recognizeWith,
requireFailure
};
}),
events: {
pointerdown: this._onPointerDown,
pointermove: this._onPointerMove,
pointerleave: this._onPointerMove
}
});
for (const eventType in EVENT_HANDLERS) {
if (eventType === 'dblclick') {
// 使用 watch(被动监听),避免双击识别器被拾取系统意外启用
eventManager.watch(eventType, this._onEvent);
} else {
eventManager.on(eventType, this._onEvent);
}
}
return eventManager;
}
这段代码直接对应 RFC 描述的"EventManager 是 Hammer.js 的扩展"这一论断,并揭示了三个关键设计:
- recognizers(识别器):从
RECOGNIZERS常量构建 Hammer 风格的手势识别器,且支持通过Deck的eventRecognizerOptions属性对每个识别器做参数覆盖(optionsOverride),最终把识别器绑定到对应的事件名上; - 事件路由:
pointerdown/pointermove/pointerleave直连拾取系统(picking),而click/dblclick/panstart/panmove/panend等通过EVENT_HANDLERS映射到 deck.gl 的onClick/onDragStart/onDrag/onDragEnd回调; - dblclick 的特殊处理:被动监听(
watch)双击事件,使双击缩放只由控制器的doubleClickZoom选项决定,避免拾取系统误触发。
3.2 识别器拓扑与事件映射常量
modules/core/src/lib/constants.ts 集中定义了事件处理的两张关键表,是理解整个事件流的最短路径:
export const EVENT_HANDLERS = {
click: 'onClick',
dblclick: 'onClick',
panstart: 'onDragStart',
panmove: 'onDrag',
panend: 'onDragEnd'
} as const;
// Order matters: recognizeWith/requireFailure resolve by name, so a recognizer
// must be registered before any later entry can reference it.
export const RECOGNIZERS = {
multipan: [Pan, {threshold: 10, pointers: 2, trackpad: true}],
pinch: [Pinch, {trackpad: true}, null, ['multipan']],
pan: [Pan, {threshold: 1}, ['pinch'], ['multipan']],
dblclick: [Tap, {event: 'dblclick', taps: 2, enable: false}],
dblclickdrag: [DoubleClickDrag, {event: 'dblclickdrag', enable: false}, ['dblclick'], null],
click: [Tap, {event: 'click'}, ['dblclickdrag'], ['dblclick', 'dblclickdrag']]
} as const;
这张表直接体现了 Hammer.js 的 recognizeWith / requireFailure 识别器协同机制:
- multipan(双指平移):阈值 10 像素、要求 2 个触点,并支持 trackpad 合成输入;
- pinch(捏合缩放):trackpad 可用,且必须等 multipan 失败后才接管(
requireFailure: ['multipan']); - pan(单指/鼠标拖拽):阈值仅 1 像素,与 pinch 互相 recognizeWith、与 multipan 互斥;
- click / dblclick / dblclickdrag:三者构成优先级链——click 需要 dblclickdrag 失败、dblclick 需要 dblclickdrag 失败,双击系列默认
enable: false,避免给单击事件引入约 300ms 的延迟。
这与 docs/developer-guide/interactivity.md 中列出的内置事件回调(onHover、onClick、onDragStart、onDrag、onDragEnd)一一对应:应用层注册回调后,deck.gl 自动跟踪事件、运行拾取引擎,并把携带 PickingInfo 的结果回调给应用。
3.3 控制器:事件的上层消费者
RFC 附录中"控制器代码不随 event-manager 拆出"的决策,在当前源码中同样清晰可见:控制器仍留在 deck.gl 的 core 模块内,但它们全部以 mjolnir.js 的事件类型为输入。例如 modules/core/src/controllers/controller.ts 引入:
import type {
EventManager,
MjolnirEvent,
MjolnirGestureEvent,
MjolnirWheelEvent,
MjolnirKeyEvent
} from 'mjolnir.js';
并在 EVENT_TYPES(modules/core/src/controllers/controller.ts)中声明了控制器监听的全部事件族:
const EVENT_TYPES = {
WHEEL: ['wheel'],
PAN: ['panstart', 'panmove', 'panend'],
PINCH: ['pinchstart', 'pinchmove', 'pinchend'],
MULTI_PAN: ['multipanstart', 'multipanmove', 'multipanend'],
DOUBLE_CLICK: ['dblclick'],
DOUBLE_CLICK_DRAG: ['dblclickdragstart', 'dblclickdragmove', 'dblclickdragend', 'dblclickdragcancel'],
KEYBOARD: ['keydown']
} as const;
由此可以还原完整的事件分层:mjolnir.js(原生 DOM 事件 → 归一化的手势/指针/键盘事件)→ deck.gl EventManager(事件路由)→ 控制器(将手势翻译为 viewState 变化)与拾取系统(将指针位置翻译为 PickingInfo)。从源码结构看,globe-controller、orthographic-controller、terrain-controller(分别见 globe-controller.ts、orthographic-controller.ts、terrain-controller.ts)都直接消费 MjolnirGestureEvent / MjolnirWheelEvent 类型,进一步印证了这一分层在各类控制器中的统一性。
四、Step 2:react-map-gl 迁移到新模块
RFC 规划的第二步是:一旦新模块发布,立即用 mjolnir.js 替换 react-map-gl 中的事件处理实现("This should happen as soon as the new module is published")。
这一步的价值在于消除 deck.gl 与 react-map-gl 之间长期存在的重复实现。结合第 3 节的源码证据可以推断,迁移完成后,两个项目的交互层共享同一套事件归一化与手势识别逻辑,任何对 mjolnir.js 的修复(例如某个浏览器的手势兼容问题)都会自动惠及双方,这正是 RFC 反复强调的"避免在两处反复打补丁"("Having to regularly add fixes in two places is frustrating")的痛点解法。
五、附录一:MapController 是否也应拆分?
RFC 用一个专门附录讨论了不在本 RFC 正式范围但最棘手的问题:deck.gl 与 react-map-gl 共享的地图控制器(MapController)片段应如何处理?
作者给出了四个候选方向的利弊权衡:
- 放进 event-manager 仓库:不合适——控制器是特殊用途组件,与通用的
EventManager定位不符("They don't really fit into an event-manager repo"); - 放进 viewport-mercator-project:同样不合适(原文"Putting them in viewport-mercator-project is also...",后文未完成,但语境明确表示否定);
- 为控制器单独建仓库:作者认为这有点过度——会滑向"微仓库世界"("going a little too far into the micro-repo world");
- 继续容忍两处重复:需要评估实际成本("What is the practical cost of keep these duplicated?")。
RFC 没有强行给出答案,而是把问题留给社区与后续决策。从当前仓库状态看,控制器最终保留在 deck.gl core 模块内部(modules/core/src/controllers/ 目录),且仅依赖 mjolnir.js 的类型与事件而非控制器实现,这可以看作对选项 1、2 的否定与对"控制器留驻 deck.gl"这一默认路径的延续。
六、附录二:luma.gl 是否也接入 EventManager?
第二个附录讨论的是 luma.gl 的事件处理去留,同样标注为"不属于本 RFC 的正式部分"。
RFC 的核心担忧是框架栈体积:luma.gl 的遗留事件处理重复实现了 EventManager 的大部分功能,而当时团队正面临框架整体体积的顾虑("At a time when we are facing concerns about the size of our framework stack, duplicated functionality is something we want to avoid")。基于此,RFC 抛出了一组开放问题:
- luma.gl 的事件处理能否被
EventManager完全替换? - 还是 luma.gl 干脆不再内置事件处理,让示例直接引入 EventManager?
- 或者把 EventManager 与 luma.gl 的
AnimationLoop集成,追求"终极便利"? - 在 luma.gl 下一次大版本升级前,是否先写一个模拟
addEvents接口的薄包装以保持兼容? - API 兼容性如何取舍?是否直接发布 luma.gl 5.0(作者推测 luma.gl 的非 deck.gl 用户并不多,迁移成本可控)?
这些开放问题说明,mjolnir.js 的拆分从一开始就被设计为生态级复用——它不仅是 deck.gl 内部的重构,更是 vis.gl 三件套(deck.gl / react-map-gl / luma.gl)共享事件基础设施的第一步。
七、总结:一份 RFC 到一套通用事件架构
回顾 break-out-event-manager-rfc.md,它的贡献可以概括为三点:
- 边界划分:精确界定"事件管理层"(拆出)与"控制器层"(暂留)的边界,为模块化提供了可执行的切割清单;
- 命名与定位:确立
mjolnir.js作为 Hammer.js 扩展的独立模块身份,并配套测试、文档(ocular)与跨设备示例三项发布门槛; - 生态愿景:明确拆分的终极目标是在 deck.gl、react-map-gl 与 luma.gl 之间消除重复事件处理,为后续所有交互功能的迭代提供统一底座。
而这份 2017 年的 RFC 之所以值得今天重读,是因为它已完整兑现:当前仓库中 mjolnir.js 作为独立依赖被 modules/core/package.json 声明,Deck 通过 modules/core/src/lib/deck.ts 的 _createEventManager 完成事件管道装配,EVENT_HANDLERS 与 RECOGNIZERS 在 modules/core/src/lib/constants.ts 定义了完整的手势拓扑,而所有控制器则统一消费 MjolnirGestureEvent / MjolnirWheelEvent 等事件类型。想深入理解 deck.gl 交互机制,从这三个文件切入,再对照 docs/developer-guide/interactivity.md 的 onClick / onDrag / onHover 回调实践,即可形成"协议层(mjolnir.js)→ 路由层(EventManager)→ 消费层(Controller + Picking)"的完整认知闭环。