Flutter 组件属性速查

MaterialApp

属性：

key – Widget 的 key（Key）。
navigatorKey – 顶层导航钥匙（GlobalKey）。
scaffoldMessengerKey – ScaffoldMessenger 的 key（GlobalKey）。
title – 应用标题（String）。
onGenerateTitle – 动态生成标题的回调（BuildContext -> String）。
color – 应用主题色（Color）。
theme – 主题配置（ThemeData）。
darkTheme – 暗色主题（ThemeData）。
themeMode – 主题模式（ThemeMode）。
locale – 当前本地化信息（Locale）。
localizationsDelegates – 本地化代理列表（LocalizationsDelegate 列表）。
supportedLocales – 支持的语言列表（List）。
home – 应用的默认路由（Widget，通常为 Scaffold 或自定义页面）。
routes – 静态路由表（Map）。
initialRoute – 初始路由（String）。
onGenerateRoute – 动态路由生成器（RouteFactory）。
onUnknownRoute – 未知路由处理（RouteFactory）。
navigatorObservers – 导航观察者列表（List）。
builder – 构建顶层 Widget 的回调（WidgetBuilder）。
debugShowMaterialGrid – 是否显示网格（debug 用，bool）。
debugShowCheckedModeBanner – 是否显示 debug 横幅（bool）。
showPerformanceOverlay – 是否显示性能叠加（bool）。
checkerboardRasterCacheImages – 检查栅格缓存（bool）。
checkerboardOffscreenLayers – 检查离屏图层（bool）。
shortcuts – 快捷键映射（Map）。
actions – 动作映射（Map）。

示例：

MaterialApp(
  key: const Key('app_root'), // Widget唯一标识，用于定位/区分同类型Widget
  navigatorKey: GlobalKey<NavigatorState>(), // 全局导航键，可通过key获取NavigatorState
  scaffoldMessengerKey: GlobalKey<ScaffoldMessengerState>(), // 全局SnackBar/Toast控制键
  title: 'Flutter组件示例', // 应用标题（任务栏/切换应用时显示）
  onGenerateTitle: (context) => '动态标题', // 动态生成标题（可根据上下文/语言切换）
  color: Colors.blue, // 应用主题色（低版本兼容）
  theme: ThemeData( // 亮色主题配置
    primarySwatch: Colors.blue, // 主色调
    brightness: Brightness.light, // 亮度
  ),
  darkTheme: ThemeData(brightness: Brightness.dark), // 暗色主题
  themeMode: ThemeMode.system, // 主题模式（跟随系统/亮色/暗色）
  locale: const Locale('zh', 'CN'), // 本地化语言（中文）
  localizationsDelegates: const [ // 本地化代理（处理多语言）
    DefaultMaterialLocalizations.delegate,
    DefaultWidgetsLocalizations.delegate,
  ],
  supportedLocales: const [ // 支持的语言列表
    Locale('zh', 'CN'),
    Locale('en', 'US'),
  ],
  home: const Scaffold(body: Center(child: Text('首页'))), // 默认首页
  routes: { // 静态路由表
    '/second': (context) => const Scaffold(body: Text('第二页')),
  },
  initialRoute: '/', // 初始路由（配合routes使用）
  onGenerateRoute: (settings) { // 动态路由生成（处理未在routes定义的路由）
    if (settings.name == '/dynamic') {
      return MaterialPageRoute(builder: (context) => const Text('动态页面'));
    }
    return null;
  },
  onUnknownRoute: (settings) { // 未知路由（404页面）
    return MaterialPageRoute(builder: (context) => const Text('页面不存在'));
  },
  navigatorObservers: [ // 导航观察者（监听页面跳转）
    NavigatorObserver(),
  ],
  builder: (context, child) { // 全局Widget包装（如添加全局遮罩）
    return child!;
  },
  debugShowMaterialGrid: false, // Debug模式是否显示Material网格（辅助布局）
  debugShowCheckedModeBanner: false, // 隐藏Debug横幅
  showPerformanceOverlay: false, // 显示性能叠加层（调试性能）
  checkerboardRasterCacheImages: false, // 栅格缓存图片棋盘化（调试渲染）
  checkerboardOffscreenLayers: false, // 离屏图层棋盘化（调试渲染）
  shortcuts: const { // 快捷键映射（桌面端）
    LogicalKeySet(LogicalKeyboardKey.control, LogicalKeyboardKey.keyS): SaveIntent(),
  },
  actions: { // 快捷键对应动作
    SaveIntent: CallbackAction<SaveIntent>(onInvoke: (intent) => print('保存')),
  },
);

// 自定义Intent（快捷键示例用）
class SaveIntent extends Intent {}

Scaffold

说明：Scaffold 提供了基本的 Material 页面结构：AppBar、Body、Drawer、FloatingActionButton 等。

属性：

key – Widget 的 key（Key）。
appBar – 顶部应用栏（通常为 AppBar）。
body – 页面主体（Widget）。
floatingActionButton – 悬浮按钮（FloatingActionButton）。
floatingActionButtonLocation – 悬浮按钮位置（FloatingActionButtonLocation）。
floatingActionButtonAnimator – 悬浮按钮动画器（FloatingActionButtonAnimator）。
persistentFooterButtons – 持续显示的底部按钮（List）。
drawer – 抽屉（Drawer）。
endDrawer – 右侧抽屉（Drawer）。
bottomNavigationBar – 底部导航栏（Widget）。
bottomSheet – 底部弹出（Widget）。
backgroundColor – 背景色（Color）。
resizeToAvoidBottomInset – 键盘弹出时是否调整（bool）。
primary – 是否为主 Scaffolding（bool）。
drawerDragStartBehavior – 抽屉拖动行为（DragStartBehavior）。
extendBody – 是否扩展 body 到底部（bool）。
extendBodyBehindAppBar – 是否延伸到 appBar 后（bool）。

