Merge branch 'working' into css

Author: MachinisteWeb

ru/data.md

@@ -138,7 +138,7 @@ export default context => {
         // заполнено состоянием, необходимым для рендеринга приложения.
         // Когда мы присоединяем состояние к контексту, и есть опция `template`
         // используемая для рендерера, состояние будет автоматически
-        // сериализовано и внедрено в HTML как window.__INITIAL_STATE__.
+        // сериализовано и внедрено в HTML как `window.__INITIAL_STATE__`.
         context.state = store.state
 
         resolve(app)
@@ -215,7 +215,7 @@ if (window.__INITIAL_STATE__) {
 
 2. **Загружать данные после отображения нового представления:**
 
-  Эта стратегия располагает логику загрузки данных на стороне клиента в функции компонента `beforeMount`. Это позволяет переключаться мгновенно при срабатывании навигации по маршруту, поэтому приложение ощущается более отзывчивым. Однако на момент отображения нового представления у него не будет полных данных. Поэтому необходимо иметь добавлять условие проверки загруженности состояния для каждого компонента, использующего эту стратегию.
+  Эта стратегия располагает логику загрузки данных на стороне клиента в функции компонента `beforeMount`. Это позволяет переключаться мгновенно при срабатывании навигации по маршруту, поэтому приложение ощущается более отзывчивым. Однако на момент отображения нового представления у него не будет полных данных. Поэтому необходимо добавлять условие проверки загруженности состояния для каждого компонента, использующего эту стратегию.
 
   Этого можно достичь с помощью глобальной примеси на клиенте:
 

zh/README.md

@@ -0,0 +1,46 @@
+# Vue.js 服务器端渲染指南
+
+> **注意：**本指南需要最低为如下版本的 Vue，以及以下 library 支持：
+> - vue & vue-server-renderer >= 2.3.0
+> - vue-router >= 2.5.0
+> - vue-loader >= 12.0.0 & vue-style-loader >= 3.0.0如果先前已经使用过 Vue 2.2 的服务器端渲染(SSR)，您应该注意到，推荐的代码结构现在[略有不同](./structure.md)（使用新的 [runInNewContext](./api.md#runinnewcontext) 选项，并设置为 `false`）。现有的应用程序可以继续运行，但建议您迁移到新的推荐规范。
+
+## 什么是服务器端渲染(SSR)？
+
+Vue.js 是构建客户端应用程序的框架。默认情况下，可以在浏览器中输出 Vue 组件，进行生成 DOM 和操作 DOM。然而，也可以将同一个组件渲染为服务器端的 HTML 字符串，将它们直接发送到浏览器，最后将静态标记"混合"为客户端上完全交互的应用程序。
+
+服务器渲染的 Vue.js 应用程序也可以被认为是"同构"或"通用"，因为应用程序的大部分代码都可以在服务器**和**客户端上运行。
+
+## 为什么使用服务器端渲染(SSR)？
+
+与传统 SPA（Single-Page Application - 单页应用程序）相比，服务器端渲染(SSR)的优势主要在于：
+
+- 更好的 SEO，由于搜索引擎爬虫抓取工具可以直接查看完全渲染的页面。
+
+请注意，截至目前，Google 和 Bing 可以很好对同步 JavaScript 应用程序进行索引。在这里，同步是关键。如果您的应用程序初始展示 loading 菊花图，然后通过 Ajax 获取内容，抓取工具并不会等待异步完成后再行抓取页面内容。也就是说，如果 SEO 对你的站点至关重要，而你的页面又是异步获取内容，则你可能需要服务器端渲染(SSR)解决此问题。
+
+- 更快的内容到达时间(time-to-content)，特别是对于缓慢的网络情况或运行缓慢的设备。无需等待所有的 JavaScript 都完成下载并执行，才显示服务器渲染的标记，所以你的用户将会更快速地看到完整渲染的页面。通常可以产生更好的用户体验，并且对于那些「内容到达时间(time-to-content)与转化率直接相关」的应用程序而言，服务器端渲染(SSR)至关重要。
+
+使用服务器端渲染(SSR)时还需要有一些权衡之处：
+
+- 开发条件所限。浏览器特定的代码，只能在某些生命周期钩子函数(lifecycle hook)中使用；一些外部扩展库(external library)可能需要特殊处理，才能在服务器渲染应用程序中运行。
+- 涉及构建设置和部署的更多要求。与可以部署在任何静态文件服务器上的完全静态单页面应用程序(SPA)不同，服务器渲染应用程序，需要处于 Node.js server 运行环境。
+- 更多的服务器端负载。在 Node.js 中渲染完整的应用程序，显然会比仅仅提供静态文件的 server 更加大量占用 CPU 资源(CPU-intensive - CPU 密集)，因此如果您预料在高流量环境(high traffic)下使用，请准备相应的服务器负载，并明智地采用缓存策略。
+
+在对您的应用程序使用服务器端渲染(SSR)之前，您应该问第一个问题是否真的需要它。这主要取决于内容到达时间(time-to-content)对应用程序的重要程度。例如，如果您正在构建一个内部仪表盘，初始加载时的额外几百毫秒并不重要，这种情况下去使用服务器端渲染(SSR)将是一个小题大作之举。然而，内容到达时间(time-to-content)要求是绝对关键的指标，在这种情况下，服务器端渲染(SSR)可以帮助您实现最佳的初始加载性能。
+
+## 服务器端渲染 vs 预渲染(SSR vs Prerendering)
+
+如果您调研服务器端渲染(SSR)只是用来改善少数营销页面（例如 `/`, `/about`, `/contact` 等）的 SEO，那么您可能需要**预渲染**。无需使用 web 服务器实时动态编译 HTML，而是使用预渲染方式，在构建时(build time)简单地生成针对特定路由的静态 HTML 文件。优点是设置预渲染更简单，并可以将您的前端作为一个完全静态的站点。
+
+如果您使用 webpack，您可以使用 [prerender-spa-plugin](https://github.com/chrisvfritz/prerender-spa-plugin) 轻松地添加预渲染。它已经被 Vue 应用程序广泛测试 - 事实上，[作者](https://github.com/chrisvfritz)是 Vue 核心团队的成员。
+
+## 关于此指南
+
+本指南专注于，使用 Node.js server 的服务器端单页面应用程序渲染。将 Vue 服务器端渲染(SSR)与其他后端设置进行混合使用，是其它后端自身的一个主题，本指南不包括在内。
+
+本指南将会非常深入，并且假设您已经熟悉 Vue.js 本身，并且具有 Node.js 和 webpack 的相当不错的应用经验。如果您具有更高级解决方案，可以提供一个平缓的开箱即用体验，您应该去尝试使用 [Nuxt.js](http://nuxtjs.org/)。它建立在同等的 Vue 技术栈之上，但抽象出很多模板，并提供了一些额外的功能，例如静态站点生成。但是，如果您需要更直接地控制应用程序的结构，Nuxt.js 并不适合这种使用场景。无论如何，阅读本指南将更有助于更好地了解一切如何运行。
+
+当您阅读时，参考官方 [HackerNews Demo](https://github.com/vuejs/vue-hackernews-2.0/) 将会有所帮助，此示例使用了本指南涵盖的大部分技术。
+
+最后，请注意，本指南中的解决方案不是限定的 - 我们发现它们对我们来说很好，但这并不意味着无法继续改进。可能会在未来持续改进，欢迎通过随意提交 pull request 作出贡献！

zh/SUMMARY.md

@@ -0,0 +1,27 @@
+- [基本用法](basic.md)
+- [编写通用代码](universal.md)
+- [源码结构](structure.md)
+- [路由和代码分割](routing.md)
+- [数据预取和状态](data.md)
+- [客户端混合](hydration.md)
+- [Bundle Renderer 指引](bundle-renderer.md)
+- [构建配置](build-config.md)
+- [CSS 管理](css.md)
+- [Head 管理](head.md)
+- [缓存](caching.md)
+- [流式渲染](streaming.md)
+- [API 参考](api.md)
+    - [createRenderer](api.md#createrendereroptions)
+    - [createBundleRenderer](api.md#createbundlerendererbundle-options)
+    - [Class: Renderer](api.md#class-renderer)
+    - [Class: BundleRenderer](api.md#class-bundlerenderer)
+    - [Renderer 选项](api.md#renderer-options)
+    - [template](api.md#template)
+    - [clientManifest](api.md#clientmanifest)
+    - [inject](api.md#inject)
+    - [shouldPreload](api.md#shouldpreload)
+    - [runInNewContext](api.md#runinnewcontext)
+    - [basedir](api.md#basedir)
+    - [cache](api.md#cache)
+    - [directives](api.md#directives)
+    - [webpack 插件](api.md#webpack-plugins)

zh/basic.md

@@ -0,0 +1,144 @@
+# 基本用法
+
+## 安装
+
+```bash
+npm install vue vue-server-renderer --save
+```
+
+我们将在整个指南中使用 NPM，但是还可以随意使用 [Yarn](https://yarnpkg.com/en/)。
+
+#### 注意
+
+- 推荐使用 Node.js 版本 6+。
+- `vue-server-renderer` 和 `vue` 必须匹配版本。
+- `vue-server-renderer` 依赖一些 Node.js 原生模块，因此只能在 Node.js 中使用。我们可能会提供一个更简单的构建，可以在将来在其他「JavaScript 运行时(runtime)」运行。
+
+## 渲染一个 Vue 实例
+
+```js
+// 第 1 步：创建一个 Vue 实例
+const Vue = require('vue')
+const app = new Vue({
+  template: `<div>Hello World</div>`
+})
+// 第 2 步：创建一个 renderer
+const renderer = require('vue-server-renderer').createRenderer()
+// 第 3 步：将 Vue 实例渲染为 HTML
+renderer.renderToString(app, (err, html) => {
+  if (err) throw err
+  console.log(html)
+  // => <div data-server-rendered="true">Hello World</div>
+})
+```
+
+## 与服务器集成
+
+在 Node.js 服务器中使用时相当简单直接，例如 [Express](https://expressjs.com/)：
+
+```bash
+npm install express --save
+```
+
+---
+
+```js
+const Vue = require('vue')
+const server = require('express')()
+const renderer = require('vue-server-renderer').createRenderer()
+server.get('*', (req, res) => {
+  const app = new Vue({
+    data: {
+      url: req.url
+    },
+    template: `<div>访问的 URL 是： {{ url }}</div>`
+  })
+  renderer.renderToString(app, (err, html) => {
+    if (err) {
+      res.status(500).end('Internal Server Error')
+      return
+    }
+    res.end(`
+      <!DOCTYPE html>
+      <html lang="en">
+        <head><title>Hello</title></head>
+        <body>${html}</body>
+      </html>
+    `)
+  })
+})
+server.listen(8080)
+```
+
+## 使用一个页面模板
+
+当你在渲染 Vue 应用程序时，renderer 只从应用程序生成 HTML 标记(markup)。在这个示例中，我们必须用一个额外的 HTML 页面包裹容器，来包裹生成的 HTML 标记。
+
+为了简化这些，你可以直接在创建 renderer 时提供一个页面模板。多数时候，我们会将页面模板放在特有的文件中，例如 `index.template.html`：
+
+```html
+<!DOCTYPE html>
+<html lang="en">
+  <head><title>Hello</title></head>
+  <body>
+    <!--vue-ssr-outlet-->
+  </body>
+</html>
+```
+
+注意 `<!--vue-ssr-outlet-->` 注释 -- 这里将是应用程序 HTML 标记注入的地方。
+
+然后，我们可以读取和传输文件到 Vue renderer 中：
+
+```js
+const renderer = createRenderer({
+  template: require('fs').readFileSync('./index.template.html', 'utf-8')
+})
+renderer.renderToString(app, (err, html) => {
+  console.log(html) // will be the full page with app content injected.
+})
+```
+
+### 模板插值
+
+模板还支持简单插值。给定如下模板：
+
+```html
+<html>
+  <head>
+    <!-- 使用双花括号(double-mustache)进行 HTML 转义插值(HTML-escaped interpolation) -->
+    <title>{{ title }}</title>
+    <!-- 使用三花括号(triple-mustache)进行 HTML 不转义插值(non-HTML-escaped interpolation) -->
+    {{{ meta }}}
+  </head>
+  <body>
+    <!--vue-ssr-outlet-->
+  </body>
+</html>
+```
+
+我们可以通过传入一个"渲染上下文对象"，作为 `renderToString` 函数的第二个参数，来提供插值数据：
+
+```js
+const context = {
+  title: 'hello',
+  meta: `
+    <meta ...>
+    <meta ...>
+  `
+}
+renderer.renderToString(app, context, (err, html) => {
+  // page title will be "Hello"
+  // with meta tags injected
+})
+```
+
+也可以与 Vue 应用程序实例共享 `context` 对象，允许模板插值中的组件动态地注册数据。
+
+此外，模板支持一些高级特性，例如：
+
+- 在使用 `*.vue` 组件时，自动注入「关键的 CSS(critical CSS)」；
+- 在使用 `clientManifest` 时，自动注入「资源链接(asset links)和资源预加载提示(resource hints)」；
+- 在嵌入 Vuex 状态进行客户端融合(client-side hydration)时，自动注入以及 XSS 防御。
+
+在之后的指南中介绍相关概念时，我们将详细讨论这些。