SamsaraJS 输入模块指南:鼠标、触摸与 pinch/scale/rotate 手势识别实战
SamsaraJS 输入模块指南:鼠标、触摸与 pinch/scale/rotate 手势识别实战
SamsaraJS 输入模块是构建连续 UI(Continuous UI)的核心一环:它把鼠标、触摸、滚轮以及双指手势统一成 start / update / end 三种标准事件流,让你用同一套代码同时驱动桌面与移动端交互。本文带你快速掌握 samsara/inputs/ 目录下的全部输入类,并实战演示 pinch(捏合)、scale(缩放)、rotate(旋转)三种手势识别的用法。
先认识一个典型场景:连续 UI 里输入是怎么用的
想象一下 Google Now 卡片界面:手指一滑,搜索栏上浮、背景山脉图随动、卡片弹性收起——所有元素都在"跟着你的手"动。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 并绑定到可拖拽的蓝色内容区上——无论是鼠标拖拽还是手指滑动,都能把侧边抽屉平滑拉开。
GenericInput 还提供 addInput / unsubscribeInput / setOptions 等方法,可以随时动态增删输入源或批量修改所有输入的配置。
手势识别实战:pinch、scale、rotate 三件套
双指手势类都继承自内部的 TwoFingerInput(基类名带下划线前缀,表示"用于继承、不直接实例化")。它封装了双指距离、角度、中心点的几何计算,例如:
calculateDistance—— 两指间距离(源码)calculateAngle—— 两指连线相对 X 轴的夹角,基于Math.atan2calculateCenter—— 两指中点,常用于"以哪一点为中心缩放"
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/ 参考文档。


