powerbi-report-authoring

重要说明

1. 要根据工作区名称查找工作区详情（包括其 ID）：列出所有工作区，然后使用 JMESPath 进行筛选
2. 要根据工作区 ID、项类型和项名称查找项详情（包括其 ID）：列出该工作区中此类型的所有项，然后使用 JMESPath 进行筛选

Power BI 报表创作技能（PBIR/PBIP 格式）

此技能支持读取、编辑和创建 Power BI 报表定义文件，这些文件采用 PBIP （Power BI Project） 文件使用的 PBIR（Power BI Report） 格式。

必须/优先/避免

必须

• 仅将此技能用于具体的 PBIR/PBIP 报表文件操作，例如页面、视觉对象、筛选器、切片器、导航、书签、主题、格式设置、验证、Desktop 重新加载和截图。
• 每完成一个逻辑批次后，使用 powerbi-report-author validate 验证 PBIR。
• 对于渲染输出的更改，使用 powerbi-desktop 的重新加载/截图工作流。
• 在编写视觉对象角色、格式对象、枚举值、选择器或表达式编码之前，先使用 CLI 查询功能。

优先

• 从已批准的 Design Brief: 或 _brief/report-spec.md 开始构建全新报表。
• 在编写文件之前，将视觉设计方面的不确定性提交给 powerbi-report-design。
• 对于语义模型元数据或模型侧更改，在可用时使用语义模型创作技能、Power BI Modeling MCP 或本地 TMDL 文件。

避免

• 当 CLI 元数据或参考文件可用时，不要凭记忆猜测 PBIR JSON。
• 不要仅使用此技能来处理开放式设计、报表规划或 Fabric 报表项 CRUD；应与 powerbi-report-design、powerbi-report-planning 或 powerbi-report-management 配合使用。

快速入门工作流

0. 规划／设计路由 → 对于从零开始的构建，先阅读 powerbi-report-planning；对于主题、视觉风格、布局、重新设计或评审，阅读 powerbi-report-design。返回此处了解 PBIR 机制。开始编写前，将 _brief/report-spec.md 中的 Design Brief: yaml 代码块（或对话中经批准的内联 Design Brief: 代码块）用作实现上下文。
1. 设置／更新 CLI → 首次使用前，确认 powerbi-report-author 和全局 powerbi-desktop 命令均可用；请参阅 CLI 设置。
2. 了解模型 → 如果有语义模型 MCP Server／技能，请使用；否则直接阅读 TMDL 文件，了解表、列和度量值名称。
3. 桌面端上下文 → 如需查看 Desktop 实时状态、打开 PBIP／PBIX 文件、重新加载、截图或进行视觉验证，请使用来自 @microsoft/powerbi-desktop-bridge-cli 的 powerbi-desktop CLI；请参阅 编辑 → 验证 → 重新加载 → 截图循环。
4. 按意图选择指南 → 使用主题文件和示例选择相关指南。
5. 使用 CLI 元数据 → 使用创作元数据与验证 CLI查找准确的视觉角色、格式对象、属性名称、枚举值和选择器要求；不要凭记忆推断。
6. 检查常见陷阱 → 当更改涉及视觉对象、绑定、筛选器、格式、布局或 Desktop 渲染时，请在编辑或验证前阅读反模式与陷阱。
7. 验证 → 每完成一批逻辑相关的 PBIR 更改后，运行 powerbi-report-author validate <path-to-.Report-dir>；请参阅验证。
8. 验证渲染效果 → 对任何渲染输出更改，都要使用 powerbi-desktop 重新加载并截图；请参阅编辑 → 验证 → 重新加载 → 截图循环和截图审查。只有验证和视觉审查均通过后，才能继续。对于仪表板／报表构建，仅搭建页面框架并不算完成——每个请求的页面都需要包含绑定数据的视觉对象。
9. 反馈结果 → 向用户简要总结已完成的工作以及遇到的问题（包括重大和轻微问题）。

主题文件和示例

编辑前，根据用户的意图选择相关主题文件：

