企业官网建设流程全解析

• 前端
• UI组件

本篇技术指南围绕 FAST Element（@microsoft/fast-element）公开 API 中的StyleTarget接口展开，它定义了"可以被样式作为注入目标"的节点契约，是css()模板样式、ElementStyles组合以及 Shadow DOM 样式注入在运行时落地的关键抽象。读完本文，你将掌握StyleTarget的属性、方法签名与废弃项，理解AdoptedStyleSheetsStrategy与StyleElementStrategy两套策略如何在底层利用该接口完成样式注入与移除，以及如何借助normalizeStyleTarget的解析规则判断样式最终作用于 ShadowRoot、宿主元素还是document。

StyleTarget 是什么

在 FAST Element 的公开 API 体系中，StyleTarget是一个接口（Interface），文档中的定位描述为"A node that can be targeted by styles"，即可以被样式定位（注入）的节点。它定义了一组最小化的 DOM 操作能力，使得样式系统不直接依赖完整的Node/HTMLElement类型，而是面向一个"足够用于样式注入"的结构化契约进行编程。

在 1.x 的 API 文档中，StyleTarget位于fast-element包顶层导出命名空间之下（fast-element.md），与ElementStyles、StyleStrategy等样式相关类型共同构成样式子系统的基础设施。

其接口签名为：

export interface StyleTarget

该接口包含1 个属性和4 个方法（其中prepend()已标记为废弃），分别对应样式系统在运行时对节点执行的"追加、查询、移除、采用样式表"等操作。

源码中的完整接口定义

在仓库中，StyleTarget的实际定义位于 packages/fast-element/src/styles/style-strategy.ts（第 5～28 行），比 API 文档中展示的签名多了一层结构约束——它通过Pick<Node, "getRootNode">要求实现方具备getRootNode()能力：

export interface StyleTarget extends Pick<Node, "getRootNode"> { adoptedStyleSheets?: CSSStyleSheet[]; append(styles: HTMLStyleElement): void; removeChild(styles: HTMLStyleElement): void; querySelectorAll<E extends Element = Element>(selectors: string): NodeListOf<E>; }

值得注意的差异：

• 源码中没有prepend()方法——因为 API 文档已将其标记为废弃，推荐统一使用append()，因此源码层面只保留了append()这一条添加路径；
• 接口要求实现方具备getRootNode()，这一能力在normalizeStyleTarget()中被用来回退解析最终的样式作用域（详见下文）；
• adoptedStyleSheets是可选的（?修饰），因为并非所有运行环境（浏览器）都支持构造式样式表（Constructable Stylesheets）。

与StyleTarget配套的还有StyleStrategy接口（同文件第 34～45 行），它规定了策略对象必须具备的对称操作：

export interface StyleStrategy { addStylesTo(target: StyleTarget): void; removeStylesFrom(target: StyleTarget): void; }

即：凡是能对StyleTarget执行"添加样式"与"移除样式"的对象，都可称为一种样式策略。StyleTarget描述"在哪里注入"，StyleStrategy描述"怎么注入"，二者共同支撑ElementStyles的运行时行为。

属性详解：adoptedStyleSheets

adoptedStyleSheets是StyleTarget唯一的属性，API 文档描述为"Stylesheets to be adopted by the node."（该节点要采用的样式表）。

adoptedStyleSheets?: CSSStyleSheet[];

• 类型：CSSStyleSheet[]（可选属性，支持undefined）；
• 语义：对应 Web 平台标准中的构造式样式表（Constructable Stylesheets）能力。通过构造CSSStyleSheet并使用replaceSync()填入 CSS 文本，再把样式表实例挂到目标节点的adoptedStyleSheets数组上，浏览器即可让这些样式直接作用于该节点（ShadowRoot、document或 Element），无需生成<style>DOM 元素；
• 为什么可选：ElementStyles.supportsAdoptedStyleSheets（packages/fast-element/src/styles/element-styles.ts 第 123～125 行）会在运行时检测环境能力：

public static readonly supportsAdoptedStyleSheets = Array.isArray((document as any).adoptedStyleSheets) && "replace" in CSSStyleSheet.prototype;

