Flutter 新手入门完全指南#

Flutter 是 Google 推出的跨平台 UI 框架，使用 Dart 语言，一套代码可以同时运行在 Android、iOS、Web 和 HarmonyOS 上。本文从零开始，带你掌握 Flutter 开发的核心知识。

一、快速开始#

创建项目#

1
flutter create --platforms web 项目名称

运行项目#

找到 lib/main.dart 中的 main 函数，点击 run 即可启动。

项目目录结构#

目录/文件	说明
`.dart_tool`	Dart 工具生成的文件缓存
`build`	构建输出目录
`lib`	项目主要源代码
`test`	测试代码
`web`	Web 平台特定配置和资源
`pubspec.yaml`	项目依赖配置文件

Flutter 中所有界面元素都是 Widget（组件）。应用从 main.dart 的 main 函数开始，runApp 函数接收一个根 Widget 来启动应用：

1
runApp(MyApp());

三、Material 组件库#

Flutter 内置了 Material Design 组件库，提供统一的视觉风格，确保在 Android、iOS、Web 等平台上保持一致的外观。

四、核心容器组件#

MaterialApp — 应用根组件#

整个应用被 MaterialApp 包裹，它是应用的入口 Widget。

1
void main(List<String> args) {
2
  runApp(
3
    MaterialApp(
4
      title: "我的 Flutter 应用",
5
      theme: ThemeData(scaffoldBackgroundColor: Colors.white),
6
      home: Scaffold(),
7
    ),
8
  );
9
}

常用属性：

title — 应用标题（可选）
theme — 应用主题
home — 应用首页

Scaffold — 页面骨架#

Scaffold 提供了页面的基本结构，包括标题栏、主体内容、底部导航栏等。

1
Scaffold(
2
  appBar: AppBar(title: Text("标题栏")),
3
  body: Container(child: Center(child: Text("主体内容"))),
4
  bottomNavigationBar: SizedBox(
5
    height: 80,
6
    child: Center(child: Text("底部区域")),
7
  ),
8
  floatingActionButton: FloatingActionButton(
9
    onPressed: () {},
10
    child: Icon(Icons.add),
11
  ),
12
  drawer: Drawer(),
13
)

常用属性：

appBar — 顶部标题栏
body — 页面主体
bottomNavigationBar — 底部导航栏
backgroundColor — 背景颜色
floatingActionButton — 浮动操作按钮
drawer — 侧边抽屉

五、自定义组件#

StatelessWidget — 无状态组件#

适用于不需要管理状态的静态 UI。内部状态不可变，只根据传入的属性渲染。

1
class MyWidget extends StatelessWidget {
2
  const MyWidget({super.key});
3

4
  @override
5
  Widget build(BuildContext context) {
6
    return MaterialApp(
7
      title: "无状态组件示例",
8
      theme: ThemeData(scaffoldBackgroundColor: Colors.red),
9
      home: Scaffold(
10
        appBar: AppBar(title: Text("标题")),
11
        body: Center(child: Text("内容")),
12
      ),
13
    );
14
  }
15
}

StatefulWidget — 有状态组件#

适用于需要管理状态的交互式组件（计数器、开关、表单等）。

创建有状态组件需要 两个类：

第一个类 — 继承 StatefulWidget，定义参数，创建 State 对象
第二个类 — 继承 State，管理可变数据和业务逻辑，实现 build 方法

1
// 第一个类：对外接口
2
class Counter extends StatefulWidget {
3
  const Counter({super.key});
4

5
  @override
6
  State<Counter> createState() => _CounterState();
7
}
8

9
// 第二个类：内部实现（下划线开头表示私有）
10
class _CounterState extends State<Counter> {
11
  int count = 0;
12

13
  @override
14
  Widget build(BuildContext context) {
15
    return Column(
16
      children: [
17
        TextButton(
18
          onPressed: () {
19
            setState(() { count--; });
20
          },
21
          child: Text("减"),
22
        ),
23
        Text("$count"),
24
        TextButton(
25
          onPressed: () {
26
            setState(() { count++; });
27
          },
28
          child: Text("加"),
29
        ),
30
      ],
31
    );
32
  }
33
}

