syncfusion-blazor-range-selectors

範囲セレクターの実装

NuGet： Syncfusion.Blazor.Charts + Syncfusion.Blazor.Themes（または個別パッケージの Syncfusion.Blazor.RangeNavigator）
名前空間： Syncfusion.Blazor.Charts

データ範囲の選択やチャートのナビゲーションに使用する、Syncfusion Blazor Range Selector（RangeNavigator）コンポーネントの実装に関する包括的なスキルです。Range Selector では、ドラッグ可能なつまみを使って大量のデータコレクションから特定の範囲を選択できます。時系列データや数値データを直感的にフィルターし、ナビゲートできます。

このスキルを使用するタイミング

次のような場合は、すぐにこのスキルを使用してください。

• ドラッグ可能なつまみを使ってチャートで範囲選択を有効にする
• 大規模な時系列データセットを日付範囲でフィルターする
• 金融データや株価をナビゲートする
• 視覚的なフィードバックを備えたチャートのズーム／パンコントロールを作成する
• データ範囲に基づくダッシュボードのフィルタリングを実装する
• クイックナビゲーション用の期間セレクターボタン（1M、3M、6M、YTD、1Y、All）を追加する
• 面、折れ線、またはステップラインの系列でデータの傾向を表示する
• インタラクティブなデータ探索インターフェイスを構築する
• ドリルダウン分析用にデータをフィルターする
• Blazor Server、WebAssembly、または Web App 向けに、応答性の高い範囲選択コントロールを作成する
• 複数のチャートで同期されたフィルタリングを有効にする
• パフォーマンスが重要なシナリオ向けに軽量なチャートナビゲーションを実装する
• 選択したデータ範囲の視覚的なコンテキストを提供する

コンポーネントの概要

Syncfusion Blazor Range Selector（SfRangeNavigator）は、データ範囲の選択とナビゲーションに特化したコントロールです。次の機能を備えています。

• ドラッグ可能なつまみ：範囲の境界を選択する左右のハンドル
• 視覚的な系列：データの傾向を表示する折れ線、面、またはステップライン
• 期間セレクター：RangeNavigatorPeriodSelectorSettings、RangeNavigatorPeriods、RangeNavigatorPeriod によるクイックプリセットボタン
• 値の種類：DateTime、Numeric、Logarithmic データに対応
• インタラクティブな選択：ラベルのクリックまたはつまみのドラッグによる範囲の更新
• データバインディング：ローカルおよびリモートのデータソースとの連携
• カスタマイズ：RangeNavigatorBorder、RangeNavigatorMargin、RangeNavigatorStyleSettings、RangeNavigatorThumbSettings、ツールチップ設定による豊富なスタイル、テーマ、書式設定オプション

主な機能：

• 範囲の選択方法：つまみのドラッグ、ラベルのタップ、またはプログラムによる設定
• 系列の種類：折れ線（既定）、面、ステップライン
• 値のバインディング：一方向および双方向のバインディングに対応
• 連携：期間セレクターやその他のチャートと連携
• エクスポート：PNG、JPEG、SVG、PDF へのエクスポート機能
• アクセシビリティ：キーボードナビゲーションに対応し、WCAG に準拠

ドキュメントとナビゲーションガイド

はじめに

📄 参照： references/getting-started.md

インストール、セットアップ、最初の範囲セレクターについては、ここから始めてください。次の内容を扱います。

• Syncfusion.Blazor.RangeNavigator NuGet パッケージのインストール
• Blazor Server、WebAssembly、Web App のセットアップ
• サービスの登録とテーマの設定
• サンプルデータを使った基本的な SfRangeNavigator の実装
• プロジェクト構造とスクリプトの参照
• よくあるセットアップの問題のトラブルシューティング

基本的な設定

範囲の選択と値

📄 参照： references/range-configuration.md

範囲選択の動作と値のバインディングを設定します。

• 開始値と終了値を設定する Value プロパティ
• 一方向および双方向のバインディングパターン
• 値の種類（DateTime、Numeric、Logarithmic）
• 範囲選択のためのつまみのドラッグ
• クイック選択のためのラベルのタップ
• プログラムによる範囲の更新と検証

系列の種類

📄 参照： references/series-types.md

系列の表示方法を選択し、カスタマイズします。

• 傾向線に使う折れ線系列
• 塗りつぶし領域に使う面系列
• 離散データに使うステップライン系列
• 系列のカスタマイズ（色、幅、塗りつぶし）
• 複数系列への対応