示例：

Scaffold(
  key: const Key('page_scaffold'), // Widget唯一标识
  appBar: AppBar( // 顶部应用栏
    title: const Text('Scaffold示例'), // 标题
    leading: const Icon(Icons.menu), // 左侧图标
    actions: const [Icon(Icons.search)], // 右侧操作图标
  ),
  body: const Center(child: Text('页面主体内容')), // 页面主体
  floatingActionButton: FloatingActionButton( // 悬浮按钮
    onPressed: () {}, // 点击事件
    child: const Icon(Icons.add), // 按钮图标
  ),
  floatingActionButtonLocation: FloatingActionButtonLocation.endFloat, // 悬浮按钮位置（右下角）
  floatingActionButtonAnimator: FloatingActionButtonAnimator.scaling, // 悬浮按钮动画
  persistentFooterButtons: const [ // 底部固定按钮（始终显示）
    TextButton(onPressed: () {}, child: Text('按钮1')),
    TextButton(onPressed: () {}, child: Text('按钮2')),
  ],
  drawer: Drawer( // 左侧抽屉
    child: ListView(
      children: const [DrawerHeader(child: Text('侧边栏'))],
    ),
  ),
  endDrawer: Drawer(child: const Text('右侧抽屉')), // 右侧抽屉
  bottomNavigationBar: BottomNavigationBar( // 底部导航栏
    items: const [
      BottomNavigationBarItem(icon: Icon(Icons.home), label: '首页'),
      BottomNavigationBarItem(icon: Icon(Icons.settings), label: '设置'),
    ],
    currentIndex: 0, // 当前选中项
    onTap: (index) {}, // 切换事件
  ),
  bottomSheet: const SizedBox( // 底部弹出层
    height: 50,
    child: Center(child: Text('底部弹窗')),
  ),
  backgroundColor: Colors.grey[100], // 页面背景色
  resizeToAvoidBottomInset: true, // 键盘弹出时自动调整布局（避免被遮挡）
  primary: true, // 是否为顶级Scaffold（占用状态栏空间）
  drawerDragStartBehavior: DragStartBehavior.start, // 抽屉拖动触发方式
  extendBody: true, // 主体延伸到底部导航栏下方（透明导航栏时用）
  extendBodyBehindAppBar: true, // 主体延伸到AppBar下方（透明AppBar时用）
);

状态更新 – setState

说明：setState 用于在 StatefulWidget 中更新状态并触发界面重建。

属性：

无 – 此为行为 API，属于 State 类的方法，用于触发重建。

示例：

class CounterWidget extends StatefulWidget {
  @override
  _CounterWidgetState createState() => _CounterWidgetState();
}

class _CounterWidgetState extends State<CounterWidget> {
  int _count = 0; // 内部状态

  void _increment() {
    setState(() {
      // 在这里修改状态，框架会重新调用 build
      _count++;
    });
  }

  @override
  Widget build(BuildContext context) {
    return Column(
      children: [
        Text('count: \\$_count'),
        ElevatedButton(onPressed: _increment, child: Text('Increment')),
      ],
    );
  }
}

Container

说明：Container 是通用容器，可设置尺寸、边距、内边距、背景、边框、对齐等。

属性：

key – Widget 的 key（Key）。
alignment – 子组件对齐方式（Alignment）。
padding – 内边距（EdgeInsets）。
color – 背景色（Color，只有当 decoration 为 null 时生效）。
decoration – 装饰（Decoration，例如 BoxDecoration，可设置 color、borderRadius、border 等）。
foregroundDecoration – 前景装饰（Decoration）。
width – 宽度（double）。
height – 高度（double）。
constraints – 大小约束（BoxConstraints）。
margin – 外边距（EdgeInsets）。
transform – 变换矩阵（Matrix4）。
transformAlignment – 变换对齐点（Alignment）。
clipBehavior – 裁剪行为（Clip）。

示例：

Container(
  key: const Key('custom_container'), // Widget唯一标识
  alignment: Alignment.center, // 子组件对齐方式（居中）
  padding: const EdgeInsets.all(16), // 内边距（上下左右16px）
  // color: Colors.red, // 背景色（与decoration互斥，二选一）
  decoration: BoxDecoration( // 装饰器（比color功能更丰富）
    color: Colors.blue, // 背景色
    borderRadius: BorderRadius.circular(12), // 圆角
    border: Border.all(color: Colors.black, width: 2), // 边框
    boxShadow: const [ // 阴影
      BoxShadow(color: Colors.grey, blurRadius: 5, offset: Offset(2, 2)),
    ],
  ),
  foregroundDecoration: const BoxDecoration( // 前景装饰（覆盖在子组件上）
    color: Color.fromRGBO(255, 255, 255, 0.2), // 半透明遮罩
  ),
  width: 300, // 固定宽度
  height: 200, // 固定高度
  constraints: const BoxConstraints( // 尺寸约束（优先级高于width/height）
    minWidth: 100, // 最小宽度
    maxWidth: 400, // 最大宽度
    minHeight: 50, // 最小高度
    maxHeight: 300, // 最大高度
  ),
  margin: const EdgeInsets.symmetric(vertical: 10, horizontal: 20), // 外边距（上下10，左右20）
  transform: Matrix4.rotationZ(0.1), // 旋转变换（0.1弧度）
  transformAlignment: Alignment.center, // 变换的中心点
  clipBehavior: Clip.hardEdge, // 裁剪方式（超出容器部分裁剪）
  child: const Text('Container内容', style: TextStyle(color: Colors.white)), // 子组件
);