快捷创建： 输入 stlessW 快速创建无状态组件，statefulW 快速创建有状态组件。

六、组件生命周期#

Widget 的生命周期分为三个阶段：

创建阶段 — createState() → initState() → build()
更新阶段 — didUpdateWidget() → setState() → build()
销毁阶段 — deactivate() → dispose()

七、事件处理 — GestureDetector#

GestureDetector 是功能最丰富的手势检测组件，支持点击、双击、长按等。

1
GestureDetector(
2
  onTap: () => print("单击"),
3
  onDoubleTap: () => print("双击"),
4
  onLongPress: () => print("长按"),
5
  child: Text("点击我"),
6
)

其他常用事件组件：

组件	说明
`InkWell`	带水波纹效果的点击
`TextButton`	文本按钮
`IconButton`	图标按钮
`ElevatedButton`	凸起按钮

八、状态更新 — setState#

调用 setState() 会触发 build() 重新执行，从而更新 UI：

1
class _MyState extends State<MyWidget> {
2
  int count = 0;
3

4
  @override
5
  Widget build(BuildContext context) {
6
    return Row(
7
      children: [
8
        TextButton(
9
          onPressed: () {
10
            setState(() { count--; });
11
          },
12
          child: Text("减"),
13
        ),
14
        Text("$count"),
15
        TextButton(
16
          onPressed: () {
17
            setState(() { count++; });
18
          },
19
          child: Text("加"),
20
        ),
21
      ],
22
    );
23
  }
24
}

注意： 修改变量后必须调用 setState() 才能触发 UI 更新。

九、常用基础组件#

Container — 多功能容器#

Container 是最常用的组合容器，支持设置宽高、边距、装饰、变换等。

1
Container(
2
  margin: EdgeInsets.all(20),
3
  padding: EdgeInsets.all(10),
4
  width: 200,
5
  height: 200,
6
  alignment: Alignment.center,
7
  decoration: BoxDecoration(
8
    color: Colors.blue,
9
    borderRadius: BorderRadius.circular(10),
10
    border: Border.all(width: 3, color: Colors.yellow),
11
  ),
12
  transform: Matrix4.rotationZ(0.05),
13
  child: Text("Hello", style: TextStyle(color: Colors.white)),
14
)

尺寸优先级： 明确宽高 > constraints 约束 > 父组件约束 > 自适应

注意： color 和 decoration 不能同时使用。

Center — 居中组件#

1
Center(
2
  child: Container(
3
    width: 100,
4
    height: 100,
5
    child: Center(child: Text("居中")),
6
  ),
7
)

Align — 对齐组件#

精确控制子组件在父容器中的位置：

1
Align(
2
  alignment: Alignment.bottomRight,
3
  child: Icon(Icons.star, size: 50),
4
)

Center 继承自 Align，等价于 Align(alignment: Alignment.center)。

Padding — 内边距组件#

1
Padding(
2
  padding: EdgeInsets.symmetric(vertical: 10, horizontal: 20),
3
  child: Container(color: Colors.blue),
4
)

EdgeInsets 常用方式：

EdgeInsets.all(20) — 四边相同
EdgeInsets.only(left: 10, top: 20) — 指定某一边
EdgeInsets.symmetric(vertical: 10, horizontal: 20) — 纵向/横向

Text — 文本组件#

1
Text(
2
  "这是一段很长的文本内容...",
3
  maxLines: 2,
4
  overflow: TextOverflow.ellipsis,
5
  style: TextStyle(
6
    fontSize: 20,
7
    color: Colors.blue,
8
    fontWeight: FontWeight.bold,
9
    fontStyle: FontStyle.italic,
10
    decoration: TextDecoration.underline,
11
  ),
12
)

TextSpan — 富文本#

在同一段文本中显示不同样式：

1
Text.rich(
2
  TextSpan(
3
    text: "Hello ",
4
    style: TextStyle(fontSize: 40),
5
    children: [
6
      TextSpan(text: "Flutter", style: TextStyle(color: Colors.red)),
7
      TextSpan(text: "!", style: TextStyle(color: Colors.blue)),
8
    ],
9
  ),
10
)

Image — 图片组件#

项目资源图片：

在 pubspec.yaml 中声明资源路径：

