vue中组件为json文件_为Vue文件组件生成JSON文档

vue中组件为json文件

Vuedoc分析器 (The Vuedoc Parser)

Generate a JSON documentation for a SFC Vue component.

为SFC Vue组件生成JSON文档。

安装 (Install)

npm install --save @vuedoc/parser

特征 (Features)

• Extract the component name (from the name field or from the filename)

  提取组件名称(从名称字段或文件名中提取)

• Extract the component description

  提取组件描述

• Keywords Support: You can define your own keywords with the @ symbol like

  关键字支持：您可以使用@符号定义自己的关键字，例如

  
  
  

  @author Jon Snow

  @author Jon Snow

• Extract component model

  提取组件模型

• Extract component props

  提取道具

• Extract component data

  提取组件数据

• Extract computed properties with dependencies

  提取具有依赖性的计算属性

• Extract component events

  提取组件事件

• Extract component slots

  提取组件插槽

• Extract component methods

  提取成分方法

• Class Component Support

  类组件支持

• Vue Property Decorator Support

  Vue属性装饰器支持

• JSDoc Support (@param and

  JSDoc支持( @param和

  
  
  

  @return tags)

  @return标签)

选件 (Options)

name	description
filename	The filename to parse. Required unless filecontent is passed
filecontent	The file content to parse. Required unless filename is passed
encoding	The file encoding. Default is 'utf8'
features	The component features to parse and extract.
	Default features: ['name', 'description', 'keywords', 'slots', 'model', 'props', 'data', 'computed', 'events', 'methods']
loaders	Use this option to define custom loaders for specific languages
defaultMethodVisibility	Can be set to 'public' (default), 'protected', or 'private'
ignoredVisibilities	List of ignored visibilities. Default: ['protected', 'private']
stringify	Set to true to disable parsing of literal values and stringify literal values. Default: false

名称	描述
文档名称	要解析的文件名。 必需的 ，除非filecontent传递
文件内容	要解析的文件内容。 除非传递filename否则为必需
编码方式	文件编码。 默认为'utf8'
特征	该组件具有解析和提取功能。
	默认功能： ['name', 'description', 'keywords', 'slots', 'model', 'props', 'data', 'computed', 'events', 'methods']
装载机	使用此选项可以为特定语言定义自定义加载程序
defaultMethodVisibility	可以设置为'public' ( 默认 )， 'protected'或'private'
被忽略的可能性	忽略的可见性列表。 默认值： ['protected', 'private']
串化	设置为true将禁用对文字值的解析并对文字值进行字符串化。 默认值： false

Note for stringify option

注意stringify选项

By default Vuedoc Parser parses literal values defined in the source code. This means:

默认情况下，Vuedoc Parser解析源代码中定义的文字值。 这表示：

const binVar = 0b111110111 // will be parsed as binVar = 503
const numVar = 1_000_000_000 // will be parsed as numVar = 1000000000

To preserve literal values, set the stringify option to true.

要保留文字值，请将stringify选项设置为true 。

用法 (Usage)

See test/fixtures/checkbox.vue for an Vue Component decoration example.

有关Vue组件装饰示例，请参见test / fixtures / checkbox.vue 。

const Vuedoc = require('@vuedoc/parser')
const options = {
  filename: 'test/fixtures/checkbox.vue'
}

Vuedoc.parse(options)
  .then((component) => console.log(component))
  .catch((err) => console.error(err))

This will print this JSON output:

这将打印此JSON输出：

{
  "name": "checkbox" // The component name
  "description": "A simple checkbox component" // The component description
  // Attached component keywords
  "keywords": [
    { "name": "author", "description": "Sébastien" }
  ],
  "props": [ ... ],
  "data": [ ... ],
  "computed": [ ... ],
  "slots": [ ... ],
  "events": [ ... ],
  "methods": [ ... ]
}

See test/fixtures/checkbox-result.json for the complete result.

有关完整结果，请参见test / fixtures / checkbox-result.json 。

句法 (Syntax)

添加组件名称 (Add component name)

By default, Vuedoc Parser use the component's filename to generate the component name.

默认情况下，Vuedoc Parser使用组件的文件名来生成组件名称。

To set a custom name, use the name field like:

要设置自定义名称，请使用name字段，例如：

export default {
  name: 'my-checkbox'
}

You can also use the @name keyword to set the component name:

您还可以使用@name关键字设置组件名称：

/**
 * @name my-checkbox
 */
export default {
  // ...
}

添加组件说明 (Add component description)

To add a component description, just add a comment before the export default statement like:

要添加组件描述，只需在export default语句之前添加一个注释，例如：

/**
 * Component description
 */
