介绍

Cookbook vs 指南

这份 cookbook 和指南的不同之处在哪里？存在的意义是什么？

• 更专注：在指南里，我们实际上是在讲一个故事。每个章节都以之前章节的知识进行构建和假设。而在 cookbook 里，每个案例都有各自的代表性。也就是说每个案例都专注于 Vue 的某个特定方面，而不是一个概览。

• 更有深度：为了避免指南写得太长，我们试着只包含了尽可能简单的示例来帮助你理解每个功能，然后就奔下一个话题了。在 cookbook 里，我们以更生动的形式包含了更复杂的示例并结合特性。每个案例都可以尽可能的翔实，以彻底探索这个领域。

• 传授 JavaScript：在指南里，我们假设你至少具有 ES5 JavaScript 的中级水平。例如，我们不会解释 Array.prototype.filter 在计算属性中是如何过滤一个列表的。然而在 cookbook 里，我们将对一些必要的 JavaScript 特性 (包括 ES6/2015+) 进行探索和解释，以帮助我们构建更好的 Vue 应用。

• 探索生态系统：对于高级特性，我们会假设你已经对生态系统有一定了解。例如，如果你想在 webpack 中使用单文件组件，我们不会解释如何在 webpack 中配置 Vue 以外的部分。在 cookbook 里，我们有空间去更深度探索这些生态系统中的库——至少能到对 Vue 开发者普遍使用的程度。

除了这些不同，请注意这份 cookbook 仍不是入门教程。其大部分内容都假设你已经理解 HTML、CSS、JavaScript、npm/yarn 等基本概念。

参与 Cookbook 贡献

我们的目标

Cookbook 为开发者提供了一些示例，涵盖常见的或有趣的用例，并逐步解释更复杂的细节。我们的目标是超越一个简单的示例介绍，展现更广泛适用的概念及其注意事项。

如果你有兴趣参与贡献，请将您的想法填入 issue 并加上 cookbook idea 的标签作为起步，这样我们就可以帮助并引导您完成一个 pull request。在你的想法被认同之后，请尽可能遵循以下模板。有些小节是必须的，有些是可选的。我们强烈建议您遵循其顺序，但这也不是必须的。通常情况下案例应该：

• 解决一个具体的普遍性问题
• 从尽可能简单的示例开始
• 一次只介绍一个复杂的点
• 链接到其它文档，而不是在这里重新解释概念
• 把问题描述清楚，而不是假设大家对这个问题很熟悉
• 解释过程，而不是只告诉你最终结果
• 解释策略的利弊，包括它不适用于什么场景
• 会提及相关的替代方案，但会放到一个单独的案例中细讲

我们需要您遵照下面的模板。当然我们也理解有的时候为了使内容更清晰或顺畅你是有必要做一些调整的。另外不论怎样，所有的案例都应该从某些点上讨论选择使用这个模式的细微差别，且我们倾向于它们以替代方案章节的形式出现。

基本的示例

必须的

• 用一两句话来说明问题。
• 用一两句话解释最简单的可能的解决方案。
• 显示一小段代码示例。
• 用一句话解释它完成了什么。

关于其价值的细节

必须的

• 解决人们在看例子时可能遇到的常见问题。(最好以块引用格式呈现)
• 显示常见错误的例子，以及如何避免它们。
• 用非常简单的代码示例展示好模式和坏模式。
• 讨论这个模式令人信服的理由。参考链接不是必需的，但鼓励提供。

实际的例子

必须的

通过以下方式演示能够为常见或有趣的用例提供支持的代码：

• 通过几个简单的设置例子，或者
• 嵌入一个 CodePen / JSFiddle 的例子如果你选择稍后再提供，那么你仍应该表述它是什么和做什么。

额外的上下文

可选的

为这个模式写点东西，描述在这个模式下，它会应用到什么地方，为什么它能正常工作；以及在此基础上运行一些代码、提供一些延伸阅读材料，都是非常有帮助的。

何时避免这个模式

可选的

本节不是必需的，但强烈建议。你没有必要写一些特别简单易懂的事项，比如根据状态的改变开关 class，但是对于 mixin 这样的更高阶的模式来说是非常重要的。大多数高阶的问题的答案都是“要看情况！”，该部分就包含了这一点。在此，我们要诚实地看待模式何时有用，何时应该避免，什么时候更有意义。

替代方案

可选的，除非这部分内容在之前已经提供过了

如果你已经在上一节提供了避免使用的条件，那么这一节是必须的。探索其它方法非常重要，这样人们在遇到某些反模式的情形时不至于无所适从。这样做是因为考虑到 web 是一个不同人有着不同代码结构解决不同问题的大舞台。这个应用是大是小？它们要把 Vue 集成到一个现成的项目中还是从零起步构建新项目？它们的用户只是想达成一个目标还是多个？有很多异步数据吗？所有的这些担忧都会影响实现替代品。一篇好的 cookbook 会为开发者提供这些相关信息。

致谢

文档贡献是需要很多时间的，如果您花时间提交这部分的文档，我们将感激不尽。