JS使用classList API添加、删除和切换class类名

作者:白露时间:2026-11-20 08:49:19浏览:303

详细讲解在 JavaScript 中使用 Element.classList API 对 HTML 元素的 class 类名进行添加(add)、删除(remove)、切换(toggle)、检测(contains)及替换(replace)的完整用法与避坑指南。

分类:JavaScript DOM 编程 标准:DOM Parsing and Serialization / WHATWG DOM 适用环境:现代主流浏览器 / Node.js (JSDOM)
JS使用classList API添加、删除和切换class类名
图 0:Element.classList 核心操作方法全景与特性一览

在前端交互开发中,通过 JavaScript 改变 HTML 元素的 CSS 类名是最基础也是最高频的操作。现代浏览器提供了原生的 Element.classList 接口,专门用于对元素的 class 属性进行结构化管理。借助该 API 提供的 add()、remove() 和 toggle() 等方法,开发者可以直接对类名集合执行增、删、改、查,无需再进行复杂的字符串解析与拼接,大幅提升了代码的可读性与健壮性。

一、认识 Element.classList 与底层机制

在早期的 DOM 操作中,读取和修改类名通常依赖 element.className 属性。由于 className 返回的是一个单纯的字符串(DOMString),当一个元素拥有多个以空格隔开的类名时,任何增加、移除操作都必须依靠字符串拼接(如 += " active")或正则表达式替换。这种做法容易引发空格冗余、误删相似类名(例如替换 "btn" 时误将 "btn-primary" 破坏)以及重复添加相同类名等问题。

为了解决字符串操作的弊端,W3C 与 WHATWG DOM 规范引入了 Element.classList。它是一个只读属性,返回一个 DOMTokenList 接口的实例。虽然 classList 本身不可被重新赋值(即执行 el.classList = 'box' 是无效的),但其内部维护着一个与元素 class 属性实时双向同步的标记集合(Token Set),并暴露了一系列便捷的方法来修改这个集合。

JS使用classList API添加、删除和切换class类名
图 1:传统 className 字符串模式与现代 classList DOMTokenList 机制对比

DOMTokenList 具有类数组(Array-like)的特征,支持通过索引访问单个类名,拥有 length 属性,并且原生支持 forEach 迭代。同时,它具备集合(Set)的去重特性,在处理类名时天然避免了重复项的产生。

二、使用 add() 方法添加类名

element.classList.add() 用于向指定元素的 class 属性中追加一个或多个类名。它的行为非常直观且具有幂等性:如果待添加的类名在元素中已经存在,add() 会静默忽略,不会产生多余的副本,也不会抛出任何错误。

1. 单个类名的添加

最常规的用法是传入单个类名字符串:

// 获取目标 DOM 节点
const cardElement = document.querySelector('.card');

// 向 card 元素添加 'highlight' 类名
cardElement.classList.add('highlight');

// 结果验证:
// 原 DOM:<div class="card"></div>
// 变更后:<div class="card highlight"></div>

2. 批量添加多个类名

在实际工程中,一个状态变更可能需要同时应用多个类名(例如样式基类和变体类)。add() 方法支持接收多个逗号分隔的参数,一次性完成批量追加:

const buttonElement = document.querySelector('#submit-btn');

// 批量添加三个独立类名
buttonElement.classList.add('btn-loading', 'is-disabled', 'shadow-sm');

// 配合 ES6 扩展运算符(Spread Operator)将数组类名解构传入:
const stateClasses = ['visible', 'fade-in', 'animated'];
buttonElement.classList.add(...stateClasses);

关键规则提醒:禁止直接传入带有空格的复合字符串,例如 buttonElement.classList.add('btn active')。因为 classList 把每个参数严格视为单个 Token,包含空格的字符串会直接触发 DOMException: Failed to execute 'add' on 'DOMTokenList': The token provided contains HTML space characters 错误。添加多个类必须使用多个参数或展开运算符。

三、使用 remove() 方法删除类名

element.classList.remove() 用于从元素中移出一个或多个指定的类名。该方法同样具备极强的防御性:如果目标元素原本就不包含该类名,调用 remove() 不会发生任何异常,代码能够平稳继续执行。

1. 单个与批量删除

与 add() 类似,remove() 可以接受一个或多个类名参数:

const modal = document.querySelector('.modal-dialog');

// 删除单个类名,隐藏弹窗
modal.classList.remove('is-open');

// 批量移除多个修饰类
modal.classList.remove('modal-large', 'has-backdrop', 'theme-dark');

// 尝试删除一个原本不存在的类名:安全静默跳过,无副作用
modal.classList.remove('non-existent-class');

在清空特定分类的样式时,可以利用解构方式批量移除。相比以往使用正则表达式或字符串 replace,remove() 完全排除了子字符串误匹配的隐患。

四、使用 toggle() 方法智能切换类名

在用户交互中,诸如下拉菜单展开/收起、侧边栏显示/隐藏、开关按钮启用/禁用等行为,本质上都是在“存在”与“不存在”两个状态之间来回轮换。在过去,这往往需要先调用 if (el.className.indexOf(...) > -1) 进行显式条件分支判断,而 classList.toggle() 则将这一逻辑封装为了单一原子操作。

