滚动

滚动是这套框架里唯一需要”知道内容总长度”的功能,而内容总长度只有在测量之后才知道;同时列表可能很长,不可能全部测量。Scroller 就是为这个矛盾设计的:它把”位置 ↔ 条目”的换算集中到一处,并把”条目尺寸”变成一种可以被惰性求值的查询。

Scroller 的状态模型

Scroller 同时是一个一维区间(low / high,即视口)和一个滚动控制器。它的状态分四类:

状态 含义
items 条目序列,每个条目提供 identity 与 size。访问 size 可能触发加载
rawScroll 真实滚动位置
scroll 滚动位置,可能是动画值
offset / scrollIndex 首个可见条目的偏移与索引,作为换算的锚点

为什么区分 rawScroll 与 scroll:滚动位置常常接一个动画属性让滚动平滑,于是”目标位置”与”当前渲染位置”必须分开。实际使用的规则是——夹取用 rawScroll,可见区间计算用 scroll。

单位

Scroller 的入参必须是未缩放的像素,因为滚动量来自鼠标位移,而鼠标位移本身与 GUI 缩放无关。Scroller 因此需要 DslScaleContext 才能把条目尺寸换算过去。

Measure.unscaled 在遇到 NaN 时静默回退为 0——滚动计算依赖这一点,但也意味着无效尺寸会被当成”零长度条目”而不是报错。

锚点而不是绝对位置

calculateIndex(scroll) 不从头遍历,而是从当前的 scrollIndex 与 offset 出发向两侧走到目标位置。这是滚动能保持 O(可见条目数) 的关键:每帧滚动量很小,锚点几乎总在附近。

offset / scrollIndex 的存在还有一个作用:可见区间上方的条目尺寸变化不会导致视觉漂移,因为位置是相对锚点表达的,而不是相对内容起点。

夹取

updateScroll() 把 rawScroll 限制在合法范围并同步给 scroll。两端各有处理:

  • 顶端:首个条目就是 0 号且位置还在它上边界之上时,直接归位到它的上边界;
  • 底端:向前累加直到填满视口,如果越过条目末尾,就减去超出量再重新归位。

结果是内容短于视口时 rawScroll 被夹到 0,即内容顶端对齐。

余量

scroll(value) 返回未消费的量:先记录滚动前后的实际位置差,再返回 value - 实际位移。到达边界后继续滚动会返回全部输入量,于是外层容器可以接手——这与事件层的滚动余量语义一致。

定位

scrollTo 有三个维度:目标(索引 / 身份 / 当前可见项)、对齐(LOW / MID / HIGH)、约束(KeepIn / KeepInRatio / AlignTo)。

  • KeepIn:条目已完整落在”视口内缩 padding“的范围内就不动,否则按最小位移把它推进来;
  • KeepInRatio:把 padding 换成视口尺寸的一个比例;
  • AlignTo:无条件按给定 Align 对齐。

ScrollConstraint 被设计成密封接口而不是枚举,因为两种”保持可见”各自需要携带参数(Measure 与 Double),枚举无法表达。

按 Align.MID 对齐的实现是”先按 LOW 定位,再回滚半个(视口 - 条目)的距离”。

不带索引时,scrollTo(Align) 的语义是在整份内容里跳转:LOW 到第一条、HIGH 到最后一条、MID 居中于内容中部那一条。

按身份定位走 Scroller.indexOf。默认实现扫描条目列表;惰性列表覆写它改为在子节点列表上查找,因为”问一个条目它的身份”本身就会触发加载。不过这只是省掉了”为了定位而全量加载”——要滚动到远处的条目,仍然必须沿路测量中间条目才能算出偏移,这是惰性列表固有的代价。

自动滚动

AutoScroll(sources, constraint) 描述”哪些原因引起的焦点变化应当把该条目滚进视野”。默认是键盘焦点变化 + KeepIn(0.px)。

实现挂在全局焦点变化回调上:命中新焦点所在的直接子节点,再按约束把它滚进来。注意它查的是直接子节点,所以嵌套滚动容器各自只对自己那一层负责。

两种滚动容器

全部加载

ScrollableColumn / ScrollableRow 假设所有条目都已存在,因此可以精确计算可见区间上下方的空间。它的测量策略是:

  • 滚动方向的最小尺寸为 0(这样父容器可以把它压小);
  • 交叉轴的最小尺寸取子节点最大值与自身声明的较大者;
  • 布局时用 close(Align.LOW) 在一个被整体平移过的区间上排列所有子节点——平移量即当前滚动位置;
  • 渲染时跳过与视口不相交的子节点。

配合 scissor 装饰器完成裁剪。

惰性

LazyColumn / LazyRow 的”懒”比名字暗示的要保守,理解它的真实边界很重要:

执行了的部分:build() 会完整执行用户的 DSL 函数,因此所有条目的组件对象都会被创建(测试里明确断言 100 个条目的列表会得到 100 个子节点)。这一步只创建对象,不构建子树。

延迟了的部分:子节点的 build()(即条目内部的结构)、交叉轴布局、滚动方向的尺寸测量、以及渲染。这些只在条目进入可见区间时发生。

具体机制是:条目尺寸查询被包装成一个访问即加载的列表。取第 i 个条目的尺寸时,才去构建该子节点、按列表视口的交叉轴范围做一次对齐与布局,然后读它的最小尺寸。结果缓存在一个与子节点数量等长的数组里。

