VuePress 编写组件库文档踩坑记录

前言

近期在造一个 vue 的组件库(这也有不少故事可以讲…),造完轮子后需要编写组件文档,选了 vuepress,在文档中需要代码演示,自然就需要引入组件库,引入组件库后编写文档正常使用没有问题,但是在 build 的时候就出麻烦了…

问题

  • 问题一

    ReferenceError: document is not defined

    出现这个问题的原因是我在编写 vue 组件的时候,在.vue文件中引入了样式文件,就是下面这个样子:

    <style lang="less">
      @import '../style/content.less';
    </style>
    

    这个大家应该很熟悉了,正常的引入样式,但是问题是组件库代码编译过后,会用到 document.querySelectory() 来进行样式处理,而 vuepress 所有的页面在生成静态 HTML 时都需要通过 Node.js 服务端渲染, Node.js 环境中自然没有 document 对象,这时候访问浏览器/DOM 中的 API 自然会报错。

    本地开发没有问题,但是 build 就会出错

  • 问题二

    window is not defined

    出现这个问题同样是因为在编写组件时用到了 window 对象,而 Node.js 中没有 window 对象。

解决

  • 第一回合

    vuepress 官方给出解决办法,就是利用 vue 的动态组件,

    <template>
      <component v-if="dynamicComponent" :is="dynamicComponent"></component>
    </template>
    <script>
    export default {
      data() {
        return {
          dynamicComponent: null
        }
      },
      mounted () {
        import('./lib-that-access-window-on-import').then(module => {
          this.dynamicComponent = module.default
        })
      }
    }
    </script>
    

    具体查看浏览器的 API 访问限制

    这种方式固然能解决问题,但是很麻烦,想想我要编写十几个组件文档,写 demo 的时候每次都要这样处理,要是遇到复杂的示例,一个 demo 里面用到了好几个组件,那岂不是麻烦得很,不够优雅,不够优雅。

    而且编写文档的时候,组件库完全可以在enhanceApp.js中一次性完整引入,不需要按需引入,比如:

    import Element from 'element-ui'
    export default ({ Vue, options, router, siteData }) => {
        Vue.use(Element);
    };
    
  • 第二回合

    其实上面第一种解决办法已经给我们提供了思路,在 beforeMountmounted 再去访问访问浏览器 / DOM 的 API。

    但是按照我们的需求,这时候不能再去 demo 组件中的 mounted 单独处理这个问题了,那我们目光又回到 enhanceApp.js,组件库的引入可以放到这里,在这里使用 mixin 来处理。

    因为是 Node.js 服务端渲染,第一想到了用 require:

    import Element from 'element-ui'
    export default ({ Vue, options, router, siteData }) => {
        Vue.use(Element);
        Vue.mixin({
            mounted() {
                var WisdomUI = require('wisdom-ui')
                Vue.use(WisdomUI)
            },
        })
    };
    
    • build 通过
    • 本地运行,组件加载失败

    头大,应该用 ES module:

    import Element from 'element-ui'
    export default ({ Vue, options, router, siteData }) => {
       Vue.use(Element);
       Vue.mixin({
           mounted() {
               import('wisdom-ui').then(function (m) {
                   Vue.use(m.default)
               })
           },
       })
    };
    
    • 本地运行没有问题
    • build 正常

    问题解决。

这里为什么不能用 require 来加载组件库,可以看看这里

https://juejin.im/post/5ec4e888f265da7716002a85

「点点赞赏,手留余香」

    还没有人赞赏,快来当第一个赞赏的人吧!
0 条回复 A 作者 M 管理员
    所有的伟大,都源于一个勇敢的开始!
欢迎您,新朋友,感谢参与互动!欢迎您 {{author}},您在本站有{{commentsCount}}条评论