1
assets:
2
  - lib/images/

使用 Image.asset 加载：

1
Image.asset(
2
  "lib/images/logo.png",
3
  width: 300,
4
  height: 300,
5
  fit: BoxFit.cover,
6
)

网络图片：

1
Image.network(
2
  "https://example.com/image.jpg",
3
  width: 300,
4
  height: 300,
5
  fit: BoxFit.cover,
6
)

BoxFit 常用值：

值	说明
`BoxFit.cover`	填充容器，可能裁剪
`BoxFit.contain`	完整显示，可能留白
`BoxFit.fill`	拉伸填满，可能变形
`BoxFit.fitWidth`	宽度填满，高度自适应

TextField — 文本输入#

1
final TextEditingController _controller = TextEditingController();
2

3
TextField(
4
  controller: _controller,
5
  obscureText: true, // 密码模式
6
  onChanged: (value) => print("输入: $value"),
7
  onSubmitted: (value) => print("提交: $value"),
8
  decoration: InputDecoration(
9
    hintText: "请输入内容",
10
    fillColor: Colors.grey[100],
11
    filled: true,
12
    contentPadding: EdgeInsets.only(left: 20),
13
    border: OutlineInputBorder(
14
      borderRadius: BorderRadius.circular(20),
15
      borderSide: BorderSide.none,
16
    ),
17
  ),
18
)

十、布局组件#

Column — 垂直布局#

子组件从上到下排列。

1
Column(
2
  mainAxisAlignment: MainAxisAlignment.center,    // 主轴（垂直）对齐
3
  crossAxisAlignment: CrossAxisAlignment.center,  // 交叉轴（水平）对齐
4
  children: [
5
    Container(width: 50, height: 50, color: Colors.red),
6
    SizedBox(height: 10),
7
    Container(width: 50, height: 50, color: Colors.green),
8
    Container(width: 50, height: 50, color: Colors.blue),
9
  ],
10
)

MainAxisAlignment 常用值：

值	效果
`start`	顶部对齐
`center`	居中
`end`	底部对齐
`spaceBetween`	两端对齐，中间均匀分布
`spaceAround`	每个子组件两侧间距相等
`spaceEvenly`	所有间距完全相等

Row — 水平布局#

子组件从左到右排列，属性与 Column 相同。

1
Row(
2
  mainAxisAlignment: MainAxisAlignment.center,
3
  children: [
4
    Container(width: 50, height: 50, color: Colors.red),
5
    SizedBox(width: 10),
6
    Container(width: 50, height: 50, color: Colors.green),
7
  ],
8
)

Flex — 弹性布局#

Row 和 Column 都是 Flex 的特例。使用 Expanded 按比例分配空间：

1
Flex(
2
  direction: Axis.horizontal, // Axis.vertical 为垂直方向
3
  children: [
4
    Expanded(
5
      flex: 2,
6
      child: Container(color: Colors.red, height: 100),
7
    ),
8
    Expanded(
9
      flex: 1,
10
      child: Container(color: Colors.green, height: 100),
11
    ),
12
  ],
13
)

Expanded 让子组件占满剩余空间，经典三段式布局：

1
Column(
2
  children: [
3
    Container(height: 100, color: Colors.red),          // 固定高度
4
    Expanded(child: Container(color: Colors.grey)),      // 占满剩余空间
5
    Container(height: 100, color: Colors.blue),          // 固定高度
6
  ],
7
)

Wrap — 流式布局#

类似 Row，但子组件超出宽度时会自动换行，适合标签、按钮组等动态内容。

1
Wrap(
2
  spacing: 10,       // 水平间距
3
  runSpacing: 10,    // 垂直间距
4
  children: List.generate(10, (index) {
5
    return Chip(label: Text("标签 $index"));
6
  }),
7
)

Stack + Position — 层叠布局#

子组件按 Z 轴叠加，Positioned 用于精确定位（类似 CSS 的绝对定位）。

1
Stack(
2
  children: [
3
    Container(width: 200, height: 200, color: Colors.grey),
4
    Positioned(
5
      left: 10,
6
      top: 10,
7
      child: Container(width: 80, height: 80, color: Colors.red),
8
    ),
9
    Positioned(
10
      right: 10,
11
      bottom: 10,
12
      child: Container(width: 80, height: 80, color: Colors.blue),
13
    ),
14
  ],
15
)

