Svelte style: 指令完全指南：从模板语法到编译与运行时实现

本篇基于 Svelte 官方文档中的 style: 指令说明，系统讲解这一模板特性：它与 style 属性的等价关系、表达式取值与简写形式、|important 修饰符、与内联样式的优先级规则以及 CSS 自定义属性支持，并结合编译器与运行时源码揭示每个特性背后的实现机制，帮助你在实际项目中正确使用并深入理解 style: 指令。

1. 什么是 style: 指令

style: 指令是设置元素内联样式的语法糖，一条 style: 指令等价于在 style 属性中写入一条对应的 CSS 声明。以下两种写法完全等价（引自官方文档 17-style.md）：

<!-- These are equivalent -->
<div style:color="red">...</div>
<div style="color: red;">...</div>

它的实际价值在于：可以脱离完整的 CSS 字符串，按属性单独控制某一条样式，并且每条样式都能独立地接入 Svelte 的响应式系统。在模板中混用 class / 内联 style 字符串时，逐条维护字符串很难做到这一点。

2. 取值形式：字面量、任意表达式与简写

2.1 字面量与任意表达式

指令的值可以是普通字符串，也可以包含任意表达式：

<div style:color="red">...</div>

<!-- The value can contain arbitrary expressions -->
<div style:color={myColor}>...</div>

表达式中可以引用组件状态、计算值、模板字符串等。从源码结构看，客户端转换逻辑 中，带值的指令会通过 build_attribute_value 把表达式编译进更新函数；共享的样式构建器 会检测表达式是否包含响应式状态（has_state）——包含状态的值会把 $.set_style(...) 调用放进 update 阶段，纯静态值则只在 init 阶段执行一次，从而避免不必要的运行时开销。

2.2 简写形式

与 class: 指令类似，style: 也允许省略右侧的值：

<div style:color>...</div>

此时 Svelte 会读取同名变量 color 的值作为样式值。这一行为在分析阶段有专门处理：StyleDirective 分析访问器 在 node.value === true 时，会到当前作用域中查找同名绑定（context.state.scope.get(node.name)），并按绑定的 kind 与 blocker 标记该表达式的响应性。对应地，在 客户端的指令对象构建 中，简写指令会被编译成对同名标识符的 getter 读取。

3. 单个元素上设置多条样式

同一个元素上可以并列多个 style: 指令，各自控制一个 CSS 属性：

<div style:color style:width="12rem" style:background-color={darkMode ? 'black' : 'white'}>...</div>

解析时，元素属性读取逻辑 会以冒号分隔出指令名（color、width、background-color）并生成 StyleDirective AST 节点；get_directive_type 负责把 style 前缀映射为该节点类型。同时，属性去重校验（element.js）会按「节点类型 + 属性名」判定重复，因此 style:color 与 class:color、普通 color 属性互不冲突，但同一元素上重复写 style:color 会触发 attribute_duplicate 错误。

4. |important 修饰符

给指令加上 |important 修饰符，可以让对应的声明带 !important：

<div style:color|important="red">...</div>

修饰符在解析阶段通过 | 切分得到（tag.name.slice(colon_index + 1).split('|')，见 element.js），而在分析阶段则有严格校验：StyleDirective.js 中，只要出现超过一个修饰符，或者修饰符不是 important，就直接抛出 style_directive_invalid_modifier 编译错误。也就是说，important 是 style: 指令唯一合法修饰符，例如 style:color|foo 无法通过编译。

编译产物上，普通指令与 |important 指令会被分装入两个对象：客户端 build_style_directives_object 返回 [normal, important] 数组（无 important 时退化为普通对象）；服务端构建 采用完全相同的双对象结构。这个结构一路传递到运行时，是下面优先级规则的基础。

5. 与 style 属性共存时的优先级

当 style: 指令与 style 属性同时存在时，指令始终获胜，甚至可以压过属性里的 !important：

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

这个结论在源码中有清晰的实现依据。共享工具 to_style 负责把「style 属性字符串 + 指令对象」合并为最终的内联样式：

1. 它先扫描 style 属性字符串中的每一条声明（跳过注释、字符串字面量与括号内的内容）；
2. 所有来自 style: 指令的属性名会进入 reserved_names 列表；
3. 凡是属性字符串中与 reserved_names 重名的声明被整条丢弃；
4. 最后按「普通指令 → important 指令」的顺序追加指令产生的声明，important 部分以 !important; 结尾（见 append_styles）。

换句话说，style: 指令不是简单拼接到字符串末尾靠 CSS 层叠取胜，而是在生成阶段就把属性字符串里的冲突声明剔除，因此「压过 !important」是确定性的行为。

运行时更新路径上，set_style 在首次渲染（或整个 style 属性字符串变化）时直接写 dom.style.cssText；当属性字符串不变、仅指令值变化时，则调用 update_styles 对变更的属性逐一执行 dom.style.setProperty(key, value, priority)，其中 priority 即为 'important'（见 style.js），实现增量更新。函数通过 STYLE_CACHE 缓存上一次的 style 属性值来判断是否只需增量更新。相关行为有专门测试覆盖，例如 style-update 用例 验证了属性、spread、自定义元素等场景，style-directive-memoize 用例 验证了指令值的记忆化。

6. 设置 CSS 自定义属性

style: 指令同样可以设置 CSS 自定义属性（CSS 变量）：

<div style:--columns={columns}>...</div>

这里有一个容易被忽略的细节：普通样式属性名会被统一小写（background-color 类名称不区分大小写），但 CSS 自定义属性名是大小写敏感的。to_css_name 专门为此做了区分——仅当名称以 -- 开头时保留原样，否则转小写。服务端 build_attr_style 中同样有「-- 前缀不转小写」的判断。因此书写 --columns 这类变量名时，建议直接采用 CSS 约定（通常全小写），以避免变量名大小写不一致导致的读取失败。

7. 完整调用链速览

把各阶段的文件串起来，一条 style: 指令的生命周期如下：

阶段	位置	职责
解析	phases/1-parse/state/element.js	识别 style: 前缀与 |important 修饰符，生成 StyleDirective 节点并做重名校验
分析	visitors/StyleDirective.js	校验修饰符合法性；标记子树为动态；解析简写形式的作用域绑定
客户端转换	RegularElement.js、shared/element.js	按 important 拆分指令对象，静态/动态分别放入 init/update 阶段，调用 $.set_style
服务端转换	server/.../shared/element.js	构建双对象结构并生成 $.attr_style(...) 调用
运行时	dom/elements/style.js、shared/attributes.js	set_style 增量更新 DOM，to_style 合并并裁剪与指令冲突的 style 属性声明

8. 要点小结

• style:color="red" 等价于 style="color: red"，但能按属性粒度接入响应式；
• 值支持任意表达式；style:color 简写等价于读取同名变量 color；
• 同一元素可并列多条 style: 指令；重复同一属性名会在编译期报错；
• important 是唯一合法修饰符，其他写法直接编译失败；
• 指令永远优先于 style 属性中的同名声明，包括带 !important 的声明；
• 可设置 CSS 自定义属性，且 -- 开头的名称保持大小写不变。

上述行为均可在当前仓库中通过对应源码文件与 runtime-runes 测试样例 复现验证，适合作为使用 style: 指令时的权威参照。