power-bi-visuals

Power BI Visuals Skill

在 PBIR 报表页面上创建和管理视觉对象。无需连接 Power BI Desktop ——这些命令直接操作 JSON 文件。

添加视觉对象

# Add by alias (pbi-cli resolves to the PBIR type)
pbi visual add --page page_abc123 --type bar
pbi visual add --page page_abc123 --type card --name "Revenue Card"

# Custom position and size (pixels)
pbi visual add --page page_abc123 --type scatter \
    --x 50 --y 400 --width 600 --height 350

# Named visual for easy reference
pbi visual add --page page_abc123 --type combo --name sales_combo

每个视觉对象都以一个文件夹的形式创建，其中包含一个 visual.json 文件，位于页面的 visuals/ 目录中。该模板包含正确的架构 URL，以及所选类型对应的 queryState 角色。

绑定数据

视觉对象初始为空。使用 visual bind 和 Table[Column] 表示法将其连接到语义模型。绑定选项因视觉对象类型而异——请参阅下方的类型表。

# Bar chart: category axis + value
pbi visual bind mybar --page p1 \
    --category "Geography[Region]" --value "Sales[Revenue]"

# Card: single field
pbi visual bind mycard --page p1 --field "Sales[Total Revenue]"

# Matrix: rows + values + optional column
pbi visual bind mymatrix --page p1 \
    --row "Product[Category]" --value "Sales[Amount]" --value "Sales[Quantity]"

# Scatter: X, Y, detail, optional size and legend
pbi visual bind myscatter --page p1 \
    --x "Sales[Quantity]" --y "Sales[Revenue]" --detail "Product[Name]"

# Combo chart: category + column series + line series
pbi visual bind mycombo --page p1 \
    --category "Calendar[Month]" --column "Sales[Revenue]" --line "Sales[Margin]"

# KPI: indicator + goal + trend axis
pbi visual bind mykpi --page p1 \
    --indicator "Sales[Revenue]" --goal "Sales[Target]" --trend "Calendar[Date]"

# Gauge: value + max/target
pbi visual bind mygauge --page p1 \
    --value "Sales[Revenue]" --max "Sales[Target]"

绑定会使用 ROLE_ALIASES 将 --value 等易读名称转换为 PBIR 角色名称（例如 Y、Values、Data）。Measure 和 Column 的类型根据角色推断： value/indicator/goal/max 角色会创建 Measure 引用，category/row/detail 角色 会创建 Column 引用。如有需要，可使用 --measure 标志进行覆盖。

检查和更新

# List all visuals on a page
pbi visual list --page page_abc123

# Get full details of one visual
pbi visual get visual_def456 --page page_abc123

# Move, resize, or toggle visibility
pbi visual update vis1 --page p1 --width 600 --height 400
pbi visual update vis1 --page p1 --x 100 --y 200
pbi visual update vis1 --page p1 --hidden
pbi visual update vis1 --page p1 --visible

# Delete a visual
pbi visual delete visual_def456 --page page_abc123

容器属性

在视觉对象容器本身设置边框、背景或标题：

pbi visual set-container vis1 --page p1 --background "#F0F0F0"
pbi visual set-container vis1 --page p1 --border-color "#CCCCCC" --border-width 2
pbi visual set-container vis1 --page p1 --title "Sales by Region"

视觉对象计算

添加在视觉对象作用域内运行的 DAX 计算：

pbi visual calc-add vis1 --page p1 --role Values \
    --name "RunningTotal" --expression "RUNNINGSUM([Revenue])"

pbi visual calc-list vis1 --page p1
pbi visual calc-delete vis1 --page p1 --name "RunningTotal"

批量操作

通过 --type 或 --name-pattern 筛选，同时操作多个视觉对象：

# Find visuals matching criteria
pbi visual where --page overview --type barChart
pbi visual where --page overview --type kpi --y-min 300

# Bind the same field to ALL bar charts on a page
pbi visual bulk-bind --page overview --type barChart \
    --category "Date[Month]" --value "Sales[Revenue]"

# Resize all KPI cards
pbi visual bulk-update --page overview --type kpi --width 250 --height 120

# Hide all visuals matching a pattern
pbi visual bulk-update --page overview --name-pattern "Temp_*" --hidden

# Delete all placeholders
pbi visual bulk-delete --page overview --name-pattern "Placeholder_*"

where、bulk-bind、bulk-update、bulk-delete 的筛选选项：

• --type —— PBIR 视觉对象类型或别名（例如 barChart、bar）
• --name-pattern —— 对视觉对象名称使用 fnmatch glob 模式（例如 Chart_*）
• --x-min、--x-max、--y-min、--y-max —— 位置边界（像素）

