# @ckeditor/jsdoc-plugins 中文文档

规范地址：https://npmcn.com/package/%40ckeditor/jsdoc-plugins/

版本：43\.1\.0
npm 元数据更新时间：2025-06-26T08:12:24.498Z
中文译文更新时间：2026-11-09T23:20:22.011Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40ckeditor/jsdoc-plugins
原文对照：https://npmcn.com/package/%40ckeditor/jsdoc-plugins/?lang=original
项目主页：https://github.com/ckeditor/ckeditor5-dev/tree/master/packages/jsdoc-plugins
源码仓库：https://github.com/ckeditor/ckeditor5-dev

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

- 包体积（解压后）：73.1 kB，27 个文件
- TypeScript 类型：未声明
- Node.js 要求：\>=18\.0\.0
- 运行依赖：3 个
- 首次发布：2017-01-24T09:53:52.956Z
- 最新版本发布：2025-06-26T08:12:24.315Z
- 近 30 天下载量：12170（2026-10-10 至 2026-11-08，npm 官方下载统计）
- 已发布版本数：223（近 12 个月 0 个）

## 中文简介

由CKEditor 5团队开发的各种JSDoc插件.

## 安装

```sh
npm install @ckeditor/jsdoc-plugins
```

也可以使用：`pnpm add @ckeditor/jsdoc-plugins`、`yarn add @ckeditor/jsdoc-plugins`、`bun add @ckeditor/jsdoc-plugins`

## README

# JSDoc 插件概览

