前端UI组件【免费下载链接】fastThe adaptive interface system for modern web experiences.项目地址https://gitcode.com/gh_mirrors/fa/fast点击查看免费下载fastAnchoredRegion是 Microsoft FAST 组件库microsoft/fast-components中用于向 DesignSystem 注册 AnchoredRegion 组件的工厂函数。借助它开发者可以在页面中声明式地放置一个锚定区域容器该容器的内容会相对某个锚点anchor元素定位并能根据锚点与父级 viewport 之间的可用空间自动选择放置方位甚至按可用空间自动调整自身尺寸。读完本文你将掌握fastAnchoredRegion的签名与注册方式、AnchoredRegion的全部定位属性positioning mode、scaling、viewport lock、inset、threshold 等并能基于 FAST Foundation 自行组合出属于你自己的锚定区域组件。一、fastAnchoredRegion 是什么在 FAST 生态中AnchoredRegion是一个位于microsoft/fast-foundation包的容器型自定义元素Custom HTML Element它的核心能力是把内容相对于另一个锚点元素定位同时根据锚点与 viewport 之间的可用空间做自适应翻转或拉伸。而fastAnchoredRegion则是microsoft/fast-components包中导出的注册器registry工厂函数它把一个已经配好模板与样式的AnchoredRegion实现注册进 FAST 的 DesignSystem从而让fast-anchored-region标签在页面中可用。其官方 API 文档定位如下见 fastAnchoredRegion variableA function that returns anAnchoredRegionregistration for configuring the component with a DesignSystem. ImplementsanchoredRegionTemplate.其中anchoredRegionTemplate是 fast-foundation 中导出的模板变量类型为FoundationElementTemplateViewTemplateAnchoredRegion它定义了AnchoredRegion组件内部渲染所需的 DOM 结构默认插槽承载内容同时通过内部节点绑定来支撑定位计算。组件生成的自定义元素标签是fast-anchored-region。函数签名解读API 文档给出的完整签名如下fastAnchoredRegion: ( overrideDefinition?: import(microsoft/fast-foundation).OverrideFoundationElementDefinition{ baseName: string; template: import(microsoft/fast-foundation).FoundationElementTemplate import(microsoft/fast-element).ViewTemplateAnchoredRegion, any, import(microsoft/fast-foundation).FoundationElementDefinition ; styles: import(microsoft/fast-foundation).FoundationElementTemplate import(microsoft/fast-element).ElementStyles, import(microsoft/fast-foundation).FoundationElementDefinition ; } | undefined ) import(microsoft/fast-foundation).FoundationElementRegistry { baseName: string; template: FoundationElementTemplateViewTemplateAnchoredRegion, any, FoundationElementDefinition; styles: FoundationElementTemplateElementStyles, FoundationElementDefinition; }, typeof AnchoredRegion ;它接受一个可选的overrideDefinition参数。如果传入则可以覆盖默认的baseName、template与styles用于对组件进行定制例如替换模板结构或皮肤如果省略则使用microsoft/fast-components内置的默认实现。需要注意的预览状态该 API 在官方文档中被明确标注为This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.也就是说fastAnchoredRegion连同AnchoredRegion的若干属性属于预览性 API可能在后续版本中随反馈而调整。在将其用于生产环境前建议锁定 FAST 组件库版本并关注版本变更日志。二、安装与注册Setup1. 注册到 DesignSystem在microsoft/fast-components中通过provideFASTDesignSystem()获取 DesignSystem 实例然后调用.register(fastAnchoredRegion())即可完成注册import { provideFASTDesignSystem, fastAnchoredRegion } from microsoft/fast-components; provideFASTDesignSystem() .register( fastAnchoredRegion() );执行后fast-anchored-region标签即可在应用中使用。注册是幂等的同一个注册器重复调用不会重复注册。2. 独立使用不依赖组件库注册表如果你的项目只想依赖microsoft/fast-foundation而不引入整套microsoft/fast-components皮肤可以像文档的Create your own design一节那样直接组合 foundation 的类与模板import { AnchoredRegion, anchoredRegionTemplate as template, } from microsoft/fast-foundation; import { anchoredRegionStyles as styles } from ./my-anchored-region.styles; export const myAnchoredRegion AnchoredRegion.compose({ baseName: anchored-region, template, styles, });这里AnchoredRegion类继承自FoundationElement见 AnchoredRegion class因此继承了template、styles、$presentation等 FoundationElement 成员anchoredRegionStyles是 fast-components 中导出的样式变量类型为FoundationElementTemplateElementStyles在自定义示例中你可以用./my-anchored-region.styles替换成自己的样式。三、基础用法始终显示在锚点上方AnchoredRegion的关键定位属性是anchor锚点元素的 HTML ID。下面是一个始终渲染在锚点上方的经典示例来自 组件文档div idviewport button idanchor Button is an anchor /button fast-anchored-region anchoranchor vertical-positioning-modelocktodefault vertical-default-positiontop This shows up above the button /fast-anchored-region /div拆解这个示例anchoranchor告诉组件去查找idanchor的元素并以此为定位参照vertical-positioning-modelocktodefault垂直方向锁定到默认位置不根据空间做动态调整vertical-default-positiontop垂直默认位置是锚点上方。四、完整属性模型控制定位的 14 个开关AnchoredRegion的水平与垂直两个轴各自拥有一组对称的属性。下表汇总了全部公开字段及其默认值依据 AnchoredRegion class 与 组件文档 API 章节属性类型默认值说明anchorstring锚点元素的 HTML ID区域相对它定位viewportstringviewport 元素的 HTML ID区域相对它计算可用空间horizontalPositioningModeAxisPositioningModeuncontrolled水平方向定位逻辑locktodefault强制默认位置dynamic按可用空间决策uncontrolled不控制水平定位horizontalDefaultPositionHorizontalPositionunset水平默认位置相对锚点horizontalViewportLockbooleanfalse水平方向上区域是否保持留在 viewport 内即脱离锚点跟随horizontalInsetbooleanfalse水平方向上区域是否与锚点重叠horizontalThresholdnumber—分配给默认位置的空间窄到多少时改选最宽区域进行布局horizontalScalingAxisScalingModecontent区域宽度如何计算verticalPositioningModeAxisPositioningModeuncontrolled垂直方向定位逻辑取值同上verticalDefaultPositionVerticalPositionunset垂直默认位置相对锚点verticalViewportLockbooleanfalse垂直方向上区域是否保持留在 viewport 内verticalInsetbooleanfalse垂直方向上区域是否与锚点重叠verticalThresholdnumber—分配给默认位置的空间矮到多少时改选最高区域进行布局verticalScalingAxisScalingModecontent区域高度如何计算fixedPlacementbooleanfalse是否使用 CSSposition: fixed定位否则使用position: absolute。fixed 可让区域突破父容器约束autoUpdateModeAutoUpdateModeanchor触发区域重新计算定位的事件源对应的 HTML 属性名均为 kebab-case连字符命名例如horizontal-positioning-mode、vertical-default-position、fixed-placement、auto-update-mode等见 组件文档 Attributes 章节。除上述属性外组件还暴露了以下只读/派生成员anchorElement: HTMLElement | null——解析出的锚点 DOM 元素viewportElement: HTMLElement | null——解析出的 viewport DOM 元素verticalPosition: AnchoredRegionPositionLabel | undefined——当前垂直方位horizontalPosition: AnchoredRegionPositionLabel | undefined——当前水平方位update: () void——手动触发一次位置重算。枚举类型取值这些属性背后的联合类型见 fast-foundation API 文档 中的类型条目如下AxisPositioningMode uncontrolled | locktodefault | dynamic定义locktodefault强制使用默认位置dynamic根据可用空间自动选边uncontrolled完全不做该轴的控制。AxisScalingMode anchor | fill | content定义anchor让区域尺寸跟随锚点fill让区域尺寸填满可用空间content让区域尺寸由内容决定。HorizontalPosition start | end | left | right | center | unset定义。VerticalPosition top | bottom | center | unset定义。AutoUpdateMode anchor | auto定义anchor仅在锚点尺寸变化时重新定位默认auto在以下任一情况触发重算——显式调用update()、锚点尺寸变化、窗口 resize、viewport resize、文档内任意滚动事件。AnchoredRegionPositionLabel start | insetStart | insetEnd | end | center定义描述区域相对锚点的方位按轴解读时start即 left/topend即 right/bottominsetStart/insetEnd表示区域与锚点重叠inset时偏向 start/end 的方位。五、预置 Flyout 方案AnchoredRegionConfig为了快速实现常见的浮层flyout/popover效果microsoft/fast-foundation提供了AnchoredRegionConfig接口与一组预置配置常量见 AnchoredRegionConfig interface 与 组件文档 API 章节。AnchoredRegionConfig是一个用来存储与常见 flyout 定位方案对应的锚定区域配置的工具接口其字段与AnchoredRegion的公开属性一一对应autoUpdateMode、fixedPlacement、horizontalDefaultPosition、horizontalInset、horizontalPositioningMode、horizontalScaling、horizontalThreshold、horizontalViewportLock以及垂直方向的对称一组。六个预置常量如下常量行为FlyoutPosTop始终在锚点上方宽度匹配锚点高度由内容决定FlyoutPosBottom始终在锚点下方宽度匹配锚点高度由内容决定FlyoutPosTallest根据可用空间自动选择上方或下方宽度匹配锚点高度由内容决定FlyoutPosTopFill始终在锚点上方宽度匹配锚点高度填满可用空间FlyoutPosBottomFill始终在锚点下方宽度匹配锚点高度填满可用空间FlyoutPosTallestFill根据可用空间自动选择上方或下方宽度匹配锚点高度填满可用空间这组常量对应的类型均为AnchoredRegionConfig是组合复杂浮层场景如菜单、提示框、下拉框时的快速起点先取一个预置配置再按需覆盖个别字段。六、事件、插槽与运行机制事件AnchoredRegion向外派发两个自定义事件见 组件文档 Events 章节loaded当区域加载完成且可见时触发positionchange当区域位置发生变化时触发。插槽组件只有一个默认插槽用于放置锚定区域的内容见 AnchoredRegion class。定位原理从源码结构推断从 API 结构可以推断其实现要点anchorElement/viewportElement是运行期由anchor/viewport的 ID 解析得到的 DOM 引用所有定位计算都基于这两个元素在坐标系中的实际包围盒bounding boxpositioning mode决定是否/如何选边locktodefault直接用*DefaultPositiondynamic会比较锚点两侧上下/左右可用空间配合*Threshold决定何时切换到更宽/更高的区域scaling决定尺寸来源content由内容撑开、anchor跟随锚点、fill拉伸到可用空间horizontalViewportLock/verticalViewportLock为 true 时区域会被拉回 viewport 边界内可能脱离锚点fixedPlacement为 true 时采用position: fixed可以突破父容器的 overflow/裁剪约束——这正是实现菜单、tooltip 弹出而不被中间层容器截断的关键开关autoUpdateMode控制重算触发源update()方法始终可以强制触发一次重算。七、常见组合把六种 Flyout 用起来以预置常量为基础一个典型的自适应下拉菜单场景可以这样组织import { FlyoutPosTallestFill, AnchoredRegionConfig, } from microsoft/fast-foundation; // 使用最高侧 填满的配置并进一步定制 const menuConfig: AnchoredRegionConfig { ...FlyoutPosTallestFill, fixedPlacement: true, autoUpdateMode: auto, horizontalViewportLock: true, verticalViewportLock: true, };fast-anchored-region anchormenu-anchor horizontal-positioning-modedynamic vertical-positioning-modedynamic horizontal-default-positionstart vertical-default-positionbottom horizontal-scalinganchor vertical-scalingfill fixed-placement auto-update-modeauto ul!-- 菜单内容 --/ul /fast-anchored-region效果是菜单默认从锚点下方开始显示宽度与锚点对齐若下方空间不足则自动翻转到上方配合auto-update-modeauto窗口缩放、滚动时都会重新计算位置。八、在 1.x 文档体系中的位置本主题涉及的 API 文档均位于仓库的 sites/website/src/docs/1.x/api 目录下是 1.x 版本线 API 文档API Documenter 自动生成的一部分入口fast-components 包索引、fast-foundation 包索引组件实现fastAnchoredRegion变量、anchoredRegionStyles 样式类与配置AnchoredRegion 类、AnchoredRegionConfig 接口、anchoredRegionTemplate 模板组件使用指南fast-anchored-region 组件文档。在仓库的其他示例中也能看到锚定/浮层类组件的典型落地场景例如 Blazor 集成文档 中对组件使用的说明更多相关组件如fast-avatar的fast-anchored-region引用可参见 fast-components.allcomponents。九、小结fastAnchoredRegion是 FAST 组件库中锚定布局能力的标准入口通过 DesignSystem 注册它把 foundation 层的AnchoredRegion类、模板与样式完整地带到你的应用中。真正强大的是其轴对称的属性模型——positioning modeuncontrolled / locktodefault / dynamic、default position、scalingcontent / anchor / fill、viewport lock、inset、threshold配合fixedPlacement与autoUpdateMode足以覆盖从简单 tooltip 到自适应翻转菜单的绝大多数浮层场景。如果你需要完全自定义的观感还可以绕过fastAnchoredRegion直接用AnchoredRegion.compose()组合自己的模板与样式。需要提醒的是该 API 目前处于预览状态投入生产前请锁定版本并做好回归验证。赞分享前端UI组件【免费下载链接】fastThe adaptive interface system for modern web experiences.项目地址https://gitcode.com/gh_mirrors/fa/fast点击查看免费下载相关推荐FAST 组件注册实战fastTab 与 Tabs 组件在 DesignSystem 中的集成指南FAST 组件注册实战fastTab 与 Tabs 组件在 DesignSystem 中的集成指南 fastTab 是 microsoft/fast com前端UI组件FAST 组件实战fastTextArea 注册函数与 fast-text-area 多行文本域组件全面解析FAST 组件实战fastTextArea 注册函数与 fast text area 多行文本域组件全面解析 fastTextArea 是 FAST 1.x前端UI组件FAST 组件 fastSelect注册与定制 fast-select 下拉选择组件完整指南FAST 组件 fastSelect注册与定制 fast select 下拉选择组件完整指南 导读 本文围绕 microsoft/fast componen前端UI组件上一篇Material Theme开发者指南如何贡献主题变体与扩展功能下一篇在iPhone上畅玩Minecraft Java版零门槛指南PojavLauncher从安装到优化全流程创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考