文件	何时阅读
authoring.md	添加／修改页面、视觉对象、钻取和交互 — 包含完整的 JSON 示例
powerbi-desktop.md	在 Desktop 中进行实时验证 — powerbi-desktop 命令、PID 选择、重新加载、截图、错误和故障排除
screenshot-review.md	在 Desktop 截图后，查看截图清单和渲染输出故障排除
formatting-overview.md	更改外观前先阅读 — 层叠模型、编码规则、选择器，以及指向其他格式设置文件的导航
formatting.md	编辑 visual.json 外观 — 选择器、VCO、编码机制、背景图路由和层叠
color-strategy.md	图表数据点颜色 — 主题 dataColors、dataPoint.defaultColor 和带选择器的 dataPoint.fill，以及跨视觉对象的度量值颜色一致性
conditional-formatting.md	数据驱动格式设置 — 颜色渐变（FillRule）、基于规则的格式设置、图标集、数据条、Web URL 和字段值
page-formatting.md	编辑 page.json 外观 — 画布背景、壁纸和页面背景图
filter-pane.md	筛选器窗格（outspacePane）和筛选器卡片（filterCard）样式 — 已应用／可用状态样式、窗格宽度、搜索／复选框颜色
theming.md	创建或编辑 theme.json — dataColors、textClasses、visualStyles、样式预设和 ThemeDataColor 参考
re-theming.md	为已有视觉对象的报表切换主题 — 重新设置主题的工作流（颜色映射 + 批量调整）、深色模式清单、深色↔浅色极性更改。若要更改带有各视觉对象覆盖设置的报表中的颜色，请与 theming.md 配合使用。
expressions.md	构建字段引用（Column、Measure、Aggregation、Hierarchy）和排序定义
filters.md	添加／修改筛选器 — 包含完整的 JSON 示例
slicers.md	添加／修改切片器或切片器选择前先阅读 — Agent 工作流、JSON 模板和选择配置
cartesian.md	添加条形图、柱形图和折线图 — 系列、角色、查询模式（多度量值、钻取层次结构、日期层次结构）和格式设置
map.md	添加地图视觉对象 — 模板、角色、地理编码工作流和渲染失败处理
card.md	添加或设置 KPI／卡片视觉对象的格式 — cardVisual、id 选择器、标注／值大小和强调条
table.md	添加或设置表格／矩阵的格式 — tableEx、pivotTable、列自动扩展以适应内容和行带状样式
image.md	添加图像视觉对象 — 本地资源、URL、数据绑定图像、ImageUrl 验证／拒绝工作流；也包括图表视觉对象的绘图区背景图
shape.md	添加形状视觉对象 — 容器、分隔线、背景和参考图匹配
textbox.md	添加静态或动态文本框视觉对象 — 段落、文本片段和绑定值表达式
version-control.md	Git 分支、提交和回滚 — 任务涉及版本控制或安全回滚规划时阅读

从零构建 / 设计交接

具体工作确定后，此技能负责 PBIR 文件机制：页面/视觉对象 JSON、绑定、筛选器、切片器、主题、格式设置、导航、书签、验证、Desktop 重新加载和截图。

对于新的报告/仪表板请求、需求收集、依赖项检查、审批或端到端构建排序，请在创作前使用 powerbi-report-planning。对于开放式视觉设计、重新设计/样式调整、品牌/主题方向、图表选择或布局评审，请使用 powerbi-report-design。在规范/设计简报获批或有具体 PBIR 编辑任务需要实施后，回到此处 — 关于如何使用简报，请参见快速入门第 0 步。

大型构建的执行

对于完整报告/PBIP 构建，不要将完整的 PBIP 生成工作委派给子 Agent — 负责的 Agent 必须协调设计简报、模型清单、跨页面一致性、验证循环和 Desktop 检查。

如果上下文或重复工作构成限制，应优先使用确定性的 Node.js 生成器来读取获批的设计简报并写入 PBIR JSON。如果委派仍有帮助，可按页面或视觉对象类别拆分任务，并向每个子 Agent 提供相关的简报摘录、确切字段/度量值以及布局/视觉对象规范；让其返回范围明确的 PBIR JSON 或补丁，再由负责的 Agent 集成并验证。

CLI 设置

