power-bi-pages

Power BI 页面技能

管理 PBIR 报表中的页面。页面是 definition/pages/ 中的文件夹， 其中包含 page.json 文件和 visuals/ 目录。无需连接 Power BI Desktop。

列出和检查页面

# List all pages with display names, order, and visibility
pbi report list-pages

# Get full details of a specific page
pbi report get-page page_abc123

get-page 返回：

• name、display_name、ordinal（排序顺序）
• width、height（画布大小，单位为像素）
• display_option（例如 "FitToPage"）
• visual_count —— 页面上的视觉对象数量
• is_hidden —— 页面是否在导航窗格中隐藏
• page_type —— "Default" 或 "Drillthrough"
• filter_config —— 页面级筛选器配置（如果有）
• visual_interactions —— 自定义视觉对象交互规则（如果有）
• page_binding —— Drillthrough 参数定义（如果是 Drillthrough 页面）

添加页面

# Add with display name (folder name auto-generated)
pbi report add-page --display-name "Executive Overview"

# Custom folder name and canvas size
pbi report add-page --display-name "Details" --name detail_page \
    --width 1920 --height 1080

默认画布大小为 1280x720（标准 16:9）。常见替代尺寸：

• 1920x1080 —— Full HD
• 1280x960 —— 4:3
• 适用于移动设备或仪表板布局的自定义尺寸

删除页面

# Delete a page and all its visuals
pbi report delete-page page_abc123

这会删除整个页面文件夹，包括所有视觉对象子目录。

页面背景

# Set a solid background colour
pbi report set-background page_abc123 --color "#F5F5F5"

页面可见性

控制页面是否显示在报表导航窗格中：

# Hide a page (useful for drillthrough or tooltip pages)
pbi report set-visibility page_abc123 --hidden

# Show a hidden page
pbi report set-visibility page_abc123 --visible

书签

书签会记录页面级状态（筛选器、可见性、滚动位置）。 它们位于 definition/bookmarks/ 中：

# List all bookmarks in the report
pbi bookmarks list

# Get details of a specific bookmark
pbi bookmarks get "My Bookmark"

# Add a new bookmark
pbi bookmarks add "Executive View"

# Delete a bookmark
pbi bookmarks delete "Old Bookmark"

# Toggle bookmark visibility
pbi bookmarks set-visibility "Draft View" --hidden

Drillthrough 页面

Drillthrough 页面在 page.json 中包含一个 pageBinding 字段，用于定义 Drillthrough 参数。在 Drillthrough 页面上调用 get-page 时， page_binding 字段会返回完整的绑定定义，其中包括参数名称、绑定的筛选器和字段表达式。普通页面则返回 null。

要创建 Drillthrough 页面，请先添加页面，然后在 Power BI Desktop 中将其配置为 Drillthrough （目前尚不支持通过 CLI 配置 PBIR Drillthrough——CLI 可以读取并报告 Drillthrough 配置）。

工作流：设置报表页面

# 1. Add pages in order
pbi report add-page --display-name "Overview" --name overview
pbi report add-page --display-name "Sales Detail" --name sales_detail
pbi report add-page --display-name "Regional Drillthrough" --name region_drill

# 2. Hide the drillthrough page from navigation
pbi report set-visibility region_drill --hidden

# 3. Set backgrounds
pbi report set-background overview --color "#FAFAFA"

# 4. Verify the setup
pbi report list-pages

路径解析

页面命令会从父级 pbi report 命令组继承报表路径：

1. 显式指定：pbi report --path ./MyReport.Report list-pages
2. 自动检测：从 CWD 开始向上查找 *.Report/definition/
3. 从 .pbip 查找：从 .pbip 文件查找同级 .Report 文件夹

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

默认情况下，每个写入命令都会自动同步 Power BI Desktop。依次设置多个页面时，Desktop 会在每次设置后重新加载。

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

# Suppress sync while setting up pages
pbi report --no-sync add-page --display-name "Overview" --name overview
pbi report --no-sync add-page --display-name "Details" --name details
pbi report --no-sync set-background overview --color "#F2F2F2"
pbi report --no-sync set-background details --color "#F2F2F2"

# Single reload when all page setup is done
pbi report reload

JSON 输出

pbi --json report list-pages
pbi --json report get-page page_abc123
pbi --json bookmarks list

---

注意事项

• **delete-page 不可撤销，会删除整个文件夹及其中的视觉对象：**没有回收站，也无法撤销。如果页面包含其他位置没有副本的独有视觉对象，它们就会消失。删除前务必执行 pbi report export-tmdl 或提交到 Git。
• **set-visibility --hidden 不会阻止用户通过已发布报表 URL 访问页面：**任何拥有深层链接 /reports/{id}/{pageId} 的人仍能加载该页面。对于敏感的草稿页面，还应限制工作区角色——可见性只是 UX 标志，不是安全边界。
• **包含 pageBinding 的钻取页面虽会显示在 get-page 中，但目前无法通过 CLI 创建：**你可以读取和列出这类页面，但必须在 Desktop 中配置绑定。通过 Desktop 往返处理有时会重新格式化无关的页面设置——提交前请先查看差异。
• **add-page 的序号会从当前最大值之后自动分配，而不是按视觉顺序追加到末尾：**如果之前删除过页面，新序号可能与用户感知的页面顺序冲突。使用 pbi report list-pages 确认可见顺序。
• **书签按视觉对象 ID（而非名称）捕获视觉状态：**保存书签后重命名视觉对象，会导致书签仍指向旧 ID——书签可以加载，但重命名后的视觉对象不会应用书签状态。重命名后务必重新创建书签。
• **默认页面尺寸 1280x720 在 Desktop 中看起来正常，在移动设备上却会显示异常：**Desktop 默认以 FitToPage 模式呈现；Service 在手机上会使用手机布局（如果已定义），否则会裁切内容。对于可能在移动设备上查看的报表，务必定义手机布局，或将画布宽度设为不超过 1080。