HTML5注释怎么写参数说明_函数参数注释的规范与示例【模板】-html教程-PHP中文网

HTML注释仅支持纯文本，不能解析参数或类型；参数说明应使用JS中的JSDoc或TS接口定义，而非HTML注释。

html5注释怎么写参数说明_函数参数注释的规范与示例【模板】

HTML 中的注释写法与常见误用

HTML 本身不支持带参数说明的注释语法，只能写纯文本，不能解析成函数签名或类型提示。所谓“HTML5 注释写参数说明”，实际是开发者在 HTML 模板里手写文档式注释，用于辅助理解嵌入的 JS 逻辑、模板变量或组件接口。

容易踩的坑：把当作可被工具识别的标准（像 JSDoc 那样），但浏览器和多数构建工具默认完全忽略这些注释，也不会校验参数名是否匹配真实代码。

注释内容不会出现在 DOM 中，但会保留在源码里，影响加载体积（尤其大段说明）
若混用 <script></script> 内联脚本，别在 HTML 注释里写 JS 类型（如），这不属于任何标准，仅靠人工维护
Vue / Svelte 等框架的单文件组件中，仍只是 HTML 注释，不是组件 Props 文档 —— 应该用 <script setup></script> 上方的 JSDoc 或块

JSDoc 风格注释必须写在 JS 代码中，而非 HTML

要真正实现“函数参数说明”，注释必须紧贴 JS 函数声明，使用标准 JSDoc 语法，并由支持 JSDoc 的工具（如 TypeScript、ESLint、Volar、IDE）解析。HTML 文件里的 <script></script> 标签内可以写，但位置和格式有硬性要求。

正确示例（放在 <script></script> 内部，且紧邻函数）：

/**
 * 格式化用户信息并插入到页面
 * @param {string} name - 用户姓名，必填
 * @param {number} age - 年龄，大于 0
 * @param {boolean} [isActive=false] - 是否启用状态，可选
 */
function renderUser(name, age, isActive = false) {
  document.getElementById('user').textContent = `${name} (${age})`;
}

@param 后必须跟空格、类型（用花括号包裹）、参数名、短横线和说明
可选参数用方括号标记：[isActive=false]，类型后不能加问号（那是 TypeScript 语法，JSDoc 不认）
注释块必须用 /** */，不能用 // 或
若 HTML 中通过 <script src="..."></script> 引入外部 JS，则注释必须写在那个 .js 文件里，HTML 中写无效

HTML 模板中模拟参数说明的实用做法

当 HTML 作为模板（如 PHP、Django、Nunjucks 渲染上下文）时，开发者常在注释中“手写接口契约”。这不是标准，但团队约定后可提升可读性。关键是要保持简洁、一致、不与真实逻辑耦合。

推荐写法（以含变量的静态 HTML 片段为例）：

Vue Wrap

Vue 入门指南 — JavaScript 框架

下载

<!--
  组件：user-card
  Props：
    - name: string, required
    - avatarUrl: string, optional
    - badge: 'vip' | 'new' | undefined
-->
<div class="card">
  @@##@@" alt="">
  <h3></h3>
</div>

用 Props： 明确区分这是接口描述，不是运行时注释
类型用简写（string、number），枚举值用单引号包裹（'vip'），可选用 optional 或默认值标注
避免写复杂类型（如 {id: number, tags: string[]}），这类应移至配套 JS 或类型定义文件
不要在注释里写逻辑（如 “如果 badge 是 vip 则加金边”），样式/行为应由 CSS 类或 JS 控制，注释只管“传什么”

TypeScript + HTML 混合项目中的真实约束点

如果你用 TypeScript 编写逻辑、HTML 仅作结构，那么“参数说明”的权威来源只能是 TS 接口或类型定义，HTML 注释没有任何校验能力。强行在 HTML 里重复写参数，反而增加维护成本和不一致风险。

例如，一个组件接收的 props 应定义为：

interface UserCardProps {
  name: string;
  avatarUrl?: string;
  badge?: 'vip' | 'new';
}

然后在调用处（JSX 或模板字符串）由 IDE 提示补全，而不是靠 HTML 注释记忆。

HTML 注释无法防止传错类型（比如传了 avatarUrl={123}），只有 TS 能做这件事
构建工具（如 Vite + vue-tsc）会检查 TS 类型，但完全无视
如果团队坚持 HTML 内写文档，建议只写高阶说明（如“此区域由后端 JSON 渲染，字段见 /api/user/schema”），把细节交给接口文档或 TS 类型

真正起作用的参数说明，永远绑定在可执行、可校验、可跳转的代码位置上 —— 不是 HTML 注释，而是函数上方的 JSDoc，或是 .d.ts 文件里的 interface。HTML 里的文字，顶多算便签。