前提条件：Node.js 20 或更高版本。 使用 node --version 检查。如果未安装或版本较旧，请从 nodejs.org 或通过包管理器安装 — Windows：winget install OpenJS.NodeJS.LTS；macOS：brew install node；Linux：发行版软件包或 nodesource。

在会话中使用 CLI 之前，请确保已安装最新的全局版本：

npm install -g @microsoft/powerbi-report-authoring-cli@latest @microsoft/powerbi-desktop-bridge-cli@latest

确认两者都位于 PATH 中：

powerbi-report-author --version
powerbi-desktop --version

PBIR 文件布局

磁盘上的 PBIP 项目如下所示：

<Report>.pbip                              # Project manifest
├── <Report>.Report/
│   ├── .platform                          # Fabric metadata (type, logicalId)
│   ├── definition.pbir                    # Report → SemanticModel binding
│   ├── definition/
│   │   ├── version.json                   # Format version (e.g. "2.0.0")
│   │   ├── report.json                    # Report-level: themes, settings, resources
│   │   └── pages/
│   │       ├── pages.json                 # Page order + active page name
│   │       └── <pageId>/
│   │           ├── page.json              # Page: displayName, size, type, filters
│   │           └── visuals/
│   │               └── <visualId>/
│   │                   └── visual.json    # Visual: type, position, query, formatting
│   ├── CustomVisuals/                     # Third-party .pbiviz packages
│   └── StaticResources/
│       ├── SharedResources/BaseThemes/    # Built-in base themes
│       └── RegisteredResources/           # User images, custom theme JSON
└── <Report>.SemanticModel/                # OUT OF SCOPE

关键文件

文件	用途	Agent 规则
.platform	Fabric/PBIP 报告项元数据	将其与 .Report 文件夹放在一起
definition.pbir	通过 byPath 或 byConnection 绑定报告 → 语义模型	除非有意迁移，否则保留架构/版本
version.json	PBIR 格式元数据	保留完整的脚手架文件，包括 $schema
report.json	报告级设置、主题、资源	通过引用进行编辑，并在更改后验证
pages.json	页面顺序和活动页面	将每个新页面添加到 pageOrder；保留 activePageName
page.json	页面元数据、大小、筛选器	除非已获准调整大小，否则保留尺寸
visual.json	视觉对象类型、位置、查询、格式设置	使用 CLI 元数据验证角色和格式设置
localSettings.json	用户本地设置	不要提交或依赖此文件

架构 URL 使用前缀 developer.microsoft.com/json-schemas/fabric/item/report/definition/。 后缀是带版本号的 PBIR 契约，Power BI Desktop 会在大多数版本发布时更新这些契约（例如，撰写本文时的 visualContainer/2.9.0、page/2.1.0、report/3.3.0 — 任何用户的 PBIP 中都可能出现更新的值）。编辑时，始终保留现有的 $schema 值；添加新文件时，从同一报告中相同类型的现有文件复制 $schema URL。不要自行编造或提升版本。使用 powerbi-report-author validate 进行验证。

元数据编写与验证 CLI

需要不可凭猜测的 PBIR 信息时，请使用 powerbi-report-author：包括视觉对象类型、数据角色、格式设置对象、属性名称、枚举值、选择器、表达式／值编码以及报表验证。CLI 是 PBIR 编写细节的事实来源；示例和记忆都不是。

命令	用途	使用时机
catalog list	列出所有内置视觉对象类型（以及任何已弃用的条目）	选择视觉对象类型时
catalog describe <type>	角色、格式设置键、基数	创建／编辑视觉对象前
formatting list-objects <type>	有效的 objects.* 键 + VCO 键；标记需要 id 选择器的对象	应用格式设置前
formatting describe-object <type> <object>	属性名称、类型、枚举值、描述；需要 id 选择器时提供 _selectorHint	查找准确的属性名称和允许值时
formatting describe-property <type> <object> <prop>	查询单个属性的详细信息	已知对象，且只想查询某个属性时
formatting search <type> <regex>	使用正则表达式搜索所有格式设置对象 + VCO	不知道某个属性属于哪个对象时
formatting list-vcos	列举共享的 visualContainerObjects	审查边框／容器格式设置范围时
validate <path>	全面验证 .pbip 或 .Report 目录：JSON Schema、结构、ID、格式设置属性、枚举值、嵌套、布局边界、主题	每批更改后
preview-* <path> [--with-derived]	报表清单：preview-visuals、preview-pages、preview-filters、preview-themes	审查现有报表内容时
--help / <command> --help	命令语法和可用选项	使用不熟悉的命令或标志前

