FAST Element `shadowOptions` 配置完全指南：控制自定义元素 Shadow DOM 的创建方式

前端UI组件【免费下载链接】fastThe adaptive interface system for modern web experiences.项目地址https://gitcode.com/gh_mirrors/fa/fast点击查看免费下载导读shadowOptions是microsoft/fast-element中PartialFASTElementDefinition的核心配置属性它决定了 FAST 自定义元素创建 Shadow DOM 的方式默认开放open模式、封闭closed模式或是直接渲染到 Light DOM。本文将以 fast-element.partialfastelementdefinition.shadowoptions.md 为骨架结合 fast-definitions.ts 与 element-controller.ts 的源码实现完整讲解该属性的签名、默认值语义、三种取值行为、与attachShadow的对应关系以及实际组件中的配置范例。属性签名与定义位置shadowOptions是PartialFASTElementDefinition接口的成员属性该接口位于 fast-definitions.ts。其类型签名如下readonly shadowOptions?: PartialShadowRootOptions | null;几个关键点readonly该属性在定义阶段只读用于向FASTElementDefinition提供元数据不会在运行期被用户代码直接修改。PartialShadowRootOptions只需提供与默认值有差异的字段未提供的字段会与框架默认值合并。| null显式传入null表示不使用 Shadow DOM元素模板将渲染到 Light DOM。值得留意的是仓库源码中的ShadowRootOptions接口比浏览器原生ShadowRootInit多扩展了一个registry字段见 fast-definitions.ts用于为 shadow root 提供自定义元素注册表beta能力export interface ShadowRootOptions extends ShadowRootInit { /** * A registry that provides the custom elements visible * from within this shadow root. * beta */ registry?: CustomElementRegistry; }在 1.x API 文档中PartialFASTElementDefinition对该属性的表述为 Options controlling the creation of the custom elements shadow DOM控制自定义元素 Shadow DOM 创建的选项与源码注释完全一致。三种取值的语义与默认行为源码构造函数对shadowOptions的归一化逻辑是理解该属性的钥匙见 fast-definitions.tsthis.shadowOptions nameOrConfig.shadowOptions void 0 ? defaultShadowOptions : nameOrConfig.shadowOptions null ? void 0 : { ...defaultShadowOptions, ...nameOrConfig.shadowOptions };而模块顶部的默认值定义为const defaultShadowOptions: ShadowRootInit { mode: open };由此可以归纳出三种取值行为取值行为结果未提供undefined使用默认值以mode: open创建开放的 Shadow Root{ mode: closed }等配置对象与defaultShadowOptions浅合并以用户指定选项创建 Shadow Rootnull归一化为void 0不创建 Shadow DOM模板渲染到 Light DOM注意合并方向{ ...defaultShadowOptions, ...nameOrConfig.shadowOptions }意味着用户配置会覆盖默认值因此只需写出与默认不同的字段即可例如shadowOptions: { mode: closed }会自动继承mode之外的其余默认语义此处默认值仅含mode。源码级验证ElementController 如何消费该配置shadowOptions从定义流向运行时的桥梁是ElementController。在其构造函数中element-controller.ts定义中的配置被写入控制器public constructor(element: TElement, definition: FASTElementDefinition) { this._notifier new PropertyChangeNotifier(element); this.source element; this.definition definition; this.shadowOptions definition.shadowOptions; ... }随后在shadowOptions的 setter 中element-controller.ts执行实际的 Shadow DOM 挂载逻辑public set shadowOptions(value: ShadowRootOptions | undefined) { // options on the shadowRoot can only be set once if (this._shadowRootOptions void 0 value ! void 0) { this._shadowRootOptions value; let shadowRoot this.source.shadowRoot; if (shadowRoot) { this.hasExistingShadowRoot true; } else { shadowRoot this.source.attachShadow(value); if (value.mode closed) { shadowRoots.set(this.source, shadowRoot); } } } }这段代码揭示了三个实现细节Shadow Root 只允许创建一次注释 options on the shadowRoot can only be set once 表明一旦_shadowRootOptions被赋值后续赋值会被忽略——这是浏览器规范中attachShadow不可重复调用的直接映射。closed模式的内部跟踪当mode: closed时浏览器不会暴露element.shadowRoot因此 FAST 内部用shadowRoots一个WeakMapElement, ShadowRoot见 element-controller.ts保存引用供框架内部如样式注入、shadowRootFor查询见该文件 L36 与 L948 附近注释继续访问。null配置Light DOM不会触发attachShadow因为value为undefined时整个分支被跳过模板改由 Light DOM 路径渲染。在customElement装饰器中使用shadowOptions最常见的消费入口是customElement装饰器。该装饰器定义于 fast-element.ts其参数类型正是string | PartialFASTElementDefinitionexport function customElement(nameOrDef: string | PartialFASTElementDefinition) { return function (type: ConstructableHTMLElement) { define(type, nameOrDef); }; }默认开放 Shadow DOM以下写法不提供shadowOptionsFAST 会以默认的{ mode: open }创建 Shadow Root模板渲染进 Shadow DOMimport { FASTElement, customElement, attr, html } from microsoft/fast-element; const template htmlNameTag div classheader h3${x x.greeting.toUpperCase()}/h3 /div div classbody slot/slot /div ; customElement({ name: name-tag, template }) export class NameTag extends FASTElement { attr greeting: string Hello; }封闭模式shadowOptions: { mode: closed }customElement({ name: name-tag, template, shadowOptions: { mode: closed } }) export class NameTag extends FASTElement { attr greeting: string Hello; }需要注意官方文档 working-with-shadow-dom.md 的提醒Avoid usingclosedmode since it affects event propagation and makes custom elements less inspectable. 尽量避免使用closed模式因为它会影响事件传播并降低自定义元素的可检查性。这正对应前述源码行为closed模式下外部无法通过element.shadowRoot访问内部 DOMcomposedPath()中 Shadow DOM 内部目标也不会出现详见 working-with-shadow-dom.md事件路径看起来就像自定义元素本身是第一个 target。Light DOM 渲染shadowOptions: nullcustomElement({ name: name-tag, template, shadowOptions: null }) export class NameTag extends FASTElement { attr greeting: string Hello; }官方文档同时给出了重要约束working-with-shadow-dom.mdIf you choose to render to the Light DOM, you will not be able to compose the content, use slots, or leverage encapsulated styles. Light DOM rendering is not recommended for reusable components. It may have some limited use as the root component of a small app. 如果选择渲染到 Light DOM将无法组合内容、使用 slot也无法获得样式封装。Light DOM 渲染不建议用于可复用组件仅适合作为小型应用的根组件等有限场景。与原生attachShadow选项的完整对应shadowOptions的PartialShadowRootOptions类型意味着它暴露了标准Element.attachShadow()的全部选项。官方文档 working-with-shadow-dom.md 明确指出除 mode 之外还可以指定如delegatesFocus: true等新选项且只需写出与默认值不同的字段。标准ShadowRootInit支持的核心选项均由shadowOptions透传给attachShadow选项类型作用modeopen \| closed控制 Shadow Root 的可见性FAST 默认opendelegatesFocusboolean焦点委托键盘焦点从 shadow host 委托给可聚焦的 shadow 内部元素slotAssignmentnamed \| manual控制 slot 分配模式较新浏览器支持clonableboolean允许cloneNode()时克隆 Shadow Root较新浏览器支持serializableboolean允许通过 Declarative Shadow DOM 序列化较新浏览器支持这些选项在较新浏览器中才可用且要求元素在构造时由 FAST 统一调用attachShadow完成挂载。以焦点管理为例配置方式如下customElement({ name: my-dialog, template, shadowOptions: { mode: open, delegatesFocus: true } }) export class MyDialog extends FASTElement { // 焦点将自动委托到 Shadow DOM 内第一个可聚焦元素 }组件库中的真实配置范例在仓库的组件文档中shadowOptions被广泛使用。例如 fast-components.fastbutton.md 与 fast-components.fasttoolbar.md 展示了fast-button、fast-toolbar等基础组件的定义片段以下为文档中呈现的形态customElement({ name: fast-button, template, styles, shadowOptions: { ... } })此外fast-components.allcomponents.md 汇总了fast-avatar、fast-search、fast-text-field、fast-anchor、fast-text-area、fast-number-field、fast-picker、fast-breadcrumb、fast-combobox等一系列组件的定义其中均包含shadowOptions字段。在 design-systems/creating-a-component-library.md 与 design-systems/fast-frame.md 的设计系统文档中也给出了shadowOptions在库级配置中的写法后者还提示更多 Shadow 选项的细节可参考原生Element.attachShadow()规范。若需要快速查阅速记形态resources/cheat-sheet.md 的速查表中也包含了带shadowOptions的组件定义示例。与FASTElementDefinition的关系Partial 到完整定义需要区分两个相关但不同的属性PartialFASTElementDefinition.shadowOptions本文主题类型为PartialShadowRootOptions | null是用户书写定义时提供的部分配置允许省略字段、允许传null。FASTElementDefinition.shadowOptions见 fast-element.fastelementdefinition.shadowoptions.md 与 fast-definitions.ts类型为ShadowRootOptions是归一化后的完整配置——由构造函数完成默认值合并再交付给ElementController执行attachShadow。这一Partial 输入 → 合并默认值 → 完整定义 → 控制器消费的链路正是shadowOptions设计的核心用户永远只需声明差异框架负责补齐默认语义默认mode: open。小结shadowOptions用极简的 API 覆盖了 Shadow DOM 创建的全部决策点省略→ 开放 Shadow DOM框架默认{ mode: closed }→ 封闭 Shadow DOM牺牲可检查性换取更强封装null→ Light DOM 渲染放弃 slot 组合与样式封装仅适用于根组件等场景其余attachShadow选项delegatesFocus等→ 按需透传只写差异项。其运行时行为可在 element-controller.ts 中验证Shadow Root 仅创建一次、closed模式由内部WeakMap跟踪、Light DOM 路径不触发attachShadow。理解了这三点你就能在 FAST 应用中精确掌控自定义元素的渲染域与封装边界。赞分享前端UI组件【免费下载链接】fastThe adaptive interface system for modern web experiences.项目地址https://gitcode.com/gh_mirrors/fa/fast点击查看免费下载相关推荐深入解析 fast-element 的 ComposableStyles自定义元素 Shadow DOM 的可组合样式类型深入解析 fast element 的 ComposableStyles自定义元素 Shadow DOM 的可组合样式类型 导读 ComposableStyl前端UI组件深入解析 fast-element 的 PartialFASTElementDefinition自定义元素元数据配置接口全指南深入解析 fast element 的 PartialFASTElementDefinition自定义元素元数据配置接口全指南 导读 PartialFASTE前端UI组件FASTElementDefinition 深度解析microsoft/fast-element 自定义元素元数据与注册机制完全指南FASTElementDefinition 深度解析microsoft/fast element 自定义元素元数据与注册机制完全指南 本文以 micros前端UI组件上一篇DXVK配置文件验证工具检查参数有效性下一篇终极GameFramework实战指南如何快速开发完整RPG游戏创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考