# @eggjs/view 中文文档

规范地址：https://npmcn.com/package/%40eggjs/view/

版本：4\.1\.0
npm 元数据更新时间：2026-10-07T08:20:15.808Z
中文译文更新时间：2026-11-13T10:00:58.732Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40eggjs/view
原文对照：https://npmcn.com/package/%40eggjs/view/?lang=original
项目主页：https://github.com/eggjs/egg/tree/next/plugins/view
源码仓库：https://github.com/eggjs/egg

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：28.3 kB，21 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=22\.18\.0
- 运行依赖：2 个
- peer 依赖：egg 4\.2\.0
- 首次发布：2025-02-03T16:31:32.266Z
- 最新版本发布：2026-10-07T08:20:15.160Z
- 近 30 天下载量：4700（2026-10-13 至 2026-11-11，npm 官方下载统计）
- 已发布版本数：53（近 12 个月 33 个）

## 中文简介

彩蛋底部视图插件

## 安装

```sh
npm install @eggjs/view
```

也可以使用：`pnpm add @eggjs/view`、`yarn add @eggjs/view`、`bun add @eggjs/view`

## README

# @eggjs/视图

[![NPM version](https://img.shields.io/npm/v/@eggjs/view.svg?style=flat-square)](https://npmjs.org/package/@eggjs/view) [![NPM download](https://img.shields.io/npm/dm/@eggjs/view.svg?style=flat-square)](https://npmjs.org/package/@eggjs/view) [![Node.js Version](https://img.shields.io/node/v/@eggjs/view.svg?style=flat)](https://nodejs.org/en/download/) [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat-square)](https://makeapullrequest.com/) ![CodeRabbit Pull Request Reviews](https://img.shields.io/coderabbit/prs/github/eggjs/view)

彩蛋底部视图插件

**它是一个已经内置的用于鸡蛋的插件.**

## 安装

```bash
npm i @eggjs/view
```

## 使用量

```js
// {app_root}/config/plugin.ts
export default {
  view: {
    enable: true,
    package: '@eggjs/view',
  },
};
```

## 使用模板引擎

[@eggjs/视图](https://github.com/eggjs/egg/tree/next/plugins/view) 没有内置视图引擎,所以你应该选择一个模板引擎,比如 [简况](https://github.com/mde/ejs),并安装 [蛋景画](https://github.com/eggjs/egg-view-ejs) 插件 .

您可以先选择模板引擎, 链接 [简况](https://github.com/mde/ejs),所以我们使用 [蛋景画](https://github.com/eggjs/egg-view-ejs) 插件 .

`egg-view` 进入 [鸡蛋](https://eggjs.org/),所以你只需要配置 [蛋景画](https://github.com/eggjs/egg-view-ejs)。 。 。 .

```js
// config/plugin.ts
export default {
  ejs: {
    enable: true,
    package: 'egg-view-ejs',
  },
};
```

配置映射, 文件为 `.ejs` 扩展将由 ejs 提供.

```js
// config/config.default.ts
export default {
  view: {
    mapping: {
      '.ejs': 'ejs',
    },
  },
};
```

在控制器中,你可以打电话 `ctx.render`。 。 。 .

```js
export default (app: Application) => {
  return class UserController extends app.Controller {
    async list() {
      const { ctx } = this;
      await ctx.render('user.ejs');
    }
  };
}
```

如果你打电话 `ctx.renderString`,您应当在视图选项中指定视图引擎.

```js
export default (app: Application) => {
  return class UserController extends app.Controller {
    async list() {
      const { ctx } = this;
      ctx.body = await ctx.renderString(
        '<%= user %>',
        { user: 'popomore' },
        {
          viewEngine: 'ejs',
        }
      );
    }
  };
}
```

## 使用多视图引擎

\[egg-view\]支持多视图引擎,因此在一个应用程序中可以使用多个模板引擎.

如果您想要添加其它模板引擎, 如 [尼姑](http://mozilla.github.io/nunjucks),然后可以添加 [蛋-观-出](https://github.com/eggjs/egg-view-nunjucks) 插件 .

配置插件和映射

```js
// config/plugin.ts
export default {
  ejs: {
    enable: true,
    package: 'egg-view-ejs',
  },
  nunjucks: {
    enable: true,
    package: 'egg-view-nunjucks',
  },
};
```

```js
// config/config.default.ts
export default {
  view: {
    mapping: {
      '.ejs': 'ejs',
      '.nj': 'nunjucks',
    },
  },
};
```

您可以简单地将文件转换为 `.nj` 扩展名.

```js
await ctx.render('user.nj');
```

## 如何写入视图插件

你用得着 [@eggjs/视图](https://github.com/eggjs/egg/tree/next/plugins/view)用于注册插件的 API .

### 查看引擎

首先创建视图引擎类, 并执行 `render` 财务报告和审定财务报表 `renderString`,如果模板引擎不支持,只需丢出一个错误. 视图引擎为上下文级别,因此在 `constructor`。 。 。 .

```js
// lib/view.ts
export default class MyView {
  constructor(ctx) {
    // do some initialize
    // get the plugin config from `ctx.app.config`
  }

  async render(fullpath: string, locals: Record<string, any>) {
    return myengine.render(fullpath, locals);
  }

  async renderString() {
    throw new Error('not implement');
  }
}
```

`render` 财务报告和审定财务报表 `renderString` 支持生成器函数,同位素函数,或普通函数返回承诺.

如果模板引擎只支持回调,你可以用"承诺"来包接.

```js
class MyView {
  render(fullpath, locals) {
    return new Promise((resolve, reject) => {
      myengine.render(fullpath, locals, (err, result) => {
        if (err) {
          reject(err);
        } else {
          resolve(result);
        }
      });
    });
  }
}
```

这些方法有三个论点:, `renderString` 将会通过 tpl 作为第一个参数而不是名称在 `render`。 。 。 .

`render(name, locals, viewOptions)`

-   名称: 可以从 root 中解析的文件路径 (`app/view` (默认)
-   本地数据: 模板使用的数据
-   视图选项:每次渲染的视图选项,可以覆盖视图默认配置 `config/config.default.js`。插件如果有配置,则应执行. 执行视图引擎时,您将收到来自 `render`,选项包括:
    -   root: 蛋景会将名称解为完整路径,但在视图选项中将根和名进行分解.
    -   名称: 调用时的原名
    -   本地: 调用时的原本地人

`renderString(tpl, locals, viewOptions)`

-   tpl: 模板字符串而不是文件, 使用在 `renderString`
-   当地人: 与 `render`
-   视图选项: 与 `render`

### 登记册

在定义了视图引擎后,可以注册.

```js
// app.ts
import type { Application } from 'egg';
import MyView from './lib/view';

export default (app: Application) => {
  app.view.use('myName', MyView);
}
```

你可以定义一个视图引擎名称,通常是一个模板名称.

### 配置

定义插件名称并依赖 [@eggjs/视图](https://github.com/eggjs/egg/tree/next/plugins/view)

```json
{
  "eggPlugin": {
    "name": "myName",
    "dependencies": ["view"]
  }
}
```

设置默认配置 `config/config.default.ts`,名称等于插件名称.

```js
export default {
  myName: {},
};
```

参见一些例子

-   [蛋景画](https://github.com/eggjs/egg-view-ejs)
-   [蛋-观-出](https://github.com/eggjs/egg-view-nunjucks)

## 配置

### 根号

根为 `${baseDir}/app/view` ,但您可以定义多个目录,由 `,`。 。 。 . [@eggjs/视图](https://github.com/eggjs/egg/tree/next/plugins/view) 将会从所有根目录中找到一个文件.

```js
export default (appInfo: EggAppInfo) => {
  const baseDir = appInfo.baseDir;
  return {
    view: {
      root: `${baseDir}/app/view,${baseDir}/app/view2`,
    },
  };
}
```

### 默认扩展

在提交文件时,您应当指定一个扩展名,允许 [@eggjs/视图](https://github.com/eggjs/egg/tree/next/plugins/view) 你知道你想用什么引擎吗. 但是,你可以定义 `defaultExtension` 不写入扩展名.

```js
// config/config.default.ts
export default {
  view: {
    defaultExtension: '.html',
  },
};

// controller
export default (app: Application) => {
  return class UserController extends app.Controller {
    async list() {
      const { ctx } = this;
      // render user.html
      await ctx.render('user');
    }
  }
}
```

### 视图引擎和默认视频引擎

使用时 `renderString`,请在视图配置中指定视图Engine,见上文示例.

不过,你可以定义 `defaultViewEngine` 不每次设置.

```js
// config/config.default.ts
export default {
  view: {
    defaultViewEngine: 'ejs',
  },
};
```

见 [配置/ 配置. 默认. ts](https://github.com/eggjs/egg/blob/next/plugins/view/src/config/config.default.ts) 更详细.

## 问题和建议

请打开一个问题 [这里](https://github.com/eggjs/egg/issues)。 。 。 .

## 许可证

[麻省理工学院](https://npmcn.com/package/%40eggjs/view/LICENSE)

## 贡献者

[![Contributors](https://contrib.rocks/image?repo=eggjs/egg)](https://github.com/eggjs/egg/graphs/contributors)

制造的 [贡献者-img](https://contrib.rocks/)。 。 。 .

## 常见问题

### @eggjs/view 是什么？

彩蛋底部视图插件

### 如何安装 @eggjs/view？

在项目目录运行 npm install @eggjs/view，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：egg（4\.2\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @eggjs/view 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @eggjs/view 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @eggjs/view 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=22\.18\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @eggjs/view 可以商用吗？

@eggjs/view 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @eggjs/view 的下载量有多少？

根据 npm 官方下载统计，@eggjs/view 在 2026/10/13 – 2026/11/11 这 30 天内被下载 4,700 次，日均约 157 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @eggjs/view 还在维护吗？

最新版本 4\.1\.0 发布于 2026/10/07（1 个月前）；至今共发布 53 个版本，其中过去 12 个月发布了 33 个；首次发布于 2025/02/04。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。