power-bi-report

Power BI 报表技能

在顶层管理 Power BI PBIR 报表项目——搭建脚手架、验证、预览和集成 Desktop。大多数操作无需连接 Power BI Desktop。

PBIR 格式

PBIR（增强型报表格式）将报表存储为一组 JSON 文件：

MyReport.Report/
  definition.pbir            # dataset reference
  definition/
    version.json             # PBIR version
    report.json              # report settings, theme
    pages/
      pages.json             # page order
      page_abc123/
        page.json            # page settings
        visuals/
          visual_def456/
            visual.json      # visual type, position, bindings

每个文件都有 Microsoft 提供的公开 JSON 架构，可用于验证。 截至 2026 年 1 月，PBIR 已正式发布（GA），并自 2026 年 3 月起成为 Desktop 的默认格式。

创建报表

# Scaffold a new report project
pbi report create ./MyProject --name "Sales Report"

# With dataset reference
pbi report create ./MyProject --name "Sales" --dataset-path "../Sales.Dataset"

这会创建完整的文件夹结构，其中包含 definition.pbir、report.json、version.json 和一个空的 pages/ 目录。

报表信息与验证

# Show report metadata summary (pages, theme, dataset)
pbi report info
pbi report info --path ./MyReport.Report

# Validate report structure and JSON files
pbi report validate

验证会检查：

• 必需文件是否存在（definition.pbir、report.json、version.json）
• 所有 JSON 文件是否都能无错误地解析
• 架构 URL 是否存在且一致
• pages.json 中的页面引用是否与实际页面文件夹匹配

预览

启动报表布局的实时 HTML 预览：

pbi report preview

打开浏览器，显示所有页面的视觉占位符、类型、位置和数据绑定。文件更改时，预览会自动刷新。

需要可选依赖项 preview：pip install pbi-cli-tool[preview]

Desktop 集成

# Trigger Power BI Desktop to reload the current report
pbi report reload

Power BI Desktop 的开发者模式会自动检测 TMDL 更改，但不会检测 PBIR 更改。此命令会向 Desktop 窗口发送键盘快捷键以触发重新加载。需要可选依赖项 reload：pip install pbi-cli-tool[reload]

禁用自动同步（--no-sync）

默认情况下，每个写入命令（add-page、delete-page、set-background、set-theme 等）都会在每次操作后自动同步 Power BI Desktop。分多个步骤构建报表时，这会导致 Desktop 在每条命令后都重新加载。

在 report 命令组中使用 --no-sync 可禁用逐条命令同步，然后在最后调用一次 pbi report reload：

# BAD: Desktop reloads after every command
pbi report add-page --display-name "Overview" --name overview
pbi report set-background overview --color "#F2F2F2"

# GOOD: suppress sync during build, reload once at the end
pbi report --no-sync add-page --display-name "Overview" --name overview
pbi report --no-sync set-background overview --color "#F2F2F2"
pbi report reload

--no-sync 可用于以下命令组：report、visual、filters 和 bookmarks。

转换

# Convert a .Report folder into a distributable .pbip project
pbi report convert ./MyReport.Report --output ./distributable/

路径解析

所有报表命令都会自动检测 .Report 文件夹：

1. 显式指定：pbi report --path ./MyReport.Report info
2. 自动检测：从 CWD 向上查找 *.Report/definition/
3. 从 .pbip 文件查找：从 .pbip 文件定位同级的 .Report 文件夹

工作流：构建完整报表

此工作流使用多个技能中的命令：

# 1. Scaffold report (this skill)
pbi report create . --name "SalesDashboard" --dataset-path "../SalesModel.Dataset"

# 2. Add pages (power-bi-pages skill)
pbi report add-page --display-name "Overview" --name overview
pbi report add-page --display-name "Details" --name details

# 3. Add visuals (power-bi-visuals skill)
pbi visual add --page overview --type card --name revenue_card
pbi visual add --page overview --type bar --name sales_by_region

# 4. Bind data (power-bi-visuals skill)
pbi visual bind revenue_card --page overview --field "Sales[Total Revenue]"
pbi visual bind sales_by_region --page overview \
    --category "Geo[Region]" --value "Sales[Amount]"

# 5. Apply theme (power-bi-themes skill)
pbi report set-theme --file brand-colors.json

# 6. Validate (this skill)
pbi report validate

组合模型与报表

pbi-cli 涵盖语义模型层和报表层：

# Model layer (requires pbi connect)
pbi connect
pbi measure create Sales "Total Revenue" "SUM(Sales[Amount])"

# Report layer (no connection needed)
pbi report create . --name "Sales"
pbi visual add --page overview --type card --name rev_card
pbi visual bind rev_card --page overview --field "Sales[Total Revenue]"

相关技能

技能	使用场景
power-bi-visuals	添加、绑定、更新、删除视觉对象
power-bi-pages	添加、移除、配置页面和书签
power-bi-themes	主题、条件格式
power-bi-filters	页面和视觉对象筛选器

JSON 输出

pbi --json report info
pbi --json report validate

---

注意事项

• **report validate 对无法在 Desktop 中打开的 PBIR 仍会通过：**验证只会检查 JSON 结构和必需文件，不会验证数据集绑定、架构 URL 版本或视觉对象的 queryState 一致性。验证通过后，Desktop 仍提示“无法打开报表”，这是已知的陷阱。
• **--dataset-path 是相对于 .Report 文件夹的路径，而非 CWD：**在创建时，../Sales.Dataset 参数可以正确解析；但如果之后移动 .Report 文件夹，绑定会悄然失效。请使用稳定的工作区布局，或在 CI 中使用绝对路径。
• **pbi report reload 会向当前获得焦点的窗口发送键盘快捷键：**如果触发重新加载时用户正在其他应用中输入，按键就会发送到该应用。请仅在一批操作结束时执行重新加载，并提醒用户不要切换上下文。
• **report convert 转换为 .pbip 时不会打包语义模型：**它会生成一个通过路径引用数据集的 .pbip 框架。分发生成的文件夹时，如果没有同时打包 .SemanticModel 目录，打开时就会出现“找不到数据集”错误。
• **PBIR 架构版本按文件固定，而非按项目固定：**混用由不同 Desktop 版本编写的文件（例如，一个页面由 2026 年 3 月的版本编辑，另一个页面由 2026 年 1 月的版本编辑），可能会导致某个版本的验证失败，而另一个版本的验证通过。请始终一并升级整个项目。
• **--no-sync 只对其所在的命令组生效：**执行 pbi visual --no-sync add ... 后再执行 pbi report set-background ...，第二条命令后仍会同步。批处理中涉及的每个命令组都要设置 --no-sync。