更多命令：powerbi-report-author-cli.md。

验证结果处理

每批逻辑上的 PBIR 编辑完成后，运行 powerbi-report-author validate <path-to-.Report-dir>。

• failed / 非零退出码：在 Desktop 重新加载前修复所有错误。Desktop 可能会拒绝无效的 PBIR，或无法正确渲染。
• succeededWithWarnings：继续之前先检查警告。未知的视觉对象类型或主题视觉对象键通常意味着拼写错误，除非报表有意使用自定义 .pbiviz。
• 诊断信息包含文件路径和 JSON 路径。利用这些信息直接定位出错节点。
• 对于大量诊断信息，使用 --pretty 输出易读结果，或使用 --out <file> 将完整结果写入文件。

视觉对象能力防护规则

将以下内容作为编辑前的安全检查。编辑前，务必使用 powerbi-report-author 确认准确的角色、格式设置对象、属性、枚举值和选择器。

优先使用现代视觉对象类型

切勿创建旧版视觉对象类型。若要修复现有的旧版视觉对象，请迁移到现代类型，并根据 CLI 元数据重新构建角色／格式设置。

请勿创建	替代类型
card	cardVisual
multiRowCard	cardVisual — 多个 KPI 请使用多值 cardVisual（在 Data 中包含多个投影）
table	tableEx
matrix	pivotTable
map、filledMap	azureMap

实例选择器

部分格式设置对象需要 { id: ... } 选择器。运行 formatting list-objects 和 formatting describe-object；遵循 _selectorHint 以及 references/formatting.md 中的双条目模式。

编辑 → 验证 → 重新加载 → 截图循环

对于渲染输出的更改，请遵循此循环。验证、重新加载和截图审查均无问题后，再报告完成。

┌──────────────────────────────────────────────────────────┐
│  1. Edit PBIR files                                      │
│  2. Validate           → errors? fix and go to 1         │
│  3. Desktop status     → choose the correct bridge PID   │
│  4. Desktop reload     → error? fix PBIR and go to 1     │
│  5. Screenshot/review  → issues? fix and go to 1         │
│  6. Clean              → report completion               │
└──────────────────────────────────────────────────────────┘

规则：

• 步骤 2 — powerbi-report-author validate <path-to-.Report-dir>。传入报表定义目录（例如 Sales.Report），而不是 .pbip 文件或项目根目录。重新加载前修复所有错误——无效的 PBIR 错误会在 Desktop 中显示。
• 步骤 3–5 — 使用 powerbi-desktop CLI：先运行 status 选择 PID，然后对 PBIP/PBIR 当前文件使用 reload --pid <pid>，并使用同一 PID 截取屏幕截图。然后按照下文进行截图审查。 运行 status 后，如果选中的实例显示 hasUnsavedChanges: true，请勿立即重新加载；应要求用户保存或放弃其 Desktop UI 更改，重新运行 status，并且只有在该值变为 false 后才继续。 reload 仅处理报表/PBIR 更改。对于语义模型/TMDL 更改，请使用语义模型技能或 Modeling MCP；如果更改未反映出来，请重新打开 PBIP。 例外： 主题 JSON 文件的缓存键基于文件名——Desktop 重新加载时可能不会应用编辑内容。可以为主题文件添加随机后缀并更新 report.json，也可以关闭并重新打开 Desktop。

Desktop CLI 命令：

命令	用途	使用时机
open "<path.pbip>"	为 PBIP/PBIX 启动 Power BI Desktop	启动 Desktop 或打开目标报表时
status	列出 Desktop Bridge 实例、当前文件、报表目录和 Bridge 状态	重新加载/截屏前；选择正确的 PID
reload --pid <pid>	重新加载所选 Desktop 实例当前的 PBIP 报表文件	在已打开的 PBIP 中完成 PBIR 编辑验证后
screenshot <page-id> --pid <pid> --output <file>	按 PBIR 页面 ID 截取一个页面	仅更改单个页面时
screenshot-all --pid <pid> --output-dir <dir>	截取报表的所有页面	更改主题、导航、页面顺序或整个报表时

