powerbi-report-authoring

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

CRITICAL NOTES

To find the workspace details (including its ID) from workspace name: list all workspaces and, then, use JMESPath filtering

To find the item details (including its ID) from workspace ID, item type, and item name: list all items of that type in that workspace and, then, use JMESPath filtering

重要注意事项

从工作区名称查找工作区详情（包括其ID）：列出所有工作区，然后使用JMESPath筛选

从工作区ID、项类型和项名称查找项详情（包括其ID）：列出该工作区中该类型的所有项，然后使用JMESPath筛选

Power BI Report Authoring Skill (PBIR/PBIP Format)

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

This skill enables reading, editing, and creation of Power BI report definition files in the PBIR (Power BI Report) format used by PBIP (Power BI Project) files.

本技能支持读取、编辑和创建PBIR（Power BI报表）格式的Power BI报表定义文件，该格式为PBIP（Power BI项目）文件所使用。

Must/Prefer/Avoid

必须/推荐/避免

MUST

必须

Use this skill only for concrete PBIR/PBIP report-file mechanics such as pages, visuals, filters, slicers, navigation, bookmarks, themes, formatting, validation, Desktop reloads, and screenshots.
Validate PBIR with
```
powerbi-report-author validate
```
after each logical batch.
Use
```
powerbi-desktop
```
reload/screenshot workflows for rendered-output changes.
Use CLI capability lookup before writing visual roles, formatting objects, enum values, selectors, or expression encodings.

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

PREFER

AVOID

避免

Do not guess PBIR JSON from memory when CLI metadata or reference files are available.
Do not use only this skill for open-ended design, report planning, or Fabric report item CRUD; pair it with
```
powerbi-report-design
```
,
```
powerbi-report-planning
```
, or
```
powerbi-report-management
```
.

当CLI元数据或参考文件可用时，不要凭记忆猜测PBIR JSON结构。
不要仅使用本技能进行开放式设计、报表规划或Fabric报表项CRUD操作；需搭配
```
powerbi-report-design
```
、
```
powerbi-report-planning
```
或
```
powerbi-report-management
```
使用。

Quick Start Workflow

快速开始流程

Plan/design routing → for greenfield builds, read
```
powerbi-report-planning
```
first; for theming, visual style, layout, redesigns, or critiques, read
```
powerbi-report-design
```
. Return here for PBIR mechanics. Before authoring, use the
```
Design Brief:
```
yaml block from
```
_brief/report-spec.md
```
(or an approved inline
```
Design Brief:
```
block in the conversation) as implementation context.
Set up/update CLIs → before first use, confirm
```
powerbi-report-author
```
and the global
```
powerbi-desktop
```
command are available; see CLI Setup.
Understand the model → use the Semantic Model MCP Server/skill if available, or read TMDL files directly for table/column/measure names
Desktop context → for live Desktop status, opening PBIP/PBIX files, reloads, screenshots, or visual verification, use the
```
powerbi-desktop
```
CLI from
```
@microsoft/powerbi-desktop-bridge-cli
```
; see Edit → Validate → Reload → Screenshot Loop.
Route by intent → use Topic Files and Examples to pick the relevant guide.
Use CLI metadata → use Authoring Metadata & Validation CLI for exact visual roles, formatting objects, property names, enum values, and selector requirements; do not infer these from memory.
Check common pitfalls → read Anti-Patterns and Pitfalls before editing or validating when the change touches visuals, bindings, filters, formatting, layout, or Desktop rendering.
Validate → run
```
powerbi-report-author validate <path-to-.Report-dir>
```
after every logical batch of PBIR changes; see Validation.
Verify rendering → for any rendered-output change, use
```
powerbi-desktop
```
reload + screenshots; see Edit → Validate → Reload → Screenshot Loop and Screenshot Review. Do not proceed until both validation and visual review pass. For dashboard/report builds, page scaffolding is not completion — each requested page needs data-bound visuals.
Report back → give the user a concise summary of what was done and any issues encountered (major and minor).

规划/设计路由 → 从零开始构建报表时，先阅读
```
powerbi-report-planning
```
；涉及主题、可视化样式、布局、重新设计或评审时，阅读
```
powerbi-report-design
```
。返回此处进行PBIR具体操作。创作前，将
```
_brief/report-spec.md
```
中的
```
Design Brief:
```
yaml块（或对话中已获批的内嵌
```
Design Brief:
```
块）作为实现上下文。
设置/更新CLI → 首次使用前，确认
```
powerbi-report-author
```
和全局
```
powerbi-desktop
```
命令可用；请查看CLI设置。
理解模型 → 若可用则使用语义模型MCP服务器/技能，或直接读取TMDL文件获取表/列/度量值名称
Desktop上下文 → 如需实时Desktop状态、打开PBIP/PBIX文件、重载、截图或可视化验证，请使用
```
@microsoft/powerbi-desktop-bridge-cli
```
中的
```
powerbi-desktop
```
CLI；请查看编辑 → 验证 → 重载 → 截图循环。
按意图路由 → 使用主题文件与示例选择相关指南。
使用CLI元数据 → 使用创作元数据与验证CLI获取准确的可视化角色、格式对象、属性名称、枚举值和选择器要求；不要凭记忆推断这些内容。
检查常见陷阱 → 当更改涉及可视化组件、绑定、筛选器、格式设置、布局或Desktop渲染时，在编辑或验证前阅读反模式与陷阱。
验证 → 完成每一批次PBIR逻辑修改后，运行
```
powerbi-report-author validate <path-to-.Report-dir>
```
；请查看验证。
确认渲染效果 → 对于任何渲染输出更改，使用
```
powerbi-desktop
```
重载+截图；请查看编辑 → 验证 → 重载 → 截图循环和截图评审。必须在验证和可视化评审均通过后才能继续。对于仪表板/报表构建，页面框架搭建完成并不代表结束——每个请求的页面都需要绑定数据的可视化组件。
反馈结果 → 向用户简要总结已完成的操作以及遇到的所有问题（包括主要和次要问题）。