只有在"浏览器支持document.adoptedStyleSheets数组、且CSSStyleSheet.prototype上存在replace方法"时，才会走 adopted-style-sheets 路线；否则回退到<style>元素注入方案，此时adoptedStyleSheets便不会被使用。

在AdoptedStyleSheetsStrategy（packages/fast-element/src/components/element-controller.ts 第 956～987 行）中，该属性的读写逻辑如下：

public addStylesTo(target: StyleTarget): void { addAdoptedStyleSheets(normalizeStyleTarget(target), this.sheets); } public removeStylesFrom(target: StyleTarget): void { removeAdoptedStyleSheets(normalizeStyleTarget(target), this.sheets); }

其中addAdoptedStyleSheets/removeAdoptedStyleSheets的基础实现（同文件第 1030～1040 行）通过展开数组实现追加与过滤移除：

let addAdoptedStyleSheets = (target: Required<StyleTarget>, sheets: CSSStyleSheet[]) => { target.adoptedStyleSheets = [...target.adoptedStyleSheets!, ...sheets]; }; let removeAdoptedStyleSheets = (target: Required<StyleTarget>, sheets: CSSStyleSheet[]) => { target.adoptedStyleSheets = target.adoptedStyleSheets!.filter( (x: CSSStyleSheet) => sheets.indexOf(x) === -1, ); };

源码中还针对 Safari 16.4 的 FrozenArray 缺陷做了分支适配（同文件第 1041～1064 行）：检测到document.adoptedStyleSheets支持push/splice时，改为原地修改数组，规避赋值导致样式表周期性丢失的 bug。

方法详解

append(styles)

append(styles: HTMLStyleElement): void;

• 功能：通过"追加"方式向目标节点添加样式（"Adds styles to the target by appending the styles."）；
• 参数：styles: HTMLStyleElement，要添加的样式元素；
• 返回：void。

append()是当前推荐的添加路径。在StyleElementStrategy（element-controller.ts 第 997～1028 行）中，每个样式串会先被包装成带唯一类名（fast-${id}）的<style>元素再追加：

public addStylesTo(target: StyleTarget): void { target = usableStyleTarget(normalizeStyleTarget(target)); const styles = this.styles; const styleClass = this.styleClass; for (let i = 0; i < styles.length; i++) { const element = document.createElement("style"); element.innerHTML = styles[i]; element.className = styleClass; target.append(element); } }

prepend(styles)

prepend(styles: HTMLStyleElement): void;

• 功能：通过"前置"方式向目标节点添加样式；
• 参数：styles: HTMLStyleElement，要添加的样式元素；
• 返回：void；
• ⚠️ 废弃警告：API 文档明确标注"This API is now obsolete. - use append()"，即新代码应改用append()。由于同一节点上的<style>注入顺序会影响 CSS 级联优先级，当前实现统一走追加路径以保证可预期的覆盖顺序。

removeChild(styles)

removeChild(styles: HTMLStyleElement): void;

• 功能：从目标节点移除样式（"Removes styles from the target."）；
• 参数：styles: HTMLStyleElement，要移除的样式元素；
• 返回：void。

在StyleElementStrategy.removeStylesFrom()（element-controller.ts 第 1018～1027 行）中，移除操作依赖querySelectorAll按之前注入的styleClass精确查找再逐个removeChild：

public removeStylesFrom(target: StyleTarget): void { target = usableStyleTarget(normalizeStyleTarget(target)); const styles: NodeListOf<HTMLStyleElement> = target.querySelectorAll( `.${this.styleClass}`, ); for (let i = 0, ii = styles.length; i < ii; ++i) { target.removeChild(styles[i]); } }

querySelectorAll(selectors)

querySelectorAll<E extends Element = Element>(selectors: string): NodeListOf<E>;

• 功能：返回目标节点下所有匹配指定选择器的元素后代（"Returns all element descendants of node that match selectors."）；
• 参数：selectors: string，用于查询的 CSS 选择器；
• 返回：NodeListOf<E>，泛型E默认约束为Element，便于调用方按具体元素类型收窄结果。

