docs: explain native visual protocols and legacy page coordinate rules

This commit is contained in:
2026-11-12 18:36:10 +08:00
parent 13a8b1b4b5
commit df7e1846b2
3 changed files with 108 additions and 0 deletions
+19
View File
@@ -1,6 +1,10 @@
//! 旧 Page.mode 的兼容空间策略,以及页面级的正逆相机变换。
//! 新组合应优先使用普通布局、ScrollView 和独立场景视口;保留这里是为了兼容已有 window/vertical/horizontal/canvas 页面。
//!
//! 调用路径:Block.mode 属性解码用 Mode.parse;根布局按 Mode.constraints 选择有限/可延伸轴。
//! scene/输入导航使用 Surface 的正逆变换和可见性判断,内容变化后用 clamp 收敛兼容页面偏移。
//! 本模块不创建窗口、不修改 VM;Page 表面导航与独立 CanvasViewport/ScrollBlock 是不同状态。
//!
//! 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};
@@ -25,6 +29,7 @@ pub enum Mode {
impl Mode {
/// 返回内部枚举或对象对应的稳定源名称。
pub fn name(self) -> &'static str {
// 源字段编码与序列化采用同一组小写策略名,布局方向不由显示标题推断。
match self {
Self::Window => "window",
Self::Vertical => "vertical",
@@ -35,6 +40,7 @@ impl Mode {
/// 把外部源码或属性表示转换为内部枚举/结构,并反馈不支持的输入。
pub fn parse(name: &str) -> Result<Self, VmError> {
// 仅接受四个兼容模式,未知值明确拒绝,不能默认为 window。
match name {
"window" => Ok(Self::Window),
"vertical" => Ok(Self::Vertical),
@@ -52,6 +58,7 @@ impl Mode {
let Some(size) = viewport else {
return crate::layout::root_constraints(None);
};
// MAX_DIMENSION 在根约束中充当可延伸轴上限,不把它当作真实窗口尺寸。
let limit = crate::ui_bridge::MAX_DIMENSION as f32;
// 数组采用 [最小宽, 最小高, 最大宽, 最大高];竖/横页面仍至少占满当前视口。
match self {
@@ -66,12 +73,14 @@ impl Mode {
#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
/// 页面级兼容相机状态和有限内容范围,支持绘制与命中正逆变换。
pub struct Surface {
// 兼容 Page 空间策略,决定根约束及偏移夹取规则。
pub mode: Mode,
// 发布给原生侧的页面身份文本,不是托管强引用。
pub page: String,
// 视图左上角对应的世界坐标;绘制时先减 pan 再乘 zoom。
pub pan: Point,
#[serde(default = "unit")]
// 世界到视图的均匀比例,反变换要求非零有限;模型/文档入口负责合法范围。
pub zoom: f32,
// 布局产出的内容宽高,用于有限模式钳制;不决定 Canvas 的导航边界。
pub extent: Size,
@@ -85,6 +94,7 @@ fn unit() -> f32 {
impl Default for Surface {
/// 建立类型约定的初始值,供尚未发布或尚未交互的状态使用。
fn default() -> Self {
// 初始 Window 表面无页面身份、零偏移且单位缩放,可作为合法空发布值。
Self {
mode: Mode::Window,
page: String::new(),
@@ -127,6 +137,7 @@ impl Surface {
pub fn contains(&self, point: [f32; 2], viewport: Option<Size>) -> bool {
// 传入的数组是世界坐标。转换后使用左/上包含、右/下排除的视口边界;
// 未知视口时仍排除负坐标,但不限制右/下界。
// 传入世界坐标先投影到视图空间,再按视口半开边界检查,不能与 Rect.contains 的闭边界混淆。
let point = self.to_view(Point::new(point[0], point[1]));
point.x >= 0.0
&& point.y >= 0.0
@@ -138,10 +149,12 @@ impl Surface {
// Window 重置所有导航;单轴模式清除另一轴并恢复单位缩放。
// 内容小于视口时 max(0) 令可滚动范围归零,避免 clamp 出现反向上下限。
match self.mode {
// 普通窗口页面关闭导航能力,每次夹取恢复零 pan 与 zoom=1。
Mode::Window => {
self.pan = Point::default();
self.zoom = 1.0;
}
// 纵向模式仅允许 y 在内容高−视口高内移动,清横向偏移并禁用缩放。
Mode::Vertical => {
self.zoom = 1.0;
self.pan.x = 0.0;
@@ -150,6 +163,7 @@ impl Surface {
.y
.clamp(0.0, (self.extent.height - viewport.height).max(0.0));
}
// 横向模式同理仅允许 x 移动,内容缩短后最大偏移随之减少。
Mode::Horizontal => {
self.zoom = 1.0;
self.pan.y = 0.0;
@@ -158,6 +172,7 @@ impl Surface {
.x
.clamp(0.0, (self.extent.width - viewport.width).max(0.0));
}
// 自由画布不按内容边缘夹取,保留可查看负世界坐标与空白区域的导航。
Mode::Canvas => {}
}
}
@@ -174,9 +189,12 @@ mod tests {
let mut view = Surface::new(Mode::Canvas);
view.pan = Point::new(-240.0, 120.0);
view.zoom = 0.75;
// 固定视图指针位置作为缩放锚点,计算缩放前它对应的世界点。
let pointer = Point::new(300.0, 180.0);
// 保存锚点世界位置,改变 zoom 后反求 pan,保证 to_view(world) 仍等于 pointer。
let world = view.to_world(pointer);
assert_eq!(view.to_view(world), pointer);
// 模拟指针锚定缩放而不是绕世界原点缩放,随后检查可见与不可见点。
view.zoom = 2.0;
view.pan = Point::new(
world.x - pointer.x / view.zoom,
@@ -214,6 +232,7 @@ mod tests {
height: 600.0,
});
assert_eq!(view.pan, Point::new(0.0, 200.0));
// 内容缩到视口之内后重新夹取,旧 y=200 必须回零,不能继续显示内容外空白。
view.extent.height = 100.0;
view.clamp(Size {
width: 400.0,