Skip to content

ReactorD3 分两层,你选择在哪一层上创作。高层 DSL —— LineChart、BarChart、AreaChart、PieChart,外加 TreeChart 和 ForceGraph —— 覆盖了仪表盘反复要的那些场景:一个系列、一个 x 访问器、一个 y 访问器,以及一个由库替你接好的、有主张的视觉表面(坐标轴、网格、调色板、键盘导航、屏幕阅读器摘要)。当有主张的表面不合身时 —— 你想把某个扇区的百分比渲染在扇区内部、你想要一张热力图、你想要一个定制的平行坐标视图 —— 同一个库又暴露了构建出那些高层形状的 D3 基元:LinearScale、BandScale、D3Canvas、D3LinePath<T>、D3ArcPath,以及高层图表上的 *LabelView 逃生舱。这与 Recharts 和 Observable Plot 所画的取舍相同 —— 便利优先,逃生舱在下面 —— 只不过每个 D3 基元都渲染为 WinUI 形状,且用着与高层图表相同的那块 Canvas,因此降一层绝不意味着换渲染器。默认挑高层;只有当高层表面拒绝了你要的东西时才下探到 D3。

图表

ReactorD3 把数据可视化带进 Microsoft.UI.Reactor(Reactor)。图表 DSL 提供 LineChart、BarChart、AreaChart 和 PieChart 等高层工厂方法,产出标准的 Reactor 元素。你绑定数据,用流畅 API 配置外观,图表就渲染为 Canvas 上的原生 WinUI 形状。

把 DSL 与标准 Reactor 工厂方法一并导入。图表由可选的 Microsoft.UI.Reactor.Advanced 包提供(spec 062 §7),所以先加上它的包引用:

<PackageReference Include="Microsoft.UI.Reactor.Advanced" Version="0.1.0-preview.15" />
using static Microsoft.UI.Reactor.Factories;
using static Microsoft.UI.Reactor.Charting.Charts;

折线图

LineChart 在你的数据点上画一条连续折线。传入一个集合以及 X 和 Y 的访问器函数:

class LineChartDemo : Component
{
    private static readonly SalesPoint[] Data =
    [
        new(1, 120), new(2, 180), new(3, 150),
        new(4, 220), new(5, 310), new(6, 280),
        new(7, 350), new(8, 400), new(9, 380),
        new(10, 420), new(11, 460), new(12, 510)
    ];

    public override Element Render()
    {
        return VStack(12,
            SubHeading("Line Chart"),
            LineChart(Data, d => d.Month, d => d.Revenue)
                .Title("Monthly Revenue — Line")
                .SeriesName("Revenue")
                .Units("months", "USD")
                .AxisLabel(ChartAxisType.X, "Month")
                .AxisLabel(ChartAxisType.Y, "Revenue (USD)")
                .Width(600).Height(250)
                .Stroke("#0078D4").StrokeWidth(2.5)
                .ShowGrid(true).ShowAxes(true)
        ).Padding(24);
    }
}

折线图

图表会自动缩放坐标轴以适配你的数据,并做 .Nice() 取整。用 .ShowGrid() 开关网格线,用 .ShowAxes() 开关坐标轴标签。

条形图

BarChart 渲染竖直条。每个数据点变成一根条,其高度映射到 Y 值:

class BarChartDemo : Component
{
    private static readonly SalesPoint[] Data =
    [
        new(1, 340), new(2, 420), new(3, 510), new(4, 380)
    ];

    public override Element Render()
    {
        return VStack(12,
            SubHeading("Bar Chart"),
            BarChart(Data, d => d.Month, d => d.Revenue)
                .Title("Quarterly Revenue — Bar")
                .SeriesName("Revenue")
                .Units("quarters", "USD")
                .AxisLabel(ChartAxisType.X, "Quarter")
                .AxisLabel(ChartAxisType.Y, "Revenue (USD)")
                .Width(600).Height(250)
                .Fill("#50C878")
                .ShowGrid(true).ShowAxes(true)
        ).Padding(24);
    }
}

条形图

条宽根据数据点数量自动计算。用 .Fill() 设置条形颜色,用 .FillOpacity() 控制透明度。

面积图

AreaChart 填充数据折线与基线之间的区域。它把填充区域与一条折线叠加起来:

