GridView

GridView 以网格形式排列子组件。

构造方式速查

构造方式	适用场景	性能
`GridView()`	少量已知子组件	一般
`GridView.count()`	固定列数	一般
`GridView.extent()`	固定每项最大宽度	一般
`GridView.builder()`	大数据量，按需构建	好

构造函数

GridView — 基本构造

dart

GridView({
  Key? key,                                              // 组件标识
  Axis scrollDirection = Axis.vertical,                   // 滚动方向
  bool reverse = false,                                  // 是否反向排列
  ScrollController? controller,                           // 滚动控制器
  bool? primary,                                          // 是否使用默认控制器
  ScrollPhysics? physics,                                 // 滚动物理效果
  bool shrinkWrap = false,                                // 是否根据内容确定尺寸
  EdgeInsetsGeometry? padding,                            // 内边距
  required SliverGridDelegate gridDelegate,               // 网格布局代理（必填）
  bool addAutomaticKeepAlives = true,                     // 是否自动保持子组件存活
  bool addRepaintBoundaries = true,                       // 是否添加重绘边界
  bool addSemanticIndexes = true,                         // 是否添加语义索引
  double? cacheExtent,                                    // 预渲染区域大小
  List<Widget> children = const [],                       // 子组件列表
  int? semanticChildCount,                                // 语义子组件数量
})

GridView.count — 固定列数

dart

GridView.count({
  Key? key,                                              // 组件标识
  Axis scrollDirection = Axis.vertical,                   // 滚动方向
  bool reverse = false,                                  // 是否反向排列
  ScrollController? controller,                           // 滚动控制器
  bool? primary,                                          // 是否使用默认控制器
  ScrollPhysics? physics,                                 // 滚动物理效果
  bool shrinkWrap = false,                                // 是否根据内容确定尺寸
  EdgeInsetsGeometry? padding,                            // 内边距
  required int crossAxisCount,                             // 交叉轴（水平）列数（必填）
  double mainAxisSpacing = 0.0,                           // 主轴（垂直）间距
  double crossAxisSpacing = 0.0,                          // 交叉轴（水平）间距
  double childAspectRatio = 1.0,                          // 子组件宽高比（宽/高）
  List<Widget> children = const [],                       // 子组件列表
})

GridView.extent — 固定最大宽度

dart

GridView.extent({
  Key? key,                                              // 组件标识
  Axis scrollDirection = Axis.vertical,                   // 滚动方向
  bool reverse = false,                                  // 是否反向排列
  ScrollController? controller,                           // 滚动控制器
  bool? primary,                                          // 是否使用默认控制器
  ScrollPhysics? physics,                                 // 滚动物理效果
  bool shrinkWrap = false,                                // 是否根据内容确定尺寸
  EdgeInsetsGeometry? padding,                            // 内边距
  required double maxCrossAxisExtent,                     // 交叉轴每项最大宽度（必填）
  double mainAxisSpacing = 0.0,                           // 主轴（垂直）间距
  double crossAxisSpacing = 0.0,                          // 交叉轴（水平）间距
  double childAspectRatio = 1.0,                          // 子组件宽高比（宽/高）
  List<Widget> children = const [],                       // 子组件列表
})

GridView.builder — 按需构建（推荐大数据量）

dart

GridView.builder({
  Key? key,                                              // 组件标识
  Axis scrollDirection = Axis.vertical,                   // 滚动方向
  bool reverse = false,                                  // 是否反向排列
  ScrollController? controller,                           // 滚动控制器
  bool? primary,                                          // 是否使用默认控制器
  ScrollPhysics? physics,                                 // 滚动物理效果
  bool shrinkWrap = false,                                // 是否根据内容确定尺寸
  EdgeInsetsGeometry? padding,                            // 内边距
  required SliverGridDelegate gridDelegate,               // 网格布局代理（必填）
  required IndexedWidgetBuilder itemBuilder,              // 列表项构建器（必填）
  int? itemCount,                                         // 列表项数量
  bool addAutomaticKeepAlives = true,                     // 是否自动保持子组件存活
  bool addRepaintBoundaries = true,                       // 是否添加重绘边界
  bool addSemanticIndexes = true,                         // 是否添加语义索引
  double? cacheExtent,                                    // 预渲染区域大小
  int? semanticChildCount,                                // 语义子组件数量
})

常用属性速查

