尧图网页设计  指令：观测 `＜slot＞` 分配节点并同步到属性的权威指南)
前端UI组件【免费下载链接】fastThe adaptive interface system for modern web experiences.项目地址https://gitcode.com/gh_mirrors/fa/fast点击查看免费下载slotted()是microsoft/fast-element提供的模板指令directive用于观测某个slot元素通过assignedNodes()返回的分配节点并在这些节点发生变化时自动更新组件上的指定属性。本文以仓库 API 文档 为骨架结合 slotted.ts 源码、node-observation.ts 基类 与 Playwright 测试完整讲解其函数签名、两种调用方式、可配置选项以及如何用它在实际组件中构建可响应变化的插槽内容。一、slotted() 是什么在 Web Components 的 Shadow DOM 机制中slot是宿主元素与影子树之间的插槽外部传入的 Light DOM 内容会被分配到插槽中。当我们需要在组件内部对这些被分配进来的节点而不是组件自己渲染的节点做引用、统计或渲染时slotted()指令就是官方提供的桥梁。按 fast-element.slotted.md 的官方定义A directive that observes theassignedNodes()of a slot and updates a property whenever they change.即观测某个 slot 的assignedNodes()返回值并在其发生变化时把结果更新到一个属性上。它属于引用型指令referential directives家族与ref引用单个 DOM 节点、children引用某个元素的所有子节点并列。三者区别如下指令观测目标底层机制典型场景ref单个模板内节点视图绑定直接拿到video、canvas等节点的引用children某元素的所有子节点MutationObserver统计/遍历某容器下的全部子节点slotted某个slot的分配节点slot 上的slotchange事件 assignedNodes()感知外部传入插槽的内容变化与children使用MutationObserver不同slotted只监听slotchange事件成本更低且天然与 Shadow DOM 的插槽分配语义对齐。二、函数签名与类型定义slotted的官方签名见 fast-element.slotted.mdexport declare function slottedT any( propertyOrOptions: (keyof T string) | SlottedBehaviorOptionskeyof T string ): CaptureTypeT;当前仓库 1.x 系列中实际导出实现见 packages/fast-element/src/templating/slotted.tsexport function slottedTSource any, TParent any( propertyOrOptions: | (keyof TSource string) | SlottedDirectiveOptionskeyof TSource string, ): CaptureTypeTSource, TParent { if (isString(propertyOrOptions)) { propertyOrOptions { property: propertyOrOptions }; } return new SlottedDirective( propertyOrOptions as SlottedDirectiveOptionskeyof TSource string, ); }对签名做逐项拆解参数propertyOrOptions二选一。传一个字符串属性名keyof T string保证该名字必须是源类型T上真实存在的键函数会自动把它包装为{ property: propertyOrOptions }传一个选项对象SlottedBehaviorOptions可同时配置property、filter以及assignedNodes()的参数返回值CaptureTypeTSource, TParent一个可供html模板编译器识别的捕获类型标记表明该指令捕获了模板中的某个节点位置。TSource是视图数据源类型TParent是父视图类型泛型TSource any, TParent any仓库源码使用TSource/TParent命名而文档中的 API 摘要使用T any两者是同一泛型参数在不同生成阶段的不同命名语义一致。SlottedBehaviorOptions 选项接口选项接口定义fast-element.slottedbehavioroptions.mdexport interface SlottedBehaviorOptionsT any extends NodeBehaviorOptionsT, AssignedNodesOptions它由两部分组成NodeBehaviorOptionsT定义于 node-observation.tsproperty: T要把观测到的节点数组赋值到的属性名filter?: ElementsFilter可选的节点过滤函数签名(value: Node, index?: number, array?: Node[]) boolean对数组中的每个节点调用一次返回true的节点才会被同步到属性。AssignedNodesOptions即浏览器原生HTMLSlotElement.assignedNodes()的参数类型flatten?: boolean若为true返回的节点列表包含所有后备内容fallback content被扁平化后的节点这些参数最终原样透传给 getNodes() 中的assignedNodes(this.options)。便捷过滤器elements()仓库在 node-observation.ts 中提供了一个开箱即用的过滤器const selectElements (value: Node): boolean value.nodeType 1; export const elements (selector?: string): ElementsFilter selector ? value value.nodeType 1 (value as HTMLElement).matches(selector) : selectElements;不带参数调用elements()只保留nodeType 1的元素节点过滤掉文本节点、注释节点等带选择器调用elements(li)在元素节点的基础上再用matches()做 CSS 选择器匹配该工厂函数同时服务于children与slotted两个指令属于共享工具。三、核心用法两种调用方式方式一直接传属性名当组件上已经声明了一个属性配合observable可获得响应式更新可以直接把属性名传给slotted()import { FASTElement, customElement, html, slotted } from microsoft/fast-element; const template htmlMyElement div slot ${slotted(slottedNodes)}/slot /div ; customElement({ name: my-element, template }) export class MyElement extends FASTElement { observable slottedNodes: Node[]; slottedNodesChanged() { // 响应插槽节点变化 } }这段示例取自官方 using-directives.md 文档。关键行为slottedNodes会被填充为该 slot 的assignedNodes()结果Node[]属性用observable装饰后插槽内容变化时属性会动态更新模板中凡是依赖该属性的绑定都会自动重渲染可选的*Changed变更回调如slottedNodesChanged()会在节点变化时被调用与ref、children类似节点在connectedCallback生命周期之后才可用官方文档专门给出提示应优先依赖变更处理器而不是假设节点在connectedCallback中已就绪。方式二传选项对象当需要过滤节点或指定assignedNodes()参数时改用对象形式import { FASTElement, customElement, html, slotted, elements } from microsoft/fast-element; const template htmlMyElement div slot ${slotted({ property: items, filter: elements(my-item) })}/slot /div ;这里filter: elements(my-item)表示只有匹配my-item选择器的元素节点才会被同步到items属性文本节点和其他元素都会被过滤掉。四、运行时行为源码级实现原理slotted()返回的SlottedDirectiveslotted.ts继承了NodeObservationDirective基类四个核心方法构成了完整的观测生命周期export class SlottedDirective extends NodeObservationDirectiveSlottedDirectiveOptions { observe(target: EventSource): void { target.addEventListener(slotEvent, this); // slotEvent slotchange } disconnect(target: EventSource): void { target.removeEventListener(slotEvent, this); } getNodes(target: HTMLSlotElement): Node[] { return target.assignedNodes(this.options); } handleEvent(event: Event): void { const target event.currentTarget as any; this.updateTarget(this.getSource(target), this.computeNodes(target)); } }1. 监听机制slotchange 事件observe()在目标slot元素上注册slotchange事件监听器disconnect()负责移除。当插槽的分配节点集合变化如外部新增/移除子节点、节点被重分配时浏览器触发slotchange指令通过handleEvent触发一次更新。2. 取值机制assignedNodes()getNodes()调用原生assignedNodes(this.options)获取分配节点。传入的flatten等选项会在这里生效。从源码看slotted不使用MutationObserver因此只关心分配到插槽的节点变化而非元素子树的任意变动——这是它与children在语义上的根本区别。3. 过滤与赋值computeNodes / updateTarget基类 node-observation.ts 统一处理过滤与赋值protected updateTarget(source: any, value: ReadonlyArrayany): void { source[this.options.property] value; } protected computeNodes(target: any): Node[] { let nodes this.getNodes(target); if (filter in this.options) { nodes nodes.filter(this.options.filter!); } return nodes; }即先取原始节点 → 若有filter则过滤 → 一次性赋值给source[property]。因为属性是observable的赋值动作本身就会触发 FAST 的观察者通知机制驱动依赖该属性的绑定与变更回调。4. 绑定与解绑生命周期基类的bind/unbindnode-observation.ts完成视图绑定时的初始化与清理bind通过controller.targets[this.targetNodeId]定位到模板中的slot节点将 controller 挂到节点的内部属性上立即用当前节点更新一次属性然后调用observe()注册监听并登记到controller.onUnbind(this)unbind先把属性置为空数组emptyArray再disconnect()移除监听最后清空挂在节点上的 controller 引用——确保视图销毁后不会再有回调泄漏或误更新。5. 防御性细节注意SlottedDirective.handleEvent与测试中都体现了两个工程细节指令把自身作为事件处理器this传给addEventListener并通过event.currentTarget取目标节点避免了额外的闭包分配测试中专门验证了DOM 被 JSON.stringify 时不应抛错slotted.pw.spec.ts 第 402-441 行说明指令在节点上挂载的内部 controller 属性被设计为不可序列化侵入的基类通过id生成的内部属性名_controllerProperty与noop化等机制规避了序列化问题。五、测试用例印证六种行为契约仓库的 slotted.pw.spec.ts 用 Playwright 在真实浏览器中验证了指令的行为契约可作为理解slotted()语义的权威清单测试验证内容returns an SlottedDirectiveslotted(test)返回的确实是SlottedDirective实例creates a behavior by returning itself指令的createBehavior()返回自身无状态无副作用的行为单例gathers nodes from a slotbind 后属性被填充为 slot 的全部分配节点顺序一致gathers nodes from a slot with a filter传入filter: elements(foo-bar)后属性只包含匹配元素updates when slotted nodes change向宿主追加子节点并等待Updates.next()后属性自动同步新增节点updates when slotted nodes change with a filter节点变化后过滤逻辑依然生效clears and unwatches when unboundunbind 后属性被清空且后续 DOM 变化不再更新属性should not throw if DOM stringified对引用做JSON.stringify不抛异常这组测试从创建 → 绑定取值 → 过滤 → 动态更新 → 解绑清理 → 序列化安全六个维度锁定了slotted()的完整行为读者若在集成时遇到异常可对照这些断言排查。六、应用场景与对比选型典型场景感知外部传入的插槽内容slotted()最常见的用途是让组件感知使用者传入的插槽内容。官方文档明确建议优先使用变更处理器*Changed来响应插槽节点变化而不是假设节点在connectedCallback时已经就绪。例如在fast-foundation系列组件中select、listbox、toolbar、breadcrumb等组件都大量依赖slotted观测机制来收集插槽中的选项节点并做出响应相关 API 可参见 fast-foundation 的 slotted 相关 API 文档。与children的选型对比维度childrenslotted观测对象元素的所有子节点含未插槽的 Light DOM 节点分配到指定slot的节点底层机制MutationObserver可选subtreeslotchange事件 assignedNodes()选项差异支持subtree子树观测时必须提供selector支持flatten扁平化后备内容适用场景需要监控容器子树整体变化只关心进入某个插槽的分配结果从 using-directives.md 的提示可知若把children放在模板根template元素上拿到的是自定义元素所有 Light DOM 子节点无论它们是否被插槽分配而slotted只反映分配到特定slot的节点。七、小结slotted()是 FAST Element 中连接外部 Light DOM 内容与组件内部逻辑的关键指令两种传参字符串属性名自动包装或SlottedBehaviorOptions对象可配property、filter、flatten响应式联动配合observable属性与*Changed回调插槽节点变化时属性自动更新源码机制清晰slotchange监听 assignedNodes()取值 可插拔filter由 SlottedDirective 与 NodeObservationDirective 共同实现行为有测试背书slotted.pw.spec.ts 覆盖了从绑定、过滤、动态更新到解绑清理的完整契约。当你需要组件对外部传入了什么内容、什么时候变化做出响应时slotted()就是首选方案——在动手前请先确认组件的属性已用observable声明并优先通过变更处理器响应节点变化。赞分享前端UI组件【免费下载链接】fastThe adaptive interface system for modern web experiences.项目地址https://gitcode.com/gh_mirrors/fa/fast点击查看免费下载相关推荐Fast-Element children() 指令详解在 FASTElement 中观察与同步子节点Fast Element children 指令详解在 FASTElement 中观察与同步子节点 children 是 microsoft/fast el前端UI组件深入解析 microsoft/fast-element 的 ChildrenBehaviorOptions子节点与子树观察的完整配置指南深入解析 microsoft/fast element 的 ChildrenBehaviorOptions子节点与子树观察的完整配置指南 导读 Childr前端UI组件FAST Element 的 ChildrenBehavior.disconnect() 详解子节点观测的拆除与资源回收FAST Element 的 ChildrenBehavior.disconnect 详解子节点观测的拆除与资源回收 导读 在基于 microsoft/fa前端UI组件上一篇Assetic 项目常见问题解决方案下一篇DeepSeek Coder 33B Base未来发展趋势与技术路线图创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 FAST Element 的 slotted() 指令：观测 `＜slot＞` 分配节点并同步到属性的权威指南
前端UI组件【免费下载链接】fastThe adaptive interface system for modern web experiences.项目地址https://gitcode.com/gh_mirrors/fa/fast点击查看免费下载slotted()是microsoft/fast-element提供的模板指令directive用于观测某个slot元素通过assignedNodes()返回的分配节点并在这些节点发生变化时自动更新组件上的指定属性。本文以仓库 API 文档 为骨架结合 slotted.ts 源码、node-observation.ts 基类 与 Playwright 测试完整讲解其函数签名、两种调用方式、可配置选项以及如何用它在实际组件中构建可响应变化的插槽内容。一、slotted() 是什么在 Web Components 的 Shadow DOM 机制中slot是宿主元素与影子树之间的插槽外部传入的 Light DOM 内容会被分配到插槽中。当我们需要在组件内部对这些被分配进来的节点而不是组件自己渲染的节点做引用、统计或渲染时slotted()指令就是官方提供的桥梁。按 fast-element.slotted.md 的官方定义A directive that observes theassignedNodes()of a slot and updates a property whenever they change.即观测某个 slot 的assignedNodes()返回值并在其发生变化时把结果更新到一个属性上。它属于引用型指令referential directives家族与ref引用单个 DOM 节点、children引用某个元素的所有子节点并列。三者区别如下指令观测目标底层机制典型场景ref单个模板内节点视图绑定直接拿到video、canvas等节点的引用children某元素的所有子节点MutationObserver统计/遍历某容器下的全部子节点slotted某个slot的分配节点slot 上的slotchange事件 assignedNodes()感知外部传入插槽的内容变化与children使用MutationObserver不同slotted只监听slotchange事件成本更低且天然与 Shadow DOM 的插槽分配语义对齐。二、函数签名与类型定义slotted的官方签名见 fast-element.slotted.mdexport declare function slottedT any( propertyOrOptions: (keyof T string) | SlottedBehaviorOptionskeyof T string ): CaptureTypeT;当前仓库 1.x 系列中实际导出实现见 packages/fast-element/src/templating/slotted.tsexport function slottedTSource any, TParent any( propertyOrOptions: | (keyof TSource string) | SlottedDirectiveOptionskeyof TSource string, ): CaptureTypeTSource, TParent { if (isString(propertyOrOptions)) { propertyOrOptions { property: propertyOrOptions }; } return new SlottedDirective( propertyOrOptions as SlottedDirectiveOptionskeyof TSource string, ); }对签名做逐项拆解参数propertyOrOptions二选一。传一个字符串属性名keyof T string保证该名字必须是源类型T上真实存在的键函数会自动把它包装为{ property: propertyOrOptions }传一个选项对象SlottedBehaviorOptions可同时配置property、filter以及assignedNodes()的参数返回值CaptureTypeTSource, TParent一个可供html模板编译器识别的捕获类型标记表明该指令捕获了模板中的某个节点位置。TSource是视图数据源类型TParent是父视图类型泛型TSource any, TParent any仓库源码使用TSource/TParent命名而文档中的 API 摘要使用T any两者是同一泛型参数在不同生成阶段的不同命名语义一致。SlottedBehaviorOptions 选项接口选项接口定义fast-element.slottedbehavioroptions.mdexport interface SlottedBehaviorOptionsT any extends NodeBehaviorOptionsT, AssignedNodesOptions它由两部分组成NodeBehaviorOptionsT定义于 node-observation.tsproperty: T要把观测到的节点数组赋值到的属性名filter?: ElementsFilter可选的节点过滤函数签名(value: Node, index?: number, array?: Node[]) boolean对数组中的每个节点调用一次返回true的节点才会被同步到属性。AssignedNodesOptions即浏览器原生HTMLSlotElement.assignedNodes()的参数类型flatten?: boolean若为true返回的节点列表包含所有后备内容fallback content被扁平化后的节点这些参数最终原样透传给 getNodes() 中的assignedNodes(this.options)。便捷过滤器elements()仓库在 node-observation.ts 中提供了一个开箱即用的过滤器const selectElements (value: Node): boolean value.nodeType 1; export const elements (selector?: string): ElementsFilter selector ? value value.nodeType 1 (value as HTMLElement).matches(selector) : selectElements;不带参数调用elements()只保留nodeType 1的元素节点过滤掉文本节点、注释节点等带选择器调用elements(li)在元素节点的基础上再用matches()做 CSS 选择器匹配该工厂函数同时服务于children与slotted两个指令属于共享工具。三、核心用法两种调用方式方式一直接传属性名当组件上已经声明了一个属性配合observable可获得响应式更新可以直接把属性名传给slotted()import { FASTElement, customElement, html, slotted } from microsoft/fast-element; const template htmlMyElement div slot ${slotted(slottedNodes)}/slot /div ; customElement({ name: my-element, template }) export class MyElement extends FASTElement { observable slottedNodes: Node[]; slottedNodesChanged() { // 响应插槽节点变化 } }这段示例取自官方 using-directives.md 文档。关键行为slottedNodes会被填充为该 slot 的assignedNodes()结果Node[]属性用observable装饰后插槽内容变化时属性会动态更新模板中凡是依赖该属性的绑定都会自动重渲染可选的*Changed变更回调如slottedNodesChanged()会在节点变化时被调用与ref、children类似节点在connectedCallback生命周期之后才可用官方文档专门给出提示应优先依赖变更处理器而不是假设节点在connectedCallback中已就绪。方式二传选项对象当需要过滤节点或指定assignedNodes()参数时改用对象形式import { FASTElement, customElement, html, slotted, elements } from microsoft/fast-element; const template htmlMyElement div slot ${slotted({ property: items, filter: elements(my-item) })}/slot /div ;这里filter: elements(my-item)表示只有匹配my-item选择器的元素节点才会被同步到items属性文本节点和其他元素都会被过滤掉。四、运行时行为源码级实现原理slotted()返回的SlottedDirectiveslotted.ts继承了NodeObservationDirective基类四个核心方法构成了完整的观测生命周期export class SlottedDirective extends NodeObservationDirectiveSlottedDirectiveOptions { observe(target: EventSource): void { target.addEventListener(slotEvent, this); // slotEvent slotchange } disconnect(target: EventSource): void { target.removeEventListener(slotEvent, this); } getNodes(target: HTMLSlotElement): Node[] { return target.assignedNodes(this.options); } handleEvent(event: Event): void { const target event.currentTarget as any; this.updateTarget(this.getSource(target), this.computeNodes(target)); } }1. 监听机制slotchange 事件observe()在目标slot元素上注册slotchange事件监听器disconnect()负责移除。当插槽的分配节点集合变化如外部新增/移除子节点、节点被重分配时浏览器触发slotchange指令通过handleEvent触发一次更新。2. 取值机制assignedNodes()getNodes()调用原生assignedNodes(this.options)获取分配节点。传入的flatten等选项会在这里生效。从源码看slotted不使用MutationObserver因此只关心分配到插槽的节点变化而非元素子树的任意变动——这是它与children在语义上的根本区别。3. 过滤与赋值computeNodes / updateTarget基类 node-observation.ts 统一处理过滤与赋值protected updateTarget(source: any, value: ReadonlyArrayany): void { source[this.options.property] value; } protected computeNodes(target: any): Node[] { let nodes this.getNodes(target); if (filter in this.options) { nodes nodes.filter(this.options.filter!); } return nodes; }即先取原始节点 → 若有filter则过滤 → 一次性赋值给source[property]。因为属性是observable的赋值动作本身就会触发 FAST 的观察者通知机制驱动依赖该属性的绑定与变更回调。4. 绑定与解绑生命周期基类的bind/unbindnode-observation.ts完成视图绑定时的初始化与清理bind通过controller.targets[this.targetNodeId]定位到模板中的slot节点将 controller 挂到节点的内部属性上立即用当前节点更新一次属性然后调用observe()注册监听并登记到controller.onUnbind(this)unbind先把属性置为空数组emptyArray再disconnect()移除监听最后清空挂在节点上的 controller 引用——确保视图销毁后不会再有回调泄漏或误更新。5. 防御性细节注意SlottedDirective.handleEvent与测试中都体现了两个工程细节指令把自身作为事件处理器this传给addEventListener并通过event.currentTarget取目标节点避免了额外的闭包分配测试中专门验证了DOM 被 JSON.stringify 时不应抛错slotted.pw.spec.ts 第 402-441 行说明指令在节点上挂载的内部 controller 属性被设计为不可序列化侵入的基类通过id生成的内部属性名_controllerProperty与noop化等机制规避了序列化问题。五、测试用例印证六种行为契约仓库的 slotted.pw.spec.ts 用 Playwright 在真实浏览器中验证了指令的行为契约可作为理解slotted()语义的权威清单测试验证内容returns an SlottedDirectiveslotted(test)返回的确实是SlottedDirective实例creates a behavior by returning itself指令的createBehavior()返回自身无状态无副作用的行为单例gathers nodes from a slotbind 后属性被填充为 slot 的全部分配节点顺序一致gathers nodes from a slot with a filter传入filter: elements(foo-bar)后属性只包含匹配元素updates when slotted nodes change向宿主追加子节点并等待Updates.next()后属性自动同步新增节点updates when slotted nodes change with a filter节点变化后过滤逻辑依然生效clears and unwatches when unboundunbind 后属性被清空且后续 DOM 变化不再更新属性should not throw if DOM stringified对引用做JSON.stringify不抛异常这组测试从创建 → 绑定取值 → 过滤 → 动态更新 → 解绑清理 → 序列化安全六个维度锁定了slotted()的完整行为读者若在集成时遇到异常可对照这些断言排查。六、应用场景与对比选型典型场景感知外部传入的插槽内容slotted()最常见的用途是让组件感知使用者传入的插槽内容。官方文档明确建议优先使用变更处理器*Changed来响应插槽节点变化而不是假设节点在connectedCallback时已经就绪。例如在fast-foundation系列组件中select、listbox、toolbar、breadcrumb等组件都大量依赖slotted观测机制来收集插槽中的选项节点并做出响应相关 API 可参见 fast-foundation 的 slotted 相关 API 文档。与children的选型对比维度childrenslotted观测对象元素的所有子节点含未插槽的 Light DOM 节点分配到指定slot的节点底层机制MutationObserver可选subtreeslotchange事件 assignedNodes()选项差异支持subtree子树观测时必须提供selector支持flatten扁平化后备内容适用场景需要监控容器子树整体变化只关心进入某个插槽的分配结果从 using-directives.md 的提示可知若把children放在模板根template元素上拿到的是自定义元素所有 Light DOM 子节点无论它们是否被插槽分配而slotted只反映分配到特定slot的节点。七、小结slotted()是 FAST Element 中连接外部 Light DOM 内容与组件内部逻辑的关键指令两种传参字符串属性名自动包装或SlottedBehaviorOptions对象可配property、filter、flatten响应式联动配合observable属性与*Changed回调插槽节点变化时属性自动更新源码机制清晰slotchange监听 assignedNodes()取值 可插拔filter由 SlottedDirective 与 NodeObservationDirective 共同实现行为有测试背书slotted.pw.spec.ts 覆盖了从绑定、过滤、动态更新到解绑清理的完整契约。当你需要组件对外部传入了什么内容、什么时候变化做出响应时slotted()就是首选方案——在动手前请先确认组件的属性已用observable声明并优先通过变更处理器响应节点变化。赞分享前端UI组件【免费下载链接】fastThe adaptive interface system for modern web experiences.项目地址https://gitcode.com/gh_mirrors/fa/fast点击查看免费下载相关推荐Fast-Element children() 指令详解在 FASTElement 中观察与同步子节点Fast Element children 指令详解在 FASTElement 中观察与同步子节点 children 是 microsoft/fast el前端UI组件深入解析 microsoft/fast-element 的 ChildrenBehaviorOptions子节点与子树观察的完整配置指南深入解析 microsoft/fast element 的 ChildrenBehaviorOptions子节点与子树观察的完整配置指南 导读 Childr前端UI组件FAST Element 的 ChildrenBehavior.disconnect() 详解子节点观测的拆除与资源回收FAST Element 的 ChildrenBehavior.disconnect 详解子节点观测的拆除与资源回收 导读 在基于 microsoft/fa前端UI组件上一篇Assetic 项目常见问题解决方案下一篇DeepSeek Coder 33B Base未来发展趋势与技术路线图创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考