syncfusion-react-timeline

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Implementing Syncfusion React Timeline

实现Syncfusion React Timeline组件

The Timeline component displays events or steps in chronological order with visual indicators. It supports vertical and horizontal layouts, multiple alignment modes, customizable dots and connectors, templates, and events for complete flexibility.

Timeline组件用于按时间顺序展示事件或步骤，并配有视觉指示器。它支持垂直和水平布局、多种对齐模式、可自定义的节点与连接线、模板以及事件，提供完全的灵活性。

When to Use This Skill

何时使用此技能

Use the Timeline component when:

Displaying event sequences chronologically (project milestones, shipping tracking, activity logs)
Creating career progression or timeline visualizations
Building step-by-step process flows
Showing company history or project roadmap
Implementing event feeds with timestamps
Displaying before/after comparisons in alternate layouts
Customizing visual indicators (icons, images, colors) for events

Choose Timeline over alternatives:

vs Stepper: Timeline shows completed events; Stepper guides users through steps
vs List: Timeline emphasizes chronological relationships and connections
vs Chart: Timeline focuses on event sequence; Chart focuses on data relationships

在以下场景使用Timeline组件：

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

选择Timeline而非其他组件的场景：

对比Stepper组件：Timeline用于展示已完成的事件；Stepper用于引导用户完成步骤
对比List组件：Timeline强调事件的时序关系和关联性
对比Chart组件：Timeline聚焦于事件序列；Chart聚焦于数据关系

Quick Start Example

快速开始示例

tsx

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;

tsx

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;

Component Overview

组件概述

TimelineComponent is the root container that manages the timeline layout and behavior.

Key Properties:

```
orientation
```
: Layout direction (
```
Vertical
```
|
```
Horizontal
```
)

align

: Content positioning (

Before

After

Alternate

AlternateReverse

)

```
reverse
```
: Invert display order (most recent first)
```
cssClass
```
: Apply custom styles
```
template
```
: Custom rendering for timeline items

ItemsDirective & ItemDirective define timeline items within the component.

Item Properties:

```
content
```
: Main event text or template
```
oppositeContent
```
: Secondary text on opposite side
```
dotCss
```
: CSS class for dot styling (icons, images, custom appearance)
```
cssClass
```
: Individual item styling
```
disabled
```
: Disable interaction and dim appearance

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

核心属性：

```
orientation
```
：布局方向（
```
Vertical
```
|
```
Horizontal
```
）

align

：内容定位（

Before

After

Alternate

AlternateReverse

）

```
reverse
```
：反转显示顺序（最新事件优先）
```
cssClass
```
：应用自定义样式
```
template
```
：时间线项的自定义渲染模板

ItemsDirective & ItemDirective用于在组件内定义时间线项。

项属性：

```
content
```
：事件的主要文本或模板
```
oppositeContent
```
：另一侧的次要文本
```
dotCss
```
：用于节点样式的CSS类（图标、图片、自定义外观）
```
cssClass
```
：单个项的样式类
```
disabled
```
：禁用交互并淡化外观

Documentation and Navigation Guide

文档与导航指南

Getting Started

快速入门

📄 Read: references/getting-started.md

Installation via npm and package dependencies
CSS imports and theme setup
Basic TimelineComponent structure
ItemsDirective and ItemDirective usage
Running your first timeline application

📄 阅读： references/getting-started.md

通过npm安装及依赖配置
CSS导入与主题设置
基础TimelineComponent结构
ItemsDirective和ItemDirective的使用方法
运行首个时间线应用

Layout Configuration

布局配置

📄 Read: references/layout-configuration.md

Orientation options (Vertical, Horizontal)
Alignment modes (Before, After, Alternate, AlternateReverse)
Content positioning strategies
Choosing the right layout for your use case
Code examples for each layout combination

📄 阅读： references/layout-configuration.md

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

Items and Content

项与内容

📄 Read: references/items-and-content.md

Adding string content
Template-based rich content
Opposite content configuration
Dot customization with icons, images, and text
Disabling individual items
Per-item CSS classes

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

添加字符串内容
基于模板的富内容
另一侧内容配置
使用图标、图片和文本自定义节点
禁用单个项
逐项设置CSS类

Styling and Customization

