matlab-build-chart

MATLAB 图表构建器

创建、自定义并交互使用 MATLAB 图表和绘图——可用于独立图窗、Live Scripts 或 uifigure 应用。

何时使用此技能

在以下情况下使用此技能：

• 在任何上下文中绘制数据（折线图、散点图、条形图、直方图、热图、曲面图、极坐标图、地理图、体积图）
• 配置坐标轴（标签、范围、刻度、图例、字体、导出）
• 添加注释（xline、yline、xregion、text）
• 添加或自定义数据提示
• 创建交互式绘图（点击、悬停、拖动回调）
• 为图表添加动画或流式数据
• 使用 tiledlayout/nexttile 排列多个坐标轴
• 优化图表渲染性能
• 为出版物或报告导出图窗
• 用户未指定图表类型，只说“帮我把这些数据可视化”

何时不使用此技能

• 构建完整应用（使用 matlab-build-app——它会在图表相关子步骤中调用此技能）
• 应用深色模式、品牌颜色或自定义颜色主题（使用 matlab-apply-theme）
• 使用 Simulink 示波器或 Simscape 绘图
• 通过拖放式 GUI 创建 App Designer 图表

工作流

User request arrives
        |
        +-- FAST PATH (most requests)
        |   Chart type named OR unambiguous single-axes plot
        |   AND no interactivity / animation / multi-panel / performance concern
        |       |
        |       v
        |   Infer rendering context (default: standalone figure)
        |   Read relevant references --> Build directly
        |
        +-- PLAN PATH (complex or ambiguous)
                |
                +-- Ambiguous intent (no chart type named, unclear data question)
                |       --> Identify visualization intent (see Intent Taxonomy)
                |
                +-- Rendering context unclear AND it matters
                |       --> Ask: standalone figure, Live Script, or uifigure app?
                |
                v
            Present inline plan for approval
                |
                v
            User confirms --> Read references --> Build

快速路径触发条件（直接构建，无需计划）

以下条件必须全部满足：

• 已指定图表类型，或意图明确对应某一种类型
• 只有一个坐标轴（无平铺/多面板布局）
• 无自定义交互（未指定用户回调）
• 无动画或流式数据
• 无明确的性能限制
• 渲染上下文明确，或默认使用独立图窗

计划路径触发条件（先提供计划）

出现以下任一情况时，走计划路径：

• 多面板/平铺图窗
• 自定义交互（点击、悬停、拖动回调）
• 动画或流式数据
• 对性能敏感（大型数据集、实时更新）
• 需要协调配色方案/主题的品牌化或设计型图窗
• “帮我把这些数据可视化”的意图不明确——类型或意图不清楚
• 在同一图窗中包含多种可视化意图

渲染上下文

以下三种上下文决定适用哪组限制：

上下文	限制	判断依据
独立图窗	仅通用规则	默认；请求中提到 figure/axes
Live Script	仅通用规则	用户提到 Live Script、.mlx、纯文本 Live Code
uifigure 应用	通用规则 + uifigure 规则	用户提到 uifigure；作为应用构建器的子步骤调用

如果未说明且无法推断上下文，则假设使用独立图窗。只有在上下文区别会影响结果时才询问（例如，热图的父级对象因上下文而异）。

可视化意图分类

仅当用户未指定具体图表类型或函数时才启用。如果用户说“散点图”或“热图”，则跳过意图选择并直接构建。

表达意图

意图	数据问题	推荐函数
比较	不同项目的数值如何比较？	bar、barh、bar3、bar3h、pareto、stem、stairs、loglog、semilogx、semilogy
趋势/时间序列	数值随时间如何变化？	plot、area、stackedplot、stairs、stem、fplot、fplot3
分布	数据如何分布？	histogram、histogram2、boxchart、violinplot、raincloudplot、swarmchart、swarmchart3、scatterhistogram、binscatter、polarhistogram
关系	变量之间有什么关系？	scatter、scatter3、bubblechart、bubblechart3、plotmatrix、parallelplot、binscatter、spy、fimplicit
构成	整体由哪些部分组成？	piechart、donutchart、堆叠 bar、堆叠 area、wordcloud、bubblecloud

数据领域意图

