npm - @modern-js/main-doc - Versions diffs - 2.60.6 → 2.62.0 - Mend

@modern-js/main-doc 2.60.6 → 2.62.0

Files changed (59) hide show

package/docs/zh/guides/topic-detail/generator/plugin/api/afterForged.md DELETED Viewed

@@ -1,50 +0,0 @@
----
-sidebar_position: 3
----
-# afterForged
-`afterForged` 为生成器插件中用于文件操作后其他步骤操作的生命周期函数。
-## 类型
-```ts
-export type AfterForgedAPI = {
-  isInGitRepo: () => Promise<boolean>;
-  initGitRepo: () => Promise<void>;
-  gitAddAndCommit: (commitMessage: string) => Promise<void>;
-  install: () => Promise<void>;
-};
-export type PluginAfterForgedFunc = (api: AfterForgedAPI, inputData: Record<string, unknown>) => Promise<void>;
-export interface IPluginContext {
-   afterForged: (func: PluginAfterForgedFunc) => void;
-  ...
-}
-```
-## API
-下面将分别介绍 api 参数提供的 API。
-### isInGitRepo
-判断当前项目是否为一个 Git 仓库。
-### initGitRepo
-初始化当前项目为 Git 仓库。
-### gitAddAndCommit
-提交当前仓库变更。
-参数：
-- `commitMessage`: commit 信息。
-### install
-在项目根目录安装依赖。`install` 函数中将根据 `packageManager` 的值使用对应的包管理工具安装依赖。

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

@@ -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 DELETED Viewed

@@ -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 DELETED Viewed

@@ -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)。
-:::