Vue - The Good Parts: 文档

前言

文档，可以说是一件最容易做的事情，但是同时又是一件最难做好的一件事情。我们也总是在看各种文档，也在吐槽这个文档写的不好，那个写的不好，亦或者回过头来，吐槽我们自己的文档写的也不好。

Vue 能够这么火爆，其文档的贡献也是不可磨灭的。在开源领域，也有一个核心精神就是文档先行。那 Vue 就是这里的佼佼者，也是大家喜欢 Vue，Vue 受到这么多开发者喜欢的其中一个核心原因。

那 Vue 的文档是怎么设计的呢？包含哪些部分？对于我们自身的项目而言，如果也要写文档，我们可以从中借鉴些什么呢？

这里也抛出一个问题：Vue 的文档有这么多的部分，如果你是一个重度的 Vue 用户，是否你已经通读过 Vue 的文档，了解了 Vue 的方方面面？

正文分析

What

Vue 的文档放在 cn.vuejs.org/index.html 上的，当然如果英语好，可以访问英文版本 vuejs.org/index.html。

这里所列的就是首页，我们可以看到整个文档所包含的内容：

• 首页
• 学习
  • 文档
    • 教程
    • API
    • 风格指南
    • 示例
    • CookBook
  • 视频教程
• 生态系统
  • 帮助
    • 论坛
    • 聊天室
    • 聚会
  • 工具
    • Devtools
    • Vue CLI
    • Vue Loader
  • 核心插件
    • Vue Router
    • Vuex
    • Vue 服务端渲染
  • 信息
    • 周刊
    • Roadmap
    • 活动
    • Twitter
    • 博客
    • 工作
    • DEV 社区
• 团队
• 资源列表
• 支持 Vue
• 多语言
• 参与翻译

基本上包含了 Vue 相关的方方面面了。

How

那有了这些导航和概览的东西是不能说文档写的好的，只能说写的比较全，我们可以进一步挑一些部分进行分析：

• 首页
• 学习
  • 文档
    • 教程
    • API
    • 风格指南
    • 示例
    • Cookbook

首页

首页的重要性不言而喻，是属于第一印象，而且需要抓住用户，Vue 的首页的样子：

最核心的：

• logo（让别人记住你）
• slogan - 渐进式 JavaScript 框架（吸引人，想一探究竟）
• 指引
  • 为什么选择 Vue.js，视频的形式（整体介绍，0-1的印象，有入门理论，有实操项目）
  • 起步 - 快速上手（吸引到你之后，如果按照快速上手的步骤，符合用户预期，甚至超越预期）
  • 项目地址 GitHub（共建、star）
• 特性（权衡，最吸引人的地方）
  • 易用
  • 灵活
  • 高效
• 顶部整站导航

整体来看，核心就是做好第一印象，吸引用户，这里的重点也就是面向新用户，抓住他们。

教程

教程对于一个项目的重要性不言而喻，最重要的就是教会开发者入门且能够做复杂应用，以及帮助用户理解设计和一些细节，理论上学会了教程相关的内容，你应该是一名合格的 Vue 开发者了。

我们可以从 Vue 的教程来看：

• 基础
• 深入了解组件
• 过渡 & 动画
• 可复用性 & 组合
• 工具
• 规模化
• 内在
• 迁移
• 更多

从基础到更多的一些生态方面的涉及都包含在内了，很全面同时又比较容易认知，这是教程的核心。

接下来我们就以：基础、深入了解组件、过渡 & 动画 来详细分析分析他们。

基础部分

对于新手入门而言，基础部分则是十分重要的，这里最核心的就是把用户当成纯新用户，甚至是对前端都不怎么了解的用户，去一步步教会他们怎么实现功能，并且这些经验是在以后深入使用 Vue 也是一样有用的。

可以大概理解为：照葫芦画瓢，完成之后，惊呼：Amazing！而且，除此之外，Vue 教程每部分都有相关的视频搭配，更生动形象了！

现在看下教程中的核心中的核心，基础部分。

Vue 中将基础的部分划分为了以下几个部分：

