Merge branch 'master' into cn

# Conflicts: # src/perf/index.md # src/v2/api/index.md # src/v2/cookbook/index.md # src/v2/guide/comparison.md # src/v2/guide/components.md # src/v2/guide/events.md # src/v2/guide/forms.md # src/v2/guide/index.md # src/v2/guide/installation.md # src/v2/guide/instance.md # src/v2/guide/join.md # src/v2/guide/list.md # src/v2/guide/render-function.md # src/v2/guide/state-management.md # src/v2/guide/syntax.md # src/v2/guide/transitioning-state.md # src/v2/guide/unit-testing.md # src/v2/style-guide/index.md # themes/vue/layout/page.ejs # themes/vue/layout/partials/ecosystem_dropdown.ejs # themes/vue/layout/partials/sidebar.ejs # themes/vue/layout/sponsors-page.ejs # themes/vue/source/js/common.js
volksbright · Mar 18, 2018 · cf9591a · cf9591a
2 parents ad6d457 + 2f8d5d1
commit cf9591a
Show file tree

Hide file tree

Showing 140 changed files with 9,139 additions and 250 deletions.
diff --git a/assets/data.ai b/assets/data.ai
diff --git a/assets/hn-architecture.ai b/assets/hn-architecture.ai
diff --git a/assets/mvvm.ai b/assets/mvvm.ai
diff --git a/assets/why-vue/french.js.srt b/assets/why-vue/french.js.srt
diff --git a/package-lock.json b/package-lock.json
diff --git a/package.json b/package.json
@@ -25,4 +25,4 @@
     "hexo-server": "^0.2.2",
     "request": "^2.83.0"
   }
