create-pbi-report

创建 Power BI 报表

使用 pbir CLI 创建并搭建 Power BI 报表。使用 uv tool install pbir-cli 或 pip install pbir-cli 安装。请同时加载 pbir-cli 和 pbi-report-design 技能。

模糊或不够具体的提示

如果用户的请求没有说明具体度量值、受众背景、结构偏好或格式要求（例如“给我做个仪表板”“创建一些包含 KPI 的内容”），请先查阅 references/vague-prompts.md。通过有针对性的问题弥合意图与需求规格之间的差距；对于用户无法或不愿指定的内容，再应用合理的默认设置（sqlbi 主题、执行仪表板模式、由模型驱动的 KPI 选择）。

规则

• 可视化对象之间不得相互重叠
• 对于静态格式设置，优先调整主题，而不是单独覆盖可视化对象的格式
• 对于条件格式，优先使用带有主题颜色（如“bad”）的扩展度量值
• 始终在有名称的项目文件夹中创建报表（例如 sales-dashboard/Sales.Report）
• 每次修改后都运行 pbir validate
• 新报表已包含 sqlbi 主题；除非用户明确要求使用其他主题，否则不要运行 pbir theme apply-template
• 新报表已包含默认的 Page 1，其中有一个位于 (20,20)、高度为 90 的 textbox 可视化对象，用作页面标题；不要新增文本框，而应使用 pbir pages rename 重命名现有页面。所有可视化对象的 y 坐标都应为 120 或更大，以避免与标题文本框重叠。

快速参考

1. 向用户确认工作区和语义模型。如果用户想要连接到 Power BI Desktop，或使用源数据创建报表，请说明必须先在 Fabric 或 Power BI 中发布语义模型。

2. 分析用户的需求。考虑缺少的信息，例如图表、筛选器、格式和分析。若有不明确之处，请使用 AskUserQuestion。

3. 整理设计简报（受众、目的、决策问题、包含各页面意图的页面列表、确定的设计风格、交付目标）；在开始构建前征得用户同意；参见 references/design-brief.md。

4. 考虑缺失的语义模型对象——不仅要考虑用户提出的内容，也要考虑能丰富可视化对象的目标值（前 1 年）、基准值（期间平均值）或趋势聚合（14 天滚动值）。

5. 创建项目文件夹和报表（默认格式为 PBIP）：

   mkdir -p /path/to/report-name
   cd /path/to/report-name
   pbir new report "Name.Report" -c "Workspace/Model.SemanticModel"
   

6. 重命名默认页面（除非报表需要多个页面，否则不要新增页面）：pbir pages rename "Name.Report/Page 1.Page" --to "Overview" -f

7. 仅当用户要求自定义主题时，才运行：pbir theme apply-template "Name.Report" template-name（默认已包含 sqlbi 主题）

8. 发现模型字段：pbir model "Name.Report" -d

9. 查询筛选器或格式设置所需的字段值：pbir model "Name.Report" -q "EVALUATE VALUES('Table'[Column])"

10. 检查字段数据类型：pbir model "Name.Report" -d -t Table

11. 添加可视化对象（页面已包含标题文本框）：pbir add visual kpi "Name.Report/Overview.Page" --title "Revenue"

12. 配置查询缩减（切片器 + 重型可视化对象）：参见 references/interactivity.md

13. 设置交叉筛选覆盖和页面导航：参见 references/interactivity.md

14. 添加筛选器和切片器；配置切片器同步与重置：参见 references/interactivity.md

15. 验证：pbir validate "Name.Report"

16. 发布：pbir publish "Name.Report" "Workspace.Workspace/Name.Report"

17. 发布后在 Fabric 中打开：pbir publish "Name.Report" "Workspace.Workspace/Name.Report" -o

18. 或者在 Power BI Desktop 中本地打开：pbir open "Name.Report"

分步流程

步骤 1：了解业务流程

创建可视化内容前，先探索语义模型，了解业务领域。使用 pbir model "Report.Report" -d 检查表、列、度量值和层次结构。请考虑：

• 此模型涵盖哪个领域？（销售、财务、运营、物流等）
• 哪些 KPI 和度量值最重要？
• 有哪些维度和层次结构可用于切片数据？
• 哪种时间粒度最合适？（每日、每周、每月、每季度）

开始创建前，通过 AskUserQuestion 提交一份具体方案。方案应包括：

• 要显示哪些 KPI 卡片，以及它们展示哪些度量值
• 要包含哪些趋势图，以及采用何种时间粒度
• 哪些类别细分最有参考价值
• 要提供什么明细表／矩阵，以及采用哪些层次结构
• 筛选器应如何限定数据范围

先反复完善设计再执行——修改计划比重建可视化内容成本更低。

