bevy-ui

Bevy 0.19 — UI

何时使用此技能

• 创建基于 Node 的面板、按钮、标签、叠加层或菜单。
• 处理 Interaction::{None, Hovered, Pressed} 和视觉状态。
• 适配 0.19 Parley 迁移后的文本样式。
• 管理通过指针获取的 InputFocus 或可访问名称。
• 使用 children![] 构建静态树，或使用 with_children 构建动态树。

标准模式

use bevy::{
    input_focus::{FocusCause, InputFocus},
    prelude::*,
};

fn main() {
    App::new()
        .add_plugins(DefaultPlugins) // includes InputFocusPlugin in 0.19
        .add_systems(Startup, setup)
        .add_systems(Update, style_button)
        .run();
}

fn setup(mut commands: Commands, assets: Res<AssetServer>) {
    commands.spawn(Camera2d);
    commands.spawn((
        Node {
            width: percent(100),
            height: percent(100),
            align_items: AlignItems::Center,
            justify_content: JustifyContent::Center,
            ..default()
        },
        children![(
            Button,
            AccessibleLabel::new("Start game"),
            Node {
                width: px(180),
                height: px(64),
                border: UiRect::all(px(3)),
                border_radius: BorderRadius::MAX,
                align_items: AlignItems::Center,
                justify_content: JustifyContent::Center,
                ..default()
            },
            BackgroundColor(Color::srgb(0.12, 0.12, 0.15)),
            BorderColor::all(Color::WHITE),
            children![(
                Text::new("Start game"),
                TextFont {
                    font: assets.load("fonts/FiraSans-Bold.ttf").into(),
                    font_size: FontSize::Px(32.0),
                    ..default()
                },
                TextColor(Color::WHITE),
            )],
        )],
    ));
}

fn style_button(
    mut focus: ResMut<InputFocus>,
    mut buttons: Query<
        (Entity, &Interaction, &mut BackgroundColor),
        (Changed<Interaction>, With<Button>),
    >,
) {
    for (entity, interaction, mut background) in &mut buttons {
        *background = match interaction {
            Interaction::Pressed => {
                focus.set(entity, FocusCause::Pressed);
                BackgroundColor(Color::srgb(0.15, 0.55, 0.25))
            }
            Interaction::Hovered => BackgroundColor(Color::srgb(0.22, 0.22, 0.28)),
            Interaction::None => BackgroundColor(Color::srgb(0.12, 0.12, 0.15)),
        };
    }
}

主题

主题	参考
Node、Val、flex/grid 布局	布局
FontSource、FontSize、TextLayout	文本
Button、Interaction、Changed	交互
颜色、边框和圆角	颜色和边框
调色板常量	调色板
InputFocus、语义、可访问标签	无障碍
静态和动态子项	子项
常见问题	易错点

易错点

• 新插入的组件会满足 Changed<T>。交互系统通常会在首次 Update 时处理新按钮；当需要区分插入和后续修改时，请使用 Ref<T>::is_added()。
• 指针悬停和输入焦点并不相同。请勿仅因光标移入或移出，就移动或清除键盘／辅助技术焦点。
• TextFont.font 的类型是 FontSource；使用 .into() 转换 Handle<Font>。font_size 的类型是 FontSize，例如 FontSize::Px(32.0)。
• InputFocus 的字段是私有的。请使用 get、set(entity, FocusCause) 和 clear。DefaultPlugins 会对其进行初始化。
• 可见的文本子项会为 Button 提供推断名称，但如果可见文本不存在、仅用于装饰或含义模糊，请使用 AccessibleLabel。

另请参阅

• bevy-a11y — 完整的游戏无障碍实现。
• bevy-fluent — 本地化 UI 文本。
• bevy-cameras — UI 摄像机和渲染目标。
• bevy-ecs-queries — 变更检测。