class AreaChartDemo : Component
{
    private static readonly SalesPoint[] Data =
    [
        new(1, 50), new(2, 120), new(3, 200),
        new(4, 350), new(5, 480), new(6, 600),
        new(7, 720), new(8, 850), new(9, 1020),
        new(10, 1150), new(11, 1300), new(12, 1500)
    ];

    public override Element Render()
    {
        return VStack(12,
            SubHeading("Area Chart"),
            AreaChart(Data, d => d.Month, d => d.Revenue)
                .Title("Monthly Revenue — Area")
                .SeriesName("Revenue")
                .Units("months", "USD")
                .AxisLabel(ChartAxisType.X, "Month")
                .AxisLabel(ChartAxisType.Y, "Revenue (USD)")
                .Width(600).Height(250)
                .Stroke("#9B59B6").Fill("#9B59B6")
                .FillOpacity(0.2)
                .ShowGrid(true).ShowAxes(true)
        ).Padding(24);
    }
}

面积图

用 .FillOpacity() 控制区域透明度。取一个较低的值(0.15--0.3),既让网格线透出来,又能填满形状。

饼图

PieChart 把数据分成成比例的弧。把 .InnerRadius() 设为大于 0 就得到环形图:

class PieChartDemo : Component
{
    private static readonly CategoryData[] Data =
    [
        new("Engineering", 42),
        new("Marketing", 18),
        new("Sales", 25),
        new("Support", 15)
    ];

    public override Element Render()
    {
        return VStack(12,
            SubHeading("Pie Chart"),
            PieChart(Data, d => d.Value, d => d.Name)
                .Title("Team Distribution")
                .Description("Pie chart showing team size across Engineering, Marketing, Sales, and Support.")
                .Width(300).Height(300)
                .InnerRadius(60)
                .PadAngle(0.03)
        ).Padding(24);
    }
}

饼图

传入一个标签访问器即可在每条弧的重心处显示文本。颜色默认在 Category10 调色板里循环 —— 用 .SetColors() 覆盖。

图表配置

所有图表类型共享一组通用的构造器方法:

方法 默认值 用途
.Width(n) 400 画布宽度(像素)
.Height(n) 300 画布高度(像素)
.Margin(l, t, r, b) 40, 20, 20, 30 坐标轴/标签边距,顺序为 left, top, right, bottom
.Stroke(color) #4285f4 线条/边框颜色
.Fill(color) #4285f4 填充颜色
.StrokeWidth(n) 2 线条粗细
.FillOpacity(n) 0.3 填充透明度(0--1)
.ShowAxes(bool) true 显示坐标轴线与标签
.ShowGrid(bool) true 显示横向网格线

颜色接受任何 CSS 风格的字符串:#RGB、#RRGGBB、rgb(r,g,b),或 steelblue 这类具名颜色。想要能随深色模式自适应的调色板感知颜色,参见 styling 和下面的 .Palette(...) 无障碍修饰符。

把数据绑定到状态

图表是标准 Reactor 元素。状态变化时,图表用新数据重新渲染:

class CombinedChartDemo : Component
{
    private static readonly SalesPoint[] Data2024 =
    [
        new(1, 100), new(2, 140), new(3, 180),
        new(4, 200), new(5, 260), new(6, 300)
    ];

    private static readonly SalesPoint[] Data2025 =
    [
        new(1, 160), new(2, 220), new(3, 280),
        new(4, 320), new(5, 390), new(6, 450)
    ];

    private static readonly string[] Years = ["2024", "2025"];

    public override Element Render()
    {
        var (year, setYear) = UseState(0);
        var data = year == 0 ? Data2024 : Data2025;

        return VStack(12,
            SubHeading("Interactive Chart"),
            ComboBox(Years, year, setYear),
            AreaChart(data, d => d.Month, d => d.Revenue)
                .Title("Revenue by Year")
                .SeriesName("Revenue")
                .Units("months", "USD")
                .Interactive()
                .Width(600).Height(250)
                .Stroke("#0078D4").Fill("#0078D4")
                .FillOpacity(0.15)
                .ShowGrid(true).ShowAxes(true)
        ).Padding(24);
    }
}

交互式图表

用 hooks 里的 UseState 之类来驱动数据选择。图表在每次渲染时重建 —— 为保持交互流畅,请把数据集控制在约 1000 个点以内。

