diff --git a/src/render/layout.rs b/src/render/layout.rs index d3456b1..f33b1a7 100644 --- a/src/render/layout.rs +++ b/src/render/layout.rs @@ -2,6 +2,10 @@ //! Row/Column/Overlay、边距、边框、内边距、对齐和弹性空间都在有限约束内计算;过大的尺寸和坐标返回错误。 //! 缓存按组件形状、子项尺寸和约束判断可复用性。frame 先在克隆状态中求解,成功才替换运行状态,防止失败污染已发布几何。 //! +//! 调用路径:UiBridge/原生视觉入口调用 LayoutRuntime 或 frame_with_viewport 进行纯原生布局。 +//! source_layout 复用约束、measure_native、flex_sizes、arrange_native 等单节点函数,在外层驱动源协议收敛。 +//! 本模块只处理不可变 UiNode 和原生数值,不执行 VM 或持有托管根;每次出现身份由父 ID/slot/业务身份共同确定。 +//! //! Iterative measure/arrange/paint over derived visual data. Every occurrence //! has its own geometry; measurement caches never become semantic object state. use crate::{ @@ -12,14 +16,19 @@ use crate::{ use anyhow::{Context as _, Result, bail}; use std::collections::{HashMap, HashSet}; +// 一次原生整树构建最多展开一万个出现,共享业务对象的不同位置也各计一次。 const MAX_LAYOUT_VISITS: usize = 10_000; #[derive(Debug, Clone, Copy, Default, PartialEq)] /// 上右下左四边的空间占用,用于 margin、padding 和 border 计算。 pub struct Insets { + // 顶侧占用,来自上 margin/padding/border 的哪一层由调用方确定。 pub top: f32, + // 右侧占用,horizontal 与 left 相加,不含父容器自身位置。 pub right: f32, + // 底侧占用,vertical 与 top 相加。 pub bottom: f32, + // 左侧占用,安排内容原点时加到父边框盒 x。 pub left: f32, } @@ -47,15 +56,20 @@ impl Insets { /// 交叉轴对齐规则;Stretch 需要结合子项是否自动尺寸决定实际拉伸。 pub enum CrossAlign { #[default] + // 对齐内容区起点;内容溢出时其他偏移模式也退回起点。 Start, + // 按交叉轴非负剩余空间的一半偏移,不改变自然尺寸。 Center, + // 按交叉轴全部非负剩余空间偏移。 End, + // 偏移为零,尺寸拉伸由 flex_sizes 按 Auto/上下限另行计算。 Stretch, } impl CrossAlign { /// 返回内部枚举或对象对应的稳定源名称。 pub fn name(self) -> &'static str { + // 模型字段编码用稳定小写名字,alignSelf 的 auto 不属于此枚举,由 Option 在模型层表示。 match self { Self::Start => "start", Self::Center => "center", @@ -66,6 +80,7 @@ impl CrossAlign { /// 把外部源码或属性表示转换为内部枚举/结构,并反馈不支持的输入。 pub fn parse(value: &str) -> Result { + // 拒绝未知对齐策略;auto 应在调用方转为无自身覆盖,不能解析成某个具体父策略。 match value { "start" => Ok(Self::Start), "center" => Ok(Self::Center), @@ -81,6 +96,7 @@ impl CrossAlign { fn offset(self, available: f32, occupied: f32) -> f32 { // 溢出时剩余空间归零,Center/End 都退化为起点对齐,避免把内容前缘移出可达滚动范围。 let spare = (available - occupied).max(0.0); + // Stretch 的位置与 Start 相同,实际可拉伸尺寸在分配阶段已经决定。 match self { Self::Start | Self::Stretch => 0.0, Self::Center => spare / 2.0, @@ -93,14 +109,19 @@ impl CrossAlign { /// 容器主轴的内容对齐或剩余间隔分配方式。 pub enum MainAlign { #[default] + // 主轴从内容起点顺序排列。 Start, + // 把正剩余空间平分到内容前后,保持既定子项尺寸与固定 gap。 Center, + // 将正剩余空间放到首项之前。 End, + // 至少两个孩子时把剩余空间均匀加到项间,原固定 gap 仍保留。 SpaceBetween, } impl MainAlign { /// 返回内部枚举或对象对应的稳定源名称。 pub fn name(self) -> &'static str { + // 把已验证主轴枚举编码回源属性,字段名与布局分派共享这组名称。 match self { Self::Start => "start", Self::Center => "center", @@ -110,6 +131,7 @@ impl MainAlign { } /// 把外部源码或属性表示转换为内部枚举/结构,并反馈不支持的输入。 pub fn parse(value: &str) -> Result { + // 主轴只支持四个明确策略,不接受交叉轴 stretch 或任意别名。 match value { "start" => Ok(Self::Start), "center" => Ok(Self::Center), @@ -128,7 +150,9 @@ impl MainAlign { pub struct FlexPolicy { // Some 指定主轴首选基准,None 使用首次内容测量;grow/fill 的缺省基准在 flex_sizes 中解释为零。 pub basis: Option, + // 主轴弹性分配下限,还要与对应盒模型 min/max 求交。 pub min: f32, + // 主轴弹性分配上限,达到后退出剩余空间的再分配。 pub max: f32, // 收缩权重还会乘 basis;默认零表示空间不足时不主动压缩该项。 pub shrink: f32, @@ -148,25 +172,35 @@ impl Default for FlexPolicy { #[derive(Default, Debug, Clone, Copy, PartialEq, serde::Serialize, serde::Deserialize)] /// 逻辑宽高值,不隐含窗口像素比例或相机缩放。 pub struct Size { + // 逻辑横向长度,测量/分配上下文决定是自然尺寸还是实际边框盒宽。 pub width: f32, + // 逻辑纵向长度,不携带 DPI 或相机倍率。 pub height: f32, } #[derive(Debug, Clone, PartialEq)] /// 影响原生测量的缓存形状,避免把颜色等纯绘制变化视为尺寸变化。 enum Shape { + // 非默认盒策略把尺寸约束也纳入缓存键,防止同业务对象在不同父分配中误用结果。 Sized(Box, crate::box_model::Sizing, [f32; 4]), + // 文本内容、字号等级与有效换行宽都影响测量,颜色不进入键。 Text(String, u32, f32), + // 固定自然宽高,亦用于视口、间隔和场景外包范围。 Rect(f32, f32), + // 方向、有效 inset、gap 和孩子外尺寸一起决定容器自然尺寸。 Container(bool, Insets, f32, Vec), + // 为内容形状套上实际 inset,文字自然测量需加回边框/内边距。 Padded(Box, Insets), } #[derive(Debug, Clone, Hash, PartialEq, Eq)] /// 结构出现身份键,区分同一业务对象在不同父位置的展示。 struct Key { + // 父出现 Mount ID;同一业务节点在不同父下要有不同出现身份。 parent: Option, + // 父组成边的稳定 slot,不是当前数组下标或屏幕坐标。 slot: u64, + // 孩子业务身份文本,替换为不同对象时同一 slot 也不能误复用旧出现。 block: String, } @@ -177,27 +211,41 @@ pub struct LayoutRuntime { sizes: HashMap, // 出现身份取父 Mount、稳定 slot 和 Block 身份三元组,区别于仅按业务组件分配一个全局 ID。 ids: HashMap, + // 已分配 ID 高水位,清出现表或取消重试也不应降低。 next_id: u64, + // 每次成功 structure/frame 构建递增,供后续 Mount 与输入归属校验。 pub version: u64, + // 本次实际执行 measure_shape 的缓存未命中次数,不是扫描节点总数。 pub measured: usize, + // 完整原生构建安排出现次数;结构准备不记为已完成排列。 pub arranged: usize, + // 纯原生完整构建记一轮,结构准备记零;源布局驱动另统计其迭代。 pub settle_passes: usize, + // 此同步原生构建的工作片统计,源协议可恢复切片由外层驱动维护。 pub slices: usize, + // 本窗口逻辑可用大小,未知时使用有限数值的无界哨兵。 pub viewport: Option, + // 可选旧 Page 模式,用于生成根轴约束;独立场景视口另有自己的有限盒。 pub page_mode: Option, } /// 迭代遍历中的一个出现,保存父子索引、约束与稳定 ID。 struct Item<'a> { + // 借用当前原生不可变视觉节点,构建完成前根树需保持存活。 node: &'a UiNode, + // items 中父出现索引,发布时再转换为父 Mount ID。 parent: Option, + // items 中有序子出现索引,同一 UiNode Arc 可出现在多个索引。 children: Vec, + // 由结构 Key 复用或新分配的本出现 ID。 id: u64, + // 此出现独立的 [minW,minH,maxW,maxH],不能按共享业务对象合并。 constraints: [f32; 4], } /// 检查尺寸非负、有限且不超过布局上限。 fn bounded(value: f32) -> Result { + // 所有最终测量长度经此边界检查,NaN/负数/超预算都导致本次布局失败。 if !value.is_finite() || !(0.0..=MAX_DIMENSION as f32).contains(&value) { bail!("UI layout exceeds the 1000000 coordinate/size limit"); } @@ -206,6 +254,7 @@ fn bounded(value: f32) -> Result { /// 检查允许有正负方向的坐标仍在安全布局范围内。 fn coordinate(value: f32) -> Result { + // 位置允许负方向,但有限性和绝对值预算仍约束最终原点及远端。 if !value.is_finite() || value.abs() > MAX_DIMENSION as f32 { bail!("UI coordinate exceeds the 1000000 limit"); } @@ -233,9 +282,11 @@ fn content_limit(available: f32, inset: f32) -> f32 { } /// 把父盒子的可用尺寸传递给子项,扣除容器内边距并考虑主轴是否可延伸。 pub fn child_constraints(node: &UiNode, parent: [f32; 4]) -> [f32; 4] { + // 先让父自身 boxWidth/Height 与 max 约束进入可用空间,再选择孩子的轴规则。 let parent = node.sizing.available(parent); // Overlay 双轴都受内容盒上限约束;不像 Row/Column 在主轴自然展开。 if let UiKind::Overlay { .. } = node.kind { + // Overlay 双轴内容区扣 border+有效 padding,不让孩子共享线性主轴无界规则。 let padding = insets(node); return [ 0.0, @@ -244,6 +295,7 @@ pub fn child_constraints(node: &UiNode, parent: [f32; 4]) -> [f32; 4] { content_limit(parent[3], padding.vertical()), ]; } + // 二维世界及其观察容器不拿屏幕宽强迫世界内容换行,世界约束使用无界哨兵。 if matches!( node.kind, UiKind::Canvas { .. } | UiKind::Scene2D { .. } | UiKind::CanvasViewport { .. } @@ -251,6 +303,7 @@ pub fn child_constraints(node: &UiNode, parent: [f32; 4]) -> [f32; 4] { // 世界 Canvas/Scene2D 与其观察视口不把屏幕尺寸传入世界布局,场景孩子用无界轴约束。 return root_constraints(None); } + // 滚动孩子约束基于视口实际分配及允许轴,构造宽高先受父约束夹取。 if let UiKind::Scroll { width, height, .. } = node.kind { return arranged_child_constraints( node, @@ -278,6 +331,7 @@ pub fn child_constraints(node: &UiNode, parent: [f32; 4]) -> [f32; 4] { /// 从子项可用范围扣除外边距,并使最小值不超过调整后的最大值。 pub fn margin_constraints(child: &UiNode, mut constraints: [f32; 4]) -> [f32; 4] { + // 按横纵轴分别扣两侧 margin,不能用某一轴的总外边距同时改另一轴。 for (axis, margin) in [child.margin.horizontal(), child.margin.vertical()] .into_iter() .enumerate() @@ -303,10 +357,13 @@ pub fn occurrence_constraints( ) -> [f32; 4] { // 世界面板 UI 根必须精确按纹理分辨率布局,最小与最大相同,不让外层视口世界尺寸泄入纹理空间。 if let UiKind::Viewport3D { panels, .. } = &parent.kind { + // 面板 child_index 与 panels/children 保持同序,该 UI 根按自己的纹理尺寸精确布局。 let size = panels[child_index]; return [size.width, size.height, size.width, size.height]; } + // Fill 初次测量需扣父内容 inset,后面再由 margin_constraints 扣孩子外边距。 let inset = insets(parent); + // 两轴独立判断 fill 与当前 offer 是否有限,不能因另一轴有限就允许无界 fill。 for (axis, dimension, available, padding) in [ (0, child.sizing.width, offer.width, inset.horizontal()), (1, child.sizing.height, offer.height, inset.vertical()), @@ -330,6 +387,7 @@ pub fn initial_child_constraints( constraints: [f32; 4], child_index: usize, ) -> [f32; 4] { + // 父自身盒策略先收窄初次可分配最大值,提供给 occurrence_constraints 补有限 fill offer。 let offer = parent.sizing.available(constraints); occurrence_constraints( parent, @@ -348,15 +406,18 @@ pub fn initial_child_constraints( pub fn arranged_child_constraints(node: &UiNode, available: [f32; 4], bounds: Size) -> [f32; 4] { // 滚动允许轴无界以容纳内容,禁用轴使用实际已安排的视口尺寸,文字才能按最终交叉轴宽度换行。 if let UiKind::Scroll { axis, .. } = node.kind { + // 禁用滚动轴使用此出现已安排 bounds 扣 inset,不能继续按最初构造参数给文字宽度。 let padding = insets(node); return [ 0.0, 0.0, + // 允许横向滚动时内容宽使用无界哨兵;禁止横向时用实际内容视口有限宽以驱动换行。 if axis.horizontal() { MAX_DIMENSION as f32 } else { (bounds.width - padding.horizontal()).max(0.0) }, + // 纵轴独立判断是否可延伸,禁用轴必须受当前出现 bounds 限制。 if axis.vertical() { MAX_DIMENSION as f32 } else { @@ -397,6 +458,7 @@ pub fn insets(node: &UiNode) -> Insets { /// 提取容器方向与间距等原生布局配置,叶节点不参与容器规则。 fn container(node: &UiNode) -> Option<(bool, Insets, f32)> { + // 只识别线性 Row/Column/Button/Scroll,Overlay/世界场景在调用方有独立布局分支。 match &node.kind { UiKind::Row { gap, .. } => Some((true, insets(node), *gap)), UiKind::Scroll { gap, .. } => Some((false, insets(node), *gap)), @@ -409,20 +471,26 @@ fn container(node: &UiNode) -> Option<(bool, Insets, f32)> { /// 根据容器方向选择主轴,供 flex 和对齐共享同一判断。 pub fn main_axis(node: &UiNode) -> Option { + // row=true 映射横轴 0,纵向映射轴 1;非线性节点返回 None。 container(node).map(|(row, _, _)| usize::from(!row)) } /// 根据形状键计算期望尺寸,包括文字换行、容器子项和盒模型占用。 fn measure_shape(shape: &Shape) -> Result { + // 只根据 Shape 计算原生自然/盒策略尺寸,不修改 UiNode、出现身份或任何业务对象。 let size = match shape { + // 先测内部内容形状,再由完整盒策略按当前约束求边框盒尺寸。 Shape::Sized(shape, sizing, constraints) => { sizing.resolve(measure_shape(shape)?, *constraints)? } + // 内容自然尺寸外加 inset,尺寸结果仍会在函数尾做全局预算检查。 Shape::Padded(shape, padding) => padding.outer(measure_shape(shape)?), Shape::Text(value, size, width) => { + // 同一文字样式用于单行自然宽和受限换行高,避免测量两套字体规则。 let style = TextStyle::ui(*size); // 自然文字宽度与受限换行高度分别测量;布局宽度不超过可用宽度,高度反映完整段落行数。 let intrinsic = text::measure(value, style); + // 用同一字号在有效宽度下重新排段落高度,不能把自然单行高当作换行高。 let wrapped = text::measure_wrapped(value, style, *width); Size { width: intrinsic.width.min(*width), @@ -445,6 +513,7 @@ fn measure_shape(shape: &Shape) -> Result { padding.vertical() } + gap * children.len().saturating_sub(1) as f32; + // 交叉轴取最大孩子外尺寸,再加父交叉轴 inset,不把横向孩子高相加。 let cross = children .iter() .map(|s| if *row { s.height } else { s.width }) @@ -454,6 +523,7 @@ fn measure_shape(shape: &Shape) -> Result { } else { padding.horizontal() }; + // 将主/交叉轴长度还原为物理 width/height,方向不同不改变计算规则。 if *row { Size { width: along, @@ -474,14 +544,18 @@ fn measure_shape(shape: &Shape) -> Result { /// 建立影响测量的形状键,将布局属性、子项测量结果和约束组合起来。 fn shape(node: &UiNode, children: Vec, constraints: [f32; 4]) -> Result { + // 先应用当前盒策略得到内容可测量上限,文字宽度键必须反映该次出现的有效约束。 let available = node.sizing.available(constraints); + // 按 UiKind 提取只影响测量的数据,纯绘制颜色/材质不会制造测量缓存失效。 let shape = match &node.kind { UiKind::Overlay { .. } => { + // Overlay 自然尺寸使用孩子含 margin 的最大外框,再加自身有效 inset。 let padding = insets(node); // Overlay 取含各自 margin 的子盒最大宽高,不把重叠项逐个相加。 let size = children.into_iter().zip(node.children()).fold( Size::default(), |size, (child, node)| { + // 先把此孩子 margin 加到自身边框盒,避免只看内容尺寸漏算外占用。 let child = node.margin.outer(child); Size { width: size.width.max(child.width), @@ -499,6 +573,7 @@ fn shape(node: &UiNode, children: Vec, constraints: [f32; 4]) -> Result { + // 世界内容外包范围从零开始,因此只有负坐标且右下端仍为负时不会扩张正向 extent。 let mut size = Size::default(); // 场景尺寸仅累计孩子右下端最大值;负方向内容不向左上平移整体,导航仍由相机负责。 for (position, child) in positions.iter().zip(children) { @@ -508,6 +583,7 @@ fn shape(node: &UiNode, children: Vec, constraints: [f32; 4]) -> Result { + // 文字内容有效宽由本次 available 扣有效 inset,测量后 Padded 再加回。 let padding = insets(node); Shape::Padded( Box::new(Shape::Text( @@ -522,7 +598,9 @@ fn shape(node: &UiNode, children: Vec, constraints: [f32; 4]) -> Result Shape::Rect(*size, *size), UiKind::Scroll { width, height, .. } => Shape::Rect(*width, *height), _ => { + // 剩余种类必须是已知线性容器;未知原生协议明确失败,不猜测为 Column。 let (row, padding, gap) = container(node).context("unknown native visual protocol")?; + // 缓存键保存含每个孩子 margin 的外尺寸,margin 改变即使孩子本身尺寸不变也需重测父。 let children = children .into_iter() .zip(node.children()) @@ -539,7 +617,7 @@ fn shape(node: &UiNode, children: Vec, constraints: [f32; 4]) -> Result, constraints: [f32; 4]) -> Result { measure_shape(&shape(node, children, constraints)?) } @@ -549,19 +627,26 @@ pub fn measure_native(node: &UiNode, children: Vec, constraints: [f32; 4]) #[derive(Debug, Default)] /// 只读布局调用期间提供给 Mount 查询的派生上下文,不作为业务状态保留。 pub struct Context { + // 本轮当前出现的不可变根节点;准备未完成为 None,不可回退旧快照伪装。 pub node: Option>, + // 孩子本轮受约束实测尺寸,供原生 measure/arrange 复用而不重复跑源子树。 pub children: Vec, // 本轮首次测量的首选尺寸,不应被上轮 flex 实际分配覆盖,否则反复测量会改变伸缩基准。 pub preferred: Vec, + // 排列阶段可用的临时 [x,y,w,h];测量阶段为 None,禁止提前读几何。 pub bounds: Option<[f32; 4]>, } /// 为单个原生节点按已分配几何生成内容命令;容器背景/边框与整树遍历由外层组织。 pub fn paint_native(node: &UiNode, x: f32, y: f32, size: Size) -> Option { // 文字内容盒需要减 inset 并带 wrap_bounds;Rect/Button 背景则画完整 border-box。 + // 保留分配 Size,防止 Text 模式中的字号字段 size 遮蔽后误用为像素盒宽高。 let size_for_text = size; + // 文字和三维视口绘制内容区,普通矩形/按钮仍使用完整边框盒。 let inset = insets(node); + // 每个节点至多生成一条内容/背景命令,边框和孩子由外层 paint_commands/遍历追加。 match &node.kind { + // 三维 View 占内容区,扣掉边框/内边距后负面积夹为零,世界矩阵保持不变。 UiKind::Viewport3D { view, .. } => Some(RenderCommand::Scene3D { x: x + inset.left, y: y + inset.top, @@ -569,6 +654,7 @@ pub fn paint_native(node: &UiNode, x: f32, y: f32, size: Size) -> Option Some(RenderCommand::Text { x: x + inset.left, y: y + inset.top, @@ -580,6 +666,7 @@ pub fn paint_native(node: &UiNode, x: f32, y: f32, size: Size) -> Option Some(RenderCommand::RoundedRect { x, y, @@ -588,6 +675,7 @@ pub fn paint_native(node: &UiNode, x: f32, y: f32, size: Size) -> Option Some(RenderCommand::RoundedRect { x, y, @@ -596,15 +684,18 @@ pub fn paint_native(node: &UiNode, x: f32, y: f32, size: Size) -> Option None, } } /// 从一个节点及其分配几何生成原生绘制命令,包括背景、边框与内容。 pub fn paint_commands(node: &UiNode, x: f32, y: f32, size: Size) -> Vec { + // 先收集可选内容命令,再顺序追加四边填充条,保证边框覆盖自身内容边缘。 let mut commands: Vec<_> = paint_native(node, x, y, size).into_iter().collect(); // 边框按四个零圆角条分别追加,宽厚各自钳到盒大小;不使用单一 stroke_width 混淆不等厚四边。 let border = node.border; + // 按上、下、左、右四条矩形逐一绘制边框,允许每边厚度不同。 for [x, y, width, height] in [ [x, y, size.width, border.top.min(size.height)], [ @@ -621,6 +712,7 @@ pub fn paint_commands(node: &UiNode, x: f32, y: f32, size: Size) -> Vec 0.0 && height > 0.0 { commands.push(RenderCommand::RoundedRect { x, @@ -640,6 +732,7 @@ pub fn paint_commands(node: &UiNode, x: f32, y: f32, size: Size) -> Vec bool { + // 只解释线性父主轴对应的孩子盒策略,交叉轴 fill 不增加主轴增长权重。 (if row { child.sizing.width } else { @@ -649,7 +742,9 @@ fn main_fill(child: &UiNode, row: bool) -> bool { /// 取出主轴 flex/尺寸策略共同约束下的最小和最大分配范围。 fn main_limits(child: &UiNode, row: bool) -> (f32, f32) { + // 盒模型提供物理轴的 min/max,下面与 flex_policy 范围求交。 let sizing = child.sizing; + // 根据父方向选择孩子的宽或高界限,不能将 flexMin 永远解释为宽度。 let (min, max) = if row { (sizing.min_width, sizing.max_width) } else { @@ -665,17 +760,21 @@ fn main_limits(child: &UiNode, row: bool) -> (f32, f32) { pub fn flex_sizes(node: &UiNode, bounds: Size, children: &[Size], preferred: &[Size]) -> Vec { // Overlay 各孩子独立填内容盒,不共享主轴剩余量;普通线性容器才做下方加权增长/收缩。 if matches!(node.kind, UiKind::Overlay { .. }) { + // Overlay 各项独享同一有限内容区,不把空间按兄弟总权重分割。 let inset = insets(node); return children .iter() .zip(node.children()) .map(|(size, child)| { + // 复制孩子实测值,只修改符合 fill/stretch 条件的轴,不改共享 UiNode。 let mut size = *size; + // Overlay 横轴显式 fill 才占扣 margin 后可用宽,再受盒 min/max 夹取。 if child.sizing.width == crate::box_model::Dimension::Fill { size.width = (bounds.width - inset.horizontal() - child.margin.horizontal()) .max(0.0) .clamp(child.sizing.min_width, child.sizing.max_width); } + // Overlay 纵轴 fill 或 auto+stretch 可扩高;显式 fixed 高度不被父对齐覆盖。 if child.sizing.height == crate::box_model::Dimension::Fill || (child.sizing.height == crate::box_model::Dimension::Auto && child.align_self.unwrap_or(node.cross_align) == CrossAlign::Stretch) @@ -688,19 +787,27 @@ pub fn flex_sizes(node: &UiNode, bounds: Size, children: &[Size], preferred: &[S }) .collect(); } + // 非 Overlay 的非线性节点没有主轴弹性分配,原样返回孩子尺寸。 let Some((row, padding, gap)) = container(node) else { return children.to_vec(); }; + // 按视觉树孩子顺序读取策略,和输入 children/preferred 尺寸保持同序。 let nodes = node.children(); + // 保留原实测尺寸副本,交叉轴拉伸与主轴重分配依次写到该返回值。 let mut output = children.to_vec(); // 先处理交叉轴 Stretch,仅 Auto 维度可拉伸;明确 Fixed 不因父对齐策略被改写。 + // 先按每个孩子 alignSelf 或父 crossAlign 判断交叉轴资格,不依赖主轴是否有增长权重。 for (child, size) in nodes.iter().zip(&mut output) { + // 只有有效对齐为 stretch 才进入尺寸改写,center/end 仅在排列时产生偏移。 if child.align_self.unwrap_or(node.cross_align) == CrossAlign::Stretch { + // 取得孩子盒轴策略和 min/max,拉伸仍不能超过这些明确界限。 let sizing = child.sizing; + // Row 的交叉轴为高度,只拉伸 auto 高,扣父 inset 与孩子上下 margin。 if row && sizing.height == crate::box_model::Dimension::Auto { size.height = (bounds.height - padding.vertical() - child.margin.vertical()) .max(0.0) .clamp(sizing.min_height, sizing.max_height); + // 纵向父的交叉轴为宽度,同样只拉伸 auto 宽,不修改 fixed。 } else if !row && sizing.width == crate::box_model::Dimension::Auto { size.width = (bounds.width - padding.horizontal() - child.margin.horizontal()) .max(0.0) @@ -722,6 +829,7 @@ pub fn flex_sizes(node: &UiNode, bounds: Size, children: &[Size], preferred: &[S - nodes .iter() .map(|child| { + // 扣除每个孩子在主轴两侧的 margin,不能把横向父的上下 margin 算入可分配宽。 if row { child.margin.horizontal() } else { @@ -737,6 +845,7 @@ pub fn flex_sizes(node: &UiNode, bounds: Size, children: &[Size], preferred: &[S .zip(preferred) .map(|(child, size)| { child.flex_policy.basis.unwrap_or_else(|| { + // 有增长或主轴 fill 且没有显式 basis 时从零参与分配,避免把原自然宽重复计入。 if child.flex > 0.0 || main_fill(child, row) { 0.0 } else if row { @@ -747,23 +856,28 @@ pub fn flex_sizes(node: &UiNode, bounds: Size, children: &[Size], preferred: &[S }) as f64 }) .collect(); + // 每个原 basis 先夹主轴合法范围,再根据总剩余量决定增长或收缩。 let mut sizes: Vec = nodes .iter() .zip(&bases) .map(|(child, basis)| { + // 按孩子当前主轴取 flex/box 交集,这份界限同时用于初始夹取与终点饱和。 let (min, max) = main_limits(child, row); basis.clamp(min as f64, max as f64) }) .collect(); // 初始 basis 先钳 min/max,剩余正数为增长,负数为收缩;非参与项仍占据其合法基准尺寸。 let free = space - sizes.iter().sum::(); + // free>0 进入增长,否则是收缩;即使无可分配余量也不会重新发明自然基准。 let growing = free > 0.0; // 增长按 flex,主轴 Fill 且 flex=0 用权重1;收缩按 shrink×原 basis,保持大内容承担较多缩减。 let weights: Vec = nodes .iter() .zip(&bases) .map(|(child, basis)| { + // 增长读取 flex(fill 且 flex=0 时给单位权重),收缩读取 shrink×原始 basis。 if growing { + // 纯 fill 的默认增长权重为一;显式 flex 则使用其用户权重。 if main_fill(child, row) && child.flex == 0.0 { 1.0 } else { @@ -774,10 +888,13 @@ pub fn flex_sizes(node: &UiNode, bounds: Size, children: &[Size], preferred: &[S } }) .collect(); + // 增长端点是各自 max,收缩端点是各自 min,方便以剩余容量统一分配。 let limits: Vec = nodes .iter() .map(|child| { + // 本次取分配终点,策略选择取决于整体 free 的符号,不按单个孩子单独猜测。 let (min, max) = main_limits(child, row); + // 选择本轮饱和终点,之后用绝对容量统一处理增长与收缩。 if growing { max as f64 } else { min as f64 } }) .collect(); @@ -792,12 +909,19 @@ pub fn flex_sizes(node: &UiNode, bounds: Size, children: &[Size], preferred: &[S } }) .collect(); + // 剩余增长/收缩工作量取绝对值,方向只在更新 sizes 时施加。 let mut remaining = free.abs(); + // 只对正权重未饱和项继续分配;饱和项退出后重算剩余权重,避免被夹掉的空间丢失。 while remaining > 0.0 && !active.is_empty() { + // 每轮以当前 active 权重总和为分母,不继续把已触顶/触底项计入比例。 let total = active.iter().map(|&i| weights[i]).sum::(); + // 累计本轮真实分配量,受单项容量限制后可能小于 remaining。 let mut spent = 0.0; + // 记录是否有项达到限制;无饱和时按比例已分完,应停止而不追逐浮点残差。 let mut saturated = false; + // 全部项使用同一轮 remaining 比例,不能边更新 remaining 边偏向后项。 for &i in &active { + // 本项距离增长/收缩端点的绝对容量,本轮 amount 不得超过它。 let capacity = (limits[i] - sizes[i]).abs(); // 本轮按同一 remaining 比例计算,再限制到该项剩余容量;不能为单项超配后再粗暴钳制丢掉剩余量。 let amount = (remaining * weights[i] / total).min(capacity); @@ -812,7 +936,9 @@ pub fn flex_sizes(node: &UiNode, bounds: Size, children: &[Size], preferred: &[S if !saturated { break; } + // 饱和后筛出仍有容量的项,下一轮只在这些项中重新分配剩余量。 active.retain(|&i| { + // 增长保留 sizemin,正权重条件在初始 active 已验证。 if growing { sizes[i] < limits[i] } else { @@ -820,7 +946,9 @@ pub fn flex_sizes(node: &UiNode, bounds: Size, children: &[Size], preferred: &[S } }); } + // 只把最终主轴数值写回 output,交叉轴保留前面的 stretch 结果。 for (size, along) in output.iter_mut().zip(sizes) { + // 横向父写 width,纵向父写 height,不能用同一个 Size 字段表示所有主轴。 if row { size.width = along as f32; } else { @@ -842,8 +970,11 @@ pub fn arrange_native( if matches!(node.kind, UiKind::Viewport3D { .. }) { return Ok(node.children().iter().map(|_| (0., 0.)).collect()); } + // Overlay 各孩子独立在同一内容盒内对齐,不能按线性游标累加位置。 if let UiKind::Overlay { .. } = node.kind { + // 取得含 border 的有效内容 inset,后面的对齐可用范围扣除它。 let padding = insets(node); + // Overlay 把 mainAlign 的 center/end 映射为横轴偏移;其他主轴模式在此按 start 处理。 let horizontal = match node.main_align { MainAlign::Center => CrossAlign::Center, MainAlign::End => CrossAlign::End, @@ -853,7 +984,9 @@ pub fn arrange_native( .iter() .zip(node.children()) .map(|(size, child)| { + // 对齐比较占用含孩子 margin,最终原点再加左/上 margin。 let outer = child.margin.outer(*size); + // 每项独立计算绝对原点,兄弟的大小或数量不改变本项对齐空间。 let point = ( x + padding.left + child.margin.left @@ -873,7 +1006,9 @@ pub fn arrange_native( }) .collect(); } + // 二维视口里的 Scene2D 根先放在内容起点,世界相机投影由后续 viewport 处理。 if matches!(node.kind, UiKind::CanvasViewport { .. }) { + // 边框/内边距影响视口内容原点,但不重写场景内部业务 x/y。 let inset = insets(node); return Ok(node .children() @@ -881,19 +1016,24 @@ pub fn arrange_native( .map(|_| (x + inset.left, y + inset.top)) .collect()); } + // 世界布局直接用各孩子业务位置加父原点,不做线性 gap 或主轴对齐。 if let UiKind::Canvas { positions, .. } | UiKind::Scene2D { positions, .. } = &node.kind { return Ok(positions .iter() .map(|point| (x + point[0], y + point[1])) .collect()); } + // 其余种类只有线性容器才安排孩子,叶节点返回空位置表。 let Some((row, padding, gap)) = container(node) else { return Ok(vec![]); }; + // 按实际分配后的主轴外尺寸与固定 gap 求总占用,margin 不能漏算。 let occupied = children .iter() .zip(node.children()) .map(|(child, node)| { + // 根据父方向取宽+左右 margin 或高+上下 margin,交叉尺寸不进入主轴占用。 + // 父交叉轴内容尺寸先扣该方向的 inset:Row 用高,纵向父用宽。 if row { child.width + node.margin.horizontal() } else { @@ -902,7 +1042,9 @@ pub fn arrange_native( }) .sum::() + gap * children.len().saturating_sub(1) as f32; + // 父实际分配的主轴边框盒长度,下一步扣父 inset 与孩子总占用。 let available = if row { bounds.width } else { bounds.height }; + // 不足空间时剩余量夹为零,center/end 不产生负偏移让内容前缘不可达。 let spare = (available - if row { padding.horizontal() @@ -911,6 +1053,7 @@ pub fn arrange_native( } - occupied) .max(0.0); + // 主轴 center/end 只分配剩余空白,不再更改 flex 阶段已经求好的尺寸。 let offset = match node.main_align { MainAlign::Center => spare / 2.0, MainAlign::End => spare, @@ -922,13 +1065,21 @@ pub fn arrange_native( } else { 0.0 }; + // 线性游标从父起侧 inset 加整体 offset 开始,后续逐项累积外尺寸和间距。 let mut cursor = if row { padding.left } else { padding.top } + offset; + // 输出只含孩子原点,顺序对应 children 和 node.children,不携带托管引用。 let mut points = Vec::with_capacity(children.len()); + // 逐孩子按实际尺寸、各自 margin 与 alignSelf 计算,避免把共享业务对象的两处位置合并。 for (index, child) in children.iter().enumerate() { + // 用同一位置索引取得样式,不能按 block_id 查找唯一孩子而误处理中重复出现。 let child_node = &node.children()[index]; + // 本项四边外占用,主轴推进和交叉对齐分别使用对应两边和。 let margin = child_node.margin; + // 显式 alignSelf 优先,None 才继承此父出现的 crossAlign。 let align = child_node.align_self.unwrap_or(node.cross_align); + // 在父交叉内容尺寸中按孩子外尺寸求非负偏移,不修改主轴游标。 let cross = align.offset( + // 孩子交叉外尺寸包含对应两边 margin,与父内容尺寸使用同一物理轴。 if row { bounds.height - padding.vertical() } else { @@ -940,6 +1091,7 @@ pub fn arrange_native( child.width + margin.horizontal() }, ); + // 把主轴 cursor 与交叉偏移按方向还原成绝对 x/y,并叠加父与孩子起侧边距。 let point = if row { ( x + cursor + margin.left, @@ -971,6 +1123,7 @@ pub fn arrange_native( impl LayoutRuntime { /// 从页面模式和当前视口生成根节点约束;无视口时使用明确的无界轴哨兵。 pub fn root_constraints(&self) -> [f32; 4] { + // 有旧页面模式时按其有限/延伸轴生成根约束,否则用普通视口最大约束。 self.page_mode.map_or_else( || root_constraints(self.viewport), |mode| mode.constraints(self.viewport), @@ -978,10 +1131,12 @@ impl LayoutRuntime { } /// 撤销指定业务组件的测量缓存,下一次遇到该节点重新求值。 pub fn invalidate(&mut self, block: &str) { + // 只移除指定业务身份最后一份测量键,其他节点缓存和稳定出现 ID 不受此入口影响。 self.sizes.remove(block); } /// 提高新 Mount ID 的分配下限,避免取消/重试后复用已经暴露过的出现身份。 pub fn reserve_identity_floor(&mut self, floor: u64) { + // 取消恢复后把临时分配过的 ID 高水位带回,不能重新分配可能已暴露的身份。 self.next_id = self.next_id.max(floor); } /// 返回出现 ID 的当前分配高水位,供桥接层在取消/重试后继续保持唯一性。 @@ -998,7 +1153,9 @@ impl LayoutRuntime { pub fn frame(&mut self, root: &UiNode) -> Result { // Stage all cache/identity changes; a rejected frame leaves the last // valid occurrence registry intact and never publishes partial geometry. + // 缓存、ID 分配和统计都先在副本上变更,build 失败不污染当前运行时。 let mut next = self.clone(); + // 完整原生构建成功才提交副本;返回 Frame 仍由桥接添加投影/发布上下文。 let frame = next.build(root, false)?; *self = next; Ok(frame) @@ -1007,7 +1164,9 @@ impl LayoutRuntime { /// Allocate stable occurrence identities without measuring or publishing geometry. /// 先建立稳定的出现身份和父子关系,但不把此阶段当成最终测量结果。 pub fn structure(&mut self, root: &UiNode) -> Result { + // 结构准备也使用事务式副本,失败不能留下部分新出现映射。 let mut next = self.clone(); + // 只分配身份和链接,暂用零几何;后续源布局才提供有效测量与排列结果。 let frame = next.build(root, true)?; *self = next; Ok(frame) @@ -1022,6 +1181,7 @@ impl LayoutRuntime { ) -> Result { // 缓存只有完整 Shape 相等才复用,纯颜色变化不在测量 Shape 中,因此无需重做尺寸求解。 let shape = shape(node, children, constraints)?; + // 同业务 ID 还必须完整 Shape 相等才命中;不同约束共享对象可能轮流覆盖最后键。 if let Some((_, size)) = self .sizes .get(&node.block_id) @@ -1030,6 +1190,7 @@ impl LayoutRuntime { return Ok(*size); } self.measured += 1; + // 实际未命中才测量,成功后更新 sizes;失败不安装不可用的测量条目。 let size = measure_shape(&shape)?; self.sizes.insert(node.block_id.clone(), (shape, size)); Ok(size) @@ -1037,15 +1198,20 @@ impl LayoutRuntime { /// 迭代展开出现树、计算约束和几何、产生绘制命令;结构准备与完整布局共用此驱动。 fn build(&mut self, root: &UiNode, structural: bool) -> Result { + // 按本次构建重置计数;structural 只准备身份,不把零几何当一次已完成测量/排列。 self.measured = 0; self.arranged = 0; self.settle_passes = usize::from(!structural); self.slices = usize::from(!structural); + // 将树展开为父先子后出现数组,每个位置保存自己的约束与身份。 let mut items = Vec::>::new(); // 用显式栈构建父先子后 items,根采用 slot0/无父;孩子逆序入栈保持原始布局顺序。 let mut work = vec![(root, None::, 0, self.root_constraints())]; + // 本轮结构键集合用于检测重复 slot,并在成功后移除过时 ID 映射。 let mut used = HashSet::new(); + // 显式 DFS 遍历原生视觉树,共享 Arc 在不同 slot/父下仍会形成独立出现。 while let Some((node, parent, slot, constraints)) = work.pop() { + // 按本次展开条目数检查一万上限,超限拒绝整帧而不是截断余下孩子。 if items.len() >= MAX_LAYOUT_VISITS { bail!("expanded UI layout exceeds 10000 nodes"); } @@ -1053,6 +1219,7 @@ impl LayoutRuntime { if node.slots.len() != node.children().len() { bail!("invalid child slot table"); } + // 稳定身份包含父 Mount ID、组成 slot 和业务 ID;不是仅凭对象身份分配一个 ID。 let key = Key { parent: parent.map(|i| items[i].id), slot, @@ -1073,7 +1240,9 @@ impl LayoutRuntime { if !used.insert(key) { bail!("duplicate child slot in one presentation"); } + // 保存本出现的数组索引,后面作为孩子 parent 与尺寸/位置数组下标。 let index = items.len(); + // 将当前索引追加到父孩子列表,保持实际遍历次序供后序测量与兄弟链接。 if let Some(parent) = parent { items[parent].children.push(index); } @@ -1084,6 +1253,7 @@ impl LayoutRuntime { id, constraints, }); + // 孩子逆序压栈以按原组成顺序出栈,初始约束同时按该出现的父 offer 细化。 for (child_index, (child, slot)) in node.children().iter().zip(&node.slots).enumerate().rev() { @@ -1095,7 +1265,9 @@ impl LayoutRuntime { )); } } + // 每个出现一个尺寸槽,不按共享业务 ID 合并几何;结构准备保留这些零值占位。 let mut sizes = vec![Size::default(); items.len()]; + // 完整路径才反向测量,使每个父求自然尺寸时孩子尺寸已经可用。 if !structural { // 反向 items 自底向上测量,孩子尺寸已经求出;structural=true 完全跳过此步骤,零几何仅用于挂载准备。 for (index, item) in items.iter().enumerate().rev() { @@ -1109,19 +1281,28 @@ impl LayoutRuntime { ); } } + // 原点按出现数组独立保存,根为零,父排列后写入各子槽。 let mut points = vec![(0.0_f32, 0.0_f32); items.len()]; + // 最终发布几何数组容量按出现数预留,但不会在构建失败时替换旧运行状态。 let mut mounts = Vec::with_capacity(items.len()); + // 先序展开时按节点内容/边框顺序追加业务命令,后续投影阶段再处理视口和滚动。 let mut commands = Vec::new(); + // 默认每个出现无后继,下面只对同一父的相邻孩子建立 next_sibling。 let mut siblings = vec![None; items.len()]; // 先按每个父的孩子顺序建立 next_sibling,最后一个默认 None;这与业务孩子列表身份不同。 + // 父先序数组不保证相邻元素就是同级,须显式按每个父的 children 建链接。 for item in &items { + // 只把相邻孩子前项连向后项,最后一个保留 None,不串到下个父的子树。 for pair in item.children.windows(2) { siblings[pair[0]] = Some(items[pair[1]].id); } } + // 按先序安排,父已先给孩子写入尺寸/原点,当前项可生成对应 Mount 与自身绘制。 for (index, item) in items.iter().enumerate() { self.arranged += usize::from(!structural); + // 读取此出现原点,接着检查原点和加宽高后的两个远端都在有符号坐标预算中。 let (x, y) = points[index]; + // 取本出现实际尺寸,可能已被父 flex 分配覆盖,不能重新读取业务自然尺寸。 let size = sizes[index]; coordinate(x)?; coordinate(y)?; @@ -1151,19 +1332,24 @@ impl LayoutRuntime { interactive: item.node.interactive, pointer_events: item.node.pointer_events, }); + // 只有完整路径生成内容/边框命令,结构准备不得把零几何发布为实际画面。 if !structural { commands.extend(paint_commands(item.node, x, y, size)); } + // 结构准备只需要身份/链接,直接跳过孩子尺寸分配和位置安排。 if structural { continue; } + // 收集此父孩子当前尺寸作为单次纯原生分配的输入,源协议多轮 remeasure 在外层完成。 let child_sizes: Vec<_> = item.children.iter().map(|child| sizes[*child]).collect(); // 自顶向下用父实际尺寸更新孩子分配后再求原点;更复杂的源协议反复求解由 source_layout 驱动。 let child_sizes = flex_sizes(item.node, size, &child_sizes, &child_sizes); + // 按出现索引写回 flex/拉伸实际分配,不改变共享 UiNode 的自然属性。 for (child, allocated) in item.children.iter().zip(&child_sizes) { sizes[*child] = *allocated; } + // 把 arrange_native 的同序位置表写入每个子出现槽,之后先序遍历即可消费。 for (child, point) in item.children .iter() @@ -1174,6 +1360,7 @@ impl LayoutRuntime { } // 成功求解后丢弃已消失出现和不在本树的测量缓存,避免历史页面不断积累派生条目。 self.ids.retain(|key, _| used.contains(key)); + // 成功后只保留本树出现过的业务测量键,避免切页后旧派生尺寸持续积累。 let blocks: HashSet<_> = items .iter() .map(|item| item.node.block_id.as_str()) @@ -1196,11 +1383,13 @@ impl LayoutRuntime { /// 在临时 LayoutRuntime 中生成完整几何,成功后才替换现有缓存和身份状态。 pub fn frame(root: &UiNode) -> Result { + // 一次性调用没有跨帧缓存;需要稳定出现身份的窗口应保留自己的 LayoutRuntime。 LayoutRuntime::default().frame(root) } /// 为指定逻辑视口建立临时布局运行时并求完整帧。 pub fn frame_with_viewport(root: &UiNode, viewport: Size) -> Result { + // 为独立原生测量/测试建立有限视口运行时,不创建 VM 或 OS 窗口资源。 LayoutRuntime { viewport: Some(viewport), ..Default::default()