syncfusion-aspnetcore-timeline

技能：Syncfusion Timeline 组件

概述

Timeline 组件按时间顺序展示一系列事件或活动。它支持以可配置的布局直观呈现时间关系和发展过程。Timeline 支持垂直和水平方向、灵活的内容对齐策略（Before、After、Alternate、AlternateReverse）以及丰富的模板功能。它常用于在 Web 应用中展示项目里程碑、流程、历史事件或任何按时间顺序发展的内容。

功能范围

组件职责（Timeline 负责）：

• 渲染 Timeline 的可视结构（圆点、连接线、时间线）
• 根据指定的方向和对齐方式管理项目布局
• 处理方向支持（RTL 模式）
• 在渲染和初始化期间触发生命周期事件
• 通过基于 CSS 的方式自定义可视元素
• 解析并渲染项目的模板内容

开发者职责（由你控制）：

• 准备包含内容和配置属性的项目数据
• 设计内容模板（HTML 结构、格式）
• 通过 CSS 类设置圆点、连接线和 Timeline 元素的样式
• 处理事件（created、beforeItemRender），实现自定义行为
• 管理动态数据更新
• 确保模板内容包含无障碍属性
• 定义由事件触发的应用专属逻辑

Timeline 不负责处理的内容：

• 状态之间的动画或过渡效果（由 CSS 负责）
• 响应式布局断点（需要使用 CSS 媒体查询）
• 页面重新加载后数据的持久化或状态管理（由应用层负责）
• 超大型数据集（100,000+ 个项目）的无限滚动或虚拟化
• 无障碍标记生成（你必须确保提供正确的 ARIA 标签）
• 项目筛选或排序（将数据传递给 Timeline 前需预先处理）

工作原理

渲染流程：

1. 初始化：Timeline 接收 items 数组和配置属性（align、orientation、reverse 等）
2. 布局计算：组件根据方向（Vertical/Horizontal）和对齐方式（Before/After/Alternate/AlternateReverse）确定项目位置
3. 触发事件：组件完成渲染后触发 created 事件
4. 项目渲染：为每个项目创建 DOM 元素前会触发 beforeItemRender 事件（允许在渲染前修改项目属性）
5. 构建 DOM：Timeline 构建可视结构：
   • 连接各项目的时间线/连接线
   • 每个项目位置上的圆点元素
   • 根据对齐方式定位的内容容器
   • 位于主要内容对侧的反向内容
6. 应用 CSS：应用 cssClass、项目级 cssClass 和圆点级 dotCss 中指定的所有 CSS 类

方向的影响：

• Vertical（默认）：项目自上而下排列。Before/After 对齐方式控制内容的左右位置。
• Horizontal：项目从左向右排列。Before/After 对齐方式控制内容的上下位置。

对齐行为：

• Before：内容位于一侧，oppositeContent 位于另一侧（取决于方向）
• After：内容与 Before 的位置相反
• Alternate：项目交替排列在两侧，与方向无关
• AlternateReverse：项目按相反顺序交替排列在两侧

数据绑定：

• 按照项目在 items 数组中的顺序渲染
• reverse 属性会反转显示顺序，但不会修改源数据
• 内容可以是静态字符串，也可以根据 itemIndex 上下文通过函数动态生成

配置与用法

必需配置

@using Syncfusion.EJ2.Layouts;

<ejs-timeline id="timeline">
    <e-timeline-items>
        <e-timeline-item content="Initial Release"></e-timeline-item>
        <e-timeline-item content="Version 2.0"></e-timeline-item>
        <e-timeline-item content="Latest Update"></e-timeline-item>
    </e-timeline-items>
</ejs-timeline>

可选配置

