Svelte Styling Reference (Svelte 5)

本技能覆盖 Svelte 组件的样式系统，包括作用域样式、全局样式、CSS 自定义属性、class 处理、style: 指令、嵌套 <style> 和 scoped keyframes。

When to use this skill

当用户需要编写 Svelte 组件的样式、处理样式隔离、CSS 变量传递、style: 指令、动画 keyframes、或理解 Svelte 编译器如何处理样式时使用本技能。

Critical: Scoped Styles

<style> 块中的 CSS 默认作用域化——仅影响当前组件内的元素：

<style>
  p { color: burlywood; }
  .container { padding: 1em; }
</style>

编译时 Svelte 为作用域内的选择器自动添加哈希类（如 svelte-123xyz）。

特异性（Specificity）

Scoped 选择器额外增加 +0-1-0 特异性（来自作用域类），可能覆盖全局相同选择器：

/* 全局 */
p { color: blue; }

/* 组件内（scoped，优先级更高） */
p { color: red; }

:where() 包装

当同一作用域类需要出现在选择器中多次时，只有第一次实际贡献特异性；后续出现被包裹在 :where(.svelte-xyz123) 中，贡献零特异性。这避免了深层选择器（如 .a .b .c）的特异性爆炸。

Scoped Keyframes

@keyframes 名称也会自动作用域化，同一组件内 animation: name 引用会被重写以匹配：

<style>
  @keyframes bounce {
    0%, 100% { transform: translateY(0); }
    50% { transform: translateY(-20px); }
  }
  .animated { animation: bounce 1s; }  /* 编译为 bounce-svelte-abc123 */
</style>

何时样式不生效

• 元素由子组件渲染（scoped 不会穿透组件边界）
• {@html} 内容（没有作用域类）
• 类名是动态/程序化添加的，且选择器未使用 :global(...)
• 选择器不匹配模板中实际存在的元素
• 在 style="" 属性或 JS 中使用 scoped keyframe 名称（用 -global- 解决）

Critical: Global Styles

:global(...) 单选择器

<style>
  :global(body) { margin: 0; }          /* 全局 body */
  div :global(strong) { color: goldenrod; } /* 嵌套全局 */
  p:global(.big.red) { font-weight: bold; } /* 带条件 */
</style>

• :global(selector) — 整个选择器退出作用域。
• parent :global(child) — 父级保留作用域，子级不保留（最常用形式）。
• tag:global(.class.class) — 元素仍带作用域类，但触发类不需出现在模板中（适用于第三方库运行时添加的类）。

:global { ... } 块（多选择器）

