前端UI组件【免费下载链接】fastThe adaptive interface system for modern web experiences.项目地址https://gitcode.com/gh_mirrors/fa/fast点击查看免费下载horizontalViewportLock是microsoft/fast-foundation中AnchoredRegion类的一个布尔型公开属性对应 HTML 属性horizontal-viewport-lock。开启后锚定区域anchored region会在水平轴上脱离锚点元素强制保持自身完全位于视口范围内——这是实现菜单、下拉框、浮层和 Tooltip 不随锚点被裁切的关键开关。本文将基于本仓库sites/website/src/docs/1.x/api/下的 API 文档结合组件使用指南完整讲解该属性的语义、默认行为、配置方式及其与定位模式、缩放策略、verticalViewportLock的配合用法。一、属性定位horizontalViewportLock 在 AnchoredRegion API 中的位置horizontalViewportLock属于AnchoredRegion类。该类定义在microsoft/fast-foundation包中声明形式为export declare class AnchoredRegion extends FoundationElement即它是一个继承自FoundationElement的自定义 HTML 元素Custom HTML Element承载了锚定区域的全部定位能力。在 AnchoredRegion 类文档 中该类暴露了如下关键属性属性类型默认值说明anchorstring锚点元素的 HTML IDviewportstring视口元素的 HTML IDhorizontalPositioningModeAxisPositioningModeuncontrolled水平放置逻辑locktodefault强制默认位置dynamic按可用空间决策uncontrolled不控制horizontalDefaultPositionHorizontalPositionunset相对锚点的默认水平位置horizontalViewportLockbooleanfalse是否在水平轴上保持区域位于视口内即脱离锚点horizontalInsetbooleanfalse区域是否在水平轴上与锚点重叠horizontalThresholdnumber—默认位置可用空间窄到何种程度时改选最宽区域布局horizontalScalingAxisScalingModecontent区域宽度如何计算fixedPlacementbooleanfalse是否使用position: fixed定位以突破父容器从该表可以清楚看到horizontalViewportLock的默认值为false即默认情况下区域只跟随锚点定位不会主动保证自身留在视口内。本文主讲的属性页面对应的 API 文档位于 fast-foundation.anchoredregion.horizontalviewportlock.md其完整的属性列表可见 fast-foundation.anchoredregion.md。二、属性签名与语义脱离锚点、保持可见该属性的 API 文档给出了精确的类型签名与语义描述horizontalViewportLock: boolean;官方描述Remarks 与字段说明Whether the region remains in the viewport (ie. detaches from the anchor) on the horizontal axis 该区域在水平轴上是否保持位于视口内即是否脱离锚点同时文档明确标注了它在 HTML 层面的映射HTML Attribute:horizontal-viewport-lock理解这个语义的关键在于“脱离锚点detaches from the anchor”未启用false默认区域的位置完全以锚点元素为基准计算跟随锚点的水平坐标排布。如果锚点靠近视口边缘区域可能被视口边界裁切或出现水平滚动条。启用true当按照锚点计算的水平位置会导致区域超出视口时区域会“脱离”锚点被约束回视口边界以内保证自身的水平方向内容始终完整可见。该属性与垂直方向上的对称属性verticalViewportLock相互独立两者分别控制水平轴与垂直轴详见 verticalViewportLock 属性文档对应 HTML 属性vertical-viewport-lock。因此一个锚定区域可以做到“水平锁视口、垂直跟随锚点”或任意组合从而适配不同交互浮层的需求。三、配置方式属性Property与 HTML 特性Attribute在 FAST 组件体系中属性与 HTML 特性通过 kebab-case 自动映射。horizontalViewportLock对应的 HTML 特性为horizontal-viewport-lock两者等价选择哪种写法取决于使用场景在 HTML / 模板中声明声明式fast-anchored-region anchoranchor horizontal-viewport-lock vertical-viewport-lock Floating content that always stays fully in the viewport /fast-anchored-region由于该属性为布尔类型HTML 上只需书写特性名即可视为true布尔特性语义。在脚本中通过属性赋值命令式const region document.querySelector(fast-anchored-region); region.horizontalViewportLock true;在组件自定义组成时通过组合 API 配置参考 fast-anchored-region 组件指南 中的“Create your own design”部分可以基于AnchoredRegion.compose()创建自定义锚定区域此时模板中的特性声明直接决定该属性行为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, });四、在 AnchoredRegionConfig 配置对象中的体现horizontalViewportLock不仅存在于组件类上还作为AnchoredRegionConfig接口的可选只读属性出现。该接口的 API 文档fast-foundation.anchoredregionconfig.md将其描述为A utility interface to store anchored region configurations that correspond to various common flyout positioning schemes 一个用于存储对应各种常见浮出层flyout定位方案的锚定区域配置的工具接口其声明形式为readonly horizontalViewportLock?: boolean;也就是说AnchoredRegionConfig是一种“定位方案”的描述对象可以用它预置一组常用的浮出层定位预设。在 fast-anchored-region.mdx 组件指南 的 Variables 表格中可以看到 FAST 预置的六种浮出层定位变量变量名行为FlyoutPosTop始终位于锚点上方宽度匹配锚点高度由内容决定FlyoutPosBottom始终位于锚点下方宽度匹配锚点高度由内容决定FlyoutPosTallest根据可用空间在上下之间选择宽度匹配锚点高度由内容决定FlyoutPosTopFill始终位于锚点上方宽度匹配锚点高度按可用空间填充FlyoutPosBottomFill始终位于锚点下方宽度匹配锚点高度按可用空间填充FlyoutPosTallestFill根据可用空间在上下之间选择宽度匹配锚点高度按可用空间填充这些变量类型均为AnchoredRegionConfig。当你在自己的浮层组件中复刻类似的“配置方案”时可以在配置对象中显式加入horizontalViewportLock以及verticalViewportLock、horizontalInset、horizontalThreshold、horizontalScaling等从而把“是否锁视口”作为方案的一部分打包复用而无需在每个实例上重复书写 HTML 特性。五、实战水平视口锁定的典型应用场景5.1 基础用法结合定位模式使用先完成组件注册。参考组件指南的 Setup 部分import { provideFASTDesignSystem, fastAnchoredRegion } from microsoft/fast-components; provideFASTDesignSystem() .register( fastAnchoredRegion() );注册完成后即可在页面中使用。以下示例来自组件指南的 Usage 部分展示了一个“始终渲染在锚点上方”的区域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若希望该区域在锚点贴近视口左/右边缘时仍不溢出可补充水平轴约束fast-anchored-region anchoranchor vertical-positioning-modelocktodefault vertical-default-positiontop horizontal-viewport-lock Content that never overflows the viewport horizontally /fast-anchored-region5.2 与水平定位模式的配合要点horizontalViewportLock并非独立决定水平位置它是在其他水平定位属性已经确定候选位置后对“是否允许区域超界”的最终约束。实践中通常与以下属性协同horizontal-positioning-mode取值为locktodefault强制默认位置、dynamic按可用空间决策、uncontrolled不控制。当锚点位于视口边缘时dynamic会优先把区域摆放到空间更大的一侧而horizontal-viewport-lock则负责在空间依然不足时把区域“拉回”视口内。horizontal-default-positionHorizontalPosition类型默认unset定义相对锚点的默认水平方位。horizontal-threshold默认位置可用空间窄到何种程度时改选最宽区域number类型。horizontal-inset布尔值默认false定义区域是否在水平轴上与锚点重叠。horizontal-scalingAxisScalingMode类型默认content决定区域宽度是按内容还是按可用空间计算。一个可推断的实践原则当horizontal-scaling与可用空间相关如填充式布局且锚点靠近视口边缘时horizontal-viewport-lock的价值最大——它能保证即使布局模式把区域推向了超界方向最终呈现依然完整可见。5.3 典型浮层场景horizontal-viewport-lock/vertical-viewport-lock最常见的落地场景是各种浮层组件下拉菜单 / 组合框浮层锚点输入框靠近视口右侧时下拉面板若不锁定视口会被横向裁切出现横向滚动条。上下文菜单右键锚点位于视口角落时菜单应自动收缩到视口内而非超出边界。气泡提示 / Tooltip详见下文第六节FAST 的fast-tooltip组件直接复用了这对属性。弹出式日历、选择器面板通过fixed-placement突破父容器裁剪后视口锁定是防止面板越界的最后一道防线。需要说明的是fixedPlacement属性默认false控制区域使用position: fixed可突破父容器还是position: absolute。当使用fixed定位时区域不再受父容器的裁剪影响此时“视口锁定”的约束作用更纯粹地作用于浏览器视口本身。六、相关组件fast-tooltip 中的 horizontalViewportLockFAST 的 Tooltip 组件在其 API 中同样暴露了horizontalViewportLock与verticalViewportLock两个布尔属性详见 fast-tooltip 组件指南 的 Fields 表格属性类型说明horizontalViewportLockbooleanControls if the tooltip will always remain fully in the viewport on the horizontal axis是否让提示气泡在水平轴上始终完整保持在视口内verticalViewportLockbooleanControls if the tooltip will always remain fully in the viewport on the vertical axis垂直轴同理对应的 HTML 特性为horizontal-viewport-lock与vertical-viewport-lock。Tooltip 组件底层基于锚定区域实现其autoUpdateMode字段文档中明确标注“Corresponds to anchored-region auto-update-mode”因此它继承了锚定区域的定位与视口锁定语义。使用示例div fast-button idanchorHover me/fast-button fast-tooltip anchoranchor horizontal-viewport-lock vertical-viewport-lock Tooltip text /fast-tooltip /div这也为理解horizontalViewportLock提供了一条清晰的验证路径在 Tooltip 与 AnchoredRegion 两套 API 文档中该属性的语义完全一致——在对应轴上始终完整可见必要时脱离锚点。七、使用建议与注意事项默认关闭按需开启horizontalViewportLock默认false。普通场景锚点远离视口边缘无需开启只有锚点可能出现在视口边缘、浮层可能越界时才需要。与verticalViewportLock独立设置水平与垂直轴互不影响可按需只锁定一个轴例如“水平锁视口、垂直跟随锚点”。布尔特性的写法在 HTML 中仅书写horizontal-viewport-lock即为开启如需关闭则移除特性或通过属性赋值为false。与定位模式配合它是对定位结果的最终约束而不是定位策略本身需要结合horizontal-positioning-mode、horizontal-default-position、horizontal-threshold、horizontal-scaling等属性共同完成完整的水平布局。配置方案可复用需要批量创建同一定位行为的浮层时可参考AnchoredRegionConfig与FlyoutPos*预置变量的设计把horizontalViewportLock等选项封装进配置对象。参考资料本仓库内本文主文档fast-foundation.anchoredregion.horizontalviewportlock.md类完整 APIfast-foundation.anchoredregion.md垂直方向对应属性fast-foundation.anchoredregion.verticalviewportlock.md配置接口fast-foundation.anchoredregionconfig.md 及 config 的 horizontalViewportLock组件使用指南注册、示例、字段表fast-anchored-region.mdx复用同一属性的 Tooltip 组件fast-tooltip.mdx以上 API 页面均由 API Documenter 自动生成位于 sites/website/src/docs/1.x/api 目录下与组件使用指南相互印证可作为开发浮层、下拉与提示类组件时的权威参考。赞分享前端UI组件【免费下载链接】fastThe adaptive interface system for modern web experiences.项目地址https://gitcode.com/gh_mirrors/fa/fast点击查看免费下载相关推荐Apache DataFusion 13.0.0 版本技术解析类型强制转换重构、时区支持与查询优化Apache DataFusion 13.0.0 版本技术解析类型强制转换重构、时区支持与查询优化 Apache DataFusion 13.0.02022前端UI组件FAST 框架 fast-anchored-region 水平定位指南深入解析 AnchoredRegionConfig.horizontalDefaultPositionFAST 框架 fast anchored region 水平定位指南深入解析 AnchoredRegionConfig.horizontalDefaultP前端UI组件基于 Zeit Now 与 Go 语言构建 Hasura 事件触发器回显Echo服务从建表、部署到验证的完整指南基于 Zeit Now 与 Go 语言构建 Hasura 事件触发器回显Echo服务从建表、部署到验证的完整指南 本文以仓库中的 Zeit Now G前端UI组件上一篇GeoFire for Java实战案例构建附近商家搜索功能的最佳实践下一篇cuDF Java JAR 构建与发布流水线基于 ci-wheel 容器的一站式打包实践创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考