deck.gl 事件管理模块拆分离析:从 EventManager 到独立库 mjolnir.js 的架构演进

原创2026-09-13 18:17:541,383 阅读
文章标签:数据可视化前端3D渲染图表库GIS图形学

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 为独立模块设定了三个质量门槛:

  1. Tests:明确记录"already has a strong test suite",即 EventManager 在拆分前就已具备扎实的测试基础,拆分时测试用例整体随迁;
  2. Documentation:文档使用 ocular(vis.gl 生态自研的文档工具链)构建,参考文档(reference documentation)已部分就位,RFC 建议补充 Usage 类使用文档;
  3. 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)片段应如何处理?

作者给出了四个候选方向的利弊权衡:

  1. 放进 event-manager 仓库:不合适——控制器是特殊用途组件,与通用的 EventManager 定位不符("They don't really fit into an event-manager repo");
  2. 放进 viewport-mercator-project:同样不合适(原文"Putting them in viewport-mercator-project is also...",后文未完成,但语境明确表示否定);
  3. 为控制器单独建仓库:作者认为这有点过度——会滑向"微仓库世界"("going a little too far into the micro-repo world");
  4. 继续容忍两处重复:需要评估实际成本("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,它的贡献可以概括为三点:

  1. 边界划分:精确界定"事件管理层"(拆出)与"控制器层"(暂留)的边界,为模块化提供了可执行的切割清单;
  2. 命名与定位:确立 mjolnir.js 作为 Hammer.js 扩展的独立模块身份,并配套测试、文档(ocular)与跨设备示例三项发布门槛;
  3. 生态愿景:明确拆分的终极目标是在 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)"的完整认知闭环。

登录后查看全文
deck.gl