Flame 布局系统详解:ExpandedComponent 弹性填充组件使用指南
Flame 布局系统详解:ExpandedComponent 弹性填充组件使用指南
本篇技术指南聚焦于 Flame 游戏引擎布局系统中的 ExpandedComponent(弹性填充组件),它借鉴了 Flutter Expanded 控件的行为,允许子组件在行(RowComponent)或列(ColumnComponent)等线性布局中自动占据主轴方向上的剩余空间,是构建自适应 HUD、菜单与跨屏幕 UI 的关键工具。读完本文,你将掌握 ExpandedComponent 的用法、其与父级线性布局的底层交互机制(尺寸传递、剩余空间分配算法),以及它与其他布局属性(gap、mainAxisAlignment)的相互影响与限制。
从布局组件家族说起
Flame 将 Flutter 布局系统中的"行、列、对齐、内边距、弹性填充"等概念引入游戏世界,让开发者能够以声明式方式排列组件,而不是手工计算像素坐标——这在构建 HUD、菜单或需要适配不同屏幕尺寸的 UI 时尤其重要。整个布局家族由以下五个组件构成(见 布局总览):
- AlignComponent(对齐组件)
- RowComponent(行组件)
- ColumnComponent(列组件)
- ExpandedComponent(弹性填充组件,即本文主角)
- PaddingComponent(内边距组件)
其中 ExpandedComponent 本身不做太多事情,它存在的意义是"告知"父级 LinearLayoutComponent 调整自身的计算方式,从而让自己占据主轴(main axis)上的任意空闲空间。
ExpandedComponent 是什么
ExpandedComponent 定义在 expanded_component.dart,其工作方式与 Flutter 的 Expanded 控件类似。核心约束与行为如下:
- 必须是线性布局的直接子级:它通过
ParentIsA<LinearLayoutComponent>约束自身,只能作为RowComponent、ColumnComponent(或LinearLayoutComponent.fromDirection生成的行/列)的直接子组件使用。 - 不参与收缩包裹:
ExpandedComponent自身永远不会尝试 shrink-wrap(收缩包裹)。它只向父级报告intrinsicSize(固有尺寸),并从父级接收尺寸信息。 - 依赖父级分配尺寸:它本身不主动计算大小,而是等待父级在布局时通过
setLayoutAxisLength把主轴长度写入它。 - shrink-wrap 时失效:如果父级
LinearLayoutComponent在主轴上处于 shrink-wrap 模式(即size传了null),则ExpandedComponent不会展开,尺寸退化为其子组件的固有尺寸。
典型用法示例
以下代码(来自 源码注释)展示了在一个 ColumnComponent 中使用 ExpandedComponent 让某个子组件撑满剩余垂直空间:
ColumnComponent(
children: [
ExpandedComponent(
child: TextComponent(text: 'foo'),
);
TextComponent(text: 'bar')
],
);
foo 文本组件会占据列方向上的所有剩余空间,而 bar 保持其固有高度。
构造函数与参数详解
ExpandedComponent 的构造函数(见 expanded_component.dart)如下:
ExpandedComponent({
super.key,
super.position,
super.anchor,
super.priority,
super.inflateChild = true,
super.child,
}) : super(size: null);
各参数含义:
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
key |
ComponentKey? |
null |
组件的键,用于在子组件树中查找与区分 |
position |
Vector2? |
null |
组件位置,由父级布局覆盖 |
anchor |
Anchor? |
默认 | 组件的锚点(定位参考点) |
priority |
int |
默认 | 渲染优先级 |
inflateChild |
bool |
true |
是否让内部布局机制同步修改子组件的尺寸 |
child |
PositionComponent? |
null |
被弹性填充的子组件 |
注意构造函数将 size 硬编码为 null——这正是"不收缩包裹、等待父级分配尺寸"的实现方式:在 LayoutComponent 基类中,layoutSize 为 null 意味着该轴使用 intrinsicSize,而 ExpandedComponent 的 size 会被父级布局直接写入。
底层机制:LayoutComponent 与 SingleLayoutComponent
要真正理解 ExpandedComponent,需要先了解它的两条继承/混入链:
-
LayoutComponent(定义于 layout_component.dart)是 Flame 布局系统的抽象基类,它引入了两个关键概念:layoutSizeX/layoutSizeY:显式设定的布局尺寸(可为null)。resetSize()会把size重置为layoutSize ?? intrinsicSize。intrinsicSize:作为容器能够容纳子组件的最小可能尺寸。setLayoutAxisLength(LayoutAxis axis, double? value):只修改单个轴的长度。与setLayoutSize(同时设置两轴、只触发一次 size 监听)不同,setLayoutAxisLength用于选择性设置宽度或高度,这是ExpandedComponent接收父级尺寸写入的入口。isShrinkWrappedIn(LayoutAxis axis):判断某轴是否处于收缩包裹模式(layoutSize == null)。layoutChildren():刷新布局的入口,由子组件增删、自身或子组件尺寸变化等事件触发。
-
SingleLayoutComponent(定义于 single_layout_component.dart)是面向"单子组件"布局的抽象类(ExpandedComponent与PaddingComponent都继承它)。它负责:- 管理唯一的
child:设置child会自动把旧子组件从父级移除、并挂载新子组件。 - 提供
inflateChild标志,决定布局机制是否修改子组件尺寸;syncChildSize()会在inflateChild == true时把子组件尺寸同步为availableSize。 intrinsicSize直接定义为child?.size ?? Vector2.zero(),即固有尺寸就是子组件的尺寸。
- 管理唯一的
核心原理:尺寸如何从父级流向子级
ExpandedComponent 覆盖了两个关键方法(见 expanded_component.dart):
@override
void setLayoutAxisLength(LayoutAxis axis, double? value) {
super.setLayoutAxisLength(axis, value);
final child = this.child;
if (inflateChild && child != null && value != null) {
// We want to set the child's size.
if (child is LayoutComponent) {
child.setLayoutAxisLength(axis, value);
} else {
child.size[axis.axisIndex] = value;
}
}
}
@override
void layoutChildren() {
resetSize();
parent.layoutChildren();
}
setLayoutAxisLength的级联:父级把主轴长度写入ExpandedComponent后,它会立刻把同一长度级联写入自己的子组件——若子组件本身是LayoutComponent(如嵌套的布局),则调用其setLayoutAxisLength;否则直接设置child.size对应轴的值。这一机制保证了弹性区域内的内容被真正"拉伸"。layoutChildren的委托:它先resetSize()再调用parent.layoutChildren(),即把布局计算交还给父级线性布局完成。父级据此重新计算每个子组件的位置与尺寸,实现"接收父级尺寸信息"的定位方式。
父级如何分配剩余空间:_mainAxisSizing 算法
当父级 LinearLayoutComponent 执行主轴布局时,会通过 _mainAxisSizing(见 linear_layout_component.dart)处理所有 ExpandedComponent:
可用剩余空间 = 布局尺寸 - 非弹性子组件占用空间 - 间隙总占用
每个弹性组件分得 = 剩余空间 / 弹性组件数量
算法逻辑:
- 先累计所有非
ExpandedComponent子组件在主轴上占用的空间(nonExpandingOccupiedSpace); - 计算
gapSpace = numberOfGaps * gap; - 得出
freeSpace = availableSpace - nonExpandingOccupiedSpace - gapSpace; - 若存在
freeSpace > 0且至少有一个ExpandedComponent,则把freeSpace平均分配给每个弹性组件(spacePerExpandedComponent),通过setLayoutAxisLength写入。
三个提前退出的条件值得注意(见 源码 L298-L306):
- 父级主轴处于 shrink-wrap 模式(此时分配没有意义,弹性组件退化为固有尺寸);
- 剩余空间
<= 0(没有可分配的余量); - 子组件中没有
ExpandedComponent。
测试用例 "ExpandedComponent among children are sized correctly"(见 linear_layout_component_test.dart)验证了这一分配:在一个 size: Vector2(200, 100) 的行/列中放入 CircleComponent(radius: 20)(直径 40)与 ExpandedComponent(child: RectangleComponent(size: Vector2(100, 50))) 后,弹性组件最终尺寸为:水平方向 (200 - 40, 50),垂直方向 (100, 100 - 40)——即主轴方向被拉伸填满剩余空间,交叉轴方向保持子组件原尺寸;且测试还断言 expandedComponent.child?.size == expandedComponent.size,即子组件尺寸被同步拉伸。
与其他布局属性的相互作用
ExpandedComponent 的存在会改变父级线性布局的若干行为,这些在 linear_layout_component.dart 的类注释 中有明确说明:
- 禁用 space 类对齐:一旦子组件中存在
ExpandedComponent,MainAxisAlignment.spaceAround、spaceBetween、spaceEvenly会被自动禁用(见gapgetter 的守卫条件),子组件之间的间距完全由gap决定。原因在于弹性组件会填满所有可用空间,space 类对齐已无意义。 - shrink-wrap 模式下的行为:当父级主轴 shrink-wrap 时,
mainAxisAlignment表现得如同MainAxisAlignment.start,ExpandedComponent不再展开、尺寸等于其intrinsicSize(即子组件尺寸)。 - gap 的计算:
gapgetter 在存在ExpandedComponent或对齐方式不属于 space 类时会直接返回_gap;否则会根据未占用空间与间隔数量动态计算间隔。
使用建议与注意事项
- Experimental 状态:
ExpandedComponent及其所在布局 API 目前处于实验阶段(源码顶部标注 "Warning: Experimental. API and behavior may change."),引入前需评估 API 变动的风险。 - 必须直接挂在行/列下:
ParentIsA<LinearLayoutComponent>保证了运行时约束,但务必把它作为RowComponent/ColumnComponent的直接子组件使用。 - 组合多个弹性组件:多个
ExpandedComponent会平分剩余空间,适合实现"一侧固定、另一侧均分"的典型 UI 布局。 - 配合
gap使用:弹性组件之间或弹性组件与普通子组件之间的间距由gap控制,而不是对齐属性。 - 嵌套布局:
ExpandedComponent的子组件可以是另一个LayoutComponent(如嵌套的行/列),此时尺寸会通过setLayoutAxisLength继续向下传递,可实现复杂的分层 UI。