数字滚轮

上下拖动一至三列数字滚轮,松手后吸附到选中值。

数字滚轮用于有界的数字输入,比如日期、时长或重复次数。每一列独立滚动、循环取值,松手后吸附到最近一格;当前列显示标签徽标和绿色描边,方便在窄屏上确认正在编辑的是哪一列。Column 描述一列的范围、初值、标签和徽标宽度,NumericWheel<N> 的 N 就是列数。

Rust
use aeris_ui::{
    device::numeric_wheel::{Column, NumericWheel},
    geometry::Rect,
};
滚轮数量

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

基础用法
use aeris_ui::{device::numeric_wheel::{Column, NumericWheel}, geometry::Rect};

let wheel = unsafe {
    NumericWheel::mount(
        root,
        Rect::new(0, 100, 336, 200),
        [
            Column { min: 1, max: 12, initial: 3, label: b"Month\0", badge_width: 84 },
            Column { min: 1, max: 31, initial: 15, label: b"Day\0", badge_width: 60 },
        ],
        0,
        on_wheel,
    )
};

extern "C" fn on_wheel(event: lv::Obj) {
    app.wheel.handle_event(event);
}

// 用户点按“完成”时读取并吸附到整格。
let [month, day] = app.wheel.finish();

把回调事件原样交给 handle_event,提交时调用 finish。

组件结构

组成说明
标签徽标36 px 高,显示在列顶部,只出现在当前列。
滚动视口158 px 高,上下各露出一部分相邻行,形成滚轮感。
数字轨道三行数字循环复用,每行高 74 px,字号 58 px。
渐隐素材视口上下边缘叠加遮罩,弱化远离中心的行。
边框4 px;当前列绿色,其余列为灰色。
触摸层独立于数字的透明滚动对象,接收按下、滚动和滚动结束事件。

整列高 200 px,标准列宽 92 px;空间不足时先压缩列间距,再压缩列宽,但每列不小于 72 px。

示例

单列

重复次数
let wheel = unsafe {
    NumericWheel::mount(
        root,
        Rect::new(0, 120, 336, 200),
        [Column { min: 1, max: 9, initial: 1, label: b"Times\0", badge_width: 96 }],
        0,
        on_wheel,
    )
};

三列

时、分、秒
let wheel = unsafe {
    NumericWheel::mount(
        root,
        Rect::new(0, 82, 336, 200),
        [
            Column { min: 0, max: 23, initial: 0, label: b"Hour\0", badge_width: 76 },
            Column { min: 0, max: 59, initial: 25, label: b"Min\0", badge_width: 76 },
            Column { min: 0, max: 59, initial: 0, label: b"Sec\0", badge_width: 76 },
        ],
        0,
        on_wheel,
    )
};

读取与写回

values 只读取当前值,set 会把各列滚到指定值并重新居中:

同步外部状态
let [hour, minute, second] = app.wheel.values();
app.wheel.set([hour, minute, 0]);

联动校验

多列彼此独立,组件不会替应用做日期合法性检查。月份变化后由应用决定日期上限,再调用 set 修正:

按月份修正日期
let [month, day] = app.wheel.values();
let last = days_in_month(month, app.year);
if day > last {
    app.wheel.set([month, last]);
}

当前列

mount 的 active 是零基列索引,决定初始哪一列显示徽标和绿色描边。之后点按其他列会更新当前列,但不会改变已经选中的值。

滚动与吸附

  • 每列在 min..=max 之间循环,滚过末尾会回到开头。
  • 拖动带惯性,松手后吸附到最近的 74 px 刻度。
  • 滚动位置远离中心时会重新居中,避免长时间滚动后数值漂移。
  • 一次只有一个列是当前列;切换列不会触发值变化回调。
  • 组件没有逐帧 draw,吸附动画由 LVGL 的滚动对象推进。

接口参考

NumericWheel::mount

pub unsafe fn mount(
    parent: Obj,
    bounds: Rect,
    specs: [Column; N],
    active: usize,
    callback: LvxEventCallback,
) -> Option<Self>
参数类型说明
parentObj有效的父对象。
boundsRect滚轮区域;高度至少 200 px,宽度须容纳每列至少 72 px。
specs[Column; N]1–3 列,每列的取值范围和标签。
activeusize初始当前列,必须小于 N。
callbackLvxEventCallback接收滚动对象的按下、滚动与滚动结束事件。

返回 Some 表示创建成功;active 越界、min > max、max > 99、标签没有 NUL 结尾,或空间不足时返回 None。

Column

字段类型说明
minu8最小值,包含。
maxu8最大值,包含,上限 99。
initialu8初始值;超出范围时会被夹到边界。
label&'static [u8]NUL 结尾的徽标文本。
badge_widthi32徽标宽度,创建时夹到 1..=列宽。

方法

方法返回值说明
handle_event(event)—转交回调事件;内部会忽略自身复位产生的事件。
values()[u8; N]读取当前值,不改变滚动位置。
set(values)—滚到指定值并重新居中,越界值夹到范围边界。
finish()[u8; N]读取当前值并吸附到整格,适合提交时调用。

常量与限制

项目值说明
列数1–3由泛型参数 N 决定。
组件高度200 px视口 158 px,行高 74 px。
标准列宽92 px最小 72 px,列间距最大 22 px。
数值范围0–99每列独立设置闭区间。

主题与样式

  • 当前列徽标使用固定绿色 0x4CE045,标签为黑色小字;非当前列隐藏徽标。
  • 当前列描边同为绿色,其他列为 0xBFBFBF。
  • 数字为白色,渐隐素材使用组件库的滚轮遮罩位图。
  • 滚轮不读取 Color::Accent,主题换色不会改变徽标和描边颜色。

交互与适配

  • 在 UI 线程创建;父对象负责销毁,实例使用期间父对象必须有效。
  • 回调必须把事件交给创建时的同一实例,handle_event 依靠滚动对象指针找到对应列。
  • 组件自身不校验业务规则,月份天数、时区或时长上限由应用处理。
  • 每列最多 100 个值;需要更大范围时改用分级滑块或分段输入。
  • 放在页面底部时,确保 200 px 高度和标签区域都不会被裁切。

相关组件

设备端入口:device::numeric_wheel::NumericWheel

大纲