mcpField
M
modifying-theme-json

modifying-theme-json

github.com/data-goblin设计与 UI1.1k91 次安装今天更新
代码仓库

关于 modifying-theme-json

modifying-theme-json 是面向 Power BI 报告主题设计与规范检查的技能，适用于需要统一视觉格式的报告维护者。它要求通过 pbir 执行修改，并提供审计、主题继承和验证流程。

主要功能

  1. 01检查主题颜色与字体
  2. 02分析格式级联及视觉覆盖
  3. 03通过 pbir 修改主题
  4. 04验证主题与报告结构

适用场景

  1. 01统一报告中的颜色和字体
  2. 02检查视觉对象的格式来源
  3. 03替换主题并验证显示效果

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/data-goblin/power-bi-agentic-development --skill modifying-theme-json

安装后在 Claude Code 中输入/modifying-theme-json确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

examples/
DataGoblins2021.json
Fluent2-CY26SU03.json
examples/visualTypes/
actionButton.md
advancedSlicerVisual.md
aiNarratives.md
areaChart.md
azureMap.md
barChart.md
bookmarkNavigator.md
card.md
cardVisual.md
clusteredBarChart.md
clusteredColumnChart.md
columnChart.md
decompositionTreeVisual.md
donutChart.md
filledMap.md
filter.md
funnel.md
gauge.md
group.md
hundredPercentStackedAreaChart.md
hundredPercentStackedBarChart.md
hundredPercentStackedColumnChart.md
image.md
keyDriversVisual.md
kpi.md
lineChart.md
lineClusteredColumnComboChart.md
lineStackedColumnComboChart.md

详细介绍

Power BI 报表主题

使用此技能进行主题设计和合规性决策。命令详情请使用 pbir-cli 技能。

不可妥协的工具使用规则

所有报表和主题变更都必须使用 pbir。绝不要直接编辑 theme.json、visual.json、序列化的 .Theme 片段或其他报表 JSON。绝不要改用 jq、Shell 替换或 JSON 编辑技能。如果 pbir 不支持所需操作，请停止并报告缺少的功能。

只能通过 pbir cat、pbir get 或只读示例读取 JSON。优先使用结构化 CLI 检查命令，因为这些命令会说明格式级联和使用情况。

主题为何重要

主题将原本可能在各个视觉对象间逐渐偏离的格式集中管理。主题应负责管理重复使用的选项，例如：

  • 数据系列调色板和语义化的良好／中性／不良颜色
  • 背景色、前景色、结构色、渐变色、超链接色和空值颜色
  • 字体系列、字号、字重和层级
  • 标题、边框、内边距和阴影等通配容器默认值
  • 卡片、切片器、图表、表格、文本框和图像等视觉对象类型的默认值

视觉对象级覆盖项应仅用于内容特定的例外情况或条件格式。以主题为先的报表更易于重新打造品牌、比较差异和维护。

格式级联

Power BI defaults
  -> theme wildcard defaults
  -> theme visual-type defaults
  -> selected style preset
  -> visual instance overrides

最后一层优先级最高。使用 pbir visuals format 诊断意外的渲染结果；该命令会报告有效值及其来源。不要检查或修补 visual.json。

修改前先审计

pbir theme colors "Report.Report"
pbir theme fonts "Report.Report"
pbir color list "Report.Report"
pbir fonts list "Report.Report"
pbir visuals format "Report.Report/Page.Page/Visual.Visual"
pbir bpa run "Report.Report"

检查是否存在硬编码颜色、重复的视觉对象级字体或容器覆盖项、不一致的视觉对象类型、对比度不足、调色板过大，以及在不同视觉对象中含义不一致的情绪色。