属性	类型	说明
`crossAxisCount`	`int`	`.count()` 专属：列数
`maxCrossAxisExtent`	`double`	`.extent()` 专属：每项最大宽度
`mainAxisSpacing`	`double`	主轴（垂直）间距
`crossAxisSpacing`	`double`	交叉轴（水平）间距
`childAspectRatio`	`double`	子组件宽高比（宽/高），默认 1.0 = 正方形
`scrollDirection`	`Axis`	滚动方向：`vertical` 或 `horizontal`
`padding`	`EdgeInsetsGeometry`	内边距
`shrinkWrap`	`bool`	是否根据内容确定尺寸
`physics`	`ScrollPhysics`	滚动物理效果

childAspectRatio — 宽高比

值	形状	说明
`1`	正方形	宽 = 高（默认）
`0.75`	竖长方形	宽 = 高 × 0.75（高度更大）
`1.5`	横长方形	宽 = 高 × 1.5（宽度更大）

SliverGridDelegate 速查

SliverGridDelegateWithFixedCrossAxisCount — 固定列数

dart

SliverGridDelegateWithFixedCrossAxisCount(
  crossAxisCount: 3,         // 列数
  mainAxisSpacing: 4,        // 行间距
  crossAxisSpacing: 4,       // 列间距
  childAspectRatio: 0.8,     // 宽高比（宽/高）
)

SliverGridDelegateWithMaxCrossAxisExtent — 固定最大宽度

dart

SliverGridDelegateWithMaxCrossAxisExtent(
  maxCrossAxisExtent: 200,   // 每项最大宽度
  mainAxisSpacing: 4,        // 行间距
  crossAxisSpacing: 4,       // 列间距
  childAspectRatio: 1,        // 宽高比
)

快速示例

固定列数（最常用）

dart

import 'package:flutter/material.dart';

class GridViewCountExample extends StatelessWidget {
  const GridViewCountExample({super.key});

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text('GridView.count')),
      // ─── ★ GridView.count 固定列数 ──────────────
      body: GridView.count(
        crossAxisCount: 2,        // 每行 2 列
        mainAxisSpacing: 8,       // 行间距
        crossAxisSpacing: 8,      // 列间距
        padding: const EdgeInsets.all(8),
        children: [
          Container(color: Colors.red),
          Container(color: Colors.blue),
          Container(color: Colors.green),
          Container(color: Colors.yellow),
        ],
      ),
      // ─── ☆ GridView.count 固定列数 ──────────────
    );
  }
}

大数据量（按需构建）

dart

import 'package:flutter/material.dart';

class GridViewBuilderExample extends StatelessWidget {
  const GridViewBuilderExample({super.key});

  @override
  Widget build(BuildContext context) {
    final items = List.generate(50, (i) => 'Item $i');

    return Scaffold(
      appBar: AppBar(title: const Text('GridView.builder')),
      // ─── ★ GridView.builder 按需构建 ──────────────
      body: GridView.builder(
        gridDelegate: const SliverGridDelegateWithFixedCrossAxisCount(
          crossAxisCount: 2,
          mainAxisSpacing: 8,
          crossAxisSpacing: 8,
          childAspectRatio: 1,
        ),
        itemCount: items.length,
        itemBuilder: (context, index) {
          return Container(
            color: Colors.primaries[index % Colors.primaries.length],
            child: Center(
              child: Text(
                items[index],
                style: const TextStyle(color: Colors.white, fontWeight: FontWeight.bold),
              ),
            ),
          );
        },
      ),
      // ─── ☆ GridView.builder 按需构建 ──────────────
    );
  }
}

GridView vs ListView

特性	GridView	ListView
排列方式	网格	线性列表
适用场景	图片墙、商品列表	消息列表、设置项
横向使用	也可以 `scrollDirection: Axis.horizontal`	同样支持

GridView ​

构造方式速查 ​

构造函数 ​

GridView — 基本构造 ​

GridView.count — 固定列数 ​

GridView.extent — 固定最大宽度 ​

GridView.builder — 按需构建（推荐大数据量） ​

常用属性速查 ​

childAspectRatio — 宽高比 ​

SliverGridDelegate 速查 ​

SliverGridDelegateWithFixedCrossAxisCount — 固定列数 ​

SliverGridDelegateWithMaxCrossAxisExtent — 固定最大宽度 ​

快速示例 ​

固定列数（最常用） ​

大数据量（按需构建） ​

GridView vs ListView ​

GridView

构造方式速查

构造函数

GridView — 基本构造

GridView.count — 固定列数

GridView.extent — 固定最大宽度

GridView.builder — 按需构建（推荐大数据量）

常用属性速查

childAspectRatio — 宽高比

SliverGridDelegate 速查

SliverGridDelegateWithFixedCrossAxisCount — 固定列数

SliverGridDelegateWithMaxCrossAxisExtent — 固定最大宽度

快速示例

固定列数（最常用）

大数据量（按需构建）

GridView vs ListView