@modern-js/main-doc 2.60.6 → 2.61.0

package/docs/zh/guides/topic-detail/generator/plugin/api/context.md

@@ -1,184 +0,0 @@
----
-sidebar_position: 1
----
-
-# context
-
-生成器插件在 `main` 文件中默认导出了一个函数，函数参数为 `context`，生成器插件提供的所有 API 都是由这个 `context` 提供的。
-
-## 类型
-
-我们先大概了解一下 `context` 的类型定义：
-
-```ts
-export interface IPluginContext {
-  locale?: string;
-  addInputBefore: (key: string, input: Schema) => void;
-  addInputAfter: (key: string, input: Schema) => void;
-  setInput: (key: string, field: string, value: unknown) => void;
-  setInputValue: (value: Record<string, unknown>) => void;
-  setDefaultConfig: (value: Record<string, unknown>) => void;
-  isFileExist: (fileName: string) => Promise<boolean>;
-  readDir: (dir: string) => Promise<string[]>;
-  setGitMessage: (gitMessage: string) => void;
-  onForged: (func: PluginForgedFunc) => void;
-  afterForged: (func: PluginAfterForgedFunc) => void;
-}
-```
-
-`context` 提供的内容主要分为三类：
-
-- 获取当前生成器执行环境信息
-
-- 操作 input 输入
-
-- 生成器插件生命周期函数
-
-下面将从这三个分类分别介绍生成器插件 API。
-
-
-### 获取信息
-
-#### locale
-
-获取生成器插件执行环境的语言。`@modern-js/create` 提供了 `zh` 和 `en` 两种语言，这里即为对应的这两种值。
-
-#### isFileExist
-
-判断文件是否存在。我们很多时候需要在定义操作前确认目标项目文件是否已经存在，可以直接通过该 API 获取。
-
-例如我们需要获取 `package.json` 文件是否存在，然后做相应的操作：
-
-```ts
-const isExist = await context.isFileExist('package.json');
-if (isExist) {
-    ...
-}
-```
-
-#### readDir
-
-获取文件夹内文件列表。我们很多时候需要在定义操作前获取目标项目文件夹下面文件列表，可以直接通过该 API 获取。
-
-例如我们需要获取 src 文件夹下所有文件，然后进行相应操作：
-
-```ts
-const files = await context.readDir('src');
-
-files.map(name => {
-    ...
-});
-```
-
-### input 操作
-
-input 操作中使用的 key 参数可参考[配置参数](/guides/topic-detail/generator/create/config.html)，需要在使用对应工程方案下的 key，即不支持在 `solution` 和 `scenes`。
-
-input 操作中的 input 参数对应的 Schema 类型可参考 [Input](/guides/topic-detail/generator/plugin/api/input.html)。
-
-#### addInputBefore
-
-在指定的 input `key` 前添加问题。
-
-例如：
-
-```ts
-context.addInputBefore('packageManager', {
-  type: 'object',
-  properties: {
-    language: {
-      type: 'string',
-      title: '开发语言',
-      enum: [
-        { label: 'TS', value: 'ts' },
-        { label: 'ES6+', value: 'js' },
-      ],
-    },
-  },
-});
-```
-
-#### addInputAfter
-
-在指定的 input `key` 后添加问题。
-
-例如：
-
-```ts
-context.addInputAfter('packageManager', {
-  type: 'object',
-  properties: {
-    language: {
-      type: 'string',
-      title: '开发语言',
-      enum: [
-        { label: 'TS', value: 'ts' },
-        { label: 'ES6+', value: 'js' },
-      ],
-    },
-  },
-});
-```
-
-:::info
-1. 添加问题的 `key` 不能和 Modern.js 提供的工程方案自身的问题的 `key` 重复。
-2. 添加问题 `addInputAfter` 的优先级高于 `addInputBefore`，当同时对一个 key 添加 After 问题和对其后一个key 添加 Before 问题时，After 问题会在 Before 之前。
-3. 当需要在相同 `key` 前面或者后面添加多个问题时，可多次调用该方法，问题的顺序会按照调用顺序进行排列。
-
-:::
-
-#### setInput
-
-设置指定 input `key` 的属性。
-
-例如设置 `packageName` 的 `title` 属性：
-
-```ts
-context.setInput('packageName', 'title', "展示名称");
-```
-
-:::info
-对于 Modern.js 工程方案提供的输入选项，只支持删除，不支持增加，增加会造成代码中的逻辑判断存在问题。
-:::
-
-
-#### setInputValue
-
-设置指定 input `key` 的选项默认值。
-
-例如设置 `packageManager` 的默认值：
-
-```ts
-context.setInputValue({
-  packageManager: 'npm',
-});
-```
-
-:::info
-设置完成后，该问题还是需要交互，只是会使用生成器插件配置的默认值。
-:::
-
-#### setDefaultConfig
-
-设置指定 input `key` 的默认值。
-
-例如设置 `packageManager` 的默认值：
-
-```ts
-context.setDefaultConfig({
-  packageManager: 'npm',
-});
-```
-
-:::info
-设置完成后，将不再展示对应问题，和 `@modern-js/create` 制定 `--config` 行为一致。不支持设置 `vertical` 和 `projectOrg`。
-:::
-
-#### setGitMessage
-
-设置 Git 初始提交信息。Modern.js 默认 Git 初始化提交信息为 `feat: init`，通过该函数可以修改。
-
-
-### 生命周期函数
-
-生命周期函数比较复杂，将通过后面两节 [`onForged`](/guides/topic-detail/generator/plugin/api/onForged.html) 和 [`afterForged`](/guides/topic-detail/generator/plugin/api/afterForged.html) 分别介绍。