步骤 1b：汇总并锁定设计简报

将步骤 1 的探索结果和对模糊提示的调查结果汇总成一份设计简报。这不是第二轮需求收集，而是将已有信息整理成一份统一规格，供后续构建步骤执行。简报需说明受众、目的、查看者必须回答的 2-5 个决策问题、每个页面各自明确意图的页面列表、确定的设计风格（基调与标志性元素），以及交付目标。可复制的模板及各字段的填写说明见 references/design-brief.md。

通过 AskUserQuestion 提交一次简报，征求明确的“同意”或“修改 X”批准。获批后，将简报视为已锁定：构建步骤据此执行，不再重新讨论范围；如果之后需要变更范围，应重新打开简报，而不是悄然改变可视化内容。

获批的简报将交由 pbi-report-design 技能处理（该技能负责设计规范：在其中确定设计风格，并将每个页面意图映射到具体布局），随后进入下方的构建步骤。按概念引用设计风格和页面意图到布局的映射；这些推理归 pbi-report-design 负责，因此此处不要重复说明。

步骤 2：确定位置和连接

确定要在哪里创建报表，以及要连接哪个模型。目的、受众和决策问题已在锁定的简报中确定（步骤 1b）；此处不要再次询问。

pbir model                                       # List all known reports/models
pbir connect MyWorkspace MyReport                # Set active connection

如果用户提供了工作区位置，请先在项目文件夹中本地创建报表，然后发布。

步骤 3：创建报表

先创建项目文件夹，再在其中创建报表。默认格式为 PBIP。

mkdir -p sales-dashboard && cd sales-dashboard
pbir new report "Sales.Report" -c "MyWorkspace/Sales.SemanticModel"

生成的结构：

sales-dashboard/
  Sales.Report/
    definition/
      pages/
      report.json
    StaticResources/
    definition.pbir
  Sales.pbip

步骤 4：重命名默认页面并添加更多页面

报表自带一个默认的“Page 1”，其中已包含页面标题文本框。请重命名该页面，而不是创建新页面。仅在需要时添加其他页面。

pbir pages rename "Sales.Report/Page 1.Page" --to "Overview" -f  # Rename default page
pbir add page "Sales.Report/Detail.Page" -n "Detail"              # Add extra pages only if needed
pbir pages active-page "Sales.Report" "Overview"

步骤 5：配置主题（仅在用户要求时）

默认已包含 sqlbi 主题。只有用户明确要求使用其他主题或自定义颜色时，才修改主题。

# Only if user wants a different theme:
pbir theme apply-template "Sales.Report" custom-theme

# Or to customize specific colors:
pbir theme set-colors "Sales.Report" --good "#00B050" --bad "#FF0000"
pbir theme set-text-classes "Sales.Report" title --font-size 16
pbir theme set-formatting "Sales.Report" "card.*.border.radius" --value 8

步骤 6：为页面添加可视化对象

先检查页面的实际尺寸——不要假设页面尺寸为 1280x720。使用 pbir pages json "Report.Report/Page.Page" 进行验证。对象模型会验证可视化对象是否位于页面边界内。

用有明确目的的视觉层级填充画布。1280x720 页面的一般布局：

• 第 1 行（y：20-160）：KPI 可视化对象——使用 2-3 个 kpi 可视化对象展示带目标值和趋势线的关键指标
• 第 2 行（y：180-460）：趋势 + 细分——折线图/面积图（约占 60% 宽度）+ 条形图/柱形图（约占 40% 宽度）
• 第 3 行（y：480-700）：详细表格/矩阵——使用全宽 tableEx 或 matrix，并包含层次结构和条件格式

如需包含精确坐标、间距验证和可视化命令的完整布局示例，请参阅 references/layout-example.md。

关键原则：

• 间距一致：根据 (margin, gap, page_width, page_height) 计算位置。对于 1280x720 页面，margin=24、gap=16 时，可用宽度 = 1232。放置可视化对象前请验证计算结果。
• 避免重复标题：页面标题 = 主题（“订单行”），可视化对象标题 = 区分信息（“按重点客户划分”“月度趋势”）。隐藏副标题：pbir visuals subtitle "path" --no-show
• 排序：图表默认按第一个度量值降序排序。执行 pbir visuals bind 后，显式设置排序：pbir visuals sort "path" -f "Table.Measure" -d Descending

对于允许用户选择要查看的度量值或维度的报表，请使用字段参数，将 N 个近似重复的可视化对象合并为一个。请参阅 references/interactivity.md（字段参数部分）。

步骤 7：配置查询缩减

对于包含切片器或页面较繁忙（矩阵、地图、高基数表格）的报表，请在创建时应用查询缩减，而不是事后处理。事后改造会留下过时的交互配对，而且页面可能已经存在意外配置的交叉筛选。

