flutter：文档注释与生成接口文档

Badge是什么

在 Flutter 里 Badge 通常指的是一种 “徽章”效果 —— 在某个组件（通常是图标）右上角显示一个小红点或者数字，用来表示未读消息、通知数量等等。

Flutter 本身的 Material 组件库 里已经自带了 Badge（从 Flutter 3.7 开始引入）。

之前很多人会用第三方库，比如 badges 包。

推荐优先使用 官方的 Badge，更轻量且未来兼容性好。

常用参数

参数名	类型	作用	示例
child	Widget	被包裹的主组件（通常是图标）	Icon(Icons.mail)
label	Widget?	徽章内容（一般是数字或点）	Text('5')
isLabelVisible	bool	是否显示徽章	false 隐藏徽章
backgroundColor	Color?	徽章背景色	Colors.red
textColor	Color?	徽章文字颜色	Colors.white
padding	EdgeInsetsGeometry?	内边距	EdgeInsets.all(4)
alignment	AlignmentGeometry?	徽章相对于 child 的位置	Alignment.topRight
offset	Offset?	相对于 alignment 的偏移	Offset(2, -2)

使用案例

import 'package:flutter/material.dart';

void main() {
  runApp(const MyApp());
}

/// 主应用入口
class MyApp extends StatelessWidget {
  const MyApp({super.key});

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'Badge 示例',
      theme: ThemeData(useMaterial3: true), // 使用 Material 3 风格
      home: const BadgeDemoPage(),
    );
  }
}

/// Badge 示例页面
class BadgeDemoPage extends StatefulWidget {
  const BadgeDemoPage({super.key});

  @override
  State<BadgeDemoPage> createState() => _BadgeDemoPageState();
}

class _BadgeDemoPageState extends State<BadgeDemoPage> {
  bool _isVisible = false; // 控制徽章是否显示
  int _count = 5; // 徽章数字（可扩展）

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text("Badge 示例")),
      body: Center(
        child: Column(
          mainAxisAlignment: MainAxisAlignment.center,
          children: [
            /// 1. 未读消息红点
            Badge(
              label: const Text(''), // 空文本 -> 显示小红点
              backgroundColor: Colors.red,
              child: const Icon(Icons.mail, size: 40),
            ),
            const SizedBox(height: 30),

            /// 2. 购物车数量
            Badge(
              label: const Text('12'),
              backgroundColor: Colors.green,
              textColor: Colors.white,
              child: const Icon(Icons.shopping_cart, size: 40),
            ),
            const SizedBox(height: 30),

            /// 3. 动态隐藏/显示徽章
            Badge(
              isLabelVisible: _isVisible, // 动态控制
              label: Text('$_count'), // 显示数字
              backgroundColor: Colors.blue,
              child: const Icon(Icons.notifications, size: 40),
            ),
            const SizedBox(height: 20),

            /// 控制按钮
            ElevatedButton(
              onPressed: () {
                setState(() {
                  _isVisible = !_isVisible; // 切换显示/隐藏
                });
              },
              child: Text(_isVisible ? "隐藏徽章" : "显示徽章"),
            ),

            const SizedBox(height: 10),

            /// 数字加一按钮（扩展玩法）
            ElevatedButton(
              onPressed: () {
                setState(() {
                  _count++; // 数字递增
                  _isVisible = true; // 确保徽章显示
                });
              },
              child: const Text("增加徽章数字"),
            ),
          ],
        ),
      ),
    );
  }
}

第一个图标：信封右上角小红点。

第二个图标：购物车右上角数字 12。

第三个图标：通知图标，可以 点击按钮动态显示/隐藏徽章，还能点按钮让数字递增。