Flame 布局系统详解:ExpandedComponent 弹性填充组件使用指南

原创2026-09-15 18:05:591,727 阅读
文章标签:游戏开发图形学跨平台3D渲染UI组件

Flame 布局系统详解:ExpandedComponent 弹性填充组件使用指南

本篇技术指南聚焦于 Flame 游戏引擎布局系统中的 ExpandedComponent(弹性填充组件),它借鉴了 Flutter Expanded 控件的行为,允许子组件在行(RowComponent)或列(ColumnComponent)等线性布局中自动占据主轴方向上的剩余空间,是构建自适应 HUD、菜单与跨屏幕 UI 的关键工具。读完本文,你将掌握 ExpandedComponent 的用法、其与父级线性布局的底层交互机制(尺寸传递、剩余空间分配算法),以及它与其他布局属性(gap、mainAxisAlignment)的相互影响与限制。

从布局组件家族说起

Flame 将 Flutter 布局系统中的"行、列、对齐、内边距、弹性填充"等概念引入游戏世界,让开发者能够以声明式方式排列组件,而不是手工计算像素坐标——这在构建 HUD、菜单或需要适配不同屏幕尺寸的 UI 时尤其重要。整个布局家族由以下五个组件构成(见 布局总览):

其中 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:

可用剩余空间 = 布局尺寸 - 非弹性子组件占用空间 - 间隙总占用
每个弹性组件分得 = 剩余空间 / 弹性组件数量

算法逻辑:

  1. 先累计所有非 ExpandedComponent 子组件在主轴上占用的空间(nonExpandingOccupiedSpace);
  2. 计算 gapSpace = numberOfGaps * gap;
  3. 得出 freeSpace = availableSpace - nonExpandingOccupiedSpace - gapSpace;
  4. 若存在 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 会被自动禁用(见 gap getter 的守卫条件),子组件之间的间距完全由 gap 决定。原因在于弹性组件会填满所有可用空间,space 类对齐已无意义。
  • shrink-wrap 模式下的行为:当父级主轴 shrink-wrap 时,mainAxisAlignment 表现得如同 MainAxisAlignment.start,ExpandedComponent 不再展开、尺寸等于其 intrinsicSize(即子组件尺寸)。
  • gap 的计算:gap getter 在存在 ExpandedComponent 或对齐方式不属于 space 类时会直接返回 _gap;否则会根据未占用空间与间隔数量动态计算间隔。

使用建议与注意事项

  1. Experimental 状态:ExpandedComponent 及其所在布局 API 目前处于实验阶段(源码顶部标注 "Warning: Experimental. API and behavior may change."),引入前需评估 API 变动的风险。
  2. 必须直接挂在行/列下:ParentIsA<LinearLayoutComponent> 保证了运行时约束,但务必把它作为 RowComponent / ColumnComponent 的直接子组件使用。
  3. 组合多个弹性组件:多个 ExpandedComponent 会平分剩余空间,适合实现"一侧固定、另一侧均分"的典型 UI 布局。
  4. 配合 gap 使用:弹性组件之间或弹性组件与普通子组件之间的间距由 gap 控制,而不是对齐属性。
  5. 嵌套布局:ExpandedComponent 的子组件可以是另一个 LayoutComponent(如嵌套的行/列),此时尺寸会通过 setLayoutAxisLength 继续向下传递,可实现复杂的分层 UI。

继续探索

登录后查看全文
flame