godot-ui-theming

用途

Godot UI 主题化技能用于在 Godot 引擎中建立一致的 UI 视觉标识。它通过 Theme 资源、StyleBox 样式、字体管理与覆盖系统，帮助开发者统一界面外观，并支持多主题（如明色、暗色、高对比度）切换。

主要能力

• Theme 资源与 StyleBox：使用 StyleBoxFlat/StyleBoxTexture 定义面板与按钮外观，通过 Theme 资源实现共享样式与继承。
• 主题继承与类型变体：在 Theme 编辑器中创建类型变体（如 DangerButton），基于基础类型继承属性，仅覆盖差异部分，避免复制场景或样式盒。
• 动态主题切换：在根 Control 节点上替换 Theme 资源，Godot 会自动向所有后代传播；配合 NOTIFICATION_THEME_CHANGED 更新不支持自动主题化的元素。
• 运行时 StyleBox 颜色修改：先 duplicate() 再修改，避免污染共享 Theme 资源。
• 字体管理：通过 Theme 编辑器或项目主题设置字体与字号，保证 UI 可读性。
• 无障碍支持：高对比度主题使用纯黑/白与更粗的焦点轮廓；RTL/LTR 双向布局通过主题变体镜像；控制器/键盘提示图标按设备切换。
• 资源优化：使用 AtlasTexture 打包 UI 图标以减少绘制调用；2D/像素艺术使用无损压缩，UI 背景大图使用有损或 Basis Universal 压缩。

使用方式

该技能提供多个 GDScript 脚本作为参考实现，包括：

• global_theme_manager.gd：动态切换、主题变体与回退处理。
• ui_scale_manager.gd：运行时主题切换与 DPI/分辨率缩放管理。
• theme_swapper.gd：基于级联主题根传播的明暗模式实现。
• danger_button_assignment.gd：使用 theme_type_variation 进行语义化 UI 样式。
• dynamic_stylebox_color.gd：安全的运行时 StyleBox 修改，演示 duplicate() 模式。
• procedural_theme_safe.gd：使用 NOTIFICATION_THEME_CHANGED 为生成 UI 元素可靠主题化。
• custom_chart_drawing.gd：在自定义 _draw() 中读取活动 Theme 属性。
• theme_isolation.gd：隔离节点与父主题，引用项目默认值。
• pulsating_ui_theme.gd：通过 Tween 动画化 UI 样式。
• crisp_ui_scaler.gd：使用 content_scale_factor 实现分辨率无关缩放。
• memory_safe_custom_drawing.gd：在类级别缓存资源以修复样式盒消失问题。
• rtl_theme_mirroring.gd：根据布局方向动态交换主题变体。
• focus_prompt_icon_swapper.gd：控制器/键盘提示图标库切换与焦点高亮面板。

主题归属决策树：应用级外观在项目设置 → GUI → Theme 中定义；单个 Control 差异使用 add_theme_*_override；按钮/面板子类型使用 theme_type_variation；运行时颜色微调先 duplicate() 再覆盖。

适用场景

• 需要统一 UI 视觉风格的游戏或应用。
• 需要支持明色/暗色/高对比度等多主题切换。
• 需要无障碍支持（控制器导航、RTL 布局、低视力高对比度）。
• 需要季节性主题变体（如万圣节、圣诞节图标库切换）。
• 需要优化 UI 绘制调用与显存占用。

限制与注意事项

• 不要在 _ready() 中为大量节点创建 StyleBox，应使用 Theme 资源共享。
• 不要忘记主题继承：子节点若有自己的 theme 会忽略父主题。
• 不要在 StyleBox 中硬编码颜色，应使用 theme.get_color()。
• 不要用 add_theme_override 处理全局样式。
• 不要在 _draw() 或 _process() 中修改主题资源。
• 不要将 StyleBoxEmpty 用于焦点样式而不提供可见替代。
• 不要用标准 set() 设置主题属性，必须使用 add_theme_color_override() 等专用 API。
• 不要用 expand_margin_* 扩大可点击区域，应使用 content_margin_* 或调整 Control 尺寸。
• 不要在 _draw() 中定义局部 StyleBox 变量，应在类级别存储。
• 不要为改一个颜色而复制场景/主题，应使用 theme_type_variation。
• 不要混淆 Theme 项与 Control 覆盖：add_theme_override 仅在该节点上优先于 Theme 资源项；切换根主题时用 remove_theme_override 清除旧覆盖。

官方文档参考包括 GUI skinning、主题编辑器、主题类型变体、字体使用、自定义 GUI 控件、尺寸与锚点、Theme、ThemeDB、Control、StyleBox、AtlasTexture、Input 等。相关技能涵盖项目基础、资源数据模式、UI 容器、信号架构、富文本、补间、输入处理、自动加载架构、导出构建、性能优化等。