Center

说明：Center 将子组件在父布局中居中。

属性：

key – Widget 的 key（Key）。
widthFactor – 宽度因子（double，可用于对子项宽度进行缩放）。
heightFactor – 高度因子（double）。
child – 子组件（Widget）。

示例：

Center(
  key: const Key('center_widget'), // Widget唯一标识
  widthFactor: 2.0, // 宽度因子（子组件宽度*2，Center宽度=子组件宽度*2）
  heightFactor: 1.5, // 高度因子（子组件高度*1.5，Center高度=子组件高度*1.5）
  child: const Text('居中显示的文本'), // 需要居中的子组件
);

Align

说明：Align 用来更精细地对齐子组件，支持 alignment 和尺寸因子。

属性：

key – Widget 的 key（Key）。
alignment – 对齐方式（Alignment, 如 Alignment.topRight）。
widthFactor – 宽度因子（double，可用于对子项宽度进行缩放）。
heightFactor – 高度因子（double）。
child – 子组件（Widget）。

示例：

Align(
  key: const Key('align_widget'), // Widget唯一标识
  alignment: Alignment.bottomRight, // 对齐方式（右下角）
  // 也可使用精确偏移：Alignment(0.5, 0.5) 等同于center
  widthFactor: 1.0, // 宽度因子（Align宽度=子组件宽度*因子）
  heightFactor: 1.0, // 高度因子（Align高度=子组件高度*因子）
  child: const Icon(Icons.star, size: 30), // 对齐的子组件
);

Padding

说明：Padding 用于给子组件添加内边距。

属性：

key – Widget 的 key（Key）。
padding – 内边距（EdgeInsets）。
child – 子组件（Widget）。

示例：

Padding(
  key: const Key('padding_widget'), // Widget唯一标识
  // 内边距配置（多种方式）
  // 方式1：上下左右统一值
  // padding: const EdgeInsets.all(16),
  // 方式2：上下/左右分别设置
  // padding: const EdgeInsets.symmetric(vertical: 8, horizontal: 16),
  // 方式3：精确设置四个方向（左、上、右、下）
  padding: const EdgeInsets.fromLTRB(10, 20, 10, 20),
  child: const Text('带内边距的文本'), // 包裹的子组件
);

Column

说明：Column 用于垂直布局，按列排列子项。

属性：

key – Widget 的 key（Key）。
children – 子组件列表（List）。
mainAxisAlignment – 主轴对齐（MainAxisAlignment，例如 center）。
crossAxisAlignment – 交叉轴对齐（CrossAxisAlignment，例如 start）。
mainAxisSize – 主轴尺寸（MainAxisSize，min 或 max）。
textDirection – 文本方向（TextDirection）。
verticalDirection – 垂直方向（VerticalDirection）。
textBaseline – 文本基线（TextBaseline，用于对齐）。

示例：

Column(
  key: const Key('column_widget'), // Widget唯一标识
  children: const [ // 垂直排列的子组件列表
    Text('第一行文本'),
    SizedBox(height: 10), // 行间距
    Text('第二行文本'),
    Icon(Icons.check),
  ],
  mainAxisAlignment: MainAxisAlignment.center, // 主轴（垂直）对齐方式（居中）
  // 主轴对齐可选值：start(顶部)、end(底部)、spaceBetween(两端对齐)、spaceAround(均匀分布)、spaceEvenly(等分)
  crossAxisAlignment: CrossAxisAlignment.start, // 交叉轴（水平）对齐方式（左对齐）
  // 交叉轴对齐可选值：center(居中)、end(右对齐)、stretch(拉伸填满)
  mainAxisSize: MainAxisSize.min, // 主轴尺寸（min：适应子组件高度；max：填满父容器高度）
  textDirection: TextDirection.ltr, // 文本方向（从左到右）
  verticalDirection: VerticalDirection.down, // 垂直排列方向（从上到下）
  textBaseline: TextBaseline.alphabetic, // 文本基线（用于多行文本对齐）
);

Row

说明：Row 用于水平布局，按行排列子项。

属性：

key – Widget 的 key（Key）。
children – 子组件列表（List）。
mainAxisAlignment – 主轴对齐（MainAxisAlignment，例如 spaceBetween）。
crossAxisAlignment – 交叉轴对齐（CrossAxisAlignment）。
mainAxisSize – 主轴尺寸（MainAxisSize）。
textDirection – 文本方向（TextDirection）。
verticalDirection – 垂直方向（VerticalDirection）。
textBaseline – 文本基线（TextBaseline）。

示例：

Row(
  key: const Key('row_widget'), // Widget唯一标识
  children: const [ // 水平排列的子组件列表
    Icon(Icons.menu),
    SizedBox(width: 10), // 列间距
    Text('标题文本'),
    Spacer(), // 自动填充剩余空间
    Icon(Icons.search),
  ],
  mainAxisAlignment: MainAxisAlignment.spaceBetween, // 主轴（水平）对齐方式（两端对齐）
  crossAxisAlignment: CrossAxisAlignment.center, // 交叉轴（垂直）对齐方式（居中）
  mainAxisSize: MainAxisSize.max, // 主轴尺寸（max：填满父容器宽度；min：适应子组件宽度）
  textDirection: TextDirection.ltr, // 文本方向（从左到右）
  verticalDirection: VerticalDirection.down, // 垂直方向（影响交叉轴对齐）
  textBaseline: TextBaseline.alphabetic, // 文本基线（用于多列文本对齐）
);

Flex 和 Expanded

说明：Flex 是 Row/Column 的底层抽象，Expanded 用来在主轴上扩展占用剩余空间。

