简介

菜谱与指南

菜谱与指南有何不同？为什么需要这样做？

• 更强的重点：在指南中，我们本质上是在讲故事。每个部分都建立在之前部分的基础上，并假设对之前部分的知识。在菜谱中，每个食谱可以并且应该独立存在。这意味着食谱可以专注于 Vue 的一个特定方面，而不是必须提供一个总体概述。

• 更深的深度：为了避免使指南过于冗长，我们尝试只包含最简单的示例来帮助您理解每个功能。然后我们继续。在菜谱中，我们可以包含更复杂的示例，以有趣的方式组合功能。每个食谱也可以根据需要尽可能长和详细，以便充分探索其利基。

• 教授 JavaScript：在指南中，我们假设至少对 ES5 JavaScript 有中级熟悉程度。例如，我们不会解释 Array.prototype.filter 如何在过滤列表的计算属性中工作。然而，在菜谱中，可以探索和解释基本的 JavaScript 功能（包括 ES6/2015+），说明它们如何帮助我们构建更好的 Vue 应用程序。

• 探索生态系统：对于高级功能，我们假设具有一些生态系统知识。例如，如果您想在 Webpack 中使用单文件组件，我们不会解释如何配置 Webpack 配置的非 Vue 部分。在菜谱中，我们有空间更深入地探索这些生态系统库 - 至少在对 Vue 开发人员普遍有用的范围内。

请注意，尽管存在所有这些差异，菜谱仍然不是一个循序渐进的手册。对于其大部分内容，您应该对 HTML、CSS、JavaScript、npm/yarn 等概念有基本了解。

菜谱贡献

我们正在寻找什么

菜谱为开发人员提供了可供参考的示例，这些示例既涵盖了常见或有趣的用例，也逐步解释了更复杂的细节。我们的目标是超越简单的入门示例，展示更广泛适用的概念，以及一些方法的注意事项。

如果您有兴趣贡献，请通过在标签为菜谱想法下提交问题来启动协作，以便我们能够帮助您引导您完成成功的拉取请求。在您的想法获得批准后，请尽可能遵循以下模板。某些部分是必需的，而另一些部分是可选的。强烈建议按照数字顺序进行，但不是必需的。

食谱通常应该

• 解决一个特定的、常见的问题
• 从最简单的示例开始
• 一次引入一个复杂性
• 链接到其他文档，而不是重新解释概念
• 描述问题，而不是假设熟悉
• 解释过程，而不仅仅是最终结果
• 解释您的策略的优缺点，包括何时适用和不适用
• 如果相关，请提及替代解决方案，但将深入探讨留给单独的食谱

我们要求您遵循以下模板。但是，我们理解，有时您可能需要为了清晰度或流程而偏离。无论哪种方式，所有食谱都应该在某个时候讨论使用此模式所做选择的细微差别，最好以替代模式部分的形式。

基本示例

必需

1. 用一两句话阐明问题。
2. 用一两句话解释最简单的解决方案。
3. 显示一个小的代码示例。
4. 用一句话解释这实现了什么。

关于值的详细信息

必需

1. 解决人们在查看示例时可能遇到的常见问题。（引用块非常适合这种情况）
2. 显示常见失误的示例以及如何避免它们。
3. 显示良好和不良模式的非常简单的代码示例。
4. 讨论为什么这可能是一个引人注目的模式。参考链接不是必需的，但鼓励使用。

现实世界示例

必需

演示为常见或有趣的用例提供支持的代码，方法是

1. 逐步介绍一些简短的设置示例，或
2. 嵌入一个 codepen/jsfiddle 示例

如果您选择后者，您仍然应该讨论它是什么以及它做什么。

附加上下文

可选

写一些关于这种模式的信息非常有帮助，它还将在哪里适用，为什么它能很好地工作，并在您这样做时逐步介绍一些代码，或者在这里为人们提供进一步的阅读材料。

何时避免这种模式

可选

本节不是必需的，但强烈推荐。对于像根据状态更改切换类这样的非常简单的事情，写它没有意义，但对于像 mixin 这样的更高级模式，它至关重要。关于开发的大多数问题的答案是 “取决于！”，本节接受了这一点。在这里，我们将诚实地看看模式何时有用以及何时应该避免，或者何时其他方法更有意义。

替代模式

必需

当您提供了上面关于避免的章节时，本节是必需的。探索其他方法很重要，这样告诉人们某些东西在某些情况下是反模式的人不会想知道。在这样做时，请考虑网络是一个大帐篷，许多人有不同的代码库结构，并且正在解决不同的目标。应用程序是大型还是小型？他们是在将 Vue 集成到现有项目中，还是从头开始构建？他们的用户只是试图实现一个目标还是多个目标？是否有大量异步数据？所有这些问题都会影响替代实现。一个好的菜谱食谱会为开发人员提供这种上下文。

谢谢

为文档做出贡献需要时间，如果您花时间向我们文档的这一部分提交 PR，我们将不胜感激。