syncfusion-blazor-charts（同步融合 Blazor 图表）

Implementing Syncfusion Blazor Charts

A comprehensive guide for implementing the Syncfusion Blazor Chart component to create interactive, feature-rich data visualizations in Blazor applications. The Chart component supports 33+ chart types, multiple axes, advanced interactivity, and extensive customization options.

When to Use This Skill

Use this skill when you need to:

• Create data visualizations in Blazor applications (line, column, bar, area, etc.)
• Implement financial charts for stock analysis (candle, HILO, HILOOC)
• Build statistical visualizations (histogram, box-whisker, pareto, waterfall)
• Display comparative data with stacked or grouped charts
• Show range-based data with range area/column charts
• Create polar or radar charts for circular data representation
• Add interactive features like tooltips, zooming, crosshair, selection
• Customize chart appearance with themes, gradients, annotations
• Handle dynamic data with live updates and data editing
• Implement accessible charts with ARIA support and internationalization

Component Overview

The Syncfusion Blazor Chart component is a powerful data visualization tool that provides:

• 33+ Chart Types: Line, Column, Bar, Area, Spline, Scatter, Bubble, Candle, HILO, Polar, Radar, and more
• Multiple Axes: Support for category, numeric, datetime, and logarithmic axes
• Rich Interactivity: Zooming, panning, crosshair, trackball, tooltips, selection
• Data Binding: Work with List, DataManager, dynamic updates, and live data
• Visual Elements: Markers, data labels, annotations, legends, gradients
• Advanced Features: Technical indicators, trend lines, strip lines, multiple panes
• Accessibility: Full ARIA support, keyboard navigation, localization, RTL
• Customization: Themes, responsive design, print support, adaptive layout

Documentation and Navigation Guide

Complete API Reference

📄 Read: references/api-reference.md

CRITICAL: Use this reference FIRST for all API-related questions

Use this authoritative API reference when:

• Looking up correct enum values (ChartSeriesType, ValueType, SelectionMode, etc.)
• Finding public method signatures (RefreshAsync, ExportAsync, ShowTooltip, etc.)
• Verifying property names and types
• Generating code samples
• Troubleshooting API-related issues

Topics covered:

• Complete list of SfChart public methods with signatures
• All chart enumerations with correct values
• Key component classes and their properties
• Method usage examples
• Common patterns and best practices

Key Points:

• All enum values are exact - do not use variations
• Method names follow C# conventions (e.g., RefreshAsync not Refresh)
• Always use @ref to access chart instance for method calls
• Namespace: Syncfusion.Blazor.Charts

Getting Started

📄 Read: references/getting-started.md

Use this when:

• Setting up a new Blazor Chart project
• Installing NuGet packages and configuring services
• Creating your first chart component
• Understanding basic chart structure and data binding
• Working with Visual Studio, VS Code, or.NET CLI

Topics covered:

• Installation and prerequisites
• Package setup (Syncfusion.Blazor.Charts)
• Namespace imports and service registration
• Script references
• Basic chart implementation
• Simple data binding example

Chart Types

Common Chart Types

📄 Read: references/chart-types-common.md

Use this for frequently-used chart types:

• Line charts for trend visualization
• Area charts for showing magnitude over time
• Column charts for categorical comparisons
• Bar charts for horizontal comparisons
• Spline charts for smooth curves
• Step charts for stepped data progression

Topics covered:

• Line, Area, Column, Bar chart implementations
• Spline and Spline Area variations
• Step Line and Step Area patterns
• When to use each chart type
• Configuration and customization
• Multi-series examples

Specialized Chart Types

📄 Read: references/chart-types-specialized.md

Use this for specialized visualization needs:

• Financial charts (Candle, HILO, HILOOC)
• Statistical charts (Box-Whisker, Histogram, Error Bar, Pareto, Waterfall)
• Stacked charts (Stack Area/Bar/Column/Line)
• Range charts (Range Area/Column/Step Area)
• Polar and Radar charts
• Scatter and Bubble charts
• Vertical chart orientation

Topics covered:

• Financial chart patterns and configurations
• Statistical analysis chart types
• Stacking modes (normal vs 100%)
• Range visualization techniques
• Circular chart layouts
• XY scatter relationships
• Chart orientation options

Axes and Data Configuration

📄 Read: references/axes-and-scales.md

Use this when:

• Configuring axis types (category, numeric, datetime, logarithmic)
• Customizing axis appearance and behavior
• Formatting axis labels and values
• Working with multiple axes
• Setting axis ranges and intervals

Topics covered:

• Category axis for discrete data
• Numeric axis for continuous values
• DateTime axis for time-series data
• Logarithmic axis for exponential data
• Axis customization (title, range, interval)
• Label formatting, rotation, and positioning
• Multiple axis configuration
• Inverse and opposed axes

📄 Read: references/data-handling.md

Use this when:

• Binding data sources to charts
• Adding, removing, or updating data dynamically
• Enabling data editing
• Sorting chart data
• Working with live or streaming data

Topics covered:

• Data source binding (List, DataManager)
• Dynamic data operations
• Data editing functionality
• Chart sorting options
• Real-time data updates
• Data serialization patterns

Visual Elements

📄 Read: references/visual-elements.md

Use this when:

• Adding data markers to chart points
• Displaying data labels on series
• Creating custom label templates
• Adding annotations (text, shapes, images)
• Applying gradient fills

Topics covered:

• Data marker types and customization
• Data label visibility and formatting
• Label positioning strategies
• Data label templates
• Last data label highlighting
• Chart annotations (text, shapes, images)
• Gradient color fills

📄 Read: references/legend.md

Use this when:

• Enabling and configuring chart legend
• Positioning legend (top, bottom, left, right)
• Customizing legend appearance
• Implementing legend click behavior
• Creating custom legend templates

Topics covered:

• Legend visibility and positioning
• Legend shape and text customization
• Interactive legend (toggle series)
• Legend pagination
• Custom legend templates
• Legend alignment options

Interactive Features

📄 Read: references/interactive-features.md

Use this when:

• Enabling tooltips with custom formatting
• Adding crosshair or trackball for data tracking
• Implementing point, series, or cluster selection
• Enabling zooming and panning
• Creating interactive user experiences

Topics covered:

• Tooltip configuration and templates
• Crosshair and trackball features
• Selection modes and patterns
• Zoom types (selection, pinch, mousewheel)
• Zoom toolbar configuration
• Pan functionality
• User interaction events

Customization and Appearance

📄 Read: references/appearance-styling.md

Use this when:

• Customizing chart appearance and themes
• Setting chart dimensions and sizing
• Configuring responsive/adaptive layout
• Enabling print functionality
• Styling background, borders, and margins

Topics covered:

• Chart appearance customization
• Theme configuration
• Chart dimensions and sizing
• Responsive design patterns
• Adaptive layout for mobile
• Print support
• Background and border styling
• Gradient customization

📄 Read: references/advanced-features.md

Use this when:

• Adding technical indicators (EMA, SMA, RSI, etc.)
• Implementing trend lines (linear, exponential, polynomial)
• Creating strip lines (horizontal/vertical bands)
• Using multiple panes (sub-charts)
• Handling empty points

Topics covered:

• Technical indicators for financial charts
• Trend line types and configuration
• Strip line patterns
• Multiple pane layouts
• Empty point handling strategies
• Row and column definitions

Accessibility and Internationalization

📄 Read: references/accessibility-internationalization.md

Use this when:

• Implementing accessible charts (ARIA, keyboard nav)
• Configuring advanced accessibility features
• Enabling internationalization (i18n)
• Setting up localization (l10n)
• Supporting RTL layouts

Topics covered:

• Accessibility features and ARIA support
• Keyboard navigation patterns
• Advanced accessibility configuration
• Internationalization setup
• Localization resources
• RTL support
• Screen reader compatibility

Events

📄 Read: references/events.md

Use this when:

• Handling chart lifecycle events
• Responding to user interactions (clicks, mouse events)
• Listening to axis, series, or point events
• Implementing custom event handlers
• Triggering actions on zoom, pan, or selection

Topics covered:

• Chart load and render events
• Point and series events
• Mouse events (click, move, leave)
• Axis label render events
• Legend events
• Zoom and pan events
• Selection events
• Event handler patterns

Practical Examples and How-To Guides

📄 Read: references/practical-examples.md

Use this for common implementation scenarios:

• Adding/removing series dynamically
• Hiding axes programmatically
• Converting milliseconds to datetime
• Updating points dynamically
• Implementing lazy loading
• Creating live/real-time charts
• Getting selected data
• Synchronizing multiple charts
• Adding threshold lines
• Custom tooltip tables

Topics covered:

• Dynamic series management
• Axis visibility control
• Date conversion techniques
• Dynamic point updates
• Lazy loading patterns
• Live chart implementation
• Selection data retrieval
• Chart synchronization
• Threshold line implementation
• Custom tooltip tables

Public Methods Reference

The SfChart component provides several public methods for programmatic control. Always use @ref to access these methods:

Essential Methods

<SfChart @ref="ChartRef">
    <!-- Configuration -->
</SfChart>

@code {
    SfChart ChartRef;

    // Refresh the chart
    async Task RefreshChart() => await ChartRef.RefreshAsync();

    // Export the chart
    async Task ExportChart() => await ChartRef.ExportAsync(ExportType.PNG, "chart.png");

    // Print the chart
    async Task PrintChart() => await ChartRef.PrintAsync();

    // Show/Hide tooltip
    void ShowChartTooltip() => ChartRef.ShowTooltip("January", 35);
    void HideChartTooltip() => ChartRef.HideTooltip();

    // Show/Hide crosshair
    void ShowChartCrosshair() => ChartRef.ShowCrosshair(100, 50);
    void HideChartCrosshair() => ChartRef.HideCrosshair();

    // Selection control
    void ClearSelections() => ChartRef.ClearSelection();

    // Sorting
    void SortData() => ChartRef.Sort("YValue", ListSortDirection.Descending);
    void ClearChartSort() => ChartRef.ClearSort();
}

See references/api-reference.md for complete method documentation.

⚠️ CRITICAL: API Usage Guidelines

1. Enum Names - MUST Use Full Namespace

Syncfusion Blazor Charts requires FULLY QUALIFIED enum names:

<!-- ✅ CORRECT - Use full namespace -->
<ChartPrimaryXAxis ValueType="Syncfusion.Blazor.Charts.ValueType.Category" />
<ChartSeries Type="Syncfusion.Blazor.Charts.ChartSeriesType.Column" />

<!-- ❌ WRONG - Short form will cause errors -->
<ChartPrimaryXAxis ValueType="ValueType.Category" />
<ChartSeries Type="ChartSeriesType.Column" />

Always use Syncfusion.Blazor.Charts. prefix for:

• ValueType (Category, Double, DateTime, etc.)
• ChartSeriesType (Column, Line, Area, etc.)
• LegendPosition, SelectionMode, ZoomMode, ChartShape, etc.

2. Component Property Restrictions

⚠️ Common Property Errors to Avoid:

ChartCrosshairLine - Limited Properties

<!-- ✅ CORRECT - Only Width and Color supported -->
<ChartCrosshairSettings Enable="true">
    <ChartCrosshairLine Width="1" Color="#666"></ChartCrosshairLine>
</ChartCrosshairSettings>

<!-- ❌ WRONG - DashArray NOT supported on ChartCrosshairLine -->
<ChartCrosshairLine Width="1" Color="#666" DashArray="5,5"></ChartCrosshairLine>

Supported ChartCrosshairLine Properties:

• Width - Line width (number)
• Color - Line color (string)

NOT Supported:

• ❌ DashArray - Will cause runtime error
• ❌ Opacity - Not available on this component

Striplines - Use Plural Form

<!-- ✅ CORRECT - ChartStriplines (plural) -->
<ChartPrimaryYAxis>
    <ChartStriplines>
        <ChartStripline Start="50" End="60" Color="red" />
    </ChartStriplines>
</ChartPrimaryYAxis>

<!-- ❌ WRONG - ChartAxisStripLineSettings does not exist -->
<ChartAxisStripLineSettings>
    <ChartAxisStripLine Start="50" End="60" />