[![npm version](https://badge.fury.io/js/%40ckeditor%2Fjsdoc-plugins.svg)](https://www.npmjs.com/package/@ckeditor/jsdoc-plugins) [![CircleCI](https://circleci.com/gh/ckeditor/ckeditor5-dev.svg?style=shield)](https://app.circleci.com/pipelines/github/ckeditor/ckeditor5-dev?branch=master)

## 概览

此寄存器由少数插件组成,用于扩展 [联合来文文件](https://github.com/jsdoc3/jsdoc)。 。 。 .

通用插件列表 :

-   `lib/validator/validator.js` - 如果在别处定义了参数列表中所使用的类型或属性类型,则验证链接是否指向现有的属性/类/模块等.
-   `lib/export-fixer/export-fixer.js` - 修正错误 `export default` 语法
-   `lib/custom-tags/error.js` - 为习惯提供支持 `@error` 标签
-   `lib/relation-fixer.js` - 解决继承问题(将子女班级与父母班级的财产相扩展)
-   `lib/longname-fixer/longname-fixer.js` - 允许在链接中作简短标记
-   `lib/utils/doclet-logger.js` - 能够将输出输入 `<CWD>/docs/api/output.json`

CKEditor 5 个特定插件

-   `lib/event-extender/event-extender.js` - CKEditor 5 专用工具,用于插入所有事件的参数.
-   `lib/custom-tags/observable.js` - CKEditor 5 可观测属性的具体标记
-   `lib/observable-event-provider.js` - 电脑编辑5

## 使用量

### JSDoc 配置

要启用以上插件, 您需要将其列表于 `plugins` jSDoc 配置文件阵列.

```json
{
    "plugins": [
        "node_modules/@ckeditor/jsdoc-plugins/lib/validator/validator",
        "node_modules/@ckeditor/jsdoc-plugins/lib/longname-fixer/longname-fixer"
    ],
    // ...
}
```

然后,拥有 [https://github.com/jsdoc3/jsdoc 互联网档案馆的存檔,存档日期2013-12-21](https://github.com/jsdoc3/jsdoc) 安装,唯一要做的是调用命令 `-c` 指向配置文件的旗帜.

```bash
jsdoc -c path/to/config.json
```

## 参考类型

参考系统因 `lib/longname-fixer/longname-fixer.js` 插件 .

### 概览

JSDoc评论中有两种参考文献. 首先他们叫 `Full references`它们到处工作 但使用它们的骗局是长名 第二个是简短的引用,可以用来指向同一文件中存在的符号.

### 全文

全部引用从 `module:`。该语法的第一部分需要匹配 `@module` 标记在相应的类中.

以下是几个例子:

-   `@param {module:command~Command}`
-   `{@link module:core/editor/editor~Editor editor}`
-   `@member {module:core/editor/editor~Editor}`

### 简短参考

有两种类型的简短参考.

参考文献从 `#` 可用于成员的方法和活动,例如:. `{@link #create}`中,这些回放可用于指向同一类或接口内的成员和方法.

参考文献从 `~` 可用于指向类和界面,例如:. `{@link ~Editor}`。 。 。 . **有一个已知的问题,指点的东西 稍后宣布, 完全的 ref应该使用,然后.**

```js
class Editor {
    /**
     * This property represents {@link ~Editor editor} name.
     *
     * @member {String} #name
     */

    /**
     * This property represents editor version.
     * See editor {@link #name name}.
     *
     * @member {String} #version
     */

     /**
      * Get version of the editor
      * Note - '@method getVersion' isn't needed here because the method is declared.
      */
     getVersion() {
         return this.version;
     }
}
```

## 活动

活动可以分配给各班.

这个 `@fires` 财务报告和审定财务报表 `@event` 标签在充分引用和简短引用当前时效果良好 `class` 编号 : `interface` 编号 : `mixin`。 。 。 .

事件可以在类机构及其之后宣布(这两种情况都有简短的参考文献).

充分提及事件必须有以下语法: `module:somemodule~SomeClass#event:eventName`。注意: `event:` 这里需要部分. 简称可以是 `event:eventName` 或者说 `eventName`。 。 。 .

```js
class FocusTracker {
    /**
     * @private
     * @fires blur
     */
    _blur() { }

    /**
     * @fires focus
     * @fires module:focustracker~FocusTracker#event:focus // this will link to the same event as above
     */

    /**
     * @event blur
     */
}

// Note: the following event will be bound to the `FocusTracker` class.
/**
 * @event focus
 */
```

## 验证

### 概览

这个 `lib/validator/validator.js` 插件本应验证JSDoc评论中的引用并检查类型.

注意 `@module` 每个文件上方需要标记才能进行验证。 没有这个标记,验证者会用消息抱怨: `Memberof property should start with 'module:'`。 。 。 .

在JSDoc编译期间,每个无效的引用或类型都会将出错投入标准输出.

### 验证标记

以下标签的参考文献经过验证:

-   `@link` - 火柴吗 _参考文献_
-   `@member` - 火柴吗 _类型_
-   `@fires` - 匹配点 _事件_
-   `@param` - 火柴吗 _类型_
-   `@implements` - 匹配点 _接口_
-   `@returns` - 火柴吗 _类型_
-   `@see` - 火柴吗 _参考文献_

### 可用类型

有下列语法的种类很少:

-   通关卡 : `*`。 。 。 .
-   基本类型:基本ES和DOM类型,例如:. `String`, (中文(简体) ), `Boolean`, (中文(简体) ), `Error`, (中文(简体) ), `Node`。 。 。 .
-   字符串字元类型 : `'someString'`。 。 。 .
-   联盟类型 : `Type1|Type2`, (中文(简体) ), `Type1|Type2|Type3`等 (中文(简体) ).
-   一般类型 : `GenericType.<BasicType>`, (中文(简体) ), `GenericType<BasicType1, BasicType2>`等 (中文(简体) ).
-   参考文献:已声明的界面,对象,事件等. E. `module:somemodule~SomeInteface`。 。 。 .

这些类型可以一起使用,例如:

```js
/**
 * @param {Map.<*>} map
 * @param {'left'|'right'} direction
 * @param {Object.<String, *>} dictionary
 * @returns {Array.<Number|module:somemodule~SomeInteface>}
 */
```

基本类型和通用类型列于 `jsdoc/validator/types.js`。 。 。 .

## 开始

### 不支持的简短引用

目前,仍然很少有不支持的标签,需要充分参考:

-   `@param`
-   `@typedef`

### 缺少验证

还有一些标签没有验证:

-   `@mixes`
-   `@augments` 编号 : `@extends`

## 阶级成员的继承

该功能由 `lib/relation-fixer/index.js` 插件 .

### 概览

截止3.4.3 JSDoc版本 [不支持静态成员的继承](https://github.com/jsdoc3/jsdoc/issues/1229)。 。 。 .

如果B类扩展了A类和A类有静态属性,JSDoc将不会将该静态属性的文档输出到B类的文档.

这个 `lib/relation-fixer` 插件检查这类案件,并更新儿童班的文件,提供继承、实施或混合静态成员的文件.

它还为类,界面和混音器的doclets添加了额外的属性,以显示相关的doclets. 这些属性是:

-   `augmentsNested` - 所有家长班级的参考文献,
-   `implementsNested` - 一系列已执行接口的参考文献,
-   `mixesNested` - 各种混合混合剂的参考文献,
-   `descendants` - 一系列关于执行、混合或扩展道格的实体的参考.

## 更改日志

见 [`CHANGELOG.md`](https://github.com/ckeditor/ckeditor5-dev/blob/master/packages/jsdoc-plugins/CHANGELOG.md) 文档.

## 常见问题

### @ckeditor/jsdoc-plugins 是什么？

由CKEditor 5团队开发的各种JSDoc插件\.

### 如何安装 @ckeditor/jsdoc-plugins？

在项目目录运行 npm install @ckeditor/jsdoc-plugins，或使用 pnpm add / yarn add / bun add。

### @ckeditor/jsdoc-plugins 支持 TypeScript 吗？

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

### @ckeditor/jsdoc-plugins 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=18\.0\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @ckeditor/jsdoc-plugins 可以商用吗？

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

### @ckeditor/jsdoc-plugins 的下载量有多少？

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

### @ckeditor/jsdoc-plugins 还在维护吗？

最新版本 43\.1\.0 发布于 2025/06/26（1\.4 年前）；至今共发布 223 个版本，其中过去 12 个月发布了 0 个；首次发布于 2017/01/24。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。