• 安装
  • 各种安装方式，满足你的一切
• 介绍（快速上手）
  • 告诉你 Vue 是什么
  • 然后一步步N个示例告诉你 Vue 可以做什么
  • 以组件示例收尾
• Vue 实例
  • 一切开始的地方，Vue 应用实例
  • 仅做示例，同时详细配置项会给到 API 部分链接
  • Vue 组件也是实例，这是可继承性
  • 数据和方法
  • 生命周期钩子&图示（这个图太经典了，基本上所有 Vue 相关的文章 分享 都会遇到）
  • 每个部分都会有相关的链到 API 部分，以便于对整体的这部分内容做了解
• 模板语法
  • 讲明白背景，以及所做的事情，对于渲染函数的部分，则单独链接到单独的模块
  • 数据绑定：插值
  • 指令是啥，有啥作用
  • 缩写，确实很有用，基本上你看到的 Vue 项目都在采用缩写的方式，很简洁明白
• 计算属性和侦听器
  • 背景，要解决的场景，再告诉你解法
  • 一些对比和差异，明确界限，而不至于滥用或者造成理解上差异
• Class 与 Style 绑定
  • Vue 对这两个常用的绑定的增强处理，一切从需求或者场景出发
  • 具体写法的展示
• 条件渲染
  • v-if 相关的展示
  • 和 v-show 区别
  • 最佳实践不要和v-for使用等等
• 列表渲染
  • 数组、对象、值循环
  • 引申到数组的更新检测，核心原理链接到深入响应式原理（这块也是相当重要，所有响应式相关的基本都包含在其中了）
  • 一些细节case，链接到组件基础/DOM 模板细节（这里会被很多人忽略，Vue 中有很多细节其实都和 DOM 模板有关系）
• 事件处理
  • 交互的重要组成部分，事件处理
  • 事件的用法和相关修饰符用法（除了基础的，修饰符就是一个很多场景）
  • 可能的用户疑问的 直接解释
• 表单输入绑定
  • “双向绑定”必会出现的场景，也是前端日常出现的一个核心场景之一
  • v-model 和各种表单项结合的情况下分别是什么效果
  • 明确告知 且 引导去 组件也是可以使用 v-model 的
• 组件基础
  • 基本的示例，带你认识什么是组件
  • 组件最本质是为了复用，讲了注意事项/坑
  • 组件的组织-最终树状
  • prop 组件数据传递
  • 单个根元素的约定
  • 组件的事件（派发和监听）
  • 插槽基本使用，直观的感知，没有多余的
  • 动态组件 场景 使用
  • 解析 DOM 模板相关注意的点
  • 上边会涉及到 各种链接到深入组件的内容

可以看出，这里的基础部分的内容的最核心的东西：带你认识各个不同的概念和用法，不去深究（会有专门的篇幅去讲，以链接链过去），聚焦最核心的这个功能可能出现的情况以及相关的注意事项。

整个的模式大概为：

• 示例，直观感受，认识他们
• 各种子场景的举例，解释
• 可能遇到的坑，规则是如何的
• 会有一些图帮助你理解
• 每个小节都有对应的视频更形象地帮助你

基本上，即使你是一个前端小白，照着给你的展示的东西，也是可以大概理解基本的概念以及特性的。此时的你也不需要深入了解他们，只需要知道有这些东西，他们的用法大概是怎么样的，或者是解决什么场景的问题，将来的遇到的时候可以找到这部分教程。

而且还有一点细节的：

• 快速上手中的示例和基础部分的模块也基本上是大致对应上的
• 组件基础中的所涉及的需要深入了解的都链接到后边的【深入了解组件】中去了，却顺序也是基本保障的

深入了解组件

这里基本上是上一节【基础/组件基础】的延伸。组件是 Vue 中的核心设计之一，所以单独拿出来一个大大的篇幅来详细的介绍组件是十分有必要的。

一起来看下，Vue 关于这块是如何“深入浅出”的：

