docs(view): use async (#1717)

docs/source/zh-cn/advanced/view-plugin.md

@@ -160,7 +160,7 @@ module.exports = class MyCustomView {
 }
 ```
 
-具体代码可[查看](https:/eggjs/egg-view-nunjucks/blob/0433cadd3bc7a88e925b01bae08cc85c38a0af71/lib/view.js#L11)
+具体代码可[查看](https:/eggjs/egg-view-nunjucks/blob/2ee5ee992cfd95bc0bb5b822fbd72a6778edb118/lib/view.js#L11)
 
 ### 安全相关
 

docs/source/zh-cn/core/view.md

@@ -37,14 +37,14 @@ exports.nunjucks = {
 // config/config.default.js
 const path = require('path');
 module.exports = appInfo => {
- return {
-  view: {
-  root: [
-  path.join(appInfo.baseDir, 'app/view'),
-  path.join(appInfo.baseDir, 'path/to/another'),
-  ].join(',')
-  }
- }
+ const config = {};
+ config.view = {
+ root: [
+ path.join(appInfo.baseDir, 'app/view'),
+ path.join(appInfo.baseDir, 'path/to/another'),
+ ].join(',')
+ };
+ return config;
 };
 ```
 
@@ -66,10 +66,10 @@ module.exports = {
 };
 ```
 
-调用 render 渲染文件
+调用 render 渲染文件时，会根据上述配置的后缀名去寻找对应的模板引擎。
 
 ```js
-ctx.render('home.nj');
+await ctx.render('home.nj');
 ```
 
 必须配置文件后缀和模板引擎的映射，否则无法找到对应的模板引擎，但是可以使用 `defaultViewEngine` 做全局配置。
@@ -98,7 +98,7 @@ module.exports = {
 };
 
 // render app/view/home.nj
-ctx.render('home');
+await ctx.render('home');
 ```
 
 ## 渲染页面
@@ -111,66 +111,68 @@ ctx.render('home');
 
 ```js
 // {app_root}/app/controller/home.js
-module.exports = function* home(ctx){
- const data = { name: 'egg' };
+class HomeController extends Controller {
+ async index() {
+ const data = { name: 'egg' };
 
- // render a template, path relate to `app/view`
- yield ctx.render('home/index.tpl', data);
+  // render a template, path relate to `app/view`
+  await ctx.render('home/index.tpl', data);
 
- // or manually set render result to ctx.body
- ctx.body = yield ctx.renderView('path/to/file.tpl', data);
+  // or manually set render result to ctx.body
+  ctx.body = await ctx.renderView('path/to/file.tpl', data);
 
- // or render string directly
- ctx.body = yield ctx.renderString('hi, {{ name }}', data, {
- viewEngine: 'nunjucks',
- });
-};
+ // or render string directly
+ ctx.body = await ctx.renderString('hi, {{ name }}', data, {
+ viewEngine: 'nunjucks',
+ });
+ }
+}
 ```
 
 当使用 `renderString` 时需要指定模板引擎，如果已经定义 `defaultViewEngine` 这里可以省略。
 
 ## Locals
 
-在渲染页面的过程中，我们通常需要一个变量来收集需要传递给模板的变量，在框架里面，我们提供了 `app.locals` 和 `this.locals`。
+在渲染页面的过程中，我们通常需要一个变量来收集需要传递给模板的变量，在框架里面，我们提供了 `app.locals` 和 `ctx.locals`。
 
 - `app.locals` 为全局的，一般在 `app.js` 里面配置全局变量。
-- `this.locals` 为单次请求的，会合并 `app.locals`。
+- `ctx.locals` 为单次请求的，会合并 `app.locals`。
 - 可以直接赋值对象，框架在对应的 setter 里面会自动 merge。
 
 ```js
-// `app.locals` 会合并到 `this.locals
-this.app.locals = { a: 1 };
-this.locals.b = 2;
-console.log(this.locals); // { a: 1, b: 2 }
+// `app.locals` 会合并到 `ctx.locals
+ctx.app.locals = { a: 1 };
+ctx.locals.b = 2;
+console.log(ctx.locals); // { a: 1, b: 2 }
 
-// 一次请求过程中，仅会在第一次使用 `this.locals` 时把 `app.locals` 合并进去。
-this.app.locals = { a: 2 };
-console.log(this.locals); // 上面已经合并过一次，故输出还是 { a: 1, b: 2 }
+// 一次请求过程中，仅会在第一次使用 `ctx.locals` 时把 `app.locals` 合并进去。
+ctx.app.locals = { a: 2 };
+console.log(ctx.locals); // 上面已经合并过一次，故输出还是 { a: 1, b: 2 }
 
 // 也可以直接赋值整个对象，不用担心会覆盖前面的值，我们通过 setter 做了自动合并。
-this.locals.c = 3;
-this.locals = { d: 4 };
-console.log(this.locals); // { a: 1, b: 2, c: 3, d: 4 }
+ctx.locals.c = 3;
+ctx.locals = { d: 4 };
+console.log(ctx.locals); // { a: 1, b: 2, c: 3, d: 4 }
 ```
 
-但在实际业务开发中，controller 中一般不会直接使用这 2 个对象，直接使用 `this.render(name, data)` 即可：
-- 框架会自动把 `data` 合并到 `this.locals`。
+但在实际业务开发中，controller 中一般不会直接使用这 2 个对象，直接使用 `ctx.render(name, data)` 即可：
+- 框架会自动把 `data` 合并到 `ctx.locals`。
 - 框架会自动注入 `ctx`, `request`, `helper` 方便使用。
 
 ```js
-this.app.locals = { appName: 'showcase' };
+ctx.app.locals = { appName: 'showcase' };
 const data = { user: 'egg' };
 
-// will auto merge `data` to `this.locals`, output: egg - showcase
-yield this.renderString('{{ name }} - {{ appName }}', data);
+// will auto merge `data` to `ctx.locals`, output: egg - showcase
+await ctx.renderString('{{ name }} - {{ appName }}', data);
 
 // helper, ctx, request will auto inject
-yield this.renderString('{{ name }} - {{ helper.lowercaseFirst(ctx.app.config.baseDir) }}', data);
+await ctx.renderString('{{ name }} - {{ helper.lowercaseFirst(ctx.app.config.baseDir) }}', data);
 ```
 
 注意：
-- **this.locals 有缓存，只在第一次访问 this.locals 时合并 app.locals。**
-- 原 Koa 中的 `context.state`，由于容易产生歧义，在框架中被覆盖为 locals，即 `this.state` 和 `this.locals` 等价，我们建议使用后者。
+- **ctx.locals 有缓存，只在第一次访问 ctx.locals 时合并 app.locals。**
+- 原 Koa 中的 `ctx.state`，由于容易产生歧义，在框架中被覆盖为 locals，即 `ctx.state` 和 `ctx.locals` 等价，我们建议使用后者。
 
 ## Helper
 
@@ -181,7 +183,7 @@ yield this.renderString('{{ name }} - {{ helper.lowercaseFirst(ctx.app.config.ba
 exports.lowercaseFirst = str => str[0].toLowerCase() + str.substring(1);
 
 // app/controller/home.js
-yield this.renderString('{{ helper.lowercaseFirst(name) }}', data);
+await ctx.renderString('{{ helper.lowercaseFirst(name) }}', data);
 ```
 
 ## Security