SamsaraJS 输入模块指南:鼠标、触摸与 pinch/scale/rotate 手势识别实战

原创2026-10-15 15:17:571,910 阅读
文章标签:前端UI库/组件

SamsaraJS 输入模块指南:鼠标、触摸与 pinch/scale/rotate 手势识别实战

SamsaraJS 输入模块是构建连续 UI(Continuous UI)的核心一环:它把鼠标、触摸、滚轮以及双指手势统一成 start / update / end 三种标准事件流,让你用同一套代码同时驱动桌面与移动端交互。本文带你快速掌握 samsara/inputs/ 目录下的全部输入类,并实战演示 pinch(捏合)、scale(缩放)、rotate(旋转)三种手势识别的用法。

先认识一个典型场景:连续 UI 里输入是怎么用的

想象一下 Google Now 卡片界面:手指一滑,搜索栏上浮、背景山脉图随动、卡片弹性收起——所有元素都在"跟着你的手"动。SamsaraJS 的 GoogleNow 示例 就是这样实现的,背景山脉图正是由输入事件持续驱动缩放与位移:

SamsaraJS 连续UI 输入模块驱动的 GoogleNow 示例背景山脉动效素材

SamsaraJS 手势输入驱动的 GoogleNow 电影卡片示例素材

山脉元素的动画逻辑在 App.js 中,通过 Transform.scale 把输入值映射为 3D 变换。

输入模块全家福:7 个输入类速览

samsara/inputs/index.js 导出了 7 个输入类,它们都继承自流(Stream)架构,订阅后会自动把 DOM 原始事件转换成统一的载荷:

输入类 监听源 用途 源码位置
MouseInput mousedown/move/up 鼠标拖拽、点击 MouseInput.js
TouchInput touchstart/move/end 触摸滑动、多点跟踪 TouchInput.js
ScrollInput wheel 事件 滚轮 / 触控板滚动 ScrollInput.js
PinchInput 双指触摸 双指距离变化(捏合量) PinchInput.js
ScaleInput 双指触摸 缩放比例 ScaleInput.js
RotateInput 双指触摸 旋转角度 RotateInput.js
GenericInput 任意多个输入 多输入统一入口 GenericInput.js

统一事件模型:无论鼠标还是触摸,事件都被归一化为:

  • start —— 按下(mousedown / touchstart)
  • update —— 移动中(mousemove / touchmove)
  • end —— 释放(mouseup / touchend)

每次事件都会携带一组现成计算好的载荷数据,包括:x/y(屏幕坐标)、value(相对起点的位移)、delta(相邻两次事件的增量)、velocity(像素/秒速度)、cumulate(累计值)、event(原始 DOM 事件)。这套载荷在 MouseInput.js 的文档注释中有完整说明。

💡 速度(velocity)特别有价值:你可以用它实现"甩一下松手后继续惯性滑动"的效果,配合 Transitions.Inertia 过渡类即可。

GenericInput:鼠标 + 触摸一套代码搞定

跨端开发最常见的诉求是:桌面端用鼠标、移动端用触摸,但业务逻辑只想写一份。GenericInput 就是为此设计的"多路输入统一入口",注册方式见 GenericInput.js 的示例注释:

// 第一步:全局注册输入类(在 main.js 中执行一次)
GenericInput.register({
    touch: TouchInput,
    mouse: MouseInput
});

// 第二步:任意视图里按名字组合多个输入
var gestureInput = new GenericInput(
    ['mouse', 'touch'],
    {direction: GenericInput.DIRECTION.X}
);
gestureInput.subscribe(surface);   // 订阅到某个 Surface 上

gestureInput.on('start',  function(payload) { /* ... */ });
gestureInput.on('update', function(payload) { /* ... */ });
gestureInput.on('end',    function(payload) { /* ... */ });

官方示例 SideMenu/js/main.js 正是这样注册 mouse 和 touch,然后在 Content.js 中创建 GenericInput 并绑定到可拖拽的蓝色内容区上——无论是鼠标拖拽还是手指滑动,都能把侧边抽屉平滑拉开。

SamsaraJS 手势输入示例 GoogleNow 导航卡片中的地图交互素材

GenericInput 还提供 addInput / unsubscribeInput / setOptions 等方法,可以随时动态增删输入源或批量修改所有输入的配置。

手势识别实战:pinch、scale、rotate 三件套

