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
+15
View File
@@ -1,3 +1,6 @@
//! 旧 Page.mode 的兼容空间策略,以及页面级的正逆相机变换。
//! 新组合应优先使用普通布局、ScrollView 和独立场景视口;保留这里是为了兼容已有 window/vertical/horizontal/canvas 页面。
//!
//! Page space is independent of the native window. The camera is applied once
//! for painting and inverted once for input; layout and Mounts stay in world units.
use crate::{geometry::Point, layout::Size};
@@ -6,6 +9,7 @@ use serde::{Deserialize, Serialize};
#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "lowercase")]
/// 旧 Page 的有限或自由空间模式,新场景视口不依赖它表达布局方向。
pub enum Mode {
#[default]
Window,
@@ -15,6 +19,7 @@ pub enum Mode {
}
impl Mode {
/// 返回内部枚举或对象对应的稳定源名称。
pub fn name(self) -> &'static str {
match self {
Self::Window => "window",
@@ -24,6 +29,7 @@ impl Mode {
}
}
/// 把外部源码或属性表示转换为内部枚举/结构,并反馈不支持的输入。
pub fn parse(name: &str) -> Result<Self, VmError> {
match name {
"window" => Ok(Self::Window),
@@ -36,6 +42,7 @@ impl Mode {
}
}
/// 为旧页面模式生成有限轴和可延伸轴的根约束。
pub fn constraints(self, viewport: Option<Size>) -> [f32; 4] {
let Some(size) = viewport else {
return crate::layout::root_constraints(None);
@@ -51,6 +58,7 @@ impl Mode {
}
#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
/// 页面级兼容相机状态和有限内容范围,支持绘制与命中正逆变换。
pub struct Surface {
pub mode: Mode,
pub page: String,
@@ -60,11 +68,13 @@ pub struct Surface {
pub extent: Size,
}
/// 生成页面相机计算所需的单位比例或边界默认值。
fn unit() -> f32 {
1.0
}
impl Default for Surface {
/// 建立类型约定的初始值,供尚未发布或尚未交互的状态使用。
fn default() -> Self {
Self {
mode: Mode::Window,
@@ -77,6 +87,7 @@ impl Default for Surface {
}
impl Surface {
/// 构造本类型并初始化其状态;资源建立和默认字段以函数体为准。
pub fn new(mode: Mode) -> Self {
Self {
mode,
@@ -85,6 +96,7 @@ impl Surface {
}
}
/// 把页面视图坐标反算为旧 Page 相机下的世界坐标。
pub fn to_world(&self, point: Point) -> Point {
Point::new(
point.x / self.zoom + self.pan.x,
@@ -92,6 +104,7 @@ impl Surface {
)
}
/// 把旧页面世界坐标变换到可见视图坐标。
pub fn to_view(&self, point: Point) -> Point {
Point::new(
(point.x - self.pan.x) * self.zoom,
@@ -99,6 +112,7 @@ impl Surface {
)
}
/// 判断给定点是否位于目标范围;需要相机转换的类型会先转换再判断。
pub fn contains(&self, point: [f32; 2], viewport: Option<Size>) -> bool {
let point = self.to_view(Point::new(point[0], point[1]));
point.x >= 0.0
@@ -106,6 +120,7 @@ impl Surface {
&& viewport.is_none_or(|size| point.x < size.width && point.y < size.height)
}
/// 只对有限页面按实际内容范围钳制偏移;自由画布不按内容边缘停止导航。
pub fn clamp(&mut self, viewport: Size) {
match self.mode {
Mode::Window => {