确认浮层

在模糊背景上呈现操作结果,支持三种底板、自定义图标和可展开的二级正文。

确认浮层用于一件事完成之后的即时反馈,例如“记录已保存”“计时已重置”。它在页面前景显示圆底图标和一句标题,可以再展开一段正文。浮层不承载表单,也不替应用执行操作,只负责把结果说清楚。

Rust
use aeris_ui::device::confirmation_overlay::{self, FirstStageTap, Icon, Options, Style};
带正文时点按一级

更改配置将自动应用并重载

基础用法
use aeris_ui::device::confirmation_overlay::{self, Style};

unsafe {
    confirmation_overlay::show(root, Style::Neutral, None, c"Record saved");
}

最简调用只用到 show、Style 和一条 NUL 结尾的标题。root 必须是有效的 336 × 480 页面根对象,浮层会覆盖整个页面并截取背景快照。传入 None 时使用内置对号,标题最多显示两行,超出部分省略。

组件结构

组成说明
背景层页面快照加模糊,与弹窗共用同一套遮罩。
底板圆盘一级样式为 182 px 圆盘,二级样式缩到 72 px 并上移。
图标默认 102 px;自定义位图按原始宽高比缩放,中心与圆盘对齐。
标题25 px,宽度 292 px,位于屏幕下方约 405 px 处。
正文仅二级布局出现,25 px 次文字色,从屏幕底部之外滑入。
时钟右上角显示设备时间,位置与标题栏一致。

浮层的点击区域是整块表面:一级点按可关闭或进入二级,二级点按直接关闭。

示例

三种底板

Style 决定圆盘的颜色和不透明度,图标与标题保持独立:

样式圆盘
Neutral主文字色,10% 不透明度,适合中性结果。
PrimarySoft强调色,25% 不透明度,适合成功但不需要抢眼的结果。
Primary强调色实底,适合需要明确强调的结果。
Primary 底板
unsafe {
    confirmation_overlay::show(root, Style::Primary, None, c"Timer reset");
}

带正文的二级布局

提供 description 后,浮层先显示一级样式,停留一段时间,再过渡到二级布局。标题会连续上移,不会重新入场。

二级样式
use aeris_ui::device::confirmation_overlay::{self, Options, Style};

unsafe {
    confirmation_overlay::show_with_options(
        root,
        Style::PrimarySoft,
        None,
        c"Record saved",
        Options {
            description: Some(c"You can find this record in your history."),
            ..Options::default()
        },
    );
}

自定义图标

Icon 接收项目内的 LVGL 位图路径和原始像素尺寸。设备端相对路径从当前模块的数据目录解析,保持宽高比,不会拉伸。

自定义图标
use aeris_ui::device::confirmation_overlay::{self, Icon, Style};

let icon = Icon { path: c"my-check.bin", width: 80, height: 80 };
unsafe {
    confirmation_overlay::show(root, Style::Primary, Some(icon), c"Synced");
}

宽或高为 0 时调用直接返回 false,不会创建浮层。

停留时间与一级点按

Options 把两段停留和一级点按行为放在一起:

完整选项
use aeris_ui::device::confirmation_overlay::{self, FirstStageTap, Options, Style};

unsafe {
    confirmation_overlay::show_with_options(
        root,
        Style::Neutral,
        None,
        c"Backup complete",
        Options {
            description: Some(c"12 files were updated."),
            first_stage_ms: 800,
            first_stage_tap: FirstStageTap::ShowDetails,
            timeout_ms: Some(6000),
        },
    );
}
  • first_stage_ms 只在一级入场完成后计时;点按一级会提前结束这段停留。
  • FirstStageTap::ShowDetails 让一级点按进入二级,Dismiss 让一级点按直接关闭。没有正文时这个选项不起作用。
  • timeout_ms: None 关闭最后一段的自动隐藏,浮层只能由点按或 dismiss 关闭。
  • timeout_ms: Some(0) 会在进入最后一段后立刻开始退场。

动效与阶段

阶段时长说明
背景淡入220 ms快照遮罩缓出。
内容入场延迟 24 ms,持续 240 ms圆盘和标题淡入并轻微上移。
图标入场延迟 96 ms,持续 168 ms图标从 25% 缩放到 100%,同时淡入。
一级停留默认 550 ms仅在带正文时进入下一阶段。
二级展开320 ms圆盘缩小上移,标题上移,正文从底部滑入。
退场内容 180 ms,背景再延迟 24 ms、持续 196 ms从当前进度反向淡出。

动画由对话框统一推进,浮层自身不读取时钟。过渡途中重复点按会从当前画面继续,不会跳回起点。

接口参考

show

pub unsafe fn show(root: Obj, style: Style, icon: Option<Icon<'_>>, message: &CStr) -> bool
参数类型说明
rootObj336 × 480 页面根对象,用于挂载浮层和获取背景快照。
styleStyleNeutral、PrimarySoft 或 Primary。
iconOption<Icon>None 使用内置对号。
message&CStr标题,NUL 结尾的 UTF-8 文本。

返回 true 表示浮层已开始入场;已有活动弹层、根对象无效或图标尺寸为 0 时返回 false。

show_with_options

pub unsafe fn show_with_options(
    root: Obj,
    style: Style,
    icon: Option<Icon<'_>>,
    message: &CStr,
    options: Options<'_>,
) -> bool

参数与 show 相同,额外接收 Options。Options 实现 Default,可以只覆盖关心的字段。

Options

字段类型默认值说明
descriptionOption<&CStr>None提供正文后启用二级布局。
first_stage_msu32550一级入场结束到二级过渡开始的停留毫秒数。
first_stage_tapFirstStageTapDismiss一级点按是查看详情还是关闭。
timeout_msOption<u32>Some(4000)最后一段的停留毫秒数;None 关闭自动隐藏。

Icon

字段类型说明
path&CStr项目内位图路径或 NUL 结尾的绝对路径。
widthu16原始像素宽。
heightu16原始像素高。

关闭与清理

函数返回值说明
dismiss(root)bool播放退场动画;当前浮层不属于该根对象时返回 false。
hide(root)—立即移除,不播放动画,适合页面暂停或销毁前清理。

常量

常量值说明
DEFAULT_FIRST_STAGE_MS550一级默认停留。
DEFAULT_TIMEOUT_MS4000最后一段默认停留。

主题与样式

  • 圆盘颜色来自 Color::Accent,Neutral 改用 Color::PrimaryText。
  • 标题使用 Color::PrimaryText,正文使用 Color::SecondaryText。
  • 背景模糊与弹窗共用,不能在浮层上单独调整模糊强度。
  • 想统一换色,用主题生成器更新语义色,而不是在调用处传色值。

交互与适配

  • 在 UI 线程调用。同一时间只允许一个浮层,dialog::busy() 为真时新的调用会失败。
  • 页面根对象销毁前调用 hide(root),避免动画定时器继续访问已删除的对象。
  • 浮层没有确认按钮。它表达结果,不请求决策;需要用户确认时用弹窗。
  • 标题适合一到两行短句,正文适合补充位置、数量或下一步;更长的内容请放到详情页。
  • 点按一级是否进入二级要在调用时就决定,运行中不能切换。

相关组件

  • 弹窗:需要在操作前请求确认时使用。
  • 状态卡:在页面内保留一条状态摘要。
  • 进度环:需要展示过程而不是结果时使用。

设备端入口:device::confirmation_overlay::{show, show_with_options, dismiss, hide}

大纲