syncfusion-aspnetcore-timeline

スキル：Syncfusion Timeline コンポーネント

概要

Timeline コンポーネントは、時系列に並べられた一連のイベントやアクティビティを表示します。設定可能なレイアウトで、時間的な関係や推移を視覚化できます。Timeline は、縦方向と横方向の両方に対応しており、柔軟なコンテンツ配置方法（Before、After、Alternate、AlternateReverse）や豊富なテンプレート機能を備えています。Web アプリケーションで、プロジェクトのマイルストーン、プロセスフロー、歴史的イベント、その他の時系列の推移を表示するためによく使用されます。

機能範囲

コンポーネントの責任（Timeline が担当）：

• タイムラインの視覚的な構造（ドット、コネクター、タイムラインの線）の描画
• 指定された方向と配置に応じた項目レイアウトの管理
• 方向のサポート（RTL モード）
• 描画時および初期化時のライフサイクルイベントの発火
• CSS による視覚要素のカスタマイズ
• 項目のテンプレートコンテンツの解析と描画

開発者の責任（開発者が制御）：

• コンテンツと設定プロパティを含む項目データの準備
• コンテンツテンプレート（HTML 構造、書式設定）の設計
• CSS クラスによるドット、コネクター、タイムライン要素のスタイリング
• カスタム動作用イベント（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 クラスが適用されます

方向による影響：

• 縦方向（デフォルト）：項目は上から下へ並びます。Before／After の配置によって、コンテンツの左右の位置が決まります。
• 横方向：項目は左から右へ並びます。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

Timeline コンポーネントのプロパティ

プロパティ	型	用途	デフォルト値
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	Timeline コンテナーに適用する 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.