docs: explain Tessera modules and execution flows in Chinese
This commit is contained in:
@@ -1,3 +1,7 @@
|
||||
//! Block 的共享赋值、底层 Data 与视觉属性实现。Block 通过 Cell 间接指向 Data,使别名能观察到同一次替换。
|
||||
//! Data 保存子组件 slot、布局配置、绑定和订阅。属性读写需要沿有效的类型/存储路径解析,不能把快照当成可变业务对象。
|
||||
//! 提取视觉数据时将托管属性覆盖到原生描述;校验负责拒绝循环、非法尺寸和不符合类型的组成。
|
||||
//!
|
||||
//! Live visual objects. All semantic references are owned by Aster's heap;
|
||||
//! native Arcs are reserved for immutable rendering snapshots.
|
||||
use std::sync::Arc;
|
||||
@@ -7,12 +11,14 @@ use endor_core::{NativeContext, ObjectPayload, ObjectRef, ObjectStore, Value, Vm
|
||||
use crate::ui_bridge::UiNode;
|
||||
|
||||
#[derive(Debug, Clone)]
|
||||
/// 稳定组成 slot 与子 Block 的配对;slot 不依赖孩子当前的屏幕位置。
|
||||
pub struct Child {
|
||||
pub slot: u64,
|
||||
pub block: ObjectRef,
|
||||
}
|
||||
|
||||
#[derive(Debug, Clone)]
|
||||
/// 原生组件分类,只描述业务组件种类;每种展示几何由布局和 Mount 另行生成。
|
||||
pub enum Kind {
|
||||
Text {
|
||||
value: String,
|
||||
@@ -49,6 +55,7 @@ pub enum Kind {
|
||||
/// The VM owns the Block -> Cell -> Data relationship. Shared assignment
|
||||
/// changes the Cell to point at another Block, retaining the original identity.
|
||||
#[derive(Debug, Clone)]
|
||||
/// 对共享 Cell 的稳定包装。赋值可让所有别名一起改指向,而每次出现的 Mount 仍独立。
|
||||
pub struct Block {
|
||||
pub state: ObjectRef,
|
||||
pub page: bool,
|
||||
@@ -56,9 +63,11 @@ pub struct Block {
|
||||
}
|
||||
|
||||
impl ObjectPayload for Block {
|
||||
/// 声明此 payload 的赋值遵循引用身份语义,避免把内部宿主状态当作可复制值。
|
||||
fn reference_assignment_only(&self) -> bool {
|
||||
true
|
||||
}
|
||||
/// 沿 Block 的共享 Cell 定位属性存储,使别名替换后读取到同一份新 Data。
|
||||
fn attribute_target(&self, store: &ObjectStore) -> Result<Option<ObjectRef>, VmError> {
|
||||
let Value::Object(value) = store.cell_get(self.state)? else {
|
||||
return Err(VmError::InvalidArgument("Block state is not an object"));
|
||||
@@ -76,6 +85,7 @@ impl ObjectPayload for Block {
|
||||
}
|
||||
}
|
||||
|
||||
/// 从 Block 当前 Data 解析其类型转发目标,使共享替换后的类型查询仍一致。
|
||||
fn type_target(&self, store: &ObjectStore) -> Result<Option<ObjectRef>, VmError> {
|
||||
let Value::Object(value) = store.cell_get(self.state)? else {
|
||||
return Err(VmError::InvalidArgument("Block state is not an object"));
|
||||
@@ -88,21 +98,26 @@ impl ObjectPayload for Block {
|
||||
}
|
||||
}
|
||||
|
||||
/// 提供受检查的 Any 下转型入口,让宿主按具体 payload 类型读取数据。
|
||||
fn as_any(&self) -> &dyn std::any::Any {
|
||||
self
|
||||
}
|
||||
/// 返回运行时诊断/类型检查使用的稳定 payload 名称。
|
||||
fn kind_name(&self) -> &'static str {
|
||||
"tessera-block"
|
||||
}
|
||||
/// 声明此 payload 是否允许使用托管属性存储,具体字段仍由类型与调用检查约束。
|
||||
fn allows_attributes(&self) -> bool {
|
||||
true
|
||||
}
|
||||
/// 枚举本对象真正拥有的托管强引用,供 Aster 引用追踪和循环回收使用。
|
||||
fn trace(&self, visit: &mut dyn FnMut(ObjectRef)) {
|
||||
visit(self.state);
|
||||
if let Some(tasks) = self.tasks {
|
||||
visit(tasks);
|
||||
}
|
||||
}
|
||||
/// 向 VM 暴露共享赋值单元;替换的是指向关系,不是逐项复制组件业务字段。
|
||||
fn assignment_cell(
|
||||
&self,
|
||||
source: ObjectRef,
|
||||
@@ -122,6 +137,7 @@ impl ObjectPayload for Block {
|
||||
}
|
||||
|
||||
#[derive(Debug, Clone)]
|
||||
/// 组件当前业务描述与组成。与一次求出的屏幕几何分开保存,替换或属性变化会触发派生快照失效。
|
||||
pub struct Data {
|
||||
pub kind: Kind,
|
||||
pub children: Vec<Child>,
|
||||
@@ -155,6 +171,7 @@ pub struct Data {
|
||||
}
|
||||
|
||||
impl Data {
|
||||
/// 构造本类型并初始化其状态;资源建立和默认字段以函数体为准。
|
||||
pub fn new(kind: Kind, children: Vec<ObjectRef>, padding: f32, gap: f32) -> Self {
|
||||
let next_slot = children.len() as u64;
|
||||
Self {
|
||||
@@ -196,6 +213,7 @@ impl Data {
|
||||
properties: None,
|
||||
}
|
||||
}
|
||||
/// 检查原生组件种类是否承载子组成,供树修改和布局选择使用。
|
||||
pub fn is_container(&self) -> bool {
|
||||
matches!(
|
||||
self.kind,
|
||||
@@ -212,15 +230,19 @@ impl Data {
|
||||
}
|
||||
|
||||
impl ObjectPayload for Data {
|
||||
/// 声明此 payload 的赋值遵循引用身份语义,避免把内部宿主状态当作可复制值。
|
||||
fn reference_assignment_only(&self) -> bool {
|
||||
true
|
||||
}
|
||||
/// 提供受检查的 Any 下转型入口,让宿主按具体 payload 类型读取数据。
|
||||
fn as_any(&self) -> &dyn std::any::Any {
|
||||
self
|
||||
}
|
||||
/// 返回运行时诊断/类型检查使用的稳定 payload 名称。
|
||||
fn kind_name(&self) -> &'static str {
|
||||
"tessera-block-data"
|
||||
}
|
||||
/// 枚举本对象真正拥有的托管强引用,供 Aster 引用追踪和循环回收使用。
|
||||
fn trace(&self, visit: &mut dyn FnMut(ObjectRef)) {
|
||||
if let Some(scene) = self.scene3d {
|
||||
visit(scene);
|
||||
@@ -255,6 +277,7 @@ impl ObjectPayload for Data {
|
||||
}
|
||||
}
|
||||
|
||||
/// 分配 Data、共享 Cell 和 Block 包装,并让托管图拥有必要引用。
|
||||
pub fn allocate(cx: &mut NativeContext<'_>, mut data: Data) -> Result<ObjectRef, VmError> {
|
||||
let page = matches!(data.kind, Kind::Page);
|
||||
for child in &data.children {
|
||||
@@ -276,11 +299,13 @@ pub fn allocate(cx: &mut NativeContext<'_>, mut data: Data) -> Result<ObjectRef,
|
||||
|
||||
/// Borrowed final data; forwarding is part of the managed graph, never an Arc
|
||||
/// ownership graph hidden from the VM's cycle collector.
|
||||
/// 解析一个 Block 当前指向的 Data,返回底层身份和借用描述。
|
||||
pub fn resolve(store: &ObjectStore, block: ObjectRef) -> Result<(ObjectRef, &Data), VmError> {
|
||||
let (reference, data, _) = resolve_tracked(store, block)?;
|
||||
Ok((reference, data))
|
||||
}
|
||||
|
||||
/// 解析 Block 的完整引用路径,并返回快照失效所需的依赖身份。
|
||||
pub fn resolve_tracked(
|
||||
store: &ObjectStore,
|
||||
block: ObjectRef,
|
||||
@@ -311,11 +336,13 @@ pub fn resolve_tracked(
|
||||
|
||||
/// Validate the entire finite expansion before establishing a new composition
|
||||
/// edge. The node count is an explicit rejected resource quota, not truncated UI.
|
||||
/// 检查当前输入或发布值的不变量,调用方据校验结果决定是否继续。
|
||||
pub fn validate(
|
||||
store: &ObjectStore,
|
||||
root: ObjectRef,
|
||||
forbidden_state: Option<ObjectRef>,
|
||||
) -> Result<(), VmError> {
|
||||
// 显式进入/退出栈模拟深度优先遍历;退出时移除祖先链标记,允许共享子树。
|
||||
enum Step {
|
||||
Enter(ObjectRef),
|
||||
Exit(ObjectRef),
|
||||
@@ -361,13 +388,16 @@ pub fn validate(
|
||||
Ok(())
|
||||
}
|
||||
|
||||
/// 将当前托管或可变状态提取为后续阶段使用的派生表示。
|
||||
pub fn snapshot(store: &ObjectStore, root: ObjectRef) -> Result<Arc<UiNode>, VmError> {
|
||||
crate::snapshot::RenderCache::default().snapshot(store, root)
|
||||
}
|
||||
|
||||
/// Native visual parameters are ordinary managed attributes too. Composition,
|
||||
/// histories and connections remain structural payload edges.
|
||||
/// 列出本类型可投影到托管属性的原生字段及默认值。
|
||||
pub fn native_properties(data: &Data) -> Vec<(&'static str, Value)> {
|
||||
/// 在源 Value 与所需数值表示之间转换,并沿用本调用的有限值/范围检查。
|
||||
fn number(value: f32) -> Value {
|
||||
Value::Number((value as f64).into())
|
||||
}
|
||||
@@ -486,6 +516,7 @@ pub fn native_properties(data: &Data) -> Vec<(&'static str, Value)> {
|
||||
fields
|
||||
}
|
||||
|
||||
/// 复制原生描述并用当前托管属性覆盖它;结果只用于展示,不反向修改业务对象。
|
||||
pub fn visual_data(store: &ObjectStore, data: &Data) -> Result<Data, VmError> {
|
||||
let mut data = data.clone();
|
||||
let properties = data
|
||||
@@ -544,6 +575,7 @@ pub fn visual_data(store: &ObjectStore, data: &Data) -> Result<Data, VmError> {
|
||||
Ok(data)
|
||||
}
|
||||
|
||||
/// 按属性名检查和解码源值,再更新对应视觉字段;非法尺寸、枚举或颜色被拒绝。
|
||||
pub fn apply_visual_property(data: &mut Data, name: &str, value: &Value) -> Result<(), VmError> {
|
||||
let bad = || VmError::InvalidArgument("invalid native visual property");
|
||||
let number = || -> Result<f32, VmError> {
|
||||
@@ -799,6 +831,7 @@ pub fn apply_visual_property(data: &mut Data, name: &str, value: &Value) -> Resu
|
||||
Ok(())
|
||||
}
|
||||
|
||||
/// 统一返回非法页面缩放错误,确保属性写入与输入路径使用相同限制。
|
||||
fn invalid_zoom() -> VmError {
|
||||
VmError::InvalidArgument("Page.zoom expects a number from 0.1 to 4")
|
||||
}
|
||||
|
||||
Reference in New Issue
Block a user