属性：

key – Widget 的 key（Key）。
flex – 权重（int，常用于 Expanded 或 Flexible）。
fit – 适配方式（FlexFit）。

示例：

Flex(
  key: const Key('flex_widget'), // Widget唯一标识
  direction: Axis.horizontal, // 排列方向（horizontal=Row，vertical=Column）
  children: [
    // Expanded：占主轴剩余空间（核心属性flex为权重）
    Expanded(
      flex: 1, // 权重1（总权重=1+2=3，占1/3宽度）
      child: Container(
        height: 50,
        color: Colors.red,
        alignment: Alignment.center,
        child: const Text('1份', style: TextStyle(color: Colors.white)),
      ),
    ),
    Expanded(
      flex: 2, // 权重2（占2/3宽度）
      fit: FlexFit.tight, // 强制填满分配的空间（默认）
      child: Container(
        height: 50,
        color: Colors.green,
        alignment: Alignment.center,
        child: const Text('2份', style: TextStyle(color: Colors.white)),
      ),
    ),
  ],
);

Wrap

说明：Wrap 是换行布局，超出会换行，类似 CSS 的 flex-wrap。

属性：

key – Widget 的 key（Key）。
direction – 方向（Axis.horizontal/vertical）。
alignment – 对齐（WrapAlignment）。
spacing – 子项间水平间距（double）。
runSpacing – 行间距（double）。
runAlignment – 行对齐（WrapAlignment）。
crossAxisAlignment – 交叉轴对齐（WrapCrossAlignment）。
textDirection – 文本方向（TextDirection）。
verticalDirection – 垂直方向（VerticalDirection）。
clipBehavior – 裁剪行为（Clip）。

示例：

Wrap(
  key: const Key('wrap_widget'), // Widget唯一标识
  direction: Axis.horizontal, // 排列方向（水平）
  alignment: WrapAlignment.start, // 主轴对齐方式（左对齐）
  spacing: 8.0, // 子组件之间的水平间距
  runSpacing: 4.0, // 行与行之间的垂直间距
  runAlignment: WrapAlignment.center, // 行对齐方式（居中）
  crossAxisAlignment: WrapCrossAlignment.center, // 交叉轴对齐方式（居中）
  textDirection: TextDirection.ltr, // 文本方向
  verticalDirection: VerticalDirection.down, // 垂直排列方向
  clipBehavior: Clip.none, // 裁剪方式（无裁剪）
  // 生成8个Chip子组件（超出宽度自动换行）
  children: List.generate(8, (index) {
    return Chip(
      label: Text('标签 $index'),
      margin: const EdgeInsets.all(2),
    );
  }),
);

Stack 和 Positioned

说明：Stack 用于叠放布局，配合 Positioned 可做绝对定位。

属性：

key – Widget 的 key（Key）。
alignment – 对齐方式（Alignment）。
textDirection – 文本方向（TextDirection）。
fit – 适配方式（StackFit）。
clipBehavior – 裁剪行为（Clip）。
children – 子组件列表（List）。

Positioned 属性：

key – Widget 的 key（Key）。
left – 距父容器左边距离（double）。
top – 距父容器顶部距离（double）。
right – 距父容器右边距离（double）。
bottom – 距父容器底部距离（double）。
width – 固定宽度（double）。
height – 固定高度（double）。

示例：

Stack(
  key: const Key('stack_widget'), // Widget唯一标识
  alignment: Alignment.center, // 默认子组件对齐方式（居中）
  textDirection: TextDirection.ltr, // 文本方向
  fit: StackFit.loose, // 子组件尺寸适配（loose：自适应；expand：填满Stack）
  clipBehavior: Clip.hardEdge, // 裁剪方式（超出Stack部分裁剪）
  children: [
    // 底层组件（背景）
    Container(
      width: 300,
      height: 200,
      color: Colors.blue[100],
    ),
    // 居中显示的文本（使用默认alignment）
    const Text('Stack底层文本'),
    // 绝对定位组件（覆盖在顶层）
    Positioned(
      key: const Key('positioned_widget'), // 唯一标识
      left: 20, // 距左侧20px
      bottom: 20, // 距底部20px
      // right: 20, // 距右侧20px（与left二选一，或同时设置固定宽度）
      // top: 20, // 距顶部20px（与bottom二选一，或同时设置固定高度）
      width: 80, // 固定宽度
      height: 40, // 固定高度
      child: ElevatedButton(
        onPressed: () {},
        child: const Text('定位按钮'),
      ),
    ),
  ],
);

Text

说明：Text 用于显示文本，支持样式与溢出处理。

属性：

key – Widget 的 key（Key）。
data – 文本内容（String，通常为第一个位置参数）。
style – 文本样式（TextStyle）。
strutStyle – 文本支撑样式（StrutStyle）。
textAlign – 对齐（TextAlign）。
textDirection – 文本方向（TextDirection）。
locale – 文本语言（Locale）。
softWrap – 是否软换行（bool）。
overflow – 溢出处理（TextOverflow，例如 ellipsis）。
textScaleFactor – 缩放因子（double）。
maxLines – 最大行数（int）。
semanticsLabel – 语义标签（String）。
textWidthBasis – 文本宽度基准（TextWidthBasis）。
textHeightBehavior – 文本高度行为（TextHeightBehavior）。

示例：

