deneb-visuals

Power BI 中的 Deneb 可视化效果（PBIR）

每次修改报表都使用 pbir。 仅在诊断时读取 PBIR 元数据。如果 pbir 不可用或缺少某项操作，请停止并报告缺失项；切勿直接编辑报表 JSON。

Deneb 是 Power BI 的认证自定义视觉对象，可在报表中直接使用 Vega 和 Vega-Lite 声明式可视化规范。使用此技能编写规范。

Provider 策略

对于新的 Deneb 可视化效果，优先使用 Vega-Lite，除非需要特定的 Vega 专属功能（信号、事件流、自定义投影、力导向／Voronoi 布局）。Vega-Lite 更简洁、更易维护，并且涵盖大多数图表类型。有关高级 Vega 功能，请参阅 references/vega-patterns.md 和 Vega 文档。

可视化对象标识

• visualType： deneb7E15AEF80B9E4D4F8E12924291ECE89A
• 捆绑运行时： Vega 6.2.0 / Vega-Lite 6.4.1（自 Deneb 1.8 起；使用 v6.json 架构 URL）
• 数据角色： 单个 dataset 角色（所有字段都放入一个“值”字段槽）
• 默认行数限制： 10,000 行（通过 dataLimit.override 覆盖）
• Provider： vegaLite（默认）或 vega（需要 Vega 专属功能时）
• 渲染模式： svg（默认，文本清晰）或 canvas（适用于大型数据集）

自定义视觉对象注册（必需）

使用 pbir cp 复制可用的 Deneb 视觉对象会一并复制其注册信息。对于新的视觉对象，使用 pbir get 检查 publicCustomVisuals，并通过 pbir set --json 更新完整列表，同时保留现有 ID。切勿直接编辑 report.json。

工作流：创建 Deneb 可视化效果

步骤 1：添加视觉对象

通过 pbir 创建视觉对象和绑定：

pbir add visual deneb7E15AEF80B9E4D4F8E12924291ECE89A \
  "Report.Report/Page.Page" --name RevenueByCategoryDeneb
pbir visuals bind "Report.Report/Page.Page/RevenueByCategoryDeneb.Visual" \
  --add "dataset:Sales.Category" --type Column
pbir visuals bind "Report.Report/Page.Page/RevenueByCategoryDeneb.Visual" \
  --add "dataset:Sales.Revenue" --type Measure

所有字段都绑定到单个 dataset 角色。列使用 Table.Column，度量值使用 Table.Measure。绑定中的字段名称必须与 Vega／Vega-Lite 规范中使用的名称一致。

步骤 2：编写规范

创建 Vega-Lite（或 Vega）JSON 规范文件。主要区别：

• Vega-Lite： "data": {"name": "dataset"}（对象）
• Vega： "data": [{"name": "dataset"}]（数组）

{
  "$schema": "https://vega.github.io/schema/vega-lite/v6.json",
  "data": {"name": "dataset"},
  "mark": {"type": "bar", "tooltip": true},
  "encoding": {
    "y": {"field": "Category", "type": "nominal"},
    "x": {"field": "Value", "type": "quantitative"}
  }
}

完整的规范文件（Vega 和 Vega-Lite）请参阅 examples/spec/，完整的 PBIR visual.json 文件请参阅 examples/visual/。规范中的字段名称必须与字段绑定中的 nativeQueryRef（显示名称）一致。

步骤 3：注入规范

pbir visuals deneb "Report.Report/Page.Page/RevenueByCategoryDeneb.Visual" \
  --spec-file chart.vl.json --provider vegaLite

CLI 会处理 PBIR 编码。规范文件中应保留普通的 Vega 或 Vega-Lite JSON。

步骤 3b：审查

向用户呈现规范之前，先调用 deneb-reviewer Agent 验证语法并提供设计反馈。

步骤 4：验证

pbir visuals bind "Report.Report/Page.Page/RevenueByCategoryDeneb.Visual" --show
pbir validate "Report.Report" --all

规范编写规则

数据绑定

• Vega："data": [{"name": "dataset"}]（数组形式）
• Vega-Lite："data": {"name": "dataset"}（对象形式）
• 字段引用显示名称。特殊字符（.、[、]、\、"）会替换为 _
• 不会替换空格——字段名称会保留空格（例如 "Order Lines"）