意图	触发条件	推荐函数
地理空间	地理坐标	geoplot、geoscatter、geobubble、geodensityplot
方向 / 极坐标	角度、周期性、罗盘数据	polarplot、polarscatter、polarhistogram、polarbubblechart、compassplot、fpolarplot
曲面与标量场	z = f(x,y)、网格、等高线	surf、surfc、surfl、mesh、meshc、meshz、ribbon、pcolor、contour、contourf、contour3、fcontour、fsurf、fmesh、fimplicit3、waterfall
矢量场与流动	方向矢量数据	quiver、quiver3、feather、streamline、streamslice、streamribbon、streamtube、streamparticles、coneplot
体可视化	3D 网格体数据	slice、contourslice、coneplot、streamslice、等值面 / 等值帽工作流
图像与矩阵	显示矩阵 / 网格	image、imagesc、heatmap、pcolor（平面着色）、spy

分类规则

• waterfall 陷阱： MATLAB 的 waterfall 是 3D 曲面图，不是金融累计图表。对于“累计到总计”，使用带隐藏基准序列的 bar 构建。
• f* 变体遵循对应数据函数的意图：fplot -> 趋势，fsurf/fmesh/fcontour -> 曲面，fimplicit -> 关系，fpolarplot -> 方向。
• 动画是跨领域的，不是一种意图。animatedline、comet、comet3 可为任何图表类型添加运动效果。请参阅 references/animation.md。
• 多意图函数： 根据用户的数据问题分类，而非图库分组。例如，相关矩阵的热力图 -> 关系；计数的热力图 -> 比较。
• 按表达意图分类，而不是按 MATLAB 文档分组。无论文档将 piechart/donutchart 归入何处，它们都属于构成类。

内联计划模板

启用计划路径时，请提交审批：

**Chart Plan: [description]**

**Context:** [Standalone figure / Live Script / uifigure app]
**Intent:** [name] -> [chosen function(s)]

**Structure:**
- [Layout description]
- [Key visual elements, annotations, interactions]

**Key decisions:**
- [Performance strategy, if applicable]  [src: references/performance.md SS]
- [Interaction model, if applicable]  [src: references/interactive-plots.md SS]
- [uifigure constraints that apply, if context = uifigure]

**References to use:**
| Reference | Role | Provenance |
|-----------|------|------------|
| `references/file.md` | [what it provides] | [src: references/file.md SS] |

Shall I proceed?

除非 (a) 用户明确要求保留规范，或 (b) chart-builder 正在作为应用构建的子步骤运行，且已有计划产物，否则不要将计划写入文件。

关键规则

通用（所有上下文）

• 必须将坐标区作为所有绘图函数的第一个参数：plot(ax, x, y)，而不是 plot(x, y)
• 必须原地更新数据（p.XData = newX）——绝不要在循环中重新绘图
• 动画必须使用 drawnow limitrate——绝不要在紧密循环中单独使用 drawnow
• 多个坐标区优先使用 tiledlayout/nexttile，而不是 subplot()
• 优先使用 exportgraphics() 进行出版级导出

uifigure 应用中的其他限制

• 必须使用 uiaxes——绝不要使用普通 axes
• 必须使用 exportgraphics() 或 exportapp()——不支持 saveas/print
• 绝不要使用 subplot()——uifigure 不支持
• 绝不要使用 annotation()——请使用 text()、xline()、yline()、xregion()、yregion()
• 绝不要使用 ginput()——请在绘图对象上使用 ButtonDownFcn
• 绝不要依赖 gcf/gca——uiaxes 默认 HandleVisibility = 'off'

快速开始

独立图窗

fig = figure;
ax = axes(fig);

t = 0:0.01:2*pi;
plot(ax, t, sin(t), 'LineWidth', 1.5);
hold(ax, 'on');
plot(ax, t, cos(t), '--', 'LineWidth', 1.5);
hold(ax, 'off');

title(ax, 'Sine and Cosine');
xlabel(ax, 'Time (s)');
ylabel(ax, 'Amplitude');
legend(ax, 'sin', 'cos');
grid(ax, 'on');
exportgraphics(ax, 'plot.png', 'Resolution', 300);

在 uifigure 应用中

fig = uifigure('Name', 'Chart Demo');
gl = uigridlayout(fig, [1 1]);
ax = uiaxes(gl);

plot(ax, t, sin(t), 'LineWidth', 1.5);
% Same API from here — only axes creation differs

