Excalidraw样式管理规范：CSS-in-JS还是原生？

Excalidraw样式管理规范：原生CSS与CSS-in-JS的工程权衡

在构建像Excalidraw这样强调实时交互、轻量嵌入和视觉一致性的开源白板工具时，样式管理远不止是“怎么写类名”这么简单。它直接关系到应用能否在低端设备上流畅运行、是否支持灵活的主题定制、以及能否通过一个<script>标签就被快速集成进任何网页。

Excalidraw的界面看似极简——画布、工具栏、弹窗、实时协作光标——但背后隐藏着复杂的动态行为：用户拖拽元素时的临时高亮、AI建议框的渐现动画、深色模式切换时全局颜色的同步更新……这些都对样式的组织方式提出了严苛要求。而面对现代前端中“CSS-in-JS vs 原生CSS”的经典抉择，我们需要从性能、体积、可维护性和实际场景出发，做出真正符合产品定位的技术决策。

为什么不能只看“开发体验”？

很多人选择CSS-in-JS，是因为它带来了极佳的开发体验：样式和组件写在一起，支持TypeScript类型推断，主题变量可以直接用JS表达式注入，热重载还能精准定位到某一行样式。听起来很完美，不是吗？

但在Excalidraw这样的项目里，开发便利性必须为运行时性能让路。

设想这样一个场景：一位用户正在使用老旧笔记本电脑参与远程头脑风暴，屏幕上同时有5个人的光标移动、图形不断被创建和删除。如果每个光标的样式（颜色、边框、阴影）都是由Emotion或Styled-components在运行时动态生成的，那么每一次鼠标移动都会触发一次样式计算、类名哈希、DOM插入甚至重排。这不仅增加了主线程负担，还可能导致内存泄漏——尤其是当旧的<style>标签未被及时清理时。

更现实的问题是包体积。Emotion的核心库压缩后仍有约12KB（gzipped），这对于一个目标是“零配置嵌入”的工具来说，是一笔昂贵的开销。相比之下，纯原生CSS + CSS Variables 的方案几乎不增加JavaScript Bundle大小，仅需几行额外的CSS规则即可实现同等主题能力。

所以问题来了：我们真的需要在所有地方都用CSS-in-JS来换取那一点编码上的优雅吗？还是说，我们应该把这种“重型武器”留给真正需要它的战场？

原生CSS：被低估的高性能选手

很多人以为“原生CSS”就是十年前那种全局污染、命名混乱的状态。但今天的原生CSS早已今非昔比，尤其是在结合现代构建工具和CSS Modules之后。

以Excalidraw中的工具栏为例：

/* styles/toolbar.module.css */ .toolbar { display: flex; gap: 8px; padding: 12px; background-color: var(--color-bg); border-bottom: 1px solid var(--color-border); } .button { padding: 6px 12px; border: 1px dashed var(--color-accent); border-radius: 4px; font-size: 14px; cursor: pointer; }

import styles from "./styles/toolbar.module.css"; function Toolbar() { return ( <div className={styles.toolbar}> <button className={styles.button}>Draw</button> <button className={styles.button}>Text</button> </div> ); }

这段代码看起来平淡无奇，但它具备几个关键优势：

• 零运行时开销：样式在构建阶段就已确定，浏览器直接解析CSSOM。
• 作用域隔离：Webpack或Vite会自动将.button编译成类似toolbar_button__abc123的唯一类名，彻底避免冲突。
• 主题友好：通过CSS自定义属性（如var(--color-accent)），可以在不重新编译样式的情况下动态更换主题。
• 调试直观：DevTools中可以直接看到类名对应的真实样式，无需展开复杂的JS对象。

更重要的是，这类静态UI组件在整个生命周期内很少发生结构性变化，完全没必要引入运行时样式引擎来“动态生成”它们的外观。

CSS-in-JS的价值在哪里？它适合Excalidraw吗？

当然，CSS-in-JS并非一无是处。它的真正价值体现在那些高度依赖props、state或上下文环境的组件上。

比如Excalidraw中可能出现的一个功能：AI驱动的智能命令输入框。当用户输入“画一个红色圆形”，系统会在下方展示预览建议，并用微妙的动画引导注意力。

import { css, useTheme } from "@emotion/react"; const suggestionStyle = (isActive: boolean) => css` padding: 8px 12px; background-color: ${useTheme().colors.suggestionBg}; border-left: 3px solid ${useTheme().colors.primary}; opacity: ${isActive ? 1 : 0.6}; transform: translateX(${isActive ? 0 : -4}px); transition: all 0.2s ease; &:hover { background-color: ${useTheme().colors.hoverBg}; } `; function AISuggestion({ active }: { active: boolean }) { return <div css={suggestionStyle(active)}>Create red circle</div>; }

在这里，css模板字面量可以根据active状态动态调整透明度和位移，同时从主题上下文中读取颜色值。这种灵活性是传统CSS难以实现的——你总不能为了每种颜色组合都预写一套类吧？

但即便如此，我们也应谨慎评估其代价：

