pbir-format

PBIR 格式参考

此 Skill 用于教 Claude 读取和使用 Power BI 增强型报表（PBIR）JSON 格式。不支持旧版 report.json 或 layout 报表元数据。要从旧版格式转换为 PBIR 格式，用户必须在 Power BI Desktop 中打开并保存报表。

使用报表时，请在合理范围内遵循心智模型。

硬性规则： 将 PBIR JSON 视为实现细节。仅在需要了解架构上下文时读取它；所有报表、视觉对象、页面、书签、筛选器、移动布局和主题更改，都必须通过 pbir 完成。绝不手动编辑、文本替换或编写脚本来修改报表 JSON。如果 pbir 无法执行所请求的更改，请停止并说明能力限制，不要自行编造直接修改原始 JSON 的替代方案。

通用重要指导

• 检查示例： 查看示例以了解有效报表
• 备份： 修改前请先复制一份报表
• PBIX、PBIP 与 PBIR： 使用 PBIR 格式的本地 .Report 文件夹。对于受支持的转换，请使用 Power BI Desktop 或 pbir report convert；不要解压、重新压缩或修补 PBIX 内部文件。不要直接处理 PBIT 文件。
• 有效 JSON 不等于可渲染 JSON： JSON 有效并不保证能够渲染。如果 visual.json 中绑定的字段无效（字段不存在、表错误或拼写错误），如果视觉元素被其容器裁切，如果模型性能问题导致 dax 查询超时，或者模型数据质量问题导致结果为 (Blank) 或空值等，视觉对象可能无法渲染。如果报表已发布到 Power BI，可使用 chrome 或 chrome devTools MCP 服务等工具检查视觉对象是否成功渲染，但通常直接请用户在 Power BI Desktop 或浏览器中检查会更快。
• 分层格式级联： 在 Power BI 报表中，格式由以下顺序决定：默认值 --> 主题通配符 (*) --> 主题 visualTypes --> 专属 visual.json 配置。主题会覆盖默认值，visualType 会覆盖主题中的通配符，而 visual.json 会覆盖所有主题格式。尽可能将格式设置放入主题，而不是专属 visual.json 配置中，这样只需在一个位置进行更改。
• PBIR 文件是严格的 JSON： 不允许添加注释
• 不要臆测： 如需了解背景信息，请查阅 Microsoft 文档和其他可靠资源，或询问用户。

报表结构

Report.Report/
+-- .pbi/localSettings.json                # Local-only, gitignored
+-- .platform                              # Fabric Git integration
+-- definition.pbir                        # Semantic model connection (byPath or byConnection) can open this file in Power BI Desktop to open the report
+-- mobileState.json                       # PBIR-Legacy artifact only; current PBIR stores phone layout per-visual in mobile.json
+-- semanticModelDiagramLayout.json        # Model diagrams
+-- CustomVisuals/                         # Private custom visuals only
+-- definition/
|   +-- version.json                       # REQUIRED -- PBIR version
|   +-- report.json                        # REQUIRED -- report-level config, including theme, report filters, settings
|   +-- reportExtensions.json              # Extension measures and visual calculations (report- and visual-level DAX)
|   +-- pages/
|   |   +-- pages.json                     # Page order, active page
|   |   +-- [PageName]/                    # Power BI Desktop may generate names with spaces; recommend no spaces for human-authored names
|   |       +-- page.json                  # Page-level properties, including size, background, filters
|   |       +-- visuals/
|   |           +-- [VisualName]/
|   |               +-- visual.json        # Visual config, formatting, and field data bindings <-- most important and complex file for report dev and formatting
|   |               +-- mobile.json        # Mobile formatting of the visual (niche)
|   +-- bookmarks/                         # Bookmarks are a bad practice and should be avoided if possible!
|       +-- bookmarks.json                 # Bookmark order and groups
|       +-- [id].bookmark.json             # Individual bookmark state containing a snapshot of the report basically
+-- StaticResources/
    +-- RegisteredResources/               # Custom themes, images
        +-- [ThemeName].json               # Custom theme <-- second most important and complex file for formatting
    +-- SharedResources/BaseThemes/        # Microsoft base themes