Topic Files and Examples

主题文件与示例

Use the user's intent to choose the relevant topic file(s) before editing:

File	When to read
`authoring.md`	Adding/modifying pages, visuals, drillthrough, interactions — includes complete JSON examples
`powerbi-desktop.md`	Live Desktop verification — `powerbi-desktop` commands, PID selection, reload, screenshots, errors, troubleshooting
`screenshot-review.md`	Screenshot review checklist and rendered-output troubleshooting after Desktop screenshot capture
`formatting-overview.md`	Read first for appearance changes — cascade model, encoding rules, selectors, routing to other formatting files
`formatting.md`	Editing `visual.json` appearance — selectors, VCOs, encoding mechanics, background-image routing, cascade
`color-strategy.md`	Chart data point colors — theme `dataColors` vs `dataPoint.defaultColor` vs `dataPoint.fill` with selectors, cross-visual measure-color consistency
`conditional-formatting.md`	Data-driven formatting — color gradients (FillRule), rules-based, icon sets, data bars, web URL, field value
`page-formatting.md`	Editing `page.json` appearance — canvas background, wallpaper, page background images
`filter-pane.md`	Filter pane ( `outspacePane` ) and filter card ( `filterCard` ) chrome — Applied/Available state styling, pane width, search/checkbox colors
`theming.md`	Creating or editing `theme.json` — dataColors, textClasses, visualStyles, style presets, ThemeDataColor reference
`re-theming.md`	Switching themes on a report with existing visuals — re-theming workflow (color mapping + bulk sweep), dark mode checklist, dark↔light polarity changes. Pair with `theming.md` when changing colors on a report with per-visual overrides.
`expressions.md`	Building field references (Column, Measure, Aggregation, Hierarchy) and sort definitions
`filters.md`	Adding/modifying filters — includes complete JSON examples
`slicers.md`	Read first when adding/modifying slicers or slicer selections — agent workflow, JSON templates, selection config
`cartesian.md`	Adding bar, column, line charts — families, roles, query patterns (multi-measure, drill hierarchy, date hierarchy), formatting
`map.md`	Adding map visuals — template, roles, geocoding workflow, handling render failures
`card.md`	Adding or formatting KPI/card visuals — `cardVisual` , id selectors, callout/value sizing, accent bars
`table.md`	Adding or formatting tables/matrices — `tableEx` , `pivotTable` , grow-to-fit columns, row banding
`image.md`	Adding image visuals — local resources, URLs, data-bound images, ImageUrl validation/refusal workflow; also plot area background images for chart visuals
`shape.md`	Adding shape visuals — containers, dividers, backgrounds, reference-image matching
`textbox.md`	Adding static or dynamic textbox visuals — paragraphs, text runs, and bound value expressions
`version-control.md`	Git branching, committing, reverting — read when the task involves version control or safe rollback planning

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

