Flutter自动生成资源引用插件flutter_gen的使用

Flutter应用程序中管理资源（如图片、字体和颜色）通常需要在代码中直接引用资源路径。这种方式不仅容易出错，而且不利于维护。flutter_gen 插件通过自动生成 Dart 文件来安全地引用这些资源，从而解决了这些问题。

Motivation

直接使用字符串形式的资源路径是不安全的。例如，在pubspec.yaml文件中定义了一个图片资源：

# pubspec.yaml
flutter:
  assets:
    - assets/images/profile.jpg

如果在代码中拼写错误了路径，将会导致运行时错误：

// 错误示例
Widget build(BuildContext context) {
  return Image.asset('assets/images/profile.jpeg'); // 这里应该是 .jpg 而不是 .jpeg
}

使用 flutter_gen 可以避免这种情况，它会生成一个类型安全的 API 来引用资源：

// 正确示例
Widget build(BuildContext context) {
  return Assets.images.profile.image();
}

Installation

Homebrew (macOS 和 Linux)

brew install FlutterGen/tap/fluttergen

asdf (macOS 和 Linux)

asdf plugin add fluttergen https://github.com/FlutterGen/asdf-fluttergen.git
asdf install fluttergen latest

Pub Global (macOS, Linux 和 Windows)

dart pub global activate flutter_gen

确保你已经配置了你的 PATH 环境变量以包含全局安装的脚本。

As a part of build_runner

1. 在 pubspec.yaml 中添加依赖项：

   dev_dependencies:
     build_runner:
     flutter_gen_runner:
   

2. 安装依赖项：

   flutter pub get
   

3. 使用 flutter_gen：

   dart run build_runner build
   

Usage

在配置好 pubspec.yaml 后，可以通过命令行运行 fluttergen 来生成资源引用代码：

fluttergen -c example/pubspec.yaml

Configuration File

flutter_gen 根据 pubspec.yaml 文件中的 flutter 和 flutter_gen 配置项生成 Dart 文件。默认配置可以在 这里 查看。

# pubspec.yaml 示例
flutter_gen:
  output: lib/gen/
  line_length: 80

  integrations:
    flutter_svg: true
    flare_flutter: true
    rive: true
    lottie: true

  colors:
    inputs:
      - assets/color/colors.xml

flutter:
  uses-material-design: true
  assets:
    - assets/images/

  fonts:
    - family: Raleway
      fonts:
        - asset: assets/fonts/Raleway-Regular.ttf
        - asset: assets/fonts/Raleway-Italic.ttf
          style: italic

Available Parsers

Assets

对于图像和其他类型的静态资源，只需要按照 官方文档 的说明指定资源，flutter_gen 将自动生成相关 Dart 文件。例如：

# pubspec.yaml
flutter:
  assets:
    - assets/images/chip.jpg
    - assets/images/icons/paint.svg
    - assets/json/fruits.json

这将生成 lib/gen/assets.gen.dart 文件。

Fonts

定义自定义字体也很简单：

# pubspec.yaml
flutter:
  fonts:
    - family: Raleway
      fonts:
        - asset: assets/fonts/Raleway-Regular.ttf
        - asset: assets/fonts/Raleway-Italic.ttf
          style: italic

Colors

从 XML 文件中读取颜色信息并生成对应的 Dart 类：

# pubspec.yaml
flutter_gen:
  colors:
    inputs:
      - assets/color/colors.xml

Example Code

以下是一个完整的示例应用，展示了如何使用 flutter_gen 自动生成的资源引用：

import 'package:flutter/material.dart';
import 'gen/assets.gen.dart';
import 'gen/colors.gen.dart';
import 'gen/fonts.gen.dart';

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

class MyApp extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'Flutter Demo',
      theme: ThemeData(
        fontFamily: FontFamily.raleway,
        primarySwatch: ColorName.crimsonRed,
      ),
      home: Scaffold(
        appBar: AppBar(
          title: Text('FlutterGen'),
        ),
        body: Center(
          child: Column(
            mainAxisAlignment: MainAxisAlignment.center,
            children: [
              SizedBox(
                width: 200,
                height: 200,
                child: Assets.flare.penguin.flare(
                  animation: 'walk',
                  fit: BoxFit.contain,
                ),
              ),
              Assets.images.chip1.image(),
              Container(
                height: 400,
                decoration: BoxDecoration(
                  image: DecorationImage(
                    image: Assets.images.chip1.provider(),
                  ),
                ),
                child: Center(child: Text('Deco')),
              ),
              Assets.images.icons.paint.svg(
                width: 120,
                height: 120,
              ),
              Text(
                'Hi there, I\'m FlutterGen',
                style: TextStyle(
                  color: ColorName.black60,
                  fontFamily: FontFamily.robotoMono,
                  fontFamilyFallback: [FontFamily.raleway],
                ),
              ),
            ],
          ),
        ),
      ),
    );
  }
}

以上代码片段展示了如何利用 flutter_gen 自动生成的资源类来构建一个简单的 Flutter 应用程序。通过这种方式，我们可以更方便地管理和引用项目中的各种资源，同时减少了由于手动输入路径而可能出现的错误。