package/docs/zh/guides/topic-detail/generator/plugin/api/input.md

@@ -1,124 +0,0 @@
----
-sidebar_position: 4
----
-
-# Input
-
-生成器插件提供了 Input 的方式完成与用户的问题交互，使用 JSON Schema 的方式进行定义：
-
-例如：
-
-```js
-const schema = {
-  type: 'object',
-  properties: {
-    language: {
-      type: 'string',
-      title: '开发语言',
-      enum: [
-        { label: 'TS', value: 'ts' },
-        { label: 'ES6+', value: 'js' },
-      ],
-    },
-  },
-};
-```
-
-JSON Schema 的格式参考了开源的 [Formily](https://formilyjs.org/) Schema 的格式，下面将对支持的字段进行介绍：
-
-## type
-
-定义当前 Schema 类型，当前支持的类型为 `string`、`number` 和 `object`。字符串输入和下拉选项都需要使用 `string` 类型。 `object` 类型用于实现 Schema 之间嵌套，需要配和 `properties` 属性使用。
-
-## title
-
-定义当前 Schema 展示名称。
-
-## default
-
-定义当前 Schema 的默认值。
-
-## enum
-
-当前 Schema 为下列选项时，定义选项内容。
-
-子项支持 `string` 或者 `{ label: string; value: string}` 类型，当下拉选项中值和展示值相同时，可直接使用 `string` 定义。
-
-当需要表示多选选项时，设置 `default` 字段为 `[]` 即可。
-
-## x-validator
-
-当前 Schema 的校验规则。当 Schema 为输入类型时，在输入完成后会自动完成校验。
-
-这里校验规则支持[ Formily 提供的校验规则](https://formilyjs.org/zh-CN/guide/advanced/validate)，例如最大值为 5：
-
-```js
-const schema = {
-  type: 'object',
-  properties: {
-    max_5: {
-      type: 'number',
-      title: '最大值(>5报错)',
-      'x-validator': {
-        maximum: 5,
-      },
-    },
-  },
-};
-```
-
-也支持直接使用验证函数：
-
-```js
-const schema = {
-  type: 'object',
-  properties: {
-    path: {
-      type: 'string',
-      title: '只能包含数字和字母',
-      'x-validator': value => {
-        if (!/^[0-9a-zA-Z]*$/g.test(value)) {
-          return '格式不正确';
-        }
-        return '';
-      },
-    },
-  },
-};
-```
-
-## x-reactions
-
-使用 Schema 之间的联动，这里和[ Formily 联动规则](https://formilyjs.org/zh-CN/guide/advanced/linkages)完全相同。
-
-例如：
-
-```js
-const schema = {
-  type: 'object',
-  properties: {
-    name: {
-      type: 'string',
-      title: '名称',
-    },
-    path: {
-      type: 'string',
-      title: '路径',
-      'x-reactions': [
-        {
-          dependencies: ['name'],
-          fulfill: {
-            state: {
-              value: '{{$deps[0]}}',
-            },
-          },
-        },
-      ],
-    },
-  },
-};
-```
-
-## properties
-
-组织当前 Schema 的结构，定义子表单。`properties` 为对象，`key` 为 Schema 关键字，`value` 为上述描述的 Schema 对象。

package/docs/zh/guides/topic-detail/generator/plugin/api/onForged.md

@@ -1,310 +0,0 @@
----
-sidebar_position: 2
----
-
-# onForged
-
-`onForged` 为生成器插件中用于文件操作的生命周期函数。
-
-## 类型
-
-```ts
-export type ForgedAPI = {
-  addFile: (params: AddFileParams) => Promise<void>;
-  addManyFiles: (params: AddManyFilesParams) => Promise<void>;
-  updateJSONFile: (fileName: string, updateInfo: Record<string, unknown>) => Promise<void>;
-  updateTextRawFile: (fileName: string, update: (content: string[]) => string[]) => Promise<void>;
-  updateModernConfig: (updateInfo: Record<string, any>) => Promise<void>;
-  rmFile: (fileName: string) => Promise<void>;
-  rmDir: (dirName: string) => Promise<void>;
-  addHelper: (name: string, fn: Handlebars.HelperDelegate) => void;
-  addPartial: (name: string, str: Handlebars.Template) => void;
-  createElement: (element: ActionElement, params: Record<string, unknown>) => Promise<void>;
-  enableFunc: (func: ActionFunction, params?: Record<string, unknown> | undefined) => Promise<void>;
-};
-
-export type PluginForgedFunc = (
-  api: ForgedAPI,
-  inputData: Record<string, unknown>,
-) => void | Promise<void>;
-
-export interface IPluginContext {
-  onForged: (func: PluginForgedFunc) => void;
-  ...
-}
-```
-
-`onForged` 参数为一个回调函数，回调函数参数为 `api` 和 `input`，分别用于提供该生命周期函数提供的 API 及当前输入信息。
-
-## 概念
-
-### 文件类型
-
-生成器插件将文件类型分为四类：
-
-- 文本文件
-
-纯文本内容文件，可使用 [Handlebars](https://handlebarsjs.com/) 或 [EJS](https://ejs.co/) 进行模板处理的文件。
-
-- 二进制文件
-
-图片、音频、视频等文件。
-
-- JSON 文件
-
-JSON 格式的文件。
-
-- 文本列表文件
-
-文件由行文本组成的文件，例如 `.gitignore`, `.editorconfig`, `.npmrc`。
-
-对应四种文件的类型定义为：
-
-```ts
-export enum FileType {
-  Text = 'text',
-  Binary = 'binary',
-  Json = 'json',
-  TextRaw = 'textRaw',
-}
-```
-
-## API
-
-下面将分别介绍 api 参数提供的 API。
-
-### addFile
-
-添加单个文件。
-
-参数类型：
-
-```ts
-export interface AddFileParams {
-  type: FileType;
-  file: string;
-  template?: string;
-  templateFile?: string;
-  force?: boolean;
-  data?: Record<string, string>;
-}
-```
-
-- `type`： 文件类型。
-- `file`：目标文件路径，相对于目标项目目录的相对路径。
-- `template`：模板内容，该字段值可直接用于模板渲染文件。优先级低于 `templateFile`。
-- `templateFile`：模板文件路径，相对于 templates 目录的相对路径即可。
-- `force`：是否强制覆盖，当目标文件存在时是否强制覆盖，默认为 false。
-- `data`：模板渲染数据。
-
-:::info
-文本类型文件默认使用 Handlebars 进行处理，当模板文件以 `.ejs` 结尾的话，会使用 [EJS](https://ejs.co/) 进行模板渲染。
-:::
-
-例如添加模板文件 `App.tsx.hanlebars` 到 `src/App.tsx` 中:
-
-```ts
-context.onForged(async (api: ForgedAPI, _input: Record<string, unknown>) => {
-  await api.addFile({
-    type: FileType.Text,
-    file: `src/App.tsx`,
-    templateFile: `App.tsx.handlebars`,
-  });
-})
-```
-
-### addManyFiless
-
-批量添加文件，一般用于添加多个文件到同一个目标目录。
-
-参数类型：
-
-```ts
-export interface AddManyFilesParams {
-  type: FileType;
-  destination: string;
-  templateFiles: string[] | (() => string[]);
-  templateBase?: string;
-  fileNameFunc?: (name: string) => string;
-  data?: Record<string, string>;
-}
-```
-
-- `type`： 文件类型。
-- `destination`：目标文件夹，相对于目标项目目录的相对路径。
-- `templateFiles`：模板文件列表，支持 [globby](https://www.npmjs.com/package/globby) 正则表达式
-- `templateBase`：模板文件的公共路径，使用该参数时目标文件会自动删除该路径。
-- `fileNameFunc`：重命名文件函数，添加文件过程中会依次将文件名传入到该函数，可以根据需要进行重命名。
-- `data`：模板渲染数据。
-
-例如将模板文件 `src-ts` 目录下所有文件渲染到 `src` 目录：
-
-```ts
-context.onForged(async (api: ForgedAPI, _input: Record<string, unknown>) => {
-  await api.addManyFiles({
-    type: FileType.Text,
-    destination: 'src',
-    templateFiles: ['src-ts/**/*'],
-    templateBase: 'src-ts',
-    fileNameFunc: name => name.replace('.handlebars', ''),
-  });
-})
-```
-
-### updateJSONFile
-
-更新 JSON 文件字段。
-
-参数类型：
-
-```ts
-fileName: strings
-updateInfo: Record<string, unknown>
-```
-
-- `fileName`：JSON 文件路径，相对于目标项目的路径。
-- `updateInfo`：更新信息，嵌套字段更新需要平铺，不然会更新整体造成内容丢失。
-
-例如更新 `package.json` 的 name 字段：
-
-```ts
-context.onForged(async (api: ForgedAPI, _input: Record<string, unknown>) => {
-  await api.updateJSONFile('package.json', { name: 'new_name' });
-})
-```
-
-例如更新 `dependencies` 的 `react-dom` 版本:
-
-```ts
-context.onForged(async (api: ForgedAPI, _input: Record<string, unknown>) => {
-  await api.updateJSONFile('package.json', {
-    'dependencies.react-dom': '^18',
-  });
-})
-```
-
-### updateTextRawFile
-
-更新文本列表文件内容。
-
-参数类型：
-
-```ts
-fileName: string
-update: (content: string[]) => string[]
-```
-
-- `fileName`： 文本列表文件路径，相对于目标项目的路径。
-- `update`：更新函数，参数为当前文件内容以 `\n` 进行分割的数组，返回值也为修改完成后的数组，`@modern-js/create` 会自动以 `\n` 合并，并写入源文件。
-
-例如 `.gitinore` 文件中增加 dist 目录：
-
-```ts
-context.onForged(async (api: ForgedAPI, _input: Record<string, unknown>) => {
-  await api.updateTextRawFile('.gitinore', (content) => [...content, 'dist']);
-})
-```
-
-### updateModernConfig(不推荐)
-
-Modern.js 配置除了可以在 `modern.config.[tj]s` 中配置外，还支持 `package.json` 中配置 `modernConfig` 配置。该函数用于更新该字段。
-
-参数类型：
-
-```ts
-updateInfo: Record<string, any>
-```
-
-- `updateInfo`： 更新内容信息。updateModernConfig 是基于 updateJSONFile 的封装，将自动更新到 `modernConfig` 字段下，updateInfo 中只需填写 `modernConfig` 下的配置字段即可。
-
-例如开启 ssr：
-
-```ts
-context.onForged(async (api: ForgedAPI, _input: Record<string, unknown>) => {
-  await api.updateModernConfig({ 'server.ssr': true });
-})
-```
-
-### rmFile
-
-删除文件。
-
-参数类型：
-
-```ts
-fileName: string
-```
-
-- `fileName`：删除的文件路径，相对于目标项目的路径。
-
-### rmDir
-
-删除文件夹。
-
-参数类型：
-
-```ts
-dirName: string
-```
-
-- `dirName`：删除的文件夹路径，相对于目标项目的路径。
-
-### addHelper
-
-添加 handlebrs 渲染的[自定义 Helper](https://handlebarsjs.com/guide/#custom-helpers)。
-
-参数类型：
-
-```ts
-name: string
-fn: Handlebars.HelperDelegate
-```
-
-- `name`：Helper 函数名称。
-- `fn`：Helper 函数实现。
-
-### addPartial
-
-添加 Handlebars 渲染的 [Partial](https://handlebarsjs.com/guide/partials.html#basic-partials)。
-
-参数类型：
-
-```ts
-name: string
-str: Handlebars.Template
-```
-
-- `name`：Partial 名称。
-- `str`：Partial 的模板字符串。
-
-### createElement
-
-自动调用 new 命令创建工程元素。
-
-参数类型：
-
-```ts
-element: ActionElement
-params: Record<string, unknown>
-```
-
-- `element`：工程元素类型，新建入口或者新建自定义 Web Server 源码目录。
-- `params`：对应创建工程元素的其他参数。
-
-### enableFunc
-
-自动调用 new 命令开启可选功能。
-
-参数类型：
-
-```ts
-func: ActionFunction
-params?: Record<string, unknown>
-```
-
-- `func`：开启功能名称。
-- `params`：对应开启功能的其他参数。
-
-:::info
-创建工程元素和开启功能配置可参考[配置参数](/guides/topic-detail/generator/new/config.html)。
-:::

package/docs/zh/guides/topic-detail/generator/plugin/category.md

@@ -1,93 +0,0 @@
----
-sidebar_position: 2
----
-
-# 类型
-
-## 介绍
-
-生成器插件分为两类：
-
-- 扩展：Web 应用( Npm 模块) = Web 应用( Npm 模块) + 生成器插件
-
-- 自定义：新应用(模块) = Web 应用(模块) + 生成器插件
-
-
-简单理解就是扩展还是使用 Modern.js 原本的工程方案名称，自定义会创建一个新的名称。
-
-## 标识
-
-生成器插件的类型通过 `package.json` 中的 meta 字段来提供：
-
-### 扩展
-
-```json title="package.json"
-{
- "meta": {
-    "extend": "mwa" // module
- }
-}
-```
-
-### 自定义
-
-```json title="package.json"
-{
- "meta": {
-    "key": "new_app",
-    "name": "新应用",
-    "type": "mwa" // module 和 custom
- }
-}
-```
-
-:::info
-自定义类型的 type 支持 custom 类型，custom 为使用 Modern.js 提供的一些项目开发的最佳实践模板，比如 `.gitignore`、`.editorConfig` 等文件，其他业务相关代码模板需要手动通过生成器插件提供。
-:::
-
-## 创建初始项目
-
-### 扩展
-
-```bash
-npx @modern-js/create@latest plugin --plugin @modern-js/generator-plugin-plugin
-? 请选择你想创建的工程类型 Npm 模块
-? 请选择项目场景 生成器插件
-? 请输入生成器插件插件包名 plugin
-? 请选择开发语言 TS
-? 请选择包管理工具 pnpm
-? 请选择插件类型 extend
-? 请选择插件基础类型 Web 应用
-```
-
-### 自定义
-
-```bash
-npx @modern-js/create@latest plugin --plugin @modern-js/generator-plugin-plugin
-? 请选择项目类型 生成器插件
-? 请选择项目组织方式 独立项目
-? 请选择开发语言 TS
-? 请选择包管理工具 pnpm
-? 请输入生成器插件插件包名 plugin
-? 请选择开发语言 TS
-? 请选择包管理工具 pnpm
-? 请选择插件类型 custom
-? 请输入插件关键字 new_app
-? 请输入插件展示名称 新应用
-? 请选择插件基础类型 Web 应用
-```
-
-## 执行顺序
-
-生成器插件支持同时使用多个，也就是执行 `@modern-js/create` 时支持多个 `--plugin` 参数。
-
-### 扩展
-
-扩展生成器插件支持在执行时会按照声明的生成器插件参数的顺序，依次执行对应 extend 的工程方案的生命周期函数。
-
-例如存在 A 和 B 两个生成器插件，A 和 B 都是 extend 的 Web 应用工程方案，A 插件声明添加 `a.ts` 文件，B 插件声明添加 `b.ts` 文件，
-执行 `npx @modern-js/create@latest --plugin A --plugin B` 时，选择 Web 应用工程时，会先生成 Web 应用默认的项目文件，然后执行 A 插件创建 `a.ts` 文件，再执行 B 插件，生成 `b.ts` 文件。
-
-### 自定义
-
-自定义生成器插件只支持同一时间运行一个生成器插件，当 `@modern-js/create` 声明 `--plugin` 参数时，会在选择工程方案之后增加选择工程方案场景选项，即为上述 `package.json` 中定义的新 name，选择对应 name 的生成器插件，即会在默认工程方案执行完成后，执行对应的生成器插件逻辑。声明 `--plugin` 参数时，工程方案场景下将会逐一列举出对应的生成器插件名称供选择。