Svelte 5 自定义 CSS 属性：向组件传递 `--*` 样式参数与 `svelte-css-wrapper` 的底层实现

Svelte 允许在组件标签上直接书写 --* 开头的 CSS 自定义属性（custom properties），无论是静态值还是随状态变化的动态值。阅读本文后，你将掌握：如何把自定义属性作为"样式 API"传给组件、编译器如何把这类标签降级（desugar）为 <svelte-css-wrapper> 包裹元素、客户端与 SSR 运行时如何渲染和更新这些属性，以及 display: contents 带来的选择器注意事项。

1. 向组件传递静态与动态的自定义属性

在 Svelte 模板中，可以在任何组件（或 <svelte:component>）上使用 --name="value" 形式的属性，既支持纯静态字符串，也支持插值表达式：

<Slider
	bind:value
	min={0}
	max={100}
	--track-color="black"
	--thumb-color="rgb({r} {g} {b})"
/>

这里 --track-color 是静态值，--thumb-color 是动态值——每当 r、g、b 发生变化，属性值会随之更新。这正是把自定义属性当作组件"样式 API"的典型用法：消费方通过几个 --* 参数控制组件外观，而无需为每种主题编写变体。

2. 编译期的降级结果：svelte-css-wrapper 与 SVG 的 <g>

由于组件的根节点未必存在（例如纯文本、片段渲染），Svelte 编译器无法保证把 --* 属性"贴"到某个真实 DOM 元素上。因此，当组件带有任意 --* 属性时，编译器会为其生成一个包裹元素。上述代码在 HTML 上下文中实际被渲染为：

<svelte-css-wrapper style="display: contents; --track-color: black; --thumb-color: rgb({r} {g} {b})">
	<Slider
		bind:value
		min={0}
		max={100}
	/>
</svelte-css-wrapper>

如果该组件处于 SVG 命名空间，则使用 <g> 元素代替：

<g style="--track-color: black; --thumb-color: rgb({r} {g} {b})">
	<Slider
		bind:value
		min={0}
		max={100}
	/>
</g>

源码层面可以印证这条路径：

• 客户端转换阶段在 client/visitors/shared/component.js 中收集所有 attribute.name.startsWith('--') 的属性到 custom_css_props 数组，动态值还会经过 memoizer，被状态依赖的表达式会包成 $.get(thunk)，保证响应式求值；
• 同一文件 component.js 中，当 custom_css_props 非空且当前命名空间为 svg 时调用 push_element('g', ...)，否则调用 push_element('svelte-css-wrapper', ...) 并固定写入 style: display: contents，最后生成 $.css_props(anchor, $.thunk({...})) 调用；
• SSR 端在 server/visitors/shared/component.js 以同样规则收集 --* 属性，运行时的 server/index.js 中 css_props() 直接输出 <svelte-css-wrapper style="display: contents; ..."> 或 <g style="..."> 字符串，使首屏 HTML 与客户端渲染结构完全一致，保证水合（hydration）顺利。

此外还有一个细节：普通组件通常可以省掉锚点注释（anchor comment）以减小产物体积，但从 3-transform/utils.js 的 is_text_first 判断可以看出，只要组件带有 --* 属性，编译器就放弃该优化——因为包裹元素内部需要一个注释锚点来挂载组件输出。

3. 客户端运行时：css_props 如何用 render_effect 更新属性

客户端的运行时实现在 internal/client/dom/blocks/css-props.js，逻辑非常直接：

export function css_props(element, get_styles) {
	if (hydrating) {
		set_hydrate_node(get_first_child(element));
	}

	render_effect(() => {
		var styles = get_styles();
		for (var key in styles) {
			var value = styles[key];
			if (value == null || value === '') {
				element.style.removeProperty(key);
			} else {
				element.style.setProperty(key, value);
			}
		}
	});
}

三点值得注意：

1. 响应式更新：属性值通过 render_effect 订阅，动态表达式依赖的状态变化会触发 effect 重跑，逐个 setProperty 到包裹元素上；
2. 显式清除：当某个属性的值变为 null/undefined 或空字符串时，调用 removeProperty 移除该属性，让组件内部 var(--x, fallback) 回退到默认值——这使得"条件性主题覆盖"成为可能；
3. 水合衔接：hydrating 期间把水合游标设置为包裹元素的第一个子节点（即编译时插入的注释锚点），与 SSR 输出的 HTML 结构对齐。

