pbi-report-design

Power BI 报表设计

修改任何报表时都使用 pbir。 pbir-format 技能仅提供只读架构上下文。 如果 CLI 不可用或缺少所需操作，请停止并报告缺口。

Power BI 报表设计的最佳实践和指南。请严格遵循这些指南，避免生成通用、格式糟糕的报表（“Power BI 废稿”）。

在遵守数据可视化规则和指南的同时勇于创新、突破边界。在 Power BI 的限制内，优先追求简洁和实效，而非美观和装饰。让报表、页面和可视化内容聚焦于回答具体问题、尽量降低认知负担，而不是看起来“漂亮又令人印象深刻”。

如果用户请求与这些指南相矛盾，请提出异议并说明更好的替代方案。目标是告知用户哪些选项能够带来更好的结果。

设计标识（布局前确定）

进行任何布局工作之前，先确定报表的设计标识，让后续每项选择都有据可依：

1. 选择一种基调……确定明确的墨色预算（restrained、corporate、editorial 或 technical），以此固定强调色数量、饱和度、网格线粗细和注释的醒目程度。
2. 选择一个标志性元素（最多两个）……选定一个在每个页面上以相同方式重复出现的元素（页眉色带、单一强调色规则、固定导航栏、KPI 轮廓、标注样式、目标线规范），让整份报表呈现为一个统一的作品。
3. 根据页面要回答的问题，为每页选择一种结构（summary、monitoring、exploration、comparison、narrative）。

记录一次基调和标志性元素，就能让“使用柔和的颜色”成为可贯彻的决策。基调预算和标志性元素目录请参阅 references/design-identity.md，页面结构选择请参阅 references/page-shapes.md。使用 modifying-theme-json 技能将设计标识序列化到主题中，而非写入单个可视化的覆盖设置。

核心规则

1. 3-30-300 规则： 最重要、最简要的信息应放在左上角（KPI、卡片等），最不重要、最详细的信息应放在右下角。
2. 标题： 所有报表页面都应有标题，可使用 textBox visualType，也可将标题置于添加到报表页面画布的背景图中。
3. 视觉对象的位置、对齐和间距： 所有视觉对象之间的间距，以及视觉对象与页面边缘（边距）之间的间距都必须相等。如果视觉对象未对齐或间距不一致，请调整以确保对齐且间距相等。
4. 主题： 报表应使用不同于默认 Power BI 主题的主题；建议使用 sqlbi 主题（请参阅 modifying-theme-json 技能，了解如何应用模板）。推荐使用主题，因为主题为所有图表提供一套默认样式，有助于遵循良好的设计实践以及品牌或样式指南。
5. 语义模型： Power BI 报表很复杂，依赖底层语义模型（位于 .SemanticModel 文件夹中的模型称为“厚报表”，Power BI/Fabric 中发布的模型称为“薄报表”）。Power BI 报表的许多功能都来自语义模型设计或 DAX 代码。
6. 报表扩展或薄报表度量值： 可以在 Power BI 报表中创建计算逻辑，称为“薄报表度量值”或“视觉计算”。应谨慎使用，且仅用于“报表专用”场景。
7. 视觉对象字段： 所有数据视觉对象都应绑定字段，并且所有绑定字段都必须确实存在于模型中；没有理由创建未绑定任何字段的视觉对象。
8. 图表选择： 根据不同场景，明智地选择要使用的视觉对象。视觉化表达能力对这项技能至关重要。
9. 颜色的使用： 颜色和格式设置必须体现已确定的品牌标识（选定的基调和标志性元素），而不是针对每个视觉对象单独选择。颜色应来自主题（themedataColor），而非内联十六进制值，这样品牌标识才能持续应用，并能在切换主题后保持一致。颜色应柔和、低饱和；除非用于表达相应含义，否则应避免使用隐含意义的颜色（例如红色表示不好、绿色表示好）。请考虑色盲情况，并使用易于识别的配色方案（例如，蓝色搭配红色，而非绿色搭配红色）。
10. 前注意属性： 样式和颜色应引导注意力，而不是用来装饰图表。视觉对象的格式设置应有明确目的，而不应只为美观。尽可能将样式存储在主题中，而非单独配置视觉对象。
11. 字体： 优先使用 Segoe UI 和 Segoe UI Semibold。不要使用自定义字体，因为无法保证用户的计算机支持这些字体。请根据视觉对象和页面的大小，评估字体是否足够大、易于阅读。
12. 页面意图： 根据页面要回答的问题，将每个页面明确归入一种形态（请参阅 references/page-shapes.md）。一个页面若试图回答两个问题，就应拆分为两个页面。