所有批量命令都至少需要 --type 或 --name-pattern，以防止 意外执行大范围操作。

支持的视觉对象类型（32 种）

图表

别名	PBIR 类型	绑定选项
bar	barChart	--category、--value、--legend
line	lineChart	--category、--value、--legend
column	columnChart	--category、--value、--legend
area	areaChart	--category、--value、--legend
ribbon	ribbonChart	--category、--value、--legend
waterfall	waterfallChart	--category、--value、--breakdown
stacked_bar	stackedBarChart	--category、--value、--legend
clustered_bar	clusteredBarChart	--category、--value、--legend
clustered_column	clusteredColumnChart	--category、--value、--legend
scatter	scatterChart	--x、--y、--detail、--size、--legend
funnel	funnelChart	--category、--value
combo	lineStackedColumnComboChart	--category、--column、--line、--legend
donut / pie	donutChart	--category、--value、--legend
treemap	treemap	--category、--value

卡片和 KPI

别名	PBIR 类型	绑定选项
card	card	--field
card_visual	cardVisual	--field（现代卡片）
card_new	cardNew	--field
multi_row_card	multiRowCard	--field
kpi	kpi	--indicator、--goal、--trend
gauge	gauge	--value、--max / --target

表格

别名	PBIR 类型	绑定选项
table	tableEx	--value
matrix	pivotTable	--row、--value、--column

切片器

别名	PBIR 类型	绑定选项
slicer	slicer	--field
text_slicer	textSlicer	--field
list_slicer	listSlicer	--field
advanced_slicer	advancedSlicerVisual	--field（平铺/图像切片器）

地图

别名	PBIR 类型	绑定选项
azure_map / map	azureMap	--category、--size

装饰和导航

别名	PBIR 类型	绑定选项
action_button	actionButton	（无数据绑定）
image	image	（无数据绑定）
shape	shape	（无数据绑定）
textbox	textbox	（无数据绑定）
page_navigator	pageNavigator	（无数据绑定）

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

默认情况下，每个写入命令都会自动同步 Power BI Desktop。依次添加或绑定多个视觉对象时，Desktop 会在每个对象操作后重新加载。

在 visual 命令组中使用 --no-sync 批量应用所有更改，然后在最后调用一次 pbi report reload：

# Suppress sync while building visuals
pbi visual --no-sync add --page overview --type card --name rev_card
pbi visual --no-sync bind rev_card --page overview --field "Sales[Total Revenue]"
pbi visual --no-sync add --page overview --type bar --name sales_bar
pbi visual --no-sync bind sales_bar --page overview --category "Product[Category]" --value "Sales[Revenue]"

# Single reload when all visuals are done
pbi report reload

JSON 输出

所有命令都支持供 Agent 使用的 --json：

pbi --json visual list --page overview
pbi --json visual get vis1 --page overview
pbi --json visual where --page overview --type barChart

---

注意事项

• visual bind 根据角色推断 Measure 还是 Column，而不是底层 TMDL 对象： 像 --value 这样的角色总是创建 Measure 引用。如果 Sales[Revenue] 实际上是列（而非度量值），视觉对象会呈现为空白，且不会报错。请使用 --measure，或改用真实度量值的名称。
• 不带 --type 或 --name-pattern 的 bulk-bind 会被阻止，但使用过于宽泛的模式可能会重新绑定无关的视觉对象： --name-pattern "Chart_*" 会匹配 Chart_Revenue、Chart_Margin，以及 Chart_Drillthrough_Hidden。请务必先运行 pbi visual where 进行预览。
• 视觉对象的位置 --x/--y 使用报表设计像素，而非屏幕像素： 在宽度为 1280 的画布上设置 --x 1280，会将视觉对象放在右边缘，无论查看者的屏幕尺寸如何。超出画布边界的视觉对象会渲染在屏幕之外，且不会发出警告。
• 通过 calc-add 添加的视觉计算会在视觉对象作用域内的度量值计算之后运行： 在视觉计算中引用度量值，会捕获筛选后的值。在 SUMX 等函数中将该计算当作度量值进行迭代，会产生意外结果，因为该计算仅存在于视觉对象的查询作用域中。
• PBIR 视觉对象的 name 是文件夹名称，重命名需要移动文件系统中的文件，而非使用 CLI 标志： --name 标志仅在创建时生效。之后执行 visual update 不会重命名。要重命名，请删除后重新添加（这会丢失视觉对象 ID），或直接编辑文件系统。
• bulk-delete --name-pattern "Placeholder_*" 不可撤销，且不会跳过确认步骤： 每次删除都会移除一个文件夹；如果同时使用 --no-sync，可能会在察觉之前就删除数十个视觉对象。请务必先使用相同模式运行 pbi visual where。