The Bevy Book

Appearance

Node 实体 ​

Bevy 的 UI 从一个组件开始：Node。和 Transform 控制世界空间中的位置一样，Node 控制 UI 元素的尺寸、布局方式和位置。但它们属于完全不同的坐标系——UI 的坐标原点在窗口左上角，Y 轴向下。

最简单的 UI 场景：一个铺满窗口的深色矩形。

rust
use bevy::prelude::*;

fn main() {
    App::new()
        .add_plugins(DefaultPlugins)
        .add_systems(Startup, setup)
        .run();
}

fn setup(mut commands: Commands) {
    commands.spawn(Camera2d);
    commands.spawn((
        Node {
            width: Val::Percent(100.0),
            height: Val::Percent(100.0),
            ..default()
        },
        BackgroundColor(Color::srgb(0.15, 0.15, 0.15)),
    ));
}

Listing 28-1：第一个 UI 实体（examples/listing-28-01.rs）

运行后你会看到一个深灰色窗口。这段代码做了三件事：

  1. Camera2d——UI 渲染需要一个 2D 相机（第 13 章讲过）。没有它，什么都看不见。
  2. Node——告诉布局引擎"我要占多大地方"。width: Val::Percent(100.0) 意味着"和父容器一样宽"，这里是窗口。
  3. BackgroundColor——给矩形填色。Node 本身没有颜色，必须搭配 BackgroundColor 才可见。

Node 自动附带的组件 ​

Node 是一个 require 组件——当你 spawn 一个带 Node 的实体时，Bevy 自动插入一组配套组件：ComputedNode（布局计算结果）、UiTransform（UI 专用变换）、BackgroundColor、BorderColor、FocusPolicy（点击穿透）、ScrollPosition、Visibility、ZIndex。你不需要手动添加它们。

尺寸：Val 枚举 ​

Node 的 width、height、padding、margin 等字段都使用 Val 枚举，支持六种单位：

变体含义示例
Val::Auto由布局引擎自动决定默认值
Val::Px(n)逻辑像素Val::Px(200.0)
Val::Percent(n)相对于父容器的百分比Val::Percent(50.0)
Val::Vw(n)视口宽度的百分比Val::Vw(10.0) = 窗口宽度的 10%
Val::Vh(n)视口高度的百分比Val::Vh(5.0) = 窗口高度的 5%
Val::VMin(n)视口较短边的百分比正方形适配利器
Val::VMax(n)视口较长边的百分比较少使用

Val::Px 是逻辑像素，会随 DPI 缩放自动乘以缩放因子——和 CSS 的 px 行为一致。

背景色与圆角 ​

BackgroundColor 接受任意 Color。配合 border_radius 可以做出圆角矩形：

rust
Node {
    width: Val::Px(200.0),
    height: Val::Px(100.0),
    border_radius: BorderRadius::all(Val::Px(12.0)),
    ..default()
},
BackgroundColor(Color::srgb(0.35, 0.5, 0.7)),

BorderRadius 也可以分别为四个角指定不同半径：BorderRadius::new(左上, 右上, 右下, 左下)。

padding 与 margin ​

padding 控制节点内部边距（内容与边框之间），margin 控制外部边距（与相邻节点之间）。两者都用 UiRect 表示四边的值：

rust
Node {
    padding: UiRect::all(Val::Px(16.0)),
    margin: UiRect {
        left: Val::Px(10.0),
        right: Val::Px(10.0),
        top: Val::Px(5.0),
        bottom: Val::Px(5.0),
    },
    ..default()
}

UiRect 提供快捷构造：UiRect::all(val) 四边相同、UiRect::horizontal(val) 左右相同、UiRect::vertical(val) 上下相同。

小结：Node + BackgroundColor + Camera2d 是 UI 的最小三件套。Val 枚举决定尺寸的表达方式，UiRect 统一表达四边间距。