Flutter虚拟静态资源构建插件virtual_statics_builder的使用

介绍

virtual_statics_builder 是一个用于在 Dart 中覆盖密封类的静态字段的插件（通过生成的伴随枚举实现）。本文将详细介绍如何使用该插件。

开始使用

首先，你需要在项目的依赖中添加 virtual_statics 包，并同时添加 virtual_statics_builder 和 build_runner 到开发依赖中。

运行以下命令来添加这些依赖：

dart pub add virtual_statics dev:virtual_statics_builder dev:build_runner

使用方法

1. 准备文件

在你的文件中添加必要的注解和部分指令。然后运行 build_runner 来生成代码。

示例代码如下：

// myfile.dart

// 导入 virtual_statics 包
import 'package:virtual_statics/virtual_statics.dart';

// 添加部分指令
// 替换 'myfile' 为你正在处理的文件名
// 生成的代码将被放置在 'myfile.g.dart'
part 'myfile.g.dart';

// 在密封类上添加 @virtualStatics 注解
@virtualStatics
sealed class Animal {

  // 在静态字段上添加 @virtual 注解
  // 这个字段应该在所有子类中可用
  @virtual
  static const dbId = 0;
}

// 确保至少有一个子类
sealed class Dog extends Animal {
  // 实现标记为虚拟的方法
  // 注意你不需要在子类中添加任何注解
  // （这是因为无法使用 @override 注解...）
  static const dbId = 1;
}

运行代码生成器：

dart run build_runner build

如果遇到错误，请检查是否遗漏了需要实现的方法或注解位置是否正确。修复后重试即可。

设计原理

基本设计

• 标注密封类：你可以用 @virtualStatics 注解一个密封类，并用 @virtual 注解其上的静态字段。
• 生成枚举：如果该类被至少一个子类扩展，则会生成一个与密封类同名的枚举，每个子类对应一个变体。
• 枚举定制：可以通过 @virtualStatics 的 postFix 参数自定义枚举名称。

枚举功能

生成的枚举具有以下特性：

• 提供一个工厂方法，接受密封类的一个子类实例并返回对应的枚举变体。
• 在密封类上生成扩展，为每个密封类实例提供 .virtuals 属性以访问枚举变体。

静态字段实现

• static const 字段：可以转换为枚举上的常量字段。
• 其他字段：通过枚举上的大 switch 表达式分发到对应的子类方法。

方法参数默认值

方法的可选参数默认值不会从根密封类复制到子类，而是将参数类型设置为可选。

完整示例

以下是一个完整的示例代码，展示如何使用 virtual_statics_builder。

// animal.dart

import 'package:virtual_statics/virtual_statics.dart';

part 'animal.g.dart';

@virtualStatics
sealed class Animal {
  @virtual
  static const String species = "Unknown";

  @virtual
  static int get age => 0;
}

sealed class Dog extends Animal {
  static const String species = "Dog";
  static int get age => 5;
}

sealed class Cat extends Animal {
  static const String species = "Cat";
  static int get age => 3;
}

运行代码生成器后，生成的 animal.g.dart 文件可能类似如下：

// animal.g.dart

enum _AnimalVirtuals {
  dog,
  cat;

  factory _AnimalVirtuals.from(Animal value) {
    if (value is Dog) return _AnimalVirtuals.dog;
    if (value is Cat) return _AnimalVirtuals.cat;
    throw Exception("Unexpected value");
  }

  String get species {
    switch (this) {
      case _AnimalVirtuals.dog:
        return Dog.species;
      case _AnimalVirtuals.cat:
        return Cat.species;
    }
  }

  int get age {
    switch (this) {
      case _AnimalVirtuals.dog:
        return Dog.age;
      case _AnimalVirtuals.cat:
        return Cat.age;
    }
  }
}

extension VirtualsExtension on Animal {
  _AnimalVirtuals get virtuals => _AnimalVirtuals.from(this);
}

其他信息

如果你遇到更严重的问题，请在 GitHub 仓库 上提交问题。

开发指南

1. 克隆项目并导航到项目根目录。
2. 如果你使用 VSCode，可以使用已有的工作区文件。
3. 使用 melos 工具管理依赖：

   dart pub global activate melos
   melos bootstrap