<ejs-timeline id="timeline" align="Alternate" orientation="Horizontal" reverse="false" enableRtl="false" enablePersistence="false" cssClass="custom-timeline" locale="en-US">
    <e-timeline-items>
        <e-timeline-item content="Phase 1" oppositeContent="Q1 2024" dotCss="e-icons e-check" cssClass="phase-active"></e-timeline-item>
        <e-timeline-item content="Phase 2" oppositeContent="Q2 2024" dotCss="e-icons e-pending"></e-timeline-item>
    </e-timeline-items>
</ejs-timeline>

默认值

属性	默认值	行为
align	TimelineAlign.After	默认将内容放置在底部/右侧
orientation	TimelineOrientation.Vertical	项目垂直堆叠
reverse	false	按源顺序显示项目
enableRtl	false	从左到右的文本方向
enablePersistence	false	会话之间不保存状态
locale	'en-US'	英语本地化
items	[]（空）	为空时不渲染任何项目

关键 API

时间轴组件属性

属性	类型	用途	默认值
items	TimelineItemModel[]	要渲染的时间轴项目数组	[]
align	TimelineAlign enum	内容对齐策略（Before/After/Alternate/AlternateReverse）	After
orientation	TimelineOrientation enum	显示方向（Vertical/Horizontal）	Vertical
reverse	boolean	反转项目显示顺序	false
template	string	用于自定义项目渲染的 HTML 模板选择器	N/A
enableRtl	boolean	启用从右到左的文本方向	false
enablePersistence	boolean	在页面重新加载之间持久化状态	false
cssClass	string	应用于时间轴容器的 CSS 类	''
locale	string	区域设置/本地化标识符	'en-US'

TimelineItem 属性

属性	类型	用途	默认值
content	string | Function	项目的主要文本或模板（接收 itemIndex）	''
oppositeContent	string | Function	与主要内容相对的次要内容（接收 itemIndex）	''
dotCss	string	点元素的 CSS 类（图标、图像、样式）	''
disabled	boolean	禁用此项目的视觉效果/交互	false
cssClass	string	此项目容器的 CSS 类	''

事件

事件	触发时机	用例
created	组件渲染完成后	初始化自定义行为、访问已渲染的元素
beforeItemRender	创建每个项目的 DOM 元素之前	根据条件修改项目属性、应用动态样式

事件参数：

• created：无自定义属性
• beforeItemRender：提供 element（HTMLElement）、index（number）、name（'beforeItemRender'）

对齐枚举（TimelineAlign）

public enum TimelineAlign
{
    Before,           // Content on first side (left/top depending on orientation)
    After,            // Content on second side (right/bottom) — DEFAULT
    Alternate,        // Items alternate sides in order
    AlternateReverse  // Items alternate sides in reverse order
}

方向枚举（TimelineOrientation）

public enum TimelineOrientation
{
    Vertical,        // Items stack top-to-bottom (default)
    Horizontal       // Items arrange left-to-right
}

示例

场景：展示包含里程碑日期和状态指示器的产品发布流程时间轴。

@using Syncfusion.EJ2.Layouts;

<ejs-timeline id="release-timeline" align="Alternate" orientation="Vertical" cssClass="release-timeline">
    <e-timeline-items>
        <e-timeline-item content="Alpha Release" oppositeContent="January 2024" dotCss="e-icons e-info"></e-timeline-item>
        <e-timeline-item content="Beta Release" oppositeContent="March 2024" dotCss="e-icons e-check"></e-timeline-item>
        <e-timeline-item content="Production Release" oppositeContent="June 2024" dotCss="e-icons e-star"></e-timeline-item>
    </e-timeline-items>
</ejs-timeline>

模板示例：

@using Syncfusion.EJ2.Layouts;

<div class="container" style="height: 350px">
    <ejs-timeline id="timeline">
        <e-timeline-items>
            <e-timeline-item content="#content-template"></e-timeline-item>
            <e-timeline-item content="#content-template"></e-timeline-item>
            <e-timeline-item content="#content-template"></e-timeline-item>
            <e-timeline-item content="Out for Delivery"></e-timeline-item>
        </e-timeline-items>
    </ejs-timeline>