动态数据更新

图表是原生 Reactor 元素,因此你只需要改状态。用 UseState、UseReducer 或任何 Hook 来更新数据 —— 协调器会对新旧元素树做差异比对,只打补丁变化的部分:

class DynamicDataDemo : Component
{
    private static readonly List<SalesPoint> InitialPoints =
        Enumerable.Range(1, 8)
            .Select(i => new SalesPoint(i, Random.Shared.Next(50, 500)))
            .ToList();

    public override Element Render()
    {
        var (points, updatePoints) = UseReducer(InitialPoints);

        return VStack(12,
            SubHeading("Dynamic Data"),
            Button("Randomize", () => updatePoints(_ =>
                Enumerable.Range(1, 8)
                    .Select(i => new SalesPoint(i, Random.Shared.Next(50, 500)))
                    .ToList())),
            BarChart<SalesPoint>(points, d => d.Month, d => d.Revenue)
                .Title("Dynamic Revenue Data")
                .SeriesName("Revenue")
                .Units("months", "USD")
                .Width(600).Height(250)
                .Fill("#E74C3C")
                .ShowGrid(true).ShowAxes(true)
        ).Padding(24);
    }
}

动态数据

对于高频更新(60fps 流式),用 OnReady 拿到一个句柄,它暴露底层 Canvas 供直接操作。这与动画管线用的是同一个合成器属性逃生舱 —— 静态几何通过 Reactor 渲染,活的值则直接改写。

自定义标签元素

大多数图表只需要基于字符串的标签 API(AxisLabel、LabelAccessor、DataLabel)。只有当纯文本不够时才去够 *View 扩展 —— 比如图标加文本的刻度、混合排版的多行标签,或把某个扇区的百分比渲染在扇区内部。

饼图扇区标签

LabelView 替换每个饼图扇区上内置的文本文本标签。委托收到该扇区的数据项以及一个描述其几何的 PieSliceLayout,并返回任意 Element:

// 百分比渲染在扇区内部。字符串标签访问器仍然传入,
// 以便屏幕阅读器描述该扇区。
PieChart(Data, d => d.Value, d => d.Name)
    .Title("Team Distribution")
    .Width(300).Height(300)
    .InnerRadius(50).PadAngle(0.02)
    .LabelView((d, layout) =>
        TextBlock($"{layout.Fraction:P0}")
            .FontSize(12).Bold().Foreground(Theme.AccentText))

在每个扇区内部渲染百分比的饼图

PieSliceLayout 暴露该扇区的 Index、Value、Fraction、CentroidX/CentroidY、StartAngle/EndAngle、InnerRadius/OuterRadius,以及解析出的调色板 Color,因此一个标签可以呼应扇区几何而无须重算它。

坐标轴刻度标签

XTickLabelView 和 YTickLabelView 把数字刻度标签替换成任意 Element。每个委托收到该刻度的定义域值:

// X 轴刻度:为每个刻度渲染月份名加一个小标题。
LineChart(Data, d => d.Month, d => d.Revenue)
    .Title("Revenue by Month")
    .SeriesName("Revenue")
    .Width(600).Height(220)
    .Stroke("#0078D4").StrokeWidth(2.5)
    .ShowGrid(true).ShowAxes(true)
    .XTickLabelView(t => VStack(2,
        TextBlock(Months[Math.Clamp((int)t - 1, 0, Months.Length - 1)])
            .FontSize(11).SemiBold(),
        TextBlock("month").FontSize(8).Opacity(0.6)))

带月份名坐标轴刻度的折线图

方法 用途
PieChartElement<T>.LabelView(Func<T, PieSliceLayout, Element>, Func<T, string>? name = null, bool interactive = false) 用任意 Element 替换内置扇区文本,锚定在扇区重心上
ChartElement<T>.XTickLabelView(Func<double, Element>, Func<double, string>? name = null, bool interactive = false) 替换 X 轴刻度标签,在刻度上水平居中
ChartElement<T>.YTickLabelView(Func<double, Element>, Func<double, string>? name = null, bool interactive = false) 替换 Y 轴刻度标签,右对齐到坐标轴边缘

