Powerbi Code First Dashboards

Power BI Dashboards from Code——零手动UI工作

Python脚本生成PBIR JSON文件，Power BI将其呈现为完整的多页仪表板。没有拖动字段，没有点击菜单——每个视觉对象一行Python。

你需要的

整个方法依赖于 两个文本文件 它们共同定义了一个完整的仪表板：

**1. *_Dashboard_Prompts.md** --数据模型规范。此文件描述了数据层的所有内容：要加载哪些CSV、列数据类型、表关系、日历表以及按阶段组织的所有DAX度量值。将其视为一个配方，当在Power BI Desktop（或MCP代理）中逐步执行时，会生成一个完全连接的数据模型。它不生成任何视觉效果，只生成视觉效果会查询的模型。

2. scripts/generate_pages.py --视觉布局脚本。纯Python（除了stdlib之外没有依赖关系）。当你运行它时，它会写 visual.json 将文件放入您的PBIR文件夹结构中 .pbip 项目。每个文件都定义了一个视觉元素：它的类型、在画布上的位置、大小、数据绑定和格式（卡片上的强调栏、样式化的表头、干净的图表网格线、数据标签）。视觉效果的设计是为了在首次打开时看起来很专业，而不是像原始数据转储。

这些文件是从哪里来的？ 你自己写，或者让克劳德生成，或者混合搭配。看 入门指南 在......下面

图1——获取两个文件

您需要一个Prompts文件（数据模型规范）和一个generate_pages.py（可视化布局脚本）。有两种方法可以获得它们：

flowchart LR
    CSV[Your CSV Files] --> CHOOSE{Choose a path}

    CHOOSE -->|Manual| YOU[You study the examples\nin this repo]
    YOU --> MANUAL_P[You write\nDashboard_Prompts.md]
    YOU --> MANUAL_S[You write\ngenerate_pages.py]

    CHOOSE -->|Automated| BRIEF[You write a 1-paragraph\nbusiness brief]
    BRIEF --> SKILL[Claude Skill reads\nCSVs + brief]
    SKILL --> GEN_P[Dashboard_Prompts.md\ngenerated]
    SKILL --> GEN_S[generate_pages.py\ngenerated]

    MANUAL_P --> REVIEW[Review both files]
    MANUAL_S --> REVIEW
    GEN_P --> REVIEW
    GEN_S --> REVIEW

    REVIEW --> READY[Ready to execute]

    style CSV fill:#f9f,stroke:#333
    style READY fill:#9f9,stroke:#333
    style REVIEW fill:#ffd,stroke:#333

这些路径也可以混合使用——例如，使用Claude生成Prompts文件（为您编写所有DAX），但自己编写Python脚本来控制确切的页面布局，反之亦然。

Prompts文件始终是一个可人工审查的检查点。无论是你写的还是克劳德生成的，在任何东西接触Power BI之前，你都可以阅读每个DAX指标和关系。

图2——执行管道

一旦你有了这两个文件，执行就有三个步骤。唯一真正的选择是如何构建数据模型（步骤1）。

flowchart TD
    START[Dashboard_Prompts.md\n+ generate_pages.py] --> STEP1{Step 1: Build Data Model\nfrom Prompts file}

    STEP1 -->|Manual| PBI[Open Power BI Desktop\nGet Data, type each DAX measure,\ncreate relationships yourself]
    STEP1 -->|Automated| MCP[Paste phases into\nClaude Desktop / Claude Code\nMCP agent executes commands]

    PBI --> SAVE[Save as .pbip\nClose Power BI Desktop]
    MCP --> SAVE

    SAVE --> STEP2[Step 2: Run generate_pages.py\npython scripts/generate_pages.py]
    STEP2 --> JSON[visual.json files written\ninto PBIR folder structure]
    JSON --> STEP3[Step 3: Reopen .pbip in Power BI\nApply theme, review — 5-10 min]
    STEP3 --> DONE[Dashboard Ready]

    style START fill:#ffd,stroke:#333
    style DONE fill:#9f9,stroke:#333
    style SAVE fill:#fff,stroke:#e55,stroke-width:2px

