Scroll View 滚动视图

对齐 WinUI 3 ScrollView 的容器控件：内容超出视口时滚动、平移、缩放，滚动条为 WinUI 3 的 overlay 样式（2px 细滑块，指针进入容器即显示；指针移到滚动条上时滑块加粗为 6px、药丸轨道连同两端步进按钮展开，离开后收起，2s 无交互整体淡出）。

基础用法（垂直）

默认 content-orientation="vertical"，滚轮 / 触控平移 / 拖动滚动条均可滚动。

<FluereScrollView class="h-80">
  <div v-for="row in rows" :key="row">第 {{ row }} 行内容 · Windows 11 原生滚动体验</div>
</FluereScrollView>

横向滚动

content-orientation="horizontal"，内容高度约束到视口，宽度自由增长。Shift + 滚轮或触控横向滑动。

<FluereScrollView class="h-40" content-orientation="horizontal">
  <div class="flex gap-fluent-m">…卡片列表…</div>
</FluereScrollView>

双向滚动

content-orientation="both"，内容在横向与纵向均不受约束。

<FluereScrollView class="h-72" content-orientation="both">
  <div class="grid grid-cols-6 gap-fluent-m">…单元格…</div>
</FluereScrollView>

嵌套滚动

内层 ScrollView 位于外层内容之中。鼠标滚轮归属对齐 WinUI 3：指针停在内层上时由内层独占滚轮， 即使内层已滚到极限，外层也不会跟着滚动；把指针移到内层之外的外层内容上，滚轮才交给外层（触控 / 笔由指针捕获独占）。

<FluereScrollView class="h-96">
  <!-- 外层内容 -->
  <FluereScrollView class="h-40">…内层 A 独占滚轮…</FluereScrollView>
  <FluereScrollView class="h-40">…内层 B 独占滚轮…</FluereScrollView>
</FluereScrollView>

焦点滚动

焦点（Tab 或程序化 focus()）进入内容内的元素时，元素自动滚进视口 —— 对齐 WinUI BringIntoViewOnFocusChange（缺省开启），键盘用户不会把焦点留在视口之外；元素已在视口内时不产生动画。 该次滚动同样触发 bring-into-view 事件，可在回调中取消或改写目标偏移。

容器获得焦点（或焦点在内容内）时，方向键、PageUp / PageDown、Home / End 滚动视图；命中 input / textarea / select / contenteditable 时按键交还给输入控件。

缩放

zoom-mode="enabled"：Ctrl / Cmd + 滚轮或双指捏合缩放，缩放中心为指针位置。对齐 WinUI 的 min-zoom-factor / max-zoom-factor 约束。

<FluereScrollView class="h-80" content-orientation="both" zoom-mode="enabled">
  <!-- Ctrl / Cmd + 滚轮 或双指捏合缩放 -->
</FluereScrollView>

滚动条可见性

vertical-scroll-bar-visibility 支持 auto（默认，overlay）/ visible（常驻）/ hidden（仍可滚动）。

<FluereScrollView>…auto（默认，overlay）…</FluereScrollView>
<FluereScrollView vertical-scroll-bar-visibility="visible">…常驻…</FluereScrollView>
<FluereScrollView vertical-scroll-bar-visibility="hidden">…隐藏但可滚动…</FluereScrollView>

程序化 API

对齐 WinUI 方法：scrollTo / scrollBy / zoomTo / zoomBy / addScrollVelocity / addZoomVelocity / bringIntoView（支持动画与 correlation ID）， 以及只读属性 horizontalOffset / verticalOffset / zoomFactor / extentWidth / extentHeight / viewportWidth / viewportHeight / scrollableWidth / scrollableHeight / state / currentAnchor。完整签名见下方「方法」与「只读属性」两张表。

<template>
  <FluereScrollView
    ref="sv"
    content-orientation="both"
    zoom-mode="enabled"
    @view-changed="refreshReadout"
  >
    …内容…
  </FluereScrollView>
  <button @click="sv?.scrollBy(0, 120)">下滚 120px</button>
  <button @click="sv?.scrollTo(0, 0)">回到顶部</button>
  <button @click="sv?.zoomBy(0.25)">放大</button>
</template>

<script setup lang="ts">
const sv = ref<InstanceType<typeof FluereScrollView>>()
</script>

事件

