当前位置：首页 > Web前端 > vue.js

使用VuePress搭建Element的组件库文档官网

时间：2023-04-01 10:38:50 vue.js

本教程有视频版，看B站《VuePress搭建Element组件库文档》为什么要用VuePress？社区中有很多优秀的文档工具供我们前端程序员选择，比如Gitbook、Hexo、Docusaurus。对于个人使用，我体验过的最好的文档工具是Docusaurus。Docusaurus具有配置简单、目录结构合理、Markdown渲染配置灵活等一系列优点。但对Vue开发者不太友好的是，Docusaurus是基于React的。如果你想在里面使用Vue，渲染Vue组件，就会变得非常困难。所以如果你是Vue开发者，在编写Vue相关的组件文档时，我个人推荐使用官方的VuePress。下面的教程将使用VuePress生成一个类似Element的组件文档库，包括Vue组件展示、示例代码展示、自定义主题等常用功能。安装并创建项目vuepress-element-docmkdirvuepress-element-doc&&cdvuepress-element-doc初始化npm包管理并在package.json中添加脚本npminit-y//package.json"scripts":{"dev":"vuepressdevdocs","build":"vuepressbuilddocs"},installVuePress+Elementnpminstallvuepresselement-ui--registry=https://registry.npm.taobao.org因为我们要做的是Element组件文档页面，所以这里顺便安装Element。如果需要显示自己的组件库，可以安装或导入自己的组件库的js和css。创建主页新建主页.md文件新建docs/README.md---home:trueheroImage:https://artice-code-1258339218.cos.ap-beijing.myqcloud.com/vuepress/element-index.pngheroText:Elementfeatures:-title:ConsistencyConsistencydetails:Consistentwithreallife:符合现实生活的流程和逻辑，遵循用户习惯的语言和概念-title:Feedback反馈详情：通过界面风格和交互动态，用户可以清晰感知自己的操作-title:Efficiency效率详情：界面简洁明了，让用户快速识别而不是回忆，减轻用户的记忆负担。footer:by饿了么---###设计原则一致性

一致性

反馈

反馈

efficiency

效率

可控

Controllability

