Flutter网页编译器插件build_web_compilers的使用

目录

• Installation
• Usage
• Configuration
  • Compiler arguments
  • Customizing emitted file names
  • Customizing the WebAssembly loader
  • Configuring -D environment variables
  • Legacy builder options
• Manual Usage

Installation

为了在浏览器中运行代码，您需要将build_web_compilers作为开发依赖项添加到您的pubspec.yaml文件中：

dev_dependencies:
  build_web_compilers: 

Usage

如果您使用的是自动生成的构建脚本（通过dart run build_runner <command>而不是手写build.dart文件），那么只需要上面列出的dev_dependency。

Configuration

默认情况下，此包使用Dart development compiler（dartdevc，也称为DDC）将Dart编译为JavaScript。在发布构建中（使用--release运行构建工具时），则使用dart2js作为编译器。此外，该包还支持编译为WebAssembly，目前需要通过构建器选项启用dart2wasm。

Compiler arguments

要自定义编译器，您需要添加一个配置build_web_compilers:entrypoint构建器的build.yaml文件，类似于以下内容：

targets:
  $default:
    builders:
      build_web_compilers:entrypoint:
        generate_for:
          - test/**.browser_test.dart
          - web/**.dart
        options:
          compilers:
            dart2js:
              args:
                - O2
            dart2wasm:
              args:
                - O3

Customizing emitted file names

build_web_compilers生成的文件名可以根据启用的编译器进行更改，默认名称取决于启用了哪些编译器。所有名称可以通过使用loader选项或编译器选项中的extension标志进行覆盖：

targets:
  $default:
    builders:
      build_web_compilers:entrypoint:
        options:
          loader: .load.js
          compilers:
            dart2js:
              extension: .old.js
            dart2wasm:
              extension: .new.mjs

Customizing the WebAssembly loader

在某些情况下，例如针对Node.JS时，dart2wasm生成的加载程序可能不合适。可以通过将选项设置为null来禁用内置加载程序：

targets:
  $default:
    builders:
      build_web_compilers:entrypoint:
        options:
          loader: null
          compilers:
            dart2js:
            dart2wasm:

Configuring -D environment variables

为了确保每个模块的一致性构建，必须全局配置环境变量。使用YAML映射进行配置。定义的环境变量可以使用const String.fromEnvironment和const bool.fromEnvironment读取：

global_options:
  build_web_compilers:ddc:
    options:
      environment:
        SOME_VAR: some value
        ANOTHER_VAR: false

也可以在命令行上使用--define参数指定：

webdev serve -- '--define=build_web_compilers:ddc=environment={"SOME_VAR":"changed"}'

对于dart2js，可以在dart2js编译器条目内的args选项中使用：

targets:
  $default:
    builders:
      build_web_compilers:entrypoint:
        options:
          compilers:
            dart2js:
              args:
                - -DSOME_VAR=some value
                - -DANOTHER_VAR=true

要跨多个编译器应用变量，必须将其添加到每个编译器中：

targets:
  $default:
    builders:
      build_web_compilers:entrypoint:
        options:
          compilers:
            dart2js:
              args:
                - -DSOME_VAR=some value
                - -DANOTHER_VAR=true
            dart2wasm:
              args:
                - -DSOME_VAR=some value
                - -DANOTHER_VAR=true

Legacy builder options

以前版本的build_web_compilers仅支持使用compiler选项启用单个编译器。如果只想使用dart2js进行所有构建，可以使用该选项：

targets:
  $default:
    builders:
      build_web_compilers:entrypoint:
        generate_for:
          - test/**.browser_test.dart
          - web/**.dart
        options:
          compiler: dart2js
          dart2js_args:
            - -O2

同样，只使用dart2wasm编译：

targets:
  $default:
    builders:
      build_web_compilers:entrypoint:
        options:
          compiler: dart2wasm
          dart2wasm_args:
            - -O2

当未设置任何选项时，compiler选项隐式设置为在发布构建中使用dart2js，而在其他情况下使用dartdevc。请注意，当设置时，compilers选项优先于compiler选项。

Manual Usage

如果您正在使用自定义构建脚本，则需要将以下构建器应用程序添加到已有的列表中，通常位于列表末尾（除非您需要对js文件进行后处理）：

[
  apply(
    'build_web_compilers:ddc',
    [
      (_) => new ModuleBuilder(),
      (_) => new UnlinkedSummaryBuilder(),
      (_) => new LinkedSummaryBuilder(),
      (_) => new DevCompilerBuilder()
    ],
    toAllPackages(),
    // 推荐但不是必需的。这使得只有被入口点导入的模块才会被编译。
    isOptional: true,
    hideOutput: true),
  apply('build_web_compilers:entrypoint',
    // 您还可以使用`WebCompiler.Dart2Js`。如果您不关心`dartdevc`，也可以完全省略之前的构建器应用程序。
    [(_) => new WebEntrypointBuilder(WebCompiler.DartDevc)], toRoot(),
    hideOutput: true,
    // 这些通配符应仅匹配您的入口点。
    defaultGenerateFor: const InputSet(
      include: const ['web/**', 'test/**.browser_test.dart'])),
]

示例Demo

下面是一个完整的示例项目结构，演示如何使用build_web_compilers：

项目结构

my_flutter_web_app/
├── lib/
│   └── main.dart
├── web/
│   └── index.html
├── pubspec.yaml
└── build.yaml

pubspec.yaml

name: my_flutter_web_app
description: A sample Flutter web app using build_web_compilers.
publish_to: 'none' # Remove this line if you wish to publish to pub.dev
version: 1.0.0+1

environment:
  sdk: ">=2.12.0 <3.0.0"

dependencies:
  flutter:
    sdk: flutter

dev_dependencies:
  flutter_test:
    sdk: flutter
  build_runner: ^2.1.7
  build_web_compilers: ^3.5.0

flutter:
  uses-material-design: true

build.yaml

targets:
  $default:
    builders:
      build_web_compilers:entrypoint:
        generate_for:
          - web/**.dart
        options:
          compilers:
            dart2js:
              args:
                - O2
            dart2wasm:
              args:
                - O3

lib/main.dart

import 'package:flutter/material.dart';

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

class MyApp extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'Flutter Web Demo',
      theme: ThemeData(
        primarySwatch: Colors.blue,
      ),
      home: MyHomePage(title: 'Flutter Web Home Page'),
    );
  }
}

class MyHomePage extends StatefulWidget {
  MyHomePage({Key? key, required this.title}) : super(key: key);

  final String title;

  @override
  _MyHomePageState createState() => _MyHomePageState();
}

class _MyHomePageState extends State<MyHomePage> {
  int _counter = 0;

  void _incrementCounter() {
    setState(() {
      _counter++;
    });
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: Text(widget.title),
      ),
      body: Center(
        child: Column(
          mainAxisAlignment: MainAxisAlignment.center,
          children: <Widget>[
            Text(
              'You have pushed the button this many times:',
            ),
            Text(
              '$_counter',
              style: Theme.of(context).textTheme.headline4,
            ),
          ],
        ),
      ),
      floatingActionButton: FloatingActionButton(
        onPressed: _incrementCounter,
        tooltip: 'Increment',
        child: Icon(Icons.add),
      ),
    );
  }
}

web/index.html

<!DOCTYPE html>
<html>
<head>
  <meta charset="UTF-8">
  <title>Flutter Web Demo</title>
  <script defer src="main.dart.js"></script>
</head>
<body>
  <div id="my-app"></div>
</body>
</html>

通过上述配置和代码，您可以创建一个简单的Flutter Web应用程序，并使用build_web_compilers进行编译和优化。