默认情况下,你返回的元素以非交互方式渲染:图表会对整个已实现子树(而不只是外层包装器)强制施加 AccessibilityView.Raw,并清除每个内部控件的 IsTabStop,因此没有任何内部 peer 暴露给辅助技术,标签内部也不会有任何东西进入键盘 Tab 序。图表那套结构化无障碍描述(见下)因此始终是唯一真相来源。该元素也会自动锚定 —— 构造时你不需要已知尺寸,图表会在布局时重新定位。

两个可选参数对此做细化:

  • name 为这种情形提供一个可访问名称投影:你在没有字符串 LabelAccessor(饼图)/ DataLabel(折线/条形/面积图)的情况下使用了 *View 覆盖。对于饼图扇区,该投影喂给图表自己的扇区描述符,于是播报出的名字与可见标签一致,而不是退回到 Slice {n}。对于坐标轴刻度,它在已实现的刻度元素上设置 AutomationName(刻度没有逐刻度描述符)。有字符串 LabelAccessor/DataLabel 时优先用它;只有当视觉完全住在 *View 里时才去够 name。
  • interactive: true 是一个可选启用的逃生舱:它保留子树的 peer 与 tab stop,使你标签内的可聚焦子元素保持可达。一旦你设置了它,你就要为标签的无障碍负责 —— 图表不再隐藏它。在运行时切换 interactive 会重挂载标签,让隐藏/取消隐藏立即生效。

图表无障碍

图表开箱即完全可访问。加 .Title() 和 .SeriesName() 供屏幕阅读器识别,加 .Units() 做坐标轴注解,加 .Interactive() 开启键盘导航:

/// <summary>
/// Canonical accessible chart pattern — demonstrates all recommended accessibility
/// modifiers for both static and interactive charts. Follow this pattern to ensure
/// charts are fully accessible to screen readers, keyboard users, and users who
/// need forced-colors or reduced-motion.
/// </summary>
class AccessibleChartDemo : Component
{
    private static readonly SalesPoint[] Data =
    [
        new(1, 120), new(2, 180), new(3, 150),
        new(4, 220), new(5, 310), new(6, 280)
    ];

    public override Element Render()
    {
        return VStack(12,
            SubHeading("Accessible Chart"),

            // 静态可访问图表:Title + SeriesName + Units
            LineChart(Data, d => d.Month, d => d.Revenue)
                .Title("Monthly Revenue 2024")
                .SeriesName("Revenue")
                .Units("months", "USD")
                .AxisLabel(ChartAxisType.X, "Month")
                .AxisLabel(ChartAxisType.Y, "Revenue (USD)")
                .Width(600).Height(250)
                .Stroke("#0078D4").StrokeWidth(2.5)
                .ShowGrid(true).ShowAxes(true),

            // 交互式可访问图表:加上键盘导航与点调用
            BarChart(Data, d => d.Month, d => d.Revenue)
                .Title("Monthly Revenue — Interactive")
                .SeriesName("Revenue")
                .Units("months", "USD")
                .Interactive()
                .Width(600).Height(250)
                .Fill("#50C878")
                .ShowGrid(true).ShowAxes(true)
        ).Padding(24);
    }
}

可访问图表

无障碍修饰符

方法 用途
.Title(str) 可见标题与可访问名称
.Description(str) 覆盖自动生成的摘要
.SeriesName(str) 为数据系列命名
.Units(x, y) 坐标轴单位注解(如 "months"、"USD")
.AxisLabel(axis, str) 显式坐标轴标签
.Interactive() 启用键盘导航与虚拟焦点
.OnPointInvoke(handler) 在某个点上按下 Enter/Space 时的回调
.AlternateView(element) 在图表与数据表之间切换(T 键)
.Palette(palette) 经筛选的色盲安全调色板
.SeriesColors(colors) 自定义系列颜色(经扫描器校验)
.SetColors(colors) 自定义饼图扇区颜色(经扫描器校验;是 .SeriesColors 在饼图上的对应物)
.RawColors(colors) 原始系列颜色 —— 逃生舱,不做校验(Tier 4)
.ChartBackground(color) 声明所渲染的背景,使调色板对比度(A11Y_CHART_011)针对这唯一的实际背景做检查(warning 级),而不是针对固定的浅色/深色背景之一(info 级)
.SeriesShapes(shapes) 用于双重编码的标记形状
.SeriesDashes(dashes) 用于双重编码的虚线样式

