FAST 设计系统注册入口 provideFASTDesignSystem() 完全指南：签名、参数与 DesignSystem 链式配置

前端UI组件【免费下载链接】fastThe adaptive interface system for modern web experiences.项目地址https://gitcode.com/gh_mirrors/fa/fast点击查看免费下载provideFASTDesignSystem()是 FAST 组件库microsoft/fast-components面向应用侧的统一设计系统入口函数调用它即可为指定元素获取或创建 DesignSystem 实例并通过返回的链式 API 完成组件注册与全局配置。读完本文你将掌握该函数的完整签名语义、底层DesignSystem.getOrCreate实现原理、基于 element 参数的多作用域挂载方式以及withPrefix、withShadowRootMode、withElementDisambiguation等全套配置实战方案。函数签名与语义provideFASTDesignSystem由microsoft/fast-components导出其 API 契约定义在仓库的 fast-components.providefastdesignsystem.md 中export declare function provideFASTDesignSystem(element?: HTMLElement): DesignSystem;参数说明参数类型说明elementHTMLElement可选将设计系统挂载root于该元素上。不传时默认挂载在document.body上。返回值返回DesignSystem实例即一个FAST Design System。它本质上是设计系统功能的 API 网关在 fast-foundation.designsystem.md 中可以看到其完整形状DesignSystem: Readonly{ tagFor(type: Constructable): string; responsibleFor(element: HTMLElement): DesignSystem; getOrCreate(node?: Node | undefined): DesignSystem; }这个返回实例支持链式调用register、withPrefix、withShadowRootMode、withElementDisambiguation、withDesignTokenRoot等方法每个方法都返回DesignSystem自身以便继续链式调用这也是下文所有实战示例能够写成.register(...)链的基础。函数语义该函数的核心语义是为指定元素提供一个设计系统——如果该元素上已经存在设计系统则直接返回已创建的实例否则新建一个。这正是提供者函数provider function设计模式在 FAST 中的落地。用一句话概括provideFASTDesignSystem()是 FAST Frame 官方对底层DesignSystem.getOrCreate()的封装。它在 FAST 架构中的位置要理解这个函数为何存在需要先了解 FAST 的设计系统分层思想。仓库的 creating-a-component-library.md 给出了四层模型foundation componentsmicrosoft/fast-foundation提供的可复用组件类与模板与任何设计系统无关追求最大灵活性design system在 foundation 之上叠加设计系统自身的独特主张样式、元素前缀、design token、主题色等导出组件注册函数供应用选用application应用只注册自己需要的组件features仅使用应用中已注册的组件并通过 design token 定制功能。FAST Frame即microsoft/fast-components处于第二层。它的组件必须先注册进一个DesignSystem才能在 HTML 中作为自定义元素使用——这正是provideFASTDesignSystem()的职责所在。按照 fast-frame.md 的说明Web 组件在用于 HTML 之前必须与DesignSystem完成注册。底层原理DesignSystem.getOrCreate 与提供者函数从源码与文档可以确认provideFASTDesignSystem()的底层机制与自定义设计系统的提供者函数完全同构。creating-a-component-library.md 展示了社区如何为自定义设计系统编写等价的提供者函数export function provideSpecialDesignSystem(element?: HTMLElement): DesignSystem { return DesignSystem.getOrCreate(element).withPrefix(special); }该文档明确解释了底层DesignSystem.getOrCreate的行为获取直接附着在指定元素上的设计系统若不存在则创建默认情况下未提供 element在document.body上创建设计系统。由此可以推断provideFASTDesignSystem()的内部实现遵循同样的getOrCreate(element)模式只是额外固化了 FAST Frame 的默认配置如默认前缀fast。提供者函数的意义在于把元素查找与创建的逻辑抽象成更友好的 API同时允许把默认配置例如默认元素前缀烘焙进函数内部。基本用法注册组件并投入页面安装npm install --save microsoft/fast-components或使用 yarnyarn add microsoft/fast-components注册单个组件按 components/getting-started.md 的标准做法导入组件注册函数与提供者函数然后链式注册import { fastButton, provideFASTDesignSystem } from microsoft/fast-components; provideFASTDesignSystem() .register( fastButton() );register()方法会把组件与服务注册到设计系统及其底层的依赖注入容器中见 designsystem.register.md从而向平台注册自定义元素。注册完成后组件即可像原生 HTML 元素一样使用fast-buttonHello world/fast-button一键注册全部组件cheat-sheet.md 提供了快捷方式——通过allComponents一次性注册全部组件import { allComponents, provideFASTDesignSystem } from microsoft/fast-components; provideFASTDesignSystem().register(allComponents);按需注册与 tree-shaking官方文档特别提醒当使用 Webpack、Rollup 等支持 tree-shaking 的打包器时应逐个导入并注册组件确保未使用的组件被摇树优化剔除出产物见 components/getting-started.md。这是provideFASTDesignSystem().register(...)按参数逐个接收注册项register(...params: any[])的重要原因。防 FOUC未定义样式闪动自定义元素在升级完成前可能没有样式浏览器渲染它们会造成未样式内容闪动FOUC。fast-frame.md 建议由消费应用自行添加如下 CSS:not(:defined) { visibility: hidden; }注意组件自身不会做这件事必须由应用层应用这段样式。CDN 方式若不想走 npm 构建流程可以使用 CDN 上预打包的模块脚本typemodule例如script typemodule srchttps://cdn.jsdelivr.net/npm/microsoft/fast-components/dist/fast-components.min.js/script从 CDN 使用时无需手动调用provideFASTDesignSystem()——CDN 脚本内部已经自动完成设计系统初始化与全部组件注册见 components/getting-started.md。生产环境建议锁定具体版本号避免始终指向最新发布。element 参数设计系统的作用域控制element参数是provideFASTDesignSystem()最具价值的可选项。它决定了设计系统被扎根root在哪棵 DOM 子树之上不传参设计系统默认建立在document.body注册的组件在整个文档中可用这是绝大多数单页应用的用法传元素设计系统只作用于以该元素为根的子树。这为多设计系统共存、分区定制主题提供了可能——例如页面的不同区域可以各自调用provideFASTDesignSystem(sectionEl)并注册不同的组件配置。设计系统根的概念还延伸到 design token 的发射位置链式方法withDesignTokenRoot(root)可覆盖默认 CSS 自定义属性design token 默认值的发射根节点其签名见 designsystem.withdesigntokenroot.mdwithDesignTokenRoot(root: HTMLElement | Document | null): DesignSystem;其中传入null会禁用 DesignToken 的自动注册。这一方法让provideFASTDesignSystem()返回的实例在多根应用场景下拥有精确控制 token 作用域的能力。链式配置五个常用 DesignSystem 配置方法fast-frame.md 指出DesignSystem 是绝大多数组件配置的入口可以控制自定义元素在浏览器中的定义方式、使用的模板与样式表、以及同名自定义元素的消歧策略。以下配置作用于注册到该设计系统的所有组件除非该选项在组件注册时被显式指定组件级配置优先级更高。withPrefix自定义元素前缀Web 组件Custom Elements必须遵循 HTML 命名规范——元素名必须包含-。FAST 默认给所有注册元素加上fast前缀因此fastButton注册后对应fast-button。如需整体更换前缀使用withPrefix签名见 designsystem.withprefix.mdimport { fastButton, provideFASTDesignSystem } from microsoft/fast-components; provideFASTDesignSystem() .withPrefix(faster) .register(fastButton())此后元素在 HTML 中写作faster-buttonClick me!/faster-buttonwithShadowRootMode统一关闭 Shadow DOM组件开发者通常以open模式推荐且默认创建 Shadow Root但可通过withShadowRootMode全局改为closed签名见 designsystem.withshadowrootmode.mdprovideFASTDesignSystem() .withShadowRootMode(closed) .register(/* ... */)withElementDisambiguation同名元素消歧默认行为下已注册过的元素名不会向平台重复注册但其元素定义回调仍会被调用从而允许在所属 DOM 子树内定义备选外观样式与模板。fast-frame.md 强调最佳实践是避免重复注册同一组件若架构上难以避免可提供自定义回调处理。回调会收到三个参数被注册的标签名、当前注册的类型、该标签已注册的类型并可返回三种值string返回一个字符串作为元素的新注册名ElementDisambiguation.definitionCallbackOnly默认回调的返回值不重新注册元素但允许其回调运行并为该元素定义备选外观。注意同一元素存在多种外观会触发较慢的渲染路径非必要不要使用ElementDisambiguation.ignoreDuplicate完全忽略重复元素注册时不采取任何动作。示例签名见 designsystem.withelementdisambiguation.mdprovideFASTDesignSystem() .withElementDisambiguation((nameAttempt, typeAttempt, existingType) { if (nameAttempt foo) { return bar; } return ElementDisambiguation.ignoreDuplicate; }) .register(/* ... */)组件级配置在 register 时覆盖以上 DesignSystem 级配置作用于全部组件但每个选项也可以在组件注册时单独配置或覆盖组件级配置优先于设计系统级配置见 fast-frame.md// 组件级前缀 provideFASTDesignSystem() .register( fastButton({ prefix: faster }) ); // 组件级模板 provideFASTDesignSystem() .register( fastButton({ template: html pA completely new template/p }) ); // 组件级样式完全替换 provideFASTDesignSystem() .register( fastButton({ styles: css /* completely replace the original styles */ }) ); // 组件级样式在原始样式上扩展 provideFASTDesignSystem() .register( fastButton({ styles: (ctx, def) css ${buttonStyles(ctx, def)} /* add your style augmentations here */ }) ); // 组件级 Shadow 配置mode delegatesFocus provideFASTDesignSystem() .register( fastButton({ shadowOptions: { mode: closed, delegatesFocus: true } }) );官方文档同时提示当前样式与模板函数存在一处轻微的类型缺陷扩展原始样式时可能需要将第二个参数强转例如${buttonStyles(ctx, def as any)}。在框架集成中使用React 示例provideFASTDesignSystem()返回的 DesignSystem 也是框架集成如 React的接入点。integrations/react.md 展示了将其直接传给provideReactWrapper的用法import { provideFASTDesignSystem, fastCard, fastButton } from microsoft/fast-components; import { provideReactWrapper } from microsoft/fast-react-wrapper; import React from react; const { wrap } provideReactWrapper( React, provideFASTDesignSystem() ); export const FastCard wrap(fastCard()); export const FastButton wrap(fastButton())随后即可在 JSX 中使用封装后的 React 组件FastCard h2FAST React/h2 FastButton appearanceaccent onClick{() console.log(clicked)}Click Me/FastButton /FastCard这一模式说明提供者函数的返回值不只服务于原生注册也是各类集成层React/Angular/Svelte/Vue 等详见 cheat-sheet.md 的集成列表复用同一个 DesignSystem 实例的桥梁。自定义设计系统照搬提供者函数模式如果要在 FAST Frame 之外构建自己的设计系统可完全复刻provideFASTDesignSystem()的模式creating-a-component-library.md 建议先用microsoft/fast-foundation的基础组件类与模板组合出自己的组件import { Button, buttonTemplate as template, } from microsoft/fast-foundation; import { buttonStyles as styles } from ./special-button.styles; export const specialButton Button.compose({ baseName: button, template, styles, shadowOptions: { delegatesFocus: true, }, }); export const buttonStyles styles;然后导出提供者函数并注册组件provideSpecialDesignSystem() .register( specialButton() );至此provideFASTDesignSystem()所代表的设计系统提供者模式在自定义场景下得到了完整闭环入口函数负责获取/创建设计系统并固化默认配置链式注册负责登记组件与覆盖配置element 参数负责划定作用域——三者共同构成了 FAST 自适应界面系统对外暴露的最主要编程接口。赞分享前端UI组件【免费下载链接】fastThe adaptive interface system for modern web experiences.项目地址https://gitcode.com/gh_mirrors/fa/fast点击查看免费下载相关推荐FAST 组件库 fastSliderLabel 注册函数详解在 DesignSystem 中配置 fast-slider-labelFAST 组件库 fastSliderLabel 注册函数详解在 DesignSystem 中配置 fast slider label fastSlider前端UI组件FAST 1.x fastDesignSystemProvider 全面解析DesignSystem 注册与设计令牌分发实战FAST 1.x fastDesignSystemProvider 全面解析DesignSystem 注册与设计令牌分发实战 fastDesignSystem前端UI组件FAST 组件库 fastDisclosure 注册函数完全指南从 DesignSystem 注册到自定义 Disclosure 组件FAST 组件库 fastDisclosure 注册函数完全指南从 DesignSystem 注册到自定义 Disclosure 组件 本文以 micros前端UI组件上一篇Podman --volumes-from 选项完全指南容器间共享卷的原理、用法与源码实现下一篇League Akari英雄联盟玩家的智能本地化效率工具完全指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考