前端UI组件【免费下载链接】fastThe adaptive interface system for modern web experiences.项目地址https://gitcode.com/gh_mirrors/fa/fast点击查看免费下载导读本文以 fast-element 1.x API 参考文档 中FASTElement变量的类型签名为骨架深入讲解microsoft/fast-element中最核心的FASTElement基类它既是一个可直接继承的自定义元素基类new () HTMLElement FASTElement又通过from()与define()两个静态助手提供继承扩展 平台注册的完整能力。读完本文你将掌握 FASTElement 的构造原理、三种定义方式继承FASTElement、FASTElement.from()派生、customElement装饰器、PartialFASTElementDefinition全部配置项以及connectedCallback/disconnectedCallback/attributeChangedCallback/$emit等生命周期方法背后的控制器实现。FASTElement 是什么一个最小基类 静态助手的复合变量按 原文档 的定义FASTElement是A minimal base class for FASTElements that also provides static helpers for working with FASTElements. 一个供 FASTElement 使用的最小基类同时提供用于操作 FASTElement 的静态助手。其完整类型签名如下FASTElement: (new () HTMLElement FASTElement) { fromTBase extends { new (): HTMLElement; prototype: HTMLElement; }(BaseType: TBase): new () InstanceTypeTBase FASTElement; defineTType extends Function(type: TType, nameOrDef?: string | PartialFASTElementDefinition | undefined): TType; }解读这个签名可以得到三条核心信息它是一个可调用的构造器new () HTMLElement FASTElement意味着可以直接class MyElement extends FASTElement来创建自定义元素类实例同时具备原生HTMLElement能力与 FAST 扩展能力它附带from静态方法可从任意以HTMLElement为基类的类型派生新的 FAST 元素基类它附带define静态方法以类名或配置对象描述元素将其注册为平台自定义元素并返回类型本身便于链式使用。在仓库源码中这一构造器 静态助手复合变量由 fast-element.ts 中的Object.assign(createFASTElement(HTMLElement), { from, define })组装而成。FASTElementConstructor接口同文件 L163-L199正是这个复合变量完整的 TypeScript 描述。构造器createFASTElement 如何生成一个 FAST 元素类createFASTElementfast-element.ts接收一个基类类型并返回继承它的新类。新建实例时构造函数会先调用super()随后立刻执行ElementController.forCustomElement(this)为该实例绑定唯一的控制器function createFASTElementT extends typeof HTMLElement( BaseType: T, ): { new (): InstanceTypeT FASTElement } { const type class extends (BaseType as any) { public readonly $fastController!: ElementController; public constructor() { super(); ElementController.forCustomElement(this as any); } public $emit(type: string, detail?: any, options?: OmitCustomEventInit, detail): boolean | void { return this.$fastController.emit(type, detail, options); } public connectedCallback(): void { this.$fastController.connect(); } public disconnectedCallback(): void { this.$fastController.disconnect(); } public attributeChangedCallback( name: string, oldValue: string | null, newValue: string | null, ): void { this.$fastController.onAttributeChangedCallback(name, oldValue, newValue); } }; FASTElementDefinition.registerBaseType(type); return type as any; }注意几个实现细节控制器的延迟绑定$fastController声明为readonly但不在构造函数中赋值而是由ElementController.forCustomElement(this)在内部完成注入保证每个实例只对应一个控制器生命周期回调的转发标准自定义元素回调connectedCallback、disconnectedCallback、attributeChangedCallback全部转交给$fastController的connect()、disconnect()、onAttributeChangedCallback()这意味着自定义元素的渲染、样式、绑定和销毁逻辑都由 ElementController 统一接管基类注册每次创建都会调用FASTElementDefinition.registerBaseType(type)把该类型登记为 FAST 基类型供后续compose阶段识别详见下文define一节。FASTElement 接口的实例成员FASTElement接口fast-element.ts向所有实例暴露了四个核心成员对应 API 文档中的子页面成员签名说明$fastControllerreadonly $fastController: Controller负责生命周期与渲染的底层控制器见 fast-element.fastelement._fastcontroller.md$emit(type, detail?, options?)boolean \| void派发自定义 HTML 事件默认bubbles与composed为 true且仅在元素已连接时派发见 fast-element.fastelement._emit.mdconnectedCallback()void元素接入文档时由平台调用见 fast-element.fastelement.connectedcallback.mddisconnectedCallback()void元素移出文档时由平台调用attributeChangedCallback(name, oldValue, newValue)void被观测属性变化时由平台调用从源码看$emit只是$fastController.emit的一层薄封装而ElementController.emit在 element-controller.ts 中预设了{ bubbles: true, composed: true, cancelable: true }的默认事件选项。控制器内部还维护了connecting / connected / disconnecting / disconnected四个生命周期阶段Stages 枚举因此元素的连接、渲染、卸载都能按阶段精细控制。静态助手 from从任意 HTMLElement 基类派生 FAST 元素from的声明如下fromTBase extends { new (): HTMLElement; prototype: HTMLElement; }(BaseType: TBase): new () InstanceTypeTBase FASTElement;实现非常直接fast-element.tsfunction fromTBase extends typeof HTMLElement(BaseType: TBase) { return createFASTElement(BaseType); }即FASTElement.from(SomeHTMLElementSubclass)等价于调用createFASTElement生成一个继承自该基类的新 FAST 元素类。典型应用场景是希望以某个自定义的 HTML 基类而非标准HTMLElement为起点构建 FAST 元素从而复用既有 DOM 能力在类型层面保留InstanceTypeTBase的成员同时混入 FASTElement 的生命周期与渲染能力。TBase extends { new (): HTMLElement; prototype: HTMLElement }的约束确保传入类型是合法的 HTML 元素构造器返回类型new () InstanceTypeTBase FASTElement则在静态类型上精确描述了继承自 TBase 且具备 FAST 能力的新构造器。静态助手 define注册平台自定义元素define是 FAST 元素体系中最常用的入口支持三种重载见 fast-element.ts// 形式一以实例调用FASTElement.define(my-element) / FASTElement.define({ name: my-element, ... }) defineTType(this: TType, nameOrDef: string | PartialFASTElementDefinitionTType, extensions?): PromiseTType; // 形式二显式传入类型FASTElement.define(MyClass, my-element) defineTType(type: TType, nameOrDef?: string | PartialFASTElementDefinitionTType, extensions?): PromiseTType; // 形式三合并重载后的具体实现 define(type, nameOrDef?, extensions?): PromiseTType其工作流程可拆解为四步与 fast-definitions.ts 中的FASTElementDefinition紧密配合兼容参数若nameOrDef是数组则视为extensions并把nameOrDef置为undefined组合定义调用FASTElementDefinition.compose(type, nameOrDef)创建定义元数据compose位于 fast-definitions.ts对已注册的 FAST 基类型会额外派生一层类以避免重复污染原型应用扩展applyFASTElementExtensions(def, def.registry, extensions)在注册前执行传入的扩展回调解析模板并注册通过resolveFASTElementTemplate(def)解析模板——若模板是 Promise异步模板解析场景会等待其完成后才调用def.define().type完成平台注册def.define()本身是幂等的同注册表下不会重复定义见 fast-definitions.ts最后返回TType类型本身便于链式调用。注意define返回的是PromiseTType。由于模板解析可能是异步的例如从远程加载模板元素的实际平台注册customElements.define可能延后调用方若需立即使用元素应await该 Promise。PartialFASTElementDefinitiondefine 的配置对象define的nameOrDef参数接受 PartialFASTElementDefinition 接口其源码定义见 fast-definitions.ts完整配置项如下配置项类型说明默认行为namestring自定义元素的注册名必须无templateElementViewTemplate \| FASTElementTemplateResolver渲染模板可以是html标签模板产物也可以是模板解析器含异步解析无模板则不渲染内容stylesComposableStyles \| ComposableStyles[]关联样式可传css产物或样式数组无attributes(AttributeConfiguration \| string)[]自定义属性列表字符串形式会按命名规则自动生成属性定义默认收集attr装饰器声明shadowOptionsPartialShadowRootOptions \| nullShadow DOM 创建选项缺省为开启的 open shadow root传null则模板渲染到 light DOM见 fast-definitions.tselementOptionsElementDefinitionOptions传给平台customElements.define的选项如extends缺省合并默认值registryCustomElementRegistry注册目标注册表默认全局customElements全局注册表schemaSchema可选 schema声明式模板解析时自动赋值也可手动提供以驱动 schema 扩展无在FASTElementDefinition构造器中fast-definitions.ts这些配置会被转换为属性定义集合attributes、propertyLookup属性名 → 属性定义与attributeLookup属性名 → 属性定义两张查找表、标准observedAttributes数组通过Reflect.defineProperty(type, observedAttributes, ...)挂到类型上以及规范化的样式与 shadow 选项。也就是说define不只是调用customElements.define它同时为元素的响应式属性系统准备好了全部元数据。customElement 装饰器声明式的 define 封装除define静态方法外microsoft/fast-element还提供等价的 customElement 装饰器export declare function customElement( nameOrDef: string | PartialFASTElementDefinition ): (type: Function) void;其实现位于 fast-element.ts本质上就是对define(type, nameOrDef)的调用export function customElement(nameOrDef: string | PartialFASTElementDefinition) { return function (type: ConstructableHTMLElement) { define(type, nameOrDef); }; }两种写法的关系// 写法一静态方法 class MyElement extends FASTElement {} MyElement.define({ name: my-element, template, styles }); // 写法二装饰器等价 customElement({ name: my-element, template, styles }) class MyElement extends FASTElement {}实际项目示例可见 examples/csr/todo-app/src/todo-form.ts其中TodoForm类使用customElement({ name: todo-form, template, styles })完成定义。生命周期方法实战控制器视角的 connected / disconnected / attributeChanged原文档强调这三个回调由平台在元素接入/移出文档、观测属性变化时调用。在 FAST 中这些回调最终都汇入ElementController其典型流程是connectedCallback()→$fastController.connect()触发connected阶段进行首次渲染若needsInitialization为 true、应用样式、绑定模板视图与行为、建立连接disconnectedCallback()→$fastController.disconnect()进入disconnected阶段解绑行为、清理订阅为可能的重新连接做准备attributeChangedCallback(name, oldValue, newValue)→$fastController.onAttributeChangedCallback(...)由属性定义AttributeDefinition完成类型转换、触发响应式更新并调用元素自身的attributeChangedCallback钩子。仓库中的 todo-app 示例 展示了正确覆写生命周期的方式——覆写时必须调用super以保留 FAST 控制器的行为connectedCallback(): void { super.connectedCallback(); this.subscribeToTodos(); this.syncTodos(); } disconnectedCallback(): void { this.unsubscribeFromTodos(); super.disconnectedCallback(); }从声明到注册的完整调用链把以上内容串联起来一次典型的元素定义在仓库中经历如下链路对应 main.ts 示例TodoApp.define({ name: todo-app, template, styles }) └─ FASTElement.define 静态方法 └─ FASTElementDefinition.compose(TodoApp, { ... }) // fast-definitions.ts L555 └─ new FASTElementDefinition(...) // 收集属性/样式/shadow 选项 └─ applyFASTElementExtensions(def, registry, extensions) └─ resolveFASTElementTemplate(def) // 解析模板可能异步 └─ def.define() // 幂等地注册到 registry └─ registry.define(name, type, elementOptions) // 平台 customElements.define若使用装饰器形式如 todo-form.ts则customElement在类定义阶段即调用同一条define链路。三种定义方式继承 静态 define、FASTElement.from()派生、customElement装饰器最终都收敛到FASTElementDefinition.compose → define这一套统一的元数据组装与平台注册管线。总结FASTElement是microsoft/fast-element自定义元素体系的地基它是一个最小基类通过createFASTElement(HTMLElement)生成构造时自动绑定ElementController将connectedCallback、disconnectedCallback、attributeChangedCallback、$emit全部委托给控制器它是一个静态助手容器from()允许从任意 HTMLElement 派生 FAST 基类define()接受字符串或PartialFASTElementDefinition配置对象完成属性收集、模板解析与平台注册且返回PromiseTType以兼容异步模板它与customElement装饰器、FASTElementDefinition元数据体系共同构成声明即用的开发体验。如需进一步查阅相关 API可继续阅读 fast-element API 索引 中的FASTElementDefinition、Controller、ElementViewTemplate等条目或在仓库中直接研读 fast-element.ts、element-controller.ts 与 fast-definitions.ts 的实现。赞分享前端UI组件【免费下载链接】fastThe adaptive interface system for modern web experiences.项目地址https://gitcode.com/gh_mirrors/fa/fast点击查看免费下载相关推荐FASTElement 生命周期机制深入解析基于 microsoft/fast-element 的自定义元素控制器架构FASTElement 生命周期机制深入解析基于 microsoft/fast element 的自定义元素控制器架构 FASTElement 是 FAST前端UI组件FAST Element 架构深度解析从 microsoft/fast-element 导出到自定义元素的完整生命周期FAST Element 架构深度解析从 microsoft/fast element 导出到自定义元素的完整生命周期 导读 本文是 microsoft/前端UI组件Wasp 0.13 依赖管理package.json 中声明 npm 依赖与内部版本锁定规则Wasp 0.13 依赖管理package.json 中声明 npm 依赖与内部版本锁定规则 本篇指南聚焦 Wasp 0.13 版本的依赖管理规则如何在项目前端UI组件上一篇QEMU PCI 串口设备完全指南pci-serial / pci-serial-2x / pci-serial-4x 的规格、用法与源码剖析下一篇MidiEditor免费开源MIDI编辑器的完整指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考