本篇文章为《前端组件库的开发与维护》系列的第七篇文章。本文案例在线文档：calendar.hxkj.vip。GitHub 仓库：github.com/TangSY/vue3…。

前言

类似于 ElementUI 和 AntDesign 这样的 UI 组件库，除了自身功能完善，良好的文档支持，也是开发者乐于使用的一大原因。否则的话，开发者面临组件中大量的 API 根本无从下手。

那这些组件的文档到底是怎么写的呢？需要单独写个站点项目进行维护吗？

这些疑问咱们暂且不谈，先定义下，咱们想要的文档，需要哪些必要元素？

组件的简介、使用说明、常见问题、更新日志
详细列举组件的所有属性（API），包括类型、说明、默认值等
真实组件的渲染，可交互，示例代码复制即可直接使用

按照这个目标，再来探讨一下，到底应该怎么搭建一个完善的文档站点。

如果阅读过本系列的第一篇文章，应该就会发现其实一开始就已经选定了技术实现方案--Vant-Cli，咱们今天就用它来一步一步把站点搭起来。

搭建

对于还没有使用 Vant-Cli 搭起基础框架的，可以参考这篇文章先搭起来：基础框架的搭建

之后直接执行：yarn dev，就已经可以看到文档最初的模样了，给咱们预置了一个 Button 示例组件：

可以看到形成这样一个组件示例的大致结构：

用于右侧渲染的组件代码被放置在组件名称的 demo 文件夹下
用于渲染使用文档的 README.MD 文件被放置在组件名称的跟目录下

接下来咱们就可以依葫芦画瓢的编写自己的组件文档啦！

简介

这个比较简单，就是你给组件库做一个自我介绍，推荐从以下两个方面考虑：

突出组件库的独特性：在简介中，强调组件库的独特性和特点，例如组件库提供了哪些功能，它与其他组件库的不同之处，以及它的优势等
简洁明了：简介需要简洁明了，尽可能用简单易懂的语言介绍组件库，避免使用过多的术语和技术词汇。

以上两点加起来尽量一句话搞定。

之后再附上组件支持哪些特性，这里的描述可以尽量详细。例如：

常见问题（FAQ）

虽然这一环节的内容很容易被大部人忽略，根本不会去翻看 FAQ，习惯性的直接提问。但，我们还是可以给予有需要的人很大的帮助。

这里可以归纳一些用户经常遇到的问题，一般为使用过程中容易出现的问题，bug 性质的问题不会出现在这。尽量做到以下几点：

保持问题和答案简洁明了：用户通常会在浏览网页时快速浏览内容，因此你的问题和答案都应该简洁明了。不要使用过多的技术术语和复杂的语句，以确保用户可以轻松地找到他们想要的答案。
组织结构清晰：将常见问题按照相关主题分组。比如将所有关于布局的问题放在一起，将所有关于表单的问题放在一起等等。这样可以使用户更容易找到他们需要的答案，并且可以使 FAQ 更易于维护。
回答问题要详细：确保你的答案清晰明了，包含足够的信息，以便用户可以理解并解决问题。尽可能提供示例代码、截图等，以帮助用户更好地理解问题和答案。
定期更新FAQ：经常更新 FAQ 以确保其与组件库最新版本保持一致，并根据用户反馈及时添加新的问题和答案。
在其他文档中链接FAQ：在其他文档中，如组件文档或安装说明等，链接到 FAQ 页面，以便用户可以轻松地找到他们需要的信息。

常见问题编写样板：

API 列表

这个是组件最基本的组成部分，其他的统统可以不要，这部分内容是绝对不能舍去的，那怎么把它维护好呢，我觉得可以往以下几个方面靠拢：

明确API属性的用途：为每个属性提供简短的描述，以便其他开发人员了解它们的用途和用法。
分类和组织：API 属性可以按照功能或类别进行分类和组织。这可以使其他开发人员更轻松地找到他们需要的API属性。
包含默认值：为每个 API 属性提供默认值。这可以使其他开发人员了解属性的默认设置，以及它们如何影响组件的行为。
明确属性类型：在列举 API 属性时，需要明确属性类型，例如布尔值、字符串、数字或对象等。这可以使其他开发人员更好地理解如何正确使用API属性。
及时更新文档：当 API 属性发生变化时，需要及时更新文档。这可以确保其他开发人员可以了解 API 属性最新的用法和行为。文档与实际效果不一致是大忌！

具体如何实行，下图示例可以参考一下：

DEMO 示例

作为一个成熟的组件库，最重要的就是这一部分了，它可以帮助其他开发人员快速了解组件的用法和功能。以下是编写组件示例 DEMO 时需要遵循的规范：

