update zh docs

skyline0705 · skyline0705 · commit ee944ca53115 · 2019-02-19T02:38:35.000+08:00
diff --git a/docs/zh/api/README.md b/docs/zh/api/README.md
@@ -84,6 +84,11 @@ bundleRenderer.renderToStream([context]): stream.Readable
 
 ### template
 
+- **类型:**
+  - `string`
+  - `string | (() => string | Promise<string>)` (2.6开始)
+ **使用字符串模板时:**
+
 为整个页面的 HTML 提供一个模板。此模板应包含注释 `<!--vue-ssr-outlet-->`，作为渲染应用程序内容的占位符。
 
 模板还支持使用渲染上下文 (render context) 进行基本插值：
@@ -101,13 +106,41 @@ bundleRenderer.renderToStream([context]): stream.Readable
 
   在 2.5.0+ 版本中，嵌入式 script 也可以也可以在生产模式 (production mode) 下自行移除。
 
+  在 2.6.0+ 版本中，如果存在`context.nonce`，它将作为`nonce`属性添加到嵌入式脚本中。这将允许内联脚本使用nonce属性来保证CSP。
+
 此外，当提供 `clientManifest` 时，模板会自动注入以下内容：
 
 - 渲染当前页面所需的最优客户端 JavaScript 和 CSS 资源（支持自动推导异步代码分割所需的文件）；
 - 为要渲染页面提供最佳的 `<link rel="preload/prefetch">` 资源提示 (resource hints)。
 
 你也可以通过将 `inject: false` 传递给 renderer，来禁用所有自动注入。
 