データと連携

データバインディング

📄 参照： references/data-binding.md

レンジセレクターのデータソースを設定します：

• ローカルデータソース（List、Array、ExpandoObject）
• SfDataManager を使用したリモートデータバインディング
• DateTime データの処理と書式設定
• 数値データと対数スケールデータ
• データの更新と動的な変更

期間セレクターとの統合

📄 参照： references/period-selector-integration.md

すばやく移動できる期間セレクターボタンを追加します：

• 定義済みの期間ボタン（1M、3M、6M、YTD、1Y、All）
• カスタム期間の設定
• 範囲変更との統合
• 期間選択時のイベント処理
• スタイル設定と配置

カスタマイズとスタイル設定

軸のカスタマイズ

📄 参照： references/axis-customization.md

軸、グリッド、ラベルをカスタマイズします：

• グリッド線の設定（主目盛りと副目盛り）
• 目盛りのカスタマイズ（サイズ、色、位置）
• ラベルの書式設定と回転
• 間隔の種類（Years、Months、Days、Hours、Minutes）
• 対数軸のサポート
• RTL（右から左）表示のサポート

外観のカスタマイズ

📄 参照： references/visual-customization.md

外観、テーマ、レイアウトを制御します：

• チャートの寸法（Width、Height、Margin）
• テーマの選択（Material、Bootstrap、Fluent、Tailwind、Fabric、Highcontrast）
• ツールチップの設定とテンプレート
• パフォーマンス向上のための軽量レンダリングモード
• カスタムスタイルと配色
• レスポンシブデザインのパターン

高度な機能

エクスポート、イベント、アクセシビリティ

📄 参照： references/export-events-accessibility.md

エクスポートやイベントを処理し、アクセシビリティを確保します：

• エクスポート：PNG、JPEG、SVG、PDF へのエクスポート機能
• イベント：Changed、Loaded、TooltipRender イベントの処理
• アクセシビリティ：WCAG 準拠、キーボードナビゲーション、スクリーンリーダー、ハイコントラストテーマ
• ARIA 属性とテストチェックリスト

クイックスタートの例

イベント処理を備えた、時系列データをフィルタリングするための最小構成のレンジセレクターを示します：

@using Syncfusion.Blazor.Charts

@{
    DateTime[] range = SelectedRange as DateTime[] ?? new DateTime[] { DateTime.Now, DateTime.Now };
}
<h3>Stock Price Range Selector</h3>
<p>Selected Range: @range[0].ToShortDateString() to @range[1].ToShortDateString()</p>

<SfRangeNavigator @bind-Value="@SelectedRange" 
                  ValueType="RangeValueType.DateTime"
                  LabelFormat="MMM-yy"
                  IntervalType="RangeIntervalType.Months">
        <RangeNavigatorEvents Changed="OnRangeChanged"></RangeNavigatorEvents>
    <RangeNavigatorRangeTooltipSettings Enable="true"></RangeNavigatorRangeTooltipSettings>
    <RangeNavigatorSeriesCollection>
        <RangeNavigatorSeries DataSource="@StockData" 
                              XName="Date" 
                              YName="Close" 
                              Type="RangeNavigatorType.Area"
                              Fill="#3F51B5">
        </RangeNavigatorSeries>
    </RangeNavigatorSeriesCollection>
</SfRangeNavigator>

@code {
    public class StockInfo
    {
        public DateTime Date { get; set; }
        public double Close { get; set; }
    }
    
    public object SelectedRange = new DateTime[] 
    { 
        new DateTime(2020, 01, 01), 
        new DateTime(2021, 01, 01) 
    };
    
    public List<StockInfo> StockData = new List<StockInfo>
    {
        new StockInfo { Date = new DateTime(2018, 01, 01), Close = 35 },
        new StockInfo { Date = new DateTime(2019, 01, 01), Close = 42 },
        new StockInfo { Date = new DateTime(2020, 01, 01), Close = 48 },
        new StockInfo { Date = new DateTime(2021, 01, 01), Close = 56 },
        new StockInfo { Date = new DateTime(2022, 01, 01), Close = 62 }
    };
    
    private void OnRangeChanged(ChangedEventArgs args)
    {
        // Handle range change event
        Console.WriteLine($"Range changed: {args.Start} to {args.End}");
    }
}

