# @cloudgpt/timeline-editor 中文文档

规范地址：https://npmcn.com/package/%40cloudgpt/timeline-editor/

版本：1\.0\.0
npm 元数据更新时间：2025-08-13T09:42:47.661Z
中文译文更新时间：2026-11-10T03:28:31.751Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40cloudgpt/timeline-editor
原文对照：https://npmcn.com/package/%40cloudgpt/timeline-editor/?lang=original
项目主页：https://github.com/cloudgpt/timeline-editor#readme
源码仓库：https://github.com/cloudgpt/timeline-editor

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：269 kB，32 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：5 个
- peer 依赖：react ^15\.3\.0 \|\| ^16\.0\.0-alpha \|\| ^17\.0\.0 \|\| ^18\.0\.0 \|\| ^19\.0\.0，react-dom ^15\.3\.0 \|\| ^16\.0\.0-alpha \|\| ^17\.0\.0 \|\| ^18\.0\.0 \|\| ^19\.0\.0
- 首次发布：2025-08-13T09:42:47.029Z
- 最新版本发布：2025-08-13T09:42:47.340Z
- 近 30 天下载量：5644（2026-10-10 至 2026-11-08，npm 官方下载统计）
- 已发布版本数：1（近 12 个月 0 个）

## 中文简介

增强具有高级功能的回放时间线编辑器,包括主题系统,最长持续时间控制,光标定制,手柄造型,以及视频编辑应用程序的媒体支持等.

## 安装

```sh
npm install @cloudgpt/timeline-editor
```

也可以使用：`pnpm add @cloudgpt/timeline-editor`、`yarn add @cloudgpt/timeline-editor`、`bun add @cloudgpt/timeline-editor`

## README

# @ cloudgpt/ 时间线编辑器

