FAST 自适应配色系统中的 neutralFillStealthFocus：隐形填充焦点态 Design Token 深入解析-平芜编程栈

前端
UI组件

【免费下载链接】fast

The adaptive interface system for modern web experiences.

项目地址：https://gitcode.com/gh_mirrors/fa/fast

neutralFillStealthFocus是 FAST Frame 设计系统（@microsoft/fast-components）中"隐形填充（Stealth Fill）"配色 Recipe 家族的一员，专门用于定义组件在获得键盘焦点（focus）时的背景填充色。本文将围绕该 Token 的官方 API 定义，结合同一家族的 rest / hover / active 状态 Token、delta 偏移量 Token、Recipe 接口以及 FAST 的 Design Token 与自适应配色系统文档，深入讲解它的类型签名、底层求值机制、配套参数，以及在实际组件样式中的配置方法，帮助你完整掌握这一"低调但关键"的焦点态配色方案。

官方 API 定义与类型签名

根据@microsoft/fast-components的自动生成 API 文档，neutralFillStealthFocus是一个导出的变量（variable），其完整签名为：

neutralFillStealthFocus: import("@microsoft/fast-foundation").CSSDesignToken<Swatch>

类型为CSSDesignToken<Swatch>：它是@microsoft/fast-foundation提供的设计令牌（Design Token），会向 DOM 自动发射对应的 CSS 自定义属性（custom property），供样式系统消费；
值类型为Swatch：即调色板（Palette）中的一个颜色样本，实现了相对亮度（RelativeLuminance），并提供contrast(target)（计算对比度）与toColorString()（转换为颜色字符串）等方法，是整个自适应配色系统的原子单位。

在 API 文档的变量索引中，它与兄弟 Token 一起被列出（见 fast-components 变量清单）：

Token 变量	类型
`neutralFillStealthRest`	`CSSDesignToken<Swatch>`
`neutralFillStealthHover`	`CSSDesignToken<Swatch>`
`neutralFillStealthActive`	`CSSDesignToken<Swatch>`
`neutralFillStealthFocus`	`CSSDesignToken<Swatch>`
`neutralFillStealthRestDelta`/`HoverDelta`/`ActiveDelta`/`FocusDelta`	`DesignToken<number>`
`neutralFillStealthRecipe`	`DesignToken<InteractiveColorRecipe>`

也就是说，neutralFillStealthFocus只是整套隐形填充方案的一个"输出结果"，它的值由更底层的 Recipe 与 Delta 参数共同计算得出。

Stealth Fill 在 FAST Frame 配色体系中的定位

要理解neutralFillStealthFocus，首先要理解"隐形填充"这一 Recipe 的设计意图。在 FAST Frame 自适应配色系统文档中，neutralFillStealth被这样描述：

neutralFillStealth—— Stateful（有状态）。比neutralFill更低调：静止态（rest）下是透明的，常用于低优先级功能，以降低视觉注意。

这正是 "Stealth（隐形）" 一词的由来：它与普通填充neutralFill不同，静止时完全透明、融入背景；只有当用户与组件交互（悬停、按下、聚焦）时，才逐渐浮现出填充色。这类 Recipe 常被用于工具栏图标按钮、低优先级操作、信息密度较高的场景，让次要功能"平时隐身、交互时现身"。

在 FAST Frame 的 Recipe 术语体系中（见 fast-frame.md 自适应配色章节）：

"Fill"表示该 Recipe 用于填充较大面积，通常指组件的背景板（backplate）；
"Stateful"表示该 Recipe 支持 rest（静止）、hover（悬停）、active（按下）、focus（焦点）四种交互状态，每个状态对应一个独立的输出色值。

因此，neutralFillStealthFocus就是"隐形填充 Recipe"在focus 状态下的具体输出。

从 Recipe 到四态 Token 的求值机制

neutralFillStealthFocus不是随意指定的固定颜色，而是由 Recipe 算法实时计算出来的。API 文档揭示了完整链条：

Recipe 层：neutralFillStealthRecipe: DesignToken<InteractiveColorRecipe>（见 neutralFillStealthRecipe API）。InteractiveColorRecipe接口只暴露一个求值方法（见 InteractiveColorRecipe.evaluate()）：

evaluate(element: HTMLElement, reference?: Swatch): InteractiveSwatchSet;