• 组件注册
  • 组件名字的各种情况，以及限制
  • 全局/局部注册，他们的语法、场景以及区别是啥
  • 模块系统和组件注册结合的场景去看，甚至是基础的组件的自动全局注册也包含在内了
• Prop
  • 大小写问题
  • 类型
  • 动态/静态 Prop 情况，也包含了直接传递一整个对象的写法
  • 单向数据流的思想，相对应的对于 Prop 的限制，不能修改
  • Prop 验证问题，组件友好的重要性
  • 非 Prop 的属性的处理，延伸到 inheritAttrs 配置项以及 $attrs 相关
• 自定义事件
  • 事件名的问题
  • 之前所涉及到的组件的 v-model 相关，同时也延伸到了 $listeners 相关
  • 原生事件的绑定问题 .natvie 修饰符以及同步 .sync 修饰符相关背景、介绍、使用
• 插槽
  • 定义，场景：内容分发，来源 Web Components 规范
  • 作用域、插槽默认内容
  • 具名插槽，场景以及注意事项
  • 作用域插槽，解决什么问题，以及相关注意点
  • 动态插槽名
  • 具名插槽的缩写
  • 其他的示例，插槽相关的一些更强大更灵活的使用
  • 相关废弃说明
• 动态组件 & 异步组件
  • 在动态组件上使用 keep-alive，从示例场景出发，以及链接到 keep-alive 的文档（这里的核心还是动态组件）
  • 异步组件，很好用的功能，涉及细节以及相关配置，基本上这种场景的方方面面都考虑到了
• 处理边界情况
  • 访问元素、组件
  • 事件侦听器相关
  • 组件循环引用
  • 模板定义的替代品
  • 控制更新相关

虽然是深入的部分，但是在讲述的时候也基本上遵从了前边在基础中所涉及的：示例啊、聚焦相关的模式。额外的点，所有的这些部分都顶部加了友情提示，你需要了解组件基础，防止因为对组件不了解所导致的问题（从标题上也可以看出，是属于深入的部分，有一定的成本在的）。

同时，你也注意到了，在 Vue 的很多地方都涉及到大小写、驼峰等相关的解释和规则，基本上所有的都源自于 DOM 模板解析所带来的。

过渡 & 动画

过渡 & 动画这块也是 Vue 的特性之一，功能还是非常强大的。

• 进入/离开 & 列表过渡
  • 概述，大概讲明白适用的场景和提供的功能，聚焦核心的进入、离开和列表的过渡
  • 单元素、组价的过渡
    • 各种demo的演示，CSS过渡控制、JS控制
    • 配合图片详细解析整个动画过程
  • 初始渲染的过渡特性支持
  • 多个元素的过渡，有啥场景和限制
  • 列表过渡，场景以及使用，以及FLIP动画的支持
  • 可复用的过渡，一些场景下，如果我们想复用，给到你示例，且最佳实践是使用函数式组件
  • 动态过渡，我们在很多场景中都是需要动态过渡的能力的，例如我们做统一的封装类似于端原生页切换的效果的时候，一个是正向的动画 一个是逆向的动画，就是利用了动态过渡
• 状态过渡
  • 主要是指的数据元素场景下的动效处理
  • 状态动画与侦听器，这里的核心就是利用 Vue 的响应式提供相关的能力可以很方便的做一些各种动效，一些示例的演示
  • 赋予设计以生命，最后的升华，给到了一个更为复杂的例子，强大的能力

在过渡和动画这里，详细展示了 Vue 中提供的很好用的特性，做过渡和动画的各种示例和演示，满足你的各个场景的需求。

---

到这里一些教程相关的我们挑选了部分做了一些大概的分析，你会发现他们的模式或者原则基本是一致的：

• 如果需要，给一个大概的概念解释；同时对于有依赖模块的知识的时候，给出醒目的提醒
• 都会有视频的支持，或者一些场景下给到图来帮助开发者理解，产出了很多经典的图
• 一个个的示例，由浅入深的带你了解当前模块的使用、一些注意事项、版本相关的信息
• 比较聚焦，不发散，和当前强相关的有一些解释，其他的更深入的内容，如果有必要是在单独的模块中详细描述
• 整体下来是比较全面的，基本涉及到了框架整体各个功能模块的介绍
• 会包含一些深入理解的模块，但是出发点是为了用户更好理解 Vue，用 Vue 更顺手，真正深入浅出教你学会使用 Vue
• 会有一些周边生态相关的介绍，根据你的场景去选择
• 提供良好的版本迁移指南，且有对应的工具相搭配

