Flutter常量键生成插件constant_keys_generator的使用

Flutter常量键生成插件constant_keys_generator的使用

简介

constant_keys_generator 是一个Flutter Dart库，用于生成包含表示给定JSON或YAML文件中JSON路径的字符串常量的Dart文件。该工具帮助开发人员在Flutter项目中管理JSON路径作为常量。

功能

• 输入文件：接受JSON或YAML文件作为输入。
• 输出文件：生成一个包含所有输入文件路径的字符串常量的Dart文件。
• 易于使用：通过 build_runner 构建命令运行。
• Flutter兼容：非常适合需要结构化JSON路径管理的Flutter项目。

安装

在 pubspec.yaml 文件中添加以下内容：

dev_dependencies:
  constant_keys_generator: ^最新版本号

然后运行以下命令安装包：

flutter pub add --dev constant_keys_generator

使用指南

1. 配置文件设置

创建一个名为 constant_keys_generator.yaml 的配置文件，放在项目的根目录下：

constant_keys_generator:
  output_dir: "generated"  # 输出目录（在lib目录内）
  file_configs:
    - input_file: "assets/translations/*.json"  # 输入文件路径，支持glob模式
      output_file: "locale_keys"  # 输出文件名（不包括 .g.dart 扩展名）

或者，可以直接在 pubspec.yaml 中添加配置：

constant_keys_generator:
  output_dir: "generated"
  file_configs:
    - input_file: "assets/translations/*.json"
      output_file: "locale_keys"

2. 准备输入文件

在 assets/translations 目录下准备两个翻译文件：

• en.json

{
  "common": {
    "appName": "Constant keys generator"
  }
}

• vi.json

{
  "common": {
    "appName": "Trình tạo khóa cố định"
  }
}

3. 运行生成器

执行以下命令以运行代码生成器：

dart run build_runner build

4. 验证生成的文件

生成的文件将位于 lib/generated/constant_keys/locale_keys.g.dart，内容如下：

// ignore_for_file: camel_case_types
class _LocaleKeys_Common {
  final String appName = 'common.appName';
  _LocaleKeys_Common();
}

class _LocaleKeys {
  final _LocaleKeys_Common common = _LocaleKeys_Common();
  _LocaleKeys();
}

// ignore: non_constant_identifier_names
final LocaleKeys = _LocaleKeys();

生成文件的用例

当使用 easy_localization 库时，虽然该库提供了代码生成机制，但生成的结果（无论是keys格式还是json格式）都不太方便使用。因此，我们开发了这个库作为替代方案，用于生成类型安全的键。

例如，使用生成的文件与 easy_localization 结合：

import 'package:easy_localization/easy_localization.dart';
import 'package:example/generated/constant_keys/locale_keys.dart';

Text(tr(LocaleKeys.common.appName))

或者：

import 'package:easy_localization/easy_localization.dart';
import 'package:example/generated/constant_keys/locale_keys.dart';

String appName = tr(LocaleKeys.common.appName);

完整示例

1. 准备JSON文件

在 assets/translations 目录下准备三个翻译文件：

• en.json

{
  "common": {
    "appName": "Constant keys generator"
  }
}

• vi.json

{
  "common": {
    "appName": "Trình tạo khóa cố định"
  }
}

• ja.json

{
  "common": {
    "appName": "定数キージェネレータ"
  }
}

2. 更新 pubspec.yaml

在 pubspec.yaml 中添加以下配置：

constant_keys_generator:
  file_configs:
    - input_file: "assets/translations/*.json"
      output_file: "locale_keys"

3. 运行 build_runner 构建

执行以下命令以生成文件：

dart run build_runner build

4. 验证生成的文件

生成的文件将位于 lib/generated/constant_keys/locale_keys.g.dart，内容如下：

// ignore_for_file: camel_case_types
class _LocaleKeys_Common {
  final String appName = 'common.appName';
  _LocaleKeys_Common();
}

class _LocaleKeys {
  final _LocaleKeys_Common common = _LocaleKeys_Common();
  _LocaleKeys();
}

// ignore: non_constant_identifier_names
final LocaleKeys = _LocaleKeys();

5. 使用生成的常量

在 main.dart 中使用生成的常量：

import 'package:flutter/material.dart';
import 'package:easy_localization/easy_localization.dart';
import 'package:example/generated/constant_keys/locale_keys.dart';

void main() async {
  WidgetsFlutterBinding.ensureInitialized();
  await EasyLocalization.ensureInitialized();

  runApp(
    EasyLocalization(
      supportedLocales: const [Locale('en'), Locale('ja'), Locale('vi')],
      path: 'assets/translations',
      fallbackLocale: const Locale('en'),
      child: const MyApp(),
    ),
  );
}

class MyApp extends StatelessWidget {
  const MyApp({super.key});

  [@override](/user/override)
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'Flutter Demo',
      theme: ThemeData(
        colorScheme: ColorScheme.fromSeed(seedColor: Colors.deepPurple),
        useMaterial3: true,
      ),
      home: MyHomePage(title: tr(LocaleKeys.common.appName)),
    );
  }
}

class MyHomePage extends StatelessWidget {
  final String title;

  const MyHomePage({super.key, required this.title});

  [@override](/user/override)
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: Text(title),
      ),
      body: Center(
        child: Text(
          tr(LocaleKeys.common.appName),
          style: Theme.of(context).textTheme.headlineMedium,
        ),
      ),
    );
  }
}