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

@modern-js/main-doc 2.60.6 → 2.62.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

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