<style>
  :global {
    p { margin: 1em; }
    .theme-dark { --bg: #111; }
  }

  .parent :global {
    .foo .bar { color: red; }  /* .parent 是 scoped，.foo .bar 是全局 */
  }
</style>

:global 块中的选择器按原样发出，不降低特异性——只有 .foo .bar 自身的特异性。

全局 Keyframes

在 keyframe 名称前加 -global-：

<style>
  @keyframes -global-my-animation-name {
    0% { opacity: 0; }
    100% { opacity: 1; }
  }
</style>

编译后 -global- 前缀被移除，成为 my-animation-name，可被其他组件、<style> 属性、JS 引用。

编译器只重写同一 <style> 块内的 animation 引用。style="..." 属性、{@html} 内容、JS、style:color 指令中的 keyframe 名称不会被重写——这些地方需要 -global- 名称。

Critical: CSS Custom Properties

传入自定义属性

<Slider bind:value --track-color="black" --thumb-color="rgb(255 0 0)" />

编译时 Svelte 包裹一层 svelte-css-wrapper（或 SVG 中的 <g>）承载内联 style：

<svelte-css-wrapper style="display: contents; --track-color: black; --thumb-color: rgb(255 0 0)">
  <Slider ... />
</svelte-css-wrapper>

包装元素有 display: contents 但仍会出现在 > 子选择器匹配中——必要时改用后代选择器。

组件内读取

<style>
  .track { background: var(--track-color, #aaa); }
  .thumb { background: var(--thumb-color, blue); }
</style>

CSS 自定义属性可级联

无需直接传值，只要父元素定义了 CSS 变量，子组件即可读取：

/* 全局 */
:root { --primary: #ff3e00; }

Critical: style: Directive

style: 指令是 style="..." 属性的简写，每个属性一个指令。

<div style:color="red">A</div>           <!-- 字符串字面量 -->
<div style:color={myColor}>B</div>        <!-- 表达式 -->
<div style:color>C</div>                  <!-- 简写：变量名与属性名相同 -->

多个样式

<div style:color style:width="12rem" style:--columns={columns}>...</div>

CSS 自定义属性

style:--var 设置 CSS 变量：

<div style:--columns={columns} style:--gap="1rem">...</div>

!important 修饰符

style:color|important="red" → 编译为 style="color: red !important"。

优先级

style: 指令胜出于同元素上的 style="" 属性——即使 style="" 中使用了 !important：

<div style:color="red" style="color: blue !important">This will be red</div>

数值单位

数字不会自动加单位：

<div style:width={10}>...</div>          <!-- 错误：width: 10 -->
<div style:width="{10}px">...</div>      <!-- 正确 -->

Critical: class Attribute

Svelte 5.16+ 的 class 属性支持对象和数组（用 clsx 处理）。

对象形式

<div class={{ cool: isCool, large: isLarge }}>...</div>

数组形式

<div class={[faded && 'saturate-0 opacity-50', large && 'scale-200']}>...</div>

混合

<Button class={['btn', props.class]} />

类型安全

<script lang="ts">
  import type { ClassValue } from 'svelte/elements';
  let { class: cls }: { class: ClassValue } = $props();
</script>
<div class={['original', cls]}>...</div>

5.16 之前的 falsy 行为

历史原因：class={false} 会被序列化为 class="false"，但 class={undefined} / class={null} 会让属性消失。Svelte 未来版本会让所有 falsy 值省略 class。

Critical: class: Directive（已不推荐）

Svelte 5.16+ 推荐用 class={} 对象/数组形式替代 class: 指令：

<!-- 等价 -->
<div class={{ cool, lame: !cool }}></div>
<div class:cool class:lame={!cool}></div>

Critical: Nested <style> Elements

一个组件只能有一个顶层 <style> 块，但可以嵌套 <style> 标签（不经过作用域处理，直接插入 DOM）：

<div>
  <style>
    /* 原生 style 标签，无作用域，规则全局生效 */
    div { color: red; }
  </style>
</div>

使用场景：

• 主题 token 的 {#if} 切换（变量随切换增删）
• 第三方组件自带的 CSS
• 动态主题变量
• 邮件 / SVG 模板

注意： 嵌套 <style> 中的 @keyframes 名称是全局的，不会被重写。多个组件中同名 keyframe 会冲突。

Critical: {@html} and Scoped Styles

{@html} 注入的内容没有作用域类，scoped 选择器不会匹配。用 :global(...) 解决：

<style>
  :global(.highlight) { color: red; }
</style>

警告： 永远不要用 :global(...) 来样式化你无法完全控制的 HTML——XSS 风险。

Quick Fixes

| 问题 | 解决方案 | |------|----------| | 样式不生效 | 检查 scoped 哈希是否覆盖；用 :global | | 组件样式传不进去 | 用 CSS 自定义属性（--var）而非 scoped 选择器 | | 父组件不能覆盖子组件的样式 | 用 --var 传值，或用 :global（不推荐） | | 全局样式被组件 scoped 覆盖 | scoped 提升 +0-1-0 特异性；用 :where() 或增加全局选择器特异性 | | Tailwind 类不生效 | JIT 找不到动态拼接的类名；用 class={[...]} 数组映射或 safelist | | 动态 style="animation: x" 找不到 keyframe | keyframe 是 scoped 的；用 @keyframes -global-x | | style: 不生效 | 检查表达式语法；数值需要单位 | | > .child 不匹配 | 父传 --var 时包了 svelte-css-wrapper；改用后代选择器 | | slot 内容样式不到 | 用 ::slotted(selector) 从父组件样式化 |

Gotchas

1. Scoped 样式隔离 — 通过哈希类实现，不会真正"隐藏"样式（查看页面源码可见）
2. Scoped 选择器 +0-1-0 特异性 — 总是高于相同形状的全局选择器
3. @keyframes 名称也 scoped — style="animation: name" 找不到 scoped 名称（用 -global-）
4. {@html} 内容不受 scoped 影响 — 插入的 HTML 无作用域类
5. CSS 变量不需要 scoped — var(--custom) 天然跨作用域和级联
6. svelte-css-wrapper 元素 — 父传 --var 时插入，破坏 > 子选择器
7. :global 不降低特异性 — 它退出作用域，但不退出 specificity
8. 嵌套 <style> 是全局 — 不走 Svelte 编译器，原样插入 DOM
9. 编译器只在同 <style> 块内重写 animation — 其他地方需 -global-
10. <style> 属性和 JS 中的 scoped keyframe 名称 — 不被重写

FAQ

Q: 如何让样式影响子组件内部？ A: 两种方式：① 父组件传入 CSS 自定义属性（推荐）；② 用 :global（影响全局，会破坏封装）。

Q: Svelte 编译后 class 名称是什么？ A: 形如 svelte-123xyz 的哈希，组件级唯一。

Q: scoped 样式会赢过全局样式吗？ A: 是。scoped 提升 +0-1-0 特异性。同形状的全局 p 输给 scoped p。

Q: 何时用 :global 而不是 CSS 变量？ A: 当你必须控制选择器本身（位置、选择什么），而不是传入值时，用 :global。大多数"传值"的场景用 CSS 变量更好。

Q: 为什么 class:[...] 数组中的 falsy 值不会变成字符串？ A: Svelte 用 clsx 规则过滤掉 false/null/undefined/""/0。class={false} 才会变成 class="false"（历史行为，5.16+ 已改变数组形式）。

Q: 嵌套 <style> 中的规则为什么是全局的？ A: 嵌套 <style> 不经过 Svelte 编译器的 scoping 处理，按原样插入 DOM。浏览器会像处理普通 <style> 一样解析它。

Q: scoped keyframe 可以从外部触发吗？ A: 不行。scoped keyframe 名称在编译时被改写，外部无法用裸名引用。用 @keyframes -global-name。

Q: style: 指令和 style="..." 属性同时用会怎样？ A: style: 胜出，即使 style="" 用了 !important。这是 Svelte 5 的设计。

Q: 我能用 bg-${color}-500 这样的模板字符串做动态 Tailwind 类吗？ A: 不能可靠工作——JIT 看不到完整类名。用查找表（{ red: 'bg-red-500', ... }）或 safelist。

Examples

| File | Description | |------|-------------| | examples/README.md | Entry point listing all example files with descriptions | | examples/scoped-styles.md | Scoped styles, specificity, :where() trick, when styles don't apply, compiled output, svelte-css-wrapper | | examples/scoped-keyframes.md | @keyframes scoping, the -global- prefix, sharing animations, triggering from JS, prefers-reduced-motion | | examples/global-patterns.md | :global(...) single, compound, nested, block, and when to use vs CSS custom properties | | examples/style-directive.md | style:property, style:--var, \|important, expressions, multiple styles, value coercion | | examples/nested-style.md | Raw <style> tags inside templates, {#if}/{#each} style fragments, lifecycle, gotchas | | examples/tailwind.md | Tailwind CSS, arbitrary values, dynamic theming with custom properties, safelist, twMerge |

References

| File | Description | |------|-------------| | references/README.md | Entry point listing all reference files with descriptions | | references/scoped-deep.md | Deep dive into scoping mechanism, hash generation, :where() wrapping, nested <style>, edge cases | | references/scoped-keyframes.md | Scoped keyframes, the -global- prefix, sharing across components, rewriter rules | | references/global-reference.md | Full reference for :global(...) single, nested, block, compound, with cascade and transform examples | | references/specificity.md | Specificity interactions, :where() / :is() / :not(), override strategies, cascade order | | references/style-directive.md | All style: forms, style:--var serialization, \|important, value coercion, precedence | | references/css-custom-properties.md | CSS Custom Properties: passing, reading, cascading, dynamic updates | | references/class-directive.md | class vs class: directive, ClassValue types, clsx patterns |