Flutter未知功能插件rabbit的使用（由于介绍为undefined，故以“未知功能”代替）

Flutter未知功能插件rabbit的使用（由于介绍为undefined，故以“未知功能”代替）

Rabbit 帮助你快速且一致地创建这些包装小部件，同时保留原始小部件的所有参数，允许你自定义所需的部分。

例如，给定一个 Container 小部件：

Container(
  color: Colors.red,
  child: child,
)

生成一个 RedContainer 小部件来封装这种样式，并在整个应用程序中重用它：

RedContainer(
  child: child,
)

目录

• Rabbit
• Table of Contents
• Requirements
• Installation
• Getting Started
• Configuration Options
  • Example Configuration
  • Widgets
  • Output Directory
  • Prefix
  • Documentation
  • Pipeable Extensions
• Multiple Constructors
• Known Limitations
• Maintaining Generated Code
• Common Use Cases
  • Theming Widgets
  • Adding Default Behaviors
• Best Practices
  • When to Use Wrappers
  • When Not to Use Wrappers
  • Naming Conventions
• Complaints

需求

• Flutter 3.22.0 或更高版本

安装

在项目依赖中添加 Rabbit：

dart pub add rabbit

或者手动添加到 pubspec.yaml 文件中：

dependencies:
  rabbit: ^latest_version

然后运行：

dart pub get

入门

在这个例子中，我们将生成一个 RedContainer 小部件，该小部件与 Container 小部件相同，但具有红色背景颜色。

1. 在 pubspec.yaml 中配置你的小部件包装器：

rabbit:
  widgets:
    package:flutter/material.dart:
      - Container

有关完整的配置选项，请参见 配置 部分。

1. 运行生成命令：

dart run rabbit generate

这将在默认输出目录中生成一个 $Container 小部件。

1. 查找生成的小部件并根据需要进行自定义。

class RedContainer extends StatelessWidget {
  
  final AlignmentGeometry? alignment;
  final EdgeInsetsGeometry? padding;
  // ... 和其余的 Container 属性

  const RedContainer({
    super.key,
    this.alignment,
    this.padding,
    // ... 和其余的 Container 属性
  });

  @override
  Widget build(BuildContext context) {
    return Container(
      color: Colors.red,
      alignment: alignment,
      padding: padding,
      // ... 和其余的 Container 属性
    );
  }
}

现在你可以像使用 Container 小部件一样使用 RedContainer 小部件。

1. （可选）重命名生成的文件： 将生成的文件重命名为 red_container.dart 以便更好的可读性和导入语句。

配置选项

可以在 pubspec.yaml 下的 rabbit 键下配置以下选项：

示例配置

rabbit:
  output_dir: lib/src/widgets
  prefix: My
  docs: true
  widgets:
    package:flutter/material.dart:
      - Container
      - ElevatedButton
    package:shadcn_ui/shadcn_ui.dart:
      - ShadButton

Widgets

widgets 选项是一个映射，其中：

• 键是包导入语句
• 值是需要为其生成包装器的小部件名称列表

可以使用特殊值 all 来为包中的所有小部件生成包装器：

rabbit:
  widgets:
    package:flutter/material.dart:
      - all  # 将为所有 Material 小部件生成包装器

Output Directory

生成文件放置的目录。

rabbit:
  output_dir: lib/src/widgets  # 你的自定义路径

• 默认值：lib/src/wrapped
• 如果目录不存在，将自动创建
• 相对路径基于项目根目录解析
• 生成的小部件将匹配原始小部件的包结构

Prefix

生成的小部件名称前缀，用于避免命名冲突。

rabbit:
  prefix: My  # 将生成 MyContainer、MyButton 等等

• 默认值：$
• 可以设置为空字符串 ('') 如果你不希望有前缀

Documentation

控制是否包含原始小部件的文档注释。

rabbit:
  docs: true

• 默认值：false
• 包含参数描述、示例和其他文档
• 可能会显著增加生成文件的大小
• 在创建公共包或维护 API 文档时非常有用

Pipeable Extensions

作为实验性功能，Rabbit 可以为小部件生成管道扩展。这允许你使用这个运算符 (>>) 链接小部件属性，而不是嵌套构造函数。

final widget = $Container()
  >> $Padding(padding: EdgeInsets.all(16))
  >>> Text('Hello, World!');

请参阅这个提议，这个功能就是受此提议启发的。

多个构造函数

当一个小部件有多个构造函数时，Rabbit 会为每个构造函数生成一个单独的包装器。例如，对于 ListView：

// 原始 ListView 有多个构造函数：
// ListView()
// ListView.builder()
// ListView.separated()
// ListView.custom()

// Rabbit 将生成：
class $ListView extends StatelessWidget { ... }
class $ListViewBuilder extends StatelessWidget { ... }
class $ListViewSeparated extends StatelessWidget { ... }
class $ListViewCustom extends StatelessWidget { ... }

每个生成的包装器保持其对应构造函数的精确签名和功能。

已知限制

• 不支持为具有私有构造函数的小部件生成包装器
• 对于带有默认参数的小部件，这些参数在生成的代码中被设置为必需
• 不生成未带前缀类型的导入

维护生成的代码

如果 Flutter 更新更改了包装小部件的 API：

1. 备份你的定制包装器
2. 使用最新 Flutter 版本重新生成包装器：

dart run rabbit generate

1. 将自定义从备份复制到新生成的文件中

这确保你的包装器与 Flutter 的 API 更改保持同步，同时保留你的修改。

常见用例

主题化小部件

创建跨应用的一致主题化版本的小部件：

class PrimaryButton extends StatelessWidget {
  // 从 ElevatedButton 生成
  // 用主题的主色调定制
}

添加默认行为

class LoadingButton extends StatelessWidget {
  // 从 ElevatedButton 生成
  // 添加加载状态处理
}