规则

审查报表或提供反馈时，请在合理范围内遵循心智模型。

修改报表

1. 理解用户的需求。必要时提问以明确业务背景，重点了解业务流程、用户和模型。
2. 高效探索报表，找到相关页面和视觉对象。
3. 检查连接的语义模型。对于精简报表（byConnection），使用 fab、pbir 或 te CLI 工具探索模型。对于 byPath，在 Power BI Desktop 中连接本地模型。了解模型有助于掌握可用字段和计算逻辑。
4. 确定要修改的视觉对象和页面。如有需要，请向用户澄清。
5. 使用正确的 PBIR 结构和属性值规划修改。

创建报表

1. 流程与修改报表相同，但使用 pbir new 生成报表。不要手动搭建 报表 JSON。
2. 确保正确配置 definition.pbir（byPath 或 byConnection）。
3. 使用 theme.json 文件。推荐：SQLBI/Data Goblins 主题
4. 使用 pbir add filter 添加筛选器；请参阅筛选器窗格参考

其他验证

有关详细的报告设计指南（布局、间距、视觉层次、颜色、无障碍性），请参阅 pbi-report-design 技能。验证期间执行的主要规则：

• 使用自定义主题；除非用户另有指定，否则应优先通过主题设置格式，而不是为每个视觉对象单独定制 visual.json
• 视觉对象不得重叠；视觉对象之间以及视觉对象与页面边缘之间应保持相等的间距
• 每个页面都需要标题（文本框或背景图片）。确保文本框足够高，能够正常显示（24-28 pt）
• 遵循 3-30-300 规则：顶部放置 KPI/卡片，中部放置细分内容，底部放置详细信息。每页最多使用 2-3 个切片器；如需更多筛选，请使用筛选器窗格
• 优先使用 Deneb、Python 或 R 自定义视觉对象，而非 SVG 或经过大量定制的核心视觉对象——在美观性与技术债务之间取得平衡
• 仅当模型度量值无法满足需求时，才使用报告扩展（精简报告度量值、视觉对象计算）
• 将条件格式集中在扩展或模型度量值中，并引用主题语义颜色（"bad"、"good"）
• 使用一致的颜色来引导注意力，而非单纯装饰。类别超过 5 个时，避免使用饼图
• 按逻辑顺序对视觉对象排序（通常按度量值降序）。除非有明确理由，否则图表坐标轴从零开始
• 使用一致的字体。为确保无障碍性，设置 altText。以描述性名称命名视觉对象（如 revenue_bar_chart，而非 a1b2c3d4）
• 移除冗余视觉对象。对于基数较高的切片器，可考虑使用“应用”按钮
• 部署前验证请参阅 Data Goblins 报告检查清单

常见任务的阅读指南