明确示例的目标：在编写示例 DEMO 时，需要明确示例的目标和意图。示例应该覆盖组件的不同用例和方案，以便其他开发人员了解组件的不同功能及用法。
简洁明了：DEMO 代码量应该尽可能的少，只包含关键的代码，以便其他开发人员可以轻松地理解示例的执行逻辑。
提供完整的代码：以便其他开发人员可以轻松地理解示例的实现方法，同时也可以在需要时直接复制代码来使用。
示例的用途：需要说明它所演示的用途和功能，以便其他开发人员了解示例的用途和场景，以及如何在自己的项目中使用组件。
真实组件的渲染：开发人员可以非常直观的了解到不同的配置带来的不同展示效果，这一点相信大家应该感受很深。最讨厌的就是说一堆屁话，一张效果图都没有，使劲的说明支持这个支持那个，复制过来好不容易跑起来之后，只想说一句：“就这？？？”
按属性分类：可以让开发人员非常方便查看同一类的API。如果是单组件可以按传递类型分类：Events、Props、Methods。如果是多组件可以按功能分类：布局类、导航类、提示类。

单组件 DEMO 示例样板：

多组件 DEMO 示例样板：

配置 Vant-Cli

想要让网站内容更丰富，让站点更美观还得对 Vant-Cli 稍微配置一下。配置文件为项目跟目录下的 vant.config.mjs 文件。

主要需要改动 site 属性，这个是默认配置：

site: {
  title: 'hxkj-demo',
  logo: 'https://fastly.jsdelivr.net/npm/@vant/assets/logo.png',
  nav: [
    {
      title: '开发指南',
      items: [
        {
          path: 'home',
          title: '介绍',
        },
        {
          path: 'quickstart',
          title: '快速上手',
        },
      ],
    },
    {
      title: '基础组件',
      items: [
        {
          path: 'demo-button',
          title: 'DemoButton 按钮',
        },
      ],
    },
  ],
},

只包含一个基础的 demo 组件和两个菜单。

接下来咱们这就给它丰富一些内容，如下：

site: {
  // 组件库名称
  title: 'vue3-hash-calendar',
  // 组件库 logo
  logo: 'https://calendar.hxkj.vip/public/logo.png',
  // 组件库描述
  description: '基于 vue3 版本的周 月 时间选择器',
  // 百度统计 API key
  baiduAnalytics: {
    seed: 'b0668f30d62e1597bdb36d05edea8960',
  },
  // 在 `<head>` 标签中插入一段自定义的 HTML 内容。可用于修改文档站点样式
  headHtml: `<style type="text/css">
  .hash-demo-title {
    padding: 24px;
    font-size: 20px;
    text-align: center;
  }
  </style>`,
  // 暗黑模式全局 class 类名
  darkModeClass: 'van-theme-dark',
  // 普通模式全局 class 类名
  lightModeClass: 'van-theme-light',
  // 站点右上角跳转链接
  links: [
    {
      logo: 'https://fastly.jsdelivr.net/npm/@vant/assets/weapp.svg',
      url: 'https://gitee.com/HashTang/vue3-hash-calendar',
    },
    {
      logo: 'https://fastly.jsdelivr.net/npm/@vant/assets/github.svg',
      url: 'https://github.com/TangSY/vue3-hash-calendar',
    },
  ],
  // 站点左侧菜单导航
  nav: [
    {
      title: '开发指南',
      items: [
        { path: 'home', title: '介绍' },
        { path: 'quickstart', title: '快速上手' },
        { path: 'api', title: 'API' },
        { path: 'question', title: '常见问题' },
        { path: 'changelog', title: '更新日志' },
        { path: 'sponsor', title: '赞助' },
      ],
    },
    {
      title: 'Props 使用指南',
      items: propConfig,
    },
    {
      title: 'Event 使用指南',
      items: [{ title: '事件回调', path: 'event' }],
    },
    {
      title: 'Method 使用指南',
      items: [
        { title: '切换月份', path: 'switch-month' },
        { title: '切换星期', path: 'switch-week' },
        { title: '返回今日', path: 'today' },
        { title: '重置日历到指定日期', path: 'reset' },
      ],
    },
    {
      title: 'Slot 使用指南',
      items: slotConfig,
    },
  ],
},

大功告成！！！恭喜，你已经拥有一个内容丰富、美观且实用的文档站点了。

总结

今天这篇文章主要讲解了组件库文档站点包含哪些内容，以及每个内容的注意事项。

从 Vant-Cli 的配置方面优化站点丰富度、美观度。

下一篇咱们来看看如何自动集成/部署这个文档站点。

对此系列感兴趣的，不妨一键三连（点赞 + 关注 + 收藏），方便跟进后续文章。

欢迎大家在评论区留下宝贵的建议！

本系列往期文章

开启掘金成长之旅！这是我参与「掘金日新计划 · 2 月更文挑战」的第 3 天，点击查看活动详情”

组件库从开发到维护全链路讲解（七）搭建美观且实用的文档站点｜细节满满

前言

搭建

简介

常见问题（FAQ）

API 列表

DEMO 示例

配置 Vant-Cli

总结

本系列往期文章