JS中className字符串操作与classList API的区别及选择

作者：页面旅途

时间：2026-11-02

深入对比JavaScript中操作元素类名的两种核心方式：className字符串操作与classList API。解析两者的底层数据结构、常见陷阱、方法差异、性能表现与技术选型建议。

文章目录

在编写前端交互时，无论是给弹窗添加展开动画、为选项卡切换高亮，还是为按钮标记禁用状态，修改 DOM 元素的类名都是最基础且高频的操作。在原生 JavaScript 中，开发者通常会面临两种选择：直接赋值或拼接 element.className 字符串，或者使用现代浏览器提供的 element.classList API。结论先行：除了整体重置类名或在模版引擎中全量输出类名字符串之外，所有的增量添加、删除、切换和状态判断，均应首选 classList。

图 1：className 与 classList 操作形态概览

一、底层数据模型与工作原理

要理解两者的本质差异，首先需要观察它们在浏览器 DOM 树中的表示形式。HTML 元素上的 class 属性在规范中本质是一个以空格分隔词元（tokens）的原始文本。但在 JavaScript 对象模型中，宿主环境对这两个属性的建模方式截然不同。

className 是 DOM Level 2 时代就存在的标准属性，对应 IDL 类型为 DOMString。它直接暴露出元素 class 特征的纯文本映射。当你读取 el.className 时，浏览器将当前元素的所有类名拼成一整个长字符串返回；当你写入 el.className = "..." 时，浏览器直接将原属性缓冲区整串覆盖，并触发全量分词与样式重新匹配。

而 classList 引入于 HTML5 规范，返回的是一个实现了 DOMTokenList 接口的伪数组对象。该对象与底层 DOM 属性是实时绑定的（live collection），但它在内存中以结构化词元列表（Token Set）的形式存在，并封装了诸如 add、remove、toggle、contains 和 replace 等针对独立类名的原子微操作。每次调用方法，底层引擎只对目标 token 进行精确检索和增删，并自动处理空白符同步。

图 2：DOM 节点下 className 与 classList 底层结构与同步模型

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

// 1. className 返回单纯的字符串
console.log(typeof btn.className); // "string"
console.log(btn.className);        // "btn primary active"

// 2. classList 返回 DOMTokenList 集合
console.log(btn.classList);        // DOMTokenList(3) ["btn", "primary", "active"]
console.log(btn.classList.length); // 3
console.log(btn.classList[0]);     // "btn"

二、className 字符串操作的常见陷阱与维护痛点

在 classList 尚未普及前，开发者操作单个类名必须依靠字符串的拼接（concatenation）和正则表达式替换（regex replacement）。由于类名由空格分割，一旦操作者稍有疏忽，就会引发隐蔽而难以排查的 UI 异常。

图 3：className 字符串手动拼接与正则替换常见缺陷分析

1. 子串误伤与词边界错误

假设一个元素包含 "btn btn-primary active" 三个类名，如果你希望移除其中的基准类 "btn"，若简单使用 el.className = el.className.replace("btn", "")，字符串匹配只会命中首个出现的子串片段，甚至误伤复合类名。例如替换 "btn" 时，若原串为 "btn-primary btn"，第一个 "btn" 就会被抹掉，导致原有的 "btn-primary" 变成了损坏的 "-primary"，直接使主按钮的 CSS 样式全部失效。

2. 重复追加与类名臃肿

很多初学者在需要激活状态时习惯使用 el.className += " active"。然而，如果这一逻辑在滚动监听、输入校验或轮询回调等高频事件中多次触发，且没有提前检查，类名串就会不断膨胀为 "btn active active active"。虽然 CSS 权重对重复类名生效一次，但这会无谓地增加 DOM 字符串长度，加剧内存与选择器解析负担。

3. 繁琐冗长的正则开销

为了安全地使用 className 移除某个类名，开发者不得不编写繁琐的边界正则：

// 手动安全移除一个类名的传统写法
function removeClassLegacy(element, classNameToRemove) {
  const reg = new RegExp('(^|\s+)' + classNameToRemove + '(\s+|$)', 'g');
  element.className = element.className.replace(reg, ' ').trim();
}

这种写法不仅可读性极差，每次执行都需要动态创建正则表达式对象，并且必须额外调用 trim() 消除首尾遗留的空格，代码非常脆弱。

三、classList API 的原子方法流水线

classList API 彻底终结了手动解析类名字符串的时代。浏览器将类名管理提升到了引擎原生级别，每个方法都在底层 C++ 中直接维护 token 数组，具备高度的健壮性和自洽性。

图 4：classList API 核心操作流水线与原子处理能力

1. `add(...tokens)`：支持多类名追加与内置幂等性

classList.add() 可以一次性接收一个或多个类名参数。最关键的是，它具备原生去重机制（幂等性）。如果目标类名已在元素上存在，引擎会自动忽略，永远不会产生重复类名：

const box = document.querySelector('.box');

// 一次性添加多个类名
box.classList.add('is-visible', 'theme-dark');

// 即使重复添加多次，依然只保留一份
box.classList.add('is-visible');
console.log(box.className); // "box is-visible theme-dark"

2. `remove(...tokens)`：安全剔除与静默容错