Text(
  '这是一段超长的测试文本，用于演示文本溢出处理、样式配置等属性的使用方式', // 文本内容
  key: const Key('text_widget'), // 唯一标识
  style: const TextStyle( // 文本样式
    fontSize: 16, // 字体大小
    color: Colors.black87, // 字体颜色
    fontWeight: FontWeight.bold, // 字体粗细（bold=粗体）
    fontStyle: FontStyle.italic, // 字体样式（italic=斜体）
    decoration: TextDecoration.underline, // 文本装饰（下划线）
    decorationColor: Colors.red, // 装饰线颜色
    letterSpacing: 1.0, // 字间距
    wordSpacing: 2.0, // 词间距（英文）
    height: 1.5, // 行高
  ),
  strutStyle: const StrutStyle(height: 1.5), // 文本支撑样式（统一行高）
  textAlign: TextAlign.left, // 文本对齐方式（左对齐）
  textDirection: TextDirection.ltr, // 文本方向（从左到右）
  locale: const Locale('zh', 'CN'), // 本地化（影响数字/日期格式）
  softWrap: true, // 是否自动换行（true=换行，false=不换行）
  overflow: TextOverflow.ellipsis, // 溢出处理（ellipsis=省略号，clip=裁剪，fade=渐变）
  textScaleFactor: 1.0, // 文本缩放因子（适配系统字体大小）
  maxLines: 2, // 最大显示行数
  semanticsLabel: '测试文本', // 语义标签（无障碍访问）
  textWidthBasis: TextWidthBasis.parent, // 文本宽度基准（基于父容器）
  textHeightBehavior: const TextHeightBehavior( // 文本高度行为
    applyHeightToFirstAscent: true,
    applyHeightToLastDescent: true,
  ),
);

Image

说明：Image 系列用于加载图片（asset/network/file）。

属性：

key – Widget 的 key（Key）。
image – 图片提供者（ImageProvider，如 AssetImage/NetworkImage）。
frameBuilder – 帧构建器（FrameBuilder）。
loadingBuilder – 加载构建器（LoadingBuilder）。
errorBuilder – 错误回调（ImageErrorWidgetBuilder）。
semanticLabel – 语义标签（String）。
excludeFromSemantics – 是否从语义树中排除（bool）。
width – 宽度（double）。
height – 高度（double）。
color – 颜色混合（Color）。
colorBlendMode – 颜色混合模式（BlendMode）。
fit – 填充方式（BoxFit）。
alignment – 对齐方式（Alignment）。
repeat – 重复方式（ImageRepeat）。
centerSlice – 中心切片（Rect）。
matchTextDirection – 是否根据文本方向翻转（bool）。
gaplessPlayback – 无缝播放（bool）。
isAntiAlias – 抗锯齿（bool）。
filterQuality – 过滤质量（FilterQuality）。

示例：

Image.network(
  'https://example.com/test.jpg', // 网络图片URL
  key: const Key('image_widget'), // 唯一标识
  frameBuilder: (context, child, frame, wasSynchronouslyLoaded) {
    // 图片帧构建器（可自定义加载过程UI）
    if (frame == null) return const CircularProgressIndicator(); // 加载中显示进度条
    return child;
  },
  loadingBuilder: (context, child, loadingProgress) {
    // 加载构建器（监听加载进度）
    if (loadingProgress == null) return child;
    return Center(
      child: CircularProgressIndicator(
        value: loadingProgress.expectedTotalBytes != null
            ? loadingProgress.cumulativeBytesLoaded / loadingProgress.expectedTotalBytes!
            : null,
      ),
    );
  },
  errorBuilder: (context, error, stackTrace) {
    // 加载失败UI
    return const Icon(Icons.error, color: Colors.red);
  },
  semanticLabel: '测试图片', // 语义标签（无障碍访问）
  excludeFromSemantics: false, // 是否排除在语义树外
  width: 200, // 图片宽度
  height: 150, // 图片高度
  color: Colors.grey, // 颜色混合（叠加颜色）
  colorBlendMode: BlendMode.multiply, // 颜色混合模式
  fit: BoxFit.cover, // 填充方式（cover=覆盖，contain=适应，fill=拉伸，fitWidth=适配宽度）
  alignment: Alignment.center, // 对齐方式
  repeat: ImageRepeat.noRepeat, // 重复方式（noRepeat=不重复，repeat=平铺）
  centerSlice: const Rect.fromLTRB(10, 10, 100, 100), // 中心切片（.9图拉伸用）
  matchTextDirection: false, // 是否跟随文本方向翻转
  gaplessPlayback: false, // 图片切换时是否无缝播放
  isAntiAlias: true, // 是否开启抗锯齿（提升清晰度）
  filterQuality: FilterQuality.high, // 过滤质量（high=高质量，low=低质量）
);

// 本地资源图片示例（属性与network一致，仅imageProvider不同）
// Image.asset(
//   'assets/images/test.png', // 本地资源路径（需在pubspec.yaml配置）
//   width: 200,
//   height: 150,
//   fit: BoxFit.contain,
// );

TextField

说明：TextField 是文本输入框，通常配合 TextEditingController 使用。

属性：

key – Widget 的 key（Key）。
controller – 文本控制器（TextEditingController）。
focusNode – 焦点节点（FocusNode）。
decoration – 输入装饰（InputDecoration，例如 labelText、hintText、border）。
keyboardType – 键盘类型（TextInputType）。
textInputAction – 输入动作（TextInputAction）。
textCapitalization – 自动大写（TextCapitalization）。
style – 文本样式（TextStyle）。
strutStyle – StrutStyle。
textAlign – 文本对齐（TextAlign）。
textAlignVertical – 文本垂直对齐（TextAlignVertical）。
autofocus – 自动获得焦点（bool）。
readOnly – 只读（bool）。
toolbarOptions – 工具栏选项（ToolbarOptions）。
showCursor – 是否显示光标（bool）。
obscureText – 密文（bool）。
autocorrect – 自动更正（bool）。
enableSuggestions – 启用建议（bool）。
maxLines – 最大行数（int）。
minLines – 最小行数（int）。
expands – 是否展开填满（bool）。
maxLength – 最大长度（int）。
onChanged – 文本变化回调（ValueChanged）。
onEditingComplete – 编辑完成回调（VoidCallback）。
onSubmitted – 提交回调（ValueChanged）。
inputFormatters – 输入格式化（List）。
enabled – 是否启用（bool）。
cursorWidth – 光标宽度（double）。
cursorHeight – 光标高度（double）。

