Flutter插件merging_builder_svb的使用方法

Flutter插件merging_builder_svb的使用方法

在本教程中，我们将详细介绍如何使用名为merging_builder_svb的插件。请注意，由于该插件在文档中未被明确说明，我们使用“未知功能”来指代它。

引言

源代码生成已经成为构建和维护大量数据模型、数据访问对象、小部件等的重要软件开发工具。库merging_builder_svb包含以下（合成输入）构建器类：

• <MergingBuilder>读取多个输入文件，并将合并后的输出写入一个输出文件。构建器提供了按逆拓扑顺序排序输入文件的选项。
• <StandaloneBuilder>读取一个或多个输入文件，并将独立文件写入自定义位置。这里的“独立”意味着输出文件可以写入自定义文件夹，而不仅仅是扩展名，还可以配置输出文件的名称。

Flutter插件merging_builder_svb的使用

根据source_gen的示例，通常会将构建器和生成器与使用这些构建器的代码分离。

在本库提供的示例中，定义新构建器的包称为researcher_builder，而使用此构建器的包称为researcher。要设置构建系统，需要执行以下步骤：

步骤1：添加依赖项

在定义构建器的包的pubspec.yaml文件中包括merging_builder_svb和build作为依赖项。（在此示例中，生成器还需要analyzer和source_gen包。）

dependencies:
  merging_builder_svb: ^x.x.x
  build: ^x.x.x

dev_dependencies:
  analyzer: ^x.x.x
  source_gen: ^x.x.x

步骤2：创建自定义生成器

在定义构建器的包中，创建一个继承自MergingGenerator的自定义生成器。用户需要实现generateItemForAnnotatedElement和generateMergedContent方法。下面是一个示例，其中generateItemForAnnotatedElement从注释的类中读取字符串列表，generateMergedContent将数据合并并生成输出到researchers.dart文件。

import 'dart:async';
import 'package:analyzer/dart/element/element.dart';
import 'package:build/src/builder/build_step.dart';
import 'package:merging_builder_svb/merging_builder_svb.dart';
import 'package:merging_builder_svb/src/annotations/add_names.dart';
import 'package:source_gen/source_gen.dart';
import 'package:quote_buffer/quote_buffer.dart';

/// 读取注释类中的字符串并生成输出。
class AddNamesGenerator extends MergingGenerator<List<String>, AddNames> {
  /// 生成文件顶部的代码片段。
  static String get header {
    return '/// Added names.';
  }

  /// 生成文件底部的代码片段。
  static String get footer {
    return '/// This is the footer.';
  }

  @override
  List<String> generateStreamItemForAnnotatedElement(
    Element element,
    ConstantReader annotation,
    BuildStep buildStep,
  ) {
    final List<String> result = [];
    if (element is ClassElement) {
      final nameObjects =
          element.getField('names')?.computeConstantValue()?.toListValue();
      if (nameObjects != null) {
        for (final nameObj in nameObjects) {
          result.add(nameObj.toStringValue());
        }
        return result;
      }
    }
    return null;
  }

  /// 返回合并后的内容。
  @override
  FutureOr<String> generateMergedContent(Stream<List<String>> stream) async {
    final b = QuoteBuffer();
    int i = 0;
    final List<List<String>> allNames = [];
    // 迭代流：
    await for (final names in stream) {
      b.write('final name$i = [');
      b.writelnAllQ(names, separator2: ',');
      b.writeln('];');
      ++i;
      allNames.add(names);
    }

    b.writeln('');
    b.writeln('final List<List<String>> names = [');
    for (var names in allNames) {
      b.writeln('  [');
      b.writelnAllQ(names, separator2: ',');
      b.writeln('  ],');
    }
    b.writeln('];');
    return b.toString();
  }
}

步骤3：创建构建器实例

创建一个MergingBuilder实例。构建器通常放置在一个名为builder.dart的文件中，位于构建器包的lib文件夹下。

import 'package:build/build.dart';
import 'package:merging_builder_svb/merging_builder_svb.dart';

import 'src/generators/add_names_generator.dart';
import 'src/generators/assistant_generator.dart';

/// 定义一个合并构建器。
/// 支持 `input_files`，`output_file`，`header`，`footer` 和 `sort_assets` 等选项。
Builder addNamesBuilder(BuilderOptions options) {
  BuilderOptions defaultOptions = BuilderOptions({
    'input_files': 'lib/*.dart',
    'output_file': 'lib/output.dart',
    'header': AddNamesGenerator.header,
    'footer': AddNamesGenerator.footer,
    'sort_assets': true,
  });

  // 应用用户设置的选项。
  options = defaultOptions.overrideWith(options);
  return MergingBuilder<List<String>, LibDir>(
    generator: AddNamesGenerator(),
    inputFiles: options.config['input_files'],
    outputFile: options.config['output_file'],
    header: options.config['header'],
    footer: options.config['footer'],
    sortAssets: options.config['sort_assets'],
  );
}

/// 定义一个独立构建器。
Builder assistantBuilder(BuilderOptions options) {
  BuilderOptions defaultOptions = BuilderOptions({
    'input_files': 'lib/*.dart',
    'output_files': 'lib/output/assistant_(*).dart',
    'header': AssistantGenerator.header,
    'footer': AssistantGenerator.footer,
    'root': ''
  });
  options = defaultOptions.overrideWith(options);
  return StandaloneBuilder<LibDir>(
      generator: AssistantGenerator(),
      inputFiles: options.config['input_files'],
      outputFiles: options.config['output_files'],
      root: options.config['root']);
}

步骤4：配置构建器

在定义构建器的包中，添加构建器add_names_builder的配置。MergingBuilder的构建扩展必须使用合成输入的表示法指定。例如，"$lib$"表示输入文件位于lib文件夹或其子文件夹中。

builders:
  add_names_builder:
    import: "package:researcher_builder/builder.dart"
    builder_factories: ["addNamesBuilder"]
    build_extensions: {"lib/$lib$": ["lib/output.dart"]}
    auto_apply: root_package
    build_to: source
  assistant_builder:
    import: "package:researcher_builder/builder.dart"
    builder_factories: ["assistantBuilder"]
    build_extensions: {"lib/$lib$": ["*.dart"]}
    auto_apply: root_package
    build_to: source

步骤5：配置使用者

在使用自定义构建器的包中，将add_names_builder添加到已知构建器列表中。build.yaml文件如下所示。

targets:
  $default:
    builders:
      researcher_builder|add_names_builder:
        enabled: true
        options:
          input_files: 'lib/input/*.dart'
          output_file: 'lib/output/researchers.dart'
          sort_assets: false
          header: '// Header specified in build.yaml.'
          footer: '// Footer specified in build.yaml.'
      researcher_builder|assistant_builder:
        enabled: true
        options:
          input_files: 'lib/input/*.dart'
          output_files: 'lib/output/assistant_(*).dart'
          root: ''

步骤6：添加开发者依赖项

在使用构建器的包中，将researcher_builder和build_runner作为dev_dependencies添加到pubspec.yaml文件中。

name: researcher
description: 示例演示如何使用库merging_builder_svb。

environment:
  sdk: '>=2.8.1 <3.0.0'

dev_dependencies:
  build_runner: ^1.10.0
  researcher_builder:
    path: ../researcher_builder

步骤7：启动构建过程

通过运行以下命令来启动构建过程：

# pub run build_runner build --delete-conflicting-outputs --verbose