样式与定制

📄 Read: references/styling-and-customization.md

Connector styling (common and per-item)
Dot color, size, shadow, outline, and variants
CSS custom properties for dots
e-outline class usage
Complete customization examples

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

连接线样式（全局及逐项）
节点的颜色、尺寸、阴影、轮廓及变体
节点的CSS自定义属性
e-outline类的使用
完整定制示例

Events and Callbacks

事件与回调

📄 Read: references/events-and-callbacks.md

```
created
```
event when component renders
```
beforeItemRender
```
event for item customization
Event handling patterns and use cases

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

组件渲染完成时的
```
created
```
事件
用于项定制的
```
beforeItemRender
```
事件
事件处理模式及使用场景

Advanced Features

高级功能

📄 Read: references/advanced-features.md

Template property for complete custom rendering
Template context (item, itemIndex)
Reverse property for newest-first display
Complex template patterns
When to use templates vs built-in properties

📄 阅读： references/advanced-features.md

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

Accessibility

无障碍访问

📄 Read: references/accessibility.md

WCAG 2.2 and Section 508 compliance
ARIA attributes and roles
Keyboard navigation support
RTL (Right-to-Left) language support
Mobile device accessibility

📄 阅读： references/accessibility.md

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

Common Patterns

常见模式

Pattern 1: Vertical Timeline with Before Alignment

模式1：垂直布局+Before对齐

tsx

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

tsx

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

Pattern 2: Horizontal Alternate Layout

模式2：水平布局+交替对齐

tsx

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

tsx

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

Pattern 3: Timeline with Custom Dots and Icons

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

tsx

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

tsx

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

Pattern 4: Activity Feed with Reverse Order

模式4：反转顺序的活动动态

tsx

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

tsx

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

Key Props Summary

核心属性汇总

Prop	Type	Values	Purpose
`orientation`	string	`Vertical` (default), `Horizontal`	Layout direction
`align`	string	`Before` , `After` , `Alternate` , `AlternateReverse`	Content positioning
`reverse`	boolean	`true` , `false` (default)	Reverse item order
`cssClass`	string	CSS class name	Global styling
`template`	function	React function	Custom item rendering
`content` (item)	string \| function	Text or template	Event text/content
`oppositeContent` (item)	string \| function	Text or template	Secondary content
`dotCss` (item)	string	CSS class	Dot styling
`disabled` (item)	boolean	`true` , `false`	Disable item
`cssClass` (item)	string	CSS class	Per-item styling

属性	类型	可选值	用途
`orientation`	string	`Vertical` （默认）, `Horizontal`	布局方向
`align`	string	`Before` , `After` , `Alternate` , `AlternateReverse`	内容定位
`reverse`	boolean	`true` , `false` （默认）	反转项顺序
`cssClass`	string	CSS类名	全局样式
`template`	function	React函数	自定义项渲染
`content` （项属性）	string \| function	文本或模板	事件文本/内容
`oppositeContent` （项属性）	string \| function	文本或模板	次要内容
`dotCss` （项属性）	string	CSS类	节点样式
`disabled` （项属性）	boolean	`true` , `false`	禁用项
`cssClass` （项属性）	string	CSS类	逐项样式

Troubleshooting

故障排除

Timeline not displaying:

Ensure CSS imports are included (tailwind3.css or your theme)
Container must have explicit height:
```
style={{ height: '350px' }}
```
ItemsDirective must contain ItemDirective children

Items not centered vertically:

Add
```
height
```
to TimelineComponent container
Adjust with CSS custom properties:
```
--dot-size
```
,
```
--dot-outer-space
```

Content positioning unexpected:

Verify

align

property:

Before

After

Alternate

AlternateReverse

Check
```
oppositeContent
```
is defined for two-sided layouts
Confirm
```
orientation
```
matches your layout intent

Dots not visible:

Verify dots have
```
e-outline
```
class or custom CSS styling
Check
```
dotCss
```
property contains valid CSS class names
Ensure theme CSS includes dot styles

Templates not rendering:

Verify template function returns valid JSX
Check context properties:
```
props.item
```
,
```
props.itemIndex
```
Ensure function signature matches:
```
(props: any) => JSX.Element
```

时间线未显示：

确保已导入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
```