步骤1的第三个选项是TMDL/表格编辑器——导出或写入TMDL文件并将其部署到Power BI项目，完全跳过桌面UI。

Power BI桌面必须 关闭 当您运行generate_pages.py时，它会锁定PBIR文件。带红线的“保存并关闭”步骤是Power BI UI和Python脚本之间的关键切换。

运作原理

上面的两张图显示了全貌。简而言之：获取这两个文件（图1），然后执行它们（图2）。无论您采取哪种路径获取文件，执行管道总是有相同的三个步骤：

1. 构建数据模型 从Prompts文件中加载CSV，创建关系，添加DAX度量值。在Power BI Desktop中手动或通过MCP代理执行此操作。另存为 .pbip.
2. 运行generate_pages.py （关闭Power BI）--脚本写入 visual.json 将文件放入PBIR文件夹结构。
3. 重新打开 .pbip --所有页面都以格式化的、数据绑定的视觉效果显示。应用主题以实现全局颜色一致性，查看标题和布局（5-10分钟）。

下面的两个选项通过特定的步骤端到端地遍历每条路径。

入门指南

先决条件

这两个选项都需要：

• Power BI桌面 （Windows）启用PBIR预览功能：文件>选项>预览功能，然后启用： *使用增强元数据格式（PBIR）存储报告*, *Power BI项目（.pbip）保存选项*, *以TMDL格式存储语义模型*.
• Python 3.x --任何版本。脚本仅使用stdlib模块(json, os, hashlib, shutil).

选项A：完全手动

您自己编写这两个文件，并手动执行每一步。没有AI参与。

1. 写入提示文件。 创建一个 *_Dashboard_Prompts.md 它指定了您的数据模型：要加载哪些CSV、列数据类型、所有表关系、日历表和每个DAX度量值。使用此仓库中的现有提示文件作为模板（例如。， supply_chain/SupplyChain_Dashboard_Prompts.md).
2. 编写Python脚本。 创建一个 scripts/generate_pages.py 使用 make_* 功能。使用现有脚本和 技能档案 作为函数库、布局约定和视觉选择启发式的参考。
3. 在Power BI Desktop中构建数据模型。 打开Power BI，通过获取数据加载CSV，然后按照提示文件一步一步地操作——设置列类型，在模型视图中创建关系，添加日历表，并将每个DAX度量值键入（或粘贴）到 _Measures 桌子。这是最耗时的部分。
4. 另存为 .pbip. 文件>另存为，选择Power BI项目格式。然后 关闭Power BI桌面 （它锁定文件）。
5. 运行脚本。 python scripts/generate_pages.py --写 visual.json 将文件放入PBIR文件夹结构。
6. 重新打开 .pbip --所有页面都以格式化的、数据绑定的视觉效果显示。可选地应用主题JSON以实现全局颜色一致性。

选项B：全自动

Claude从原始CSV和简短的业务简报中生成这两个文件，然后MCP代理构建数据模型。

1. 准备你的CSV。 当表遵循星型模式命名时效果最佳(FactXxx, DimXxx)具有匹配的关系ID列。
2. 加载技能。 将你的CSV与技能文件一起放入Claude Code中(skills/PBIR_Dashboard_Generator_Skill.md)在上下文中加载。
3. 简短地写一段。 描述仪表板应该关注什么——例如。， *“供应链仪表板通过同比比较跟踪订单履行、库存周转和供应商绩效。”*
4. Claude生成了这两个文件。 这 *_Dashboard_Prompts.md （数据模型规范）和 generate_pages.py （视觉布局脚本）。检查两者——提示文件是一个人类可读的检查点，您可以在继续之前检查每个DAX度量值和关系。
5. 通过MCP执行提示文件。 将每个阶段粘贴到您的MCP客户端（Claude Desktop、Claude Code或任何具有Power BI建模MCP服务器的客户端）。代理以编程方式加载表、创建关系并输入DAX度量值。
6. 另存为 .pbip那么 关闭Power BI桌面.
7. 运行生成的脚本。 python scripts/generate_pages.py.
8. 重新打开 .pbip --应用主题，复习，完成。

