阅读 1216

读 VuePress(四)插件机制的设计

前言

从 9 月份开始,vuepress 源码进行了重新设计和拆分。先是开了个 next 分支,后来又合并到 master 分支,为即将发布的 1.x 版本做准备。

最主要的变化是:大部分的全局功能都被拆分成了插件的形式,以可插拔的方式来支撑 vuepress 的运作,这一点很像 webpack。

具体架构如下:

架构

从图中我们可以看出,vuepress 被划分成了两个部分:前端部分和服务端(Node.js)部分。

  1. 前端部分
  1. 服务端部分
  • 2.1 构建流程,这部分暴露出了 webpackwebpack-dev-servermarkdown-it动态模块的配置。
  • 2.2 用户文件,包括配置文件和 markdown 文件(文档),这些文件相当于站点的元数据。
  • 2.3 主题,这部分被划分为配置文件和布局组件。vuepress 提供了一份默认的主题。

在这个架构中,主题即插件。也就是说使用(开发)一个主题和使用(开发)一个插件的方式几乎一致。

  • 2.4 插件 API,这是今天我们重点介绍的部分,特别是插件机制的核心实现。

根据这个架构,vuepress 的插件便可以做很多事情了。具体用法可以参考文档

内部插件和官方插件

让我们先来了解一下 vuepress 的内部插件和官方插件都有些什么,借助插件机制做了哪些事情。

内部插件

  1. 全局增强:默认用来实现全局应用增强的逻辑。 它使用 enhanceAppFiles 指定增强全局应用和主题的文件路径。凭着这个,vuepress 就能准确地找到你全局增强或是主题的文件所在地。

  2. 布局组件:默认提供的布局组件。 它使用 clientDynamicModules 来实现动态引入布局相关的组件。

  3. 页面组件:默认提供的页面组件(布局组件的子组件)。 它使用 clientDynamicModules 来实现动态引入页面相关的组件。

  4. 根组件混入:默认往根组件混入的逻辑。 它使用 clientDynamicModules 来实现动态混入元信息。包括根组件的标题、语言等。

  5. 路由:默认的生成路由逻辑。 它使用 clientDynamicModules 来实现动态注册路由。我们的 markdown 文件在转换成 vue 组件后就是通过它自动注册到 vue-router 的。

  6. 站点数据:默认的生成站点数据逻辑。 它使用 clientDynamicModules 来实现生成全局站点数据。我们在页面里拿到的全局计算属性 $site 就是这样来的。

  7. 模块化转化:将 cmd 代码转成 esm 代码的逻辑。 还是用 clientDynamicModules 来实现将 cmd 代码转成 esm 代码。主要是因为 ClientComputedMixin 这个类前后端代码都要使用。

  8. 样式增强 全局样式增强。使用 enhanceAppFiles 和 ready 钩子来实现(主题样式+用户样式+父主题样式)。

  9. 样式覆盖 全局样式覆盖,使用 ready 钩子来实现,覆盖 config.styl 和父主题的 palette。

  10. dataBlock数据注入 解析 blockType=data 的数据,使用 chainWebpack 和 enhanceAppFiles 来实现,对 blockType=data 类型的数据注入到 markdown 生成的 vue 组件里去,每个组件可以访问自己的 $dataBlock 属性拿到。