このコードで作成されるもの：

• 青色の塗りつぶし（#3F51B5）で株価の推移を示すエリアチャート
• 範囲選択用のドラッグ可能なつまみ
• 初期選択範囲：2020年1月から2021年1月
• 「MMM-yy」形式の月ラベル
• ホバー時に値を表示するツールチップ
• 範囲変更に応答するイベントハンドラー
• @bind-Value ディレクティブによる双方向バインディング

一般的なユースケース

1. 期間セレクターによる株価のフィルタリング

期間ボタンを使って株価データをすばやくフィルタリングします：

@using Syncfusion.Blazor.Charts

<SfRangeNavigator @bind-Value="@SelectedRange" 
                  ValueType="RangeValueType.DateTime"
                  IntervalType="RangeIntervalType.Months"
                  LabelFormat="MMM yy">
    <RangeNavigatorRangeTooltipSettings Enable="true" DisplayMode="TooltipDisplayMode.Always">
    </RangeNavigatorRangeTooltipSettings>
    <RangeNavigatorPeriodSelectorSettings>
        <RangeNavigatorPeriods>
            <RangeNavigatorPeriod Text="1M" Interval="1" IntervalType="RangeIntervalType.Months"></RangeNavigatorPeriod>
            <RangeNavigatorPeriod Text="3M" Interval="3" IntervalType="RangeIntervalType.Months"></RangeNavigatorPeriod>
            <RangeNavigatorPeriod Text="6M" Interval="6" IntervalType="RangeIntervalType.Months"></RangeNavigatorPeriod>
            <RangeNavigatorPeriod Text="YTD"></RangeNavigatorPeriod>
            <RangeNavigatorPeriod Text="1Y" Interval="1" IntervalType="RangeIntervalType.Years"></RangeNavigatorPeriod>
            <RangeNavigatorPeriod Text="All"></RangeNavigatorPeriod>
        </RangeNavigatorPeriods>
    </RangeNavigatorPeriodSelectorSettings>
    <RangeNavigatorSeriesCollection>
        <RangeNavigatorSeries DataSource="@StockData" XName="Date" YName="Close" Type="RangeNavigatorType.Area">
        </RangeNavigatorSeries>
    </RangeNavigatorSeriesCollection>
</SfRangeNavigator>

@{
    DateTime[] range = SelectedRange as DateTime[] ?? new DateTime[] { DateTime.Now, DateTime.Now };
}
<p>Selected Range: @range[0].ToShortDateString() to @range[1].ToShortDateString()</p>

@code {
    public object SelectedRange = new DateTime[] 
    { 
        new DateTime(2022, 01, 01), 
        new DateTime(2023, 01, 01) 
    };
    
    public List<StockInfo> StockData = GetStockData();
    
    private static List<StockInfo> GetStockData()
    {
        // Sample data generation
        var data = new List<StockInfo>();
        var startDate = new DateTime(2020, 01, 01);
        var random = new Random();
        
        for (int i = 0; i < 100; i++)
        {
            data.Add(new StockInfo 
            { 
                Date = startDate.AddDays(i * 10), 
                Close = 100 + random.Next(-20, 20) 
            });
        }
        
        return data;
    }

    public class StockInfo
    {
        public DateTime Date { get; set; }
        public double Close { get; set; }
    }
}

2. 範囲ベースのフィルタリングを備えたダッシュボード

チャートデータをレンジセレクターと同期します：

@using Syncfusion.Blazor.Charts

<div class="dashboard-container">
    <h3>Sales Dashboard</h3>
    <SfRangeNavigator Value="@SelectedRange"
                      ValueType="RangeValueType.DateTime"
                      Height="140px">

        <RangeNavigatorEvents Changed="OnRangeChanged" />

        <RangeNavigatorSeriesCollection>
            <RangeNavigatorSeries DataSource="@SalesDetails"
                                  XName="Date"
                                  YName="Revenue"
                                  Type="RangeNavigatorType.Area" />
        </RangeNavigatorSeriesCollection>

    </SfRangeNavigator>
    <SfChart Height="300px">
        <ChartPrimaryXAxis ValueType="Syncfusion.Blazor.Charts.ValueType.DateTime"
                           Minimum="@SelectedRange[0]"
                           Maximum="@SelectedRange[1]" />

        <ChartSeriesCollection>
            <ChartSeries DataSource="@FilteredData"
                         XName="Date"
                         YName="Revenue"
                         Type="ChartSeriesType.Column" />
        </ChartSeriesCollection>
    </SfChart>