示例：

// 第一步：定义文本控制器（用于控制/获取输入内容）
final TextEditingController _textController = TextEditingController(text: '初始值');
// 第二步：定义焦点节点（控制输入框焦点）
final FocusNode _focusNode = FocusNode();

// 输入框组件
TextField(
  key: const Key('text_field'), // 唯一标识
  controller: _textController, // 文本控制器（核心）
  focusNode: _focusNode, // 焦点节点
  decoration: InputDecoration( // 输入框装饰（样式）
    labelText: '用户名', // 标签文本
    hintText: '请输入用户名', // 提示文本（占位符）
    prefixIcon: const Icon(Icons.person), // 左侧图标
    suffixIcon: const Icon(Icons.clear), // 右侧图标
    border: const OutlineInputBorder( // 边框样式
      borderRadius: BorderRadius.all(Radius.circular(8)),
    ),
    enabledBorder: const OutlineInputBorder( // 未激活时边框
      borderSide: BorderSide(color: Colors.grey),
    ),
    focusedBorder: const OutlineInputBorder( // 激活时边框
      borderSide: BorderSide(color: Colors.blue),
    ),
    errorText: '输入格式错误', // 错误提示文本
    helperText: '请输入6-12位字母或数字', // 辅助说明文本
    contentPadding: const EdgeInsets.all(12), // 内边距
  ),
  keyboardType: TextInputType.text, // 键盘类型（text=文本，number=数字，email=邮箱）
  textInputAction: TextInputAction.next, // 键盘回车按钮样式（next=下一项，done=完成）
  textCapitalization: TextCapitalization.none, // 自动大写（none=不大写，words=单词首字母）
  style: const TextStyle(fontSize: 16, color: Colors.black), // 输入文本样式
  strutStyle: const StrutStyle(), // 文本支撑样式
  textAlign: TextAlign.left, // 文本对齐
  textAlignVertical: TextAlignVertical.center, // 文本垂直对齐
  autofocus: false, // 是否自动获取焦点
  readOnly: false, // 是否只读
  toolbarOptions: const ToolbarOptions( // 长按工具栏选项
    copy: true,
    cut: true,
    paste: true,
    selectAll: true,
  ),
  showCursor: true, // 是否显示光标
  cursorWidth: 2.0, // 光标宽度
  cursorHeight: 20.0, // 光标高度
  cursorColor: Colors.blue, // 光标颜色
  obscureText: false, // 是否隐藏输入（密码框用true）
  autocorrect: true, // 是否自动更正（英文）
  enableSuggestions: true, // 是否启用输入建议
  maxLines: 1, // 最大行数（1=单行，null=多行）
  minLines: 1, // 最小行数
  expands: false, // 是否填满父容器（需配合maxLines=null使用）
  maxLength: 12, // 最大输入长度（显示计数器）
  maxLengthEnforcement: MaxLengthEnforcement.enforced, // 强制限制最大长度
  onChanged: (value) { // 文本变化回调
    print('输入内容：$value');
  },
  onEditingComplete: () { // 编辑完成回调（键盘done/next）
    _focusNode.unfocus(); // 失去焦点
  },
  onSubmitted: (value) { // 提交回调（点击回车）
    print('提交内容：$value');
  },
  inputFormatters: [ // 输入格式化（限制输入内容）
    FilteringTextInputFormatter.allow(RegExp(r'[a-zA-Z0-9]')), // 仅允许字母数字
  ],
  enabled: true, // 是否启用输入框
);

// 注意：StatefulWidget中需释放资源
// @override
// void dispose() {
//   _textController.dispose();
//   _focusNode.dispose();
//   super.dispose();
// }

SingleChildScrollView

说明：SingleChildScrollView 适用于只有一个子元素但需要滚动的场景。

属性：

key – Widget 的 key（Key）。
scrollDirection – 滚动方向（Axis）。
reverse – 是否反向（bool）。
padding – 内边距（EdgeInsets）。
primary – 是否作为主滚动视图（bool）。
physics – 滚动物理（ScrollPhysics）。
controller – 滚动控制器（ScrollController）。
clipBehavior – 裁剪行为（Clip）。
child – 子组件（通常为 Column）。

示例：

SingleChildScrollView(
  key: const Key('scroll_view'), // 唯一标识
  scrollDirection: Axis.vertical, // 滚动方向（vertical=垂直，horizontal=水平）
  reverse: false, // 是否反向滚动（true=从底部/右侧开始）
  padding: const EdgeInsets.all(16), // 内边距
  primary: true, // 是否作为主滚动视图（配合Scaffold使用，处理状态栏）
  physics: const AlwaysScrollableScrollPhysics(), // 滚动物理（AlwaysScrollable=始终可滚，Bouncing=弹性）
  controller: ScrollController(), // 滚动控制器（监听/控制滚动位置）
  clipBehavior: Clip.hardEdge, // 裁剪方式
  // 子组件（通常是Column/Row，内容超出父容器时可滚动）
  child: Column(
    children: List.generate(30, (index) {
      return ListTile(
        title: Text('滚动条目 $index'),
        leading: const Icon(Icons.list),
      );
    }),
  ),
);

