Back to Details

godot-ui-theming

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

UI Theming

UI主题设计

Theme resources, StyleBox styling, font management, and override system define consistent UI visual identity.
Theme资源、StyleBox样式、字体管理和覆盖系统定义了一致的UI视觉标识。

Available Scripts

可用脚本

global_theme_manager.gd

global_theme_manager.gd

Expert theme manager with dynamic switching, theme variants, and fallback handling.
具备动态切换、主题变体和回退处理功能的专业主题管理器。

ui_scale_manager.gd

ui_scale_manager.gd

Runtime theme switching and DPI/Resolution scale management.
运行时主题切换与DPI/分辨率缩放管理工具。

NEVER Do in UI Theming

UI主题设计中的禁忌

  • NEVER create StyleBox in _ready() for many nodes — 100 buttons × 
    StyleBoxFlat.new()
    in 
    _ready()
    ? 100 duplicate objects. Create ONCE in theme resource, reuse via inheritance.
  • NEVER forget theme inheritance — Child Control with custom theme? Parent theme ignored. Set 
    theme
    on root Control, children auto-inherit unless overriding.
  • NEVER hardcode colors in StyleBox — 
    style.bg_color = Color(0.2, 0.3, 0.5)
    ? Unmaintainable. Define colors in theme, reference via 
    theme.get_color("primary", "Button")
    .
  • NEVER use add_theme_override for global styles — Call 
    add_theme_*_override()
    on 50 nodes? Brittle. Define in Theme resource for automatic propagation.
  • NEVER skip corner_radius_all shortcut — Set 4 corner radii individually? Verbose. Use 
    corner_radius_all = 5
    for uniform corners (StyleBoxFlat only).
  • NEVER modify theme during rendering — Change theme in 
    _draw()
    OR 
    _process()
    ? Constant re-layout = performance tank. Load themes at initialization OR on user action only.
  1. Project Settings → GUI → Theme
  2. Create new Theme resource
  3. Assign to root Control node
  4. All children inherit theme
  • 切勿在_ready()中为大量节点创建StyleBox —— 100个按钮在_ready()中分别调用
    StyleBoxFlat.new()
    ？会生成100个重复对象。应在Theme资源中创建一次，通过继承复用。
  • 切勿忘记主题继承 —— 子Control使用自定义主题后，父主题会被忽略？应在根Control节点设置
    theme
    ，子节点除非主动覆盖，否则会自动继承。
  • 切勿在StyleBox中硬编码颜色 —— 像
    style.bg_color = Color(0.2, 0.3, 0.5)
    这样的写法？难以维护。应在Theme中定义颜色，通过
    theme.get_color("primary", "Button")
    引用。
  • 切勿为全局样式使用add_theme_override —— 在50个节点上调用
    add_theme_*_override()
    ？这种方式很脆弱。应在Theme资源中定义，实现自动传播。
  • 切勿跳过corner_radius_all快捷方式 —— 分别设置4个圆角半径？过于繁琐。对于StyleBoxFlat，使用
    corner_radius_all = 5
    实现统一圆角。
  • 切勿在渲染过程中修改主题 —— 在
    _draw()
    或
    _process()
    中修改主题？会导致持续重布局，性能急剧下降。仅在初始化或用户操作时加载主题。
  1. 项目设置 → GUI → 主题
  2. 创建新的Theme资源
  3. 分配给根Control节点
  4. 所有子节点自动继承主题

StyleBox Pattern

StyleBox模式

gdscript
undefined
gdscript
undefined

Create StyleBoxFlat for buttons

为按钮创建StyleBoxFlat

var style := StyleBoxFlat.new() style.bg_color = Color.DARK_BLUE style.corner_radius_top_left = 5 style.corner_radius_top_right = 5 style.corner_radius_bottom_left = 5 style.corner_radius_bottom_right = 5
var style := StyleBoxFlat.new() style.bg_color = Color.DARK_BLUE style.corner_radius_top_left = 5 style.corner_radius_top_right = 5 style.corner_radius_bottom_left = 5 style.corner_radius_bottom_right = 5

Apply to button

应用到按钮

$Button.add_theme_stylebox_override("normal", style)
undefined
$Button.add_theme_stylebox_override("normal", style)
undefined

Font Loading

字体加载

gdscript
undefined
gdscript
undefined

Load custom font

加载自定义字体

var font := load("res://fonts/my_font.ttf") $Label.add_theme_font_override("font", font) $Label.add_theme_font_size_override("font_size", 24)
undefined
var font := load("res://fonts/my_font.ttf") $Label.add_theme_font_override("font", font) $Label.add_theme_font_size_override("font_size", 24)
undefined

Reference

参考资料

Related

相关内容

  • Master Skill: godot-master
  • 核心技能：godot-master