这个README.md中有三种语法：YAML:顶端以---Wrapped是YAML语法的FrontMatter，必须位于.md的最前面，可选Markdown：其中###设计原则部分就是Markdown语法，相信大家都不陌生with.html:最后是我们熟悉的HTML语法，众所周知，HTML语法可以在.md中使用。注意：docs/README.md中的图片地址是OSS上的地址，因为这样更方便你使用se。当然你也可以使用对于本地公共文件，详见Vuepress/StaticResources/PublicFiles。创建配置文件并新建docs/.vuepress/config.js，填写基本配置信息。注意这个文件是VuePress的核心文件，有丰富的配置项。module.exports={theme:'',title:'VuePress+Element',description:'VuePress构建Element的组件库文档教程示例代码',base:'/',port:'8080',themeConfig:{},head:[],plugins:[],markdown:{}}启动项目使用命令运行VuePress查看效果npmrundevbrowser访问localhost:8080，如果没有意外，相信你已经可以看到了页面上如下可以了，这个页面是我们在README.md文件中写的YAML+Markdown+HTML的整体效果。创建组件页面创建新组件页面的.md文件/docs/comps/README.md，并填写内容。这里模仿的是Element官网的安装页面。#安装##npm安装推荐使用npm安装，配合webpack打包工具使用效果更好。npmielement-ui-S##CDN目前可以通过unpkg.com/element-ui获取最新版资源，在页面导入js和css文件即可开始使用。创建/docs/comps/select.md并填写内容。创建两个文件方便我们后面设置文档侧边栏，这里是Element官网的selector组件页面。＃选择选项太多时选择器，请使用下拉菜单以显示和选择内容。##基本用法适用于广泛的基础单选配置顶部导航栏在/docs/.vuepress/config.js中配置顶部导航栏的配置字段themeConfig.nav。代码如下：module.exports={theme:'',title:'VuePress+Element',description:'VuePress构建Element组件库文档教程示例代码',base:'/',port:'8080',themeConfig:{//新代码nav:[//配置顶部导航栏{text:'Home',link:'/'},{text:'Component',link:'/comps/'}]},head:[],plugins:[],markdown:{}}在/docs/.vuepress/config.js中配置组件页面文档的侧边栏配置顶部导航栏的配置字段themeConfig.sidebar。代码如下：module.exports={theme:'',title:'VuePress+Element',description:'VuePress构建Element组件库文档教程示例代码',base:'/',port:'8080',themeConfig:{nav:[{text:'Homepage',link:'/'},{text:'Component',link:'/comps/'}],sidebar:{//配置侧边栏部分'/comps/':['/comps/','/comps/select.md']}},head:[],plugins:[],markdown:{}}在这一点上我相信你会看到这样的东西你的浏览器页面不见了，是不是有点Element文档的味道？组件显示效果的实现不过到目前为止，我们还没有介绍Element的组件部分。既然是组件库，我们自然希望能像Element一样实现组件的展示，下面是示例代码。这部分，我们来看看如何实现这个效果。安装演示插件。这里我们将使用vuepress-plugin-demo-container插件。使用以下命令安装npminstallvuepress-plugin-demo-container然后在/docs/中。在vuepress/config.js文件中配置插件module.exports={//...plugins:['demo-container'],//配置插件markdown:{}}知道enhanceApp.js的你有没有想过我们通常在项目中使用Element时，需要在app.js中引入Element，调用Vue.use(Element)才能在Vue中使用Element组件。如果我们要在VuePress中使用Element，我们需要在哪里写这段代码呢？此时我们需要知道一个新的文件enhanceApp.js，它是VuePress中仅次于config.js的第二重要的文件。当你想做一些Vue应用级别的配置时，你需要在这个文件中进行配置。让我们在这里创建这个文件：/docs/.vuepress/enhanceApp.js。从'element-ui'导入ElementUI；导入'element-ui/lib/theme-chalk/index.css'；导出默认异步({Vue})=>{if(typeofprocess==='undefined'){Vue.use(ElementUI)}}导入Element组件接下来，让我们尝试在我们刚刚创建的/docs/comps/select.md中使用Element。用以下内容替换原来的内容。＃选择选项太多时选择器，请使用下拉菜单以显示和选择内容。##Basicusage适用于广泛的基本radio:::demo适用于广泛的基本radio\```html（注意：需要去掉前面的'\'!!!）\```（注意：需要去掉前面的'\'！！！）:::如果一切顺利，相信此时你应该可以看到如下效果：VuePress的部署目前未知，组件库的基础框架已经搭建完成，剩下的就是填写内容了，最后部署。现在让我们谈谈部署部分。执行部署命令还记得我们之前在package.json中配置了VuePress部署脚本的“build”：“vuepressbuilddocs”吗？所以我们只需要执行下面的命令用npmrunbuild查看文件，你会发现此时多了一个文件/docs/.vuepress/dist，dist目录就是我们最终的部署目录。├──文档│├──.vuepress││├──config.js││├──dist│││├──404.html│││├──资产││││├──css│││││└──0.styles.262ade0c.css││││├──字体│││││├──element-icons.535877f5.woff│││││└de.──3element39.──3element-iconsttf││││├──img│││││└──search.83621669.svg││││└──js││││├──2.ae254118││3js││.c4b624da.js││││├──4.8c48097d.js││││├──5.a4fed9a4.js│││├──6.efea7d5a.js─││e17.│4│js││││├──8.8ee7961b.js││││├──9.e8d922fc.js││││└──app.90733c82.js││││├──comps│index.html││││└──select.html│││└──index.html││└──enhanceApp.js│├──README.md│└──comps│├──README.md│└──select.md├──package-lock.json└──package.json使用WebServer部署，只需将根目录指向/docs/.vuepress/dist/即可部署到服务中，这里我们使用本地的MAMPApache作为WebServer，当然你也可以使用nginx什么的你想部署到你最喜欢的服务器。此时输入WebServer配置的端口名，可以看到已经部署成功。

上一篇：AntDesignVue中的a-upload组件通过axios实现了文件列表上传和更新echo的前后端处理方案

下一篇：【译文】游雨溪：Ref语法糖提案

使用VuePress搭建Element的组件库文档官网相关文章

最新推荐

猜你喜欢