用途:在构建 Vizro 仪表板时,帮助选择图表类型、应用 Plotly Express 约定、处理颜色规则以及构建 KPI 卡片。
图表选择:比较类别用条形图(优先水平);时间趋势用折线图(12 个点以上);简单部分对整体用饼图/环形图(仅限 2–5 个切片);复杂部分对整体用堆叠条形图;分布用直方图或箱线图;相关性用散点图。禁止使用:3D 图表、6 个及以上切片的饼图、双 Y 轴、不从零开始的条形图。
Plotly 约定:Plotly Express 不进行聚合,需在 app.py 或自定义图表函数中预聚合。条形图按值排序(从大到小),除非基于时间;始终从零开始。折线图需预聚合并按 x 升序排序。当刻度自解释时移除轴标题,移除图例标题(仅保留项目)。
颜色规则:Plotly 图表与 KPI 卡片不要指定颜色——不使用 marker_color、十六进制色码、color_discrete_map 或 color_discrete_sequence。即使类别具有表面语义含义也适用。仅在用户明确要求时覆盖。AG Grid 不会自动采用 Vizro 模板颜色,需使用 from vizro.themes import palettes, colors 进行单元格样式设置。
自定义图表(@capture("graph")):在需要聚合/排序、调用 update_layout()/update_traces()、参考线、参数驱动逻辑、双轴、多轨迹 go.Figure()、共享图例控制时使用。实践中大多数条形图和折线图需要 @capture("graph") 函数在内部聚合数据。
KPI 卡片:使用 Figure 模型中 vizro.figures 的内置 kpi_card / kpi_card_reference。切勿将 KPI 卡片重建为自定义图表,除非内置严格无法实现(如动态文本)。标题放在 figure 参数中,而非组件上。
深入参考:需要扩展图表类型决策树、Plotly Express 格式化约定、调色板/颜色名称与用例、无障碍规则或详细 @capture("graph") 指南时,加载 chart-best-practices.md。
限制:资料未提供安装命令、价格或平台信息。