docs: clarify graphics resource and Block validation call paths

This commit is contained in:
2026-11-12 20:24:05 +08:00
parent 1f26349436
commit b44d7833ea
2 changed files with 16 additions and 2 deletions
+10 -2
View File
@@ -427,6 +427,9 @@ 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.
/// 完整展开 Block/Cell/孩子图,拒绝环、禁止目标回边及超过 10000 次展开的组成。
/// allocate/Scene3D 面板构造传 None,只检查已有图;共享赋值传目标 Cell,
/// Children 的 append/insert/replace 和 Page 的 render/navigate 则传目标 Data。
/// 因此 forbidden_state 虽沿用 state 名称,实际可以是 Cell 或 Data 身份;二者都不能在新子图中出现。
pub fn validate(
store: &ObjectStore,
root: ObjectRef,
@@ -472,7 +475,8 @@ pub fn validate(
let Value::Object(value) = store.cell_get(state)? else {
return Err(VmError::InvalidArgument("invalid Block state"));
};
// Cell 当前值若直接指向将被修改的禁用目标,同样形成回边,不能只比较当前 Cell。
// Children/Page 编辑传入的是 Data 身份,要在此比较 Cell 的值;共享赋值传入的 Cell 已在上方比较。
// 例如给容器追加它自己的别名时,包装身份可能不同,最终 Data 相同仍须拒绝。
if forbidden_state == Some(value) {
return Err(VmError::InvalidArgument(
"Block composition would create a cycle",
@@ -502,6 +506,8 @@ pub fn snapshot(store: &ObjectStore, root: ObjectRef) -> Result<Arc<UiNode>, VmE
/// Native visual parameters are ordinary managed attributes too. Composition,
/// histories and connections remain structural payload edges.
/// 列出本类型可投影到托管属性的原生字段及默认值。
/// allocate 用返回值初始化 properties;visual_data 用字段名重读当前值;RenderCache 用同一集合登记精确失效依赖。
/// 新增原生视觉字段时需同时补这里与 apply_visual_property,否则可能出现可解码但不进入快照/缓存观察的字段。
pub fn native_properties(data: &Data) -> Vec<(&'static str, Value)> {
/// 把已有 f32 默认字段编码为源 Number;这里不做范围校验,读取解码由 apply_visual_property 处理。
fn number(value: f32) -> Value {
@@ -643,7 +649,7 @@ pub fn visual_data(store: &ObjectStore, data: &Data) -> Result<Data, VmError> {
let properties = data
.properties
.ok_or(VmError::InvalidArgument("missing Block properties"))?;
// 字段集合由原生种类确定,每项从当前存储读取,保留业务属性依赖以驱动后续失效。
// 字段集合由原生种类确定,每项从当前存储读取;RenderCache 调用方另用同一字段集合登记精确缓存依赖。
for (name, _) in native_properties(&data) {
// 借用读取的源值先解码到副本,错误不会反写已存在的业务描述。
let value = store.get_attr(properties, name)?;
@@ -707,6 +713,8 @@ pub fn visual_data(store: &ObjectStore, data: &Data) -> Result<Data, VmError> {
}
/// 按属性名检查和解码源值,再更新对应视觉字段;非法尺寸、枚举或颜色被拒绝。
/// binding::refresh 在写入托管属性前用副本试解码;visual_data 在全量覆盖后另查 min/max 和视口协议。
/// 本函数只验证本次值并更新传入 Data,不自行写 properties,也不保证多个相关字段组合起来一定合法。
pub fn apply_visual_property(data: &mut Data, name: &str, value: &Value) -> Result<(), VmError> {
// 绑定刷新在写回前、visual_data 在读取时调用本解码器;通用类型/范围失败统一为视觉属性错误。
let bad = || VmError::InvalidArgument("invalid native visual property");