# @alifd/api-extractor 中文文档

规范地址：https://npmcn.com/package/%40alifd/api-extractor/

版本：3\.7\.2
npm 元数据更新时间：2025-12-25T06:43:37.495Z
中文译文更新时间：2026-11-06T23:21:21.617Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40alifd/api-extractor
原文对照：https://npmcn.com/package/%40alifd/api-extractor/?lang=original
项目主页：https://github.com/alibaba-fusion/api-extractor
源码仓库：https://github.com/alibaba-fusion/api-extractor

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：24.7 kB，5 个文件
- 模块格式：CommonJS
- TypeScript 类型：未声明
- 运行依赖：5 个
- 首次发布：2018-08-22T02:54:00.835Z
- 最新版本发布：2021-06-11T03:02:25.122Z
- 近 30 天下载量：2179（2026-10-06 至 2026-11-04，npm 官方下载统计）
- 已发布版本数：15（近 12 个月 0 个）

## 中文简介

一个帮助从 React 组件中提取 api 的工具 .

## 安装

```sh
npm install @alifd/api-extractor
```

也可以使用：`pnpm add @alifd/api-extractor`、`yarn add @alifd/api-extractor`、`bun add @alifd/api-extractor`

## README

# @alifd/api-extractor

一个从 React 组件代码中提取 API 信息的工具，一般用来生成 API 文档，开发编辑器组件 API 提示插件以及开发页面搭建平台组件物料的属性面板，代码中附加信息书写方式来源于[jsDoc](http://usejsdoc.org/)，整体底层解析工具依赖于 [react-docgen](https://github.com/reactjs/react-docgen) 和 [doctrine](https://github.com/eslint/doctrine)。

[![npm package](https://img.shields.io/npm/v/@alifd/api-extractor.svg?style=flat-square)](https://www.npmjs.org/package/@alifd/api-extractor)

## Feature

-   支持通过`propTypes`获得属性类型
-   支持通过`defaultProps`获得属性默认值
-   支持通过`propTypes`上的 jsDoc 注释获得属性描述，自定义属性默认值
-   支持通过书写 jsDoc 获取函数类型属性的参数和返回值
-   支持通过书写 jsDoc 获取对象类型属性的属性
-   支持通过书写 jsDoc 获取组件静态方法和实例方法的描述，参数以及返回值
-   支持根据提取的 API 信息生成 markdown 片段，方便灵活组织API文档
-   支持通过按照约定书写组件上的 jsDoc 来获得父组件与子组件关系
-   支持通过`propTypes = {...Base.propTypes}`的方式扩展

## Install

```
npm install @alifd/api-extractor
```

## Usage

```js
const extractor = require('@alifd/api-extractor');
const apiInfo = extractor.extract(componentDirPath);
// const apiInfo = extractor.extractFile(componentFilePath);
```

## API

### extract(componentDirPath, options, parentMap)

**参数**：

-   componentDirPath `String` 组件代码文件夹路径
-   options `Object` 可选项
    -   md `Boolean` 是否生成`props`和`method`的 markdown 片段，默认值为`false`
    -   fileErrorHandler `Function` 自定义单个文件的错误处理函数，默认直接抛出错误
-   parentMap `Object` 可选项 组件继承关系，例如 Nav 继承自 Menu ，通过该参数可将 Menu 上的props merge到 Nav上

```js
{
  'Nav': {
    name: 'Menu',
    path: 'my-path/src/menu'
  },
  'Nav.Item': {
    name: 'Menu.Item',
    path: 'my-path/src/menu'
  }
}
```

**返回值**：

`Object` 参考下方 Example

### extractFile(componentFilePath, options)

**参数**：

-   componentFilePath `String` 组件代码文件路径
-   options `Object` 可选项
    -   md `Boolean` 是否生成`props`和`method`的 markdown 片段，默认值为`false`

**返回值**：

`Object` 参考下方 Example

### generatePropsMD(props)

**参数**：

-   props `Object` 使用`extract`方法生成api信息的`props`属性

**返回值**：

`String` props对应的markdown文本

### generateMethodMD(method)

**参数**：

-   method `Object` 使用`extract`方法生成api信息的`methods`属性的Item

**返回值**：

`String` method对应的markdown文本

## Example

如果传入的组件代码根路径下存在以下两个文件：

menu.js

```js
import React, { Component} from 'react';
import PropTypes from 'prop-types';

/**
 * Menu
 **/
export default class Menu extends Component {
  static propTypes = {
    /**
     * the menu size
     **/
    size: PropTypes.string,
    /**
     * select menu callback
     * @param {Array} selectedKeys the seleced keys
     **/
    onSelect: PropTypes.func
  };

  static defaultProps = {
    size: 'medium',
    onSelect: () => {}
  };

  render() {
    // ...
  }
}
```

menu-item.js

```js
import React, { Component} from 'react';
import PropTypes from 'prop-types';

/**
 * Menu.Item
 **/
export default class Item extends Component {
  // ...
}
```

我们会得到如下的 json 结构：

```js
{
  "name": "Menu",                              // 组件名
  "props": {
    "size": {                                  // 属性名
      "type": {
        "name": "string"                       // 属性类型
      },
      "required": false,                       // 属性是否必需
      "description": "the menu size",          // 属性描述
      "defaultValue": {
        "value": "'medium'",                   // 属性默认值
        "computed": false
      }
    },
    "onSelect": {
      "type": {
        "name": "func"
      },
      "required": false,
      "description": "select menu callback",
      "defaultValue": {
        "value": "() => {}",
        "computed": false
      },
      "docblock": "select menu callback\n@param {Array} selectedKeys the seleced keys",
      "params": [                               // 函数参数
        {
          "name": "selectedKeys",               // 函数参数名
          "description": "the seleced keys",    // 函数参数描述
          "type": {
            "name": "Array"                     // 函数参数类型
          }
        }
      ],
      "returns": null                           // 函数返回值
    }
  },
  "propsMD": "...",                             // 开启了md参数后，所有属性渲染出的 Markdown 文件
  "methods": [],                                // 方法
  "subComponents": [                            // 子组件
    {
      "description": "Item",
      // ...
    }
  ]
}
```

该 json 结构在[react-docgen 生成的 json 结构](https://github.com/reactjs/react-docgen#proptypes)基础上扩展而成。主要增加了`subComponents`，`propsMD`，属性为函数时的`parmas`，`return`和属性为对象时的`properties`结构。

`propsMD` 属性一般用来生成README.md中的API文档，`Menu` 组件的 `propsMD` 具体如下所示：

```
参数 | 说明 | 类型 | 默认值
-----|-----|-----|-----
size | the menu size | String | 'medium'
onSelect | select menu callback<br><br>**签名**:<br>Function(selectedKeys: Array) => void<br>**参数**:<br>selectedKeys {Array} the seleced keys | Function | () => {}
```

## Note

1.  只有添加了 jsDoc 注释的组件类，组件的属性以及组件的方法，才会被工具提取出相应的 API 信息。
    
2.  只有在文件中被`export default`的组件类才会被提取 API 信息
    
3.  默认传入的组件路径下只有一个根组件，如果想对外暴露两个组件，如`Row`和`Col`，也请在 jsDoc 的注释中添加根组件的前缀，如`Grid.Row`和`Grid.Col`。
    
4.  如果想控制子组件在`subComponents`中出现的顺序，以方便生成对应的 API 文档，可以为组件类的 jsDoc 注释中添加`order`字段（默认按照首字母顺序排列），如下所示：
    
    row.js
    
    ```js
    /**
     * Grid.Row
     * @order 1
     */
    export default class Row extends Component {
      // ...
    }
    ```
    
    col.js
    
    ```js
    /**
     * Grid.Col
     * @order 2
     */
    export default class Col extends Component {
      // ...
    }
    ```
    
5.  工具只支持一层的子组件，也就是说无法处理`AAA.BBB.CCC`的情况，当然我们也不认为这是一个组件应该对外暴露的使用方式。
    
6.  如果想自定义属性默认值，可以采用下面方法（其优先级高于`defaultProps`）：
    
    ```js
    /**
     * Description of prop "aaa"
     * @default custom
     **/
    aaa: PropTypes.string,
    ```
    
7.  如果像添加属性枚举值的描述，可以采用下面方法
    
    ```js
    /**
     * Description of prop "aaa"
     * @enumdesc left, right
     **/
    bbb: PropTypes.oneOf(['left', 'right']),
    ```
    
8.  可以通过书写 description tag 来为组件增加描述
    
    ```js
    /**
     * Upload.ImageUpload
     * @description 继承 [Upload](http://fusion-demo.alibaba-inc.com/api/1.0/views/next?themeId=next&name=upload#upload-1) 的 API，除非特别说明
     */
    class ImageUpload extends Component {
      //...
    }
    ```
    
9.  以下的写法，可以获得 Base 组件中声明的 API 信息
    
    ```js
    import Base from './base';
    
    export default class Menu extends Component {
        static propTypes = {
            ...Base.propTypes,
            /**
             * description
             */
            onSelect: PropTypes.func
        }
    }
    ```

## 常见问题

### @alifd/api-extractor 是什么？

一个帮助从 React 组件中提取 api 的工具 \.

### 如何安装 @alifd/api-extractor？

在项目目录运行 npm install @alifd/api-extractor，或使用 pnpm add / yarn add / bun add。

### @alifd/api-extractor 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/alifd\_\_api-extractor 是否存在。

### @alifd/api-extractor 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @alifd/api-extractor 可以商用吗？

@alifd/api-extractor 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @alifd/api-extractor 的下载量有多少？

根据 npm 官方下载统计，@alifd/api-extractor 在 2026/10/06 – 2026/11/04 这 30 天内被下载 2,179 次，日均约 73 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @alifd/api-extractor 还在维护吗？

最新版本 3\.7\.2 发布于 2021/06/11（5 年前）；至今共发布 15 个版本，其中过去 12 个月发布了 0 个；首次发布于 2018/08/22。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。