页面布局指南

修改前先检查页面大小

添加或重新定位视觉对象前，务必查询实际页面尺寸。 不要假设页面尺寸为 1280x720 或 1920x1080——模板和现有报表的尺寸各不相同。对象模型会验证视觉对象是否位于页面边界内，因此在不了解页面尺寸的情况下设置位置或大小会导致错误。请检查页面的 page.json 文件中的 width 和 height 属性，或使用对象模型（page.width、page.height）确认尺寸。通过对象模型调整视觉对象大小时，请先设置 width/height，再设置 x/y，以避免出现超出边界的中间状态。

标准页面尺寸

• 宽度： 1280px（默认）
• 高度： 720px（16:9 宽高比）
• 替代尺寸：1920x1080，适用于高分辨率显示器

视觉间距

• 视觉元素之间的最小间距： 16px
• 边缘留白： 距离页面边缘 24-32px
• 对齐一致： 使用基于网格的定位
• 间距必须相等： 所有相邻视觉元素之间的水平和垂直间距都必须相同。所有页面边缘留白也必须相同。根据（留白、间距、页面宽度、页面高度）通过算术计算位置，以确保对齐。如果视觉元素未对齐或间距不等，请立即修正——这是报告中最明显的质量指标之一。

细节渐进

按照“细节渐进”原则安排内容：

+------------------+------------------+
|   KPIs/Cards     |   KPIs/Cards     |  <- Top: High-level, important
|   (Summary)      |   (Summary)      |
+------------------+------------------+
|                                     |
|   Charts/Trends                     |  <- Middle: Context, trends
|   (Analysis)                        |
|                                     |
+------------------+------------------+
|                                     |
|   Tables/Details                    |  <- Bottom: Detailed data
|   (Drill-down)                      |
|                                     |
+------------------+------------------+

视觉元素数量指南

• 每页最多视觉元素： 12-15 个（会影响性能）
• KPI/卡片最多数量： 顶部 4-6 个
• 切片器最多数量： 每页 3 个（改用筛选器窗格）

页面标题

每个页面都应有标题。通过 pbir 创建标题：

pbir add title "Report.Report/Page.Page" "Page Title" --width 500

标题位置：

• 左上角，位于页面留白范围内
• 高度应足以容纳所选字体，避免裁切
• 宽度：400-600px（或页面宽度减去两侧留白）

主题指南

始终先检查主题

修改视觉元素格式之前：

1. 检查主题通配符：visualStyles["*"]["*"]
2. 检查视觉类型覆盖项：visualStyles.lineChart["*"]
3. 仅在确实是个别情况时才在 visual.json 中覆盖

何时修改主题，何时修改视觉元素

• 需要更改某一类型的所有视觉元素 -> 主题
• 制定设计标准 -> 主题
• 单个视觉元素例外于主题规则 -> 视觉元素
• 特定内容的高亮（一个标注、一个参考线）-> 视觉元素

主题颜色用法

优先使用主题颜色，而非十六进制代码：

// Good - uses theme color
"expr": {"ThemeDataColor": {"ColorId": 1, "Percent": 0}}

// Avoid in visuals - use only in extension measures
"expr": {"Literal": {"Value": "'#118DFF'"}}

语义颜色（由扩展度量值返回）：

• "good" - 正值（绿色）
• "bad" - 负值（红色）
• "neutral" - 中性/未变（灰色/黄色）
• "minColor" - 渐变最小值
• "maxColor" - 渐变最大值

