emp-proptypes-docgen-plugin

A webpack plugin to inject react typescript docgen information in cweb.

Usage no npm install needed!

<script type="module">
  import empProptypesDocgenPlugin from 'https://cdn.skypack.dev/emp-proptypes-docgen-plugin';
</script>

README

emp-proptypes-docgen-plugin

通过 React Typescript Docgen 对象 生成 `empPropTypes` 并插入组件的一个webpack插件。

Install

npm install --save-dev emp-proptypes-docgen-plugin
# or
yarn add -D emp-proptypes-docgen-plugin

使用

const ts = require("typescript");
const EmpPropTypesDocgenPlugin = require("emp-proptypes-docgen-plugin").default;
const {node_modulesPropFilter} = require("emp-proptypes-docgen-plugin");

module.exports = {
  plugins: [
    // Will default to loading your root tsconfig.json
    new EmpPropTypesDocgenPlugin(),
    // or with a specific tsconfig
    new EmpPropTypesDocgenPlugin({ tsconfigPath: "./tsconfig.dev.json" }),
    // or with compiler options
    new EmpPropTypesDocgenPlugin({
      compilerOptions: { jsx: ts.JsxEmit.Preserve }
    })
    // 新版默认关闭组件内联挂载,需要手动开启
    new EmpPropTypesDocgenPlugin({
      inlineWithComponent: true
    })
    new EmpPropTypesDocgenPlugin({
      include: [path.resolve(__dirname, './src/**/*.tsx')],
      // 忽略node_modules的ts生成,用于缩减产物大小
      propFilter: node_modulesPropFilter(prop)
    })
  ]
};

支持直接推导的类型

Props 类型 表单控件
string Input
number InputNumber
boolean Switch
React.CSSProperties StyleEdit(样式编辑器)
enum , 'a' \| 'b' Select

常用 JSDoc 规范

常用注释类型 作用
@default 指定默认值
@desc / @description 指定参数描述
@type 默认从类型值直接推断,指定@type 时优先

例子

分离到 emp.docgen.json

组件内联生成例子

生成组件名称和描述

empPropTypes.defined.description

/**
 * @label 礼物图标
 * @desc 营收礼物图标
 * @visibleName PropsIcon
 */
export const PropsIcon = (props: PropsIconType) => {}

      ↓ ↓ ↓ ↓ ↓ ↓

PropsIcon.empPropTypes = {
  "defined": {
    "description": "营收礼物图标"
  },
  "name": "PropsIcon",
  "props": {...}
}

生成组件参数

empPropTypes.props

// 通过类型获取`description`和`type`
export type PropsIconType = {
  /**
   *  @type {EmpPropTypes.Upload}
   *  @default https://www.baidu.com/icon.png
   *  @desc 图标地址
   */
  iconUrl: string;
}
      ↓ ↓ ↓ ↓ ↓ ↓
PropsIcon.empPropTypes = {
  "defined": {
    "description": "营收礼物图标"
  },
  "name": "PropsIcon",
  "props": {
    "iconUrl": {
      "defaultValue": "https://www.baidu.com",
      "description": "图标地址",
      "label": "iconUrl",
      "required": true,
      "type": "Upload"
    }
  }
}

枚举类型

生成 antd - Select 组件需要的options

enum Nums = {
  /** 1个 */
  One = 1,
  /** 两个 */
  Two = 2
}
// 通过类型获取`description`和`type`
export type PropsIconType = {
  nums: Nums
}
      ↓ ↓ ↓ ↓ ↓ ↓
PropsIcon.empPropTypes = {
  "defined": {
    "description": "营收礼物图标"
  },
  "name": "PropsIcon",
  "props": {
    "nums": {
      "options": {
        "options": [{
          label: "1个",
          value: 1
        },{
          label: "两个",
          value: 2
        }]
      }
      "type": "Select"
    }
  }
}

注意事项

  1. 需要指定@visibleName(推荐指定),表示挂载配置对象的变量名。
  2. 若不指定,默认取文件名或者所在文件夹名称(一般与组件名一致)。

About

支持react-docgen-typescript 的所有参数透传。其他可用的配置项可以参考react-docgen-typescript-plugin