Flutter项目模板插件project_template的使用

项目概述

project_template 是一个用于生成项目模板和文件树的工具，支持任何编程语言或框架。该插件提供了命令行接口（CLI）和 Dart 库两种使用方式。

版本信息

模板格式

定义模板时，只需声明一个文件树，其中变量的格式为 ___VAR_NAME___。变量将在文件路径和文件内容中被检测到。

示例模板文件树

___project_name_dir___/.gitignore
___project_name_dir___/bin/___project_name_dir___.dart
___project_name_dir___/CHANGELOG.md
___project_name_dir___/project_template.yaml
___project_name_dir___/pubspec.yaml
___project_name_dir___/README.md

示例 README.md 内容

project_name

project_description

Usage

CLI:

$> ___project_name_dir___ -h

See Also

• homepage

## 项目清单

可以在 `project_template.yaml` 文件中声明项目清单：

```yaml
project_name:
  description: The name of the project.
  example: Simple App

project_name_dir:
  description: The project directory name.
  example: simple_app

project_description:
  description: The project description for `pubspec.yaml`.
  example: A simple project.
  default: A project from template.

• 具有 default 值的变量在使用 CLI 命令 create 时不是必需的。

使用方法

project_template 可以作为命令行接口（CLI）或 Dart 库使用。

CLI 使用

安装

全局激活 CLI：

$> dart pub global activate project_template

现在可以直接使用 CLI：

$> project_template --help

CLI 命令

prepare

准备一个模板目录并将其保存为单个文件。生成的文件将用于 create 命令。

准备为 JSON 文件：

$> project_template prepare -d example/template-example -r ".DS_Store$" -o /tmp/template-x.json

准备为 Zip 文件：

$> project_template prepare -d example/template-example -r ".DS_Store$" -o /tmp/template-x.zip

参数说明：

• -d: 模板目录/源
  • 目录: path/to/template-directory
  • Zip 文件: path/to/template-x.zip
  • Tar+gZip 文件: path/to/template-x.tar.gz
  • Tar 文件: path/to/template-x.tar
• -r: 要忽略的文件路径的正则表达式
• -o: 准备好的模板输出文件（用于 create 命令）
  • Zip 文件: path/to/template-x.zip
  • Tar+gZip 文件: path/to/template-x.tar.gz
  • Tar 文件: path/to/template-x.tar
  • JSON 文件: path/to/template-x.json
  • YAML 文件: path/to/template-x.yaml

info

显示模板的信息（文件、变量和清单）：

$> project_template info -t /tmp/template-x.zip

参数说明：

• -t: 模板路径
  • 目录: path/to/template-directory
  • Zip 文件: path/to/template-x.zip
  • Tar+gZip 文件: path/to/template-x.tar.gz
  • Tar 文件: path/to/template-x.tar
  • JSON 文件: path/to/template-x.json
  • YAML 文件: path/to/template-x.yaml

create

从模板创建/构建文件树：

$> project_template create -t /tmp/template-x.zip -p project_name_dir=foo -p project_name=Foo -p "project_description=Foo project." -p homepage=http://foo.com -o /tmp/project-x

参数说明：

• -t: 模板路径
  • 目录: path/to/template-directory
  • Zip 文件: path/to/template-x.zip
  • Tar+gZip 文件: path/to/template-x.tar.gz
  • Tar 文件: path/to/template-x.tar
  • JSON 文件: path/to/template-x.json
  • YAML 文件: path/to/template-x.yaml
• -p: 模板属性/变量定义
• -o: 输出目录/zip/tar.gz（生成的项目文件树将保存在这里）
  • 目录: path/to/template-directory
  • Zip 文件: path/to/template-x.zip
  • Tar+gZip 文件: path/to/template-x.tar.gz
  • Tar 文件: path/to/template-x.tar

库使用

以下是一个简单的示例，从目录加载模板，解析并构建它（使用变量定义），然后将其保存到新目录。

import 'dart:io';
import 'package:project_template/src/project_template_storage_io.dart';
import 'package:yaml_writer/yaml_writer.dart';

void main() async {
  var currentDir = Directory.current.absolute;

  var exampleDir = currentDir.path.endsWith('example')
      ? currentDir
      : Directory('${currentDir.path}/example');

  assert(
      exampleDir.existsSync(), "Can't resolve example directory: $exampleDir");

  var templateDir = 'template-example';

  var storage = StorageIO.directory(exampleDir, templateDir)
    ..ignoreFiles.add('.DS_Store');

  print(storage);

  print('----------------------------------------------------');

  var files = storage.listFiles();

  for (var file in files) {
    print('- $file \t-> ${file.directoryAbsolute}');
  }

  print('----------------------------------------------------');

  var template = await storage.loadTemplate();

  var templateVariables = template.parseTemplateVariables();

  print('Variables:\n  $templateVariables\n');

  var manifest = template.getManifest();

  print('Manifest:\n');

  print(
    YamlWriter()
        .write(manifest)
        .split(RegExp(r'[\r\n]'))
        .map((l) => '  $l')
        .join('\n'),
  );

  print('----------------------------------------------------');

  print(template.toYAMLEncoded());

  print('----------------------------------------------------');

  var variables = {
    'project_name': 'Console Simple',
    'project_name_dir': 'console_simple',
    'homepage': 'https://console-simple.domain',
  };

  var templateResolved = template.resolve(variables);

  print(templateResolved.toYAMLEncoded());

  // Save `templateResolved` to `example/template-generated`:
  // var storageSave = StorageIO.directory(exampleDir);
  // templateResolved.saveTo(storageSave, 'template-generated');
}

CLI 库使用

CLI 类基于 args 包中的 Command 和 CommandRunner，可以集成到其他项目和其他 CLI 工具中。

以下是一个使用 project_template_cli 的 tool-x 示例：

import 'dart:io';
import 'package:args/command_runner.dart';
import 'package:project_template/project_template_cli.dart';

void _consolePrinter(Object? o) {
  print(o);
}

const String cliTitle = '[Tool-X/${Template.version}]';

void main(List<String> args) async {
  var commandRunner =
      CommandRunner<bool>('tool-x', '$cliTitle - CLI Tool')
        ..addCommand(CommandInfo(cliTitle, _consolePrinter))
        ..addCommand(CommandCreate(cliTitle, _consolePrinter))
        ..addCommand(CommandPrepare(cliTitle, _consolePrinter));

  var ok = await commandRunner.run(args);

  exit(ok ? 0 : 1);
}

功能和问题

请在 issue tracker 中提交功能请求和 bug 报告。

作者

Graciliano M. Passos: gmpassos@GitHub

许可证

Apache License - Version 2.0