docs: explain Tessera modules and execution flows in Chinese
This commit is contained in:
@@ -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),
|
||||
|
||||
Reference in New Issue
Block a user