混合两条路径

手动和自动路径可以自由组合。一些常见的组合：使用Claude生成Prompts文件（为您编写所有DAX），但自己编写页面布局脚本。或者自己编写Prompts文件，但使用MCP执行它，而不是手动键入每个度量值。或者生成这两个文件，但在Power BI Desktop中手动执行Prompts文件，而不是通过MCP。每个文件和每个步骤都是独立的——选择适合您工作流程的组合。

为什么代码优先？

可复制。 重新运行脚本，获得相同的仪表板。每一次。整个管道是基于文本的，版本可控——JSON差异而不是二进制 .pbix 斑点。

快。 4个完整的仪表板内置在一小时内，而不是几天的人工工作。

可扩展。 42项措施可以手动管理。200不是。在脚本中更改表名，重新运行，完成——相同的布局，不同的数据。

可学习。 每个提示文件都是一个独立的DAX教程，其中详细说明了所有度量值。

可预测性

该架构将确定性和非确定性层分开：

AI从不编写原始JSON。它要么称之为确定性 make_* 函数（用于视觉效果）或遵循提示文件中的明确规范（用于数据模型）。模式正确性由函数保证；视觉设计决策是由该技能的启发式方法指导的。

Vibe编码为您提供了一个仪表板。代码首先给你一个仪表板工厂。

仪表板示例

跨不同业务领域的五个完整仪表板项目，每个项目都有示例CSV数据、提示文件和 generate_pages.py 脚本：

截图（PortPulse——比雷埃夫斯港拥堵）

Port Overview *Azure地图，包括船舶位置、KPI卡、按船舶类型划分的等待时间、详细信息表*

Trends & Patterns *拥堵趋势线（每日计数+7D移动平均线），按星期和小时，R ARIMA预测*

Vessel Detail *配备切片器的全船列表，R隔离森林异常检测，K表示行为集群*

Cost Impact *按船舶类型列出的等待成本圆环、按船舶列出的坡度条形图、成本明细表*

截图（供应链）

Supply Chain KPIs *KPI卡、同比折线图、条形图、圆环图、面积图*

Advanced Analytics *仪表、散点图、瀑布图、漏斗图、带状图*

Visual Showcase *堆积柱、饼图、100%堆积条形图、聚集柱*

支持的视觉类型

每个视觉元素都是一行Python代码：

make_card("sc1_rev", 20, 10, 300, 140, "_Measures", "Total Revenue")

这将为完全数据绑定的KPI卡生成PBIR JSON，并带有重音条、阴影和圆角。这 make_* 函数处理数据绑定和专业格式化，因此输出在首次打开时看起来很精致，无需手动格式化。

27种视觉类型可通过 make_* 功能： card, gauge, clusteredBar, clusteredColumn, lineChart （双Y）， areaChart, donut, pie, waterfall, funnel, scatter （具有可选的气泡尺寸）， ribbon, stackedColumn, stackedBar, 100%StackedBar, 100%StackedColumn, table, matrix, treemap, filledMap, bubbleMap, slicer, titleBar, button （页面导航）， clusteredBarGradient, clusteredColumnGradient, rVisual （嵌入式R/Python脚本）。

每个函数都有一个可视名称、画布位置（x、y、w、h）和数据绑定（类别为表/列，值为表/度量）。完整参考 技能档案.

内置格式

每 make_* 函数在生成的文件中包含专业格式默认值 visual.json。无需手动格式化即可获得干净、可呈现的结果。

卡片 --重音条（彩色顶部条纹）、阴影、圆角、干净的衬垫。设计为看起来像现代KPI图块，而不是默认的Power BI卡。