</div>

@code {
    public DateTime[] SelectedRange =
    {
        new DateTime(2023, 01, 01),
        new DateTime(2023, 06, 30)
    };

    public List<SalesData> SalesDetails = new();
    public List<SalesData> FilteredData = new();

    protected override void OnInitialized()
    {
        SalesDetails = GetSalesData();
        ApplyFilter();
    }

    private void OnRangeChanged(ChangedEventArgs args)
    {
        if (args.Start is DateTime start && args.End is DateTime end)
        {
            SelectedRange = new[] { start, end };
            ApplyFilter();
        }
    }

    private void ApplyFilter()
    {
        FilteredData = SalesDetails
            .Where(d => d.Date >= SelectedRange[0] && d.Date <= SelectedRange[1])
            .ToList();
    }

    private List<SalesData> GetSalesData()
    {
        var data = new List<SalesData>();
        var random = new Random();
        var start = new DateTime(2023, 01, 01);
        decimal revenue = 15000;

        for (int i = 0; i < 180; i++)
        {
            revenue += random.Next(-1500, 2000);

            data.Add(new SalesData
            {
                Date = start.AddDays(i),
                Revenue = Math.Max(revenue, 5000)
            });
        }

        return data;
    }

    public class SalesData
    {
        public DateTime Date { get; set; }
        public decimal Revenue { get; set; }
    }
}

3. パフォーマンス向上のための軽量モード

大規模なデータセット向けに最適化します：

@using Syncfusion.Blazor.Charts

<SfRangeNavigator Value="@SelectedRange" 
                  ValueType="RangeValueType.DateTime"
                  EnableGrouping="true"
                  GroupBy="RangeIntervalType.Months"
                  AllowSnapping="true">
    <RangeNavigatorRangeTooltipSettings Enable="true"></RangeNavigatorRangeTooltipSettings>
    <RangeNavigatorSeriesCollection>
        <RangeNavigatorSeries DataSource="@LargeDataset" 
                              XName="Timestamp" 
                              YName="Value"
                              Type="RangeNavigatorType.Line">
        </RangeNavigatorSeries>
    </RangeNavigatorSeriesCollection>
</SfRangeNavigator>

@code {
    public DateTime[] SelectedRange;
    public List<DataPoint> LargeDataset = GenerateLargeDataset(10000);

    public class DataPoint
    {
        public DateTime Timestamp { get; set; }
        public double Value { get; set; }
    }
    
    private static List<DataPoint> GenerateLargeDataset(int count)
    {
        // Generate large dataset efficiently
        return Enumerable.Range(0, count)
            .Select(i => new DataPoint 
            { 
                Timestamp = DateTime.Now.AddHours(-count + i), 
                Value = Math.Sin(i * 0.1) * 100 
            })
            .ToList();
    }
}

主要プロパティのリファレンス

必須プロパティ

プロパティ	型	説明	デフォルト
Value	DateTime[] / double[]	選択範囲 [start, end]	null
ValueType	RangeValueType	データ型（DateTime、Double、Logarithmic）	Double
DataSource	object	系列のデータコレクション	null
IntervalType	RangeIntervalType	軸の間隔（Auto、Years、Months、Days など）	Auto
LabelFormat	string	ラベルの表示形式	null
Width	string	コンポーネントの幅	"100%"
Height	string	コンポーネントの高さ	"80px"
Theme	Theme	ビジュアルテーマ（Material、Bootstrap5、Fluent、Tailwind、Fabric、HighContrast）	Material
Interval	int	軸の間隔値	1
LogBase	double	対数軸の底	10
Orientation	Orientation	水平または垂直	Horizontal

シリーズの設定

プロパティ	型	説明	デフォルト
Type	RangeNavigatorType	シリーズの種類（Line、Area、StepLine）	Line
XName	string	X 軸データのフィールド名	null
YName	string	Y 軸データのフィールド名	null
Fill	string	シリーズの塗りつぶし色	null
Width	double	シリーズの線の幅	1
Opacity	double	シリーズの不透明度（0～1）	1
Name	string	シリーズ名／ラベル	null

表示プロパティ

プロパティ	型	説明	デフォルト
EnableGrouping	bool	データのグループ化を有効にします	false
AllowSnapping	bool	サムをデータポイントにスナップします	false
EnableRtl	bool	右から左への表示をサポートします	false
TabIndex	int	キーボード操作用のタブインデックス	0