view-changed / extent-changed / state-changed / scroll-animation-starting / scroll-completed / zoom-animation-starting / zoom-completed / anchor-requested / bring-into-view， 载荷见下方「事件」表。这些是组件事件（@event）；供页面自动化使用的 DOM 命令事件 见「Agent / 自动化访问」， 事件名带 fluere: 前缀，在根元素上派发。

<FluereScrollView
  @view-changed="logEvent('view-changed')"
  @state-changed="logEvent(`state → ${$event}`)"
  @scroll-completed="logEvent(`scroll-completed #${$event.correlationId}`)"
>
  …内容…
</FluereScrollView>

Agent / 自动化访问

本组件的偏移由内容 transform 表达、presenter 是 overflow: clip（不是原生滚动容器）， 因此浏览器与自动化工具的原生滚动语义在这里不成立：scrollTop 恒为 0， scrollBy / scrollIntoView / scrollIntoViewIfNeeded 都找不到可滚动祖先 （Playwright 点击视口外元素前的自动滚动同样失效，这也是 style-spec §7 记录的那条坑）。组件为此提供两条 DOM 通路， 都不需要接触组件实例：

• 只读反射：根元素始终带一组状态属性，用来判断「动没动、还剩多少」；
• 命令事件：在根元素上派发 fluere:* 事件即可驱动滚动，落地后收到回执。

只读反射属性

取整后可安全地做相等比较来判断「到底了没有」（data-scroll-y === data-scroll-max-y）。 这些属性在偏移变化时逐帧重写，不要在 CSS 里匹配它们（否则动画期间每帧都会触发样式重算； 仓库有契约测试守着这条约定）。

命令事件

在组件根元素（.fui-scrollview）上派发，bubbles: true，因此也可以挂在页面级监听。

载荷非法（非有限数、目标不可解析）时是空操作，不抛错；bring-into-view 只接受内容区内的元素。 animationMode 传 'disabled' 可跳过动画，适合截图前的确定性定位； agentCommands 设为 false 可关闭命令事件（只读反射保留）。

const el = document.querySelector('.fui-scrollview')

// 1. 先读状态：还需要滚多少？
const remaining = Number(el.dataset.scrollMaxY) - Number(el.dataset.scrollY)

// 2. 派发命令（bubbles 让页面级监听也能收到）
el.dispatchEvent(
  new CustomEvent('fluere:scroll-by', { detail: { y: remaining, animationMode: 'disabled' } }),
)

// 3. 等回执再截图 / 断言
await new Promise((resolve) =>
  el.addEventListener('fluere:scroll-settled', resolve, { once: true }),
)

<FluereScrollView ref="sv" label="日志列表" @view-changed="refresh">
  …内容…
</FluereScrollView>

// 只读反射：读 DOM，不碰组件实例
const root = sv.value.$el
const { scrollY, scrollMaxY } = root.dataset

// 命令 + 回执
root.addEventListener('fluere:scroll-settled', refresh)
root.dispatchEvent(
  new CustomEvent('fluere:bring-into-view', {
    detail: { selector: '[data-row="24"]' },
    bubbles: true,
  }),
)

仍不适用的原生语义：组件不是原生滚动容器，因此 el.scrollTop、el.scrollBy()、 el.scrollIntoView()、CDP DOM.scrollIntoViewIfNeeded、浏览器「在页面中查找」与 #:~:text= 文本片段定位依旧不生效，请用上面的命令事件替代。 另有一条既有通路：焦点进入内容区元素时组件会按 BringIntoViewOnFocusChange 自动把它滚入视口 （对齐 WinUI，见「方法」表的 bringIntoView）。

API

属性（Props）

事件（Events）

方法（Methods）

通过模板 ref 调用；都返回本次操作的 correlationId，用于与 scroll-completed / zoom-completed 的载荷对应。

ScrollingScrollOptions / ScrollingZoomOptions 的 animationMode 取 'disabled' \| 'enabled' \| 'auto'（默认 'auto'），另有 snapPointsMode 占位。

只读属性（Readonly）

插槽（Slots）

滚轮归属（对齐 WinUI 3）：指针位于本组件内、且该方向确实可滚动时，本次滚轮由本组件独占——即使已到滚动极限也不会滚到外层 ScrollView；horizontal/verticalScrollChainMode 为 auto / never 时到极限即吞掉滚轮（等价 overscroll-behavior: contain），为 always 时才把未消化的剩余增量显式交给外层。本方向没有可滚动内容、或该方向被禁用时不占有滚轮，冒泡交给外层。触控 / 笔由指针捕获独占，不走这套判定。