[![npm version](https://img.shields.io/npm/v/@cloudgpt/timeline-editor.svg?style=flat-square)](https://www.npmjs.com/package/@cloudgpt/timeline-editor) [![npm downloads](https://img.shields.io/npm/dm/@cloudgpt/timeline-editor.svg?style=flat-square)](https://www.npmjs.com/package/@cloudgpt/timeline-editor)

**增强反应时间线编辑器** - 一个强大和内容丰富的时序编辑器组件,用于建立视频编辑应用程序、动画工具和媒体时序界面.

## 关键特性

-   🎨 **高级主题系统** - 全面定制的黑暗、光明和海洋主题
-   ⏱️ **最大持续时间控制** - 设定时限并验证行动界限
-   🎯 **自定义光标样式** - 全面控制光标外观和行为
-   🎛️ **专业人员** - 具有梯度效应的药丸形调整手柄大小
-   🎬 **视频框架支持** - 在时间表上提取和显示视频帧
-   🖼️ **图像条显示** - 图像平面预览,用于视觉动作
-   📐 **网格抓取** - 精确调整和定位
-   🎮 **拖动行辅助** - 为更好的UX提供视觉指导
-   🚀 **业绩优化** - 平滑动画和互动
-   📱 **响应设计** - 跨越不同屏幕大小的工作

## \* 安装

```bash
npm install @cloudgpt/timeline-editor
```

## 基本用途

```tsx
import { Timeline, TimelineEffect, TimelineRow } from '@cloudgpt/timeline-editor';
import React, { useState } 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: "Video Clip",
  },
  effect1: {
    id: "effect1", 
    name: "Audio Track",
  },
};

const TimelineEditor = () => {
  const [data, setData] = useState(mockData);
  
  return (
    <Timeline
      editorData={data}
      effects={mockEffect}
      onChange={setData}
      maxDuration={30} // Limit timeline to 30 seconds
      theme={{
        backgroundColor: '#191b1d',
        foregroundColor: '#ffffff',
        cursorColor: '#ff6b35',
      }}
      cursor={{
        cursorColor: '#ff6b35',
        cursorWidth: 2,
        cursorStyle: 'solid',
        showCursorHead: true,
      }}
      handles={{
        showHandles: true,
        handleOpacity: 0.3,
        handleHoverOpacity: 1,
      }}
      style={{ width: '100%', height: 400 }}
    />
  );
};
```

## 高级特性

### 主题配置

```tsx
const themeConfig = {
  backgroundColor: '#1a1a1a',
  foregroundColor: '#ffffff', 
  gridColor: 'rgba(255, 255, 255, 0.1)',
  actionBackgroundColor: '#2f3134',
  actionBorderColor: 'rgba(255, 255, 255, 0.2)',
  dragLineColor: '#ff6b35',
};

<Timeline theme={themeConfig} />
```

### 最大持续时间控制

```tsx
<Timeline
  maxDuration={60} // Limit to 60 seconds
  validateActionChange={({ action, row, start, end }) => {
    // Custom validation logic
    return end <= 60 && start >= 0;
  }}
/>
```

### 自定义光标样式

```tsx
const cursorConfig = {
  cursorColor: '#00ff88',
  cursorWidth: 3,
  cursorStyle: 'dashed',
  cursorOpacity: 0.8,
  showCursorHead: true,
  cursorShadow: '0 0 10px rgba(0,255,136,0.5)',
};

<Timeline cursor={cursorConfig} />
```

### 处理自定义

```tsx
const handleConfig = {
  showHandles: true,
  handleBackground: 'linear-gradient(180deg, #ff6b35, #ff4500)',
  handleBorderColor: 'rgba(255, 255, 255, 0.4)',
  handleOpacity: 0.4,
  handleHoverOpacity: 1,
};

<Timeline handles={handleConfig} />
```

## 媒体支助

增强的时间轴编辑器支持视频帧提取和图像预览:

```tsx
// Custom render function for media actions
const renderAction = (action, row) => {
  if (action.effectId === 'video') {
    return <VideoStrip src="/video/sample.mp4" start={action.start} end={action.end} />;
  }
  if (action.effectId === 'image') {
    return <ImageStrip src="/images/sample.jpg" start={action.start} end={action.end} />;
  }
  return null;
};

<Timeline getActionRender={renderAction} />
```

## \* 原文增强

此软件包是原版的增强版 `@xzdarcy/react-timeline-editor` 有重大改进:

-   **增强型系统** - 有综合接口的更好类型脚本支持
-   **高级造型** - 专业级外观设计和主题
-   **更好的业绩** - 优化渲染和互动处理
-   **扩展 API** - 更多的配置选项和定制能力
-   **错误修正** - 解决光标打磨和验证问题
-   **现代特征** - 支持现代反应模式和钩子

## 捐款

欢迎捐款! 请随意为错误和特性请求提交拉出请求或打开问题 .

## 许可证

麻省理工学院的执照 - 看 [自由主义](https://npmcn.com/package/%40cloudgpt/timeline-editor/LICENSE) 详细文件.

## 承认

基于杰出的工作 [@xzdarcy (英语)](https://github.com/xzdarcy) 在原反应-时间线编辑器上.

## 常见问题

### @cloudgpt/timeline-editor 是什么？

增强具有高级功能的回放时间线编辑器,包括主题系统,最长持续时间控制,光标定制,手柄造型,以及视频编辑应用程序的媒体支持等\.

### 如何安装 @cloudgpt/timeline-editor？

在项目目录运行 npm install @cloudgpt/timeline-editor，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：react（^15\.3\.0 \|\| ^16\.0\.0-alpha \|\| ^17\.0\.0 \|\| ^18\.0\.0 \|\| ^19\.0\.0）、react-dom（^15\.3\.0 \|\| ^16\.0\.0-alpha \|\| ^17\.0\.0 \|\| ^18\.0\.0 \|\| ^19\.0\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @cloudgpt/timeline-editor 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @cloudgpt/timeline-editor 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @cloudgpt/timeline-editor 可以商用吗？

@cloudgpt/timeline-editor 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @cloudgpt/timeline-editor 的下载量有多少？

根据 npm 官方下载统计，@cloudgpt/timeline-editor 在 2026/10/10 – 2026/11/08 这 30 天内被下载 5,644 次，日均约 188 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @cloudgpt/timeline-editor 还在维护吗？

最新版本 1\.0\.0 发布于 2025/08/13（1\.2 年前）；至今共发布 1 个版本，其中过去 12 个月发布了 0 个；首次发布于 2025/08/13。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。