屏幕阅读器会播报图表类型、系列数量、数据范围和各个数据点的值。键盘用户用方向键导航,用 Enter 调用数据点,用 T 切换到备用的数据表视图。框架完整的 a11y 故事在 accessibility;图表特有的契约是:颜色永远不是唯一的编码 —— 任何发给强制颜色用户的多系列图表,都要把 .Palette(...) 与 .SeriesShapes(...) 或 .SeriesDashes(...) 组合起来。

底层绘制

对于自定义可视化,ReactorD3 提供形状生成器和一套 Canvas DSL。导入 using static Microsoft.UI.Reactor.Charting.D3Charts; 可获得:

  • D3Canvas(w, h, children) —— 创建一个绘制表面
  • D3Rect、D3Circle、D3Line、D3Path —— 基元形状
  • Text、TextRight、TextCenter —— 定位文本
  • D3LinePath<T>、D3AreaPath<T>、D3ArcPath —— 生成器辅助
  • D3Axes、D3Grid、D3Legend —— 坐标轴/图例组合件
  • Brush(color)、Palette —— 画笔与默认分类调色板

这三个是位置型的:Text(x, y, text, …) 接受画布坐标,与核心的 TextBlock(...) 工厂方法无关。Reactor 没有核心 Text(...) 元素工厂 —— 别处存在的那些 Text(...) 成员是 DataGrid 的单元格渲染器与编辑器辅助器,它们返回 Func<object, Element>,而不是 Element。

比例尺是类型,不是 D3Charts 的成员 —— 它们住在更深一层命名空间里。加 using Microsoft.UI.Reactor.Charting.D3; 才能碰到它们。

比例尺类型

每个比例尺都暴露 .Map(value) 把定义域值投影到值域空间 —— 比例尺是对象而非委托,所以 scale(v) 编译不过。用 new LinearScale(domain, range) 构造一个,或用 .SetDomain(...) / .SetRange(...) 流畅地配置。

比例尺 用途
LinearScale 连续数值映射,带 .Nice() 和 .Ticks()
BandScale<T> 分类型映射,带带宽(条形图)
LogScale 面向指数数据的对数映射
PowScale 幂/平方根映射
OrdinalScale<T> 离散到离散的映射

注意: 在 Render() 里重建数据数组,后果自负。图表在快路径上按引用比较传入的数据 —— 每次渲染一个新数组,意味着图表要重新推导比例尺、重跑饼图布局、并每帧重新分配 WinUI 形状池,即使什么都没变化。症状是:一个无关状态更新时图表闪烁。修法与 Reactor 到处在用的形状一样:用 UseMemo(() => …, deps) 把数据包起来,键取真正会变的那个东西。这个模式在 PieChart 上最明显 —— 每次渲染都 new[] { … } 会让每个扇区重挂载,对那些根本没动的扇区也触发 .Transition() 的进入/退出,于是"每往一个无关的 TextBox 里敲一个键,图表就自己重画一遍"。

模式

来自滴答数据源的实时更新图表

流式图表 —— 一个价格推送、一个传感器读数 —— 驱动一个滑动窗口的数据点。把窗口放在 UseReducer 里(每次滴答从前一个窗口推导出下一个),滴答时追加,一旦 Count 超过窗口大小就丢掉头部。UseEffect 接受同步的 Action/Func<Action>,绝不接受 async lambda,所以从副作用里启动那个泵,并从返回的清理函数里取消它:

record Sample(DateTime Time, double Value);

class LiveChartDemo : Component
{
    public override Element Render()
    {
        var (samples, updateSamples) = UseReducer<IReadOnlyList<Sample>>(Array.Empty<Sample>());

        // UseEffect 接受同步的 Action/Func<Action> —— 绝不接受 async lambda。
        // 从副作用里启动泵,从返回的清理函数里取消它。
        UseEffect(() =>
        {
            var cts = new CancellationTokenSource();
            _ = PumpAsync(cts.Token);
            return () => { cts.Cancel(); };
        }, Array.Empty<object>());

        return VStack(12,
            SubHeading("Live feed"),
            LineChart(samples, s => s.Time.Ticks, s => s.Value)
                .Title("Live feed")
                .SeriesName("Value")
                .Width(600).Height(220)
                .Stroke("#0078D4")
        ).Padding(24);

        async Task PumpAsync(CancellationToken token)
        {
            using var timer = new PeriodicTimer(TimeSpan.FromMilliseconds(200));
            try
            {
                while (await timer.WaitForNextTickAsync(token))
                {
                    updateSamples(prev =>
                    {
                        var next = prev.Append(new Sample(DateTime.Now, Random.Shared.Next(0, 100))).ToList();
                        return next.Count > 60 ? next.Skip(next.Count - 60).ToList() : next;
                    });
                }
            }
            catch (OperationCanceledException)
            {
                // 卸载时的预期行为。
            }
        }
    }
}