</ChartAxisStripLineSettings>

3. Validation Checklist

Before deploying, verify:

• ✅ All enums use Syncfusion.Blazor.Charts. prefix
• ✅ ChartCrosshairLine uses ONLY Width and Color
• ✅ Striplines use <ChartStriplines> and <ChartStripline>
• ✅ Component references use @ref for method access
• ✅ Property names match official API exactly (case-sensitive)

Quick Start Example

Here's a minimal example to create a column chart with data:

@page "/chart-demo"
@using Syncfusion.Blazor.Charts

<SfChart Title="Sales Analysis">
    <ChartPrimaryXAxis Title="Month" ValueType="Syncfusion.Blazor.Charts.ValueType.Category">
    </ChartPrimaryXAxis>

    <ChartPrimaryYAxis Title="Sales in Dollar">
    </ChartPrimaryYAxis>

    <ChartTooltipSettings Enable="true"></ChartTooltipSettings>

    <ChartSeriesCollection>
        <ChartSeries DataSource="@SalesData"
                     Name="Sales"
                     XName="Month"
                     YName="SalesValue"
                     Type="Syncfusion.Blazor.Charts.ChartSeriesType.Column">
            <ChartMarker>
                <ChartDataLabel Visible="true"></ChartDataLabel>
            </ChartMarker>
        </ChartSeries>
    </ChartSeriesCollection>
</SfChart>

@code {
    public class SalesInfo
    {
        public string Month { get; set; }
        public double SalesValue { get; set; }
    }

    public List<SalesInfo> SalesData = new List<SalesInfo>
    {
        new SalesInfo { Month = "Jan", SalesValue = 35 },
        new SalesInfo { Month = "Feb", SalesValue = 28 },
        new SalesInfo { Month = "Mar", SalesValue = 34 },
        new SalesInfo { Month = "Apr", SalesValue = 32 },
        new SalesInfo { Month = "May", SalesValue = 40 },
        new SalesInfo { Month = "Jun", SalesValue = 32 }
    };
}

Prerequisites:

1. Install Syncfusion.Blazor.Charts NuGet package
2. Add @using Syncfusion.Blazor.Charts to _Imports.razor
3. Register service: builder.Services.AddSyncfusionBlazor(); in Program.cs
4. Add script reference in App.razor

Common Patterns

Multi-Series Comparison Chart

<SfChart Title="Product Sales Comparison">
    <ChartPrimaryXAxis ValueType="Syncfusion.Blazor.Charts.ValueType.Category"></ChartPrimaryXAxis>

    <ChartSeriesCollection>
        <ChartSeries DataSource="@Product1Sales" XName="Month" YName="Sales"
                     Name="Product 1" Type="Syncfusion.Blazor.Charts.ChartSeriesType.Column">
        </ChartSeries>
        <ChartSeries DataSource="@Product2Sales" XName="Month" YName="Sales"
                     Name="Product 2" Type="Syncfusion.Blazor.Charts.ChartSeriesType.Column">
        </ChartSeries>
    </ChartSeriesCollection>

    <ChartLegendSettings Visible="true"></ChartLegendSettings>
</SfChart>

Time-Series Line Chart with Zooming

<SfChart>
    <ChartPrimaryXAxis ValueType="Syncfusion.Blazor.Charts.ValueType.DateTime"
                        Title="Date">
    </ChartPrimaryXAxis>

    <ChartZoomSettings EnableSelectionZooming="true"
                       EnablePan="true"
                       EnableMouseWheelZooming="true">
    </ChartZoomSettings>

    <ChartSeriesCollection>
        <ChartSeries DataSource="@TimeSeriesData"
                     XName="Date"
                     YName="Value"
                     Type="Syncfusion.Blazor.Charts.ChartSeriesType.Line">
        </ChartSeries>
    </ChartSeriesCollection>
</SfChart>

Stacked Area Chart with Legend

