docs: 逐模块细化中文逻辑注释并覆盖测试与示例
This commit is contained in:
+29
-1
@@ -54,6 +54,8 @@ impl Axis {
|
||||
|
||||
/// 求两个裁剪矩形的交集,空区域仍保持合法非负尺寸。
|
||||
fn intersection(a: [f32; 4], b: [f32; 4]) -> [f32; 4] {
|
||||
// 输入采用 [左, 上, 宽, 高]。交集左上取较大值,右下取较小值;
|
||||
// 右/下边界再钳到左/上边界,保证完全错开时输出零面积而非负尺寸。
|
||||
let x = a[0].max(b[0]);
|
||||
let y = a[1].max(b[1]);
|
||||
[
|
||||
@@ -65,6 +67,8 @@ fn intersection(a: [f32; 4], b: [f32; 4]) -> [f32; 4] {
|
||||
}
|
||||
/// 沿出现树累计滚动偏移和裁剪;遇到独立场景视口时按其有限边界重新建立投影范围。
|
||||
pub fn project(vm: &mut Vm, table: &MountTable, root: &UiNode, frame: &mut Frame) -> Result<()> {
|
||||
// 第一阶段只建立查找表,不改坐标:Block ID 查语义节点,Mount ID 查帧中的出现。
|
||||
// 同一个 Block 可以多次出现;滚动偏移后面按 Mount 读取,不能存入这个 Block 表。
|
||||
let mut nodes = HashMap::new();
|
||||
let mut work = vec![root];
|
||||
while let Some(node) = work.pop() {
|
||||
@@ -82,6 +86,8 @@ pub fn project(vm: &mut Vm, table: &MountTable, root: &UiNode, frame: &mut Frame
|
||||
.iter()
|
||||
.map(|m| matches!(nodes[m.block_id.as_str()].kind, UiKind::Scroll { .. }))
|
||||
.collect();
|
||||
// extent 保存尚未滚动的内容右下边界。滚动容器先扣除自身右/下 inset,
|
||||
// 后续传播子内容后再加回 padding,避免把空容器的内边距算成可滚动溢出。
|
||||
let mut extent: Vec<_> = frame
|
||||
.mounts
|
||||
.iter()
|
||||
@@ -95,6 +101,7 @@ pub fn project(vm: &mut Vm, table: &MountTable, root: &UiNode, frame: &mut Frame
|
||||
(m.x + m.width - inset.right, m.y + m.height - inset.bottom)
|
||||
})
|
||||
.collect();
|
||||
// Mount 按父先子后排列,反向扫描才能先汇总子树,再将边界向父级传播。
|
||||
for i in (0..frame.mounts.len()).rev() {
|
||||
let m = &frame.mounts[i];
|
||||
if let Some(parent) = m.parent {
|
||||
@@ -103,8 +110,10 @@ pub fn project(vm: &mut Vm, table: &MountTable, root: &UiNode, frame: &mut Frame
|
||||
nodes[frame.mounts[parent].block_id.as_str()].kind,
|
||||
UiKind::CanvasViewport { .. } | UiKind::Viewport3D { .. }
|
||||
) {
|
||||
// 场景世界内部的坐标范围不扩大外部有限布局盒子的滚动范围。
|
||||
continue;
|
||||
}
|
||||
// 子滚动容器向外只贡献自己的视口;它内部的溢出由自己的偏移处理。
|
||||
let e = if scrolling[i] {
|
||||
(m.x + m.width, m.y + m.height)
|
||||
} else {
|
||||
@@ -114,6 +123,8 @@ pub fn project(vm: &mut Vm, table: &MountTable, root: &UiNode, frame: &mut Frame
|
||||
extent[parent].1 = extent[parent].1.max(e.1);
|
||||
}
|
||||
}
|
||||
// 第二阶段从父到子投影。上下文保存祖先累计位移和裁剪,而非当前节点本身的偏移。
|
||||
// 重建绘制命令及其平行元数据,保证显示、命中与裁剪使用同一套投影坐标。
|
||||
let mut contexts = HashMap::<u64, (f32, f32, Option<[f32; 4]>)>::new();
|
||||
frame.commands.clear();
|
||||
frame.command_clips.clear();
|
||||
@@ -130,6 +141,7 @@ pub fn project(vm: &mut Vm, table: &MountTable, root: &UiNode, frame: &mut Frame
|
||||
UiKind::Scroll { axis, .. } => axis,
|
||||
_ => Axis::Both,
|
||||
};
|
||||
// limits 在未改写的布局坐标里计算;禁用轴直接设零,内容比视口小时也为零。
|
||||
let limits = [
|
||||
if axis.horizontal() {
|
||||
(extent[i].0 + padding.right - m.x - m.width).max(0.0)
|
||||
@@ -142,10 +154,12 @@ pub fn project(vm: &mut Vm, table: &MountTable, root: &UiNode, frame: &mut Frame
|
||||
0.0
|
||||
},
|
||||
];
|
||||
// 当前容器跟随祖先滚动;它自己的 scroll_offset 只影响子节点,容器边框保持原位。
|
||||
m.x -= dx;
|
||||
m.y -= dy;
|
||||
m.clip = clip;
|
||||
let mut child = (dx, dy, clip);
|
||||
// 普通裁剪使用边框内侧矩形,并与祖先裁剪求交,不能扩大祖先允许的区域。
|
||||
if node.clip_children {
|
||||
let border = node.border;
|
||||
let viewport = [
|
||||
@@ -167,11 +181,14 @@ pub fn project(vm: &mut Vm, table: &MountTable, root: &UiNode, frame: &mut Frame
|
||||
let owner = vm
|
||||
.upgrade(*weak)?
|
||||
.ok_or_else(|| anyhow::anyhow!("expired scroll Mount"))?;
|
||||
// weak upgrade 临时保活 Mount。先保存 payload 读取结果再 release,
|
||||
// 这样读取失败也会先释放强引用,然后由下方 offset? 传播错误。
|
||||
let offset = vm
|
||||
.payload::<Mount>(owner, "Mount")
|
||||
.map(|mount| mount.scroll_offset);
|
||||
vm.release(owner)?;
|
||||
let offset = offset?;
|
||||
// 内容缩短时旧偏移可能超界;此处只钳制帧投影,不改写托管 Mount 的原偏移。
|
||||
let x = offset[0].clamp(0.0, limits[0]);
|
||||
let y = offset[1].clamp(0.0, limits[1]);
|
||||
m.scroll = Some([x, y, limits[0], limits[1]]);
|
||||
@@ -187,6 +204,7 @@ pub fn project(vm: &mut Vm, table: &MountTable, root: &UiNode, frame: &mut Frame
|
||||
),
|
||||
);
|
||||
}
|
||||
// 3D 子场景有独立投影空间,不能继续叠加外层二维滚动坐标和裁剪。
|
||||
if matches!(node.kind, UiKind::Viewport3D { .. }) {
|
||||
child = (0., 0., None);
|
||||
}
|
||||
@@ -218,6 +236,7 @@ pub fn coordinate(value: &Value) -> Result<f32, VmError> {
|
||||
"scroll coordinates must be numbers",
|
||||
));
|
||||
};
|
||||
// 通过 Number 文本表示转为 f32,再检查有限性及绝对值上限;允许负数以表达相对滚动。
|
||||
let n = value
|
||||
.to_string()
|
||||
.parse::<f32>()
|
||||
@@ -235,6 +254,7 @@ pub fn set(
|
||||
point: [f32; 2],
|
||||
relative: bool,
|
||||
) -> Result<(), VmError> {
|
||||
// 只允许已提交且仍挂接的出现接受滚动;布局过程中的临时 Mount 不具备稳定滚动边界。
|
||||
let mut mount = cx.store().payload::<Mount>(owner, "Mount")?.clone();
|
||||
if !mount.mounted || mount.layout.is_some() {
|
||||
return Err(VmError::InvalidArgument(
|
||||
@@ -257,7 +277,8 @@ pub fn set(
|
||||
let desktop = cx
|
||||
.upgrade(desktop)?
|
||||
.ok_or(VmError::InvalidArgument("Mount window expired"))?;
|
||||
// Check the normal mutation barrier even when the clamped result is equal.
|
||||
// 即使钳制后数值未变,也走正常写屏障,使只读调用不能借助无效滚动绕过变更限制。
|
||||
// scrollRequested 通知后续刷新重做投影,而不是在这里直接重建布局或绘制。
|
||||
cx.replace_payload(owner, mount)?;
|
||||
cx.set_attr(desktop, "scrollRequested", Value::Bool(true))
|
||||
}
|
||||
@@ -273,6 +294,7 @@ pub fn into_view(
|
||||
"scrollIntoView requires committed attached Mount",
|
||||
));
|
||||
}
|
||||
// rect 随祖先滚动调整,表示目标在当前投影中的可见需求;从最近父容器逐层向外处理。
|
||||
let mut rect = [
|
||||
mount.geometry.x,
|
||||
mount.geometry.y,
|
||||
@@ -286,6 +308,7 @@ pub fn into_view(
|
||||
};
|
||||
let mount = cx.store().payload::<Mount>(owner, "Mount")?.clone();
|
||||
parent = mount.parent;
|
||||
// 跨越独立场景边界时,外层只能滚动整个场景视口,不能使用内部世界坐标定位目标。
|
||||
if mount.geometry.canvas_viewport || mount.geometry.scene3d_viewport {
|
||||
rect = [
|
||||
mount.geometry.x,
|
||||
@@ -295,6 +318,7 @@ pub fn into_view(
|
||||
];
|
||||
}
|
||||
if let Some(offset) = mount.geometry.scroll {
|
||||
// 目标起点在视口前则向前对齐;否则只补足末端溢出,已完全可见时返回零。
|
||||
let delta = |start: f32, length: f32, viewport: f32, size: f32| {
|
||||
if start < viewport {
|
||||
start - viewport
|
||||
@@ -306,6 +330,7 @@ pub fn into_view(
|
||||
let dy = delta(rect[1], rect[3], mount.geometry.y, mount.geometry.height);
|
||||
let x = (offset[0] + dx).clamp(0.0, offset[2]);
|
||||
let y = (offset[1] + dy).clamp(0.0, offset[3]);
|
||||
// 下一层祖先看到的目标位置必须扣掉本层实际移动量,不能扣未钳制的请求量。
|
||||
rect[0] -= x - offset[0];
|
||||
rect[1] -= y - offset[1];
|
||||
if x != offset[0] || y != offset[1] {
|
||||
@@ -318,12 +343,15 @@ pub fn into_view(
|
||||
/// 按逆出现顺序选择指针处可处理当前滚动方向的最内层容器。
|
||||
pub fn wheel_target(frame: &Frame, point: Point, delta: [f32; 2]) -> Option<u64> {
|
||||
let indices: HashMap<_, _> = frame.mounts.iter().map(|mount| (mount.id, mount)).collect();
|
||||
// 逆序先取最上层命中的出现,再沿其祖先寻找能消费位移的滚动容器。
|
||||
// 不搜索被覆盖的兄弟容器,内层到边界后才交给外层滚动。
|
||||
let mut current = frame
|
||||
.mounts
|
||||
.iter()
|
||||
.rev()
|
||||
.find(|mount| mount.contains(point));
|
||||
while let Some(mount) = current {
|
||||
// 只有至少一轴钳制后真正改变偏移才接收此次输入;没有任何容器可移动则返回 None。
|
||||
if mount.scroll.is_some_and(|s| {
|
||||
(s[0] + delta[0]).clamp(0.0, s[2]) != s[0] || (s[1] + delta[1]).clamp(0.0, s[3]) != s[1]
|
||||
}) {
|
||||
|
||||
Reference in New Issue
Block a user