+**使用函数模板时:**
+
+::: warning 警告
+函数模板仅支持在2.6+且配合`renderer.renderToString`时使用。 不支持在`renderer.renderToStream`时使用
+:::
+
+`template`选项也可以是一个函数，返回最终呈现的HTML或返回可被解决为最终呈现的HTML的Promise。这允许您在模板呈现过程中使用原生字符串模板和异步操作。
+
+该函数接收两个参数：
+1. 应用组件的渲染结果字符串；
+2. 渲染上下文对象。
+
+示例:
+``` js
+const renderer = createRenderer({
+  template: (result, context) => {
+    return `<html>
+      <head>${context.head}</head>
+      <body>${result}</body>
+    <html>`
+  }
+})
+```
+
+注意当时用自定义的函数模板时，不会有任何自动注入行为发生 - 你将完全控制最终呈现的HTML所包含的内容，但也需要自己去管理所有你需要引入的部分（例如，使用bundle渲染时所生成的资源链接）。
+
 具体查看：
 
 - [使用一个页面模板](../guide/#using-a-page-template)
@@ -245,6 +278,29 @@ const renderer = createRenderer({
 
 例如，请查看 [`v-show` 的服务器端实现](https://github.com/vuejs/vue/blob/dev/src/platforms/web/server/directives/show.js)。
 
+-----------------------------------
+### serializer
+> 2.6新增
+
+为`context.state`提供一个自定义序列化函数。 由于序列化状态将是最终HTML中的一部分，出于安全原因，使用适当的函数转义HTML字符显得非常重要。当设定`{ isJSON: true }`时，默认所使用的序列化器是[serialize-javascript](https://github.com/yahoo/serialize-javascript)
+
+## 仅限服务器端使用的组件选项
+### serverCacheKey
+- **类型:** `(props) => any`
+
+  根据传入的属性(props)，生成并返回组件缓存键(cache key)。这里并不允许访问`this`。
+
+  从2.6开始, 你可以通过显式的返回`false`来避免缓存。
+
+  更多信息在 [组件级别缓存(Component-level Caching)](../guide/caching.html#component-level-caching).
+
+### serverPrefetch
+- **类型:** `() => Promise<any>`
+
+  在服务端渲染的过程中获取异步数据。此函数需要获取到的数据保存在全局store中并返回一个Promise。服务端渲染将会在此钩子函数进行等待，直到Promise被解决。此钩子函数允许通过`this`访问组件实例。
+
+  更多信息在 [数据获取(Data Fetching)](../guide/data.html).
+
 ## webpack 插件
 
 webpack 插件作为独立文件提供，并且应当直接 require：
diff --git a/docs/zh/guide/caching.md b/docs/zh/guide/caching.md
@@ -73,6 +73,10 @@ export default {
 
 返回常量将导致组件始终被缓存，这对纯静态组件是有好处的。
 
+::: tip 避免缓存
+从2.6.0开始，通过在`serverCacheKey`中显式返回`false`，将会避免缓存，重新将组件渲染
+:::
+
 ### 何时使用组件缓存
 
 如果 renderer 在组件渲染过程中进行缓存命中，那么它将直接重新使用整个子树的缓存结果。这意味着在以下情况，你**不**应该缓存组件：
diff --git a/docs/zh/guide/data.md b/docs/zh/guide/data.md

-Original file line number
+Diff line change
 ## 数据预取存储容器 (Data Store)
 -在服务器端渲染(SSR)期间，我们本质上是在渲染我们应用程序的"快照"，所以如果应用程序依赖于一些异步数据，**那么在开始渲染过程之前，需要先预取和解析好这些数据**。
 +在服务器端渲染(SSR)期间，我们本质上是在渲染我们应用程序的"快照"。在我们装载客户端应用之前，我们组件中所应用的异步数据需要处于可用状态 - 否则客户端应用会使用不同的状态进行渲染，并导致激活失败。
 -另一个需要关注的问题是在客户端，在挂载 (mount) 到客户端应用程序之前，需要获取到与服务器端应用程序完全相同的数据 - 否则，客户端应用程序会因为使用与服务器端应用程序不同的状态，然后导致混合失败。
+-
 -为了解决这个问题，获取的数据需要位于视图组件之外，即放置在专门的数据预取存储容器(data store)或"状态容器(state container)）"中。首先，在服务器端，我们可以在渲染之前预取数据，并将数据填充到 store 中。此外，我们将在 HTML 中序列化(serialize)和内联预置(inline)状态。这样，在挂载(mount)到客户端应用程序之前，可以直接从 store 获取到内联预置(inline)状态。
 +为了解决这个问题，获取的数据需要位于视图组件之外，即放置在专门的数据预取存储容器(data store)或"状态容器(state container)）"中。首先，在服务器端，我们可以在渲染时预取数据，并将数据填充到 store 中。此外
 +，我们将在应用渲染完成后，在 HTML 中序列化(serialize)和内联预置(inline)状态。这样，在挂载(mount)到客户端应用程序之前，可以直接从 store 获取到内联预置(inline)状态。
 为此，我们将使用官方状态管理库 [Vuex](https://github.com/vuejs/vuex/)。我们先创建一个 `store.js` 文件，里面会模拟一些根据 id 获取 item 的逻辑：
 import { fetchItem } from './api'
 export function createStore () {
 +  // 重要: state必须是一个函数，
 +  // 这样模块才可以多次实例化
   return new Vuex.Store({
 -    state: {
 +    state: () => ({
       items: {}
 -    },
 +    }),
     actions: {
       fetchItem ({ commit }, id) {
         // `store.dispatch()` 会返回 Promise，
         })
+      }
     },
++
     mutations: {
       setItem (state, { id, item }) {
         Vue.set(state.items, id, item)
+}
 ```
 +::: warning
 +大多数情况下，你都应该将 `state` 包装成一个函数，这样它的状态便不会泄露到下一个服务端执行。
 +[更多信息](./structure.md#avoid-stateful-singletons)
 +:::
++
++
 然后修改 `app.js`：
 ``` js
 我们需要通过访问路由，来决定获取哪部分数据 - 这也决定了哪些组件需要渲染。事实上，给定路由所需的数据，也是在该路由上渲染组件时所需的数据。所以在路由组件中放置数据预取逻辑，是很自然的事情。
 -我们将在路由组件上暴露出一个自定义静态函数 `asyncData`。注意，由于此函数会在组件实例化之前调用，所以它无法访问 `this`。需要将 store 和路由信息作为参数传递进去：
 +我们将在组件中使用 `serverPrefetch` 选项（2.6.0+中新增）。这个选项会被服务端渲染所识别，并且暂停渲染过程，直到它所返回的promise被解决。这允许我们在渲染过程中“等待”异步数据。
++
 +::: tip 提示
 +你可以在任何组件中使用`serverPrefetch`，不仅仅局限在路由级别组件上
 +:::
++
 +这里有一个`Item.vue`组件示例，它在路由匹配`'/item/:id'`时进行渲染。由于此时组件实例已经被创建，所以可以通过`this`进行访问：
 ``` html
 <!-- Item.vue -->
 <template>
 -  <div>{{ item.title }}</div>
 +  <div v-if="item">{{ item.title }}</div>
 +  <div v-else>...</div>
 </template>
 <script>
 export default {
 -  asyncData ({ store, route }) {
 -    // 触发 action 后，会返回 Promise
 -    return store.dispatch('fetchItem', route.params.id)
 -  },
   computed: {
     // 从 store 的 state 对象中的获取 item。
     item () {
       return this.$store.state.items[this.$route.params.id]
+    }
 +  },
 +  // 仅限服务端
 +  // 它将在服务端渲染时自动被调用
 +  serverPrefetch () {
 +    // 在执行后返回Promise
 +    // 以便组件在渲染执行之前等待
 +    return this.fetchItem()
 +  },
 +  // 仅限客户端
 +  mounted () {
 +    // 如果我们确定不在服务端执行
 +    // 那么在这里获取item（首先展示加载文字）
 +    if (!this.item) {
 +      this.fetchItem()
 +    }
 +  },
 +  methods: {
 +    fetchItem () {
 +      // 在执行后返回Promise
 +      return store.dispatch('fetchItem', this.$route.params.id)
 +    }
+  }
+}
 </script>
 ```
 -## 服务器端数据预取 (Server Data Fetching)
 +::: warning 警告
 +为了避免逻辑执行两次，你需要检查组件在`mounted`钩子触发时是否已完成服务端渲染
 +:::
 -在 `entry-server.js` 中，我们可以通过路由获得与 `router.getMatchedComponents()` 相匹配的组件，如果组件暴露出 `asyncData`，我们就调用这个方法。然后我们需要将解析完成的状态，附加到渲染上下文(render context)中。
 +::: tip 提示
 +你会注意到，`fetchItem()`逻辑在每一个组件中被重复调用了多次 (在 `serverPrefetch`, `mounted` 和 `watch` 回调) - 建议您自己进行抽象（例如使用混合或插件机制）以简化此类代码
 +:::
++
 +## 最终状态注入
++
 +现在我们知道了组件中，渲染过程会等待数据获取完成后继续进行，那么我们如何知道何时才是“完成”状态？为了实现此逻辑，我们需要在渲染上下文中附加一个`rendered`回调函数（同样是2.6新增），服务端渲染会在渲染过程完成时调用此回调。在这个时刻，全局store中保存的是应用的最终状态。此时我们可以在回调中将它注入到上下文当中：
 ``` js
 // entry-server.js
     router.push(context.url)
     router.onReady(() => {
 -      const matchedComponents = router.getMatchedComponents()
 -      if (!matchedComponents.length) {
 -        return reject({ code: 404 })
 -      }
+-
 -      // 对所有匹配的路由组件调用 `asyncData()`
 -      Promise.all(matchedComponents.map(Component => {
 -        if (Component.asyncData) {
 -          return Component.asyncData({
 -            store,
 -            route: router.currentRoute
 -          })
 -        }
 -      })).then(() => {
 -        // 在所有预取钩子(preFetch hook) resolve 后，
 -        // 我们的 store 现在已经填充入渲染应用程序所需的状态。
 -        // 当我们将状态附加到上下文，
 -        // 并且 `template` 选项用于 renderer 时，
 -        // 状态将自动序列化为 `window.__INITIAL_STATE__`，并注入 HTML。
 +      // `rendered`钩子函数会在应用完成渲染时被调用
 +      context.rendered = () => {
 +        // 在应用渲染完成后，此时我们的store中
 +        // 填满了组件中所使用的方案状态。
 +        // 当我们将状态附加到上下文中，并且`template`选项
 +        // 被渲染器所使用时，状态会被自动序列化并以`window.__INITIAL_STATE__`
 +        // 的形式注入到HTML中
         context.state = store.state
 +      }
 -        resolve(app)
 -      }).catch(reject)
 +      resolve(app)
     }, reject)
   })
+}
 ``` js
 // entry-client.js
 -const { app, router, store } = createApp()
 +const { app, store } = createApp()
 if (window.__INITIAL_STATE__) {
 +  // 使用服务端注入的数据进行store的初始化工作
   store.replaceState(window.__INITIAL_STATE__)
+}
 +app.$mount('#app')
 ```
+-
 -## 客户端数据预取 (Client Data Fetching)
+-
 -在客户端，处理数据预取有两种不同方式：
+-
 -1. **在路由导航之前解析数据：**
+-
 -  使用此策略，应用程序会等待视图所需数据全部解析之后，再传入数据并处理当前视图。好处在于，可以直接在数据准备就绪时，传入视图渲染完整内容，但是如果数据预取需要很长时间，用户在当前视图会感受到"明显卡顿"。因此，如果使用此策略，建议提供一个数据加载指示器 (data loading indicator)。
+-
 -  我们可以通过检查匹配的组件，并在全局路由钩子函数中执行 `asyncData` 函数，来在客户端实现此策略。注意，在初始路由准备就绪之后，我们应该注册此钩子，这样我们就不必再次获取服务器提取的数据。
+-
 -  ``` js
 -  // entry-client.js
+-
 -  // ...忽略无关代码
+-
 -  router.onReady(() => {
 -    // 添加路由钩子函数，用于处理 asyncData.
 -    // 在初始路由 resolve 后执行，
 -    // 以便我们不会二次预取(double-fetch)已有的数据。
 -    // 使用 `router.beforeResolve()`，以便确保所有异步组件都 resolve。
 -    router.beforeResolve((to, from, next) => {
 -      const matched = router.getMatchedComponents(to)
 -      const prevMatched = router.getMatchedComponents(from)
+-
 -      // 我们只关心非预渲染的组件
 -      // 所以我们对比它们，找出两个匹配列表的差异组件
 -      let diffed = false
 -      const activated = matched.filter((c, i) => {
 -        return diffed || (diffed = (prevMatched[i] !== c))
 -      })
+-
 -      if (!activated.length) {
 -        return next()
 -      }
+-
 -      // 这里如果有加载指示器 (loading indicator)，就触发
+-
 -      Promise.all(activated.map(c => {
 -        if (c.asyncData) {
 -          return c.asyncData({ store, route: to })
 -        }
 -      })).then(() => {
+-
 -        // 停止加载指示器(loading indicator)
+-
 -        next()
 -      }).catch(next)
 -    })
+-
 -    app.$mount('#app')
 -  })
 -  ```
+-
 -2. **匹配要渲染的视图后，再获取数据：**
+-
 -  此策略将客户端数据预取逻辑，放在视图组件的 `beforeMount` 函数中。当路由导航被触发时，可以立即切换视图，因此应用程序具有更快的响应速度。然而，传入视图在渲染时不会有完整的可用数据。因此，对于使用此策略的每个视图组件，都需要具有条件加载状态。
+-
 -  这可以通过纯客户端 (client-only) 的全局 mixin 来实现：
+-
 -  ``` js
 -  Vue.mixin({
 -    beforeMount () {
 -      const { asyncData } = this.$options
 -      if (asyncData) {
 -        // 将获取数据操作分配给 promise
 -        // 以便在组件中，我们可以在数据准备就绪后
 -        // 通过运行 `this.dataPromise.then(...)` 来执行其他任务
 -        this.dataPromise = asyncData({
 -          store: this.$store,
 -          route: this.$route
 -        })
 -      }
 -    }
 -  })
 -  ```
+-
 -这两种策略是根本上不同的用户体验决策，应该根据你创建的应用程序的实际使用场景进行挑选。但是无论你选择哪种策略，当路由组件重用（同一路由，但是 params 或 query 已更改，例如，从 `user/1` 到 `user/2`）时，也应该调用 `asyncData` 函数。我们也可以通过纯客户端 (client-only) 的全局 mixin 来处理这个问题：
+-
 -``` js
 -Vue.mixin({
 -  beforeRouteUpdate (to, from, next) {
 -    const { asyncData } = this.$options
 -    if (asyncData) {
 -      asyncData({
 -        store: this.$store,
 -        route: to
 -      }).then(next).catch(next)
 -    } else {
 -      next()
 -    }
 -  }
 -})
 -```
+-
 ## Store 代码拆分 (Store Code Splitting)
 在大型应用程序中，我们的 Vuex store 可能会分为多个模块。当然，也可以将这些模块代码，分割到相应的路由组件 chunk 中。假设我们有以下 store 模块：
 // store/modules/foo.js
 export default {
   namespaced: true,
++
   // 重要信息：state 必须是一个函数，
   // 因此可以创建多个实例化该模块
   state: () => ({
     count: 0
   }),
++
   actions: {
     inc: ({ commit }) => commit('inc')
   },
++
   mutations: {
     inc: state => state.count++
+  }
 import fooStoreModule from '../store/modules/foo'
 export default {
 -  asyncData ({ store }) {
 -    store.registerModule('foo', fooStoreModule)
 -    return store.dispatch('foo/inc')
 +  computed: {
 +    fooCount () {
 +      return this.$store.state.foo.count
 +    }
 +  },
 +  // 仅限服务端
 +  serverPrefetch () {
 +    this.registerFoo()
 +    return this.fooInc()
 +  },
 +  // 仅限客户端
 +  mounted () {
 +    // 我们已经在服务端增加了'count'
 +    // 我们通过'foo'状态是否存在来进行检查
 +    const alreadyIncremented = !!this.$store.state.foo
 +    // 我们注册foo模块
 +    this.registerFoo()
 +    if (!alreadyIncremented) {
 +      this.fooInc()
 +    }
   },
   // 重要信息：当多次访问路由时，
     this.$store.unregisterModule('foo')
   },
 -  computed: {
 -    fooCount () {
 -      return this.$store.state.foo.count
 +  methods: {
 +    registerFoo () {
 +      // 如果状态在服务端已被注入，则保留之前的状态
 +      this.$store.registerModule('foo', fooStoreModule, { preserveState: true })
 +    },
 +    fooInc () {
 +      return this.$store.dispatch('foo/inc')
+    }
+  }
+}
 由于模块现在是路由组件的依赖，所以它将被 webpack 移动到路由组件的异步 chunk 中。
 ----
+-
 -哦？看起来要写很多代码！这是因为，通用数据预取可能是服务器渲染应用程序中最复杂的问题，我们正在为下一步开发做前期准备。一旦设定好模板示例，创建单独组件实际上会变得相当轻松。
 +::: warning 警告
 +不要忘记在`registerModule`时使用`preserveState: true`选项，这样我们就可以保持服务器端注入的状态了
 +:::