表达式中的字段名称转义（重要）

转义方式取决于规范是独立文件，还是已注入 PBIR visual.json：

独立规范文件（位于 examples/spec/）：使用带 JSON 转义的双引号：

{"calculate": "datum[\"Order Lines\"] - datum[\"Order Lines (PY)\"]", "as": "diff"}

PBIR visual.json 内部（位于 examples/visual/）：整个规范是单引号括起来的 DAX 字面字符串。包含空格的字段名称使用成对的单引号（''）：

datum[''Order Lines''] - datum[''Order Lines (PY)'']

不属于字段名称转义的单引号（例如筛选表达式中的字符串字面量 datum.Series == 'Actuals'）可直接使用，因为它们不会与外层的单引号括号冲突。

响应式尺寸（Vega）

使用 Deneb 内置信号实现容器尺寸响应式调整：

"width": {"signal": "pbiContainerWidth - 25"},
"height": {"signal": "pbiContainerHeight - 27"}

这些偏移量会考虑内边距。对于文本标记的绝对定位，请使用 {"signal": "width"}，而不要使用硬编码的像素值。

配置（与规范分开）

始终提供配置文件，以确保样式一致。请参阅 references/vega-patterns.md 中的 Standard Config 部分。关键设置：autosize: fit、view.stroke: transparent、font: Segoe UI。

主题集成

使用 Power BI 主题颜色，而不是硬编码的十六进制值：

函数/方案	用途	在 Vega 中的用法
pbiColor(index)	按索引获取主题颜色（从 0 开始）	{"signal": "pbiColor(0)"}
pbiColor(0, -0.3)	将主题颜色加深 30%	色调：-1（深）到 1（浅）
pbiColor("negative")	情感颜色	"min"、"middle"、"max"、"negative"、"positive"
pbiColor("bad")	情感颜色的别名	"bad" = "negative"、"good" = "positive"、"neutral" = "middle"
pbiColorNominal	分类调色板（颜色各异）	"range": {"scheme": "pbiColorNominal"}
pbiColorOrdinal	序数调色板（类别有序）	"range": {"scheme": "pbiColorOrdinal"}
pbiColorLinear	连续渐变	"range": {"scheme": "pbiColorLinear"}
pbiColorDivergent	发散渐变	"range": {"scheme": "pbiColorDivergent"}

交互性

通过 visual.json 中的 vega 对象启用交互性：

功能	属性	默认值	说明
工具提示	enableTooltips	true	在 encode 中使用 "tooltip": {"signal": "datum"}
上下文菜单	enableContextMenu	true	右键单击以向下钻取
交叉筛选	enableSelection	false	需要处理 __selected__
交叉突出显示	enableHighlight	false	创建 <field>__highlight 字段

交叉筛选

当 enableSelection 为 true 时，在 encode 块中处理 __selected__（"on"、"off"、"neutral"）。选择模式：simple（自动解析，最多支持 250 个数据点）或 advanced（仅限 Vega；刷选/套索/区域选择时必需，可通过 options.limit 支持最多 2500 个数据点，并提供 pbiCrossFilterApply 和 pbiCrossFilterClear 信号）。简单模式请参阅 references/vega-patterns.md，高级信号 API 请参阅 references/advanced-patterns.md。

交叉突出显示

使用分层标记——背景降低不透明度，前景显示 <field>__highlight 值。详情请参阅 references/vega-patterns.md。

特殊运行时字段

Deneb 会向每个数据集行注入运行时字段。完整表格请参阅 references/capabilities.md。

关键字段：__row__（从 0 开始的行索引，用于替代已移除的 __identity__）、__selected__（选择状态）、<field>__highlight + <field>__highlightStatus + <field>__highlightComparator（交叉突出显示）、<field>__formatted（预格式化的值字符串）、<field>__format（Power BI 格式字符串）。

**1.9 中的重大变更：**已移除 __identity__ 和 __key__。将任何 datum.__identity__ 替换为 datum.__row__。

最佳实践