-}
+}
diff --git a/pre-deploy.js b/pre-deploy.js
@@ -39,6 +39,7 @@ Promise.all([
     installation
       .replace(/vue_version: .*/, 'vue_version: ' + version)
       .replace(/gz_size:.*/g, `gz_size: "${prodSize}"`)
+      .replace(/\/vue@[\d\.]+\//g, `/vue@${version}/`)
   )
   console.log(`\nSuccessfully updated Vue version and gzip file size.\n`)
 }).catch(err => {

diff --git a/src/_posts/012-release.md b/src/_posts/012-release.md
@@ -25,7 +25,7 @@ There are also additional props-related improvements such as explicit one-time o
 
 ### Filter Arguments Improvements
 
-In 0.11, filters always receive their arguments as plain strings. An argument can be enclosed in quotes to include whitespace, but the quotes are not automatically stripped when passed into the filter function. Some users were also confused about how to retrive a dynamic value on the vm instead of a plain string.
+In 0.11, filters always receive their arguments as plain strings. An argument can be enclosed in quotes to include whitespace, but the quotes are not automatically stripped when passed into the filter function. Some users were also confused about how to retrieve a dynamic value on the vm instead of a plain string.
 
 In 0.12, the filter argument syntax now follows a simple rule: if an argument is enclosed in quotes, it will be passed in as a plain string; otherwise, it will be evaluated against the current vm as a dynamic value.
 

diff --git a/src/images/components.png b/src/images/components.png
diff --git a/src/images/data.png b/src/images/data.png
diff --git a/src/images/dom-tree.png b/src/images/dom-tree.png
diff --git a/src/images/hn-architecture.png b/src/images/hn-architecture.png
diff --git a/src/images/hn.png b/src/images/hn.png
diff --git a/src/images/lifecycle.png b/src/images/lifecycle.png
diff --git a/src/images/logged-proxied-data.png b/src/images/logged-proxied-data.png
diff --git a/src/images/mvvm.png b/src/images/mvvm.png
diff --git a/src/images/props-events.png b/src/images/props-events.png
diff --git a/src/images/state.png b/src/images/state.png
diff --git a/src/images/transition.png b/src/images/transition.png
diff --git a/src/images/typescript-type-error.png b/src/images/typescript-type-error.png
diff --git a/src/images/vue-component-with-preprocessors.png b/src/images/vue-component-with-preprocessors.png
diff --git a/src/images/vue-component.png b/src/images/vue-component.png
diff --git a/src/perf/index.md b/src/perf/index.md
diff --git a/src/v2/api/index.md b/src/v2/api/index.md
@@ -1,4 +1,5 @@
 ---
+title: API
 type: api
 ---
 
@@ -159,7 +160,7 @@ type: api
 
 - **用法：**
 
-  设置为 `true`，以在浏览器开发工具 timeline 中，启用组件初始化(init)、编译(compile)、渲染(render)和修补(patch)的性能追踪。只能在开发模式和支持 [performance.mark](https://developer.mozilla.org/en-US/docs/Web/API/Performance/mark) API 的浏览器中运行。
+  设置为 `true`，以在浏览器开发工具的 performance/timeline 面板中，启用组件初始化(init)、编译(compile)、渲染(render)和修补(patch)的性能追踪。只能在开发模式和支持 [performance.mark](https://developer.mozilla.org/en-US/docs/Web/API/Performance/mark) API 的浏览器中运行。
 
 ### productionTip
 
@@ -256,7 +257,7 @@ type: api
 
   设置对象的属性。如果对象是响应式的，确保属性被创建后也是响应式的，同时触发视图更新。这个方法主要用于避开 Vue 不能检测属性被添加的限制。
 
-  **注意对象不能是 Vue 实例，或者 Vue 实例的根数据对象。**
+  <p class="tip">target 对象不能是 Vue 实例，或者 Vue 实例的根数据对象。</p>
 
 - **参考：**[深入响应式原理](../guide/reactivity.html)
 
@@ -977,7 +978,7 @@ type: api
 
   允许声明扩展另一个组件(可以是一个简单的选项对象或构造函数),而无需使用 `Vue.extend`。这主要是为了便于扩展单文件组件。
 
-  这和 `mixins` 类似，区别在于，组件自身的选项会比要扩展的源组件具有更高的优先级。
+  这与 `mixins` 类似。
 
 - **示例：**
 
@@ -1007,7 +1008,13 @@ type: api
 
   `provide` 选项应该是一个对象或返回一个对象的函数。该对象包含可注入其子孙的属性。在该对象中你可以使用 ES2015 Symbols 作为 key，但是只在原生支持 `Symbol` 和 `Reflect.ownKeys` 的环境下可工作。
 
-  `inject` 选项应该是一个字符串数组或一个对象，该对象的 key 代表了本地绑定的名称，value 为其 key (字符串或 Symbol) 以在可用的注入中搜索。
+  `inject` 选项应该是以下二者之一：
+  - 一个字符串数组
+  - 一个对象，对象的 key 是本地的绑定名称，value 是以下二者之一：
+    - 在可访问的 injections 对象中，通过 key （字符串或 Symbol）检索到的值
+    - 一个对象，该对象的
+      - `name` 属性是：在可访问的 injections 对象中，通过 key （字符串或 Symbol）检索到的值
+      - 并且 `default` 属性是：降级情况下会用到的回退值(fallback value)
 
   > 提示：`provide` 和 `inject` 绑定并不是可响应的。这是刻意为之的。然而，如果你传入了一个可监听的对象，那么其对象的属性还是可响应的。
 
@@ -1719,7 +1726,7 @@ type: api
 
 - **用法：**
 
-  根据表达式之真假值，切换元素的 `display` CSS 属性。
+  根据表达式的 truthy 和 falsy 值，切换元素的 `display` CSS 属性。
 
   当条件变化时该指令触发过渡效果。
 
@@ -1854,7 +1861,7 @@ type: api
 
   从 `2.4.0` 开始，`v-on` 同样支持不带参数绑定一个事件/监听器键值对的对象。注意当使用对象语法时，是不支持任何修饰器的。
 
-  用在普通元素上时，只能监听 **原生 DOM 事件**。用在自定义元素组件上时，也可以监听子组件触发的**自定义事件**。
+  用在普通元素上时，只能监听 [**原生 DOM 事件**](https://developer.mozilla.org/en-US/docs/Web/Events)。用在自定义元素组件上时，也可以监听子组件触发的**自定义事件**。
 
   在监听原生 DOM 事件时，方法以事件为唯一的参数。如果使用内联语句，语句可以访问一个 `$event` 属性： `v-on:click="handle('ok', $event)"`。
 

diff --git a/src/v2/cookbook/adding-instance-properties.md b/src/v2/cookbook/adding-instance-properties.md
@@ -1,7 +1,7 @@
 ---
 title: Adding Instance Properties
 type: cookbook
-order: 1.1
+order: 2
 ---
 
 ## Simple Example

diff --git a/src/v2/cookbook/cookbook-contributions.md b/src/v2/cookbook/cookbook-contributions.md
@@ -1,12 +1,12 @@
 ---
 title: Cookbook Contributions
 type: cookbook
-order: 1000
+order: 1
 ---
 
 ## What we're looking for
 
-The Cookbook gives developers examples to work off of that both cover common or interesting use cases, and also progressively explain more complex detail. Our goal is to move beyond a simple introductory example, and demonstrate concepts that are more widely applicable, as well as some caveats to the approach. 
+The Cookbook gives developers examples to work off of that both cover common or interesting use cases, and also progressively explain more complex detail. Our goal is to move beyond a simple introductory example, and demonstrate concepts that are more widely applicable, as well as some caveats to the approach.
 
 If you're interested in contributing, please initiate collaboration by filing an issue under the tag **cookbook idea** with your concept so that we can help guide you to a successful pull request. After your idea has been approved, please follow the template below as much as possible. Some sections are required, and some are optional. Following the numerical order is strongly suggested, but not required.
 
@@ -33,6 +33,7 @@ _required_
 _required_
 
 Demonstrate the code that would power a common or interesting use case, either by:
+
 1. Walking through a few terse examples of setup, or
 2. Embedding a codepen/jsfiddle example
 
@@ -58,4 +59,4 @@ This section is required when you've provided the section above about avoidance.
 
 ## Thank you
 
-It takes time to contribute to documentation, and if you spend the time to submit a PR this section of our docs, you do so with our gratitude.
+It takes time to contribute to documentation, and if you spend the time to submit a PR this section of our docs, you do so with our gratitude.
diff --git a/src/v2/cookbook/creating-custom-scroll-directives.md b/src/v2/cookbook/creating-custom-scroll-directives.md
@@ -0,0 +1,154 @@
+---
+title: Creating Custom Scroll Directives
+type: cookbook
+order: 7
+---
+
+## Simple Example
+
+There are many times that we might want to add a bit of behavior, especially animation, to a scroll event on a site. There are many ways to do so, but the path with the least amount of code and dependencies is perhaps to use a [custom directive](https://vuejs.org/v2/guide/custom-directive.html) to create a hook for anything that fires off a particular scroll event.
+
+```js
+Vue.directive('scroll', {
+  inserted: function (el, binding) {
+    let f = function (evt) {
+      if (binding.value(evt, el)) {
+        window.removeEventListener('scroll', f)
+      }
+    }
+    window.addEventListener('scroll', f)
+  }
+})
+
+// main app
+new Vue({
+  el: '#app',
+  methods: {
+    handleScroll: function (evt, el) {
+      if (window.scrollY > 50) {
+        el.setAttribute(
+          'style',
+          'opacity: 1; transform: translate3d(0, -10px, 0)'
+        )
+      }
+      return window.scrollY > 100
+    }
+  }
+})
+```
+
+```html
+<div id="app">
+  <h1 class="centered">Scroll me</h1>
+  <div class="box" v-scroll="handleScroll">
+    <p>Lorem ipsum dolor sit amet, consectetur adipisicing elit. A atque amet harum aut ab veritatis earum porro praesentium ut corporis. Quasi provident dolorem officia iure fugiat, eius mollitia sequi quisquam.</p>
+  </div>
+</div>
+```
+
+<p class="tip">Remember! The directive must be registered before the Vue instance.</p>
+
+We'd also need a style property that will transition the intermediary values here, in this case:
+
+```
+.box {
+  transition: 1.5s all cubic-bezier(0.39, 0.575, 0.565, 1);
+}
+```
+
+<p data-height="450" data-theme-id="5162" data-slug-hash="983220ed949ac670dff96bdcaf9d3338" data-default-tab="result" data-user="sdras" data-embed-version="2" data-pen-title="Custom Scroll Directive- CSS Transition" class="codepen">See the Pen <a href="https://codepen.io/sdras/pen/983220ed949ac670dff96bdcaf9d3338/">Custom Scroll Directive- CSS Transition</a> by Sarah Drasner (<a href="https://codepen.io/sdras">@sdras</a>) on <a href="https://codepen.io">CodePen</a>.</p>
+<script async src="https://static.codepen.io/assets/embed/ei.js"></script>
+
+Or, with GreenSock(GSAP) or any other JavaScript animation library, the code becomes even more simple:
+
+```js
+Vue.directive('scroll', {
+  inserted: function (el, binding) {
+    let f = function (evt) {
+      if (binding.value(evt, el)) {
+        window.removeEventListener('scroll', f)
+      }
+    }
+    window.addEventListener('scroll', f)
+  }
+})
+
+// main app
+new Vue({
+  el: '#app',
+  methods: {
+    handleScroll: function (evt, el) {
+      if (window.scrollY > 50) {
+        TweenMax.to(el, 1.5, {
+          y: -10,
+          opacity: 1,
+          ease: Sine.easeOut
+        })
+      }
+      return window.scrollY > 100
+    }
+  }
+})
+```
+
+Though we would remove the previous CSS transition from this implementation because it's now handled with JavaScript.
+
+## The Benefit of Using Custom Directives
+
+Vue is rich with options for directives, most of which cover very common use-cases, which can create a very productive developer experience. But even if you have an edge case not covered by the framework, it's got you covered in this case as well, because you can quite easily create a custom directive to fit your needs.
+
+Attaching and removing scroll events to elements is a really good use case for this technique because just like other directives we use, they are necessarily tied to the element and otherwise, we'd have to find the reference for it in the DOM. This pattern avoids the need for traversal, and keeps the event logic paired with the node that it's in reference to.
+
+## Real-World Example: Using a Custom Scroll Directive for Cascading Animations
+
+In the course of creating a cohesive site, you may find that you're reusing the same type of animation logic in several areas. It seems simple, we would then create a very specific custom directive, right? Well, typically if you're reusing it, you will need to change it _just_ slightly for each use.
+
+To help keep our code concise and legible, we would want to pass in some predefined arguments such as the beginning point and ending of the animation as we scroll down the page.
+
+**This example is better viewed in the [full screen version](https://s.codepen.io/sdras/debug/078c19f5b3ed7f7d28584da450296cd0).**
+
+<p data-height="500" data-theme-id="5162" data-slug-hash="c8c55e3e0bba997350551dd747119100" data-default-tab="result" data-user="sdras" data-embed-version="2" data-pen-title="Scrolling Example- Using Custom Directives in Vue" class="codepen">See the Pen <a href="https://codepen.io/sdras/pen/c8c55e3e0bba997350551dd747119100/">Scrolling Example- Using Custom Directives in Vue</a> by Sarah Drasner (<a href="https://codepen.io/sdras">@sdras</a>) on <a href="https://codepen.io">CodePen</a>.</p>
+<script async src="https://static.codepen.io/assets/embed/ei.js"></script>
+
+In the demo above, each of the sections has two different types of animation triggered from the scroll: a morphing animation, and a drawing animation that animates the individual paths in the SVG. We reuse those two animations, so we can create a custom directive for each. The arguments we'll pass in will help keep everything simple and reusable.
+
+To show how we do this, we'll take a look at the morphing shape example, where we'll need to state the start and finish, as well as pass in a path value that we'll create a morph to. These arguments are each defined as `binding.value.foo`:
+
+```js
+Vue.directive('clipscroll', {
+  inserted: function (el, binding) {
+    let f = function (evt) {
+      var hasRun = false
+      if (!hasRun && window.scrollY > binding.value.start) {
+        hasRun = true
+        TweenMax.to(el, 2, {
+          morphSVG: binding.value.toPath,
+          ease: Sine.easeIn
+        })
+      }
+      if (window.scrollY > binding.value.end) {
+        window.removeEventListener('scroll', f)
+      }
+    }
+    window.addEventListener('scroll', f)
+  }
+})
+```
+
+We can then use this animation in our template, in this case we're attaching the directive to the `clipPath` element, and pass all of our arguments to the directives in an object.
+
+```html
+<clipPath id="clip-path">
+  <path
+    v-clipscroll="{ start: '50', end: '100', toPath: 'M0.39 0.34H15.99V22.44H0.39z' }"
+    id="poly-shapemorph"
+    d="M12.46 20.76L7.34 22.04 3.67 18.25 5.12 13.18 10.24 11.9 13.91 15.69 12.46 20.76z"
+  />
+</clipPath>
+```
+
+## Alternative Patterns
+
+Custom directives are extremely useful, but you may find some situations where you need something very specific that already exists in scrolling libraries that you don't wish to rebuild from scratch yourself.
+
+[Scrollmagic](http://scrollmagic.io/) has a very rich ecosystem of offerings to work with, as well as good documentation and demos to explore. This includes, but is not limited to things like [parallax](http://scrollmagic.io/examples/advanced/parallax_scrolling.html), [cascading pinning](http://scrollmagic.io/examples/expert/cascading_pins.html), [section wipes](http://scrollmagic.io/examples/basic/section_wipes_natural.html), and [responsive duration](http://scrollmagic.io/examples/basic/responsive_duration.html).
-Original file line number
+Diff line change
@@ Expand Up / @@ -25,4 +25,4 @@ @@
         "hexo-server": "^0.2.2",
         "request": "^2.83.0"
       }
-    }
+    }