Svelte 5 中 class 的动态设置：class 属性、clsx 对象数组语法与 class: 指令详解

本文围绕 Svelte 模板语法中的 class 动态设置展开，覆盖 class 属性（含 Svelte 5.16 起对对象/数组的 clsx 支持、Svelte 5.19 起的 ClassValue 类型）与 class: 指令两种用法，并结合 Svelte 官方仓库的编译器与运行时源码，剖析从模板到 DOM 的完整处理链路，帮助你在组件库开发、Tailwind 类名组合等场景中写出类型安全且可组合的 class 逻辑。

两种设置类名的方式

Svelte 提供两种给元素设置类名的方式：class 属性和 class: 指令。理解两者的差异与演进关系，是掌握本节内容的前提。

一、class 属性：从原始值到 clsx 组合

原始值（Primitive values）

最基础的用法是把 class 当作普通属性处理，表达式求值结果直接作为类名：

<div class={large ? 'large' : 'small'}>...</div>

这里有一个历史遗留的特殊行为需要注意：

注意：出于历史原因，falsy 值（如 false 和 NaN）会被字符串化（产生 class="false"），而 class={undefined}（或 null）会导致该属性被整体省略。在 Svelte 的未来版本中，所有 falsy 值都将导致 class 属性被省略。

这一行为在源码中有明确印证。运行时提供了一个对 clsx 的薄封装（见 shared/attributes.js）：

/**
 * Small wrapper around clsx to preserve Svelte's (weird) handling of falsy values.
 * TODO Svelte 6 revisit this, and likely turn all falsy values into the empty string (what clsx also does)
 * @param  {any} value
 */
export function clsx(value) {
	if (typeof value === 'object') {
		return _clsx(value);
	} else {
		return value ?? '';
	}
}

从源码注释可以看出：对象/数组走真正的 clsx 处理；非对象值则走 value ?? ''，也就是只有 null/undefined 才被当作空字符串处理，false、0、NaN 等 falsy 值会落入后续的字符串化路径——这正是文档中所描述的“历史遗留行为”。源码注释里的 TODO 也表明，Svelte 6 计划将所有 falsy 值统一处理为空字符串（即与 clsx 行为一致），升级版本时需要注意这一变化。

对象和数组：Svelte 5.16 引入的 clsx 支持

自 Svelte 5.16 起，class 可以是对象或数组，内部使用 clsx 的规则转换为字符串。

对象形式：truthy 的 key 会被加入类名：

<script>
	let { cool } = $props();
</script>

<!-- 当 `cool` 为 truthy 时结果 `class="cool"`，
     否则 `class="lame"` -->
<div class={{ cool, lame: !cool }}>...</div>

数组形式：truthy 的值被合并：

<!-- 当 `faded` 和 `large` 都为 truthy 时，结果
     `class="saturate-0 opacity-50 scale-200"` -->
<div class={[faded && 'saturate-0 opacity-50', large && 'scale-200']}>...</div>

无论使用数组还是对象形式，都可以用一个条件同时控制多个类名，这在配合 Tailwind 等原子化 CSS 方案时尤其有用。

嵌套组合：数组中可以包含数组和对象，clsx 会自动展平。典型场景是把组件自身的固定类名与外部传入的 class prop 合并（文档中的 Button.svelte 示例）：

<!--- file: Button.svelte --->
<script>
	let props = $props();
</script>

<button {...props} class={['cool-button', props.class]}>
	{@render props.children?.()}
</button>

此时组件的使用方享有同等的组合自由度，可以继续混合使用对象、数组与字符串：

<!--- file: App.svelte --->
<script>
	import Button from './Button.svelte';
	let useTailwind = $state(false);
</script>

<Button
	onclick={() => useTailwind = true}
	class={{ 'bg-blue-700 sm:w-1/2': useTailwind }}
>
	Accept the inevitability of Tailwind
</Button>

ClassValue 类型：Svelte 5.19 起的类型安全 class

自 Svelte 5.19 起，Svelte 还导出了 ClassValue 类型，它定义了元素 class 属性所接受的值类型。当你想在组件 props 中使用类型安全的类名时，这个类型非常有用：

<script lang="ts">
	import type { ClassValue } from 'svelte/elements';

	const props: { class: ClassValue } = $props();
</script>

<div class={['original', props.class]}>...</div>

该类型在仓库中的真实定义见 elements.d.ts：

export type ClassValue = string | import('clsx').ClassArray | import('clsx').ClassDictionary;

即 ClassValue 由字符串、clsx 的数组类型和字典类型三者联合而成，与运行时 clsx 的行为完全对齐。同一文件中，各 HTML 元素的 class 属性声明也统一标注为 class?: ClassValue | undefined | null（如 elements.d.ts），意味着你在 TypeScript 中传对象或数组给 class 时都能获得完整的类型检查。

二、class: 指令

在 Svelte 5.16 之前，class: 指令是按条件设置类名最便捷的方式：

<!-- 这两个写法等价 -->
<div class={{ cool, lame: !cool }}>...</div>
<div class:cool={cool} class:lame={!cool}>...</div>