设计规则

  1. 数据调色板的类别数量应限制在报表实际需要的范围内。
  2. 饱和的强调色应留作焦点、选中状态、例外情况和关键比较之用。
  3. 为每种语义颜色指定一种固定含义。良好、中性、不良、已选中、已禁用和超链接颜色在不同页面间不得互换用途。
  4. 结构色应保持低调。坐标轴、边框、网格线和背景应有助于阅读，而非与数据争抢注意力。
  5. 使用一种可移植的字体系列和一套简洁的字号层级。通过字号和字重体现层级，而不是使用多种颜色。
  6. 优先使用通配默认值，其次是视觉对象类型默认值，最后才使用少量实例级覆盖项。
  7. 保持对比度符合无障碍要求，绝不要只依赖色相传达状态。

使用 pbir 编写

从有效模板或报表现有主题开始；不要编写空主题。

# Apply a known base when requested
pbir theme list-templates
pbir theme apply-template "Report.Report" sqlbi

# Set palette and semantic colors
pbir theme set-colors "Report.Report" \
  --data-colors '["#1971C2","#F08C00","#2F9E44","#7048E8"]' \
  --good "#2E7D32" --neutral "#6B7280" --bad "#C62828" \
  --background "#FFFFFF" --foreground "#252525"

# Set typography by semantic level
pbir theme set-fonts "Report.Report" title --font-face "Segoe UI Semibold" --font-size 14
pbir theme set-fonts "Report.Report" label --font-face "Segoe UI" --font-size 10
pbir theme set-fonts "Report.Report" callout --font-face "Segoe UI Semibold" --font-size 32

# Set repeated formatting at theme level
pbir theme set-formatting "Report.Report" "*.*.dropShadow.show" --value false
pbir theme set-formatting "Report.Report" "*.*.border.show" --value false
pbir theme set-formatting "Report.Report" "card.*.title.fontSize" --value 14

编写不熟悉的格式属性前，先运行 pbir schema describe <visualType> <object>。

将优质视觉对象提升为主题

pbir theme push-visual "Report.Report/Page.Page/BestCard.Visual" --dry-run
pbir theme push-visual "Report.Report/Page.Page/BestCard.Visual"

当某个设计出色的实例应成为其视觉对象类型的默认值时，请使用此操作。先检查试运行结果，以免意外提升内容特定的格式。

强制主题继承

清除覆盖项具有破坏性，必须先征得用户确认。除非用户明确要求移除，否则请保留条件格式。

pbir visuals clear-formatting "Report.Report/**/*.Visual" --keep-cf --dry-run -f
pbir visuals clear-formatting "Report.Report/**/*.Visual" --keep-cf -f
pbir theme colors "Report.Report" --normalize
pbir theme colors "Report.Report" --normalize --apply

如需有选择地清理，请使用 pbir visuals clear-formatting --help 中记录的标志，而不要大范围编辑文件。

复制或替换主题

pbir cp "Source.Report/theme" "Target.Report/theme" -f
pbir theme validate "Target.Report"

替换主题后，清除过时的视觉对象覆盖项，统一保留的颜色字面值，并检查前景色与背景色的明暗关系，确保文本仍清晰可见。

验证和渲染

完成一批连贯的修改后，进行一次置信度检查：

pbir theme validate "Report.Report"
pbir validate "Report.Report" --all
pbir desktop refresh "Report.Report"
pbir desktop screenshot "Report.Report" --all --output-dir screenshots

Desktop 刷新不会重新加载主题资源。评估主题更改前，请关闭并重新打开报表，然后截取屏幕截图。如果无法使用 Desktop，请先征求用户同意，再发布到沙盒工作区进行渲染验证。

详细参考

  • references/style-presets.md：各视觉类型的命名样式预设、默认预设，以及如何为视觉对象选择预设
  • pbir-cli -> references/modifying-theme.md：颜色、字体、格式设置、规范化和验证
  • pbir-cli -> references/apply-theme.md：模板、复制、清除覆盖项
  • pbir-cli -> references/format-visuals.md：级联检查和属性发现
  • pbi-report-design：布局、克制地使用颜色、层次结构和无障碍性

评论

支持 Markdown