仅当需要审查单个 PBIR 页面时，才使用 powerbi-desktop screenshot <page-id> --pid <pid>。reload 仅支持基于 PBIP 的报表。powerbi-desktop 命令均不接受 --report；请使用 status，通过 PID 选择 Desktop 实例，因为同一个 PBIP 可能在多个进程中打开。截图默认缩放比例为 2。针对每个 PID，必须按顺序运行重新加载和截图操作——绝不可针对同一 PID 并行运行，即使是为了绕过缓慢或可重试的错误。请阅读 references/powerbi-desktop.md，了解完整的命令参考和故障排查工作流。

常见的 Desktop CLI 结果：

输出/错误	含义	操作
"status": "not_connected"	无法发现 Desktop Bridge	运行 powerbi-desktop open "<path.pbip>"，或请用户启动 Desktop。如果仍然无法连接，请让用户启用 Desktop 预览功能——参见文档
AMBIGUOUS_DESKTOP_INSTANCE	存在多个可用的 Desktop Bridge 实例	运行 powerbi-desktop status，选择目标 PID，然后使用 --pid 重试
METHOD_NOT_AVAILABLE	Desktop 版本缺少必需的生产环境桥接方法	告知用户 Desktop 版本过旧或不受支持——参见文档
HostNotReady / 可重试的桥接错误	Desktop 已启动，但报表主机尚未就绪（通常在重新加载后短暂出现）	CLI 会自动重试；如果仍出现此错误，再运行一次。不要添加自定义等待时间——依靠 CLI 的重试机制。
Timeout（桥接错误）	重新加载或截图超出 CLI 的重试时限	确认 status 显示 bridgeStatus: "connected"，然后再运行一次。如果 Timeout 持续出现，请增加等待时限（例如 reload --pid <pid> --wait-seconds 120）。如果 bridgeStatus: "error" 或 status 卡住，请询问用户是否有 Desktop 模态对话框阻止输入。
截图/重新加载期间出现 Cancelled	重新加载/截图已取消——通常是同一 PID 上有并发的重新加载/截图。与 Timeout（操作耗时过长）不同。	对每个 PID，依次运行重新加载和截图。通过 status 等待状态变为 connected，然后逐个重试。
ReportDefinitionValidationFailed	Desktop 拒绝了 PBIR 定义	修复 PBIR，运行 powerbi-report-author validate <path>，然后再次重新加载
REPORT_DIR_REQUIRED	所选 PID 没有 PBIP/PBIR 当前文件；reload/screenshot-all 需要 PBIP/PBIR 状态	从 status 中选择正确的 PID，或打开目标 PBIP

截图检查

截图完成后，在报告完成之前，独立检查渲染输出。阅读 screenshot-review.md，检查布局、数据渲染、格式/主题、切片器和常见的截图失败情况，然后修复 PBIR 并重复此流程，直到没有问题。

---

验证

每完成一批逻辑相关的 PBIR 更改后，都运行 powerbi-report-author validate <path>。优先使用 .Report 目录；CLI 也接受 .pbip 文件或包含单个 .Report 目录的项目根目录。错误会阻止 Desktop 重新加载——请先修复。检查警告，除非有明确理由，否则也应修复。

验证器是一项离线预检，涵盖 PBIR 结构、JSON/架构有效性、跨文件引用、ID/名称、可视化类型、角色绑定、筛选器、格式对象/属性/枚举/选择器、visualContainerObjects、主题注册、布局边界，以及选定的 Desktop/渲染失败模式。它不能取代 Desktop 重新加载和截图检查。

---

反模式与注意事项