使用 classList.remove() 剔除类名时，引擎只按完整 token 匹配，杜绝任何子串误伤。如果被移除的类名根本不存在，方法会静默忽略而不抛出任何错误，你再也不需要提前写 if (hasCls) 判断了。

// 安全移除，不存在也不报错
box.classList.remove('is-visible', 'loading');

3. `toggle(token, force)`：智能翻转与条件开关

toggle 是 classList 中最具表现力的方法。如果类名存在则移除并返回 false；如果不存在则添加并返回 true。更强大的是它的第二可选参数 force（布尔值），它能以一行代码替代传统冗长的三元运算或 if-else 结构：

const modal = document.querySelector('#modal');
const shouldOpen = (data.status === 'success');

// 传统 className 写法需要分支判断
// if (shouldOpen) el.className += " open"; else ...

// 使用 classList toggle 第二参数：force 为 true 时添加，false 时移除
modal.classList.toggle('is-open', shouldOpen);

4. `contains(token)`：高保真状态研判

判断元素是否带有某类名，classList.contains() 能够以 $O(N)$ 极速精确检索，返回标准布尔值。相比旧式 el.className.indexOf('active') !== -1 可能会误判 active-tab 的致命缺陷，contains 能百分之百保证词元边界安全。

if (modal.classList.contains('is-open')) {
  console.log('弹窗当前正处于展开状态');
}

5. `replace(oldToken, newToken)`：原位无缝替换

在进行主题切换、状态机流转等场景下，我们需要将 theme-light 换成 theme-dark。传统方式必须先 remove 再 add，容易引发中间过渡状态。而 replace() 是原子操作：若旧类名存在，原位就地替换为新类名并返回 true；若旧类名不存在则不做任何变更并返回 false。

const isSwapped = box.classList.replace('theme-light', 'theme-dark');
console.log(isSwapped); // 成功则为 true

四、全维度特性对比与性能分析

为了给实际工程落地提供清晰的技术参照，我们将 className 字符串操作与 classList API 在功能规范、编码安全性及兼容性等维度进行横向对比：

对比维度	className 字符串操作	classList API
数据类型	`DOMString`（基础字符串类型）	`DOMTokenList`（集合对象，伪数组）
增量添加	需手动 `+= " cls"`，易漏空格	`.add(cls1, cls2)`，内置幂等防重复
精确删除	需复杂正则表达式，易误伤同前缀类名	`.remove(cls1, cls2)`，安全词元剔除
状态切换	需自行写 `if-else` 分支逻辑	`.toggle(cls, force)` 一行完成条件开关
存在性判断	`indexOf` 易误伤，必须构造正则	`.contains(cls)` 严格边界精确判断
全量重置	极简：`el.className = ""`	无法直接赋值，需循环或重新构造
性能与开销	频繁正则构造与拼接引发多次重排与字符串分配	浏览器内核 C++ 原生维护，免去脚本层字符串处理
SVG 元素兼容	旧版规范中 SVG 元素 className 为 SVGAnimatedString	现代规范中所有 SVGElement 原生支持 classList

关于 SVG 元素的特别说明： 在过去的开发中，如果对 <svg> 标签直接读取 svgElement.className，返回的不是字符串，而是一个 SVGAnimatedString 对象，导致直接给 svg.className = "icon" 产生意外甚至报错。而 modern 浏览器中的 svgElement.classList 完全遵循标准规范，像普通 HTML 元素一样提供一致的 API 体验。

五、开发中的选型策略与落地指南

虽然 classList 在灵活性与安全性上全面领先，但在特定的业务架构中，className 依然保有其不可替代的场景。结合图 5 的决策流，我们可以归纳出清晰明确的选型原则：

图 5：业务开发中操作类名的技术选型决策树

何时坚决使用 classList？

动态状态管理：抽屉开关、模态框弹出、步骤条切换、列表选中高亮等。这些场景的核心诉求是“保留原有其它类名的前提下，对某一个状态类进行开关”，必须使用 classList.add/remove/toggle。
多重状态组合判定：需要根据当前 UI 状态分支触发业务逻辑时，必须使用 classList.contains() 避免子串陷阱。
多主题或形态互斥置换：如深浅色主题切换、网格视图与列表视图切换，使用 classList.replace('mode-grid', 'mode-list')。

何时依然可以使用 className？

彻底清空或重置元素类名：如果你需要把一个动态污染过的元素恢复到没有任何样式的干净状态，el.className = '' 拥有最直观的语法和最高的执行效率。
初始化赋予全量预设样式：在动态创建 DOM（如 document.createElement('div')）时，一次性赋予一组完整类名：el.className = 'card shadow-sm p-4 text-center'，比连续调用五次 add 更清晰明了。
无运行时依赖的模板构建：在纯字符串拼装 HTML 或轻量服务端渲染（SSR）中，直接组装 class="..." 是唯一的自然形态。

综上所述，className 适用于“宏观、全量、重置”的粗粒度赋值，而 classList 则专精于“微观、增量、条件”的细粒度操作。在现代标准 Web 应用中，将二者各司其职，能从根源上杜绝类名拼接带来的边界隐患，让 DOM 状态控制代码更加优雅稳健。