与其他指令一样，当类名与变量名相同时可以使用简写：

<div class:cool class:lame={!cool}>...</div>

注意：除非你正在使用旧版本的 Svelte，否则建议避免使用 class: 指令，因为 class 属性功能更强大、更可组合。

三、源码纵览：class 从模板到 DOM 的处理链路

编译器阶段：build_set_class

在客户端编译产物中，class 属性与 class: 指令会被统一编译为一个 $.set_class 调用，核心逻辑位于 3-transform/client/visitors/shared/element.js 的 build_set_class 函数：

1. 属性值构建：先构建 class 属性的值，如果该属性被标记为 needs_clsx（即值为对象或数组），编译期会包一层 $.clsx(value) 调用，提前完成 clsx 转换；
2. 指令合并：如果存在 class: 指令，build_class_directives_object 会把所有指令构建为一个 { cool: true, lame: false } 形式的对象（即 next 参数），与 class 属性的值（value 参数）分开传递；
3. CSS 作用域哈希：若组件包含 <style>（element.metadata.scoped 为真），编译器会把组件的 CSS hash 一并传入，用于保证作用域类名始终附加；
4. 最终调用：生成 $.set_class(node_id, is_html, value, css_hash, prev, next)，其中 is_html 区分 HTML 命名空间（决定类名是否小写化）。

这说明属性形式和指令形式在底层是同一套合并机制：属性值提供“基础类名”，指令对象提供“开关类名”，两者在运行时统一处理。

运行时阶段：set_class 与 clsx 封装

运行时侧，属性分发入口 client/dom/elements/attributes.js 中的 set_attributes 对 class 做特殊处理：

if (next.class) {
	next.class = clsx(next.class);
} else if (css_hash || next[CLASS]) {
	next.class = null; /* force call to set_class() */
}

即先经过上文所述的 clsx 薄封装完成对象/数组到字符串的转换，随后在遍历属性时（attributes.js）检测到 key === 'class' 即调用 set_class(element, is_html, value, css_hash, prev, next)，传入上一轮的类名状态 prev?.[CLASS] 与指令对象 next[CLASS] 以实现增量更新。

而真正决定最终类名字符串的合并逻辑，正是 shared/attributes.js 中的 to_class(value, hash, directives) 函数，其算法可以概括为三步：

1. 基础类名：value == null ? '' : '' + value——注意这里的字符串化规则，解释了为何 false 会变成 "false" 而 undefined 是空字符串；
2. 附加 hash：如果组件有作用域样式，把 hash 追加到类名末尾（非空时以空格连接）；
3. 指令开关：遍历 directives 对象——truthy 的 key 追加进类名；falsy 的 key 则从当前类名中按“整词”匹配删除（通过空白字符边界判断，避免误删如 coolx 这类包含 cool 子串的类名），最终类名为空时返回 null（即移除该属性）。

服务端渲染路径同样复用了这套共享逻辑（见 internal/server/index.js 对 to_class/clsx 的引用），保证了客户端与 SSR 输出的 class 行为一致。

测试用例佐证

仓库中的 CSS 测试套件收录了 clsx 处理的典型样例，可用于验证编译器的裁剪与保留行为：

• tests/css/samples/clsx-can-prune：类名可静态推断时，编译器能对作用域样式做裁剪；
• tests/css/samples/clsx-cannot-prune-1、clsx-cannot-prune-2、clsx-cannot-prune-3：当类名来自运行时动态值、编译器无法静态确定时，相关样式不会被误裁剪。

这组测试恰好说明了 clsx 形式的 class 对 <style> 作用域裁剪的影响：静态可分析的类名（如对象中固定的 key）参与 CSS 选择器匹配，而完全动态的部分则保守保留全部样式。

小结与实践建议

场景	推荐写法
简单二选一类名	class={large ? 'large' : 'small'}
多条件/多类名组合（尤其 Tailwind）	class={[cond && 'a b', other && 'c']} 或 class={{ a: cond, b: other }}
组件透传 class	class={['fixed-name', props.class]}，props 声明为 ClassValue
旧版本 Svelte 或极简单开关	class:foo={cond} 或简写 class:foo

核心结论：

1. 优先使用 class 属性。自 Svelte 5.16 起它借助 clsx 支持字符串、数组、对象的任意嵌套组合，比 class: 指令更强大、更可组合；
2. 组件 props 用 ClassValue 标注（Svelte 5.19+），从 svelte/elements 导入即可获得类型安全的类名传递；
3. 注意 falsy 值的特殊字符串化行为（false → class="false"），这是为兼容历史版本而保留的语义，Svelte 源码中的 TODO 显示该行为在未来版本将改为统一省略（对齐 clsx）；
4. 动态类名会影响 CSS 裁剪。当 class 为动态对象/数组时，编译器对作用域样式的静态分析能力受限，可参考仓库 tests/css/samples/clsx-* 系列样例理解其边界。

相关源码与文档入口：模板语法 class 文档、相邻的 style 属性文档（style 与 class 共享同一套属性分发机制）、运行时合并逻辑 to_class 实现、编译入口 build_set_class。