文件	阅读场景
`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` vs `dataPoint.defaultColor` vs 带选择器的 `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`	构建字段引用（列、度量值、聚合、层次结构）和排序定义
`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分支、提交、回滚——当任务涉及版本控制或安全回滚规划时阅读

Greenfield / Design Handoff

从零开始构建 / 设计交接

This skill owns PBIR file mechanics once the work is concrete: page/visual JSON, bindings, filters, slicers, themes, formatting, navigation, bookmarks, validation, Desktop reloads, and screenshots.
Use
powerbi-report-planning
before authoring for new report/dashboard requests, requirements gathering, dependency checks, approval, or end-to-end build sequencing. Use
powerbi-report-design
for open-ended visual design, redesign/restyle, brand/theme direction, chart selection, or layout critique. Return here once there is an approved spec/design brief or a concrete PBIR edit to implement — see Quick Start step 0 for how to consume the brief.

一旦工作内容明确，本技能负责PBIR文件的具体操作：页面/可视化组件JSON、绑定、筛选器、切片器、主题、格式设置、导航、书签、验证、Desktop重载和截图。
对于新报表/仪表板请求、需求收集、依赖项检查、审批或端到端构建排序，请在创作前使用
powerbi-report-planning
。对于开放式可视化设计、重新设计/重新样式、品牌/主题方向、图表选择或布局评审，请使用
powerbi-report-design
。当有已获批的规范/设计brief或具体的PBIR编辑任务时，返回此处——请查看快速开始步骤0了解如何使用brief。

Large Build Execution

大型报表构建执行

For full report/PBIP builds, do not delegate complete PBIP generation to a subagent — the owning agent must keep the design brief, model inventory, cross-page consistency, validation loop, and Desktop verification coordinated.

When context or repetition is the constraint, prefer a deterministic Node.js generator that reads the approved design brief and writes PBIR JSON. If delegation is still useful, split it by page or visual family and give each subagent the relevant brief excerpt, exact fields/measures, and layout/visual contract; have it return scoped PBIR JSON or a patch for the owning agent to integrate and validate.

对于完整报表/PBIP构建，不要将完整PBIP生成任务委托给子Agent——主Agent必须协调设计brief、模型清单、跨页面一致性、验证循环和Desktop验证。

当上下文或重复操作成为限制因素时，建议使用确定性Node.js生成器，读取已获批的设计brief并编写PBIR JSON。若仍需委托，请按页面或可视化组件系列拆分任务，为每个子Agent提供相关brief摘录、准确字段/度量值和布局/可视化组件约定；让子Agent返回限定范围的PBIR JSON或补丁，由主Agent整合并验证。

CLI Setup

CLI设置

Prerequisite: Node.js 20 or later. Check with

node --version

. If missing or older, install from nodejs.org or via your package manager — Windows:

winget install OpenJS.NodeJS.LTS

; macOS:

brew install node

; Linux: distro package or nodesource.

Before using the CLIs in a session, ensure the latest global versions are installed:

bash

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

Confirm both are on

PATH

bash

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

前提条件：Node.js 20或更高版本。 使用

node --version

检查。若未安装或版本过低，请从nodejs.org或包管理器安装——Windows：

winget install OpenJS.NodeJS.LTS

；macOS：

brew install node

；Linux：发行版包或nodesource。

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

bash

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

确认两者均在

PATH

中：

bash

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

PBIR File Layout

PBIR文件布局

A PBIP project on disk looks like this:

text

<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

磁盘上的PBIP项目结构如下：

text

<Report>.pbip                              # 项目清单
├── <Report>.Report/
│   ├── .platform                          # Fabric元数据（类型、logicalId）
│   ├── definition.pbir                    # 报表 → 语义模型绑定
│   ├── definition/
│   │   ├── version.json                   # 格式版本（例如 "2.0.0"）
│   │   ├── report.json                    # 报表级：主题、设置、资源
│   │   └── pages/
│   │       ├── pages.json                 # 页面顺序 + 活动页面名称
│   │       └── <pageId>/
│   │           ├── page.json              # 页面：displayName、尺寸、类型、筛选器
│   │           └── visuals/
│   │               └── <visualId>/
│   │                   └── visual.json    # 可视化组件：类型、位置、查询、格式设置
│   ├── CustomVisuals/                     # 第三方.pbiviz包
│   └── StaticResources/
│       ├── SharedResources/BaseThemes/    # 内置基础主题
│       └── RegisteredResources/           # 用户图片、自定义主题JSON
└── <Report>.SemanticModel/                # 超出范围

Key Files

关键文件

File	Purpose	Agent rule
`.platform`	Fabric/PBIP report item metadata	Keep it with the `.Report` folder
`definition.pbir`	Report → semantic model binding via `byPath` or `byConnection`	Preserve schema/version unless intentionally migrating
`version.json`	PBIR format metadata	Preserve the full scaffolded file, including `$schema`
`report.json`	Report-level settings, themes, resources	Edit through references and validate after changes
`pages.json`	Page order and active page	Add every new page to `pageOrder` ; preserve `activePageName`
`page.json`	Page metadata, size, filters	Preserve dimensions unless resizing is approved
`visual.json`	Visual type, position, query, formatting	Validate roles and formatting with CLI metadata
`localSettings.json`	User-local settings	Do not commit or rely on it

Schema URLs use the prefix

developer.microsoft.com/json-schemas/fabric/item/report/definition/

. The suffixes are versioned PBIR contracts that Power BI Desktop bumps with most releases (e.g.

visualContainer/2.9.0

page/2.1.0

report/3.3.0

at the time of writing — newer values may appear in any user's PBIP). When editing, always preserve the existing
$schema
value; when adding a new file, copy the

$schema

URL from an existing file of the same type in the same report. Do not invent or bump versions on your own. Validate with

powerbi-report-author validate

文件	用途	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

进行验证。

Authoring Metadata & Validation CLI

创作元数据与验证CLI

Use

powerbi-report-author

whenever you need PBIR facts that should not be guessed: visual types, data roles, formatting objects, property names, enum values, selectors, expression/value encodings, and report validation. The CLI is the source of truth for PBIR authoring details; examples and memory are not.

Command	Purpose	When to use
`catalog list`	List all built-in visual types (and any deprecated entries)	Choosing a visual type
`catalog describe <type>`	Roles, formatting keys, cardinality	Before creating/editing a visual
`formatting list-objects <type>`	Valid `objects.*` keys + VCO keys; flags objects needing id selectors	Before applying formatting
`formatting describe-object <type> <object>`	Property names, types, enum values, descriptions; `_selectorHint` when id selector required	Finding exact property names and allowed values
`formatting describe-property <type> <object> <prop>`	Focused single-property lookup	When you already know the object and want just one property
`formatting search <type> <regex>`	Regex search across all formatting objects + VCOs	When you don't know which object a property belongs to
`formatting list-vcos`	Enumerate shared visualContainerObjects	Auditing chrome/container formatting surface
`validate <path>`	Full validation of a `.pbip` or `.Report` directory: JSON Schema, structure, IDs, formatting properties, enum values, nesting, layout bounds, theme	After every batch of changes
`preview-* <path> [--with-derived]`	Report inventory: `preview-visuals` , `preview-pages` , `preview-filters` , `preview-themes`	Auditing existing report content
`--help` / `<command> --help`	Command syntax and available options	Before using an unfamiliar command or flag

More commands:

powerbi-report-author-cli.md

当需要不应猜测的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	审核Chrome/容器格式设置范围时
`validate <path>`	对 `.pbip` 或 `.Report` 目录进行完整验证：JSON架构、结构、ID、格式属性、枚举值、嵌套、布局边界、主题	每批次更改后
`preview-* <path> [--with-derived]`	报表清单： `preview-visuals` 、 `preview-pages` 、 `preview-filters` 、 `preview-themes`	审核现有报表内容时
`--help` / `<command> --help`	命令语法和可用选项	使用不熟悉的命令或标志前

更多命令：

powerbi-report-author-cli.md

。

Validation result handling

验证结果处理

Run

powerbi-report-author validate <path-to-.Report-dir>

after every logical batch of PBIR edits.

```
failed
```
/ non-zero exit: fix every error before Desktop reload. Desktop may reject or misrender invalid PBIR.
```
succeededWithWarnings
```
: review warnings before proceeding. Unknown visual types or theme visual keys usually mean a typo unless the report intentionally uses a custom
```
.pbiviz
```
.
Diagnostics include file paths and JSON paths. Use them to jump directly to the broken node.
For large diagnostics, use
```
--pretty
```
for readable output or
```
--out <file>
```
to write the full result to a file.

完成每一批次PBIR编辑后，运行

powerbi-report-author validate <path-to-.Report-dir>

。

```
failed
```
/ 非零退出码：在Desktop重载前修复所有错误。Desktop可能会拒绝或错误渲染无效的PBIR。
```
succeededWithWarnings
```
：继续前查看警告。未知可视化类型或主题可视化键通常表示输入错误，除非报表有意使用自定义
```
.pbiviz
```
。
诊断信息包含文件路径和JSON路径。使用这些信息直接跳转到出错节点。
对于大量诊断信息，使用
```
--pretty
```
获取可读输出，或使用
```
--out <file>
```
将完整结果写入文件。

Visual Capability Guardrails

可视化组件能力约束

Use these as pre-edit safety rails. Always confirm exact roles, formatting objects, properties, enum values, and selectors with

powerbi-report-author

before editing.

将这些作为编辑前的安全准则。编辑前始终使用

powerbi-report-author

确认准确的角色、格式对象、属性、枚举值和选择器。

Prefer modern visual types

优先使用现代可视化类型

Never create legacy visual types. If repairing an existing legacy visual, migrate to the modern type and rebuild roles/formatting from CLI metadata.

Do not create	Use instead
`card`	`cardVisual`
`multiRowCard`	`cardVisual` — use multi-value `cardVisual` (multiple projections in `Data` ) for multiple KPIs
`table`	`tableEx`
`matrix`	`pivotTable`
`map` , `filledMap`	`azureMap`

永远不要创建旧版可视化类型。若修复现有旧版可视化组件，请迁移到现代类型并根据CLI元数据重新构建角色/格式设置。

不要创建	替代方案
`card`	`cardVisual`
`multiRowCard`	`cardVisual` —— 使用多值 `cardVisual` （ `Data` 中的多个投影）实现多个KPI
`table`	`tableEx`
`matrix`	`pivotTable`
`map` , `filledMap`	`azureMap`

Instance Selectors

实例选择器

Some formatting objects need

{ id: ... }

selectors. Run

formatting list-objects

and

formatting describe-object

; follow

_selectorHint

and the dual-entry pattern in

references/formatting.md

某些格式对象需要

{ id: ... }

选择器。运行

formatting list-objects

和

formatting describe-object

；遵循

_selectorHint

和

references/formatting.md

中的双条目模式。

Edit → Validate → Reload → Screenshot Loop

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

For rendered-output changes, follow this loop. Do not report completion until validation, reload, and screenshot review are clean.

text

┌──────────────────────────────────────────────────────────┐
│  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               │
└──────────────────────────────────────────────────────────┘

Rules:

Step 2 —
```
powerbi-report-author validate <path-to-.Report-dir>
```
. Pass the report definition directory (e.g.,
```
Sales.Report
```
), not the
```
.pbip
```
file or project root. Fix all errors before reload — invalid PBIR errors will surface in Desktop.
Steps 3–5 — use
```
powerbi-desktop
```
CLI:
```
status
```
to choose the PID, then
```
reload --pid <pid>
```
for PBIP/PBIR current files and screenshots from the same PID. Then perform the screenshot review below. After
```
status
```
, if the selected instance has
```
hasUnsavedChanges: true
```
, do not reload yet; ask the user to save or discard their Desktop UI changes, rerun
```
status
```
, and continue only once it is false.
```
reload
```
covers report/PBIR changes only. For semantic-model/TMDL changes, use a semantic-model skill or Modeling MCP and reopen the PBIP if changes are not reflected. Exception: Theme JSON files are cache-keyed by name — Desktop may not pick up edits on reload. Either rename the theme file with a random suffix (and update
```
report.json
```
), or close and reopen Desktop.

Desktop CLI commands:

Command	Purpose	When to use
`open "<path.pbip>"`	Launch Power BI Desktop for a PBIP/PBIX	Starting Desktop or opening the target report
`status`	List Desktop Bridge instances, current files, report dirs, and bridge state	Before reload/screenshot; choose the correct PID
`reload --pid <pid>`	Reload the selected Desktop instance's current PBIP report files	After validated PBIR edits in an open PBIP
`screenshot <page-id> --pid <pid> --output <file>`	Capture one page by PBIR page ID	Isolated page changes
`screenshot-all --pid <pid> --output-dir <dir>`	Capture every report page	Theme, navigation, page-order, or report-wide changes

Use

powerbi-desktop screenshot <page-id> --pid <pid>

when only one PBIR page needs review.

reload

is supported only for PBIP-backed reports. No

powerbi-desktop

command accepts

--report

; use

status

to select the Desktop instance by PID because the same PBIP can be open in more than one process. Screenshots default to scale

. Run reload and screenshot operations serially per PID — never in parallel against the same PID, even as a workaround for a slow or retryable error. Read

references/powerbi-desktop.md

for the complete command reference and troubleshooting workflow.

Common Desktop CLI outcomes:

Output/error	Meaning	Action
`"status": "not_connected"`	No Desktop Bridge discoverable	Run `powerbi-desktop open "<path.pbip>"` or ask the user to start Desktop. If still unreachable, ask them to enable the Desktop preview feature — see docs
`AMBIGUOUS_DESKTOP_INSTANCE`	More than one Desktop Bridge instance is available	Run `powerbi-desktop status` , choose the intended PID, retry with `--pid`
`METHOD_NOT_AVAILABLE`	Desktop build lacks a required production bridge method	Tell the user Desktop is stale/unsupported — see docs
`HostNotReady` / retryable bridge error	Desktop is up but the report host isn't ready (often briefly after a reload)	CLI auto-retries; rerun once if it surfaces. Do not add custom sleeps — rely on the CLI's retry path.
`Timeout` (bridge error)	A reload or screenshot exceeded the CLI's retry budget	Confirm `status` shows `bridgeStatus: "connected"` , then rerun once. If `Timeout` persists, raise the budget (e.g., `reload --pid <pid> --wait-seconds 120` ). If `bridgeStatus: "error"` or `status` hangs, ask the user whether a Desktop modal dialog is blocking input.
`Cancelled` during screenshot/reload	A reload/screenshot was cancelled — usually a concurrent reload/screenshot on the same PID. Distinct from `Timeout` (operation ran too long).	Run reload and screenshot serially per PID. Wait for `connected` via `status` , retry one at a time.
`ReportDefinitionValidationFailed`	Desktop rejected the PBIR definition	Fix PBIR, run `powerbi-report-author validate <path>` , then reload again
`REPORT_DIR_REQUIRED`	Selected PID has no PBIP/PBIR current file; reload/screenshot-all need PBIP/PBIR state	Select the correct PID from `status` or open the target PBIP

对于渲染输出更改，请遵循此循环。必须在验证、重载和截图评审均通过后才能报告完成。

text

┌──────────────────────────────────────────────────────────┐
│  1. 编辑PBIR文件                                      │
│  2. 验证           → 有错误？修复后回到步骤1         │
│  3. Desktop状态     → 选择正确的桥接PID   │
│  4. Desktop重载     → 有错误？修复PBIR后回到步骤1     │
│  5. 截图/评审  → 有问题？修复后回到步骤1         │
│  6. 完成              → 报告完成               │
└──────────────────────────────────────────────────────────┘

规则：

步骤2 ——
```
powerbi-report-author validate <path-to-.Report-dir>
```
。传入报表定义目录（例如
```
Sales.Report
```
），而非
```
.pbip
```
文件或项目根目录。重载前修复所有错误——无效PBIR错误会在Desktop中显现。
步骤3–5 —— 使用
```
powerbi-desktop
```
CLI：
```
status
```
选择PID，然后使用
```
reload --pid <pid>
```
重载PBIP/PBIR当前文件，并从同一PID获取截图。然后执行以下截图评审。执行
```
status
```
后，如果所选实例显示
```
hasUnsavedChanges: true
```
，请不要立即重载；请用户保存或丢弃其Desktop UI更改，重新运行
```
status
```
，仅当值为false时继续。
```
reload
```
仅覆盖报表/PBIR更改。对于语义模型/TMDL更改，请使用语义模型技能或建模MCP，若更改未反映则重新打开PBIP。 例外： 主题JSON文件按名称缓存——Desktop可能不会在重载时拾取编辑内容。可以为主题文件添加随机后缀重命名（并更新
```
report.json
```
），或关闭并重新打开Desktop。

Desktop CLI命令：

命令	用途	使用场景
`open "<path.pbip>"`	为PBIP/PBIX启动Power BI Desktop	启动Desktop或打开目标报表时
`status`	列出Desktop桥接实例、当前文件、报表目录和桥接状态	重载/截图前；选择正确的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>

。仅支持对PBIP支持的报表进行

reload

。没有

powerbi-desktop

命令接受

--report

；使用

status

按PID选择Desktop实例，因为同一PBIP可能在多个进程中打开。截图默认缩放比例为2。每个PID的重载和截图操作需串行执行——即使是为解决缓慢或可重试错误的变通方案，也不要对同一PID并行执行。请阅读

references/powerbi-desktop.md

获取完整命令参考和故障排除流程。

常见Desktop CLI结果：

输出/错误	含义	操作
`"status": "not_connected"`	未发现Desktop桥接	运行 `powerbi-desktop open "<path.pbip>"` 或请用户启动Desktop。若仍无法连接，请用户启用Desktop预览功能——查看文档
`AMBIGUOUS_DESKTOP_INSTANCE`	存在多个Desktop桥接实例	运行 `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当前文件；重载/screenshot-all需要PBIP/PBIR状态	从 `status` 选择正确的PID或打开目标PBIP