期間セレクター

プロパティ	型	説明
RangeNavigatorPeriodSelectorSettings	Component	期間セレクターの設定（Enabled、Height、Position）
RangeNavigatorPeriods	Collection	期間ボタンのコレクションコンテナー
RangeNavigatorPeriod	Item	個別の期間セレクターボタン（Text、Interval、IntervalType、Selected）

ツールチップの設定

プロパティ	型	説明	デフォルト
RangeNavigatorRangeTooltipSettings.Enable	bool	ツールチップを有効／無効にします	true
RangeNavigatorRangeTooltipSettings.DisplayMode	TooltipDisplayMode	表示モード（OnDemand、Always）	OnDemand
RangeNavigatorRangeTooltipSettings.Format	string	ツールチップの内容の書式テンプレート	null

軸のカスタマイズ

プロパティ	型	説明
RangeNavigatorMargin	Component	余白（Left、Right、Top、Bottom）
RangeNavigatorBorder	Component	枠線（Color、Width、DashArray）
RangeNavigatorMajorGridLines	Component	目盛線（Width、Color、DashArray）
RangeNavigatorMajorTickLines	Component	目盛り線（Width、Color、Height）
RangeNavigatorLabelStyle	Component	ラベルのスタイル（Color、FontFamily、Size、FontWeight）

サムの設定

プロパティ	型	説明	デフォルト
RangeNavigatorThumbSettings.Type	ThumbType	サムの形状（Circle、Rectangle）	Circle
RangeNavigatorThumbSettings.Fill	string	サムの塗りつぶし色	"#f3f3f3"
RangeNavigatorThumbSettings.Size	double	サムのサイズ（ピクセル単位）	15

イベントリファレンス

Range Navigator の操作を処理する主なイベント：

イベント	イベント引数	説明
Changed	ChangedEventArgs	範囲の選択が変更されたときに発生します（開始、終了、値）
Loaded	RangeLoadedEventArgs	コンポーネントの読み込み完了後に発生します
Resizing	RangeResizeEventArgs	サムのドラッグ中に発生します
Resized	RangeResizeEventArgs	サムのドラッグ完了後に発生します
Rendering	RangeSelectorRenderEventArgs	セレクターの描画前に発生します
TooltipRender	RangeTooltipRenderEventArgs	ツールチップの描画前に発生します
LabelRender	RangeLabelRenderEventArgs	ラベルの描画時に発生します

イベントハンドラーの例：

private void OnRangeChanged(ChangedEventArgs args)
{
    var startValue = args.Start;  // DateTime or double
    var endValue = args.End;      // DateTime or double
    var selectedData = args.SelectedData;  // Filtered data
    StateHasChanged();
}

メソッドリファレンス

プログラムから制御するための主なメソッド：

メソッド	戻り値の型	説明
ExportAsync(ExportType, string)	Task	PNG、JPEG、SVG、または PDF としてエクスポートします
Print()	Task	Range Navigator を印刷します
Refresh()	Task	コンポーネントを更新／再描画します
GetVisibleRangeModel()	VisibleRangeModel	現在表示されている範囲を取得します

実装ワークフロー

範囲セレクターを実装する際は、次の手順に従ってください。

1. インストールと基本設定については、まずGetting Startedを確認します
2. 選択動作を設定するには、Range Configurationを参照して範囲の値を設定します
3. 視覚化に使用する系列タイプをSeries Typesから選択します
4. データ構造に合わせてData Bindingを参照し、データバインディングを設定します — リモートデータを使用する場合は、信頼できる内部 API またはモックデータを優先してください。Data Binding - Security Considerationsを参照してください
5. Period Selector Integrationを使って、期間セレクターを追加します（任意）
6. 適切なラベルを設定するには、Axis Customizationで軸をカスタマイズします
7. Visual Customizationを参照して、視覚スタイルを適用します
8. Export, Events, and Accessibilityを使って、エクスポートとイベントを追加します
9. クラス、プロパティ、列挙型をすべて網羅した完全な API ドキュメントについては、API Referenceを確認します

質問や問題がある場合は、各リファレンスファイルのトラブルシューティングのセクションを参照するか、イベント処理のパターンとアクセシビリティ要件についてExport, Events, and Accessibilityを確認してください。