无障碍（WCAG 2.1）

替代文本

所有视觉元素都应包含描述性替代文本：

"visualContainerObjects": {
  "general": [{
    "properties": {
      "altText": {
        "expr": {"Literal": {"Value": "'Line chart showing monthly sales trend from January to December 2024'"}}
      }
    }
  }]
}

颜色对比度

• 背景上的文本：对比度至少为 4.5:1
• 大号文本（18pt+）：对比度至少为 3:1
• 不要仅依靠颜色传达含义

字体大小

• 最低可读字号： 12pt
• 图表推荐字号： 14pt
• 标题： 16-24pt
• KPI 值： 24-48pt

阴影与动效

• 尽量减少投影（可能引发前庭不适）
• 尽可能避免动画
• 在主题通配符中使用 dropShadow.show: false

视觉元素最佳实践

卡片和 KPI

单独一个数字没有意义。每个 KPI 都必须回答“这是好还是坏？”（目标 + 差距）以及“情况是在变好还是变差？”（趋势）。关键规则：

• 放在页面顶部或左侧，每页最多 5 个
• 存在目标时，优先使用 kpi 视觉类型，而非 card——它内置了指示器、目标和趋势线数据角色
• 始终包含目标和差距（绝对值 + 百分比）。如果不存在目标度量值，请与用户讨论：建议向语义模型添加上一年度度量值（使用 Tabular Editor CLI 或 tmdl 技能），或在必要时创建扩展度量值。常见目标包括：上一年度（CALCULATE([Measure], DATEADD('Date'[Date], -1, YEAR))）、预算或滚动平均值
• 如果没有明确的目标，请询问用户——不要让 KPI 显得孤立。讨论使用上一期间、预算还是自定义阈值更合适
• 对差距应用条件格式，而非主要值
• 将颜色与次要提示（箭头/图标）搭配使用，以确保无障碍
• 在摘要层级大幅取整（“518M”，而不是“517,893,412”）
• 选择能推动决策的可执行指标，而非虚荣指标（应用“20% 变化测试”：如果这个数字变化了 20%，是否应该有人采取不同的行动？）
• 隐藏多余的自动生成副标题
• 使用 SVG 扩展度量值添加内嵌图标（参见 custom-visuals 插件中的 svg-visuals 技能）

有关 KPI 设计、目标、趋势、格式层级、图标实现、无障碍调色板和反模式的完整指南，请参阅 references/cards-and-kpis.md。

图表

• 按值降序排序（基于时间的图表除外）
• 尽量减少网格线和坐标轴杂乱元素
• 非必要元素使用柔和的颜色
• 谨慎突出显示关键数据点

有关图表类型选择（编码层级、Cleveland-McGill 排名）、数据标签规范和小多图指南，请参阅 references/chart-selection.md。

拒绝 LLM 常见的默认做法。 仪表盘式 KPI、单色分类柱形图、缺少排序、卡片墙、将原始字段名用作标题、内嵌十六进制颜色、偏离网格、双 Y 轴、3D 图表和过大的饼图都看似合理，却会误导读者。遇到这类需求时，请提出更好的方案；参见 references/anti-patterns.md。

表格和矩阵

表格需要经过深思熟虑的设计——“容易创建”不等于“容易阅读”。关键规则：

• 放在底部，用于详细下钻（3-30-300 规则）
• 先考虑决策：在构建之前，先明确问题、受众和行动
• 当 2 列或更多分类列构成层级时（关键客户 > 客户 > 产品），使用 matrix 而非 tableEx
• 做减法，而非加法：移除网格线和厚重的条带背景；用留白区分行
• 按最重要的度量值排序（通常是差异），而非按字母顺序
• 对主要度量值列应用数据条，便于快速查看大小
• 仅对差异列应用色阶——什么都格式化就等于什么都没格式化
• 在时间背景有帮助时（“是在改善还是在恶化？”），添加迷你图
• 显示完整精度（不使用显示单位）——读者会在表格中查看详细信息

