syncfusion-react-timeline

实现 Syncfusion React 时间线

Timeline 组件按时间顺序显示事件或步骤，并提供可视化指示器。它支持垂直和水平布局、多种对齐模式、可自定义的圆点和连接线、模板以及事件，灵活性十足。

何时使用此技能

在以下情况下使用 Timeline 组件：

• 按时间顺序显示事件序列（项目里程碑、物流跟踪、活动日志）
• 创建职业发展或时间线可视化效果
• 构建分步流程
• 展示公司历史或项目路线图
• 实现带时间戳的事件动态
• 使用交替布局展示前后对比
• 自定义事件的可视化指示器（图标、图像、颜色）

选择 Timeline 而非其他组件：

• 与 Stepper 相比： Timeline 展示已完成的事件；Stepper 引导用户完成各个步骤
• 与 List 相比： Timeline 突出显示时间顺序关系和关联
• 与 Chart 相比： Timeline 侧重事件顺序；Chart 侧重数据关系

快速入门示例

import { TimelineComponent, ItemsDirective, ItemDirective } from '@syncfusion/ej2-react-layouts';
import '@syncfusion/ej2-base/styles/tailwind3.css';
import '@syncfusion/ej2-layouts/styles/tailwind3.css';

function App() {
  return (
    <div style={{ height: '350px' }}>
      <TimelineComponent>
        <ItemsDirective>
          <ItemDirective content="Shipped" />
          <ItemDirective content="Departed" />
          <ItemDirective content="Arrived" />
          <ItemDirective content="Out for Delivery" />
        </ItemsDirective>
      </TimelineComponent>
    </div>
  );
}
export default App;

组件概览

TimelineComponent 是管理时间线布局和行为的根容器。

关键属性：

• orientation：布局方向（Vertical | Horizontal）
• align：内容位置（Before | After | Alternate | AlternateReverse）
• reverse：反转显示顺序（最新内容优先）
• cssClass：应用自定义样式
• template：自定义时间线项目的渲染方式

ItemsDirective 和 ItemDirective 用于定义组件中的时间线项目。

项目属性：

• content：主要事件文本或模板
• oppositeContent：另一侧的辅助文本
• dotCss：圆点样式的 CSS 类（图标、图像、自定义外观）
• cssClass：单个项目的样式
• disabled：禁用交互并降低视觉亮度

文档和导航指南

入门

📄 阅读： references/getting-started.md

• 通过 npm 安装和配置软件包依赖项
• 导入 CSS 并设置主题
• TimelineComponent 基本结构
• ItemsDirective 和 ItemDirective 的用法
• 运行你的第一个时间线应用

布局配置

📄 阅读： references/layout-configuration.md

• 方向选项（Vertical、Horizontal）
• 对齐模式（Before、After、Alternate、AlternateReverse）
• 内容定位策略
• 根据使用场景选择合适的布局
• 各种布局组合的代码示例

项目和内容

📄 阅读： references/items-and-content.md

• 添加字符串内容
• 基于模板的富内容
• 配置辅助内容
• 使用图标、图像和文本自定义圆点
• 禁用单个项目
• 为每个项目设置 CSS 类

样式和自定义

📄 阅读： references/styling-and-customization.md

• 连接线样式（通用和单项）
• 圆点颜色、大小、阴影、轮廓和变体
• 圆点的 CSS 自定义属性
• e-outline 类的用法
• 完整的自定义示例

事件和回调

📄 阅读： references/events-and-callbacks.md

• 组件渲染时触发的 created 事件
• 用于自定义项目的 beforeItemRender 事件
• 事件处理模式和使用场景

高级功能

📄 阅读： references/advanced-features.md

• 用于完全自定义渲染的 template 属性
• 模板上下文（item、itemIndex）
• 用于按最新内容优先显示的 reverse 属性
• 复杂的模板模式
• 何时使用模板而非内置属性

无障碍访问

📄 阅读： references/accessibility.md

• 符合 WCAG 2.2 和 Section 508 标准
• ARIA 属性和角色
• 支持键盘导航
• RTL（从右到左）语言支持
• 移动设备无障碍访问

常见模式

模式 1：纵向时间线（内容前置对齐）

<TimelineComponent orientation='Vertical' align='Before'>
  <ItemsDirective>
    <ItemDirective content='Step 1' oppositeContent='Description' />
    <ItemDirective content='Step 2' oppositeContent='Description' />
  </ItemsDirective>
</TimelineComponent>

模式 2：水平交替布局

<TimelineComponent orientation='Horizontal' align='Alternate'>
  <ItemsDirective>
    <ItemDirective content='Event 1' oppositeContent='Date 1' />
    <ItemDirective content='Event 2' oppositeContent='Date 2' />
  </ItemsDirective>
</TimelineComponent>

模式 3：带自定义圆点和图标的时间线

<TimelineComponent>
  <ItemsDirective>
    <ItemDirective content='Shipped' dotCss='e-icons e-package' />
    <ItemDirective content='Delivered' dotCss='e-icons e-check' cssClass='state-completed' />
  </ItemsDirective>
</TimelineComponent>

模式 4：逆序活动动态

<TimelineComponent reverse={true}>
  <ItemsDirective>
    <ItemDirective content='Latest activity' />
    <ItemDirective content='Previous activity' />
  </ItemsDirective>
</TimelineComponent>

主要属性摘要

属性	类型	值	用途
orientation	字符串	Vertical（默认）、Horizontal	布局方向
align	字符串	Before、After、Alternate、AlternateReverse	内容位置
reverse	布尔值	true、false（默认）	反转项目顺序
cssClass	字符串	CSS 类名	全局样式
template	函数	React 函数	自定义项目渲染
content（项目）	字符串 | 函数	文本或模板	事件文本/内容
oppositeContent（项目）	字符串 | 函数	文本或模板	次要内容
dotCss（项目）	字符串	CSS 类	圆点样式
disabled（项目）	布尔值	true、false	禁用项目
cssClass（项目）	字符串	CSS 类	单个项目的样式

故障排除

时间线未显示：

• 确保已导入 CSS（tailwind3.css 或你的主题）
• 容器必须具有明确的高度：style={{ height: '350px' }}
• ItemsDirective 中必须包含 ItemDirective 子项

项目未垂直居中：

• 为 TimelineComponent 容器添加 height
• 使用 CSS 自定义属性调整：--dot-size、--dot-outer-space

内容位置不符合预期：

• 检查 align 属性：Before、After、Alternate、AlternateReverse
• 对于双侧布局，检查是否定义了 oppositeContent
• 确认 orientation 符合布局需求

圆点不可见：

• 确认圆点具有 e-outline 类或自定义 CSS 样式
• 检查 dotCss 属性是否包含有效的 CSS 类名
• 确保主题 CSS 包含圆点样式

模板未渲染：

• 确认模板函数返回有效的 JSX
• 检查上下文属性：props.item、props.itemIndex
• 确保函数签名符合要求：(props: any) => JSX.Element