ListView

说明：ListView 是常用滚动列表，ListView.builder 更高效用于大量子项。

属性：

key – Widget 的 key（Key）。
scrollDirection – 滚动方向（Axis）。
reverse – 是否反向（bool）。
controller – 滚动控制器（ScrollController）。
primary – 是否作为主滚动视图（bool）。
physics – 滚动物理（ScrollPhysics）。
shrinkWrap – 是否包裹内容（bool）。
padding – 内边距（EdgeInsets）。
itemExtent – 固定子项高度（double）。
prototypeItem – 原型子项（Widget，用于测量）。
cacheExtent – 缓存范围（double）。
itemCount – 项目数量（int，builder 模式）。
itemBuilder – 构建子项的回调（IndexedWidgetBuilder）。
separatorBuilder – 分隔构建器（ListView.separated）。
addAutomaticKeepAlives – 自动保持（bool）。
addRepaintBoundaries – 重绘边界（bool）。
addSemanticIndexes – 语义索引（bool）。
semanticChildCount – 语义子项计数（int）。
dragStartBehavior – 拖动起始行为（DragStartBehavior）。
keyboardDismissBehavior – 键盘隐藏行为（ScrollViewKeyboardDismissBehavior）。
restorationId – 恢复 ID（String）。
clipBehavior – 裁剪行为（Clip）。

示例：

ListView.builder(
  key: const Key('list_view'), // 唯一标识
  scrollDirection: Axis.vertical, // 滚动方向
  reverse: false, // 是否反向滚动
  controller: ScrollController(), // 滚动控制器
  primary: false, // 是否为主滚动视图
  physics: const BouncingScrollPhysics(), // 滚动物理（iOS弹性效果）
  shrinkWrap: false, // 是否包裹内容（true=高度适应子组件，false=填满父容器）
  padding: const EdgeInsets.all(8), // 内边距
  itemExtent: 50.0, // 固定子项高度（提升性能）
  prototypeItem: const ListTile(title: Text('原型项')), // 原型子项（自动计算高度）
  cacheExtent: 100.0, // 缓存范围（预加载可视区域外100px）
  itemCount: 20, // 子项数量
  itemBuilder: (context, index) { // 子项构建器
    return ListTile(
      title: Text('列表项 $index'),
      subtitle: const Text('子标题'),
      leading: const Icon(Icons.check),
      onTap: () => print('点击了$index项'),
    );
  },
  // 分隔线构建器（ListView.separated专用）
  // separatorBuilder: (context, index) => const Divider(height: 1),
  addAutomaticKeepAlives: true, // 自动保持状态（避免重建）
  addRepaintBoundaries: true, // 添加重绘边界（提升性能）
  addSemanticIndexes: true, // 添加语义索引（无障碍）
  semanticChildCount: 20, // 语义子项数量
  dragStartBehavior: DragStartBehavior.start, // 拖动触发方式
  keyboardDismissBehavior: ScrollViewKeyboardDismissBehavior.onDrag, // 拖动时隐藏键盘
  restorationId: 'list_view_id', // 恢复ID（保存滚动位置）
  clipBehavior: Clip.hardEdge, // 裁剪方式
);

GridView

说明：GridView 用于网格布局，可通过 GridView.count 或 GridView.builder 创建。

属性：

key – Widget 的 key（Key）。
scrollDirection – 滚动方向（Axis）。
reverse – 是否反向（bool）。
controller – 滚动控制器（ScrollController）。
primary – 是否作为主滚动视图（bool）。
physics – 滚动物理（ScrollPhysics）。
shrinkWrap – 是否包裹内容（bool）。
padding – 内边距（EdgeInsets）。
gridDelegate – 网格委托（SliverGridDelegate，例如 SliverGridDelegateWithFixedCrossAxisCount）。
children – 子组件列表（List）。
cacheExtent – 缓存范围（double）。
semanticChildCount – 语义子项计数（int）。
dragStartBehavior – 拖动起始行为（DragStartBehavior）。
keyboardDismissBehavior – 键盘隐藏行为（ScrollViewKeyboardDismissBehavior）。
restorationId – 恢复 ID（String）。
clipBehavior – 裁剪行为（Clip）。

示例：

GridView.count(
  key: const Key('grid_view'), // 唯一标识
  scrollDirection: Axis.vertical, // 滚动方向
  reverse: false, // 是否反向滚动
  controller: ScrollController(), // 滚动控制器
  primary: false, // 是否为主滚动视图
  physics: const ClampingScrollPhysics(), // 滚动物理（Android阻尼效果）
  shrinkWrap: false, // 是否包裹内容
  padding: const EdgeInsets.all(8), // 内边距
  crossAxisCount: 3, // 列数（核心属性）
  crossAxisSpacing: 8.0, // 列间距
  mainAxisSpacing: 8.0, // 行间距
  childAspectRatio: 1.0, // 子项宽高比（1:1=正方形）
  // 网格委托（另一种配置方式，与count二选一）
  // gridDelegate: const SliverGridDelegateWithFixedCrossAxisCount(
  //   crossAxisCount: 3,
  //   crossAxisSpacing: 8,
  //   mainAxisSpacing: 8,
  // ),
  children: List.generate(9, (index) { // 子组件列表
    return Container(
      color: Colors.blue[100 * (index % 9)],
      alignment: Alignment.center,
      child: Text('网格项 $index'),
    );
  }),
  cacheExtent: 100.0, // 缓存范围
  semanticChildCount: 9, // 语义子项数量
  dragStartBehavior: DragStartBehavior.start, // 拖动触发方式
  keyboardDismissBehavior: ScrollViewKeyboardDismissBehavior.onDrag, // 拖动隐藏键盘
  restorationId: 'grid_view_id', // 恢复ID
  clipBehavior: Clip.hardEdge, // 裁剪方式
);

