企业官网建设流程全解析

• 前端
• UI组件

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 variable）：

A function that returns anAnchoredRegionregistration for configuring the component with a DesignSystem. ImplementsanchoredRegionTemplate.

其中：

• anchoredRegionTemplate是 fast-foundation 中导出的模板变量，类型为FoundationElementTemplate<ViewTemplate<AnchoredRegion>>，它定义了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").ViewTemplate<AnchoredRegion, 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: FoundationElementTemplate<ViewTemplate<AnchoredRegion, any>, FoundationElementDefinition>; styles: FoundationElementTemplate<ElementStyles, 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 组件库版本，并关注版本变更日志。

二、安装与注册（Setup）

1. 注册到 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 中导出的样式变量，类型为FoundationElementTemplate<ElementStyles>；在自定义示例中你可以用./my-anchored-region.styles替换成自己的样式。

三、基础用法：始终显示在锚点上方

AnchoredRegion的关键定位属性是anchor（锚点元素的 HTML ID）。下面是一个"始终渲染在锚点上方"的经典示例（来自 组件文档）：

<div id="viewport"> <button id="anchor"> Button is an anchor </button> <fast-anchored-region anchor="anchor" vertical-positioning-mode="locktodefault" vertical-default-position="top"> This shows up above the button </fast-anchored-region> </div>

拆解这个示例：

• anchor="anchor"：告诉组件去查找id="anchor"的元素，并以此为定位参照；
• vertical-positioning-mode="locktodefault"：垂直方向锁定到默认位置，不根据空间做动态调整；
• vertical-default-position="top"：垂直默认位置是锚点上方。

四、完整属性模型：控制定位的 14 个开关

AnchoredRegion的水平与垂直两个轴各自拥有一组对称的属性。下表汇总了全部公开字段及其默认值（依据 AnchoredRegion class 与 组件文档 API 章节）：

对应的 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/top，end即 right/bottom，insetStart/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，以及垂直方向的对称一组。

六个预置常量如下：

这组常量对应的类型均为AnchoredRegionConfig，是组合复杂浮层场景（如菜单、提示框、下拉框）时的快速起点：先取一个预置配置，再按需覆盖个别字段。

六、事件、插槽与运行机制

事件

AnchoredRegion向外派发两个自定义事件（见 组件文档 Events 章节）：

• loaded：当区域加载完成且可见时触发；
• positionchange：当区域位置发生变化时触发。

插槽

组件只有一个默认插槽，用于放置锚定区域的内容（见 AnchoredRegion class）。

定位原理（从源码结构推断）

从 API 结构可以推断其实现要点：

• anchorElement/viewportElement是运行期由anchor/viewport的 ID 解析得到的 DOM 引用，所有定位计算都基于这两个元素在坐标系中的实际包围盒（bounding box）；
• positioning mode决定"是否/如何选边"：locktodefault直接用*DefaultPosition；dynamic会比较锚点两侧（上下/左右）可用空间，配合*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 anchor="menu-anchor" horizontal-positioning-mode="dynamic" vertical-positioning-mode="dynamic" horizontal-default-position="start" vertical-default-position="bottom" horizontal-scaling="anchor" vertical-scaling="fill" fixed-placement auto-update-mode="auto"> <ul><!-- 菜单内容 --></ul> </fast-anchored-region>

效果是：菜单默认从锚点下方开始显示，宽度与锚点对齐；若下方空间不足则自动翻转到上方；配合auto-update-mode="auto"，窗口缩放、滚动时都会重新计算位置。

八、在 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 mode（uncontrolled / locktodefault / dynamic）、default position、scaling（content / anchor / fill）、viewport lock、inset、threshold，配合fixedPlacement与autoUpdateMode，足以覆盖从简单 tooltip 到自适应翻转菜单的绝大多数浮层场景。如果你需要完全自定义的观感，还可以绕过fastAnchoredRegion，直接用AnchoredRegion.compose()组合自己的模板与样式。需要提醒的是，该 API 目前处于预览状态，投入生产前请锁定版本并做好回归验证。

• 前端
• UI组件