export default {
  ...
}

注释模型，道具，数据和计算出的属性 (Annotate model, props, data and computed properties)

To document props, data or computed properties, use comments like:

要记录道具，数据或计算的属性，请使用如下注释：

export default {
  props: {
    /**
     * Component ID
     */
    id: {
      type: String,
      required: true
    }
  },
  data () {
    return {
      /**
       * Indicates that the control is checked
       */
      isChecked: false
    }
  },
  computed: {
    /**
     * Indicates that the control is selected
     */
    selected () {
      return this.isChecked
    }
  }
}

Vuedoc Parser will automatically extract required and default values for properties and computed properties dependencies. It will also detect type for each defined data field.

Vuedoc Parser将自动提取属性和计算的属性依赖项的required值和default值。 它还将检测每个定义的数据字段的类型。

You can set a custom default value of an prop by using the keyword @default.

您可以使用关键字@default来设置道具的自定义默认值。

export default {
  props: {
    /**
     * Custom default value
     * @default { anything: 'custom default value' }
     */
    custom: {
      type: String,
      default: () => {
        // complex code
        return anythingExpression()
      }
    }
  }
}

To document a v-model prop, a proper way is to use the Vue's model field if you use Vue +2.2.0.

要记录v-model道具，正确的方法是如果使用Vue +2.2.0，则使用Vue的模型字段 。

export default {
  /**
   * Use `v-model` to define a reactive value of the checkbox
   */
  model: {
    prop: 'checked',
    event: 'change'
  }
}

You can also use the @model keyword on a prop if you use an old Vue version:

如果您使用旧的Vue版本，也可以在@model上使用@model关键字：

export default {
  props: {
    /**
     * The checkbox model
     * @model
     */
    model: {
      type: Array,
      required: true
    }
  }
}

To document Vue array string props, just attach a Vuedoc comment to each prop:

要记录Vue数组字符串道具，只需在每个道具上附加一个Vuedoc注释：

export default {
  props: [
    /**
     * Checkbox ID
     */
    'id',

    /**
     * The checkbox model
     */
    'value'
  ]
}

By default, all extracted things have the public visibility. To change this for one entry, add @protected or @private keyword.

默认情况下，所有提取的内容都具有public可见性。 要更改一项，请添加@protected或@private关键字。

export default {
  data: () => ({
    /**
     * This will be ignored on parsing
     * @private
     */
    isChecked: false
  })
}

注释方法，事件和位置 (Annotate methods, events and slots)

To document methods or events, just add comments before:

要记录方法或事件，只需在以下位置添加注释：

export default {
  methods: {
    /**
     * Submit form
     */
    check () {
      /**
       * Emit the `input` event on submit
       */
      this.$emit('input', true)
    }
  }
}

Vuedoc Parser automatically extracts events from component hooks:

Vuedoc Parser会自动从组件挂钩中提取事件：

export default {
  created () {
    /**
     * Emit on Vue `created` hook
     */
    this.$emit('created', true)
  }
}

Use the JSDoc @param and @return tags to define parameters and returning type:

使用JSDoc @param和@return标记定义参数和返回类型：

export default {
  methods: {
    /**
     * Submit form
     *
     * @param {object} data - Data to submit
     * @return {boolean} true on success; otherwise, false
     */
    submit (data) {
      /**
       * Emit the `loading` event on submit
       *
       * @arg {boolean} status - The loading status
       */
      this.$emit('loading', true)

      return true
    }
  }
}

Note: @arg is an alias of @param

注意： @arg是@param的别名

The parser is also able to extract events and slots from template:

解析器还能够从模板中提取事件和插槽：

Usage with non primitive name

非原始名称的用法

You can use special keywords @method and @event for non primitive name:

您可以将特殊关键字@method和@event用作非原始名称：

注释渲染功能中定义的插槽 (Annotate slots defined in Render Functions)

To annotate slots defined in Render Functions, just attach the keyword @slot to the component definition:

要注释在“渲染功能”中定义的插槽，只需将关键字@slot附加到组件定义：

/**
 * A functional component with slots defined in render function
 * @slot title - A title slot
 * @slot default - A default slot
 */
export default {
  functional: true,
  render(h, { slots }) {
    return h('div', [
      h('h1', slots().title),
      h('p', slots().default)
    ])
  }
}

You can also use the keyword @slot to define dynamic slots on template:

您也可以使用关键字@slot在模板上定义动态广告位：

关键字提取 (Keywords Extraction)

You can attach keywords to any comment and then extract them using the parser.

您可以将关键字附加到任何注释，然后使用解析器将其提取。

Usage

用法

/**
 * Component description
 *
 * @author Arya Stark
 * @license MIT
 */
