@locus/interaction

Locus 交互层 - 为动画引擎提供交互能力

安装

``bash
npm install @locus/interaction
`

功能特性

- 可拖拽组件: 点、线段、贝塞尔曲线等
- 滑块控件: 数值参数调节
- 约束系统: 水平、垂直、网格、圆形路径等
- 手势管理: 拖拽、键盘控制
- 交互会话: 暂停动画、等待用户操作、验证结果
- 反馈系统: 成功/错误动画反馈
- 播放集成: 与播放系统无缝集成

快速开始

`typescript
import {
InteractionManager,
InteractivePoint,
horizontal,
} from '@locus/interaction';

// 创建可拖拽点
const point = new InteractivePoint({
position: [100, 100],
constrain: horizontal(100), // 只能水平移动
onMove: pos => console.log('位置:', pos),
});

// 创建交互管理器
const manager = new InteractionManager({
canvas: document.querySelector('canvas'),
});

// 注册组件
manager.registerComponent(point);

// 开始交互会话
manager.startSession({
id: 'demo',
components: [point],
validation: {
type: 'position',
target: [200, 100],
tolerance: 10,
},
onSuccess: () => manager.showSuccess('正确!'),
onFail: () => manager.showError('再试一次'),
});
`

模块结构

`
@locus/interaction
├── math/ # 向量、矩阵运算
├── constraints/ # 约束系统
├── gestures/ # 手势管理
├── controls/ # 会话、验证、反馈
├── context/ # 上下文管理
├── components/ # 交互组件
└── integration/ # 播放集成
`

约束系统

`typescript
import {
horizontal, // 水平约束
vertical, // 垂直约束
grid, // 网格吸附
circular, // 圆形路径
line, // 直线路径
bounds, // 边界限制
compose, // 约束组合
} from '@locus/interaction';

// 组合约束
const constraint = compose(
grid({size: 10}),
bounds({xMin: 0, xMax: 500, yMin: 0, yMax: 300}),
);
`

验证系统

`typescript
import {Validators} from '@locus/interaction';

// 位置验证
const posValidator = Validators.position([100, 100], 10);

// 数值验证
const valValidator = Validators.value(50, 1);

// 组合验证
const combined = Validators.all(
Validators.range(0, 100),
Validators.custom(n => n % 2 === 0),
);
`

播放集成

`typescript
import {PlaybackIntegration} from '@locus/interaction';

const integration = new PlaybackIntegration({
controller: myPlaybackController,
triggers: [
{
frame: 100,
session: {
id: 'quiz-1',
components: [point],
validation: {type: 'position', target: [200, 200], tolerance: 10},
autoContinue: true,
},
},
],
});
``

API 文档

详细 API 文档请参阅 src/API.ts

版本

当前版本: 0.3.0

License

MIT