VueLens - Vue组件文档生成工具

VueLens是一个命令行工具，用于实时解析Vue组件并生成组件文档。它支持Vue 2和Vue 3组件，可以解析组件的属性、事件、插槽、方法等信息，生成易于阅读的文档。

特性

• 支持Vue 2和Vue 3组件解析
• 支持TypeScript类型声明解析
• 实时解析组件并在浏览器展示
• 可以导出为Markdown或HTML文档
• 可配置的扫描路径和端口
• 支持通过配置文件进行配置

安装

npm install -g vuelens

使用方法

命令行选项

vuel [选项]

选项:

• -v, --version - 显示版本号
• -c, --config <path> - 指定配置文件路径
• -p, --port <port> - 指定服务器端口
• -s, --scan <paths> - 指定要扫描的组件路径，使用逗号分隔
• -o, --output <path> - 输出文档的目录
• --vue-version <version> - 指定Vue版本 (2 或 3)
• --export-md - 导出为Markdown文档
• --export-html - 导出为HTML文档

基本用法

启动文档服务器

# 使用默认配置启动服务器
vuel

# 指定扫描路径和端口
vuel -s src/components,packages/ui -p 5000

导出文档

# 导出为Markdown文档
vuel --export-md -o docs/components

# 导出为HTML文档
vuel --export-html -o docs/components

配置文件

VueLens支持通过配置文件进行配置。可以在项目根目录创建vuelens.config.js文件：

module.exports = {
  // 服务器端口
  port: 3000,
  
  // 组件扫描路径 (相对于项目根目录)
  scanPaths: ['src/components'],
  
  // 文档输出路径
  outputPath: './vuelens-docs',
  
  // Vue版本 (2, 3, 或 'auto')
  vueVersion: 'auto',
  
  // 是否解析TS类型
  parseTypeScript: true,
  
  // 导出配置
  export: {
    // 是否在导出时包含示例代码
    includeExamples: true
  }
};

组件开发规范

为了让VueLens能够更好地解析您的组件，建议遵循以下规范：

组件属性说明

export default {
  props: {
    /**
     * 按钮类型
     * @values primary, secondary, danger
     */
    type: {
      type: String,
      default: 'primary',
      validator: value => ['primary', 'secondary', 'danger'].includes(value)
    },
    
    /**
     * 按钮尺寸
     * @values small, medium, large
     */
    size: {
      type: String,
      default: 'medium'
    },
    
    /**
     * 是否禁用
     */
    disabled: {
      type: Boolean,
      default: false
    }
  }
}

组件事件说明

methods: {
  /**
   * 点击按钮时触发
   * @param {MouseEvent} event - 点击事件对象
   */
  handleClick(event) {
    /**
     * 按钮点击事件
     * @event click
     * @type {MouseEvent}
     */
    this.$emit('click', event);
  }
}

组件插槽说明

<template>
  <button class="btn">
    <!-- 默认插槽用于显示按钮内容 -->
    <slot></slot>
    
    <!-- 图标插槽 -->
    <slot name="icon">
      <i v-if="hasDefaultIcon" class="default-icon"></i>
    </slot>
  </button>
</template>

export default {
  name: 'MyButton',
  /**
   * 组件拥有以下插槽
   * @slot default - 按钮文本内容
   * @slot icon - 自定义图标，如果提供则会替换默认图标
   */
}

TypeScript组件示例

import { Component, Prop, Vue, Emit } from 'vue-property-decorator';

/**
 * TypeScript按钮组件示例
 */
@Component
export default class MyButton extends Vue {
  /**
   * 按钮类型
   * @values primary, secondary, danger
   */
  @Prop({ default: 'primary' }) readonly type!: 'primary' | 'secondary' | 'danger';
  
  /**
   * 按钮尺寸
   * @values small, medium, large
   */
  @Prop({ default: 'medium' }) readonly size!: 'small' | 'medium' | 'large';
  
  /**
   * 是否禁用
   */
  @Prop({ default: false }) readonly disabled!: boolean;
  
  /**
   * 点击按钮时触发
   * @param {MouseEvent} event - 点击事件对象
   */
  @Emit('click')
  handleClick(event: MouseEvent): MouseEvent {
    return event;
  }
  
  /**
   * 渲染按钮样式类
   */
  get buttonClasses(): Record<string, boolean> {
    return {
      [`btn-${this.type}`]: true,
      [`btn-${this.size}`]: true,
      'btn-disabled': this.disabled
    };
  }
}

Vue 3 Composition API示例

<script setup lang="ts">
import { computed } from 'vue';

/**
 * 按钮类型
 * @values primary, secondary, danger
 */
const props = defineProps({
  type: {
    type: String as () => 'primary' | 'secondary' | 'danger',
    default: 'primary',
  },
  /**
   * 按钮尺寸
   * @values small, medium, large
   */
  size: {
    type: String as () => 'small' | 'medium' | 'large',
    default: 'medium',
  },
  /**
   * 是否禁用
   */
  disabled: {
    type: Boolean,
    default: false,
  },
});

/**
 * 点击按钮时触发
 * @param {MouseEvent} event - 点击事件对象
 */
const emit = defineEmits<{
  (e: 'click', event: MouseEvent): void
}>();

const handleClick = (event: MouseEvent) => {
  if (!props.disabled) {
    emit('click', event);
  }
};

/**
 * 计算按钮样式类
 */
const buttonClasses = computed(() => ({
  [`btn-${props.type}`]: true,
  [`btn-${props.size}`]: true,
  'btn-disabled': props.disabled,
}));
</script>

许可证

MIT