React时间轴编辑器：低代码可视化动画编排工具

React时间轴编辑器：低代码可视化动画编排工具

【免费下载链接】react-timeline-editorreact-timeline-editor is a react component used to quickly build a timeline animation editor.项目地址: https://gitcode.com/gh_mirrors/re/react-timeline-editor

React时间轴编辑器是一款基于React生态的低代码可视化组件，专注于快速构建时间轴动画编辑界面。通过直观的拖拽操作和灵活的配置选项，开发者可轻松实现多轨道时间线管理、动画事件编排和实时预览功能，适用于视频剪辑、互动课件、动画制作等场景。核心优势包括：TypeScript全类型支持、零侵入式集成、丰富的自定义钩子和完善的事件系统。

🚀 核心功能一览

多轨道时间线管理

支持无限层级轨道嵌套，每个轨道可独立配置时间范围和显示样式，满足复杂动画序列编排需求。轨道间支持拖拽排序和层级调整，配合智能吸附功能确保时间对齐精度。

高精度时间控制

内置毫秒级时间计算引擎，提供网格吸附（Grid Snap）和辅助线吸附（Auxiliary Line Snap）两种对齐模式，可通过配置步长实现从10ms到1s的精度控制。

实时预览与交互

集成播放器控件，支持播放/暂停、速度调节（0.5x-2x）和时间轴缩放，所有编辑操作实时反馈到预览窗口，实现"所见即所得"的开发体验。

事件驱动架构

提供从基础点击到复杂拖拽的完整事件体系，包括：

• 时间轴滚动事件（onScroll）
• 轨道项拖拽事件（onItemDrag）
• 时间变更事件（onTimeChange）
• 播放状态事件（onPlayStatusChange）

⚙️ 环境准备

系统要求

• Node.js 14.0.0+
• npm 6.0.0+ 或 yarn 1.22.0+
• React 16.8.0+（支持Hooks）

安装步骤

1. 克隆项目代码库

git clone https://gitcode.com/gh_mirrors/re/react-timeline-editor cd react-timeline-editor

2. 安装项目依赖

# 使用npm npm install # 或使用yarn yarn install

3. 构建核心包

# 编译engine核心引擎 cd packages/engine npm run build # 编译timeline组件 cd ../timeline npm run build

💡技巧提示：使用yarn workspace命令可一次性构建所有包：

yarn run build:all

🏃 5分钟启动编辑器

基础集成示例

1. 导入核心组件

import React from 'react'; import TimelineEditor from '@xzdarcy/react-timeline-editor'; import type { TimelineData, TimelineConfig } from '@xzdarcy/react-timeline-editor';

2. 定义初始数据

const initialData: TimelineData = { tracks: [ { id: 'track-1', name: '动画轨道', items: [ { id: 'item-1', start: 0, // 开始时间（ms） duration: 5000, // 持续时间（ms） content: '播放动画：奶牛', style: { backgroundColor: '#7b61ff' } } ] } ] };

3. 渲染编辑器

const App = () => { return ( <div style={{ height: '600px', width: '100%' }}> <TimelineEditor data={initialData} config={{ gridStep: 1000, // 网格步长1秒 snapToGrid: true, // 启用网格吸附 zoom: 1.0, // 初始缩放比例 showCursor: true // 显示时间光标 }} onItemDrag={(item, trackId) => { console.log(`Item ${item.id} moved to track ${trackId}`); }} /> </div> ); }; export default App;

4. 启动开发服务

cd packages/example npm run dev

打开浏览器访问http://localhost:3000即可看到运行中的时间轴编辑器。

🔧 深度配置指南

核心配置项决策表

TypeScript接口规范

TimelineConfig接口定义

interface TimelineConfig { /** 网格步长（毫秒） */ gridStep?: number; /** 是否启用网格吸附 */ snapToGrid?: boolean; /** 是否启用辅助线吸附 */ snapToAuxiliaryLine?: boolean; /** 初始缩放比例（0.5-2.0） */ zoom?: number; /** 时间轴高度 */ height?: number; /** 轨道高度 */ trackHeight?: number; /** 显示时间光标 */ showCursor?: boolean; /** 启用虚拟滚动 */ virtualScroll?: boolean; /** CSS类名前缀 */ classPrefix?: string; }

💡 实战技巧

1. 自定义轨道样式

通过trackRenderer属性自定义轨道渲染：

<TimelineEditor // ...其他配置 trackRenderer={(track, items) => ( <div className="custom-track"> <div className="track-header" style={{ backgroundColor: track.color }}> {track.name} </div> <div className="track-items">{items}</div> </div> )} />

配合CSS自定义：

.custom-track .track-header { height: 30px; line-height: 30px; padding: 0 10px; color: white; border-radius: 4px 4px 0 0; }

2. 实现自定义吸附规则

通过getSnapPosition回调定制吸附逻辑：

<TimelineEditor // ...其他配置 getSnapPosition={(position, item) => { // 实现每2秒强制吸附 const base = Math.floor(position / 2000) * 2000; return Math.abs(position - base) < 100 ? base : position; }} />

3. 集成外部播放器

通过onPlayStatusChange事件同步外部播放器：

const [currentTime, setCurrentTime] = useState(0); const [isPlaying, setIsPlaying] = useState(false); return ( <div> <TimelineEditor // ...其他配置 currentTime={currentTime} isPlaying={isPlaying} onPlayStatusChange={(status) => { setIsPlaying(status); // 同步到外部播放器 if (status) { videoRef.current.play(); } else { videoRef.current.pause(); } }} onTimeChange={(time) => { setCurrentTime(time); videoRef.current.currentTime = time / 1000; }} /> <video ref={videoRef} /> </div> );

🤔 常见问题

Q: 如何解决拖拽卡顿问题？

A: 当轨道项超过50个时，建议：

1. 启用virtualScroll: true开启虚拟滚动
2. 简化项渲染内容，避免复杂组件嵌套
3. 调整rowHeight减小渲染区域

Q: 如何实现时间轴反向滚动？

A: 通过监听onScroll事件自定义滚动逻辑：

<TimelineEditor onScroll={(scrollLeft) => { // 实现水平滚动限制 if (scrollLeft < 0) return 0; return scrollLeft; }} />

Q: 如何导出时间线数据为JSON？

A: 利用onDataChange事件实时保存数据：

<TimelineEditor onDataChange={(data) => { localStorage.setItem('timeline-data', JSON.stringify(data)); }} />

📄 许可证信息

本项目采用MIT许可证，详细信息请参见项目根目录下的LICENSE文件。

【免费下载链接】react-timeline-editorreact-timeline-editor is a react component used to quickly build a timeline animation editor.项目地址: https://gitcode.com/gh_mirrors/re/react-timeline-editor