有关表格与矩阵的选择、格式设计理念、条件格式技巧、迷你图、层级设计和反模式的完整指南，请参阅 references/tables-and-matrices.md。

切片器

• 每页最多 3 个
• 位置保持一致（顶部或左侧）
• 其他筛选器使用筛选器窗格
• 考虑在多个页面间同步切片器

筛选器窗格

筛选器窗格拥有独立于颜色和界面装饰的信息架构。关键决策包括：每个筛选器卡片是锁定还是隐藏、如何命名卡片而不重命名模型字段，以及报表级设置（应用按钮、搜索、允许更改筛选器类型）。参见 references/filter-pane.md。

移动端

Power BI 不会针对竖屏重新排列桌面页面；手机布局是从中手动挑选一部分内容，再放置到较窄的网格上。除非通过 mobile.json 明确启用，否则手机上不会渲染任何内容。有关子集选择模型和文件机制，请参阅 references/mobile.md。

报表评估标准

受要求评估或审查报表时，请重点关注客观标准。AI 很难进行主观评估——它无法直接“看到”报表，也没有直观的审美、认知负荷或有效性概念。请向用户强调这一限制。

客观检查清单

1. 页面数量： 通常超过 5-8 页就过多了
2. 每页可视化对象数量： 数量只是参考；每个可视化对象的查询成本才是关键（请参阅 references/layout-guidelines.md 的性能部分）。文本框、图像、形状和按钮不会发出查询。
3. 主题使用： 报表应使用自定义主题，以保持格式一致
4. 布局一致性：
   • 可视化对象之间的间距是否相等？
   • 页面是否有标题？
   • 是否遵循细节渐进原则（重要内容位于左上角，详细内容位于右下角）？
   • 卡片/KPI 是否位于顶部或左侧，且少于 4-6 个？
   • 切片器是否少于 3 个（改用筛选器窗格）？
   • 是否包含实用元素（刷新日期、链接、上下文）？
5. 颜色效果：
   • 是否谨慎使用条件格式（不会造成信息过载）？
   • 颜色是否柔和、低调（而非刺眼、明亮）？
   • 负面情绪色彩（红色、橙色）是否仅用于负值？
6. 信息墨水比： 是否减少了非必要元素（例如淡化网格线、禁用不必要的坐标轴/标签）？
7. 可读性： 所有元素的字体大小是否足够？
8. 无障碍性： 是否尽量减少阴影，以避免前庭不适？
9. 字体一致性： 字体大小是否有限且字体简单易读，并能在所有设备上正常显示？
10. 排序： 除非另有原因（如按时间排序），否则可视化对象应按降序排列？

评估输出

评估时，请提供：

• 发现的问题及其具体位置
• 严重程度（严重、警告、建议）
• 附带命令或模式的修复建议

设计关卡

宣布设计完成之前，请运行 references/quality-gate.md 中的收尾关卡。这不是构建前运行的规划阶段检查清单；它针对已完成的产物运行，并决定是否发布。它会验证身份信息是否已贯穿整个报表、每个页面是否只有一个意图、间距和边距是否相等且符合网格、重点提示是否有模型证据支撑，以及是否满足无障碍要求。由于 Agent 无法看到画布，请将该关卡与 pbir-cli 技能中的截图审查循环配合使用：渲染页面、查看并确认 JSON 推断的内容。

常见设计问题

问题：认知过载

症状： 颜色、可视化对象或数据点过多

修复：

• 减少可视化对象数量
• 使用柔和的调色板
• 应用细节渐进原则
• 隐藏非必要元素

问题：间距不一致

症状： 间隔不均、可视化对象未对齐

修复：

• 使用基于网格的定位
• 统一可视化对象尺寸
• 使用一致的边距

问题：可读性差

症状： 字体过小、对比度低

修复：

• 增大字体大小（最小 12pt）
• 检查颜色对比度
• 使用合适的字重

参考资料