• 是否每次重渲染都会重新计算样式？Emotion会对相同内容缓存类名，但仍存在函数调用开销。
• 是否会导致样式膨胀？长期运行下可能积累大量未使用的<style>节点。
• 是否影响SSR？虽然Emotion支持服务端提取，但需要额外配置。

因此，在Excalidraw中，这类技术更适合用于局部、低频、高交互复杂度的功能模块，而非整个UI体系的基础层。

主题系统的终极解法：CSS Variables + JS动态注入

Excalidraw支持深色/浅色模式切换，未来还可能开放品牌定制API。这就要求主题系统既能快速响应，又不能牺牲性能。

一个常见的误区是：为了“更好的主题支持”，全面转向CSS-in-JS。但实际上，原生CSS配合CSS Variables已经足够强大。

:root { --color-bg: #fff; --color-text: #000; --color-border: #ddd; --color-accent: #007acc; --color-primary: #007acc; --color-hover-bg: rgba(0, 122, 204, 0.1); } [data-theme="dark"] { --color-bg: #1e1e1e; --color-text: #f0f0f0; --color-border: #444; --color-accent: #00aaff; --color-hover-bg: rgba(0, 170, 255, 0.15); }

然后通过简单的JS操作即可实现运行时切换：

document.documentElement.setAttribute("data-theme", "dark"); // 或者动态修改单个变量 document.documentElement.style.setProperty("--color-primary", "#ff5722");

这种方式的优势非常明显：

• 无需重新渲染组件树：只要DOM引用了这些变量，样式会自动更新。
• 跨框架兼容：即使将来部分功能迁移到Vue或Svelte，也能无缝继承主题。
• 极致轻量：没有第三方依赖，仅靠浏览器原生机制完成。

更重要的是，它允许我们将“设计令牌”（design tokens）集中管理，形成统一的设计系统。企业客户可以通过注入自己的CSS变量集，轻松实现品牌化嵌入，而无需Fork代码库或引入复杂的构建流程。

架构层面的思考：分层策略才是正解

回到Excalidraw的整体架构：

+---------------------+ | App Root | +----------+----------+ | +-------v--------+ +------------------+ | Canvas Layer |<--->| AI Command Input | +------------------+ +------------------+ | +-------v--------+ | Toolbar/UI | +------------------+ | +-------v--------+ | Theme Provider | +------------------+

我们可以清晰地划分出不同层级的样式需求：

• Canvas Layer：高频更新、大量SVG元素、对性能极度敏感 → 必须使用原生CSS类切换，禁用任何运行时样式生成。
• Toolbar/UI：结构稳定、交互明确 → 使用CSS Modules + CSS Variables，兼顾可维护性与性能。
• AI Command Input：动态内容、复杂动画、状态驱动样式 → 可有限采用CSS-in-JS（如Emotion的css函数），提升开发效率。
• Theme Provider：全局控制 → 统一使用CSS Variables，通过JS动态注入实现运行时变更。

这种分层混合策略，既避免了“一刀切”带来的资源浪费，又保留了在关键路径上使用先进技术的空间。

工程实践建议：如何落地这套规范？

在实际开发中，我们可以制定如下指导原则：

✅ 推荐做法

• 默认使用原生CSS Modules作为主要样式方案，文件命名遵循[component].module.css。
• 设计系统基于CSS Variables，建立统一的tokens.css文件，包含颜色、间距、圆角等基础设计令牌。
• 主题切换通过data-theme属性控制，避免频繁修改内联样式。
• 高频更新组件禁止使用CSS-in-JS，改用预定义类名切换（如is-active,is-dragging）。
• 若必须使用CSS-in-JS，优先选用轻量方案，例如：
• @vanilla-extract/css：编译时生成CSS，零运行时。
• Emotion的css函数配合styled按需导入，避免全量引入。

❌ 避免事项

• 不要在画布相关组件中使用styled.div封装每一个小元素。
• 不要为每个颜色变体都创建新的React组件。
• 不要滥用:hover、@media等在JS中难以优化的规则。
• 不要在服务端渲染环境中忽略样式提取步骤（如未调用extractCritical）。

🔍 调试技巧

• 启用Emotion的source map支持，确保DevTools能显示原始样式位置。
• 使用Chrome Performance面板监控Recalculate Style耗时，识别潜在瓶颈。
• 定期检查DOM中是否存在大量冗余的<style>标签（常见于未正确卸载的组件）。

结语：技术选型的本质是取舍

Excalidraw的成功，很大程度上源于它对“简洁”的坚持——不仅是视觉上的手绘风格，更是架构上的克制与专注。在这种背景下，样式管理的选择不应追求时髦或理论上的完美，而应回归本质：我们是在打造一个可以嵌入任何网页的轻量级协作工具，而不是一个炫技的前端样板工程。

因此，最终的答案很明确：

以原生CSS为主干，辅以CSS Variables实现主题系统；仅在确有必要且性能可控的局部场景下，谨慎引入CSS-in-JS作为增强手段。

这不是对新技术的排斥，而是对场景的尊重。真正的工程智慧，往往体现在知道何时该“少用”而非“多用”。