1. 新建可视化时使用 Vega-Lite，除非需要 Vega 专属功能（信号、事件、力导向布局）
2. 始终在配置中使用 autosize: fit，以适应 Power BI 的响应式尺寸
3. 使用 pbiContainerWidth/pbiContainerHeight 信号编写响应式 Vega 规范
4. 使用主题颜色（pbiColor、pbiColorNominal），而不是十六进制值
5. 使用 enter/update/hover encode 块，以便清晰地管理状态（仅限 Vega）
6. 在标记上使用 "tooltip": {"signal": "datum"} 启用工具提示
7. 性能——先在 DAX 中进行聚合；标记较多时优先使用 renderMode: canvas，然后再提高 dataLimit.override。完整的调优顺序请参阅 references/advanced-patterns.md
8. 测试字段名称——确认 nativeQueryRef 与规范中的字段引用一致
9. 避免使用外部数据——AppSource 认证不允许加载外部 URL
10. 转义方式取决于上下文——独立规范中使用双引号，PBIR visual.json 中使用两个连续的单引号（参见上文的转义规则）

何时使用 Deneb

Deneb 是高级自定义视觉对象的首选方案，适用于需要交互功能（交叉筛选、工具提示、悬停效果）且超出 Power BI 原生视觉对象能力的场景。以下情况适合使用 Deneb：

• 原生不支持的自定义图表类型（子弹图、蜂群图、桑基图等）
• 精细控制视觉编码、动画和交互
• 基于矢量的渲染（任意尺寸下都清晰锐利）

对于表格或卡片中的简单内嵌图形（迷你图、数据条、进度条），如果不需要交互，请改用 SVG 度量值。对于统计可视化（分布分析、回归、相关性），如果重点是分析严谨性而非交互性，请改用 Python/R。

参考资料

• references/community-examples.md -- 按图表类型整理的 170 多个社区模板，包含作者署名和直接链接
• references/vega-patterns.md -- Vega 图表模式（条形图、折线图、散点图、环形图、堆叠图、热力图、面积图、棒棒糖图、子弹图、KPI 卡片）、标准配置、变换和比例尺参考
• references/vega-lite-patterns.md -- Vega-Lite 图表模式（仅用于编辑现有 Vega-Lite 视觉对象）
• references/pbir-structure.md -- PBIR JSON 结构（字面量编码、查询状态、交互示例）
• references/capabilities.md -- 完整的 Deneb 对象属性参考和模板格式（usermeta 架构）
• references/advanced-patterns.md -- 高级交叉筛选信号（Vega pbiCrossFilterApply/pbiCrossFilterClear）、性能优化的杠杆顺序，以及通过终端往返处理社区模板
• examples/visual/bullet-chart.json -- PBIR visual.json：包含条件指示器和交叉筛选的分面子弹图（Vega-Lite）
• examples/visual/kpi-card.json -- PBIR visual.json：包含分层文本和条件百分比变化颜色的 KPI 卡片（Vega-Lite）
• examples/visual/trend-line.json -- PBIR visual.json：包含 fold 变换和颜色／图例映射的双系列折线图（Vega-Lite）
• examples/visual/ytd-comparison.json -- PBIR visual.json：年初至今与目标的比较，包含虚线、端点标签、数字格式和基于排名的筛选（Vega-Lite）
• examples/spec/vega/ -- 独立的 Vega 规范文件（条形图、折线图）-- 转义后即可注入 visual.json
• examples/spec/vega-lite/ -- 独立的 Vega-Lite 规范文件（子弹图、KPI 卡片）-- 转义后即可注入
• examples/standard-config.json -- 所有 Deneb 规范的标准配置

获取文档

如需获取最新的 Power BI 自定义视觉对象文档，请搜索 https://learn.microsoft.com 并获取相关页面。根据用户的请求进行搜索，并按需执行多次搜索，以确保在继续操作前获得足够的上下文。注意：Vega/Vega-Lite 文档位于 vega.github.io（而非 MS Learn）-- 请使用 WebFetch 获取。

相关技能

• pbir-format（pbip 插件）-- PBIR JSON 格式参考
• pbi-report-design -- 布局和设计最佳实践
• r-visuals -- R 脚本视觉对象（ggplot2）
• python-visuals -- Python 脚本视觉对象（matplotlib）
• svg-visuals -- 通过 DAX 度量值使用 SVG（轻量级内嵌图形）