样式作用域的解析：normalizeStyleTarget

StyleTarget的契约是"节点"，但 FAST Element 实际开发中我们写的css()样式最终要注入到自定义元素的 ShadowRoot。两者的衔接由normalizeStyleTarget()完成（element-controller.ts 第 936～945 行）：

function normalizeStyleTarget(target: StyleTarget): Required<StyleTarget> { if ("adoptedStyleSheets" in target) { return target as Required<StyleTarget>; } else { return ( (getShadowRoot(target as any) as null | StyleTarget) ?? (target.getRootNode() as any) ); } }

解析规则可以概括为：

1. 若目标自身具备adoptedStyleSheets属性（如 ShadowRoot、document），直接将其作为最终注入目标；
2. 否则，先尝试取该元素（FASTElement）的 ShadowRoot；
3. 取不到 ShadowRoot 时，回退到target.getRootNode()返回的根节点。

此外usableStyleTarget()（同文件第 991～993 行）处理了一个边界情况：当目标就是document本身时，将其替换为document.body，避免样式注入到<html>/<head>之外的非法位置：

function usableStyleTarget(target: StyleTarget): StyleTarget { return target === document ? document.body : target; }

与 ElementStyles、Controller 的协同调用链

StyleTarget在实际组件运行时，通过ElementStyles与Controller形成完整调用链：

1. 组件定义阶段，css()模板或字符串经ElementStyles.normalize()（element-styles.ts 第 108～118 行）归一化为ElementStyles实例；
2. ElementStyles内部按需构造策略（strategygetter，同文件第 48～61 行）：默认根据supportsAdoptedStyleSheets选择AdoptedStyleSheetsStrategy或StyleElementStrategy，也允许通过withStrategy()自定义；
3. 组件连接（connect()）阶段，Controller.addStyles()（element-controller.ts 第 453～466 行）把ElementStyles或直接传入的HTMLStyleElement挂到元素上；若是ElementStyles且尚未附加，则调用styles.addStylesTo(source)，其中source正是以StyleTarget身份参与注入的元素实例；
4. 若传入的是裸HTMLStyleElement，则直接target.append(styles)，目标为元素的 ShadowRoot 或元素本身；
5. 组件断开时，Controller.removeStyles()（同文件第 472～487 行）对称地调用styles.removeStylesFrom(source)或target.removeChild(styles)。

也就是说，你在@customElement上通过styles属性声明的每一条 CSS，最终都会经由StyleTarget契约，落到 ShadowRoot 的adoptedStyleSheets或<style>元素之上。

自定义 StyleTarget 与自定义策略

由于StyleTarget只是一个结构性契约（getRootNode + append + removeChild + querySelectorAll + 可选 adoptedStyleSheets），理论上任何满足该形状的 DOM 节点（ShadowRoot、Element、甚至document）都可以作为注入目标。而策略层同样开放：

• ElementStyles.setDefaultStrategy()（element-styles.ts 第 99～101 行）可全局替换默认策略构造函数，适用于需要完全自定义注入行为的场景（例如服务端渲染或特定宿主环境）；
• ElementStyles.withStrategy()（同文件第 90～93 行）可为单个样式实例指定策略，结合reduceStyles()对嵌套的ElementStyles展开为扁平样式列表后再交给策略处理。

element-controller.ts模块中还同时导出了AdoptedStyleSheetsStrategy与StyleElementStrategy（均标注@internal），它们是默认的两套策略实现，可作为自定义策略的参照模板。

小结

StyleTarget是 FAST Element 样式系统中连接"样式定义"与"注入位置"的最小公共契约：

它配合StyleStrategy、ElementStyles、Controller与normalizeStyleTarget()作用域解析，实现了"一套样式定义、多种注入策略、按环境自动降级"的设计：现代浏览器走 adopted style sheets 的高效路径，老旧或不支持的环境则回退为<style>元素注入，从而保证自定义组件的样式在各类 Web 环境中都能稳定、一致地生效。

• 前端
• UI组件