docs: explain Tessera modules and execution flows in Chinese

This commit is contained in:
2026-11-11 23:36:03 +08:00
parent 4c3fc8b5dd
commit 1fedd21d3c
77 changed files with 1418 additions and 0 deletions
+56
View File
@@ -1,3 +1,7 @@
//! 原生布局求解器:自底向上测量期望尺寸,再自顶向下分配位置和实际尺寸。
//! Row/Column/Overlay、边距、边框、内边距、对齐和弹性空间都在有限约束内计算;过大的尺寸和坐标返回错误。
//! 缓存按组件形状、子项尺寸和约束判断可复用性。frame 先在克隆状态中求解,成功才替换运行状态,防止失败污染已发布几何。
//!
//! Iterative measure/arrange/paint over derived visual data. Every occurrence
//! has its own geometry; measurement caches never become semantic object state.
use crate::{
@@ -11,6 +15,7 @@ use std::collections::{HashMap, HashSet};
const MAX_LAYOUT_VISITS: usize = 10_000;
#[derive(Debug, Clone, Copy, Default, PartialEq)]
/// 上右下左四边的空间占用,用于 margin、padding 和 border 计算。
pub struct Insets {
pub top: f32,
pub right: f32,
@@ -19,12 +24,15 @@ pub struct Insets {
}
impl Insets {
/// 返回该边距集合在水平方向占据的总空间。
pub fn horizontal(self) -> f32 {
self.left + self.right
}
/// 返回该边距集合在垂直方向占据的总空间。
pub fn vertical(self) -> f32 {
self.top + self.bottom
}
/// 在内容尺寸外加上对应四边占用,得到外层测量尺寸。
fn outer(self, size: Size) -> Size {
Size {
width: size.width + self.horizontal(),
@@ -36,6 +44,7 @@ impl Insets {
/// Alignment inside a finite cross-axis content box. Overflow remains start
/// aligned so that content cannot become inaccessible beyond the leading edge.
#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
/// 交叉轴对齐规则;Stretch 需要结合子项是否自动尺寸决定实际拉伸。
pub enum CrossAlign {
#[default]
Start,
@@ -45,6 +54,7 @@ pub enum CrossAlign {
}
impl CrossAlign {
/// 返回内部枚举或对象对应的稳定源名称。
pub fn name(self) -> &'static str {
match self {
Self::Start => "start",
@@ -54,6 +64,7 @@ impl CrossAlign {
}
}
/// 把外部源码或属性表示转换为内部枚举/结构,并反馈不支持的输入。
pub fn parse(value: &str) -> Result<Self, endor_core::VmError> {
match value {
"start" => Ok(Self::Start),
@@ -66,6 +77,7 @@ impl CrossAlign {
}
}
/// 根据交叉轴对齐方式计算有限剩余空间中的偏移。
fn offset(self, available: f32, occupied: f32) -> f32 {
let spare = (available - occupied).max(0.0);
match self {
@@ -77,6 +89,7 @@ impl CrossAlign {
}
#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
/// 容器主轴的内容对齐或剩余间隔分配方式。
pub enum MainAlign {
#[default]
Start,
@@ -85,6 +98,7 @@ pub enum MainAlign {
SpaceBetween,
}
impl MainAlign {
/// 返回内部枚举或对象对应的稳定源名称。
pub fn name(self) -> &'static str {
match self {
Self::Start => "start",
@@ -93,6 +107,7 @@ impl MainAlign {
Self::SpaceBetween => "space-between",
}
}
/// 把外部源码或属性表示转换为内部枚举/结构,并反馈不支持的输入。
pub fn parse(value: &str) -> Result<Self, endor_core::VmError> {
match value {
"start" => Ok(Self::Start),
@@ -108,6 +123,7 @@ impl MainAlign {
/// Main-axis constraints interpreted independently by each parent occurrence.
#[derive(Debug, Clone, Copy, PartialEq)]
/// 主轴伸缩策略与限值,不能用一个宽度常量替代完整分配规则。
pub struct FlexPolicy {
pub basis: Option<f32>,
pub min: f32,
@@ -115,6 +131,7 @@ pub struct FlexPolicy {
pub shrink: f32,
}
impl Default for FlexPolicy {
/// 建立类型约定的初始值,供尚未发布或尚未交互的状态使用。
fn default() -> Self {
Self {
basis: None,
@@ -126,12 +143,14 @@ impl Default for FlexPolicy {
}
#[derive(Default, Debug, Clone, Copy, PartialEq, serde::Serialize, serde::Deserialize)]
/// 逻辑宽高值,不隐含窗口像素比例或相机缩放。
pub struct Size {
pub width: f32,
pub height: f32,
}
#[derive(Debug, Clone, PartialEq)]
/// 影响原生测量的缓存形状,避免把颜色等纯绘制变化视为尺寸变化。
enum Shape {
Sized(Box<Shape>, crate::box_model::Sizing, [f32; 4]),
Text(String, u32, f32),
@@ -141,6 +160,7 @@ enum Shape {
}
#[derive(Debug, Clone, Hash, PartialEq, Eq)]
/// 结构出现身份键,区分同一业务对象在不同父位置的展示。
struct Key {
parent: Option<u64>,
slot: u64,
@@ -148,6 +168,7 @@ struct Key {
}
#[derive(Debug, Clone, Default)]
/// 布局缓存、稳定出现身份与统计。构建在临时副本上完成,成功后才写回。
pub struct LayoutRuntime {
sizes: HashMap<String, (Shape, Size)>,
ids: HashMap<Key, u64>,
@@ -161,6 +182,7 @@ pub struct LayoutRuntime {
pub page_mode: Option<crate::page::Mode>,
}
/// 迭代遍历中的一个出现,保存父子索引、约束与稳定 ID。
struct Item<'a> {
node: &'a UiNode,
parent: Option<usize>,
@@ -169,6 +191,7 @@ struct Item<'a> {
constraints: [f32; 4],
}
/// 检查尺寸非负、有限且不超过布局上限。
fn bounded(value: f32) -> Result<f32> {
if !value.is_finite() || !(0.0..=MAX_DIMENSION as f32).contains(&value) {
bail!("UI layout exceeds the 1000000 coordinate/size limit");
@@ -176,6 +199,7 @@ fn bounded(value: f32) -> Result<f32> {
Ok(value)
}
/// 检查允许有正负方向的坐标仍在安全布局范围内。
fn coordinate(value: f32) -> Result<f32> {
if !value.is_finite() || value.abs() > MAX_DIMENSION as f32 {
bail!("UI coordinate exceeds the 1000000 limit");
@@ -183,6 +207,7 @@ fn coordinate(value: f32) -> Result<f32> {
Ok(value)
}
/// 从页面模式和当前视口生成根节点约束;无视口时使用明确的无界轴哨兵。
pub fn root_constraints(viewport: Option<Size>) -> [f32; 4] {
let size = viewport.unwrap_or(Size {
width: MAX_DIMENSION as f32,
@@ -191,6 +216,7 @@ pub fn root_constraints(viewport: Option<Size>) -> [f32; 4] {
[0.0, 0.0, size.width, size.height]
}
/// 从父级上限扣除内边距;无界哨兵保持无界,不因减法被误认为有限。
fn content_limit(available: f32, inset: f32) -> f32 {
if available >= MAX_DIMENSION as f32 {
available
@@ -198,6 +224,7 @@ fn content_limit(available: f32, inset: f32) -> f32 {
(available - inset).max(0.0)
}
}
/// 把父盒子的可用尺寸传递给子项,扣除容器内边距并考虑主轴是否可延伸。
pub fn child_constraints(node: &UiNode, parent: [f32; 4]) -> [f32; 4] {
let parent = node.sizing.available(parent);
if let UiKind::Overlay { .. } = node.kind {
@@ -239,6 +266,7 @@ pub fn child_constraints(node: &UiNode, parent: [f32; 4]) -> [f32; 4] {
}
}
/// 从子项可用范围扣除外边距,并使最小值不超过调整后的最大值。
pub fn margin_constraints(child: &UiNode, mut constraints: [f32; 4]) -> [f32; 4] {
for (axis, margin) in [child.margin.horizontal(), child.margin.vertical()]
.into_iter()
@@ -254,6 +282,7 @@ pub fn margin_constraints(child: &UiNode, mut constraints: [f32; 4]) -> [f32; 4]
/// Main-axis fill first measures against a finite offer, then participates in
/// weighted allocation. The unlimited-axis sentinel is never made finite by padding.
/// 根据具体子项尺寸策略和所在位置细化约束;世界 UI 根使用面板的有限像素尺寸。
pub fn occurrence_constraints(
parent: &UiNode,
child: &UiNode,
@@ -281,6 +310,7 @@ pub fn occurrence_constraints(
margin_constraints(child, base)
}
/// 生成求解开始时的子项约束,供后续测量和分配迭代使用。
pub fn initial_child_constraints(
parent: &UiNode,
child: &UiNode,
@@ -301,6 +331,7 @@ pub fn initial_child_constraints(
}
/// Scroll cross-axis constraints come from this occurrence's actual viewport,
/// including a source parent's allocation rather than only constructor size.
/// 根据已分配父尺寸重新细化子项约束,使实际安排能够反向影响换行等测量。
pub fn arranged_child_constraints(node: &UiNode, available: [f32; 4], bounds: Size) -> [f32; 4] {
if let UiKind::Scroll { axis, .. } = node.kind {
let padding = insets(node);
@@ -322,6 +353,7 @@ pub fn arranged_child_constraints(node: &UiNode, available: [f32; 4], bounds: Si
child_constraints(node, available)
}
/// 将期望尺寸限制在调用方给出的最小/最大边界内。
pub fn constrained(size: Size, constraints: [f32; 4]) -> Size {
Size {
width: size.width.clamp(constraints[0], constraints[2]),
@@ -330,6 +362,7 @@ pub fn constrained(size: Size, constraints: [f32; 4]) -> Size {
}
/// Effective content inset, including borders, in border-box coordinates.
/// 计算布局使用的有效内边距和边框占用,兼容旧的统一 padding。
pub fn insets(node: &UiNode) -> Insets {
let fallback = match node.kind {
UiKind::Row { padding, .. }
@@ -347,6 +380,7 @@ pub fn insets(node: &UiNode) -> Insets {
}
}
/// 提取容器方向与间距等原生布局配置,叶节点不参与容器规则。
fn container(node: &UiNode) -> Option<(bool, Insets, f32)> {
match &node.kind {
UiKind::Row { gap, .. } => Some((true, insets(node), *gap)),
@@ -358,10 +392,12 @@ fn container(node: &UiNode) -> Option<(bool, Insets, f32)> {
}
}
/// 根据容器方向选择主轴,供 flex 和对齐共享同一判断。
pub fn main_axis(node: &UiNode) -> Option<usize> {
container(node).map(|(row, _, _)| usize::from(!row))
}
/// 根据形状键计算期望尺寸,包括文字换行、容器子项和盒模型占用。
fn measure_shape(shape: &Shape) -> Result<Size> {
let size = match shape {
Shape::Sized(shape, sizing, constraints) => {
@@ -419,6 +455,7 @@ fn measure_shape(shape: &Shape) -> Result<Size> {
Ok(size)
}
/// 建立影响测量的形状键,将布局属性、子项测量结果和约束组合起来。
fn shape(node: &UiNode, children: Vec<Size>, constraints: [f32; 4]) -> Result<Shape> {
let available = node.sizing.available(constraints);
let shape = match &node.kind {
@@ -481,6 +518,7 @@ fn shape(node: &UiNode, children: Vec<Size>, constraints: [f32; 4]) -> Result<Sh
})
}
/// 执行原生节点测量并应用布局约束,作为源协议的原生实现。
pub fn measure_native(node: &UiNode, children: Vec<Size>, constraints: [f32; 4]) -> Result<Size> {
measure_shape(&shape(node, children, constraints)?)
}
@@ -488,6 +526,7 @@ pub fn measure_native(node: &UiNode, children: Vec<Size>, constraints: [f32; 4])
/// Private derived scratch space for one occurrence during layout. Contains no
/// managed references; source code cannot mutate it through heap attributes.
#[derive(Debug, Default)]
/// 只读布局调用期间提供给 Mount 查询的派生上下文,不作为业务状态保留。
pub struct Context {
pub node: Option<std::sync::Arc<UiNode>>,
pub children: Vec<Size>,
@@ -495,6 +534,7 @@ pub struct Context {
pub bounds: Option<[f32; 4]>,
}
/// 为单个原生节点按已分配几何生成内容命令;容器背景/边框与整树遍历由外层组织。
pub fn paint_native(node: &UiNode, x: f32, y: f32, size: Size) -> Option<RenderCommand> {
let size_for_text = size;
let inset = insets(node);
@@ -537,6 +577,7 @@ pub fn paint_native(node: &UiNode, x: f32, y: f32, size: Size) -> Option<RenderC
}
}
/// 从一个节点及其分配几何生成原生绘制命令,包括背景、边框与内容。
pub fn paint_commands(node: &UiNode, x: f32, y: f32, size: Size) -> Vec<RenderCommand> {
let mut commands: Vec<_> = paint_native(node, x, y, size).into_iter().collect();
let border = node.border;
@@ -573,6 +614,7 @@ pub fn paint_commands(node: &UiNode, x: f32, y: f32, size: Size) -> Vec<RenderCo
/// Allocate main-axis space with bounded growth and basis-weighted shrinking.
/// Preferred sizes come from this occurrence's first measurement in the solve;
/// remeasurement must not turn a prior allocation into a new intrinsic basis.
/// 判断子项主轴是否采用 fill,从而参与剩余空间分配。
fn main_fill(child: &UiNode, row: bool) -> bool {
(if row {
child.sizing.width
@@ -581,6 +623,7 @@ fn main_fill(child: &UiNode, row: bool) -> bool {
}) == crate::box_model::Dimension::Fill
}
/// 取出主轴 flex/尺寸策略共同约束下的最小和最大分配范围。
fn main_limits(child: &UiNode, row: bool) -> (f32, f32) {
let sizing = child.sizing;
let (min, max) = if row {
@@ -594,6 +637,7 @@ fn main_limits(child: &UiNode, row: bool) -> (f32, f32) {
)
}
/// 按权重分配主轴剩余空间,尊重每项 min/max;达到上限的项退出后重新分配剩余量。
pub fn flex_sizes(node: &UiNode, bounds: Size, children: &[Size], preferred: &[Size]) -> Vec<Size> {
if matches!(node.kind, UiKind::Overlay { .. }) {
let inset = insets(node);
@@ -752,6 +796,7 @@ pub fn flex_sizes(node: &UiNode, bounds: Size, children: &[Size], preferred: &[S
output
}
/// 根据最终分配尺寸计算子项原点,处理容器方向、对齐、间距与外边距。
pub fn arrange_native(
node: &UiNode,
x: f32,
@@ -887,25 +932,31 @@ 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),
)
}
/// 撤销指定业务组件的测量缓存,下一次遇到该节点重新求值。
pub fn invalidate(&mut self, block: &str) {
self.sizes.remove(block);
}
/// 提高新 Mount ID 的分配下限,避免取消/重试后复用已经暴露过的出现身份。
pub fn reserve_identity_floor(&mut self, floor: u64) {
self.next_id = self.next_id.max(floor);
}
/// 返回出现 ID 的当前分配高水位,供桥接层在取消/重试后继续保持唯一性。
pub fn identity_high_watermark(&self) -> u64 {
self.next_id
}
/// 清空结构出现身份表;业务对象和源状态不因此被复制。
pub fn clear_occurrences(&mut self) {
self.ids.clear();
}
/// 在临时 LayoutRuntime 中生成完整几何,成功后才替换现有缓存和身份状态。
pub fn frame(&mut self, root: &UiNode) -> Result<Frame> {
// Stage all cache/identity changes; a rejected frame leaves the last
// valid occurrence registry intact and never publishes partial geometry.
@@ -916,6 +967,7 @@ impl LayoutRuntime {
}
/// Allocate stable occurrence identities without measuring or publishing geometry.
/// 先建立稳定的出现身份和父子关系,但不把此阶段当成最终测量结果。
pub fn structure(&mut self, root: &UiNode) -> Result<Frame> {
let mut next = self.clone();
let frame = next.build(root, true)?;
@@ -923,6 +975,7 @@ impl LayoutRuntime {
Ok(frame)
}
/// 以形状、子项尺寸和约束查缓存;未命中才执行测量并更新本轮统计。
pub fn measure_node(
&mut self,
node: &UiNode,
@@ -943,6 +996,7 @@ impl LayoutRuntime {
Ok(size)
}
/// 迭代展开出现树、计算约束和几何、产生绘制命令;结构准备与完整布局共用此驱动。
fn build(&mut self, root: &UiNode, structural: bool) -> Result<Frame> {
self.measured = 0;
self.arranged = 0;
@@ -1091,10 +1145,12 @@ impl LayoutRuntime {
}
}
/// 在临时 LayoutRuntime 中生成完整几何,成功后才替换现有缓存和身份状态。
pub fn frame(root: &UiNode) -> Result<Frame> {
LayoutRuntime::default().frame(root)
}
/// 为指定逻辑视口建立临时布局运行时并求完整帧。
pub fn frame_with_viewport(root: &UiNode, viewport: Size) -> Result<Frame> {
LayoutRuntime {
viewport: Some(viewport),