页面容器

组织腕上页面的根对象、背景和安全区。

页面容器是每个腕上页面的起点。它按视口创建一块 336 × 480 的根对象,并由 Viewport 把屏幕边界和矩形安全区分开:子组件挂在根对象上,布局坐标相对根对象计算,而不是直接照抄屏幕坐标。

Rust
use aeris_ui::{device::page, geometry::Viewport};
基础用法
use aeris_ui::device::{cards, page};

let root = unsafe { page::screen(parent) };
if !root.is_null() {
    unsafe { cards::status_card(root, 98, "Page", "336 x 480") };
}

page::screen 使用 Viewport::BAND_10_PRO,适合当前 336 × 480 的设备。需要在其他分辨率或留出屏幕圆角时,改用 screen_in 并传入自定义视口。

组件结构

组成说明
根对象按视口边界创建的纯色背景,不接收点击和滚动。
内容区由 Viewport::content() 换算出的安全区,坐标相对根对象。
子组件标题栏、滚动容器、卡片等直接挂在根对象上,由父对象统一销毁。

页面本身不排布内容。纵向列表交给滚动容器,标题交给标题栏,页面切换交给分页器。

示例

自定义视口

Viewport::new 要求边界和安全区都大于 0,且安全区完全落在边界内。返回 None 时不要继续创建页面。

带安全区的视口
use aeris_ui::{device::page, geometry::{Rect, Viewport}};

let viewport = Viewport::new(
    Rect::new(0, 0, 336, 480),
    Rect::new(12, 88, 312, 344),
);
let root = viewport.map(|viewport| unsafe { page::screen_in(parent, viewport) });

在安全区内放滚动列表

content() 返回的矩形已经相对根对象,可以直接交给 scroll_in:

安全区内的列表
if let (Some(viewport), Some(root)) = (viewport, root) {
    unsafe { page::scroll_in(root, viewport.content()) };
}

简单返回页

只需要一个返回按钮和标题时,用 right_header,不必引入完整标题栏:

返回标题栏
unsafe { page::right_header(root, "Details\0", on_back) };

坐标与布局

项目值说明
页面宽度336 pxpage::WIDTH。
页面高度480 pxpage::HEIGHT。
内容起点82 pxpage::PAGE_TOP,标题栏下方第一条内容的常用位置。

Viewport::bounds 是屏幕范围,Viewport::content 是安全区相对根对象的偏移。两者不要混用:安全区在屏幕内缩进 12 px,换算到根对象后可能是不带偏移的另一个矩形。

接口参考

page::screen_in

pub unsafe fn screen_in(parent: Obj, viewport: Viewport) -> Obj
参数类型说明
parentObj有效的 LVGL 父对象。
viewportViewport屏幕边界与安全区。

返回页面根对象;父对象无效或创建失败时返回空指针。

相关入口

函数说明
screen(parent)使用 Viewport::BAND_10_PRO 创建页面。
scroll(parent)在默认视口内创建纵向滚动区域。
scroll_in(parent, bounds)在指定矩形内创建纵向滚动区域。
right_header(root, title, on_back)创建带返回按钮的简单标题栏。
button(parent, y, title, kind, action)在页面宽度内创建胶囊按钮。

常量

常量值说明
WIDTH336页面宽度。
HEIGHT480页面高度。
PAGE_TOP82标题栏下方的内容起点。
PAGE_BACKGROUND主题背景色未覆盖主题时的页面底色。

主题与样式

  • 根对象背景使用 Color::Background,默认是黑色,可通过主题生成器覆盖。
  • 页面本身不画圆角、描边或阴影,屏幕形状由设备外壳决定。
  • 子组件各自读取语义色,页面容器不会替它们统一着色。

交互与适配

  • 在 UI 线程创建;根对象由父对象销毁,销毁后不要再访问子组件。
  • 根对象不接收点击,点击由具体子组件绑定。
  • Viewport::new 会校验安全区,失败时不要强行布局。
  • 换设备分辨率时,先调整视口和安全区,再检查固定像素的组件是否仍放得下。
  • 页面内所有固定宽度组件按 336 px 设计,更宽的屏幕需要重新排布,而不是简单拉伸。

相关组件

  • 滚动容器:纵向内容超出屏幕时使用。
  • 标题栏:完整的主次标题和操作按钮。
  • 分页器:多个同宽页面横向切换。

设备端入口:device::page::screen_in

大纲