滚动数字
逐位滚动地呈现时间变化,未变化的数字保持原位。
滚动数字把一串时间和它的上一次值比较,只让发生变化的位滚动,其余位静止。它适合计时器详情页和计时卡:秒在跳、分钟没变时,画面不会整块重排。
use aeris_ui::{
device::{anim, rolling_number::RollingNumber},
geometry::Rect,
};更改配置将自动应用并重载
use aeris_ui::{
device::{anim, rolling_number::RollingNumber},
geometry::Rect,
};
let area = Rect::new(8, 8, 320, 98);
if let Some(mut number) = unsafe { RollingNumber::new(root, area, b"2:30", 48) } {
number.set(b"2:29", anim::now_ms(), true);
}文本只接受 ASCII 数字和冒号,最多 8 个字符。new 会在首次排布时校验字号和宽度,放不下就返回 None,不会给出一个被裁切的数字。
组件结构
| 组成 | 说明 |
|---|---|
| 裁剪视口 | area 指定的矩形,超出部分被裁掉。 |
| 数字槽位 | 最多 8 个字形槽,从右往左对齐。 |
| 双层图像 | 每个槽位有前后两层,用于滚入和滚出。 |
| 等宽排版 | 数字使用等宽前进量,冒号单独占一个槽。 |
数字由字体图集渲染,不能单独设置颜色;颜色来自字形素材。
示例
不带动画更新
number.set(b"2:28", 0, false);animate 为 false 时会立即绘制并返回 Some(false),不需要再调用 draw。
调整字号
if !number.set_font_px(56) {
// 视口放不下新字号,保留原样。
}set_font_px 会用当前文本重新排布;字号越界或宽度不够时返回 false,画面不变。
详情页圆形排版
use aeris_ui::device::rolling_number::RollingNumber;
if let Some(mut number) = unsafe { RollingNumber::detail(root, b"12:00") } {
number.set(b"11:59", anim::now_ms(), true);
}detail 会在 58–72 px 之间选择能放进圆形视图的字号,位置也按详情页的圆心计算。
高频更新
计时器可能每秒更新一次。动画未结束时再次 set 会排队,当前动画结束后接着滚向最新值:
number.set(b"2:27", anim::now_ms(), true);同一时刻只保留最后一次待处理值,中间的更新不会堆积。
立即落位
number.finish();finish 会取消动画和待处理值,直接显示最新目标,适合暂停或页面关闭前调用。
状态与动效
| 状态 | 表现 |
|---|---|
| 静止 | 所有数字完整显示。 |
| 滚动中 | 变化的位纵向滚动并交叉淡入淡出,未变化的位不动。 |
| 动画时长 | 240 ms,三次缓出。 |
| 排队中 | 当前动画结束后继续处理最新值。 |
组件不读时钟;所有时间都来自 set 和 draw 传入的毫秒值。
接口参考
RollingNumber::new
pub unsafe fn new(
parent: Obj,
area: Rect,
text: &[u8],
font_px: i32,
) -> Option<Self>| 参数 | 类型 | 说明 |
|---|---|---|
area | Rect | 数字视口的位置和尺寸,高度不小于字号。 |
text | &[u8] | ASCII 数字和冒号,最多 8 个字符。 |
font_px | i32 | 16–72 px。 |
文本格式无效、字号越界、宽度不足或字体资源未就绪时返回 None。
RollingNumber::detail
pub unsafe fn detail(parent: Obj, text: &[u8]) -> Option<Self>按详情页的圆形空间自动匹配字号,位置固定在页面中央。
方法
| 方法 | 返回值 | 说明 |
|---|---|---|
set(text, now, animate) | Option<bool> | 更新文本;None 表示格式或尺寸无效。 |
set_font_px(px) | bool | 修改字号,成功时返回 true。 |
draw(now) | bool | 推进动画,返回是否还需要下一帧。 |
finish() | — | 立即完成动画并显示最新值。 |
delete() | — | 删除组件对象。 |
主题与样式
- 数字颜色由字体图集决定,组件没有
set_color。 - 视口背景透明,页面底色直接透出。
- 详情页排版使用圆形裁剪,卡片排版使用矩形裁剪。
- 需要换数字颜色时,需要替换字体素材,而不是在运行时染色。
交互与适配
- 在 UI 线程创建和更新;父对象负责销毁。
- 文本最多 8 个字符,只支持数字和冒号。
- 视口高度必须不小于字号,宽度必须容纳整串数字。
- 动画只在
draw时推进,页面不可见时停止调用即可。 - 高频更新时只保留最新待处理值,不需要手动节流。
相关组件
设备端入口:device::rolling_number::RollingNumber