额外的，在其他模块里，同样在教程的范围之内，也包含了一些比较深入的内容，但是是为了帮助你更好的理解 Vue，更好的使用 Vue 的，例如内在模块所讲的【深入响应式原理】相关的内容，就是可以帮助你深入理解 Vue 的响应式相关原理，遇到问题的时候可以快速定位问题。也包含了在更多中会涉及【对比其他框架】，可以看到官方对于相关的一些框架是怎么对比的，有哪些思路去分析的。

API

API 是一个框架对外暴露的所有交互接口的集合，对于这部分而言，我们要做的不是简单的罗列，而是需要有一些规则的，我们就来看看 Vue 是怎么做的。

• 全局配置
• 全局 API
• 选项/数据
• 选项/DOM
• 选项/生命周期钩子
• 选项/资源
• 选项/组合
• 选项/其它
• 实例 property
• 实例方法/数据
• 实例方法/事件
• 实例方法/生命周期
• 指令
• 特殊 Attribute
• 内置的组件
• VNode接口
• 服务端渲染

一些我们可以分析出来的规则：

• 分类，子分类的去介绍，如选项整体以及实例整体，选项/数据这种分类和子分类，方便开发者记忆和聚合；这两个也基本上涵盖了 Vue API 的绝大部分
• 每个 API 都是讲清楚类型、参数、详情描述、默认值、返回值、用法、一些参考等相关信息
• 每个 API 如果有版本相关变更，需要明确
• 每个 API 不能使用的场景也会明确解释
• 每个 API 都需要一个简单明了的解释
• 一些常用的 API 是可以链接到教程去的

这样下来，你既可以了解整体 API 的全貌和分类，相对应的他们大概可以完成什么功能你也是了解的，方便你后续在实际使用中有记不起来的或者需要确认的可以很方便很快速的来到 API 这里进行定位。

风格指南

这个基本上是 Vue 最特有的一个部分，官方明确给出了作为 Vue 开发者应该遵从的一些风格指南。这是帮助开发者回避错误、小纠结和反模式的最好参考。这个也约等于是一份 Vue 的最佳实践，你也会发现，你在开发过程中如果遵从了这份风格指南的话，基本上不会出现啥问题。

这份风格指南对规则进行了四大类的划分：

并且给你了详细的解释，给到你建议和参考。

接下来就是每一部分详细的规则介绍，这里大概看下：

• 优先级A：必要的（规避错误）
  • 组件名为多个单词
  • 组件 data 必须是一个函数
  • Prop 定义要详尽（类型，默认值，是否必须，以及校验）
  • 为 v-for 设置键值，即声明 key
  • 避免 v-if 和 v-for 一起使用
  • 为组件样式设置作用域，但是布局类和APP以及组件库都不应该使用 scoped，业务场景可以选择
  • 私有 Property 名，命名 $_ 开头 甚至是直接利用闭包特性达到私有效果
