@locus/interaction

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

安装

npm install @locus/interaction

功能特性

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

快速开始

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/  # 播放集成

约束系统

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}),
);

验证系统

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),
);

播放集成

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