docs: clarify layout bounds and retained image text flow

This commit is contained in:
2026-11-12 20:41:16 +08:00
parent 0c4bd06231
commit 45b0b53d4f
6 changed files with 21 additions and 2 deletions
+4
View File
@@ -54,6 +54,7 @@ impl Mode {
/// 为旧页面模式生成有限轴和可延伸轴的根约束。
pub fn constraints(self, viewport: Option<Size>) -> [f32; 4] {
// LayoutRuntime::root_constraints 用于页面根测量;这里的可延伸轴仍有数值上限,不会向布局传 f32::INFINITY。
// 未收到原生视口尺寸时采用布局默认根约束;不能凭空建立固定宽高。
let Some(size) = viewport else {
return crate::layout::root_constraints(None);
@@ -118,6 +119,7 @@ impl Surface {
/// 把页面视图坐标反算为旧 Page 相机下的世界坐标。
// 输入在视图空间,先除缩放再加世界偏移;调用方需保证 zoom 有限且大于零。
pub fn to_world(&self, point: Point) -> Point {
// shell 先去除侧栏/设备比例等宿主偏移,再调用本逆变换;不在这里处理 Mount.view 或三维面板的第二层映射。
Point::new(
point.x / self.zoom + self.pan.x,
point.y / self.zoom + self.pan.y,
@@ -135,6 +137,7 @@ impl Surface {
/// 判断给定点是否位于目标范围;需要相机转换的类型会先转换再判断。
pub fn contains(&self, point: [f32; 2], viewport: Option<Size>) -> bool {
// UiBridge 在点击/滚动前用它排除页面外输入;point 必须已经是页面世界点,不能把原始设备像素传进来。
// 传入的数组是世界坐标。转换后使用左/上包含、右/下排除的视口边界;
// 未知视口时仍排除负坐标,但不限制右/下界。
// 传入世界坐标先投影到视图空间,再按视口半开边界检查,不能与 Rect.contains 的闭边界混淆。
@@ -146,6 +149,7 @@ impl Surface {
/// 只对有限页面按实际内容范围钳制偏移;自由画布不按内容边缘停止导航。
pub fn clamp(&mut self, viewport: Size) {
// UiBridge 布局完成后和 page_input 导航后调用;只修改这个 Surface 数值副本,写回 Page 属性或发布 Frame 由调用方完成。
// Window 重置所有导航;单轴模式清除另一轴并恢复单位缩放。
// 内容小于视口时 max(0) 令可滚动范围归零,避免 clamp 出现反向上下限。
match self.mode {