Screenshot Review

截图评审

After taking screenshots, perform an independent rendered-output review before reporting completion. Read

screenshot-review.md

, check layout, data rendering, formatting/theme, slicers, and common screenshot failure modes, then fix PBIR and repeat the loop until clean.

截取截图后，在报告完成前独立评审渲染输出。阅读

screenshot-review.md

，检查布局、数据渲染、格式设置/主题、切片器和常见截图失败模式，然后修复PBIR并重复循环直到无问题。

Validation

验证

Run

powerbi-report-author validate <path>

after every logical batch of PBIR changes. Prefer the

.Report

directory; the CLI also accepts a

.pbip

file or a project root containing a single

.Report

directory. Errors block Desktop reload — fix them first. Review warnings and fix unless there's a clear reason not to.

The validator is an offline preflight covering PBIR structure, JSON/schema validity, cross-file references, IDs/names, visual types, role bindings, filters, formatting objects/properties/enums/selectors, visualContainerObjects, theme registration, layout bounds, and selected Desktop/rendering failure patterns. It does not replace Desktop reload and screenshot review.

完成每一批次PBIR更改后，运行

powerbi-report-author validate <path>

。优先传入

.Report

目录；CLI也接受

.pbip

文件或包含单个

.Report

目录的项目根目录。错误会阻止Desktop重载——先修复错误。查看警告并修复，除非有明确的理由不修复。

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