任务	阅读
添加或修改视觉对象	references/visual-json.md —— 表达式语法、字段引用、查询角色、位置、objects 与 visualContainerObjects 的区别、选择器
更改格式或颜色	references/visual-container-formatting.md（容器外观）+ references/theme.md（主题级格式设置）。优先更改主题，而不是单独设置视觉对象格式
添加条件格式	references/schema-patterns/conditional-formatting.md + references/measures.md（用于 CF 的扩展度量值）
添加或配置筛选器	references/filter-pane.md —— 全部 7 种筛选器类型、默认值、筛选器发现
使用主题	references/theme.md —— 继承、通配符、视觉对象类型覆盖、筛选器窗格样式设置、使用 jq 检查和修改
将视觉对象格式设置推送到主题	references/theme.md —— 使用 pbir theme push-visual 预览并推广可复用的格式设置
更改页面布局或背景	references/page.md —— 尺寸、背景、壁纸、visualInteractions
创建工具提示页面	references/page.md —— 工具提示页面设置（类型、大小、可见性）+ 在视觉对象上启用 visualTooltip
创建钻取页面	references/page.md —— page filterConfig 中的钻取筛选器
更改报表设置	references/report.md —— themeCollection、resourcePackages、settings、outspacePane
添加扩展度量值	references/measures.md —— reportExtensions.json 结构、DAX 模式、引用方法
添加注释或元数据	references/annotations.md —— 为报表、页面和视觉对象添加自定义名称-值元数据，用于部署脚本、文档和外部工具
添加图像或 SVG	references/images.md —— RegisteredResources、主题中的 base64、SVG 度量值
添加或修改文本框	references/textbox.md —— 段落、textRuns、textStyle
对视觉对象排序	references/sort-visuals.md —— 查询中的 sortDefinition
跨页面同步切片器	references/visual-json.md —— syncGroup（groupName、fieldChanges、filterChanges）
编辑视觉对象交互	references/visual-json.md + references/page.md —— page.json 中的 visualInteractions（NoFilter、Filter、Highlight）
更改表格/矩阵列宽	references/visual-json.md —— 使用元数据选择器的 columnWidth
对视觉对象分组	references/visual-json.md —— visualGroup、parentGroupName、groupMode
隐藏视觉对象或字段	references/visual-json.md —— 根级别的 isHidden、查询投影控制
设置图表元素格式（标签、标记、线条）	references/visual-json.md —— labels、markers、lineStyles、dataPoint
添加分析线（参考线、趋势线、误差线、预测线）	references/visual-json.md —— y1AxisReferenceLine、trend、error、forecast
使用书签	references/bookmarks.md —— 书签状态、筛选器快照、显示/隐藏视觉对象
查找模型字段	references/semantic-model/finding-fields.md —— pbir model、te、fab 命令
重新绑定到其他模型	references/semantic-model/report-rebinding.md —— byPath 与 byConnection 转换
了解架构版本	references/schemas.md —— 所有架构类型和当前版本
验证或检查一致性	references/validation.md —— 一致性维度、pbir validate 类别、名称和必填字段规则、审计和发现命令
了解视觉对象如何生成 DAX 查询	references/semantic-model/inferring-queries-from-visuals.md —— 视觉对象元数据 → SUMMARIZECOLUMNS 映射、数据角色、IGNORE() 上下文
构建或验证 DAX 查询模式	references/semantic-model/model-queries.md —— SUMMARIZECOLUMNS 模式、ROW()、查询执行方法
在整个报表中重命名表或字段	references/how-to/fix-broken-field-references.md —— 完整的 pbir fields replace / replace-table 工作流
模型更改后修复失效的字段引用	references/how-to/fix-broken-field-references.md —— 诊断、重命名/移动/移除字段的修复工作流、切片器值注意事项
将旧版 report.json 转换为 PBIR 格式	references/how-to/convert-legacy-to-pbir.md —— 格式差异、分步转换、projections 到 queryState 的映射、验证
了解 reportExtensions.json 架构	references/report-extensions.md —— 文件架构结构、实体、视觉计算；DAX 编写模式请参阅 references/measures.md
设置动态（由度量值驱动的）替代文本	references/visual-container-formatting.md —— visualContainerObjects.general 下作为 Measure 表达式的 altText
在文本框中添加动态文本运行	references/textbox.md —— 绑定到度量值的 textRuns；必须通过 Desktop 往返一次
了解钻取的交叉筛选行为	references/visual-json.md —— drillFilterOtherVisuals 与 visualInteractions
注册自定义视觉对象（AppSource、组织商店、私有 .pbiviz）	references/report.md —— publicCustomVisuals、organizationCustomVisuals、resourcePackages
了解架构版本之间的关联	references/schemas.md —— 父级/嵌入式架构集、在报表之间复制片段
设置移动设备（手机）布局	references/pbir-structure.md —— 每个视觉对象的 mobile.json、坐标空间、Git 规范
PBIR 项目的 Git 规范	references/pbir-structure.md —— 应跟踪、忽略以及留给 Desktop 处理的内容

