使用vue styleguidist编写组件文档

最新推荐文章于 2024-11-13 13:19:56 发布

「已注销」

最新推荐文章于 2024-11-13 13:19:56 发布

阅读量1.3k

点赞数 1

分类专栏：前端工程化

本文为博主[pan-zy]原创文章，未经博主允许不得转载。

本文链接：https://blog.youkuaiyun.com/sd4015700/article/details/118634148

版权

本文档介绍了如何使用 Vue Styleguidist 编写组件文档，包括安装配置、基本配置如npm安装、命令添加、配置组件加载等。详细讲解了如何编写文档，如修改组件显示名、标注组件属性、自定义事件和插槽注释，以及如何编写示例代码和关联外部文件。此外，还涵盖了组合API的使用和特殊组件的注释方法。

摘要生成于 C知道，由 DeepSeek-R1 满血版支持，前往体验 >

示例代码地址

vue-styleguidist-demo

安装与基本配置

npm包安装

npm install --save-dev vue-styleguidist

加入`styleguide`相关命令

package.json

{
   
  "scripts": {
   
    "styleguide": "vue-styleguidist server",
    "styleguide:build": "vue-styleguidist build"
  }
}

vue-styleguidist server: 运行开发服务器。
vue-styleguidist build：生成静态 HTML 样式指南。

选项	描述
–config	指定配置文件的路径
–open	在默认浏览器中打开 Styleguidist
–verbose	打印调试信息

基本配置

最小配置

// styleguide.config.js
module.exports = {
   
    title: 'Vue Styleguidist 示例',
    components: 'src/components/**/[A-Z]*.vue',
    version: '1.1.1',
    styleguideDir: 'styleguide-dist',
    // 在编辑器的右上角添加一个小按钮，用于将编辑器的内容复制到剪贴板
    copyCodeButton:true,
    // 是否每个章节是一个独立的页面. 默认:false
    pagePerSection: true,
    // props/events/slot的说明默认是展开还是收缩: expand / collapse / hide
    usageMode: 'expand',
    // 左侧导航默认是展开还是收缩: expand / collapse / hide
    tocMode: 'expand',
    // 显示 prop、事件、槽或方法是否来自当前文件或在 mixin 或扩展组件中配置。如果它是外部的，它会显示组件的名称，并在悬停时显示文件的相对路径。
    displayOrigins: true
}

加载和公开组件

默认情况下，Styleguidist 会加载您的组件并在全局范围内公开它们以供您的示例使用。您可以使用localRegisterComponents来避免全局注册。这仅在其附加ReadMe.md文件或<docs>块中的示例中加载记录的组件。

查找组件

默认情况下，Styleguidist 将使用此glob 模式搜索组件: src/components/**/*.vue

也可自行修改:

module.exports = {
   
  components: 'src/components/**/[A-Z]*.vue'
}

但会忽略测试文件夹__tests__

章节配置

如果不进行额外的配置章节, 那么每个组件会是一个章节

name: 章节标题
content: 包含概览内容的 Markdown 文件的位置
components: glob 模式字符串、组件路径数组或 glob 模式字符串，或返回组件列表或 glob 模式字符串的函数。相同的规则适用于 root components选项
sections: 子章节数组（可以嵌套）
description: 本章节的简短说明
sectionDepth: 单页的子节数，仅在启用pagePerSection 时可用。
exampleMode: 代码示例选项卡的初始状态，使用exampleMode。
usageMode: 道具和方法选项卡的初始状态，使用usageMode。
ignore: 不应包含在该部分中的字符串/glob 数组。
href: 要导航到的 URL，而不是导航到部分内容
external: 如果设置，链接将在新窗口中打开

module.exports = {
   
  sections: [
    {
   
      name: 'Introduction',
      content: 'docs/introduction.md'
    },
    {
   
      name: 'Documentation',
      sections: [
        {
   
          name: 'Installation',
          content: 'docs/installation.md',
          description: 'The description for the installation section'
        },
        {
   
          name: 'Configuration',
          content: 'docs/configuration.md'
        },
        {
   
          name: 'Live Demo',
          external: true,
          href: 'http://example.com'</