feat(timeline): 增强时间轴拖拽吸附与片段换位

This commit is contained in:
tongtong committed 2026-09-19 01:01:07 +08:00
1 parent 38dc27501a
commit 2015d8d3c3
7 files changed
+769 -78

No files matched your search

+189 -14
View File
@@ -46,7 +46,7 @@ import {
type CameraKeyframeValue,
type KeyframeTransformValue,
} from "../schema/timeline";
import type { MotionKind } from "../schema/directorProject";
import type { MotionClip, MotionKind } from "../schema/directorProject";
import {
TRAJECTORY_POINT_MIN_GAP,
getMotionEndTime,
@@ -207,6 +207,8 @@ type TimelineTrackKind = "object" | "camera" | "character";
/** 轨道拖拽的启动阈值(px):小于它当作普通点击,避免抢走关键帧的选中点击 */
const TRACK_DRAG_THRESHOLD_PX = 4;
/** 时间滑块(片段 / 关键帧)吸附阈值(px):拖动的边缘进入其它片段边缘 / 播放头这么近就吸上去 */
const SNAP_THRESHOLD_PX = 8;
/** 轨道行的纵向几何(拖拽开始时量一次就缓存,移动中只查表) */
interface TrackRowRect {
@@ -318,6 +320,7 @@ export function TimelinePanel() {
const updateCameraKeyframeValue = useDirectorStore((state) => state.updateCameraKeyframeValue);
const setCameraKeyframeTimes = useDirectorStore((state) => state.setCameraKeyframeTimes);
const applyCameraKeyframeToShot = useDirectorStore((state) => state.applyCameraKeyframeToShot);
const setActiveCamera = useDirectorStore((state) => state.setActiveCamera);
const setTimelineDuration = useDirectorStore((state) => state.setTimelineDuration);
const clearAllKeyframes = useDirectorStore((state) => state.clearAllKeyframes);
const selectedTrajectoryPoint = useDirectorStore((state) => state.selectedTrajectoryPoint);
@@ -375,6 +378,8 @@ export function TimelinePanel() {
const [draggingTrackKey, setDraggingTrackKey] = useState<string | null>(null);
const dropTargetRef = useRef<{ key: string; position: TimelineTrackDropPosition } | null>(null);
const dropIndicatorRef = useRef<HTMLDivElement | null>(null);
/** 吸附参考线:拖动片段 / 关键帧时,边缘吸到其它片段边缘或播放头处显示一条高亮竖线 */
const snapIndicatorRef = useRef<HTMLDivElement | null>(null);
/** 当前这一次指针手势(按下 → 超过阈值才算真的开始拖拽,否则当普通点击放行) */
const dragGestureRef = useRef<{
pointerId: number;
@@ -402,6 +407,8 @@ export function TimelinePanel() {
endEdge: number;
startClientX: number;
secondsPerPixel: number;
/** 拖拽开始时该角色的全部动作片段(用于「拖动换位」:依据原始布局做确定性重排) */
startClips?: MotionClip[];
} | null>(null);
/** 拖拽开始时一次性量好的行几何:移动中只查表,绝不在事件里读布局(强制同步布局 = layout thrashing) */
const trackRectsRef = useRef(new Map<string, TrackRowRect>());
@@ -553,6 +560,9 @@ export function TimelinePanel() {
setPlaying(false);
setPlayhead(time);
applyCameraKeyframeToShot(cameraId, value);
// 把该机位设为当前编辑机位:机位面板(CameraPanel)始终按 activeCameraId 编辑,
// 否则在「机位视角」或当前激活机位与选中物体不一致时,编辑的是别的机位,改动写不回这个关键帧。
setActiveCamera(cameraId);
setSelectedKeyframe({ kind: "camera", targetId: cameraId, keyframeId });
}
@@ -560,8 +570,17 @@ export function TimelinePanel() {
if (!selectedKeyframe) return;
if (selectedKeyframe.kind === "object" && selectedObject) {
updateKeyframeValue(selectedKeyframe.targetId, selectedKeyframe.keyframeId, snapshotObjectTransform());
} else if (selectedKeyframe.kind === "camera" && selectedShot) {
updateCameraKeyframeValue(selectedKeyframe.targetId, selectedKeyframe.keyframeId, snapshotShot());
} else if (selectedKeyframe.kind === "camera") {
// 直接读「这个关键帧所属机位」的当前机位值写回,而不是 selectedShot
// (selectedShot 是「选中物体关联的机位」,在机位视角 / 激活机位与选中物体不一致时会对错机位,导致改了角度却写不回关键帧)。
const camera = project.cameras.find((c) => c.id === selectedKeyframe.targetId);
if (camera) {
updateCameraKeyframeValue(selectedKeyframe.targetId, selectedKeyframe.keyframeId, {
position: [...camera.transform.position] as [number, number, number],
lookRotation: [...camera.lookRotation] as [number, number, number],
fov: camera.fov,
});
}
}
}
function handleDeleteSelected() {
@@ -831,17 +850,28 @@ export function TimelinePanel() {
}
/**
* 点轨道空白处 = 取消片段选中。
* 片段 / 关键帧自己的手势里会 stopPropagation,正常情况冒泡不到这里;
* 点轨道空白处 = 取消所有已选中的片段 / 关键帧 / 轨迹点 / 动作片段。
* 片段 / 关键帧 / 各类手柄自己的手势里会 stopPropagation,正常情况冒泡不到这里;
* 但手势可能因为尺寸未就绪等原因提前返回(那时还没走到 stopPropagation),
* 所以这里再按事件来源兜一层,避免把刚选中的片段立刻清掉。
* 所以这里再按事件来源兜一层,避免把刚选中的条目立刻清掉。
*/
function handleTimelineGridPointerDown(event: ReactPointerEvent<HTMLDivElement>) {
if (event.target instanceof Element && event.target.closest(".timeline-trajectory-bar, .timeline-keyframe")) {
// 点在交互元素(片段条 / 关键帧 / 拖拽把手 / 删除按钮 / 添加按钮 / 折叠开关)上不算空白处,
// 那些手势自己会处理选中,这里不能清掉它们。
if (
event.target instanceof Element &&
event.target.closest(
".timeline-trajectory-bar, .timeline-keyframe, .timeline-trajectory-trim, .timeline-clip-delete, .timeline-add-clip-button, .timeline-track-icon-button"
)
) {
return;
}
// 点轨道空白处:取消所有已选中项,让右侧编辑面板回到未选中态。
setSelectedClip(null);
setSelectedKeyframe(null);
selectTrajectoryPoint(null, null);
selectMotionClip(null);
}
/**
@@ -915,7 +945,8 @@ export function TimelinePanel() {
owner: TimelineTimeDragOwner,
times: number[],
startEdge: number,
deltaSeconds: number
deltaSeconds: number,
originalClips?: MotionClip[]
) {
const endEdge = times.length > 0 ? times[times.length - 1] : startEdge;
const minShift = -startEdge;
@@ -940,7 +971,8 @@ export function TimelinePanel() {
owner.clipId,
startEdge + shift,
times[times.length - 1] + shift,
times[0]
times[0],
originalClips
);
return;
}
@@ -1026,6 +1058,11 @@ export function TimelinePanel() {
endEdge,
startClientX: event.clientX,
secondsPerPixel: duration / laneWidth,
// 拖动作片段本体时记录按下时刻的全部片段,供「拖动换位」使用
startClips:
owner.kind === "motionClip"
? (project.objects.find((o) => o.id === owner.objectId)?.characterRig?.motionClips ?? []).map((c) => ({ ...c }))
: undefined,
};
// 拖动时冻结全站毛玻璃:条 / 关键帧每次重绘都会让背后 WebGL 画布重算一次模糊
@@ -1045,24 +1082,27 @@ export function TimelinePanel() {
event.preventDefault();
event.stopPropagation();
const deltaTime = (event.clientX - drag.startClientX) * drag.secondsPerPixel;
const rawDelta = (event.clientX - drag.startClientX) * drag.secondsPerPixel;
// 吸附:把要移动的边缘吸到其它片段边缘 / 播放头(磁性对齐)
const { delta, snappedTime } = computeSnappedDelta(drag, rawDelta);
showSnapIndicator(snappedTime);
if (drag.kind === "duration") {
scaleClipDuration(drag.owner, drag.startTimes, drag.startEdge, deltaTime);
scaleClipDuration(drag.owner, drag.startTimes, drag.startEdge, delta);
return;
}
if (drag.kind === "clip") {
shiftClip(drag.owner, drag.startTimes, drag.startEdge, deltaTime);
shiftClip(drag.owner, drag.startTimes, drag.startEdge, delta, drag.startClips);
return;
}
if (drag.kind === "trimStart") {
trimClipStart(drag.owner, drag.startTimes, drag.startEdge, deltaTime);
trimClipStart(drag.owner, drag.startTimes, drag.startEdge, delta);
return;
}
moveClipKeyframe(drag.owner, drag.startTimes, drag.index, drag.startEdge, deltaTime, drag.endEdge);
moveClipKeyframe(drag.owner, drag.startTimes, drag.index, drag.startEdge, delta, drag.endEdge);
}
function handleTimeDragEnd(event: ReactPointerEvent<HTMLElement>) {
@@ -1070,6 +1110,7 @@ export function TimelinePanel() {
if (!drag || drag.pointerId !== event.pointerId) return;
timeDragRef.current = null;
hideSnapIndicator();
document.body.classList.remove("is-timeline-dragging");
try {
@@ -1097,6 +1138,138 @@ export function TimelinePanel() {
};
}
type TimeDragGesture = NonNullable<typeof timeDragRef.current>;
/**
* 收集拖拽时可吸附的目标时刻:同轨道(同角色 / 同相机)其它片段的边缘 + 播放头。
* 过滤掉被拖元素自身当前的边缘 / 关键帧时刻,避免「吸回原处」导致无法小幅移动。
*/
function buildSnapTargets(drag: TimeDragGesture): number[] {
const targets: number[] = [playhead];
const { owner } = drag;
if (owner.kind === "motionClip") {
const obj = project.objects.find((o) => o.id === owner.objectId);
for (const c of obj?.characterRig?.motionClips ?? []) {
if (c.id === owner.clipId) continue;
targets.push(c.start);
if (Number.isFinite(c.end)) targets.push(c.end);
}
} else if (owner.kind === "trajectory") {
const track = project.timeline.tracks.find((t) => t.objectId === owner.objectId);
for (const k of track?.keyframes ?? []) {
if (k.id === owner.pointId) continue;
targets.push(k.time);
}
} else if (owner.kind === "camera") {
const track = project.timeline.cameraTracks.find((t) => t.cameraId === owner.cameraId);
for (const k of track?.keyframes ?? []) targets.push(k.time);
} else if (owner.kind === "motion") {
const obj = project.objects.find((o) => o.id === owner.objectId);
if (obj) {
const start = getMotionStartTime(obj, duration);
const end = getMotionEndTime(obj, duration, start);
targets.push(start, end);
}
}
const selfTimes: number[] = [];
if (drag.kind === "clip") selfTimes.push(drag.startEdge, drag.endEdge);
else if (drag.kind === "trimStart") selfTimes.push(drag.startEdge);
else if (drag.kind === "duration") selfTimes.push(drag.endEdge);
else if (drag.kind === "point") {
const t = drag.startTimes[drag.index];
if (typeof t === "number") selfTimes.push(t);
}
return targets.filter((tt) => !selfTimes.some((s) => Math.abs(tt - s) < 1e-6));
}
/**
* 收集「网格类」吸附目标:整帧边界(k/fps)+ 刻度网格主刻度线(与车道里画出的竖网格线一致)。
* 这是一组「静态基准线」,和动态的同轨片段边缘 / 播放头互补:离后者近时优先吸到后者
* (保留原有磁性对齐,可对齐到非整帧位置),否则吸到最近的整帧 / 刻度线。
*/
function buildGridSnapTargets(): number[] {
const targets: number[] = [];
// 刻度网格:主刻度线(与车道背景的竖网格线一致),便于吸附对齐到可见网格
for (const tick of getTimelineRulerTicks(duration)) {
targets.push(tick.value);
}
// 整帧:每帧边界(k/fps),视频按帧导出,关键帧落在整帧上更自然
const frameCount = Math.floor(duration * fps + 1e-6);
for (let k = 0; k <= frameCount; k += 1) {
const tick = k / fps;
if (tick <= duration + 1e-6) targets.push(tick);
}
return targets;
}
/**
* 把候选时刻吸附到最近的目标(在阈值内),否则原样返回。
*/
function snapTimeToTargets(candidate: number, targets: number[], thresholdSec: number): number {
let best = candidate;
let bestDist = thresholdSec;
for (const t of targets) {
const d = Math.abs(candidate - t);
if (d < bestDist) {
bestDist = d;
best = t;
}
}
return best;
}
/**
* 根据拖拽手势与原始位移算出「吸附后的位移」以及被吸附到的时刻(未吸附则为 null)。
* 条本体 / 左端把手吸附起点;右端把手吸附终点;关键帧吸附其自身时刻。
*/
function computeSnappedDelta(drag: TimeDragGesture, rawDelta: number): { delta: number; snappedTime: number | null } {
const thresholdSec = SNAP_THRESHOLD_PX * drag.secondsPerPixel;
let candidate: number;
let base: number;
if (drag.kind === "clip" || drag.kind === "trimStart") {
candidate = drag.startEdge + rawDelta;
base = drag.startEdge;
} else if (drag.kind === "duration") {
candidate = drag.endEdge + rawDelta;
base = drag.endEdge;
} else {
const t = drag.startTimes[drag.index] ?? 0;
candidate = t + rawDelta;
base = t;
}
// 第一阶段:吸附到同轨其它片段边缘 / 播放头(保留原有磁性对齐,可对齐到非整帧位置)。
const primarySnapped = snapTimeToTargets(candidate, buildSnapTargets(drag), thresholdSec);
let snapped = primarySnapped;
let didSnap = Math.abs(snapped - candidate) > 1e-6;
// 第二阶段:未吸到片段边缘 / 播放头时,再吸附到整帧 / 刻度网格(对齐到可见网格与帧边界)。
if (!didSnap) {
const gridSnapped = snapTimeToTargets(candidate, buildGridSnapTargets(), thresholdSec);
if (Math.abs(gridSnapped - candidate) > 1e-6) {
snapped = gridSnapped;
didSnap = true;
}
}
return { delta: snapped - base, snappedTime: didSnap ? snapped : null };
}
/** 显示 / 隐藏吸附参考线(直接改样式,不触发 React 重绘) */
function showSnapIndicator(time: number | null) {
const el = snapIndicatorRef.current;
if (!el) return;
if (time === null || duration <= 0) {
el.classList.remove("is-visible");
return;
}
const percent = Math.min(100, Math.max(0, (time / duration) * 100));
el.style.left = `${percent}%`;
el.classList.add("is-visible");
}
function hideSnapIndicator() {
snapIndicatorRef.current?.classList.remove("is-visible");
}
/** 时长把手支持键盘微调(左右方向键 ±0.1s,按住 Shift ±0.5s) */
function handleTimeHandleKeyDown(
event: ReactKeyboardEvent<HTMLElement>,
@@ -2076,6 +2249,8 @@ export function TimelinePanel() {
<div className="timeline-playhead" style={{ left: `${playheadPercent}%` }}>
<span className="timeline-playhead-knob" />
</div>
{/* 吸附参考线:拖动片段 / 关键帧时,边缘吸到其它片段边缘或播放头处显示 */}
<div className="timeline-snap-indicator" ref={snapIndicatorRef} />
</div>
</div>
</div>