</div>

<script id="content-template" type="text/x-jsrender">
    <div class="content-container">
        <div class="title">
            ${if(itemIndex==0)} Shipped
            ${else if(itemIndex==1)} Departed
            ${else if(itemIndex==2)} Arrived
            ${/if}
        </div>
        <span class="description">
            ${if(itemIndex==0)} Package details received
            ${else if(itemIndex==1)} In-transit
            ${else if(itemIndex==2)} Package arrived at nearest hub
            ${/if}
        </span>
        <div class="info">
            ${if(itemIndex==0)} - Awaiting dispatch
            ${else if(itemIndex==1)} (International warehouse)
            ${else if(itemIndex==2)} (New york - US)
            ${/if}
        </div>
    </div>
</script>

<style>
    .content-container {
        position: relative;
        width: 180px;
        padding: 10px;
        margin-left: 5px;
        box-shadow: rgba(9, 30, 66, 0.25) 0px 4px 8px -2px, rgba(9, 30, 66, 0.08) 0px 0px 0px 1px;
        background-color: ghostwhite;
    }

    .content-container::before {
        content: '';
        position: absolute;
        left: -8px;
        transform: translateY(-50%);
        width: 0;
        height: 0;
        border-top: 5px solid transparent;
        border-bottom: 5px solid transparent;
        border-right: 8px solid silver;
    }

    .content-container .title {
        font-size: 16px;
    }
    .content-container .description {
        color: #999999;
        font-size: 12px;
    }
    .content-container .info {
        color: #999999;
        font-size: 10px;
    }
</style>

## Edge Cases and Constraints

1. **Empty Items Array**: Timeline renders no visible content if `items` is empty or null. Component container still renders (empty HTML). Always validate data before passing to Timeline.

2. **Very Large Datasets (1000+ items)**: Timeline renders all items in DOM without virtualization. Performance degrades linearly with item count. For large datasets, implement pagination or filter items client-side before binding.

3. **Template Functions with Side Effects**: If `content` or `oppositeContent` are function-type properties with side effects (logging, API calls), functions execute during rendering. Ensure functions are idempotent and fast (no async operations).

4. **RTL (enableRtl=true) with Horizontal Orientation**: Timeline correctly reverses layout direction. Test content alignment thoroughly—Alternate alignment behavior reverses in RTL mode.

5. **Disabled Items Styling**: Setting `disabled=true` does not automatically style items visually. You must define CSS for `.e-disabled` or custom class to show disabled state (e.g., opacity, strikethrough).

6. **Dot CSS Class Conflicts**: If `dotCss` specifies both icon class (e.g., `e-icons e-check`) and custom class, ensure no CSS conflicts. Icon fonts may fail to load if CDN is unreachable.

7. **Dynamic Content Updates**: If you modify `items` array after rendering, the Timeline does not automatically refresh. You must re-instantiate or call update methods. Changes to item objects alone do not trigger re-render.

8. **Accessibility with Templates**: Custom templates (using `template` property) are developer-controlled. Component does not auto-generate ARIA labels. You must include `role`, `aria-label`, `aria-describedby` attributes in templates.

9. **Locale Fallback**: If specified `locale` is not registered, Timeline falls back to `en-US`. Ensure locale data is loaded before Timeline initialization.

10. **Reverse Property Logic**: `reverse=true` reverses visual order only; source `items` array order is unchanged. This affects user perception of chronological flow but does not modify underlying data.

## Testing Checklist