图表在每次滴答时重画。对于低于 100ms 的节奏,下探到 OnReady 直接改写 Canvas —— 协调器很快,但不是免费的。定时器的清理模式见 effects-scheduling。

切换图表类型而不丢数据绑定

同一份数据既能喂折线图、条形图,也能喂面积图 —— 让用户挑形状。把 ComboBox 选中的索引存在状态里,并据此切换工厂调用:

class ChartSwitchDemo : Component
{
    private static readonly SalesPoint[] Data =
    [
        new(1, 120), new(2, 180), new(3, 150), new(4, 220), new(5, 310), new(6, 280)
    ];

    public override Element Render()
    {
        // ComboBox 上报的是选中的 *索引*,所以持有一个 int 并在其上分支。
        var (kind, setKind) = UseState(0);
        var kinds = new[] { "line", "bar", "area" };

        // 每个工厂方法都返回 ChartElement<T>,因此这个 switch 有共同的
        // 类型,下面的修饰符链是共享的。
        ChartElement<SalesPoint> chart = kind switch
        {
            0 => LineChart(Data, d => d.Month, d => d.Revenue),
            1 => BarChart(Data, d => d.Month, d => d.Revenue),
            _ => AreaChart(Data, d => d.Month, d => d.Revenue),
        };

        return VStack(8,
            SubHeading("Switch chart type"),
            ComboBox(kinds, kind, setKind),
            chart
                .Title("Revenue")
                .SeriesName("Revenue")
                .Width(600).Height(250)
                .Stroke("#0078D4")
        ).Padding(24);
    }
}

因为每个工厂方法都返回一个 ChartElement<T>,修饰符链是完全相同的 —— 唯一有分支的是构造函数。

为自定义形状下探到 D3

当高层表面不合身时(热力图、平行坐标、蜂群图),直接渲染 D3Canvas 并组合 D3 形状生成器。LinearScale / BandScale 类型与高层图表内部使用的是同一批,因此行为一致 —— .Nice()、.Ticks() 和定义域/值域设置器的工作方式完全相同。D3Axes 和 D3Grid 返回 Element[],所以用 .. 把它们展开进画布子元素:

class D3CustomDemo : Component
{
    public override Element Render()
    {
        const double w = 600, h = 240;
        const double left = 50, top = 20, right = 20, bottom = 40;
        double plotW = w - left - right, plotH = h - top - bottom;

        var data = Enumerable.Range(0, 40)
            .Select(i => (x: (double)i, y: 40 + 30 * Math.Sin(i / 4.0) + i))
            .ToArray();

        var (yMin, yMax) = D3Extent.Extent(data.Select(d => d.y));

        // 比例尺是普通对象:Set* 做流畅改写,Map 做值投影。
        var xs = new LinearScale([0, 39], [left, left + plotW]);
        var ys = new LinearScale([yMax, yMin], [top, top + plotH]).Nice();

        var line = D3Charts.Brush("#0078D4");

        return VStack(12,
            SubHeading("Custom D3 canvas"),
            D3Charts.D3Canvas(w, h,
                [.. D3Charts.D3Grid(ys, left, plotW),
                 .. D3Charts.D3Axes(xs, ys, left, top, plotW, plotH),
                 D3Charts.D3LinePath(data, x: d => xs.Map(d.x), y: d => ys.Map(d.y),
                     stroke: line, strokeWidth: 2),
                 .. data.Select(d => (Element)(D3Charts.D3Circle(xs.Map(d.x), ys.Map(d.y), 3)
                     with { Fill = line }))])
        ).Padding(24);
    }
}

这与 Observable Plot 用的是同一套组合策略 —— 几何基元置于比例尺之上 —— 只不过那些基元渲染为 WinUI 形状,而不是 SVG。要做热力图,把 D3LinePath 换成嵌套的 D3Rect;要做平行坐标,为每个轴重复调用一次 line-path。