Anti-Patterns and Pitfalls

反模式与陷阱

Pitfall	Consequence	Fix
Using `"Entity"` inside filter `Where` conditions	Filter silently fails	Use `"Source"` with the alias from `From`
Omitting `nativeQueryRef`	Visual calculations may break	Always include `nativeQueryRef`
Reusing visual/filter names	Unpredictable behavior	Generate unique IDs
Setting `visualType` to invalid string	Visual renders as error box	Run `powerbi-report-author catalog describe <type>` or `powerbi-report-author catalog list`
Wrong role name for visual type	Field is ignored; visual blank	Match role names from `powerbi-report-author catalog describe <type>`
Mixing `Column` and `Measure` types	Query fails; visual error	Columns use `Column` , measures use `Measure`
Forgetting to add page to `pages.json`	Page invisible	Add to `pageOrder` array
Booleans without correct format	Wrong type	`"true"` / `"false"` (no suffix, unquoted in Value)
Numbers without type suffix	Type mismatch	`D` for decimals, `L` for integers
Editing `$schema` version	PBI Desktop may reject	Preserve existing version
Stringified JSON in `paragraphs`	Textbox shows nothing	`paragraphs` is a native JSON array
Using textbox as a thin line/divider	Renders ~24px tall regardless of `height`	Use a `shape` visual (rectangle) instead — shapes respect small dimensions
`visualContainerObjects` as sibling of `visual`	Schema validation error in PBI Desktop	Must be inside `visual` object, as sibling of `objects`
Using `tableEx` with dimension columns and measures all in `Values`	Headers render but no data rows even when DAX confirms data exists	Use `pivotTable` ; put dimensions in `Rows` and measures in `Values`
Using PowerShell `ConvertTo-Json` to edit visual JSON	Property reordering, nesting depth truncation ( `-Depth` default is 2)	Use Node.js for JSON manipulation, or always pass `-Depth 20` and verify structure
Using regex or string replacement to modify JSON files	Corrupts nesting structure — properties end up inside sibling values, braces misalign	Read file → `JSON.parse` → modify object → `JSON.stringify` → write back. Or use the `edit` tool with exact old/new string matching
`dataPoint.fill` without a selector on single-series charts	Bars/columns invisible despite data in tooltips	Use `dataPoint.defaultColor` for a base color without a selector; `fill` requires a `metadata` selector
Using `dataPoint.defaultColor` on multi-series charts	All series/categories get the same color — no visual differentiation	Use theme `dataColors` for consistent palette across visuals, or `dataPoint.fill` with `metadata` selectors for per-series overrides — see color-strategy.md § Color Strategy Quick Reference
Clustered bar/column chart colors collapse into one legend color	The visual has a Series role but all bars and legend markers share the same hue	Use per-series `dataPoint.fill` selectors or a theme `dataColors` palette; do not use `defaultColor` on clustered charts
Relying on theme `dataColors` alone for cross-visual measure consistency	Same measure gets different colors on different visuals (index-based assignment varies with projection order)	Maintain a measure→color mapping and apply explicit `dataPoint.fill` / `defaultColor` per visual — see color-strategy.md § Cross-Visual Measure-Color Consistency
Using `ThemeDataColor` for explicit per-measure `dataPoint.fill` with metadata selectors	Colors silently resolve to white or black instead of expected palette color	Use `Literal` hex values for explicit color assignments with metadata selectors — `ThemeDataColor` is unreliable in this context
Choosing bar/series colors without checking background contrast	Bars or lines invisible against page/card background (e.g., white bars on white canvas)	Always pick saturated, mid-to-dark hues that contrast with the page and VCO background colors
`show` property on page-level `background`	Schema error — page `background` only supports `color` , `image` , `transparency`	Only VCO `background` (on visuals) has `show` ; page background is always visible
Copying property names from doc examples without verifying	Warnings or silent failures — property names vary by visual type	Always run `powerbi-report-author formatting describe-object <type> <object>` for exact property names
Guessing which object a property belongs to	Wasted calls checking wrong objects one by one	Run `powerbi-report-author formatting search <type> <regex>` to grep across all objects at once
Formatting property has no effect (no error)	Setting `show: false` on cardVisual outline without an id selector — validates but renders unchanged	Check `powerbi-report-author formatting describe-object <type> <object>` for `_selectorHint` ; use the dual-entry pattern (static + id selector entries)
Using `cardCalloutArea` on a single-value card	Properties validate but have no visible effect — `cardCalloutArea` only renders on multi-value cards (2+ measures in Data)	Use `outline` / `accentBar` / `fillCustom` with `{ id: "default" }` selector for single-value cards. For multi-value cards, `cardCalloutArea` controls per-callout tile styling — see card.md § Multi-Value Formatting
Using `"Fields"` as the `queryState` role for `cardVisual`	Cards render empty — PBI Desktop cannot resolve the binding. Validator reports `Unknown role "Fields"` and `Required role "Data" missing`	`cardVisual` 's only data role is `"Data"` . `"Fields"` is the legacy `card` visual's role name — never carry it over. Always verify role names with `powerbi-report-author catalog describe cardVisual` — see card.md § Single-Value Template
Creating separate single-value `cardVisual` instances for multiple related KPIs	Wastes canvas space and misuses the visual type — `cardVisual` natively supports multiple projections in one tile	Default to one multi-value `cardVisual` with all measures as `Data` projections when ≥2 related KPIs are requested. Only use separate cards when per-card styling differences are required — see card.md § When to Consolidate vs. Keep Separate
Adding multiple fields to button slicer Values or Label roles	Slicer breaks or shows unexpected results — each role accepts only 1 field	Put one field in Values, one in Label; additional fields go to Tooltips
Looking at `filterConfig` on other visuals to understand slicer selections	Slicer selections live only inside the slicer's own `visual.json` via `expansionStates` + `objects.general.filter` . Always read `references/slicers.md` first when modifying slicers
Creating an image visual without prompting for the source type	Wrong visual structure — URL vs local file vs data field each have different schemas and expression types	Always ask the user for the image source (local file / URL / data field) before creating the visual — see image.md § Source Types Overview
Creating a data-bound image visual with a field that lacks `dataCategory: ImageUrl`	Visual renders blank or error	Warn the user first — the visual will render blank without `dataCategory: ImageUrl` . Present alternatives (other ImageUrl fields, local file, URL) and confirm before creating — see image.md § Select from data
Placing background image on page canvas instead of visual plot area	User asks for "background image" alongside a visual (e.g., "column chart with background image") but image is placed on `page.json → objects.background` instead of `visual.objects.plotArea`	When a background image is requested in the context of a specific visual, default to `plotArea.image` . Only use page-level `background.image` when the user explicitly says "page background" / "canvas background" or no visual context exists — see image.md § Plot Area Background Image
Creating a `multiRowCard` visual	Legacy multi-row card — deprecated; `powerbi-report-author validate` warns with `PBIR_VISUAL_TYPE_DEPRECATED` . Often triggered by user phrases like "multi-card", "cards for each metric", or "card per measure"	Always use `cardVisual` . For multiple KPIs, use a single multi-value `cardVisual` with all measures as projections in the `Data` role — see card.md
Using `map` or `filledMap` instead of `azureMap` for map visuals	Legacy Bing Maps visuals — deprecated and must not be created; `powerbi-report-author validate` warns with `PBIR_VISUAL_TYPE_DEPRECATED`	Always use `azureMap` — see map.md. If the map fails to render or geocode, debug the fields, try alternative geographic columns/coordinates, or ask the user — do not silently substitute a non-map visual without consulting the user first
Creating `tableEx` / `pivotTable` without `columnAdjustment: growToFit`	Columns shrink-wrap to content, leaving unused whitespace	Always set `columnHeaders.columnAdjustment` to `growToFit` and `autoSizeColumnWidth` to `true` — see table.md
Custom table/matrix row colors with no effect (white background)	Default style preset overrides `objects` -level `backColorPrimary` / `backColorSecondary`	Set `stylePreset` VCO to `'None'` on every `tableEx` / `pivotTable` with custom colors — see table.md § Style Presets
Table cells white despite dark VCO background	`visualContainerObjects.background` only controls outer container — table cells paint on top	Set dark colors in `objects.values.backColorPrimary/Secondary` and `objects.columnHeaders.backColor` , not in VCO — see re-theming.md § Dark Mode Checklist
Dark theme applied but cards/tables/slicers still white	Dark mode triggers every formatting trap simultaneously	Follow the full re-theming.md § Dark Mode Authoring Checklist — covers stylePreset, fillCustom+id selector, objects vs VCO, and contrast audit
Theme JSON changes do not appear after Desktop reload	Desktop caches theme files by file name	Rename the theme JSON with a small random suffix, update the theme registration in `report.json` , then reload; otherwise close and reopen Desktop
Placing `sortDefinition` inside `visual` or at root of `visual.json`	Schema validation error; sort silently ignored — chart falls back to alphabetical	`sortDefinition` is a property of `query` — use `visual.query.sortDefinition` . Supported since `visualConfiguration/2.2.0`
Container shape fill doesn't match reference	Text invisible or wrong background color	Match the fill color and transparency to the reference image. If the page background already provides the color, skip the shape entirely. If the shape must be invisible, verify text color still contrasts with the page canvas — see shape.md § Container Shapes
Shape text invisible after re-theme	Shape `text` object has no explicit `fontColor` — text inherits theme foreground, but when `fill` is a light color (e.g., white pill/button) on a light page canvas, inherited dark foreground may not render or the fill blends with canvas making text vanish	Always set explicit `fontColor` on shape `text` objects (in the `{ selector: { id: "default" } }` entry). During re-theming, audit all shapes with `text.show: true` — bulk hex-replacement misses shapes that need a new `fontColor` property added
Enabling `logAxisScale` on data with zero or negative values	PBI Desktop silently falls back to linear scale with a warning — log of zero/negative is undefined	Warn the user before applying. Use `ask_user` to present alternatives (filter negatives, switch measure, use `labelDisplayUnits` ). Apply `logAxisScale: true` only after the user resolves negative values or confirms all bound values are positive — see cartesian.md § Log Scale
Changing theme without sweeping inline overrides	Old colors remain on shapes, page backgrounds, nav buttons, textboxes — theme-only change has no effect on hardcoded `Literal` hex values at Priority 2 in the cascade	When the report has per-visual color overrides, follow re-theming.md § Re-theming Workflow Steps 0–3: build a color mapping, update theme JSON, then bulk-sweep `definition/` files for old hex values before reload
Changing only `dataColors` in theme without sweeping	Shapes, accent bars, nav button borders retain old accent colors — they use hardcoded Literal hex from the old `dataColors` array, not `ThemeDataColor` references	Sweep ALL old `dataColors[N]` hex values across `definition/` files. Even same-polarity "just change the accent/data colors" requests need the full sweep — shapes and nav elements commonly hardcode `dataColors[0]` as accent fills/outlines.

