### [HTML 类名与 id 命名：六条实用规范](https://www.huociguo.com/article/1505)

**Published:** 2026-09-30T04:57:05

**Author:** 米了

**Excerpt:** 类名小写加短横线、名字描述用途、id 留给唯一性场景、JS 钩子走 data-*。六条约定加正反对照与检查清单…

类名与 id 是 HTML 里改动最频繁、约定却最少的部分。名字一旦与样式或脚本耦合，改一处要动三处。下面六条约定按改动成本从低到高排列。

![屏幕上显示彩色代码片段，用于说明类名与 id 的命名写法](https://api.huociguo.com/wp-content/uploads/2026/09/a3.jpg)

命名规范的价值体现在改动时：样式、脚本、模板三处的耦合越低越好

## 六条约定

1.  类名全小写，单词之间用短横线。写 `user-avatar`，不写 `userAvatar` 或 `User_Avatar`。
2.  名字描述用途，不描述外观。`price-red` 换成 `price-discount`，改配色时不必动名字。
3.  id 在页面内保持唯一，留给确实需要唯一性的场合：锚点跳转、label 的 for 关联、表单控件联动、脚本挂载点。
4.  不用 class 充当 JS 钩子。交互标记写进 data-\* 属性，样式与行为各占一层。
5.  缩写只用公认写法。nav、btn、cta 可以留，自造缩写跳过。
6.  同一模块内的元素统一前缀。`card-title`、`card-body`，避免通用名字在组合时撞车。

## 正反对照

```html
<!-- 改动成本高的写法 -->
<div class="box RedBox" id="top" onclick="toggleMenu()"></div>

<!-- 按约定写 -->
<div class="site-nav" id="site-nav" data-toggle="menu"></div>
```

外观词不进类名；行为不写在 onclick 属性里，改用 data-\* 标记后统一监听。

## 钩子分离后的监听写法

```js
document.addEventListener('click', (event) => {
  const trigger = event.target.closest('[data-toggle]');
  if (!trigger) return;

  const targetId = trigger.dataset.target;
  document.getElementById(targetId)?.classList.toggle('is-open');
});
```

行为绑定到 data 属性，类名调整不再影响脚本。

## 检查清单

-   类名中不含大写字母与下划线；
-   名字描述用途而非视觉表现；
-   id 唯一，只在需要唯一性的场景出现；
-   JS 钩子写在 data-\* 属性上；
-   同一模块的元素前缀一致。

## 例外情况

组件作用域方案（CSS Modules、Vue scoped、CSS-in-JS）会生成局部类名，全局冲突风险下降，但 data-\* 钩子与命名可读性这两条约定仍然有效。

**Tags:** class选择器, data属性, id选择器, 代码可维护性, 命名规范

**Categories:** HTML5

---