<SfChart Title="Resource Allocation">
    <ChartPrimaryXAxis ValueType="Syncfusion.Blazor.Charts.ValueType.Category"></ChartPrimaryXAxis>

    <ChartSeriesCollection>
        <ChartSeries DataSource="@ResourceData1" XName="Period" YName="Hours"
                     Name="Development" Type="Syncfusion.Blazor.Charts.ChartSeriesType.StackingArea">
        </ChartSeries>
        <ChartSeries DataSource="@ResourceData2" XName="Period" YName="Hours"
                     Name="Testing" Type="Syncfusion.Blazor.Charts.ChartSeriesType.StackingArea">
        </ChartSeries>
        <ChartSeries DataSource="@ResourceData3" XName="Period" YName="Hours"
                     Name="Documentation" Type="Syncfusion.Blazor.Charts.ChartSeriesType.StackingArea">
        </ChartSeries>
    </ChartSeriesCollection>

    <ChartLegendSettings Visible="true" Position="Syncfusion.Blazor.Charts.LegendPosition.Bottom">
    </ChartLegendSettings>
</SfChart>

Key Configuration Properties

Chart Component (SfChart)

• Title - Chart title text
• Width / Height - Chart dimensions (accepts px or %, default: "100%")
• Theme - Visual theme (see Theme enum in API reference)
• Background - Chart background color
• EnableAnimation - Enable/disable animation (default: true)
• SelectionMode - Selection mode (None, Series, Point, Cluster, DragXY, DragX, DragY, Lasso)
• HighlightMode - Highlight mode (None, Series, Point, Cluster)

Primary Axes (ChartPrimaryXAxis, ChartPrimaryYAxis)

• ValueType - Axis type: Syncfusion.Blazor.Charts.ValueType.Category, ValueType.Double, ValueType.DateTime, ValueType.Logarithmic, ValueType.DateTimeCategory
• Title - Axis title
• Minimum / Maximum - Axis range
• Interval - Spacing between labels
• LabelFormat - Format string for labels (e.g., "C0", "N2", "dd MMM")
• EdgeLabelPlacement - Edge label handling (None, Hide, Shift)
• LabelIntersectAction - Label intersection handling (None, Hide, Trim, Wrap, MultipleRows, Rotate45, Rotate90)
• Striplines - Use <ChartStriplines> (plural) for horizontal/vertical bands

Series (ChartSeries)

• DataSource - Data collection (IEnumerable)
• XName / YName - Property names for X and Y values (case-sensitive)
• Type - Chart type: Syncfusion.Blazor.Charts.ChartSeriesType.Column, ChartSeriesType.Line, etc. (see API reference)
• Name - Series name for legend
• Fill - Series color (CSS color string)
• Width - Line/border width (pixels)
• DashArray - Dash pattern (e.g., "5,5")
• Opacity - Transparency (0 to 1)

Interactivity

• ChartTooltipSettings - Tooltip configuration

- Enable - Show/hide tooltip - Shared - Enable shared tooltip for multiple series - Format - Custom tooltip format - Template - Custom tooltip template (RenderFragment)

• ChartZoomSettings - Zoom and pan options

- EnableSelectionZooming - Enable selection-based zoom - EnableMouseWheelZooming - Enable mouse wheel zoom - EnablePinchZooming - Enable pinch zoom (touch devices) - EnablePan - Enable panning - Mode - Zoom mode (X, Y, XY)

• SelectionMode - Selection behavior (see SelectionMode enum)
• ChartCrosshairSettings - Crosshair configuration

- Enable - Show/hide crosshair - LineType - Crosshair line type (Vertical, Horizontal, Both) - ChartCrosshairLine - Line style (Width, Color ONLY - NO DashArray)

Visual Elements

• ChartMarker - Data point markers

- Visible - Show/hide markers - Shape - Marker shape (see ChartShape enum) - Width / Height - Marker dimensions

• ChartDataLabel - Data labels on points

- Visible - Show/hide labels - Position - Label position - Template - Custom label template

• ChartLegendSettings - Legend configuration

- Visible - Show/hide legend - Position - Legend position (see LegendPosition enum)

• ChartAnnotations - Custom annotations

- Support for text, images, and shapes

Additional Resources

• Official Documentation: Syncfusion Blazor Chart Documentation
• API Reference: Chart API
• Live Demos: Blazor Chart Demos