- [ ] **Visual Rendering**: All items render with correct content, opposite content, and dots in DOM
- [ ] **Orientation Switch**: Timeline correctly renders in both Vertical and Horizontal modes
- [ ] **Alignment Modes**: All four alignment modes (Before/After/Alternate/AlternateReverse) position content correctly
- [ ] **RTL Mode**: With `enableRtl=true`, content direction reverses and layout mirroring is correct
- [ ] **Reverse Property**: With `reverse=true`, items display in reverse visual order (verify against items array)
- [ ] **Empty Dataset**: Timeline handles empty or null `items` without JavaScript errors
- [ ] **Large Dataset Performance**: Timeline renders 500+ items without browser freezing (baseline test)
- [ ] **Event Firing**: `created` event fires once after rendering; `beforeItemRender` fires for each item
- [ ] **CSS Application**: Custom CSS classes (component-level `cssClass` and item-level `cssClass`) apply correctly
- [ ] **Dot Customization**: Dot CSS classes (icons, images, text) render without font failures
- [ ] **Template Rendering**: Custom templates (if using `template` property) render content without script errors
- [ ] **Accessibility (Keyboard)**: Timeline structure is keyboard-navigable; focus management works (if interactive)
- [ ] **Accessibility (Screen Reader)**: Screen reader announces items in logical order; ARIA labels present (if configured)
- [ ] **Disabled Items**: Items with `disabled=true` render but are visually distinguishable (if styled)
- [ ] **Persistence**: With `enablePersistence=true`, state is restored on page reload (verify localStorage)
- [ ] **Dynamic Updates**: Modifying `items` after render requires manual refresh; verify no auto-refresh (expected behavior)
- [ ] **Locale Switching**: Changing `locale` property updates localized strings correctly
- [ ] **Browser Compatibility**: Timeline renders correctly in Chrome, Firefox, Safari, Edge (latest versions)

## Best Practices

1. **Pre-process Data Before Binding**: Sort, filter, and validate item data before passing to Timeline. Timeline renders items in order received—apply business logic (sorting by date, filtering by status) at the data layer, not in the component.

2. **Use Opposite Content Strategically**: Reserve opposite content for supplementary information (dates, metadata, statuses). Keep opposite content brief; use main content for primary narrative. This prevents visual clutter and maintains chronological clarity.

3. **Choose Alignment Based on Content Volume**: Use `Before` or `After` for simple, short content. Use `Alternate` when content is substantial and you need to balance visual weight. `AlternateReverse` is rarely needed; use only for specific design requirements (e.g., reverse chronological with intentional mirroring).

4. **Customize Dots with Icons, Not Text**: Leverage `dotCss` with icon fonts (Material Icons, Syncfusion icons) for visual status indicators. Avoid long text in dots; instead, encode meaning via icon and color. Icons are faster to recognize than text.

5. **Style Disabled Items Explicitly**: If using `disabled=true` for historical or read-only items, define clear CSS to visually differentiate them (e.g., reduced opacity, grayscale, strikethrough). Users must immediately recognize disabled state without hovering.

6. **Leverage Templates for Complex Layouts**: For items requiring rich HTML (images, nested lists, interactive elements), use the `template` property instead of string content. Templates offer full control; ensure templates remain self-contained and do not create accessibility barriers.

7. **Handle Accessibility in Custom Templates**: If using custom templates, manually include `role="article"`, `aria-label`, and `aria-describedby` attributes. Test with screen readers (NVDA, JAWS) to ensure content is announced in expected order and context is clear.

8. **Monitor Performance with Large Datasets**: If binding 500+ items, profile rendering time in browser DevTools. If rendering takes >500ms, consider pagination, lazy loading, or filtering. Inform users of rendering delay with a loading indicator.

9. **Test RTL Rendering If Supporting Right-to-Left Languages**: Set `enableRtl=true` and verify all alignment modes, dot positioning, and content placement mirror correctly. Test on actual right-to-left content (Arabic, Hebrew, Persian) to catch subtle layout issues.

10. **Validate Event Handlers Are Idempotent**: If `beforeItemRender` handler modifies component state, ensure modifications are safe to repeat. Handlers may fire multiple times if component re-renders; avoid side effects that compound.