r-visuals

Power BI 中的 R 可视化（PBIR）

所有报表变更都必须使用 pbir。 仅可读取 PBIR 元数据用于诊断。如果 pbir 不可用或缺少所需操作，请停止并报告缺口；切勿直接编辑报表 JSON。

R 可视化会执行 R 脚本（主要使用 ggplot2），在 Power BI 画布上呈现静态 PNG 图像。ggplot2 是首选库——其图形语法方法能够以更少的代码生成简洁、达到出版品质的统计可视化。R 特别适合统计可视化。

可视化标识

• visualType： scriptVisual
• 数据角色： Values（列和度量值，可添加多个）
• 数据变量： dataset（data.frame，自动注入）
• 行数上限： 150,000 行
• 输出： 72 DPI 的静态 PNG——不支持交互

工作流：创建 R 可视化

步骤 1：添加可视化

pbir add visual scriptVisual "Report.Report/Page.Page" --name RevenueByDateR \
  --data "Values:Sales.Date" --data "Values:Sales.Revenue"

步骤 2：编写脚本

library(ggplot2)

p <- ggplot(dataset, aes(x=Date, y=Sales)) +
  geom_col(fill="#5B8DBE") +
  theme_minimal(base_size=12) +
  theme(panel.grid.major.x=element_blank())

print(p)  # MANDATORY for ggplot2

关键规则：

• ggplot2 对象必须调用 print(p)——在 Power BI 中不会自动显示
• dataset 会作为 data.frame 自动注入；不要自行创建
• 使用索引访问列（dataset[,1]），以避免列名转义问题
• 列名中包含空格时，请使用反引号：dataset$`Order Lines`

步骤 2b：审核

向用户展示脚本之前，请调用 r-reviewer Agent 验证其正确性并提供设计反馈。

步骤 3：注入脚本

pbir visuals r "Report.Report/Page.Page/RevenueByDateR.Visual" --script-file chart.r

CLI 会处理 PBIR 字符串转义。

步骤 4：验证

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

PBIR 格式

只读诊断时，脚本存储在 visual.objects.script[0].properties 中：

{
  "source": {"expr": {"Literal": {"Value": "'library(ggplot2)\\n...\\nprint(p)'"}}},
  "provider": {"expr": {"Literal": {"Value": "'R'"}}}
}

结构与 Python 可视化相同，不同之处在于 visualType 为 scriptVisual，provider 为 'R'。

支持的包

Power BI Service（R 4.3.3）

包	版本	用途
ggplot2	3.5.1	图形语法
dplyr	1.1.4	数据处理
tidyr	1.3.1	数据整理
ggrepel	0.9.5	避免标签重叠
patchwork	1.2.0	组合多个图表
cowplot	1.1.3	出版品质的图表
corrplot	0.94	相关矩阵
viridis	0.6.5	颜色标度
RColorBrewer	1.1-3	调色板
forecast	8.23.0	时间序列预测
pheatmap	1.0.12	热图
treemap	2.4-4	树图
lattice	0.22-6	Trellis 图形

可使用约 1000 个 CRAN 包。**不支持：**需要联网的包（RgoogleMaps、mailR）。

完整包列表：https://learn.microsoft.com/power-bi/connect-data/service-r-packages-support

桌面版

任何本地安装的 R 包都可以不受限制地使用。必须单独安装 R。

最佳实践

1. 始终调用 print(p)——ggplot2 对象需要显式打印
2. 处理空数据——if (nrow(dataset) == 0) { plot.new(); text(0.5, 0.5, "No data") }
3. 使用基于索引的列访问方式——dataset[,1] 可避免列名转义问题
4. 使用 theme_minimal()——简洁的美学风格，与 Power BI 搭配效果良好
5. 将分类变量设为因子——使用 factor() 显式控制排序
6. 使用与报表主题匹配的十六进制颜色
7. 设置边距——使用 plot.margin=margin(t, r, b, l) 防止内容被裁切
8. 保持脚本简洁——桌面版超时限制为 5 分钟，Service 超时限制为 1 分钟

限制

约束	桌面版	Service
输出	静态 PNG，72 DPI	静态 PNG，72 DPI
超时	5 分钟	1 分钟
行数上限	150,000	150,000
输出大小	2 MB	30 MB
网络	不受限制	已阻止
网关	仅个人网关	仅个人网关
跨筛选 FROM	不支持	不支持
接收跨筛选	支持	支持
发布到 Web	不支持	不支持
嵌入（app-owns-data）	不支持	不支持

