基础容器

Container

多功能组合容器，可通过多种方式定义大小，有明确的优先级规则：

明确宽高 > constraints > 父组件约束 > 自适应组件大小

装饰系统：通过decoration属性实现视觉效果，但和color属性互斥。

属性类别	关键属性	作用说明
布局定位	`alignment`	控制其 child（子组件）在容器内部的对齐方式。
• 例如：`Alignment.center`（居中）、`Alignment.topLeft`（左上角）
尺寸控制	`width` / `height` / `constraints`	设置容器的宽度和高度 / 为容器设置更复杂的尺寸约束（如最小/最大宽高）
间距留白	`padding` / `margin`	按照比例分配剩余空间，实现自适应布局，常与 `Row` 和 `Column` 配合使用
装饰效果	`color` / `decoration`	为容器设置一个简单的背景颜色 / 为容器设置复杂的背景装饰
变换效果	`transform`	对容器及其内容进行矩阵变换
子组件	`child`	容器内包含的唯一直接子组件

Center - 居中组件

将其子组件在父容器的空间内进行水平和垂直方向上的居中排列

Center不能设置宽高，Center的最终大小取决于其父组件传递给它的约束，Center会向它的父组件申请尽可能大的空间

Align - 对齐组件

作用是精确控制其子组件在父容器空间内的对齐位置

alignment：子组件在父容器内的对齐方式
widthFactor：Align的宽度将是子组件宽度乘以该因子
heightFactor：Align的高度将是子组件高度乘以该因子

Padding

简单的内边距组件

线性布局

Column

属性	类型	作用说明
`mainAxisAlignment`	MainAxisAlignment	控制子组件在主轴（垂直方向）上的排列方式，如顶部对齐、居中或均匀分布。
`crossAxisAlignment`	CrossAxisAlignment	控制子组件在交叉轴（水平方向）上的对齐方式，如左对齐、右对齐或拉伸填满。
`mainAxisSize`	MainAxisSize	决定 Column 本身在垂直方向上的尺寸策略：是占满所有可用空间 (`max`)，还是仅仅包裹子组件内容 (`min`)。
`children`	List	需要被垂直排列的子组件列表。

Column本身不支持滚动，如果内容超出，需要使用ListView或者SinglechildScrollView包裹
明确尺寸约束，父组件的大小直接影响Column的最终大小各子组件的布局行为
避免过度嵌套，过深的嵌套会影响性能并增加代码的维护难度

Row

与Column的差异就是主轴方向不一样

弹性布局

Flex

作用是允许沿一个主轴排列其子组件，灵活地控制这些子组件在主轴上的尺寸比例和空间分配，像是两种线性分布的结合体

属性	类型	作用说明
`direction`	Axis.horizontal / Axis.vertical	主轴方向，决定子组件的排列方向
`mainAxisAlignment`	MainAxisAlignment	子组件在主轴方向上的对齐方式
`crossAxisAlignment`	CrossAxisAlignment	子组件在交叉轴方向上的对齐方式
`mainAxisSize`	MainAxisSize	Flex 容器自身在主轴上的尺寸策略

子组件：Flex的子组件常使用Expanded或Flexible来控制空间分配
Expanded / Flexible作为Flex的子组件通过flex属性来分配Flex组件空间
Flex布局受其父组件传递的约束影响，确保父组件提供了适当的布局约束
Expanded 与 Flexible 的区别：Expanded强制子组件填满所有的剩余空间，Flexible根据自身大小调整，不强制占满空间

流式布局

Warp

属性	常用值	作用说明
`direction`	Axis.horizontal (水平) / Axis.vertical (垂直)	设置主轴方向，即排列方向
`spacing`	数值	主轴方向上，子组件之间的间距
`runSpacing`	数值	交叉轴方向上，行（或列）之间的间距
`alignment`	WrapAlignment	子组件在主轴方向上的对齐方式
`runAlignment`	WrapAlignment	交叉轴方向上的对齐方式

注意：Column / Row / Flex内容超出均不会换行
Warp组件更像是Felx组件加了换行特性

List.generate是一个构造器，用于快速构建长度固定且每个元素可以通过索引号确定的列表

层叠布局

Stack / Positioned

可以做到将多个子组件按照Z轴进行叠加排列

属性	类型	作用说明
`alignment`	AlignmentGeometry	控制非定位子组件在 Stack 内的对齐方式，默认左上角
`fit`	StackFit	控制非定位子组件如何适应 Stack 的尺寸
`clipBehavior`	Clip	控制子组件超出 Stack 边界时的裁剪方式
`children`	List	需要被层叠排列的子组件列表

Positioned组件是Stack的黄金搭档，对子组件进行精确定位控制。Positioned必须作为Stack的直接子组件
Positioned通过方位属性来讲子组件“钉”在Stack的某个角落或边缘

图文组件

Text / TextSpan

属性	类型	作用说明
`data`	String	必需。要显示的文本内容
`style`	TextStyle	文本样式，可设置颜色、大小、粗细等
`textAlign`	TextAlign	文本在容器内的水平对齐方式，如 `.left`, `.center`
`maxLines`	int	文本显示的最高行数
`overflow`	TextOverflow	文本溢出处理方式

如果需要在同一段文本中显示不同的样式，可用Text.rich构造函数配合TextSpan来实现

Image

图片分类：

分类	作用说明
Image.asset()	加载项目资源目录（assets）中的图片。需要在 `pubspec.yaml` 文件中声明资源路径。
Image.network()	直接从网络地址加载图片。
Image.file()	加载设备本地存储中的图片文件。
Image.memory()	加载内存中的图片数据。