有了 ax 后，无论上下文如何，所有绘图调用（plot、scatter、bar、xline、hold、legend、colororder 等）都相同。

实现检查清单

图形

• 所有绘图调用都将 ax 作为第一个参数
• 添加多个序列前使用 hold(ax, 'on')
• 已配置坐标区标签、标题和网格
• 注释使用 xline/yline/text（不用 annotation()——uifigure 要求）
• 交互回调在绘图对象上使用 ButtonDownFcn（不在坐标区上——uifigure 要求）
• 动画使用 drawnow limitrate 并预先设置坐标轴范围
• 导出使用 exportgraphics()（uifigure 中必需；在所有场景中优先）
• 多个坐标区使用 tiledlayout/nexttile（uifigure 中必需；在所有场景中优先）

故障排除

标记为 (仅限 uifigure) 的问题仅适用于在 uifigure 应用中绘图。

问题	原因	修复方法
动画缓慢／卡顿	在循环中使用 plot() 或直接使用 drawnow	原地更新数据，并使用 drawnow limitrate
重新绘图后图表消失	默认值 NextPlot = 'replacechildren'	使用 hold(ax, 'on') 或原地更新数据
gcf/gca 返回错误的句柄 (仅限 uifigure)	uiaxes 的 HandleVisibility = 'off'	始终显式传入 ax
annotation() 报错 (仅限 uifigure)	uifigure 不支持	使用 text()、xline()、yline()
ginput() 报错 (仅限 uifigure)	uifigure 不支持	在绘图对象上使用 ButtonDownFcn
坐标区上的点击回调未触发 (仅限 uifigure)	uiaxes 上的 ButtonDownFcn 不可靠	在绘图对象上设置 ButtonDownFcn
uiaxes 中的热力图失败 (仅限 uifigure)	热力图需要 figure／panel 父对象	使用 heatmap(fig, ...) 或 heatmap(panel, ...)
saveas 失败 (仅限 uifigure)	uifigure 不支持	使用 exportgraphics(ax, file)
subplot() 报错 (仅限 uifigure)	uifigure 不支持	使用 tiledlayout/nexttile 或 uigridlayout

参考资料

主题	文件	覆盖内容	服务的意图
绘图类型	references/plot-types.md	折线图、散点图、条形图、直方图、热力图、曲面图	比较、趋势、分布、关系、曲面（部分）
坐标区配置	references/axes-config.md	uiaxes 设置、标签、范围、刻度、字体、图例、导出	所有意图
注释	references/annotations.md	xline、yline、xregion、text、patch	所有意图（叠加）
数据提示	references/data-tips.md	DataTipTemplate、自定义行、程序化提示	所有意图（叠加）
交互式绘图	references/interactive-plots.md	ButtonDownFcn、鼠标回调、拖动、HitTest、工具栏	规划路径：交互性
图表调色板	references/chart-palettes.md	colororder、命名调色板、SeriesIndex、与 colormap 的区别	所有意图（样式）
动画	references/animation.md	原地更新、animatedline、流式处理、性能	规划路径：动画
多个坐标区	references/multiple-axes.md	tiledlayout、nexttile、linkaxes、外围平铺	规划路径：多面板
性能	references/performance.md	延迟加载、批量更新、节流、parfeval、启动	规划路径：性能

参考资料缺口（需要后续编写）

这些意图没有专门的参考文件。请使用 MATLAB 内置 API 知识：

• 构图 — piechart、donutchart、堆叠条形图／面积图、wordcloud、bubblecloud
• 地理空间 — geoplot、geoscatter、geobubble、geodensityplot
• 方向／极坐标 — polarplot、polarscatter、polarhistogram、polarbubblechart、compassplot、fpolarplot
• 矢量场与流场 — quiver、quiver3、feather、streamline、streamslice、streamribbon、streamtube、streamparticles、coneplot
• 体积可视化 — slice、contourslice、coneplot、等值面／等值帽工作流
• 图像与矩阵（部分）— 未涵盖 image、imagesc；绘图类型中涵盖 heatmap
• 曲面（部分）— 仅涵盖 surf；mesh、contour、ribbon、pcolor 待补充

外部技能（已调用，未阅读）

• matlab-apply-theme — 图表需要暗色模式、品牌颜色或自定义调色板时使用

---

版权所有 2026 The MathWorks, Inc.

---