陷阱	后果	修复方案
在筛选器 `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` 设置如何，渲染高度约为24px	使用 `shape` 可视化组件（矩形）替代——形状支持小尺寸
`visualContainerObjects` 作为 `visual` 的同级	PBI Desktop中架构验证错误	必须位于 `visual` 对象内部，作为 `objects` 的同级
`tableEx` 将维度列和度量值全部放在 `Values` 中	表头渲染但无数据行，即使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 § 颜色策略快速参考
簇状条形/柱形图颜色合并为一个图例颜色	可视化组件有Series角色，但所有条形和图例标记共享同一色调	使用按系列的 `dataPoint.fill` 选择器或主题 `dataColors` 调色板；不要在簇状图表上使用 `defaultColor`
仅依赖主题 `dataColors` 实现跨可视化组件度量值一致性	同一度量值在不同可视化组件上显示不同颜色（基于投影顺序的索引分配不同）	维护度量值→颜色映射，并在每个可视化组件上显式应用 `dataPoint.fill` / `defaultColor` ——查看color-strategy.md § 跨可视化组件度量值颜色一致性
对带元数据选择器的显式按度量值 `dataPoint.fill` 使用 `ThemeDataColor`	颜色静默解析为白色或黑色，而非预期的调色板颜色	对带元数据选择器的显式颜色分配使用 `Literal` 十六进制值—— `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 § 多值格式设置
对 `cardVisual` 使用 `"Fields"` 作为 `queryState` 角色	卡片渲染空白——PBI Desktop无法解析绑定。验证器报告 `Unknown role "Fields"` 和 `Required role "Data" missing`	`cardVisual` 唯一的数据角色是 `"Data"` 。 `"Fields"` 是旧版 `card` 可视化组件的角色名称——不要沿用。始终使用 `powerbi-report-author catalog describe cardVisual` 验证角色名称——查看card.md § 单值模板
为多个相关KPI创建单独的单值 `cardVisual` 实例	浪费画布空间并错误使用可视化类型—— `cardVisual` 原生支持在一个磁贴中包含多个投影	当需要≥2个相关KPI时，默认使用一个多值 `cardVisual` ，将所有度量值作为Data投影。仅当需要每个卡片的样式不同时才使用单独的卡片——查看card.md § 合并与拆分场景
按钮切片器的Values或Label角色添加多个字段	切片器损坏或显示意外结果——每个角色仅接受1个字段	在Values中放一个字段，Label中放一个字段；额外字段放在Tooltips中
通过查看其他可视化组件的 `filterConfig` 理解切片器选择	切片器选择仅存储在切片器自身的 `visual.json` 中，通过 `expansionStates` + `objects.general.filter` 实现。修改切片器前请先阅读 `references/slicers.md`
创建图片可视化组件时未提示源类型	可视化组件结构错误——URL、本地文件和数据字段各自有不同的架构和表达式类型	创建可视化组件前始终询问用户图片来源（本地文件/URL/数据字段）——查看image.md § 源类型概述
使用缺少 `dataCategory: ImageUrl` 的字段创建数据绑定图片可视化组件	可视化组件渲染空白或报错	先警告用户——没有 `dataCategory: ImageUrl` 时，可视化组件会渲染空白。提供替代方案（其他ImageUrl字段、本地文件、URL）并确认后再创建——查看image.md § 从数据中选择
将背景图片放在页面画布而非可视化组件绘图区	用户要求“背景图片+可视化组件”（例如“带背景图片的柱形图”），但图片放在 `page.json → objects.background` 而非 `visual.objects.plotArea`	当在特定可视化组件的上下文中请求背景图片时，默认放在 `plotArea.image` 。仅当用户明确说明“页面背景”/“画布背景”或无可视化组件上下文时，才使用页面级 `background.image` ——查看image.md § 绘图区背景图片
创建 `multiRowCard` 可视化组件	旧版多行卡片——已弃用； `powerbi-report-author validate` 会警告 `PBIR_VISUAL_TYPE_DEPRECATED` 。通常由用户短语触发，例如“multi-card”、“每个指标对应一个卡片”或“每个度量值对应一个卡片”	始终使用 `cardVisual` 。对于多个KPI，使用单个多值 `cardVisual` ，将所有度量值作为Data投影——查看card.md
使用 `map` 或 `filledMap` 而非 `azureMap` 创建地图可视化组件	旧版必应地图可视化组件——已弃用，禁止创建； `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` ，将 `stylePreset` VCO设置为 `'None'` ——查看table.md § 样式预设
深色VCO背景下表格单元格仍为白色	`visualContainerObjects.background` 仅控制外部容器——表格单元格在上方绘制	在 `objects.values.backColorPrimary/Secondary` 和 `objects.columnHeaders.backColor` 中设置深色，而非VCO——查看re-theming.md § 深色模式清单
应用深色主题但卡片/表格/切片器仍为白色	深色模式会触发所有格式设置陷阱	遵循完整的re-theming.md § 深色模式创作清单——涵盖stylePreset、fillCustom+id选择器、objects vs VCO和对比度审核
Desktop重载后主题JSON更改未生效	Desktop按文件名缓存主题文件	为主题JSON添加随机小后缀重命名，更新 `report.json` 中的主题注册，然后重载；否则关闭并重新打开Desktop
将 `sortDefinition` 放在 `visual` 内部或 `visual.json` 根目录	架构验证错误；排序被静默忽略——图表默认按字母顺序排序	`sortDefinition` 是 `query` 的属性——使用 `visual.query.sortDefinition` 。自 `visualConfiguration/2.2.0` 起支持
容器形状填充与参考图片不匹配	文本不可见或背景颜色错误	将填充颜色和透明度与参考图片匹配。若页面背景已提供该颜色，则完全省略形状。若形状必须不可见，请验证文本颜色仍与页面画布形成对比——查看shape.md § 容器形状
重新主题化后形状文本不可见	形状 `text` 对象没有显式 `fontColor` ——文本继承主题前景色，但当 `fill` 为浅色（例如白色药丸/按钮）且页面画布为浅色时，继承的深色前景色可能无法渲染，或填充色与画布融合导致文本消失	始终在形状 `text` 对象上设置显式 `fontColor` （在 `{ selector: { id: "default" } }` 条目中）。重新主题化期间，审核所有 `text.show: true` 的形状——批量十六进制替换会遗漏需要添加新 `fontColor` 属性的形状
对包含零或负值的数据启用 `logAxisScale`	PBI Desktop静默回退到线性比例并发出警告——零/负值的对数无定义	应用前警告用户。使用 `ask_user` 提供替代方案（筛选负值、切换度量值、使用 `labelDisplayUnits` ）。仅在用户解决负值问题或确认所有绑定值均为正数后，才应用 `logAxisScale: true` ——查看cartesian.md § 对数比例
更改主题但未扫描内联覆盖设置	形状、页面背景、导航按钮、文本框仍保留旧颜色——仅更改主题对级联中优先级2的硬编码 `Literal` 十六进制值无效	当报表有每个可视化组件的颜色覆盖设置时，遵循re-theming.md § 重新主题化流程步骤0–3：构建颜色映射，更新主题JSON，然后批量扫描 `definition/` 文件中的旧十六进制值，再进行重载
仅更改主题中的 `dataColors` 但未扫描	形状、强调栏、导航按钮边框仍保留旧强调色——它们使用旧 `dataColors` 数组中的硬编码Literal十六进制值，而非 `ThemeDataColor` 引用	扫描 `definition/` 文件中所有旧的 `dataColors[N]` 十六进制值。即使是同极性的“仅更改强调色/数据颜色”请求，也需要完整扫描——形状和导航元素通常会硬编码 `dataColors[0]` 作为强调填充/轮廓。

Official Documentation

官方文档

For Microsoft Learn setup guidance, support constraints, and feature availability, use Power BI report authoring docs.

有关Microsoft Learn设置指南、支持约束和功能可用性，请查看Power BI报表创作文档。