滚动
滚动是这套框架里唯一需要”知道内容总长度”的功能,而内容总长度只有在测量之后才知道;同时列表可能很长,不可能全部测量。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 清扫前取消;声明焦点仍可用于自动滚入视野。