前端UI组件【免费下载链接】fastThe adaptive interface system for modern web experiences.项目地址https://gitcode.com/gh_mirrors/fa/fast点击查看免费下载本文基于 packages/fast-element/docs/migration/fast-html.md 编写全面讲解从microsoft/fast-htmlv1-alpha 迁移到 v1 时涉及的 hydration 标记格式变更、预渲染内容优化、声明式 API 重组Schema / ObserverMap / AttributeMap以及microsoft/fast-build配套工具的行为调整。读者将掌握新旧标记格式对照表、删除prepare()/RenderableFASTElement等废弃 API 的替换写法、declarativeTemplate()attributeMap()observerMap()的函数式声明式 API 用法以及attribute-name-strategy等配置项的迁移要点。一、迁移背景与文档定位microsoft/fast-html是 FASTThe adaptive interface system for modern web experiences生态中负责声明式 HTMLdeclarative HTML运行时的早期实验包。进入 v1 阶段后其声明式能力被正式收编进microsoft/fast-element的模块化架构中声明式运行时发布在microsoft/fast-element/declarative.jshydration水合能力独立为microsoft/fast-element/hydration.js映射扩展拆分为microsoft/fast-element/attribute-map.js与microsoft/fast-element/observer-map.js。本迁移指南fast-html.md记录的就是这一整合过程中的所有破坏性变更与替代方案。适用前提以下所有 API 与行为均以当前仓库FAST v3 分支的实际源码为准适用于从microsoft/fast-htmlv1-alpha 升级到 v1 的开发者若你的工具链还在解析旧版 hydration 标记或仍在使用RenderableFASTElement、TemplateElement等已移除导出则本文的迁移步骤直接可落地。二、Hydration 标记格式v1-alpha → v12.1 标记格式对照表v1 简化了 SSR 输出中的 hydration 标记格式。任何检查或生成 hydration 标记的工具都必须更新为使用新格式。新旧格式对照如下迁移指南原文表格旧标记新标记!-- fe-b$$start$$...$$fe-b --!--fe:b--!-- fe-b$$end$$...$$fe-b --!--fe:/b--!-- fe-repeat$$start$$...$$fe-repeat --!--fe:r--!-- fe-repeat$$end$$...$$fe-repeat --!--fe:/r--data-fe-b0 1 2/data-fe-b-0/data-fe-c-0-3data-feN迁移时需注意新标记不再内嵌索引与 scopeIdSSR 输出体积更小、格式更稳定data-feN中的N表示属性绑定数量取代了旧版以空格分隔的索引列表、逐 factory 枚举、以及起始索引 计数三种写法SSR 与客户端版本必须匹配——旧版 SSR 输出配新版客户端代码或反之都会导致解析失败详见fast-element-3.md中 Hydration Marker Format (v3) 一节该节记录了fe-eb/fe-eb元素边界标记以及HydrationMarkup.*系列 API 的重命名如parseAttributeBinding→parseAttributeBindingCount。2.2microsoft/fast-build的配套行为microsoft/fast-build的 WASM 二进制会自动产出新格式标记。升级后必须重新构建所有 fixtures 与 SSR 输出。从源码结构看microsoft-fast-convertcrates/microsoft-fast-convert承担了声明式模板的语法转换与校验工作它支持webui-prerelease与fast-v3-ts两个输出目标并校验输入必须包含恰好一个带非空name的f-template与恰好一个内层template——这保证了由构建工具产出的 SSR 标记始终符合新格式。三、预渲染内容优化v1-alpha → v13.1 已移除导出与概念移除的导出替代方案RenderableFASTElement直接继承扩展FASTElement移除的概念替代方案prepare()生命周期钩子在connectedCallback中设置状态由响应式系统更新 DOM渲染标记中的defer-hydration属性ElementController.connect()中的模板待定保护template-pending guard渲染标记中的needs-hydration属性ElementController中的hasExistingShadowRoot检测waitForAncestorHydration()不再需要——预渲染内容与连接顺序无关始终正确这里值得注意的是从源码看defer-hydration并未被完全删除而是以deferHydrationAttribute常量保留在enable-hydration.ts中用于视口相交Intersection Observer场景下的按需 hydration 渲染源码注释标注为beta。而needs-hydration的职责则由ElementController的hasExistingShadowRoot标志接管当元素带着既有 shadow root 连接时控制器据此判定走 hydrate 路径而非重新渲染见element-controller.ts中hasExistingShadowRoot true的设置与isPrerenderedPromise 的 resolve 逻辑。3.2 迁移步骤步骤 1RenderableFASTElement→MyComponent.define()declarativeTemplate()将RenderableFASTElement(MyComponent).defineAsync({...})替换为MyComponent.define({...})并在声明式模板场景下使用declarativeTemplate()。如果代码显式观察define()返回的 Promise它会在匹配的f-template提供具体模板之后 resolve// 迁移前 import { RenderableFASTElement } from microsoft/fast-html; RenderableFASTElement(MyComponent).defineAsync({ name: my-component, templateOptions: defer-and-hydrate, }); // 迁移后 MyComponent.define({ name: my-component, template: declarativeTemplate(), });步骤 2移除prepare()方法将所有初始化逻辑迁移到connectedCallback// 迁移前 class MyComponent extends FASTElement { async prepare() { this.data await fetchData(); } } // 迁移后 class MyComponent extends FASTElement { connectedCallback() { super.connectedCallback(); this.loadData(); } async loadData() { this.data await fetchData(); } }步骤 3从服务端渲染标记中移除defer-hydration与needs-hydration!-- 迁移前 -- my-component defer-hydration needs-hydration textHello template shadowrootmodeopen.../template /my-component !-- 迁移后 -- my-component textHello template shadowrootmodeopen.../template /my-component步骤 4用$fastController.isPrerendered检测预渲染组件isPrerendered是一个Promiseboolean在连接时若元素带有声明式 shadow rootDSD则 resolve 为true无论 hydration 是否实际运行connectedCallback() { super.connectedCallback(); this.$fastController.isPrerendered.then(prerendered { if (!prerendered) { this.fetchData(); } }); }3.3 预渲染优化带来的运行时行为当 hydration 启用调用enableHydration()且 FAST 元素连接时带有既有 shadow rootElementController会检测到并执行 hydrate 而非重新渲染。这带来若干优化与迁移指南配套的 README 与源码相互印证用 hydrate 替代 re-render模板调用hydrate()将既有 DOM 节点映射到绑定目标而不是克隆新 DOM声明式模板解析declarativeTemplate()会在define()完成前等待匹配的f-template因此已连接的预渲染元素能用具体模板进行 hydrate属性跳过onAttributeChangedCallback()在元素预渲染的初次 upgrade 期间跳过处理——服务端已渲染出的属性值是正确的绑定跳过HTMLBindingDirective.bind()在视图预渲染时对attribute与booleanAttribute两种 aspect 跳过updateTarget。四、Schema、ObserverMap、AttributeMap 模块化4.1 导入路径变更配置类型从template.ts迁移到各自所属模块。如果你直接从内部路径导入类型请更新导入迁移前迁移后import type { ObserverMapConfig } from ./template.jsimport type { ObserverMapConfig } from ./observer-map.jsimport type { AttributeMapConfig } from ./template.jsimport type { AttributeMapConfig } from ./attribute-map.js公开的声明式导入现在统一走以下路径声明式 APImicrosoft/fast-element/declarative.js替代microsoft/fast-html声明式工具函数microsoft/fast-element/declarative-utilities.js如deepMerge映射扩展microsoft/fast-element/attribute-map.js与microsoft/fast-element/observer-map.js。从declarative/index.ts的导出清单可以看到declarative.js入口汇聚了declarativeTemplate、TemplateParser、Schema、schemaRegistry、各类CachedPath/JSONSchema类型以及FASTElementDefinition、AttributeDefinition等核心类型。4.2 Schema 变更Schema.jsonSchemaMap静态属性被替换为每个Schema实例上的实例级schemaMap私有模块级的schemaRegistry导出用于跨元素查找。迁移前迁移后Schema.jsonSchemaMap.get(my-element)import { schemaRegistry } from microsoft/fast-element; schemaRegistry.get(my-element)源码印证在schema.ts中schemaRegistry被定义为CachedPathMapMapstring, Mapstring, JSONSchema每个Schema实例在构造时将自己注册进该 registry从而实现跨元素$ref解析例如嵌套元素的 schema 引用。4.3 公开导出一览公开入口导出函数式声明式 API导出用途declarativeTemplate()为 FAST 元素定义解析f-template标记attributeMap()定义扩展自动注册attr属性observerMap()定义扩展自动深度观察SchemaJSON schema 构建器类schemaRegistry跨元素 schema 查找的模块级注册表JSONSchemaJSON Schema 类型接口CachedPathMapSchema 注册表映射类型4.4declarativeTemplate()的底层行为从源码看declarativeTemplate()template.ts返回一个FASTElementTemplateResolver其核心逻辑为ensureTemplateElementDefined(definition.registry)——在目标 registry 中惰性定义内部的f-template元素若 registry 中已存在同名元素且不是 FAST 的实现会抛出错误通过declarativeTemplateBridge.requestTemplate(definition)等待匹配的f-template name...连接并发布模板f-template在connectedCallback中注册为 publisher发布时校验内层template数量多于 1 个抛moreThanOneTemplateProvided0 个抛noTemplateProvided解析 schemadefinition.schema ?? new Schema(name)并回写definition.schema经TemplateParser解析出strings与values最终创建ViewTemplate。如果多个匹配的f-template连接第一个连接的提供模板后续重复项不会重新赋值。五、简化后的 ObserverMap 与 AttributeMap 默认行为显式的ObserverMapOption.all与AttributeMapOption.all常量已移除。现在无参调用observerMap()→ 观察所有发现的根属性无参调用attributeMap()→ 映射所有发现的叶子绑定。迁移前迁移后observerMap(ObserverMapOption.all)observerMap()attributeMap(AttributeMapOption.all)attributeMap()源码层面ObserverMapConfig与AttributeMapConfig的默认值逻辑如下observerMapobserver-map.tsObserverMap.defineProperties()遍历schema.getRootProperties()对每个根属性定义Observable属性与${propertyName}Changed处理器配置中的properties字段可逐根属性控制观察范围布尔值或ObserverMapPathNode$observe控制节点自身是否被观察缺省时继承最近祖先的取值根级默认为true。当属性值从undefined变为对象时处理器会用代理Proxy包装对象并递归注入 observable 访问器若目标已被代理包装过则通过deepMerge深合并新值到既有代理中见observer-map-utilities.ts的assignObservables/deepMergeattributeMapattribute-map.tsAttributeMap.defineProperties()只对叶子属性创建attr式访问器——即 schema 条目没有嵌套properties、没有type、没有anyOf的属性如纯{{foo}}绑定。已存在访问器来自attr或observable装饰器的属性会被跳过避免重复定义。两个扩展在解析顺序上当二者同时存在时attribute mapping 先于 observer mapping 运行源码中attributeMapSchemaTransformPriority 0observerMapSchemaTransformPriority 1优先级数值越小越先执行。六、属性名策略默认值变更声明式属性映射的默认attribute-name-strategy现在是camelCase此前为none。例如绑定键{{firstName}}默认映射到firstName属性与first-nameHTML 属性。若你的模板依赖字面属性名可以显式恢复旧行为import { attributeMap } from microsoft/fast-element/attribute-map.js; MyElement.define( { name: my-element, template: declarativeTemplate(), }, [attributeMap({ attribute-name-strategy: none })], );源码实现印证camelToKebab将fooBar转为foo-barnone策略下属性名与属性名均按绑定键原样使用{{foo-bar}}→ 属性foo-bar、属性foo-bar。属性定义通过AttributeDefinition写入 class prototype 的访问器并同步更新observedAttributes数组、definition.attributeLookup/propertyLookup与definition.attributes若定义已注册isDefined还会调用trackLateAttributeDefinition追踪迟到的属性定义。使用microsoft/fast-build时请保持服务端与客户端设置一致fast build --attribute-name-strategynone七、声明式 TemplateElement API 移除公开的声明式 API 已切换为函数式 API。f-template的实现变为内部细节由declarativeTemplate()自动定义使用者不应直接导入或定义它。移除项替代方案TemplateElement公开导出每个 FAST 元素定义上的declarativeTemplate()TemplateElement.define({ name: f-template })无需手动定义declarativeTemplate()在目标 registry 中定义内部 publisherTemplateElement.config(callbacks)/HydrationLifecycleCallbacksenableHydration().whenHydrated(tagName)按标签等待 hydration与enableHydration().whenHydrated()等待当前活跃 hydration 批次TemplateElement.options({ my-el: { attributeMap, observerMap } })定义扩展MyElement.define(definition, [attributeMap(...), observerMap(...)])ElementOptions/ElementOptionsDictionary无替代旧声明式公开面中的AttributeMap/ObserverMap类导出attributeMap()/observerMap()扩展辅助函数及其配置类型Hydration 也不再由microsoft/fast-element自动安装。当需要复用预渲染的声明式 Shadow DOM 时必须在 FAST 元素连接之前调用enableHydration()从microsoft/fast-element/hydration.js导入。源码印证enable-hydration.tsenableHydration()通过ElementController.installHydrationHook安装 hookhook 会调用模板的hydrate()映射既有 DOM 节点并设置isPrerendered/isHydrated两个 Promise函数可被多次安全调用后续调用会把 options 合并进共享的 tracker且默认在初始批次完成后停止对新的预渲染元素进行 hydration——对于流式追加 DSD 的场景可用stopHydration: StopHydration.never保持 hook 活跃此模式下whenHydrated()会因 hydration 永无全局完成点而有意保持 pending。八、Schema 驱动的映射与可选定义 SchemaattributeMap()与observerMap()现在是由 schema 驱动的扩展且与声明式模板解耦声明式与非声明式场景均可从microsoft/fast-element导入import { attributeMap } from microsoft/fast-element/attribute-map.js; import { observerMap } from microsoft/fast-element/observer-map.js;FASTElementDefinition.schema现在是可选的。declarativeTemplate()在解析f-template标记时会自动为其赋值。手动使用 schema 的开发者可以在元素定义中传入 schemaobserverMap()也可以在配置中直接接收 schemaimport { FASTElement, Schema } from microsoft/fast-element; import { observerMap } from microsoft/fast-element/observer-map.js; class MyElement extends FASTElement {} const schema new Schema(my-element); schema.addPath({ rootPropertyName: user, pathConfig: { type: default, parentContext: null, currentContext: null, path: user.name, }, childrenMap: null, }); MyElement.define({ name: my-element }, [observerMap({ schema })]);源码印证Schema.addPathschema.ts根据pathConfig.typedefault/access/repeat/event与childrenMap子元素引用生成anyOf的$ref在根属性 schema 中构建properties、$defs与上下文信息。observerMap扩展在无 template resolver 时直接消费config.schema ?? definition.schema定义观察者若两者都缺失则抛出错误提示使用observerMap({ schema })、在元素定义上提供 schema 或改用declarativeTemplate()。九、迁移检查清单完成microsoft/fast-htmlv1-alpha → v1 迁移后建议逐项核对hydration 标记所有 SSR fixtures 与输出均由microsoft/fast-build重新生成标记为!--fe:b--/!--fe:r--与data-feN格式SSR 与客户端版本一致导出替换RenderableFASTElement→ 继承FASTElementTemplateElement/ElementOptions不再使用Schema.jsonSchemaMap→schemaRegistry生命周期prepare()逻辑迁移至connectedCallback不再调用waitForAncestorHydration()标记清理SSR 标记中移除defer-hydration与needs-hydrationdefer-hydration仍保留为deferHydrationAttribute常量仅用于视口相交按需渲染场景扩展默认行为observerMap(ObserverMapOption.all)→observerMap()attributeMap(AttributeMapOption.all)→attributeMap()属性名策略确认attribute-name-strategy期望为camelCase默认还是none并保持microsoft/fast-build与客户端配置一致hydration 显式启用需要复用预渲染 DSD 时在元素连接前调用enableHydration()流式场景使用StopHydration.never诊断场景可传入hydrationDebugger()。十、进一步阅读迁移指南microsoft/fast-elementv2 → v3含 v3 hydration 标记格式的完整 API 变更READMEFAST Element v3 的声明式 HTML、预渲染优化与 define 扩展用法声明式模板语法与实现细节声明式运行时源码入口declarativeTemplate()与f-template实现Schema 构建与schemaRegistryObserverMap 扩展实现AttributeMap 扩展实现与属性名策略enableHydration()与 hydration hook 安装microsoft/fast-build的语法转换工具microsoft-fast-convert赞分享前端UI组件【免费下载链接】fastThe adaptive interface system for modern web experiences.项目地址https://gitcode.com/gh_mirrors/fa/fast点击查看免费下载相关推荐nnU-Net V1 迁移指南TLDR从 Task 到 Dataset、从 nnUNet_ 到 nnUNetv2_ 的完整升级路径nnU Net V1 迁移指南TLDR从 Task 到 Dataset、从 nnUNet_ 到 nnUNetv2_ 的完整升级路径 导读 本文是 nnU人工智能深度学习计算机视觉医疗健康microsoft/fast-element v3 迁移指南从导入路径、声明式模板到水合标记的完整升级路线microsoft/fast element v3 迁移指南从导入路径、声明式模板到水合标记的完整升级路线 本篇指南系统讲解 microsoft/fast前端UI组件node-fetch API版本迁移终极指南从v1到v3的完整升级路径node fetch API版本迁移终极指南从v1到v3的完整升级路径 node fetch作为将浏览器Fetch API引入Node.js的轻量级模块在v后端创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