• 优先级B：强烈推荐（增强可读性）
  • 组件文件，每个组件都应该在单个文件中
  • 单文件组件的名字，需要统一，要么是PascalCase要么是kebab-case
  • 基础组件名，例如 Base、App、V，适用于特定的样式和约定的基础组件
  • 单例组件名，只应该拥有单个活跃实例的组件应该以``` The` ``前缀命名，以示其唯一性
  • 紧密耦合的组件名，父子组件场景，例如 TodoList和TodoListItem 这样
  • 组件名中的单词顺序应该是一般描述的词开头，以描述性的修饰词结尾，例如 SearchButtonRun
  • 自闭和组件，但是不能用在 DOM 模板场景
  • 模板中的组件名大小写，推荐在单文件组件以及字符串模板的情况下，使用 PascalCase，而在 DOM 模板中则采用 kebab-case；或者在所有地方采用 kebab-case
  • JS(X)中的组件名大小写，应该一直使用 PascalCase
  • 完整单词的组件名
  • Prop 名的大小写，在声明 prop 的时候，其命名应该始终使用 camelCase，而在模板和 JSX 中应该始终使用 kebab-case
  • 多个 attribute 的元素，推荐每个 attribute 单独一行
  • 模板中简单的表达式，这个是可以的，但是复杂的建议使用计算属性或者方法
  • 简单的计算属性，复杂的计算属性应该拆分为多个简单的计算属性
  • 带引号的 attribute 值
  • 指令缩写，要么全用要么全不用
• 优先级C：推荐（将选择和认知成本最小化）
  • 选项顺序：
    • 副作用：el
    • 全局感知：name、parent
    • 组件类型：functional
    • 模板修改器：delimiters、comments
    • 模板依赖：components、directives、filters
    • 组合：extends、mixins
    • 接口：inheritAttrs、model、props、propsData
    • 本地状态：data、computed
    • 事件：watch、生命周期钩子们
    • 非响应式的：methods
    • 渲染：template、render、renderError
  • 元素 attribute 的顺序：
    • 定义：is
    • 列表渲染：v-for
    • 条件渲染：v-if 相关、v-show、v-cloak
    • 渲染方式：v-pre、v-once
    • 全局感知：id
    • 唯一的 attribute：ref、key
    • 双向绑定：v-model
    • 其他 attributes：所有绑定的或者未绑定的attribute
    • 事件：v-on
    • 内容：v-html、v-text
  • 选项中的空行
    • 当有多个 Prop 的时候，你可以增加空行来分类它们
    • 单文件组件的顶级元素顺序
      • 单文件组件应该总是让 <script>、<template> 和 <style> 标签的顺序保持一致。且 <style> 要放在最后，因为另外两个标签至少要有一个
• 优先级D：谨慎使用（有潜在危险
  • 没有在 v-if/v-else-if/v-else 中使用 key
  • scoped中的元素选择器
  • 隐性的父子组件通信，即不是通过 $parent 或者变更 prop（prop 是对象的情况下）
  • 全局状态管理，没有采用 Vuex 之类的状态管理，而是使用时间总线或者 $root

这个相当于是一个规范，一个最佳实践，如果大家都能遵守上述的约定，那么大家阅读代码或者CR的时候的成本就会降低很多。并且，还可以降低很多错误或者警告的发生。

示例

示例 example 是一个完整的展示，而不是像之前在教程中的一个个的小示例 demo 展示，本质上这里的示例，是一个mini的应用。

Vue 中大概包含了：Markdown 编辑器、GitHub提交、网格组件、树形视图、SVG图标、模式组件、具有伸缩性的 Header、内嵌组件、实时deepstreamHub、Firebase + 验证、ToDoMVC、HackerNews 克隆。

这里的每一个示例都基本上用到了 Vue 中不同功能，或者是不同的写法和组织方式，大部分大家都可以直接在官网上直接看到效果以及代码实现。十分的直观，而且你也可以按照自己的思路进一步修改，做属于你自己的示例。

Cookbook

首先意识到 Cookbook 和教程的区别，这个在文档中也有详细的描述：

那么 Cookbook 的目标是什么呢？

Vue 目前提供的这部分的内容是按照如下规则的：

这些在 Vue 中已经有了详尽的解释了，包含了动机、目标、规范。

Why

个人认为，最核心的一个点，作为一个开源项目，甚至是作为一个项目，如果你有用户，那么用户怎么样可以使用你的这个项目就十分重要了。口口相传肯定是不可以的，那就只能靠文档。而且文档还有一个好处，利于 SEO，进一步增强了生态。

文档先行或者要把文档写好，在开源领域中这是一个至关重要的点，夸张一点，有些情况下可能是决定了一个项目生死或者生命周期的重要指标之一。