element：当前目标组件元素，用于向上查找所在 DOM 树中已配置的配色参数；
reference：可选的参考Swatch——这是自适应 UI 的核心概念，Recipe 依据"包含该组件的背景色"来动态取色，从而让同一个 Recipe 在浅色、深色甚至任意中间亮度背景下都能给出视觉一致的方案。

输出层：evaluate()返回一个InteractiveSwatchSet（见 InteractiveSwatchSet API），它由四个状态色组成：

属性	含义
`rest`	静止态要应用的 swatch
`hover`	悬停态要应用的 swatch
`active`	按下态要应用的 swatch
`focus`	焦点态要应用的 swatch —— 即`neutralFillStealthFocus`的值

Token 层：四个状态色分别被注入neutralFillStealthRest、neutralFillStealthHover、neutralFillStealthActive、neutralFillStealthFocus四个CSSDesignToken<Swatch>，组件样式通过读取对应 Token 即可获得当前状态下的正确背景色。

Delta 偏移量：Recipe 的"可调参数"

Recipe 的求值结果受 delta 参数控制。FAST Frame 的约定是：名为xxxFill的算法依赖同名的一组 Delta 值（见 fast-frame.md 对算法的说明），即neutralFillStealth依赖neutralFillStealthRestDelta、neutralFillStealthHoverDelta、neutralFillStealthActiveDelta、neutralFillStealthFocusDelta。以焦点态为例（见 neutralFillStealthFocusDelta API）：

neutralFillStealthFocusDelta: DesignToken<number>;

它表示：Recipe 在基础色上沿调色板方向偏移多少个色阶（palette index）来得到焦点态颜色。通过调整这些数值，设计团队可以在不改动算法逻辑的前提下，微调隐形填充在 hover / focus / active 各状态的深浅与对比度表现。

在实际组件样式中使用 neutralFillStealthFocus

neutralFillStealthFocus是CSSDesignToken，因此它可以像其他 FAST Design Token 一样直接在 FAST 样式表中作为 CSS 指令使用。设计令牌文档提供了标准用法（见 design-tokens.md 的"在 CSS 中使用 Design Tokens"章节）：

import { css } from "@microsoft/fast-element"; import { neutralFillStealthFocus } from "@microsoft/fast-components"; const styles = css` :host { background: ${neutralFillStealthFocus}; } `;

运行时，该指令会被替换为对应的 CSS 自定义属性，指令机制会确保该自定义属性被正确附加到元素上。由于 Token 值是按 DOM 树分层的，读取到的始终是"该元素实例（或最近祖先）"所配置的焦点态填充色。

按需覆盖焦点态颜色

如果你希望某个局部区域内的隐形填充焦点态颜色不同于全局默认值，应通过DesignToken.setValueFor()针对元素节点设置值，而不是在 CSS 中手写自定义属性（见下文"注意事项"）：

import { neutralFillStealthFocus } from "@microsoft/fast-components"; const container = document.querySelector("my-container"); neutralFillStealthFocus.setValueFor(container, /* 一个 Swatch 值 */);

也可以为 Token 设定默认值，使没有显式配置的节点树回落到该默认值（见 design-tokens.md 的设置默认值章节）：

neutralFillStealthFocus.withDefault(/* Swatch 默认值 */);

withDefault()设置的默认值只有在调用DesignToken.registerRoot()（或通过DesignSystem.register()自动完成根注册）后才会向 CSS 自定义属性发射。

使用注意事项

不要手动声明发射出的 CSS 自定义属性：FAST Frame 文档明确指出（见 fast-frame.md 的"Adaptive Color Don'ts"），自适应配色系统完全运行在 JavaScript 中，产出的 CSS 自定义属性应被视为不可变。若在 CSS 中自行声明这些属性，配色系统无法感知变化，组件会以错误的颜色渲染，进而引发可访问性（对比度）问题。要修改取值，请一律使用DesignToken.setValueFor()API。
保持状态一致性：隐形填充是 Stateful Recipe，四个状态 Token（rest / hover / active / focus）协同工作。单独覆盖neutralFillStealthFocus时，应同时评估 hover、active 状态的对比度表现，确保焦点环与填充效果在视觉上连续、可辨识。
透明是特性而非缺陷：rest 态透明意味着静止时的组件完全融入背景，因此这种方案更适合低优先级、可被其他视觉线索（如图标、文字）区分的功能；需要强强调的场景应改用neutralFillContrast等会满足背景对比度要求的 Recipe。