• references/design-identity.md —— 以提交为先的设计身份：语调预算（克制／企业风／编辑风／技术风）、标志性设计目录，以及如何将设计身份序列化到主题中
• references/page-shapes.md —— 按意图（摘要／监控／探索／比较／叙事）为每个页面选择一种形态：页面应包含什么、应排除什么，以及精简布局
• references/anti-patterns.md —— 应拒绝的通用默认做法（用仪表盘式图表表示 KPI、单色条形图、缺少排序、卡片墙、原始标题、内联十六进制颜色、偏离网格、双轴、3D、过大的饼图）及其修正方法
• references/quality-gate.md —— 设计关卡：结束前检查（设计身份已传递、每页只有一种意图、间距一致、标注有证据支持、无障碍性），并按问题／位置／严重程度／修复方法的形式列出
• references/cards-and-kpis.md —— KPI 卡片设计：目标、差距、趋势、格式层级、图标、无障碍配色、反模式、审查清单
• references/tables-and-matrices.md —— 表格和矩阵设计：决策框架、做减法而非加法的理念、条件格式、排序、迷你图、矩阵层级、反模式
• references/layout-guidelines.md —— 画布尺寸、间距层级（组内／组间／边距）、对齐规则、性能成本模型
• references/visual-colors.md —— 配色原则、条件格式（CF）的依据选择（渐变／规则／字段值／图标）、语义令牌、无障碍性
• references/page-titles.md —— 标题实现、无障碍标题措辞、隐藏标题／替代文本规则
• references/chart-selection.md —— 编码层级（Cleveland-McGill 排名）、图表类型选择、数据标签规范、小多图
• references/tooltips-and-annotations.md —— 报表页工具提示设计、何时不应使用工具提示、用于引导式分析的注释基元
• references/filter-pane.md —— 锁定与隐藏、卡片命名、卡片顺序、“已应用”／“可用”样式、报表级设置
• references/mobile.md —— 将手机布局设计为精心筛选的子集、mobile.json 机制、应包含／排除的内容
• references/custom-visuals.md —— 自建与采购的优先级、AppSource／组织商店的权衡、许可差距

相关技能

报表结构与格式

• pbir-format（pbip 插件）—— visual.json、page.json、report.json 结构的 PBIR JSON 格式参考
• pbip（pbip 插件）—— PBIP 项目结构、表／度量值重命名、项目分叉

自定义视觉对象

报表通常需要 Power BI 未原生提供的视觉对象。考虑使用打包的第三方视觉对象前，务必先考虑仓库内的代码路径。有关自建与采购的决策以及 AppSource／组织商店的权衡，请参阅 references/custom-visuals.md。

仓库内代码视觉对象的技能路由（均位于 custom-visuals 插件中；使用 claude plugin install custom-visuals@power-bi-agentic-development 添加）：

• deneb-visuals —— Vega/Vega-Lite 声明式视觉对象；适用于高级自定义交互式图表（交叉筛选、工具提示、悬停）
• svg-visuals —— 通过 DAX 度量值生成 SVG；适用于没有行数上限问题的内联表格／矩阵／卡片图形
• python-visuals —— matplotlib/seaborn 脚本（静态 PNG）；适用于必须在渲染时计算的统计可视化
• r-visuals —— ggplot2 脚本（静态 PNG）；适用于 R 的统计生态中没有 Python 对应方案的情况（forecast、pheatmap、corrplot）

语义模型

报表的功能高度依赖底层语义模型。报表的大多数功能——度量值、计算列、关系、层次结构、行级安全性——都定义在语义模型中，而非报表中。设计或修改报表时，你通常需要了解或修改模型。关键技能：

• tmdl（pbip 插件）——直接编辑 TMDL 文件中的度量值、列和关系
• te-docs（tabular-editor 插件）——用于模型操作的 Tabular Editor CLI
• c-sharp-scripting（tabular-editor 插件）——用于批量修改模型的 C# 脚本
• bpa-rules（tabular-editor 插件）——用于模型质量检查的 Best Practice Analyzer 规则
• connect-pbid（pbi-desktop 插件）——连接到 Power BI Desktop 的本地 Analysis Services 实例，以实时查询和修改模型