4. 在组件内部读取自定义属性（含回退值）

在组件的 <style> 中通过 var(...) 读取这些自定义属性，并可提供 fallback 值：

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

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

自定义属性沿 DOM 树继承，因此你并不必须把值直接写在组件标签上——只要自定义属性定义在组件的任意父元素上即可。常见做法是在全局样式表中把一组设计 token 定义在 :root 上，让整站共享，再在个别使用点通过组件属性做局部覆盖：

<!-- 局部覆盖：只改这一个 Slider 的轨道颜色 -->
<Slider --track-color="black" />

两种机制自然叠加：var(--track-color) 优先取到包裹元素上的局部值，取不到时才落到 :root 或 fallback。

5. 注意事项：display: contents 不影响布局，但影响选择器

<svelte-css-wrapper> 上固定携带 display: contents，浏览器不会为它生成盒（box），因此对布局、定位完全没有影响。但正如官方文档特别提醒的：

该包裹元素不影响布局，但会影响那些依赖 > 子代组合器选择"组件容器内直接子元素"的 CSS 选择器。

例如父组件中写作 .container > h2 { ... } 的规则，原本命中的 h2 现在被 <svelte-css-wrapper> 隔了一层，将不再命中。若你的组件边界处使用了子代组合器或 :has()、~ 等与 DOM 结构相关的选择器，需要在传入 --* 属性后重新验证样式。

另外值得一提的是 dev 模式下的调试体验：从测试用例 tests/runtime-runes/samples/svelte-meta-css-wrapper/_config.js 可以看到，即使组件被包裹元素包住，__svelte_meta 仍然把 h2 的源码位置正确记录为 Component.svelte 第 1 行——开发者工具中的组件归属不会因包裹元素而错乱。

6. 测试用例：如何用断言验证最终 DOM

仓库中两个测试样例可以直接作为该特性的"可运行文档"：

• tests/runtime-runes/samples/svelte-meta-css-wrapper/main.svelte：<Component --color="red" />，其中 Component.svelte 的 <style> 使用 color: var(--color)；其 _config.js 断言客户端输出为 <svelte-css-wrapper style="display: contents; --color: red;"> 包裹的结构；
• tests/runtime-runes/samples/dynamic-component-css-props/main.svelte：验证 <svelte:component this={Comp} --color="red" /> 这一动态组件形式同样会被包裹，对应断言见 dynamic-component-css-props/_config.js：

assert.htmlEqual(
	target.innerHTML,
	`<svelte-css-wrapper style="display: contents; --color: red;"><div class="svelte-lsmn3l">Hello</div></svelte-css-wrapper>`
);

7. 与 <style> 中自定义属性编译的关联细节

顺带一个与本文主题相关的编译器行为：Svelte 对 <style> 块做 CSS 压缩（minify）时，会刻意跳过自定义属性声明中的空白压缩，原因是旧版 Chromium（< 99）会把 --foo: ; 与 --foo:; 解析为不同的值。见 3-transform/css/index.js 中 if (!node.property.startsWith('--')) 的分支。这解释了为什么组件标签上的动态 --* 值（含 rgb({r} {g} {b}) 这类带空格的表达式）在压缩构建后依然保持逐字符正确。

小结

• 组件标签上的 --* 属性 = 组件的样式级 API，支持静态与动态（响应式）取值；
• 编译器将其降级为 <svelte-css-wrapper style="display: contents; ...">（SVG 上下文为 <g>），保证自定义属性有一个确定的挂载点；
• 客户端由 render_effect 驱动 setProperty/removeProperty，SSR 与客户端输出同构，水合无碍；
• 组件内用 var(--x, fallback) 消费，父级或 :root 的定义与局部属性自然级联；
• 唯一需要留意的副作用：包裹元素会改变 > 等结构选择器的命中路径，且会阻止"省略锚点注释"的编译优化（utils.js 中显式检查了 --* 属性）。