JS使用classList API添加、删除和切换class类名
图 2:classList.toggle() 方法的状态分支与 force 强制参数判定逻辑

1. 基础单参数用法与返回值

当只传入一个类名参数时,toggle() 会检查元素是否存在该类名:如果已存在,则将其删除并返回 false;如果不存在,则将其添加并返回 true。这个布尔返回值可直接用于后续逻辑分支:

const drawer = document.querySelector('#sidebar-drawer');
const toggleButton = document.querySelector('#drawer-toggle-btn');

toggleButton.addEventListener('click', () => {
  // 切换 'drawer-expanded' 类
  const isExpanded = drawer.classList.toggle('drawer-expanded');

  // 根据返回值同步修改无障碍属性 aria-expanded
  toggleButton.setAttribute('aria-expanded', String(isExpanded));
  console.log(`抽屉菜单当前展开状态:${isExpanded}`);
});

2. 双参数用法:force 强制模式

toggle() 的第二个可选参数 force 是一个布尔值(或可转换为布尔值的表达式)。当提供了 force 参数时,方法不再进行取反,而是根据 force 的真假执行确定性操作:

  • 若 force === true:强制将该类名添加到元素中(若已存在则保持存在),返回 true。
  • 若 force === false:强制将该类名从元素中移除(若已不存在则保持不存在),返回 false。
const notification = document.querySelector('#status-pill');

// 假设我们根据数据条数判断是否显示警告样式
function updateStatus(hasError) {
  // 等价于:if (hasError) add('alert') else remove('alert')
  // 一行代码优雅解决条件同步:
  notification.classList.toggle('status-error', hasError);
}

updateStatus(true);  // notification 获得 'status-error' 类
updateStatus(false); // notification 被移除 'status-error' 类

五、辅助 API:contains() 检查与 replace() 替换

除了添加、删除和切换三项核心操作外,classList 还配备了两个非常实用的辅助方法,构成了完整的类名生命周期管理能力。

JS使用classList API添加、删除和切换class类名
图 3:classList 常用方法(add / remove / toggle / contains / replace)功能特性对照表

1. element.classList.contains(token)

该方法接收一个类名字符串,返回一个布尔值,用于判定当前元素是否包含该类名。与 String.prototype.includes 不同,contains() 执行的是完整的单词匹配,绝不会发生子串混淆:

const alertBox = document.querySelector('.alert');

// 正确识别完整独立类名
if (alertBox.classList.contains('alert-warning')) {
  console.log('当前警告级别:中度警告');
} else {
  console.log('未设置警告级别');
}

2. element.classList.replace(oldToken, newToken)

用于将元素上的一个既有类名原子化替换为新的类名。如果 oldToken 存在,则完成替换并返回 true;若 oldToken 根本不存在,则放弃操作并返回 false:

const themeContainer = document.querySelector('#app-theme');

// 将 'theme-light' 替换为 'theme-dark'
const replaced = themeContainer.classList.replace('theme-light', 'theme-dark');

if (!replaced) {
  // 若未找到旧类名,可作为降级策略补充添加
  themeContainer.classList.add('theme-dark');
}

六、实战操作全流程与高频易错点总结

在规范的生产项目中运用 classList,应当遵循严谨的调用顺序与容错排查规则。下图汇总了从获取节点到样式响应的完整生命周期,并针对常见编码陷阱给出了防护建议:

JS使用classList API添加、删除和切换class类名
图 4:classList 实战操作流程规范与易错点排查全景图

常见问题与排查指南:

  1. 节点为 null 导致的运行时中断: 使用 document.querySelector 时,若选择器未匹配到任何 DOM 节点,将返回 null。直接调用 null.classList 会导致脚本中断。建议使用可选链操作符(Optional Chaining)进行安全访问:el?.classList.add('active')。
  2. Token 包含非法字符(特别是空格): 这是初学者最容易触发的错误。classList 各方法传入的字符串代表单个单词,绝不能包含空格、制表符等字符。若需处理动态传入的类名字符串,请先使用 str.trim().split(/\s+/) 拆分为数组后解构传入。
  3. 传入空字符串 "": 调用 el.classList.add("") 或 el.classList.contains("") 同样会抛出语法错误异常。动态计算类名时,务必先过滤掉假值(falsy values)。
  4. 只读属性不可直接赋值: el.classList = 'class-a' 在非严格模式下会被静默忽略,在严格模式下抛出 TypeError。若需一次性清除所有类或重置类名,应操作 el.className = 'class-a' 或 el.setAttribute('class', 'class-a')。

七、总结

Element.classList API 作为现代前端操作 DOM 类名的核心规范,以面向 Token 集合的方式取代了脆弱的字符串拼接。通过熟练组合 add()、remove()、toggle() 以及 contains() 和 replace(),开发者可以用简练、语义明确且不易出错的代码驱动界面样式的变换。在编写代码时,牢记参数禁止空格、注意空值检查,即可充分享受该 API 带来的安全与高效。

作者最新文章
相关文章
更多