由此得到几个必须知道的结论:

  • 没有预取:可见区间刚好等于视口覆盖的范围,前后都没有额外条目。滚动时的”进入视野”是即时的,快速滚动会看到条目逐帧出现。
  • 没有跨帧尺寸缓存:存放尺寸的列表在每次布局时新建,所以每帧都要重新测量可见条目的尺寸。它省掉的是”整个列表的测量”,不是”重复测量”。
  • 同一帧重复布局不重复构建:已实体化的条目在同一帧的第二次布局中只重新测量、重新定位,不会再次执行 build() 把子树注册一遍;视口宽度变化后,新的可见范围会按新尺寸重新测量。
  • 只有可见条目参与位置命中测试与渲染:hover / tooltip / 预编辑区域等按坐标查询只看已实体化的条目;未实体化的条目没有有效矩形。键盘导航视图则包含全部已声明的直接条目:焦点可以移到屏外条目,AutoScroll 再按身份把这个直接条目滚入视野。按身份查询不会把未实体化条目的子树当成完整树——它的子节点尚未构建。指针和键盘事件仍走通用容器的事件分发路径,跨帧的交互 owner 不由列表层建立。
  • 身份与懒加载无关:条目状态的稳定来自身份的稳定性(见 身份与属性),列表本身没有类似 Compose key/slot 的机制。

延迟状态的归属

滚动状态(位置、锚点、索引)属于声明该列表的容器,不是布局时碰巧激活的 screen。容器在声明处冻结 withScale / withId / withColor 的作用域;条目构建、布局、材料化和滚动换算都在这个冻结作用域里执行。因此:

  • 两个省略 scroller 参数的惰性列表各自持有独立状态,帧间不会串位;
  • 局部 withScale 内的列表按该尺度换算滚动位移,而不是按 root 尺度;
  • 交叉轴测量和延迟内容使用列表声明的尺度与颜色,即使布局发生在声明作用域退出之后。

交叉轴顺序

LazyRow 与 LazyColumn 都在滚动轴布局时先确定可见范围并加载条目;交叉轴只对这份可见集合对齐和递归布局。LazyColumn 的交叉轴宽度来自列表视口,而不是条目尚未布局时的空矩形;因此在第一帧里,宽度的确定可以发生在条目加载过程中,而不要求先跑一遍全量子节点。

布局方法(layoutHorizontal / layoutVertical)可以在同一帧内重复调用,但应发生在帧的构建/布局过程中;延迟到声明作用域退出之后的测量使用容器冻结的声明作用域,不读取当时碰巧激活的 screen 上下文。帧结束后应渲染下一帧,而不是从外部再次驱动布局。

滚动量的换算

滚动事件先用 sensitivity(默认 30)把”格数”换算成像素,再交给 scroller.scroll,最后把未消费的余量按同样比例还原回”格数”返回。

横向列表在纵向滚轮且按住 Shift 时也响应,这是一个显式的便利处理。

导航视图

滚动容器覆写了焦点导航视图:沿滚动轴时每个条目各自成组,于是方向键会逐条目移动;交叉轴时全部条目视为一组。这让长列表里按方向键能一个条目一个条目地走,而不是跨列跳。导航视图基于全部已声明的直接条目,不要求它们已经实体化;焦点落到屏外条目时由 AutoScroll 把它滚进视野。未实体化条目的内部子树不参与导航。

ScrollBar

滚动条是独立组件,不与滚动容器耦合——它只持有同一个 Scroller 引用。这样一条滚动条可以被多个容器共享,一个容器也可以挂多条滚动条。

内部结构是”按权重撑开”的三段:视口前空间、滑块、视口后空间,权重分别是 spaceBefore()、视口尺寸、spaceAfter()。因此滑块的相对长度自动反映内容比例,无需额外计算。

拖拽的处理在包裹层:记录按下位置,在鼠标移动时算出”本次位移占滚动条长度的比例”,乘以总内容长度得到滚动增量。因为滑块本身占据的是一段有长度的区域,这个比例换算在滚过整个滚动条长度时刚好遍历全部内容。

一个细节:点击轨道空白处不会跳转,只有拖动滑块才滚动。滑块是可聚焦的(能出现在焦点链里、能被朗读),但没有键盘操作,因此可以聚焦却不能键盘驱动。

已知问题

  • 循环里声明的条目共享身份:惰性列表的条目通常写在 repeat / forEach 里,而身份取自书写位置,因此每一轮都会得到同一个身份。需要按键值区分条目时必须用 forEachWithId 或显式传 id,否则按身份定位只会命中第一个。
  • ScrollConstraint 的 KeepIn、KeepInRatio、AlignTo 三个分支已有直接测试。
  • ScrollBar 的三段 Spacer 权重在 build 期用上一帧的 scroller 计算,因此第一帧的旋钮高度是 0,要到第二帧才能拖(针对它的测试也因此跑两帧)。
  • AutoScroll 现在有键盘焦点把屏外直接条目滚入视野的回归测试;CODE / MOUSE 来源以及焦点落在条目内部子节点的情况还没有独立用例。Button 只有”宽高大于 0”这一级 smoke。
  • 惰性列表的可见范围、重复布局、交叉轴材料化、独立滚动状态、非单位局部尺度和键盘自动滚动已有回归测试;LazyRow 的滚动驱动命中测试还没有独立用例。 列表的声明导航与物化输入分开:Root 跟踪 PointerId 的交互归属,Lazy 物化驱逐会在旧 local 清扫前取消;声明焦点仍可用于自动滚入视野。

This site uses Just the Docs, a documentation theme for Jekyll.