公认的，大家都认为 Vue 的文档写得好，那么从原因视角来看，这个是 Vue 开源项目的核心，不可或缺的一部分。不仅仅要把代码写的好，文档要写的好，测试也要做好，开源协作要做好，等等。这是一个对项目负责、对开发者负责的核心态度，当然，付出就会有回报，相信也正是因为 Vue 文档的全面、简单易用，Vue 生态才变得更加繁荣了，两者也是密不可分的。

总结

我们基本上分析了 Vue 文档的部分核心模块的内容，包含了：

• 首页
• 教程
• API
• 风格指南
• 示例
• Cookbook

通过对他们的详细的一个分析，我们可以发现，Vue在整个的文档设计上，还是做了很好的抽象和分类的。既不会让开发者觉得文档很多，同时又感觉很有层次，各个模块部分负责的事情很清晰。

这里我们可以做一个大概的总结和思考，以便于后续我们在写文档的时候有所借鉴和学习：

整体大纲

• 首页
• 学习
• 生态
• 团队
• 资源
• 赞助、支持
• 多语言、翻译

这里核心中的核心就是首页、学习和生态了。而对于学习的部分，又进行了一个层次的拆解：

• 文档
  • 教程
  • API
  • 风格指南
  • 示例
  • Cookbook
• 视频教程
  • 各种视频教程的地方

对于我们而言，也是可以参考学习这种文档的大纲形式，根据我们的情况按需的去增删。

内容拆解

这部分，主要核心就是文档中五个部分的拆解：

• 教程

  • 一切从基础开始，聚焦当前demo的演示，注解
  • 假定开发者是0基础，需要解释或者引导的都需要给出
  • 复杂的部分，单拎出来模块详细讲解
  • 不管是哪部分，注意前后对应，给到开发者的认知是一致的
  • 不好理解的，可以借助于图片阐述

• API

  • 做好分类
  • 按照单个类别进行详细列表式阐述
  • API 的核心一定要保障输入输出的定义，描述以及版本信息

• 风格指南

  • 官方建议的代码风格，分等级的讲述，建议 Vue 开发者都应该遵从

• 示例

  • 完整的项目展示，要规划好他们所使用到的 Vue 功能的重点，肯定不是简单的一堆示例的堆叠
  • 最好是所见即所得，也可以尝试编辑看效果

• Cookbook

  • 按照更专注、更有深度、传授 JavsScript、探索生态系统的原则进行
  • 目标就是：
    • 解决一个具体的普遍性问题
    • 从尽可能简单的示例开始
    • 一次只介绍一个复杂的点
    • 链接到其它文档，而不是在这里重新解释概念
    • 把问题描述清楚，而不是假设大家对这个问题很熟悉
    • 解释过程，而不是只告诉你最终结果
    • 解释策略的利弊，包括它不适用于什么场景
    • 会提及相关的替代方案，但会放到一个单独的案例中细讲
  • 范式：
    • 基本示例
    • 一些细节的详细价值
    • 实际的例子
    • 额外的上下文
    • 何时避免这个模式
    • 替代方案
  • 这是一种知其然知其所以然的方式，比教程会更加深入

可以看出，针对于不同的模块，我们拆解的核心要关注的还是不一样的，但是也不能形成散乱，他们之间是相互关联的关系，当有相关的关联的时候，是给到链接彼此跳转的。最终形成的是一个具有整体划分，各个模块之间彼此结合，有一定层级关系的这样的一种拆解方式来阐述，供开发者学习、查阅。

其他

当然，这里并不是说其他的部分不重要，这个是根据项目情况去选择的，我们这里更多的是举例，通过这些大纲和拆解，可以帮助我们写一个更好的文档：

1. 意识：文档的重要性，不可或缺的价值，甚至比项目本身更为重要
2. 前提：开发者都是新手，相关依赖要描述清楚
3. 内容：整体性、有层次、模块划分清晰，模块内容本身聚焦、不发散
4. 语言：简单、准确、易于理解
5. 生态：给到描述和入口，解决你更多的问题
6. 团队：成员荣誉，也是影响力的体现