CustomScrollView

说明：CustomScrollView 可组合多个 sliver，实现复杂的滚动效果（如粘性标题、伸缩 appbar 等）。

属性（常见 Sliver）：

key – Widget 的 key（Key）。
scrollDirection – 滚动方向（Axis）。
reverse – 是否反向（bool）。
controller – 滚动控制器（ScrollController）。
primary – 是否作为主滚动视图（bool）。
physics – 滚动物理（ScrollPhysics）。
shrinkWrap – 是否包裹内容（bool）。
center – 滚动中心（Key）。
anchor – 锚点（double）。
cacheExtent – 缓存范围（double）。
restorationId – 恢复 ID（String）。
clipBehavior – 裁剪行为（Clip）。
SliverAppBar – 可伸缩的 app bar（属性如 pinned、expandedHeight）。
SliverList – 列表的 sliver 版本（使用 SliverChildDelegate）。
SliverGrid – 网格的 sliver 版本。

示例：

CustomScrollView(
  key: const Key('custom_scroll_view'), // 唯一标识
  scrollDirection: Axis.vertical, // 滚动方向
  reverse: false, // 是否反向滚动
  controller: ScrollController(), // 滚动控制器
  primary: false, // 是否为主滚动视图
  physics: const AlwaysScrollableScrollPhysics(), // 滚动物理
  shrinkWrap: false, // 是否包裹内容
  center: const Key('sliver_center'), // 滚动中心（指定sliver的key）
  anchor: 0.0, // 锚点（0=顶部，1=底部）
  cacheExtent: 100.0, // 缓存范围
  restorationId: 'custom_scroll_id', // 恢复ID
  clipBehavior: Clip.hardEdge, // 裁剪方式
  // Sliver列表（核心：组合多种滚动组件）
  slivers: [
    // 可伸缩AppBar
    SliverAppBar(
      title: const Text('CustomScrollView'),
      pinned: true, // 固定在顶部
      floating: true, // 上滑显示，下滑隐藏
      expandedHeight: 200.0, // 展开高度
      flexibleSpace: const FlexibleSpaceBar(
        background: Image(
          image: NetworkImage('https://example.com/bg.jpg'),
          fit: BoxFit.cover,
        ),
      ),
    ),
    // 网格Sliver
    SliverGrid(
      gridDelegate: const SliverGridDelegateWithFixedCrossAxisCount(
        crossAxisCount: 2,
        crossAxisSpacing: 8,
        mainAxisSpacing: 8,
        childAspectRatio: 1.5,
      ),
      delegate: SliverChildBuilderDelegate(
        (context, index) => Container(
          color: Colors.green[100 * (index % 9)],
          alignment: Alignment.center,
          child: Text('网格项 $index'),
        ),
        childCount: 6,
      ),
    ),
    // 列表Sliver
    SliverList(
      delegate: SliverChildBuilderDelegate(
        (context, index) => ListTile(
          title: Text('列表项 $index'),
          leading: const Icon(Icons.list),
        ),
        childCount: 20,
      ),
    ),
    // 分隔线Sliver
    const SliverToBoxAdapter(
      child: Divider(height: 1, color: Colors.grey),
    ),
    // 固定高度Sliver
    const SliverToBoxAdapter(
      child: SizedBox(height: 50, child: Center(child: Text('固定高度区域'))),
    ),
  ],
);

PageView

说明：PageView 用于页面翻页（轮播或分页视图）。

属性：

key – Widget 的 key（Key）。
scrollDirection – 滚动方向（Axis）。
controller – 页控制器（PageController）。
physics – 滚动物理（ScrollPhysics）。
pageSnapping – 是否自动对齐到页面（bool）。
onPageChanged – 页面变化回调（ValueChanged）。
children – 页面列表（List）。
allowImplicitScrolling – 是否允许隐式滚动（bool）。

示例：

// 第一步：定义页面控制器（控制页码/滚动）
final PageController _pageController = PageController(
  initialPage: 0, // 初始页码
  viewportFraction: 0.8, // 视口比例（0.8=每页显示80%，实现卡片轮播效果）
);

// 页面视图组件
PageView(
  key: const Key('page_view'), // 唯一标识
  scrollDirection: Axis.horizontal, // 滚动方向（horizontal=水平，vertical=垂直）
  controller: _pageController, // 页面控制器
  physics: const PageScrollPhysics(), // 滚动物理（PageScroll=翻页效果）
  pageSnapping: true, // 是否自动对齐到页面（true=翻页后居中）
  onPageChanged: (index) { // 页面切换回调
    print('当前页码：$index');
  },
  children: [ // 页面列表
    Container(
      color: Colors.red,
      alignment: Alignment.center,
      child: const Text('页面1', style: TextStyle(fontSize: 30, color: Colors.white)),
    ),
    Container(
      color: Colors.green,
      alignment: Alignment.center,
      child: const Text('页面2', style: TextStyle(fontSize: 30, color: Colors.white)),
    ),
    Container(
      color: Colors.blue,
      alignment: Alignment.center,
      child: const Text('页面3', style: TextStyle(fontSize: 30, color: Colors.white)),
    ),
  ],
  allowImplicitScrolling: false, // 是否允许隐式滚动
  // 无限轮播可配合PageView.builder使用
  // itemCount: 3,
  // itemBuilder: (context, index) => Container(...),
);

// 注意：StatefulWidget中释放控制器
// @override
// void dispose() {
//   _pageController.dispose();
//   super.dispose();
// }