易犯错误	后果	修复方法
在筛选器 Where 条件中使用 "Entity"	筛选器会静默失效	使用 "Source"，并搭配 From 中的别名
省略 nativeQueryRef	可视化计算可能会出错	始终包含 nativeQueryRef
重复使用可视化项或筛选器名称	行为不可预测	生成唯一 ID
将 visualType 设置为无效字符串	可视化项会渲染为错误框	运行 powerbi-report-author catalog describe <type> 或 powerbi-report-author catalog list
为可视化类型使用错误的角色名称	字段会被忽略；可视化项为空白	使用 powerbi-report-author catalog describe <type> 中的角色名称
混用 Column 和 Measure 类型	查询失败；可视化项出错	列使用 Column，度量值使用 Measure
忘记将页面添加到 pages.json	页面不可见	将页面添加到 pageOrder 数组
布尔值未使用正确格式	类型错误	"true" / "false"（不带后缀，且在 Value 中不加引号）
数字未添加类型后缀	类型不匹配	小数使用 D，整数使用 L
编辑 $schema 版本	PBI Desktop 可能会拒绝	保留现有版本
在 paragraphs 中使用字符串化的 JSON	文本框不显示内容	paragraphs 是原生 JSON 数组
将文本框用作细线/分隔线	无论 height 设置为何值，渲染高度都约为 24 px	改用 shape 可视化项（矩形）——形状支持较小尺寸
将 visualContainerObjects 作为 visual 的同级项	PBI Desktop 中的架构验证错误	必须将其放在 visual 对象内部，与 objects 同级
对维度列和度量值都放在 Values 中的 tableEx	标题会渲染，但没有数据行，即使 DAX 确认数据存在	使用 pivotTable；将维度放在 Rows 中，将度量值放在 Values 中
使用 PowerShell ConvertTo-Json 编辑可视化 JSON	属性顺序会改变，嵌套层级会被截断（-Depth 默认为 2）	使用 Node.js 操作 JSON，或始终传入 -Depth 20 并验证结构
使用正则表达式或字符串替换修改 JSON 文件	嵌套结构会损坏——属性可能落入同级值内部，花括号也会错位	读取文件 → JSON.parse → 修改对象 → JSON.stringify → 写回。或者使用 edit 工具进行精确的旧/新字符串匹配
在单系列图表中使用不带选择器的 dataPoint.fill	即使工具提示中有数据，条形/柱形也不可见	无选择器时，使用 dataPoint.defaultColor 设置基色；fill 必须搭配 metadata 选择器
在多系列图表中使用 dataPoint.defaultColor	所有系列/类别都使用同一种颜色——没有视觉区分	使用主题 dataColors，让不同可视化项采用一致的调色板；或使用带 metadata 选择器的 dataPoint.fill 覆盖各系列颜色——参见 color-strategy.md § Color Strategy Quick Reference
簇状条形图/柱形图的颜色合并成图例中的单一颜色	可视化项有 Series 角色，但所有条形和图例标记都显示为相同色调	使用各系列的 dataPoint.fill 选择器或主题 dataColors 调色板；不要在簇状图表中使用 defaultColor
仅依赖主题 dataColors 保持跨可视化项的度量值颜色一致	同一度量值在不同可视化项中会使用不同颜色（基于索引的分配会随投影顺序而变化）	维护度量值→颜色映射，并为每个可视化项应用显式的 dataPoint.fill/defaultColor——参见 color-strategy.md § Cross-Visual Measure-Color Consistency
使用 ThemeDataColor 为带 metadata 选择器的 dataPoint.fill 显式设置各度量值颜色	颜色会静默地解析为白色或黑色，而非预期的调色板颜色	使用 Literal 十六进制值，通过 metadata 选择器显式分配颜色——在此场景中，ThemeDataColor 不可靠
选择条形/系列颜色时未检查背景对比度	条形或线条与页面/卡片背景形成颜色冲突，无法看见（例如，白色画布上的白色条形）	始终选择饱和度较高的中深色调，确保与页面和 VCO 背景颜色形成对比
在页面级 background 中使用 show 属性	架构错误——页面 background 仅支持 color、image、transparency	只有 VCO background（位于可视化项上）才有 show；页面背景始终可见
复制文档示例中的属性名称，但未核实	出现警告或静默失败——不同可视化类型的属性名称可能不同	始终运行 powerbi-report-author formatting describe-object <type> <object> 获取准确的属性名称
猜测属性属于哪个对象	逐个检查错误对象，浪费调用次数	运行 powerbi-report-author formatting search <type> <regex>，一次搜索所有对象
格式设置属性不起作用（没有错误）	在 cardVisual 轮廓上设置 show: false 却没有 ID 选择器——验证通过，但渲染结果不变	使用 powerbi-report-author formatting describe-object <type> <object> 检查 _selectorHint；采用双条目模式（静态条目 + ID 选择器条目）
在单值卡片上使用 cardCalloutArea	属性验证通过，但没有可见效果——cardCalloutArea 仅在多值卡片上渲染（Data 中有 2 个或更多度量值）	对单值卡片，使用带 { id: "default" } 选择器的 outline/accentBar/fillCustom。对多值卡片，cardCalloutArea 控制每个重点值磁贴的样式——参见 card.md § Multi-Value Formatting
将 "Fields" 用作 cardVisual 的 queryState 角色	卡片渲染为空——PBI Desktop 无法解析绑定。验证器会报告 Unknown role "Fields" 和 Required role "Data" missing	cardVisual 唯一的数据角色是 "Data"。"Fields" 是旧版 card 可视化项的角色名称——切勿照搬。始终使用 powerbi-report-author catalog describe cardVisual 核实角色名称——参见 card.md § Single-Value Template
为多个相关 KPI 创建多个独立的单值 cardVisual 实例	浪费画布空间，也不符合此可视化类型的用途——cardVisual 原生支持在一个磁贴中使用多个投影	请求包含 2 个或更多相关 KPI 时，默认使用一个多值 cardVisual，将所有度量值作为 Data 投影。仅当各卡片需要不同样式时，才使用多个卡片——参见 card.md § When to Consolidate vs. Keep Separate
向按钮切片器的 Values 或 Label 角色添加多个字段	切片器会出错或显示意外结果——每个角色只接受 1 个字段	Values 中放 1 个字段，Label 中放 1 个字段；其他字段放入 Tooltips
查看其他可视化项中的 filterConfig，以了解切片器选择状态	切片器选择状态仅存储在切片器自身的 visual.json 中，通过 expansionStates + objects.general.filter 表示。修改切片器时，务必先阅读 references/slicers.md
创建图像可视化项前未询问源类型	可视化结构错误——URL、本地文件和数据字段各自有不同的架构和表达式类型	创建可视化项前，务必询问用户图像来源（本地文件 / URL / 数据字段）——参见 image.md § Source Types Overview
创建数据绑定图像可视化项时，所用字段缺少 dataCategory: ImageUrl	可视化项显示为空白或报错	先警告用户——没有 dataCategory: ImageUrl 时，可视化项将显示为空白。提供其他 ImageUrl 字段、本地文件、URL 等替代方案，并在创建前确认——参见 image.md § Select from data
将背景图像放在页面画布上，而不是可视化项绘图区	用户在特定可视化项的背景中请求“背景图像”（例如“带背景图像的柱形图”），但图像被放在 page.json → objects.background，而不是 visual.objects.plotArea	如果用户在特定可视化项的场景中请求背景图像，默认使用 plotArea.image。只有用户明确说“页面背景”/“画布背景”，或没有可视化项上下文时，才使用页面级 background.image——参见 image.md § Plot Area Background Image
创建 multiRowCard 可视化项	旧版多行卡片——已弃用；powerbi-report-author validate 会发出 PBIR_VISUAL_TYPE_DEPRECATED 警告。用户使用“多卡片”“每个指标一张卡片”或“每个度量值一张卡片”等说法时，往往会触发此问题	始终使用 cardVisual。对于多个 KPI，使用一个多值 cardVisual，将所有度量值作为投影放在 Data 角色中——参见 card.md
地图可视化项使用 map 或 filledMap，而不是 azureMap	旧版 Bing Maps 可视化项——已弃用，且不得创建；powerbi-report-author validate 会发出 PBIR_VISUAL_TYPE_DEPRECATED 警告	始终使用 azureMap——参见 map.md。如果地图无法渲染或进行地理编码，请调试字段、尝试其他地理列/坐标，或询问用户——未先征求用户意见，不得静默改用非地图可视化项
创建 tableEx/pivotTable 时未设置 columnAdjustment: growToFit	列宽会缩至内容所需的大小，留下未使用的空白	始终将 columnHeaders.columnAdjustment 设为 growToFit，并将 autoSizeColumnWidth 设为 true——参见 table.md
自定义表格/矩阵行颜色不起作用（背景为白色）	默认样式预设会覆盖 objects 级别的 backColorPrimary/backColorSecondary	对每个使用自定义颜色的 tableEx/pivotTable，将 VCO 的 stylePreset 设为 'None'——参见 table.md § Style Presets
VCO 背景为深色，但表格单元格仍为白色	visualContainerObjects.background 只控制外部容器——表格单元格绘制在其上方	在 objects.values.backColorPrimary/Secondary 和 objects.columnHeaders.backColor 中设置深色，而不是在 VCO 中设置——参见 re-theming.md § Dark Mode Checklist
已应用深色主题，但卡片/表格/切片器仍为白色	深色模式会同时触发所有格式设置陷阱	按照完整的 re-theming.md § Dark Mode Authoring Checklist 操作——其中涵盖 stylePreset、fillCustom + ID 选择器、objects 与 VCO 的区别，以及对比度检查
重新加载 Desktop 后，主题 JSON 更改未生效	Desktop 会按文件名缓存主题文件	为主题 JSON 文件名添加短随机后缀，更新 report.json 中的主题注册，然后重新加载；或者关闭并重新打开 Desktop
将 sortDefinition 放在 visual 内部或 visual.json 根目录中	架构验证错误；排序会被静默忽略——图表会退回按字母顺序排序	sortDefinition 是 query 的属性——使用 visual.query.sortDefinition。自 visualConfiguration/2.2.0 起受支持
容器形状的填充色与参考图不符	文本不可见或背景颜色错误	让填充色和透明度与参考图一致。如果页面背景已经提供所需颜色，则完全省略形状。如果形状必须不可见，请确认文本颜色仍与页面画布形成对比——参见 shape.md § Container Shapes
重新设置主题后，形状文本不可见	形状的 text 对象没有显式 fontColor——文本会继承主题前景色，但如果浅色页面画布上的 fill 也是浅色（例如白色胶囊/按钮），继承的深色前景色可能无法渲染，或者填充色与画布融为一体，导致文本消失	始终在形状的 text 对象中显式设置 fontColor（放在 { selector: { id: "default" } } 条目中）。重新设置主题时，检查所有 text.show: true 的形状——批量替换十六进制值会遗漏需要新增 fontColor 属性的形状
对含零值或负值的数据启用 logAxisScale	PBI Desktop 会静默退回线性刻度并发出警告——零或负数的对数无定义	应用前先警告用户。使用 ask_user 提供替代方案（筛除负值、更换度量值、使用 labelDisplayUnits）。只有在用户处理完负值，或确认所有绑定值均为正数后，才应用 logAxisScale: true——参见 cartesian.md § Log Scale
更换主题时未全面检查内联覆盖项	形状、页面背景、导航按钮、文本框仍保留旧颜色——仅更改主题对级联中优先级为 2 的硬编码 Literal 十六进制值不起作用	报表有逐可视化项颜色覆盖时，按照 re-theming.md § Re-theming Workflow 的步骤 0–3 操作：创建颜色映射、更新主题 JSON，然后在重新加载前批量检查 definition/ 文件中的旧十六进制值
只更改主题中的 dataColors，但未全面检查	形状、强调栏、导航按钮边框仍保留旧强调色——这些元素使用旧 dataColors 数组中的硬编码 Literal 十六进制值，而非 ThemeDataColor 引用	在 definition/ 文件中检查 ALL 旧 dataColors[N] 十六进制值。即使只是请求更改同类颜色或“只更改强调色/数据颜色”，也必须进行全面检查——形状和导航元素通常会将 dataColors[0] 硬编码为强调色填充/轮廓。

官方文档

有关 Microsoft Learn 设置指南、支持限制和功能可用性，请参阅 Power BI 报表创作文档。