definition.pbir

报表必须连接到语义模型。有两种方式：

• byPath -- 本地 PBIP 引用/厚报表：{"byPath": {"path": "../Model.SemanticModel"}}（架构 2.0.0）
• byConnection -- 远程/薄报表：{"byConnection": {"connectionString": "Data Source=powerbi://..."}}（架构 2.0.0）

相关技能

• pbip -- PBIP 项目操作：重命名级联、项目分支、报表 JSON 模式
• tmdl -- TMDL 文件格式、编写和编辑

参考资料

获取文档： 如需获取最新的 Power BI 开发人员/报表格式文档，请搜索 https://learn.microsoft.com 并获取相关页面。根据用户的请求进行搜索，必要时运行多次搜索，以确保在继续操作前获得充分的上下文。

示例：

• examples/K201-MonthSlicer.Report/ -- 包含 7 种视觉对象类型（切片器、高级切片器视觉对象、KPI、折线图、散点图、表格、文本框）的真实 PBIR 报表，还包括扩展度量值、书签和条件格式
• examples/visuals/ -- 54 个独立的 visual.json 示例；请参阅 examples/visuals/__index.md 中的目录。分为 default/（最简、仅主题）和 formatted/（自定义格式、条件格式、渐变、筛选器）

核心参考资料：

• references/visual-json.md -- visual.json：表达式、字段引用、查询角色、位置、objects 与 vCO、选择器、排序、筛选器、钻取传播
• references/desktop-bridge.md -- 通过 pbir desktop 重新加载并截图，在画布上验证 PBIR 编辑；预览设置；定位已打开的 PBIP
• references/pbir-structure.md -- PBIR 文件夹结构、mobile.json 存储机制、git 规范
• references/schemas.md -- 架构版本、URL 和内嵌架构耦合
• references/validation.md -- 一致性维度及验证方法（架构、名称和 ID、必填字段、字段、枚举、角色、布局、主题、语义）；pbir validate 类别；审计和发现命令
• references/enumerations.md -- 有效属性枚举
• references/version-json.md -- version.json 格式（简要）
• references/platform.md -- .platform 文件格式（简要）
• references/bookmarks.md -- 书签结构和状态快照

格式与表达式：

• references/theme.md -- 主题通配符、继承、颜色系统、筛选器窗格样式、 视觉对象类型覆盖，以及相应的 pbir theme 命令
• references/schema-patterns/ -- 表达式、选择器、条件格式、视觉计算
• references/visual-container-formatting.md -- objects 与 visualContainerObjects 深入解析；动态（由度量值驱动的）altText
• references/measures-vs-literals.md -- 何时使用度量值表达式，何时使用字面值
• references/measures.md -- 扩展度量值模式

视觉对象与页面配置：

• references/textbox.md -- 文本框视觉对象格式；动态（绑定度量值）文本运行
• references/page.md -- 页面配置和背景
• references/report.md -- 报表级设置；自定义视觉对象注册（AppSource、组织商店、私有 .pbiviz）
• references/wallpaper.md -- 报表壁纸/画布背景
• references/filter-pane.md -- 筛选器窗格格式
• references/sort-visuals.md -- 视觉对象排序配置
• references/images.md -- 静态图像、主题中的 base64、SVG 度量值
• references/report-extensions.md -- reportExtensions.json 格式
• references/annotations.md -- 报表、页面和视觉对象的自定义元数据

语义模型集成：

• references/semantic-model/ -- 字段引用、模型结构、报表重新绑定、查询推断

操作指南：

• references/how-to/ -- 高级条件格式、视觉对象中的 SVG、修复损坏的字段引用、将旧格式转换为 PBIR