双指手势类都继承自内部的 TwoFingerInput(基类名带下划线前缀,表示"用于继承、不直接实例化")。它封装了双指距离、角度、中心点的几何计算,例如:

  • calculateDistance —— 两指间距离(源码)
  • calculateAngle —— 两指连线相对 X 轴的夹角,基于 Math.atan2
  • calculateCenter —— 两指中点,常用于"以哪一点为中心缩放"

1. ScaleInput:缩放比例识别

ScaleInput 输出的是一个比例值:value = 当前两指距离 / 起始两指距离(见 ScaleInput.js 的注释)。

  • 两指保持原位:value ≈ 1
  • 张到两倍距离:value ≈ 2
  • 捏到一半:value ≈ 0.5

最典型的用法是驱动一个元素的 Transform.scale:

var scaleInput = new ScaleInput();
scaleInput.subscribe(surface);

scaleInput.on('update', function(payload) {
    // 把缩放比例映射为 3D transform
    el.transform = Transform.scale([payload.value, payload.value]);
});

载荷里还包含 center(两指中点),可以把缩放中心精确对齐到用户捏合的位置,体验会自然得多。

2. PinchInput:捏合位移识别

PinchInput 与 ScaleInput 同源,但 value 是两指间的绝对距离(像素),delta 是相邻两帧距离的差值(载荷说明)。

适合的场景:

  • 图片查看器里"捏合放大/缩小",用 delta 直接累加到当前缩放
  • 地图类 UI 中把捏合量映射为视野推拉
  • 需要区分"捏合"与"整体移动"时,PinchInput 关注的是距离变化本身

一个小细节:PinchInput 默认 rails: true(DEFAULT_OPTIONS),如果你指定了 direction,正交方向上的运动会被抑制,保证手势判定更稳定。

3. RotateInput:双指旋转识别

RotateInput 基于 calculateAngle 计算两指连线的角度变化,载荷中:

  • value —— 累计旋转角(弧度)
  • delta —— 本帧角度增量
  • velocity —— 角速度(弧度/秒)

用法上通常把 value 映射到 Transform.rotateZ,用户双指一拧,元素就跟着转:

var rotateInput = new RotateInput();
rotateInput.subscribe(surface);

rotateInput.on('update', function(payload) {
    el.transform = Transform.rotateZ(payload.value);
});

⚠️ 注意:calculateAngle 在设置了 direction(单轴投影)时会返回 0(见 TwoFingerInput.js)。旋转手势必须保持二维输入,不要指定 direction。

底层功臣:TouchTracker

双指手势之所以能准确计算速度,靠的是 TouchTracker:它记录每个触摸点的历史轨迹(track/memory 可配置),让 TouchInput 能够算出可靠的 velocity 与 delta。你一般不需要直接用它,但理解它有助于调优 track(最大同时跟踪手指数)和 limit(触摸数量上限)。

常用配置参数速查

几乎所有输入类共享同一套核心选项:

选项 默认值 说明
scale 1 输入响应缩放系数,>1 更灵敏,<1 更迟钝
direction undefined 投影到单轴:DIRECTION.X(0)或 DIRECTION.Y(1);不设置则保留二维
rails false 指定 direction 后,抑制正交方向的运动,避免"斜着拖"干扰主轴
track 1(TouchInput) 最多同时跟踪的触摸点数,双指手势默认 2
limit Infinity(TouchInput) 触摸数量上限,达到后不再派发事件

一个实用技巧:做横向轮播时设 direction: X, rails: true,纵向误触就不会干扰横向翻页;反过来纵向滚动列表则用 direction: Y。

小结:输入模块的核心思路

  • 事件归一化:鼠标、触摸、滚轮、双指手势全部映射为 start/update/end 三态流
  • 载荷开箱即用:value、delta、velocity、cumulate 都已算好,直接喂给 Transitionable 或 Transform 即可
  • GenericInput 统一多端:注册一次,任意视图自由组合输入源
  • 双指三件套:ScaleInput 管比例、PinchInput 管距离、RotateInput 管角度,全部以两指中点 center 为参考

想动手体验?可以打开仓库里的 examples/SideMenu/(GenericInput 实战)和 examples/GoogleNow/(输入驱动连续动画)两个示例,源码注释非常详尽,是学习 SamsaraJS 输入模块的最佳起点。更多 API 细节可查阅仓库内的 docs/ 参考文档。

登录后查看全文
samsara