JS注解怎么标注可选参数_ JS函数可选参数的注解方式与示例

<p> 使用 jsDoc 标注可选参数需用方括号[] 包裹参数名，如 @param {type} [param] – 描述，支持默认值写法 [param=default]，提升 代码可读性 与工具 支持。</p>

在 javaScript 中，函数参数默认都是可选的，因为语言本身不会强制传参。但在使用 JSDoc 为代码添加类型注解时，明确标注哪些参数是可选的，能显著提升 代码可读性 和工具 支持（如 ide 智能提示、类型检查）。下面介绍如何用 JSDoc 正确标注 JS 函数中的可选参数。

使用 JSDoc 标注可选参数

JSDoc 通过在参数名两边加上方括号 [] 来表示该参数是可选的。这是标准且广泛支持的写法。

语法格式：

@param {类型} [参数名] - 描述

示例：

/**  * 发送通知  * @param {String} message - 要显示的消息内容  * @param {string} [level='info'] - 消息级别，可选，默认为 'info'  * @param {number} [duration] - 显示时长（毫秒），可选  */ function notify(message, level = 'info', duration) {console.log(`[${level}] ${message}`);   if (duration) {setTimeout(() => console.log('通知已结束'), duration);   } }

在这个例子中，level 和 duration 都被标记为可选参数。其中 level 还带有默认值，JSDoc 中也可以直接写默认值说明。

带默认值的可选参数注解

如果参数在函数定义中有默认值，JSDoc 依然建议用方括号包裹参数名，并可在描述中注明默认值，或直接在类型后写明。

更清晰的写法：

阿里云 - 虚拟数字人

阿里云 - 虚拟数字人是什么？…

2

查看详情

/**  * 计算折扣后价格  * @param {number} price - 原价  * @param {number} [discount=0.1] - 折扣比例，默认 10%  * @returns {number} 折后价格  */ function calcPrice(price, discount = 0.1) {return price * (1 - discount); }

这里 [discount=0.1] 表示参数可选且默认值为 0.1，IDE 和类型工具能据此提供更准确的提示。

可选参数与 typescript 风格对比

如果你使用 TypeScript，语法会更简洁：在参数名后加 ?，如 name?: string。但在纯 JS 配合 JSDoc 时，应坚持使用方括号方式。

例如，等效写法：

• TS: (name?: string) => void
• JS + JSDoc: @param {string} [name]

两者语义一致，但 JSDoc 更适合在 javascript 项目中保持类型信息。

注意事项与最佳实践

为了确保注解有效，注意以下几点：

• 只有确实可以不传的参数才标注为可选
• 有默认值的参数一定用 [param=default] 形式，增强可读性
• 配合 @returns 和 @example 可进一步完善文档
• 现代编辑器（如vs code）能根据 JSDoc 实现自动补全和错误提示

基本上就这些。合理使用 JSDoc 标注可选参数，能让 JS 函数 接口 更清晰，团队协作更顺畅。