syncfusion-react-timeline

用途

Syncfusion React Timeline 组件用于按时间顺序展示事件或步骤序列，通过视觉指示器呈现时间线关系。它适合展示项目里程碑、物流跟踪、活动日志、职业发展历程、公司历史、项目路线图、带时间戳的事件流，以及前后对比等场景。

该组件与替代方案的定位区别：相比 Stepper，Timeline 展示已完成的事件，而 Stepper 引导用户逐步操作；相比 List，Timeline 强调时间顺序与连接关系；相比 Chart，Timeline 聚焦事件序列，而 Chart 聚焦数据关系。

主要能力

布局方向：orientation 属性支持 Vertical（默认）与 Horizontal。
内容对齐：align 属性支持 Before、After、Alternate、AlternateReverse 四种内容定位方式。
顺序反转：reverse 属性可反转显示顺序，实现最新事件优先。
全局与单项样式：cssClass 属性用于全局样式，ItemDirective 的 cssClass 用于单项样式。
自定义渲染：template 属性支持对时间线项进行完全自定义渲染，模板上下文包含 item 与 itemIndex。
项内容：ItemDirective 的 content 设置主事件文本或模板，oppositeContent 设置对侧次要文本或模板。
圆点定制：dotCss 属性可为圆点设置 CSS 类，用于图标、图片或自定义外观。
禁用单项：disabled 属性可禁用交互并使该项变暗。
事件回调：提供 created（组件渲染时触发）与 beforeItemRender（项渲染前触发，用于自定义）事件。
无障碍：符合 WCAG 2.2 与 Section 508，支持 ARIA 属性与角色、键盘导航、RTL 语言以及移动设备无障碍。

使用方式

通过 npm 安装并引入包与主题 CSS，使用 TimelineComponent 作为根容器，内部通过 ItemsDirective 与 ItemDirective 定义时间线项。

快速开始示例：

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;

常见模式示例：

垂直 Before 对齐：

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

水平 Alternate 布局：

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

自定义圆点与图标：

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

反向顺序活动流：

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

关键属性：orientation（Vertical 默认、Horizontal）、align（Before、After、Alternate、AlternateReverse）、reverse（布尔值，默认 false）、cssClass（全局样式类）、template（自定义渲染函数）、content（项主内容）、oppositeContent（项对侧内容）、dotCss（项圆点样式类）、disabled（项禁用）、cssClass（项样式类）。

适用场景

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

限制与注意事项

时间线不显示时：需确保已引入 CSS（如 tailwind3.css 或对应主题），容器必须有明确高度（如 style={{ height: '350px' }}），且 ItemsDirective 必须包含 ItemDirective 子项。
项未垂直居中时：为 TimelineComponent 容器添加高度，可通过 CSS 自定义属性 --dot-size、--dot-outer-space 调整。
内容定位不符合预期时：检查 align 属性取值，确认双侧布局已定义 oppositeContent，并确认 orientation 与布局意图一致。
圆点不可见时：确认圆点具有 e-outline 类或自定义 CSS 样式，检查 dotCss 属性包含有效 CSS 类名，并确保主题 CSS 包含圆点样式。
模板未渲染时：确认 template 函数返回有效 JSX，检查上下文属性 props.item、props.itemIndex，并确保函数签名匹配 (props: any) => JSX.Element。
关于收费、价格、平台支持范围等具体信息，资料中暂未提供。

技能介绍

用途

主要能力

使用方式

适用场景

限制与注意事项