常见错误

在 Render 里构造数据数组

// 不要这样:
public override Element Render()
{
    var data = new SalesPoint[] { new(1, 120), new(2, 180), /* … */ };
    return LineChart(data, d => d.Month, d => d.Revenue);
}
class DynamicDataDemo : Component
{
    private static readonly List<SalesPoint> InitialPoints =
        Enumerable.Range(1, 8)
            .Select(i => new SalesPoint(i, Random.Shared.Next(50, 500)))
            .ToList();

    public override Element Render()
    {
        var (points, updatePoints) = UseReducer(InitialPoints);

        return VStack(12,
            SubHeading("Dynamic Data"),
            Button("Randomize", () => updatePoints(_ =>
                Enumerable.Range(1, 8)
                    .Select(i => new SalesPoint(i, Random.Shared.Next(50, 500)))
                    .ToList())),
            BarChart<SalesPoint>(points, d => d.Month, d => d.Revenue)
                .Title("Dynamic Revenue Data")
                .SeriesName("Revenue")
                .Units("months", "USD")
                .Width(600).Height(250)
                .Fill("#E74C3C")
                .ShowGrid(true).ShowAxes(true)
        ).Padding(24);
    }
}

每次渲染都分配一个新数组,于是图表的引用相等检查失败,比例尺重新推导,形状池重置 —— 尽管可见上什么都没变。把静态数据提升为 static readonly 字段,或用 UseMemo(() => BuildData(...), deps) 把动态数据包起来。

把颜色当作唯一的系列编码

// 不要这样:
LineChart(serverA, ...).Stroke("red"),
LineChart(serverB, ...).Stroke("green"),
LineChart(serverC, ...).Stroke("blue")

在强制颜色模式下(Windows 高对比度),每一条描边都坍缩成当前的强调色,用户分不清这几个系列。请把颜色与 .SeriesShapes(MarkerShape.Circle, MarkerShape.Square, MarkerShape.Triangle) 或 .SeriesDashes(DashStyle.Solid, DashStyle.Dash4_2, DashStyle.Dash2_2) 配对,这样即便没有颜色,系列依然可辨。与 WCAG 2.2 SC 1.4.1 里对图表的原则一致。

用手逐个动画 D3 形状

// 不要这样:
D3Circle(xs.Map(d.X), ys.Map(d.Y), 3)
    .Set(c =>
    {
        var anim = c.Compositor.CreateScalarKeyFrameAnimation();
        anim.InsertKeyFrame(0f, 0.0f);
        anim.InsertKeyFrame(1f, 1.0f);
        anim.Target = "Opacity";
        c.StartAnimation(anim);
    })

内联的合成动画重复了 .OpacityTransition() 和 .Transition(Transition.Fade) 已经做的事,而且绕过了 Reactor 在动画管线层面所尊重的"减少动态效果"偏好。请在 D3 形状上使用 Reactor 的动画修饰符 —— 它们的工作方式与用在 Border 或 TextBlock 上时完全一致。

提示

从高层 DSL 开始。 LineChart、BarChart、AreaChart 和 PieChart 覆盖了大多数仪表盘需求,无需触碰比例尺或生成器。

为可读性启用 .ShowGrid(true)。 网格线让从图表上读数值容易得多,折线图和面积图尤其如此。

把数据集控制在 1000 个点以内。 每个数据点都在 Canvas 上创建 WinUI 形状。更大的数据集请先聚合或采样再绘图。

实时数据只需改状态。 图表的差异比对很高效 —— 更新状态会触发协调器只打补丁变化的部分。需要 60fps 逃生舱时,用 OnReady 直接访问底层 Canvas。

比例型数据用环形图(InnerRadius > 0)。 中心那块空间很适合放一个总计或标签。

下一步

  • 动画 —— 上一篇:过渡、关键帧、交互状态
  • 高级模式 —— 下一篇:错误边界、记忆化与性能调优
  • 集合 —— 从虚拟化列表与可观察集合绑定图表数据
  • 副作用与生命周期 —— 用 UseEffect 异步加载图表数据
  • 样式与主题 —— 用主题令牌作为图表颜色,以适配深色模式
  • 无障碍 —— 屏幕阅读器、键盘导航与强制颜色指南