官方插件

  1. 活动的标题链接 它会在用户滚动页面时自动转变侧边栏的高亮标题。 它使用了 clientRootMixin 和 define 往根组件混入了滚动逻辑:监听 onScroll 事件,获取所有锚点元素并根据滚动距离计算出高亮的锚点。

  2. 回到顶部 使用了 enhanceAppFiles 和 globalUIComponents 注册了一个全局组件:点击后可以滚动到页面顶部。

  3. 博客

    • 3.1 使用 extendPageData 创建标签页和目录页
    • 3.2 使用 ready、clientDynamicModules、enhanceAppFile 创建页面元数据。
  4. ga 谷歌分析站点的库。使用了 define 和 enhanceAppFiles 初始化了 ga。

  5. 国际化(废弃) 可以让你的站点拥有切换语言的能力。使用了 enhanceAppFiles 和 additionalPages 注册了个 I18n 布局组件。

  6. 文档的最近更新时间 可以让每个文档页下面显示最近的 git 提交时间。使用 extendPageData 拓展了 $page 的 lastUpdated 属性。

  7. 图片预览 集成了 medium-zoom。使用了 define、clientRootMixin 往根组件里混入了 zoom 的初始化和更新逻辑。

  8. 分页 让共享侧边菜单栏的文档拥有分页切换的能力。使用了 enhanceAppFiles 定义了所有页面的索引和顺序。ready 定义了分页的规则如排序规则等、clientDynamicModules 生成动态模块给前端代码使用。

  9. pwa 集成 service-worker 功能 - 9.1. 使用 ready 开启 serviceWorker 选项 - 9.2. 使用 alias 实现用 vue 当事件通道 - 9.3. 使用 define、globalUIComponents 注册更新 PWA 应用按钮组件 - 9.4. 使用 enhanceAppFiles 注入 register-service-worker 的初始化和更新逻辑 - 9.5. 使用 generated 通过 workbox-build 完成 sw 功能

  10. 注册全局 Vue 组件 使用 enhanceAppFiles 把一个文件夹中的 vue 组件文件都注册好。

  11. 搜索框 使用 alias 和 define 让搜索框可以动态引入。

  12. 进度条 使用 clientRootMixin 和 enhanceAppFiles 集成 nprogress。

lerna

项目管理上,插件机制也使得原来的一个大项目拆成了 1 + N 的形式,package.json 也变得多了起来,为了管理这种项目,vuepress 引入了 lerna。

关于 lerna 的知识,有兴趣的读者可以参考:lerna管理前端packages的最佳实践

核心实现

当一系列插件要使用时,需要通过 PluginAPI 和组成它的各种 Option 来实现。

整体流程大致如下:

这里我划分成了两个阶段,用虚线分隔,一个是调用前阶段,一个是调用后阶段。插件们被调用前,是会被载入以及注册的,之后化整为零,映射成若干个 Option 实例。

源码

  1. PluginAPI 类,这部分代码包含了插件机制中的注册调用实现。
    • 构造(constructor):初始化选项、插件上下文、插件队列(可注册插件列表)、日志插件、初始化标志位、插件解析器属性,然后把选项们都装载进来(initializeOptions)。这里会把一个插件映射成若干个 Option 实例。 例如,一个插件只有 ready、chainWebpack、additionalPages 三个选项,则会得到三个 Option 实例。
    • 使用(use),需要 _initialized 标志为 false 才能调用,用于确认哪些插件是可以被注册的:
      • 对于非对象类型的插件,会调用 normalizePlugin 方法将之转成对象
        • 期间会调用 _pluginResolver(ModuleResolver 实例) 来解析模块
          • 用于解析模块的 ModuleResolver 类,工作原理类似 webpack 的模块解析。源码
          • 这里值得一提的是 resolve 方法,它支持从非字符串包、npm 包、绝对路径、相对路径中解析模块。
          • 相对路径的模块先使用 node 的原生 path.resolve 方法解析得到绝对路径,然后交给解析绝对路径模块的方法处理。
          • 绝对路径、非字符串包和 npm 包会用通用模块 CommonModule 表示。
          • 通用模块有四个属性:entry、shortcut、name、fromDep。
        • 还会调用 flattenPlugin 拍平插件,主要是获取配置。
          • 如果传入配置是函数,则返回调用后的结果,入参为插件选项、插件上下文、PluginAPI 实例。
          • 传入的配置是对象,则返回一个拷贝后的对象。
      • 非 multiple 的插件,会根据插件名字去重。
      • 标准化后的插件,会加入到插件队列中去。
      • 最后,存在插件中使用插件的情况时,会调用 useByPluginsConfig 来实现。
        • 这里面的 normalizePluginsConfig 会将配置格式化成[[p1]、[p2]的形式]。
    • 初始化(initialize):先将 _initialized 标志位置为 true,然后注册所有可用的插件。
      • 在初始化之前,内部插件的使用,会先于用户的插件。
      • 注册(applyPlugin):到这里,插件已经被拆分成细化的选项,按照信息类(pluginName、shortcut)、钩子类(ready、compiled 等)、其他类(chainWebpack、chainMarkdown、enhanceAppFiles 等)按顺序链式注册(registerOption)。
        此时,一个 Option 实例中已经承载了若干个插件的逻辑了。
    • enabledPlugins 和 disabledPlugins 两个只读属性可以取启用(可注册)或禁用(不可注册)的插件列表。
    • getOption 可以取具体的一个选项实例,applyAsyncOption 和 applySyncOption 分别应用异步选项和同步选项中的逻辑(回调函数)。