export default { ... }

Note that the description must alway appear before keywords definition

请注意，描述必须始终出现在关键字定义之前

Parsing result:

解析结果：

{
  "name": "my-checkbox",
  "description": "Component description",
  "keywords": [
    {
      "name": "author",
      "description": "Arya Stark"
    },
    {
      "name": "license",
      "description": "MIT"
    }
  ]
}

使用Mixins (Working with Mixins)

Since Vuedoc Parser don't perform I/O operations, it completely ignores the mixins property.

由于Vuedoc Parser不执行I / O操作，因此它将完全忽略mixins属性。

To parse a mixin, you need to parse its file as a standalone component and then merge the parsing result with the result of the initial component:

要解析mixin，您需要将其文件解析为一个独立的组件，然后将解析结果与初始组件的结果合并：

const Vuedoc = require('@vuedoc/parser')
const merge = require('deepmerge')

const parsers = [
  Vuedoc.parse({ filename: 'mixinFile.js' })
  Vuedoc.parse({ filename: 'componentUsingMixin.vue' })
]

Promise.all(parsers)
  .then(merge.all)
  .then((mergedParsingResult) => console.log(mergedParsingResult))
  .catch((err) => console.error(err))

Using the keyword @mixin

使用关键字@mixin

You can use the special keyword @mixin to force parsing named exported component:

您可以使用特殊关键字@mixin强制解析命名的导出组件：

import Vue from 'vue';

/**
 * @mixin
 */
export const InputMixin = Vue.extend({
  props: {
    id: String,
    Value: [ Boolean, Number, String ]
  }
});

使用options.features解析控件 (Parsing control with options.features)

options.features lets you select which Vue Features you want to parse and extract.

options.features使您可以选择要解析和提取的Vue功能。

The default value is defined by Vuedoc.Parser.SUPPORTED_FEATURES array.

默认值由Vuedoc.Parser.SUPPORTED_FEATURES数组定义。

Usage

用法

Only parse name, props, computed properties, slots and events:

仅解析name ， props ， computed properties ， slots和events ：

const Vuedoc = require('@vuedoc/parser')

const options = {
  filename: 'test/fixtures/checkbox.vue',
  features: [ 'name', 'props', 'computed', 'slots', 'events' ]
}

Vuedoc.parse(options)
  .then((component) => Object.keys(component))
  .then((keys) => console.log(keys))
  // => [ 'name', 'props', 'computed', 'slots', 'events' ]

Parse all features except data:

解析除data外的所有功能：

const Vuedoc = require('@vuedoc/parser')

const options = {
  filename: 'test/fixtures/checkbox.vue',
  features: Vuedoc.Parser.SUPPORTED_FEATURES.filter((feature) => feature !== 'data')
}

Vuedoc.parse(options)
  .then((component) => Object.keys(component))
  .then((keys) => console.log(keys))
  // => [ 'name', 'description', 'keywords', 'model',
  //      'props', 'computed', 'events', 'methods', 'slots' ]

语言处理 (Language Processing)

加载程序API (Loader API)

abstract class Loader {
  public static extend(loaderName: string, loaderClass: Loader);
  public abstract load(source: string): Promise;
  public emitTemplate(source: string): Promise;
  public emitScript(source: string): Promise;
  public emitErrors(errors: Array): Promise;
  public pipe(loaderName: string, source: string): Promise;
}

内置装载机 (Build-in loaders)

Language	Load by default?	Package
HTML	Yes	@vuedoc/parser/loader/html
JavaScript	Yes	@vuedoc/parser/loader/javascript
Pug	No	@vuedoc/parser/loader/pug
TypeScript	No	@vuedoc/parser/loader/typescript
Vue	Yes	@vuedoc/parser/loader/vue

语言	默认加载？	包
HTML	是	@ vuedoc / parser / loader / html
JavaScript	是	@ vuedoc / parser / loader / javascript
哈巴狗	没有	@ vuedoc /解析器/加载器/ pug
打字稿	没有	@ vuedoc /解析器/加载器/打字稿
Vue	是	@ vuedoc /解析器/加载器/ vue

TypeScript的用法 (TypeScript usage)

The Vuedoc Parser package contains a loader for TypeScript. To use it, you need to:

Vuedoc Parser软件包包含TypeScript的加载程序。 要使用它，您需要：

• install typescript and @types/node dependencies according the

  根据安装安装typescript和@types/node依赖项

  
  
  

  official documentation

  官方文件

• import and load the loader @vuedoc/parser/loader/typescript

  导入并加载加载程序@vuedoc/parser/loader/typescript