全屏覆盖效果（适用于水印、遮罩层）：

1
Positioned(
2
  left: 0, right: 0, top: 0, bottom: 0,
3
  child: Container(color: Colors.black54),
4
)

十一、滚动组件#

SingleChildScrollView — 单子组件滚动#

包裹单个子组件使其具有滚动能力：

1
SingleChildScrollView(
2
  padding: EdgeInsets.all(10),
3
  child: Column(
4
    children: List.generate(50, (index) {
5
      return Container(
6
        margin: EdgeInsets.only(top: 10),
7
        height: 80,
8
        color: Colors.blue,
9
        child: Center(child: Text("第 $index 项")),
10
      );
11
    }),
12
  ),
13
)

滚动控制#

通过 ScrollController 控制滚动位置：

1
final ScrollController _controller = ScrollController();
2

3
// 滚动到底部
4
_controller.animateTo(
5
  _controller.position.maxScrollExtent,
6
  duration: Duration(seconds: 1),
7
  curve: Curves.ease,
8
);
9

10
// 滚动到顶部
11
_controller.animateTo(0, duration: Duration(seconds: 1), curve: Curves.ease);

ListView — 列表组件#

懒加载，只构建可见项，性能优于 SingleChildScrollView。

默认构造：

1
ListView(
2
  padding: EdgeInsets.all(10),
3
  children: List.generate(100, (index) {
4
    return ListTile(title: Text("第 $index 项"));
5
  }),
6
)

ListView.builder（推荐）：

1
ListView.builder(
2
  itemCount: 100,
3
  itemBuilder: (context, index) {
4
    return ListTile(title: Text("第 $index 项"));
5
  },
6
)

ListView.separated（带分隔线）：

1
ListView.separated(
2
  itemCount: 100,
3
  itemBuilder: (context, index) {
4
    return ListTile(title: Text("第 $index 项"));
5
  },
6
  separatorBuilder: (context, index) => Divider(height: 1),
7
)

GridView — 网格布局#

1
GridView.count(
2
  crossAxisCount: 3,       // 每行 3 列
3
  mainAxisSpacing: 10,     // 垂直间距
4
  crossAxisSpacing: 10,    // 水平间距
5
  childAspectRatio: 1.0,   // 宽高比
6
  padding: EdgeInsets.all(10),
7
  children: List.generate(30, (index) {
8
    return Container(
9
      color: Colors.blue,
10
      child: Center(child: Text("$index", style: TextStyle(color: Colors.white))),
11
    );
12
  }),
13
)

PageView — 整页翻滚#

实现分页滚动效果，常用于引导页、图片轮播：

1
PageView(
2
  children: [
3
    Container(color: Colors.red, child: Center(child: Text("第 1 页"))),
4
    Container(color: Colors.green, child: Center(child: Text("第 2 页"))),
5
    Container(color: Colors.blue, child: Center(child: Text("第 3 页"))),
6
  ],
7
)

十二、组件通信#

父传子 — 构造函数#

父组件通过构造函数将数据传给子组件。子组件用 final 声明属性，有状态组件通过 widget.属性名 访问。

1
// 父组件
2
Child(message: "张三")
3

4
// 无状态子组件
5
class Child extends StatelessWidget {
6
  final String message;
7
  const Child({super.key, required this.message});
8

9
  @override
10
  Widget build(BuildContext context) {
11
    return Text(message);
12
  }
13
}
14

15
// 有状态子组件 — 通过 widget.message 访问
16
class _ChildState extends State<Child> {
17
  @override
18
  Widget build(BuildContext context) {
19
    return Text(widget.message);
20
  }
21
}

子传父 — 回调函数#

父组件传递一个函数给子组件，子组件调用该函数将数据传回：

1
// 父组件
2
Child(
3
  title: "点击删除",
4
  onDelete: (index) {
5
    setState(() { list.removeAt(index); });
6
  },
7
)
8

