Modern.js 生成器插件 onForged API 详解

概述

在 Modern.js 项目中，onForged 是一个非常重要的生成器插件生命周期函数，它为开发者提供了丰富的文件操作 API，用于在项目生成过程中执行各种文件操作。本文将深入解析 onForged 的功能和使用方法，帮助开发者更好地利用这一强大工具。

onForged 基本概念

onForged 是生成器插件中的一个核心生命周期函数，它在项目生成阶段被调用，主要用于处理文件操作。该函数接收两个参数：

1. api：提供了一系列文件操作方法
2. inputData：包含了当前生成过程的输入信息

文件类型分类

Modern.js 生成器将文件分为四种类型，每种类型都有特定的处理方式：

1. 文本文件(Text)：纯文本内容文件，支持模板处理
2. 二进制文件(Binary)：如图片、音频等非文本文件
3. JSON文件(Json)：JSON格式的配置文件
4. 文本列表文件(TextRaw)：由行文本组成的特殊文件，如.gitignore

核心API详解

1. 文件添加操作

addFile - 添加单个文件

这是最基础的文件添加方法，用于向项目中添加单个文件。它支持多种配置选项：

await api.addFile({
  type: FileType.Text,  // 文件类型
  file: 'src/App.tsx',  // 目标路径
  templateFile: 'App.tsx.handlebars',  // 模板文件
  force: true,  // 是否强制覆盖
  data: { title: '我的应用' }  // 模板数据
});

addManyFiles - 批量添加文件

当需要添加多个文件到同一目录时，这个方法非常高效：

await api.addManyFiles({
  type: FileType.Text,
  destination: 'src',
  templateFiles: ['templates/**/*'],
  templateBase: 'templates',
  fileNameFunc: name => name.replace('.hbs', '')
});

2. 文件更新操作

updateJSONFile - 更新JSON文件

专门用于更新JSON格式文件，支持嵌套属性更新：

// 更新顶层属性
await api.updateJSONFile('package.json', { name: 'new-project' });

// 更新嵌套属性
await api.updateJSONFile('package.json', {
  'dependencies.react': '^18.2.0'
});

updateTextRawFile - 更新行文本文件

针对.gitignore等行文本文件的专用更新方法：

await api.updateTextRawFile('.gitignore', content => [
  ...content,
  'node_modules',
  'dist'
]);

3. 文件删除操作

rmFile - 删除文件

await api.rmFile('unused-file.txt');

rmDir - 删除目录

await api.rmDir('obsolete-directory');

4. 模板处理功能

addHelper - 添加Handlebars辅助函数

api.addHelper('toUpperCase', str => str.toUpperCase());

addPartial - 添加Handlebars局部模板

api.addPartial('header', '<header>{{title}}</header>');

5. 高级功能

createElement - 创建工程元素

await api.createElement('entry', {
  entryName: 'main',
  framework: 'react'
});

enableFunc - 启用功能

await api.enableFunc('bff', {
  apiDir: 'api'
});

最佳实践建议

1. 文件操作顺序：建议先执行删除操作，再执行添加操作，避免冲突
2. 错误处理：所有API都返回Promise，建议使用try-catch处理可能的错误
3. 性能优化：批量操作优先使用addManyFiles而非多次调用addFile
4. 模板设计：合理使用Handlebars辅助函数和局部模板提高模板可维护性

总结

Modern.js 的 onForged API 提供了一套完整而强大的文件操作工具集，涵盖了从基础文件操作到高级工程配置的各种需求。通过合理利用这些API，开发者可以创建出功能丰富、高度可定制的项目生成器插件，极大地提升开发效率和项目一致性。