条形图、柱状图、甜甜圈图、饼图、瀑布图、漏斗图 --启用数据标签、隐藏轴标题（数据不言自明）、虚线网格线。

折线图和面积图 --线条更粗，虚线网格线干净，没有数据标签（趋势线上过于杂乱）。

表格 --粗体列标题，主题强调色背景和白色文本，交替行颜色，仅水平网格线。

矩阵 --与表相同的标题样式，以及干净的行标题格式。

标题栏 --全宽彩色文本框，带白色文本（Segoe UI半粗体18px），隐藏视觉标题。默认深色板岩，可自定义背景颜色。

按钮 --带有居中文本的操作按钮，可通过以下方式进行页面导航 visualLink。用于页面之间的仪表板导航。

梯度图 --具有条件格式的集群条形图/列变体。根据测量值，使用从最小到最大的渐变对条/列进行着色 FillRule 和 linearGradient2.

R视觉效果 --在Power BI的R可视化主机中运行的嵌入式R脚本。 make_r_visual 绑定数据字段并将R代码（ggplot2、forecast、solution、dplyr）直接注入PBIR JSON。在PortPulse中用于ARIMA拥堵预测、隔离林异常检测和K-means船舶行为聚类——所有这些都在仪表板中呈现为交互式ggplot2图表。

自动生成的背景 — make_background() 使用Pillow渲染每页1280x720 PNG：带有页面标题的深色标题栏、视觉集群后面的圆形容器区域、强调条纹、网格点和页脚栏。 write_background() 然后将PNG作为画布壁纸嵌入PBIR页面（RegisteredResources+page.json背景参考）。完全先编码——不需要手动导入图像。

格式内置于每个 make_* 通过内部功能 _*_objects() 助手。该架构被设计为可扩展的——添加更多的视觉参数（自定义强调色、切换阴影、控制标签位置）意味着在不破坏任何现有脚本的情况下向现有功能添加可选参数。对于全局样式（页面背景、调色板、字体系列），请应用包含的主题文件：查看>主题>浏览主题>选择 themes/code-first-dashboard.json.

相关项目

代码优先PBIR空间中的其他项目：

• PowerBPY -用于通过OOP API创建Power BI仪表板的Python包。Pip可安装。处理仪表板脚手架和数据导入；图表视觉效果目前使用列聚合（而不是DAX度量值绑定）。
• Lukas Reese的PBIR报告生成器 --Claude具备从自然语言生成原始PBIR JSON的技能。AI原生方法，支持IBCS方差图。
• pbir_tools --用于PBIR格式文件操作的Python库。数据模型聚焦。
• power双视觉模板 --用于将可视化模板注入PBIR项目的表格编辑器C#脚本。

回购结构

powerbi-code-first-dashboards/
  ecommerce/                       # E-Commerce dashboard project
  hospital/                        # Hospital Operations dashboard project
  hr/                              # HR People Analytics dashboard project
  supply_chain/                    # Supply Chain & Inventory dashboard project
  portpulse/                       # Piraeus port congestion dashboard (R analytics + live AIS)
    data/                          #   CSV files + live AIS collector script
    backgrounds/                   #   Auto-generated PNG page backgrounds
    scripts/generate_pages.py      #   PBIR visual generator (Python + Pillow)
    PortPulse_Dashboard_Prompts.md #   Full data model specification
    DEMO_GUIDE.md                  #   Demo walkthrough and setup instructions
  skills/
    PBIR_Dashboard_Generator_Skill.md  # Claude skill for auto-generating dashboards
  themes/
    code-first-dashboard.json      # Power BI theme (light)
    code-first-dashboard-dark.json # Power BI theme (dark variant)
  workflow/
    PowerBI_From_Code_Workflow.md   # Detailed methodology guide
  images/                          # Dashboard screenshots
  CLAUDE.md                        # Claude Code project instructions

技术栈