9
// 子组件
10
class Child extends StatelessWidget {
11
  final String title;
12
  final Function(int) onDelete;
13
  const Child({super.key, required this.title, required this.onDelete});
14

15
  @override
16
  Widget build(BuildContext context) {
17
    return IconButton(
18
      onPressed: () => onDelete(0),
19
      icon: Icon(Icons.delete),
20
    );
21
  }
22
}

十三、网络请求 — Dio#

安装#

1
flutter pub add dio

基本用法#

1
Dio().get("https://api.example.com/data").then((value) {
2
  print(value.data);
3
}).catchError((error) {
4
  print(error);
5
});

封装 Dio 工具类#

1
class DioUtil {
2
  final Dio _dio = Dio();
3

4
  DioUtil() {
5
    _dio.options
6
      ..baseUrl = "https://api.example.com/"
7
      ..connectTimeout = Duration(seconds: 10)
8
      ..sendTimeout = Duration(seconds: 10)
9
      ..receiveTimeout = Duration(seconds: 10);
10

11
    // 拦截器
12
    _dio.interceptors.add(InterceptorsWrapper(
13
      onRequest: (options, handler) {
14
        print("请求: ${options.uri}");
15
        return handler.next(options);
16
      },
17
      onResponse: (response, handler) {
18
        print("响应: ${response.statusCode}");
19
        return handler.next(response);
20
      },
21
      onError: (error, handler) {
22
        print("错误: ${error.message}");
23
        return handler.next(error);
24
      },
25
    ));
26
  }
27

28
  Future<Response> get(String url, {Map<String, dynamic>? params}) {
29
    return _dio.get(url, queryParameters: params);
30
  }
31
}

Web 端跨域问题： Flutter Web 默认会遇到跨域限制，需要后端配置 CORS 或使用代理。

十四、路由管理#

基本路由#

使用 Navigator.push 和 Navigator.pop 进行页面跳转：

1
// 跳转到新页面
2
Navigator.push(context, MaterialPageRoute(
3
  builder: (context) => DetailPage(),
4
));
5

6
// 返回上一页
7
Navigator.pop(context);

命名路由#

在 MaterialApp 中注册路由表，使用路由名称跳转：

1
MaterialApp(
2
  routes: {
3
    '/list': (context) => ListPage(),
4
    '/detail': (context) => DetailPage(),
5
  },
6
  initialRoute: '/list',
7
)
8

9
// 跳转
10
Navigator.pushNamed(context, '/detail');
11

12
// 传递参数
13
Navigator.pushNamed(context, '/detail', arguments: {"id": 42});
14

15
// 接收参数（在 initState 中使用 Future.microtask）
16
Map<String, dynamic> params =
17
    ModalRoute.of(context)!.settings.arguments as Map<String, dynamic>;

路由拦截 — onGenerateRoute#

在路由跳转前进行拦截判断（如登录检查）：

1
MaterialApp(
2
  routes: {
3
    "/goodsList": (context) => GoodsList(),
4
    "/cartList": (context) => CartList(),
5
    "/login": (context) => LoginPage(),
6
  },
7
  initialRoute: "/goodsList",
8
  onGenerateRoute: (settings) {
9
    if (settings.name == "/cartList") {
10
      bool isLogin = false;
11
      if (isLogin) {
12
        return MaterialPageRoute(builder: (context) => CartList());
13
      } else {
14
        return MaterialPageRoute(builder: (context) => LoginPage());
15
      }
16
    }
17
    return null;
18
  },
19
)

404 处理 — onUnknownRoute#

处理未注册的路由：

1
onUnknownRoute: (settings) {
2
  return MaterialPageRoute(builder: (context) => NotFoundPage());
3
},

总结#

知识点	核心要点
Widget	Flutter 一切皆 Widget
StatelessWidget	无状态，只负责渲染
StatefulWidget	有状态，管理可变数据
setState	触发 UI 重新渲染
布局	Column/Row/Flex/Stack/Wrap
滚动	ListView/GridView/PageView
组件通信	构造函数(父→子) / 回调(子→父)
网络请求	Dio + 拦截器封装
路由	基本路由 / 命名路由 / 路由拦截

掌握了以上内容，你已经具备了 Flutter 开发的基础能力。接下来可以深入学习状态管理（Provider / Riverpod）、动画、自定义绘制等进阶主题。

追风赶月莫停留