repository·master·Indexed 21 days ago
https://github.com/xzdarcy/react-timeline-editorA React component for building timeline animation editors. It provides a structured interface to manage rows, actions, and effects, featuring draggable action blocks, customizable scale properties, grid and auxiliary line snapping, and row reordering. The library includes a decoupled Timeline Engine Runner for playback control, including current time management and playback speed.
The Runner is a decoupled system designed to execute the data produced by the editor. It provides core playback capabilities such as setting the current time and controlling the running rate (playback speed).
While the runner provides the logic, it does not provide default UI styles. You are responsible for implementing the visual representation of the playback controls and the playback state. You can extend the runner's capabilities by defining specific behaviors (e.g., audio playback, animation playback) within each TimelineEffect.
The library provides three main categories of capabilities:
When using @xzdarcy/timeline-engine, be aware of the following technical characteristics:
React is marked as an external dependency and will not be bundled into the engine package. You must provide React in your host environment.The TimeLineEffectSource defines how and when an effect's source is triggered during playback. It supports the following trigger conditions:
start: Triggered when the runner starts playing, if the time is within the current action time range.enter: Triggered when entering the current action time area from a non-action time area.update: Triggered every frame when playing the current action (including reRender), and also triggered during reRender.leave: Triggered when leaving the current action time area.stop: Triggered when the runner pauses, if the time is within the current action time range.import { TimeLineEffectSource } from '@src/api/TimelineEffect';To use the editor, import the Timeline component along with the TimelineEffect and TimelineRow types. You must provide two main props:
editorData: An array of TimelineRow objects defining the rows and their associated actions (start time, end time, and effect ID).effects: A record mapping effect IDs to TimelineEffect objects, which define the metadata for the effects applied to actions.This setup creates a functional timeline editor with mock data.
import { Timeline, TimelineEffect, TimelineRow } from '@xzdarcy/react-timeline-editor';
import React from 'react';
const mockData: TimelineRow[] = [{
id: "0",
actions: [
{
id: "action00",
start: 0,
end: 2,
effectId: "effect0",
},
],
},
{
id: "1",
actions: [
{
id: "action10",
start: 1.5,
end: 5,
effectId: "effect1",
}
],
}]
const mockEffect: Record<string, TimelineEffect> = {
effect0: {
id: "effect0",
name: "效果0",
},
effect1: {
id: "effect1",
name: "效果1",
},
};
const TimelineEditor = () => {
return (
<Timeline
editorData={mockData}
effects={mockEffect}
/>
);
};You can synchronize the scrolling behavior of external UI elements (such as lists or other data structures) with the timeline editor. This allows users to scroll through a list of items while the timeline view stays in sync with the corresponding time position.
// Implementation details are located in the demo source:
// @src/editor-demo/editor-scroll-sync/index.tsxThe react-timeline-editor supports auto-scrolling when a user drags an item. If the mouse moves beyond the current visible timeline range while dragging, the timeline will automatically scroll to keep the interaction within view. This behavior is typically configured within the editor's internal logic to enhance the user experience during timeline manipulation.
// Note: The specific implementation details are encapsulated within the editor component.
// Refer to the editor-demo/editor-auto-scroll/index.tsx for a concrete implementation example.To create a production build of the @xzdarcy/timeline-engine package, which includes minification and removal of console statements, use the following command:
npm run buildYou can restrict how a user interacts with an action in the timeline by using the movable and flexible properties.
movable: A boolean that determines if the action can be dragged to a different position on the timeline.flexible: A boolean that determines if the action can be resized (scaled) to change its duration.When using the editor, a runner is built-in. To control playback within the editor environment, you should use the provided TimelineState for convenient control.
Because the editor does not provide default runner styles, you must customize the UI. You can synchronize your custom playback UI with the engine by attaching listeners to capture running data changes.
// Example logic for running during editing
// Note: Actual implementation details depend on the TimelineState API
// Use listeners to capture data changes for custom UI synchronization.Auxiliary Line Snap is a feature that allows actions or cursors to automatically snap to other nearby actions or cursors when they are moved close to them. This improves precision when aligning multiple elements on the timeline.
To use this feature, you must enable the auxiliary line snap setting within your editor configuration.
// Note: The specific configuration key for enabling auxiliary line snap
// is implemented in the editor component's props or configuration object.
// Refer to the component API for the exact property name.