syncfusion-react-timeline

Syncfusion React Timeline の実装

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：Before 配置の垂直タイムライン

<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	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 クラス	項目ごとのスタイル設定

トラブルシューティング

タイムラインが表示されない場合：

• 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 と一致していることを確認します