WebStorm 粘贴代码 class 被转成 className 的解决方法

场景

在 vue 中使用 tsx 开发时，粘贴代码时，class 总是被转换为 className

解决方法

将如图所示的选择框关闭即可

设置路径是：

Settings → Editor → General → Smart Keys → JSX/TSX 分组下的 Convert attribute name to camelCase or className on paste

把它取消勾选，粘贴时就不再改写属性名了。同一个分组下还有一项 Automatically insert braces on Enter（在 JSX 属性里回车时自动补花括号），这个可以保留，它没什么副作用。

这个「智能」为什么在 Vue TSX 里是错的

WebStorm 的这个转换是为 React 设计的。React 的 JSX 有一套自己的属性命名规则，和 HTML 不完全一致：

// HTML 写法              React JSX 写法
// class="btn"       →    className="btn"
// for="input-id"    →    htmlFor="input-id"
// tabindex="0"      →    tabIndex="0"
// onclick="..."     →    onClick={...}

原因是 React 早期直接把属性映射到 DOM 元素的 property 上，而 DOM property 里 class 是保留字（JS 的关键字），所以用了 className；for 同理，用 htmlFor。连字符属性统一转成驼峰。

所以当你从网上复制一段 HTML 粘到 .jsx / .tsx 文件里，WebStorm 帮你把 class 改成 className、把 tabindex 改成 tabIndex，在 React 项目里确实省事。

问题是 Vue 的 JSX 不遵守这套规则。 Vue 3 的 JSX（通过 @vitejs/plugin-vue-jsx 或 @vue/babel-plugin-jsx 编译）保持了和 Vue 模板一致的属性命名，class 就是 class：

// Vue TSX：正确写法
export default defineComponent({
  render() {
    return (
      <div class="container" style={{ color: 'red' }}>
        <label for="name">名字</label>
        <input id="name" tabindex="0" />
      </div>
    );
  },
});

Vue 的 JSX 转换会把这些属性交给 Vue 的运行时处理，运行时按渲染的是原生元素还是组件分别决定往哪放。class 和 style 在 Vue 里还有特殊待遇——它们支持对象和数组语法，且在组件上会自动合并到根元素：

// 数组语法
<div class={['btn', isActive && 'btn-active']} />

// 对象语法
<div class={{ btn: true, 'btn-active': isActive }} />

在 Vue TSX 里写 className 的后果是：它会被当成一个普通的 HTML attribute 原样渲染出去，最终 DOM 上是 <div classname="btn">（HTML attribute 不区分大小写），CSS 选择器 .btn 匹配不上，样式完全不生效。而且不报错，只是没效果，排查起来很花时间。

TypeScript 类型能不能挡住

理论上能，Vue 提供的 JSX 类型定义里 class 是合法属性、className 不是。但实际上挡不住，因为 Vue 的 JSX 类型定义为了兼容性，对 HTML 元素的属性通常是宽松的（允许任意 data-* 和未知 attribute），className 会被当成一个合法的自定义属性放过去。

想让类型检查更严格，可以在 tsconfig.json 里确认 JSX 配置指向了 Vue：

{
  "compilerOptions": {
    "jsx": "preserve",
    "jsxImportSource": "vue"
  }
}

jsxImportSource: "vue" 这一行是关键，它让 TS 用 Vue 的 JSX 类型定义而不是 React 的。如果这行配错或者项目里同时装了 @types/react，TS 可能用 React 的类型来检查 Vue 的 JSX，那就会反过来——写 class 报错、写 className 通过，完全是反的。项目里如果不用 React，检查一下 @types/react 是不是被某个依赖间接装进来了：

pnpm why @types/react
# npm 用这个
npm ls @types/react

发现有的话在 tsconfig.json 里用 types 字段限制加载范围：

{
  "compilerOptions": {
    "types": ["vite/client"]
  }
}

Smart Keys 里其它值得调的项

既然到了这个页面，顺手说几个我会改的（都在 Settings → Editor → General → Smart Keys）：

Insert pair brackets/quotes — 输入 ( 自动补 )。默认开，保留。

Surround selection on typing quote or brace — 选中一段文字后按引号，用引号把它包起来而不是替换掉。这个很实用，默认开。

Add semicolon on Enter（JavaScript 分组下）— 回车时自动补分号。如果项目用 Prettier 且配了 "semi": false，这项要关掉，不然一直在跟 Prettier 打架。

Reformat on paste（在 Settings → Editor → Code Style 里，选项名是 Reformat on paste，可选 None / Indent Block / Indent Each Line / Reformat Block）— 默认是 Indent Block，只调整缩进不动其它格式。如果设成 Reformat Block，粘贴时会按 IDE 的 Code Style 全量格式化粘进来的代码，很容易和项目的 Prettier 规则冲突。建议保持 Indent Block 或设成 None。

HTML/CSS 分组下的 Add quotes for attribute value on typing '=' — 在 HTML 里输入 = 自动补引号。写模板时省事，保留。

粘贴后修复的补救手段

如果已经粘了一堆被改写的代码，不用手动一个个改。用全局替换的正则模式（Cmd + Shift + R）批量改回来，注意加上单词边界避免误伤：

查找（开启 Regex）：\bclassName=
替换：class=

查找：\bhtmlFor=
替换：for=

驼峰属性（tabIndex、maxLength、readOnly 这些）没法用一条正则统一处理，得逐个来。但这类属性在实际代码里出现频率不高，className 是最主要的。

替换前把 File mask 填成 *.tsx，别让替换波及到真的 React 代码或者别的文件类型。替换前先看一遍 Preview 里的匹配列表，确认数量合理再执行。

一个更根本的建议：Vue 里少用 JSX

说到底，在 Vue 项目里用 TSX 是个需要理由的选择。Vue 的 SFC 模板有几个 JSX 拿不到的优势：编译期能做更多优化（静态节点提升、patch flag 标记）、v-model 之类的指令写起来简洁、IDE 的模板类型检查（vue-tsc + Volar）现在已经很完善。

TSX 真正划算的场景是渲染逻辑高度动态的地方，比如：

表格的列渲染函数，需要根据配置动态决定渲染什么
递归组件（树形结构渲染）
高阶组件、渲染函数封装
需要把 JSX 片段当变量传递、存进数组的场景

这些用模板的 v-if / v-for 嵌套会很难读，JSX 因为就是普通 JS 表达式，反而清晰。

所以我的做法是：项目主体用 SFC 模板，只在上面这几类场景下局部用 TSX。这样既避开了本文这类工具链摩擦，也保留了 JSX 的灵活性。如果整个项目全用 TSX，那 className 这个坑早晚还会以别的形式再遇到一次（比如 v-model 在 JSX 里的写法、slot 的传递方式），成本不小。