三个组成部分（详情请参阅 references/interactivity.md）：

1. 添加从每个切片器指向繁重可视化对象的 NoFilter visualInteractions 配对
2. 启用筛选器窗格中的“应用”按钮：pbir filters pane-set
3. 在每个切片器上启用单独的“应用”按钮：pbir visuals format

对于查询开销较低的导入模式报表，应用前请评估禁用交叉突出显示是否值得牺牲交互性。

步骤 8：配置交互和导航

放置可视化对象后，设置交叉筛选覆盖项并构建导航。默认情况下，所有对象都会交叉筛选其他对象，因此只需配置例外情况。对于多页报表，请添加 pageNavigator 可视化对象，而不是单独添加按钮。

分步说明和注意事项请参阅 references/interactivity.md（配置交互和导航部分）。

步骤 9：添加筛选器和切片器

pbir add filter Date Year -r "Sales.Report" --values 2025
pbir add filter Geography Region -r "Sales.Report"
pbir add filter Products Category -p "Sales.Report/Detail.Page"

如需了解切片器类型选择、同步组以及筛选器重置/持久化模式，请参阅 references/interactivity.md（切片器类型、同步和重置部分）。

步骤 10：设置可视化对象格式

大多数格式设置应来自主题（步骤 5）。仅在确有特殊需求时才应用专门的格式设置。

# Bulk formatting via glob (requires -f for glob patterns)
pbir set "Sales.Report/**/*.Visual.title.show" --value true -f
pbir set "Sales.Report/**/*.Visual.border.show" --value true -f

# Individual visual formatting
pbir visuals title "Sales.Report/Overview.Page/Revenue.Visual" --fontSize 14 --bold
pbir visuals background "Sales.Report/Overview.Page/Revenue.Visual" --color "#F8F9FA"

对于会根据切片器选择作出响应或随状态改变颜色的标题，请使用 _Report 扩展度量值：

# Author a selection-aware title measure
pbir dax measures add \
  "Sales.Report" \
  -n "Title_Sales" \
  -e "IF(ISFILTERED('Region'[Region]), \"Sales: \" & SELECTEDVALUE('Region'[Region], \"multiple regions\"), \"Sales: all regions\")" \
  -t _Report

# Bind via title CF, or drive a textbox text run with the measure

动态标题的关键规则：

• 必须使用 SELECTEDVALUE(..., "<fallback>")；否则，多选时标题会消失
• 文本度量值和颜色度量值应分开设置（一个返回字符串，一个返回“good”/“bad”等主题标记）；两者都可以单独测试
• 度量值驱动的标题不能与字面标题共存；请先清除字面标题
• 通过分析 ISFILTERED/HASONEVALUE，推理无选择、单选和多选情况下的结果，然后通过渲染进行确认

步骤 11：验证

pbir validate "Sales.Report"
pbir tree "Sales.Report" -v

步骤 12：发布或打开

pbir publish "Sales.Report" "MyWorkspace.Workspace/Sales.Report"      # Publish
pbir publish "Sales.Report" "MyWorkspace.Workspace/Sales.Report" -o   # Publish and open in browser
pbir open "Sales.Report"                                               # Open in Power BI Desktop

常见报表模式

执行仪表板

• 顶部放置 2-3 张 KPI 卡片（收入、订单、利润率）
• 1 张趋势折线图/面积图（按年筛选时按月显示，按月筛选时按日/周显示）
• 1-2 张按关键类别细分的图表（条形图/柱形图）
• 1 张包含层级和条件格式的明细表或矩阵
• 页面尺寸：1280x720（16:9）

详细分析

• 顶部放置切片器栏（日期范围、类别筛选器）
• 以大型表格或矩阵作为主要内容，并使用条件格式
• 放置辅助 KPI 卡片以提供背景信息
• 页面尺寸：1280x720 或 1920x1080

工具提示页

• 小尺寸页面（320x240 或类似尺寸）
• 2-3 个重点可视化对象
• 通过 pbir pages type "path" --type tooltip 设置

参考文件

• references/vague-prompts.md -- 处理未充分说明的提示词：提出有针对性的问题、设置合理的默认值、采用先提议再构建的工作流
• references/design-brief.md -- 已锁定的设计简报模板：决策问题、每页意图、已确定的设计特征（基调和标志性元素）、交付目标、审批关卡，以及转交至 pbi-report-design
• references/layout-example.md -- 完整布局，包含坐标、间距验证和时间粒度指导
• references/interactivity.md -- 查询缩减、交叉筛选连接、导航、切片器类型/同步/重置、字段参数
• references/limitations.md -- 需要告知用户的 Agent 限制