脚本结构模板

library(ggplot2)

# 1. Guard against empty data
if (nrow(dataset) == 0) {
  plot.new()
  text(0.5, 0.5, "No data available", cex=1.5)
} else {
  # 2. Data preparation (index-based access)
  df <- data.frame(
    category = dataset[,1],
    value = dataset[,2]
  )

  # 3. Create visualization
  p <- ggplot(df, aes(x=reorder(category, -value), y=value)) +
    geom_col(fill="#5B8DBE", width=0.7) +
    theme_minimal(base_size=12) +
    theme(
      panel.grid.major.x = element_blank(),
      axis.title = element_blank()
    )

  # 4. Render
  print(p)
}

R 与 Python 语法参考

关于语言选择，请参阅上文的“When to Use a Script Visual”部分。此表仅涵盖已采用 R 编写的脚本在语法上的机械差异：

方面	R（scriptVisual）	Python（pythonVisual）
渲染调用	print(p)	plt.show()
列访问	dataset[,1] 或 dataset$col	dataset.iloc[:,0] 或 dataset["col"]
空值保护	if (nrow(dataset) == 0)	if len(dataset) == 0:
因子／类别顺序	factor(x, levels=...)	pd.Categorical(x, categories=...)
运行时（Service）	R 4.3.3	Python 3.11

何时使用脚本视觉对象

仅当以下条件全部满足时，才使用 R 视觉对象：

• 图表没有原生等效项，也没有合理的 Deneb 规范
• 其价值在于必须在渲染时运行的统计计算（模型拟合、核密度、预测区间），而非 Vega 可以绘制的形状
• 该视觉对象不需要用作交叉筛选源、显示悬停工具提示、发布到 Web，或嵌入 app-owns-data
• 报表部署在 Pro/PPU 或更高容量中，且所在区域已启用 Fabric

如果交互性或交叉筛选很重要，请使用 Deneb（静态 PNG 不能作为选择源）。如果需求是小型内嵌标记（迷你图、条形、状态标签），请使用 SVG 度量值（无行数上限、无超时、无许可／区域限制，可在发布到 Web 时渲染）。脚本视觉对象的适用范围很窄：面向内部或组织使用、在渲染时计算的统计图表。

**确定使用脚本视觉对象后，如何在 R 与 Python 之间选择：**如果需要出版级的统计默认设置，或使用没有 Python 对应包的 R 包（forecast、corrplot、pheatmap、山脊图／小提琴图），请使用 R。如果计算主要依赖 scikit-learn、statsmodels 或 scipy，或者报表周边逻辑已经使用 Python，请使用 Python。两者都适用时，默认选择报表中其他脚本使用的语言；混用会使发布时需要验证的包范围翻倍。

不要仅因图表类型“看起来有统计意味”就默认使用脚本视觉对象。箱线图、棒棒糖图或哑铃图应使用 SVG 度量值或 Deneb；脚本应留给真正需要计算的图表。

参考资料

• references/data-model.md -- dataset 分组机制、行数／字节数上限、强制逐行输入，以及 R 特有的注意事项（Time 类型、文本渲染标志、CJK 字体）
• references/community-examples.md -- 按图表类型整理的 R Graph Gallery 示例（分布、相关性、排名、演变、流向）
• references/ggplot2-patterns.md -- 常见 ggplot2 图表模式（条形图、环形图、折线图、热力图、子弹图）
• examples/script/ -- 独立的 R 脚本（条形图、趋势线）-- 转义后即可注入 visual.json
• examples/visual/bullet-chart.json -- PBIR visual.json：子弹图，包含条件着色、错误处理和大量转义
• examples/visual/bar-chart.json -- PBIR visual.json：水平条形图，包含 PY 对比线和着色的账户标签
• examples/visual/trend-line.json -- PBIR visual.json：面积图，包含带状图和月份因子处理

获取文档

如需获取最新的 R 视觉对象／包支持文档，请搜索 https://learn.microsoft.com 并获取相关页面。根据用户的请求进行搜索，并按需执行多次搜索，以确保在继续之前获得充分的上下文。

相关技能

• pbi-report-design -- 布局和设计最佳实践
• python-visuals -- Python 脚本视觉对象（概念相同，语言不同）
• deneb-visuals -- Vega/Vega-Lite 视觉对象（交互式、基于矢量的替代方案）
• svg-visuals -- 通过 DAX 度量值实现 SVG（轻量级内嵌图形）
• pbir-format（pbip 插件）-- PBIR JSON 格式参考