const Vuedoc = require('@vuedoc/parser')
const TypeScriptLoader = require('@vuedoc/parser/loader/typescript')

const options = {
  filename: 'DatePicker.ts',
  loaders: [
    /**
     * Register TypeScriptLoader
     * Note that the name of the loader is either the extension
     * of the file or the value of the attribute `lang`
     */
    Vuedoc.Loader.extend('ts', TypeScriptLoader)
  ]
}

Vuedoc.parse(options).then((component) => {
  console.log(component)
})

创建一个自定义加载器 (Create a custom loader)

The example below uses the abstract Vuedoc.Loader class to create a specialized class to handle a template with the CoffeeScript language. It uses the Pug language for templating:

下面的示例使用抽象的Vuedoc.Loader类创建专门的类来处理使用CoffeeScript语言的模板。 它使用Pug语言进行模板制作：

const Vuedoc = require('@vuedoc/parser')
const PugLoader = require('@vuedoc/parser/loader/pug')
const CoffeeScript = require('coffeescript')

class CoffeeScriptLoader extends Vuedoc.Loader {
  load (source) {
    const outputText = CoffeeScript.compile(source);

    // don't forget the return here
    return this.emitScript(outputText);
  }
}

const options = {
  filecontent: `
    

    
  `,
  loaders: [
    /**
     * Register CoffeeScriptLoader
     * Note that the name of the loader is either the extension
     * of the file or the value of the attribute `lang`
     */
    Vuedoc.Loader.extend('coffee', CoffeeScriptLoader),

    // Register the Pug loader
    Vuedoc.Loader.extend('pug', PugLoader)
  ]
}

Vuedoc.parse(options).then((component) => {
  console.log(component)
})

Output

输出量

{
  name: 'MyInput',
  description: 'Description of MyInput component',
  slots: [
    {
      kind: 'slot',
      visibility: 'public',
      description: 'Use this slot to define a subtitle',
      keywords: [],
      name: 'subtitle',
      props: []
    }
  ],
  // ...
}

解析输出接口 (Parsing Output Interface)

type ParsingOutput = {
  name: string;               // Component name
  description: string;        // Component description
  inheritAttrs: boolean;
  keywords: Keyword[];        // Attached component keywords
  model?: ModelEntry;         // Component model
  slots: SlotEntry[];         // Component slots
  props: PropEntry[];         // Component props
  data: DataEntry[];          // Component data
  computed: ComputedEntry[];  // Computed properties
  events: EventEntry[];       // Events
  methods: MethodEntry[];     // Component methods
  errors: string[];           // Syntax and parsing errors
};

enum NativeTypeEnum {
  string,
  number,
  bigint,
  boolean,
  bigint,
  any,                        // for an explicit `null` or `undefined` values
  object,                     // for an array or an object
  CallExpression              // for a value like `new Date()`
};

type Keyword = {
  name: string;
  description: string;
}

interface Entry {
  kind: 'computed' | 'data' | 'event' | 'method' | 'model' | 'prop' | 'slot';
  visibility: 'public' | 'protected' | 'private';
  description: string;
  keywords: Keyword[];
}

interface ModelEntry extends Entry {
  kind: 'model';
  prop: string;
  event: string;
}

interface SlotEntry extends Entry {
  kind: 'slot';
  name: string;
  props: SlotProp[];
}

type SlotProp = {
  name: string;
  type: string;
  description: string;
};

interface ModelEntry extends Entry {
  kind: 'model';
  prop: string;
  event: string;
}

interface PropEntry extends Entry {
  kind: 'prop';
  name: string;               // v-model when the @model keyword is attached
  type: string | string[];    // ex. Array, Object, String, [String, Number]
  nativeType: NativeTypeEnum;
  default?: string;
  required: boolean = false;
  describeModel: boolean;     // true when the @model keyword is attached
}

interface DataEntry extends Entry {
  kind: 'data';
  name: string;
  type: NativeTypeEnum;
  initial?: string;
}

interface ComputedEntry extends Entry {
  kind: 'computed';
  name: string;
  dependencies: string[];     // list of dependencies of the computed property
}

interface EventEntry extends Entry {
  kind: 'event';
  name: string;
  arguments: EventArgument[];
}

type EventArgument = {
  name: string;
  description: string;
  type: string;
};

interface MethodEntry extends Entry {
  kind: 'method';
  name: string;
  params: MethodParam[];
  return: MethodReturn;
}

type MethodParam = {
  type: string;
  name: string;
  description: string;
  defaultValue?: string;
}

type MethodReturn = {
  type: string = 'void';
  description: string;
};

翻译自: https://vuejsexamples.com/generate-a-json-documentation-for-a-vue-file-component/

vue中组件为json文件