注意：Android/HarmonyOS/iOS使用Image.network需要配置网络权限

基本属性：

分类	类型	作用说明
width / height	double	设置图片显示区域的宽度和高度
fit	BoxFit	控制图片如何适应其显示区域，例如是否拉伸、裁剪或保持原比例
alignment	AlignmentGeometry	图片在其显示区域内的对齐方式，如 Alignment.center
repeat	ImageRepeat	当图片小于显示区域时，设置是否以及如何重复平铺图片

TextField

常用属性	作用说明
controller	文本编辑器控制器，用于获取、设置文档内容及监听变化
decoration	设置输入框的外观、如标签、提示文字、图标、边框等
style	定义输入文本的样式
maxLines	最大行数
onChanged	输入内容发生变化时执行的回调函数
onSubmitted	用户提交输入时的回调函数

使用：使用TextField必须使用有状态组件 使用TextEditingController管理输入内容、onChanged可以监听数据变化 decoration属性下的InputDecoration来定制如边框、背景、提示文字 obscureText设置为true可隐藏输入内容，用于密码输入框

滚动布局

常用滚动组件

组件	特点	使用场景
SingleChildScrollView	让单个子组件可以用滚动，所有内容一次性渲染	长表单、设置页、内容不固定但是总量不多的页面
ListView	线性列表，通过 builder 可以实现懒加载，性能优异	聊天记录、新闻、常见的单列滚动的数据列表
GridView	网格布局列表，支持懒加载，可以固定列数	图片墙、商品网格、应用图标列表
CustomScrollView	复杂布局方案，通过组合多个 Sliver 组件实现滚动	电商首页、社交 App 个人主页多个滚动紧密联动
PageView	整页滚动效果，支持横向和纵向	应用引导页、图片轮播图、书籍翻页

SingleChildScrollView

包裹一个子组件，让单个子组件实现滚动

controller：给组件的controller绑定ScrollController对象
子组件：只能包含一个子组件，要滚动多个组件，通常嵌套在Column或Row组件中
滚动方向：通过scrollDirection属性，默认为垂直方向，也可以设置为水平方向（Axis.horizontal）
特点：一次性构建所有子组件，如果嵌套的Column或Row组件中包含大量的子项，可能会导致性能问题，建议使用ListView
控制滚动：绑定一个ScrollController对象给controller对象，使用animateTo / jumpTo方法控制滚动

ListView

作用：用于构建可滚动列表的核心部件，并提供流程滚动体验
方式：提供多种构造函数，如默认构造函数、ListView.Bulider、ListView.Seperated
机制，采用按需渲染（懒加载），只构建当前可见区域的列表项，极大提升长列表性能

默认构造

适用于静态数量有限数据一次性构建所有的表项

builder模式

作用：处理长数据或动态数据的首选和推荐方式
方式：接受一个itemBuilder回调函数来按需构建列表项，通过itemCount控制列表长度
优势：按需构建，不会再初始化时将所有列表项都创建，而是根据用户的滚动行为，动态地创建和销毁列表项

separated模式

作用：在ListView.builder的基础上，额外提供了构建分割线的能力
方式：需要同时提供itemBuilder、separatorBuilder、itemCount三个属性

GridView

作用：用于创建二位可滚动网格布局的核心组件
方式：提供多种构建方式，GridView.count、GridView.extent、GridView.builder等
GirdView的默认构造方式写起来繁琐，很少使用
scrollDirection设置滚动方向横向 / 纵向（默认）

GridView.count

基于固定列数的网格布局（最常用之一）

GridView.extent

基于固定子项最大宽度/高度的网格布局（最常用之二）

通过maxCrossAxisExtent设置子项最大宽度/高度来计算横向或纵向由多少列

GridView.builder

用于网格项数量巨大或动态生成的情况，需要接收gridDelegate布局委托属性

gridDelegate：
SliverGridDelegateWithFixedCrossAxisCount：固定列数 mainAxisSpacing 主轴间距
SliverGridDelegateWithMaxCrossAxisExtent：最大宽度 crossAxisSpacing 交叉轴间距
itemBulider构建函数
itemCount构建数量
childAspectRatio是网格项的宽高比

自定义滚动容器 - CustomScrollView

作用：用于组合多个可滚动组件（如列表、网格），实现统一协调的滚动效果
Sliver：Flutter中描述可滚动试图内部一部分内容的组件，它是滚动试图的“切片”
用法：通过sliver属性接收一个Sliver组件列表
Sliver组件对应关系：
SliverList ⇒ ListView
SliverGrid ⇒ GridView
SliverAppBar ⇒ AppBar
SliverPadding ⇒ Padding
SliverToBoxAdapter ⇒ ToBoxAdapter
SliverPersistentHeader(粘性吸顶)

参考：

!image.png

SliverPersistentHeader - 粘性吸顶组件

给delegate属性赋值一个继承SliverPersistentHeaderDelegate的对象实例

设置固定属性pinned为true

maxExtent：展开时最大高度
minExtent：收缩时最小高度
shouldRebuild：是否重建
build：返回构建Widget

整页滚动容器 - PageView

作用：用于实现分页滚动视图的核心组件
方式：提供多种构造方式，默认构造方式，PageView.builder等

跳转控制

控制器：PageView绑定controller属性，对象类型为PageController
切换方法：controller.jumpToPage / animateToPage

Flutter容器