选项和异步选项,插件的本体

  1. Option 类 - 每个实例初始化 key(选项标识) 和 items(这个选项所对应的函数们) 属性。

    • 重要方法:syncApply(也叫 apply),对之前保存在实例中的 items 遍历调用 add 方法,如果 item 中的值是函数,则执行之取其返回值。
    • 在插件应用选项时如果匹配成功,会调用 add 方法将选项映射成 1-n 个对象推入 items 属性里。
    • 除了 add 还有 delete 和 clear 方法,不做赘述。(增删清)
    • 另外有 values、entries 和 appliedValues 三个只读属性,用于获取值、实体、已应用的值。
    • 管道方法(pipeline),它将实例的 values 属性柯里化成一个组合函数,依次执行。
  2. AsyncOption 类

    • asyncApply 异步版syncApply,调用函数的时候使用了 await。
    • parallelApply 如果说 pipeline 是串行,它就是并行:使用了 Promise.all
    • pipeline 同理,调用函数的时候使用了 await。

特殊选项

  1. EnhanceAppFilesOption、ClientDynamicModulesOption、GlobalUIComponentsOption、DefineOption、AliasOption 类
    • AliasOption
      • 在创建 webpack 配置的时候调用
      • 重写 apply 方法:先调用 syncApply,然后将 appliedValues 取出,设置为 webpack 的 alias
    • ClientDynamicModulesOption
      • 在 prepare 阶段调用
      • 重写 apply 方法:从 appliedItems 取出应用的插件信息,遍历写入文件以待使用
    • DefineOption
      • 类似 AliasOption,只不过是设置 webpack 的全局变量
      • 最后在 injections 插件(DefinePlugin)触发时收集选项将 define 注入进去
    • EnhanceAppFilesOption
      • 在 prepare 阶段调用
      • 重写 apply 方法:从 appliedItems 取出插件信息,生成引入模块或者注册组件的代码文件
    • GlobalUIComponentsOption
      • 类似 ClientDynamicModulesOption,写全局 ui 组件文件

调用函数型 Option 时机

  1. extendCli 创建 cli 命令时
  2. chainMarkdown 和 extendMarkdown 创建 MarkdownIt 实例时
  3. additionalPages 解析完所有页面后 3、extendPageData additionalPages 执行完之后,依赖 additionalPages 执行完的结果
  4. ready 紧跟 additionalPages 之后
  5. clientDynamicModules、enhanceAppFiles、globalUIComponents 紧跟 ready 之后
  6. define、alias
    创建公共 webpack 配置后
  7. chainWebpack
    创建 dev webpack 配置后、创建 build webpack 配置后
  8. beforeDevServer
    webpack-dev-server 的 before 选项执行后
  9. afterDevServer webpack-dev-server 的 after 选项执行后
  10. generated build 完成后
  11. updated 文件更新后
  12. clientRootMixin
    clientDynamicModules 选项执行时

编写一个 vuepress 插件

我也写了一个小插件,它可以将你的 vuepress 站点下载成一个 pdf 文件:vuepress-plugin-export-site

源码

  1. 使用 ready 选项
  2. 借助 puppeteer 和 easy-pdf-merge 实现:从上下文中拿到路由信息,然后使用 puppeteer 遍历访问并下载,最后合并成一个大 PDF。
    • 因为需要下载 chromium,所以国内网络受限。我们换成了 puppeteer-cn。
    • easy-pdf-merge 如果在 windows 下运行需要指定 jar 环境变量。

后记

我们熟悉的 webpack、vue 也有插件系统,它们都有两个共同的特点:

  1. 提供一个功能扩展点,让插件能够去扩展它。
  2. 提供一个功能注册功能,让插件注册进来。

其实插件机制也可以看做设计模式的一种体现:抽离出变化的部分,保留不变的部分。这些变化的部分,便可以称之为插件。

在我们造轮子的时候,如果轮子的功能越来越多,代码越来越臃肿的话,引入插件机制会让后续的开发更加灵活。

最后,帮插件机制的开发者真山同学宣传一下,届时会有更加精彩的 vuepress 分享: