步进器

用左右箭头在少量阶段或离散选项间切换。

步进器把“上一项 / 下一项”压缩成两个大按钮,中间显示当前阶段。它只发出方向事件,边界、文案和当前索引都由应用维护;因此可以做成不循环的向导,也可以做成首尾相接的档位。

Rust
use aeris_ui::device::{cards, lv};
use canopus_target_private::{lvx_event_get_user_data, lvx_label_set_text};
基础用法
use aeris_ui::device::{cards, lv};
use canopus_target_private::lvx_label_set_text;

let (_row, label) = unsafe { cards::stepper(root, 126, on_step) };
unsafe { lvx_label_set_text(label, b"Stage 1\0".as_ptr()) };

extern "C" fn on_step(event: lv::Obj) {
    let previous = unsafe { lvx_event_get_user_data(event) } == 0;
    app.stage = if previous {
        app.stage.saturating_sub(1)
    } else {
        (app.stage + 1).min(2)
    };
    let text = [b"Stage 1\0", b"Stage 2\0", b"Stage 3\0"][app.stage];
    unsafe { lvx_label_set_text(app.step_label, text.as_ptr()) };
}

on_step 的事件数据是 0(向前)或 1(向后),不是新的阶段值。组件不会在两端自动停住,越界处理要写在回调里。

组件结构

组成说明
行容器328 × 65 px,横向位置固定为 4 px。
左箭头65 × 65 px 点击区,图标居中。
右箭头65 × 65 px 点击区,图标居中。
中央标签198 px 宽,26 px 字号,位于两枚箭头之间。

两侧箭头带按压缩放反馈,中央标签不带交互。组件宽度固定,放进更窄的容器会超出边界。

示例

不循环的阶段向导

限制在首尾之间
extern "C" fn on_step(event: lv::Obj) {
    let previous = unsafe { lvx_event_get_user_data(event) } == 0;
    app.stage = if previous {
        app.stage.saturating_sub(1)
    } else {
        (app.stage + 1).min(STAGES - 1)
    };
    set_stage_label(app.stage);
}

箭头不会因为到达边界而变灰。需要禁用观感时,由应用调整图标透明度或忽略事件。

首尾循环

循环切换
extern "C" fn on_step(event: lv::Obj) {
    let previous = unsafe { lvx_event_get_user_data(event) } == 0;
    app.stage = if previous {
        (app.stage + STAGES - 1) % STAGES
    } else {
        (app.stage + 1) % STAGES
    };
    set_stage_label(app.stage);
}

更新标签

改文案
unsafe { lvx_label_set_text(label, b"Step 2 of 3\0".as_ptr()) };

标签是普通 LVGL 标签,可以随时改文本。文本过长会被裁切,建议控制在 198 px 以内。

接口参考

cards::stepper

pub unsafe fn stepper(
    parent: Obj,
    y: i32,
    on_step: LvxEventCallback,
) -> (Obj, Obj)
参数类型说明
parentObj步进器挂载的父对象。
yi32纵向位置,横向固定为 4 px。
on_stepLvxEventCallback方向回调,事件数据 0 向前、1 向后。

返回 (row, label):行容器用于布局或后续销毁,标签用于改文案。创建失败时两个句柄都为空。

尺寸

项目值说明
行宽328 px与卡片同宽。
行高65 px不含上下间距。
箭头点击区65 × 65 px左右各一个。
标签宽度198 px居中显示。

主题与样式

  • 标签使用固定灰色 0xDDDDDD,不读取主题的主文字色。
  • 箭头是独立位图,按压时整体缩放。
  • 行容器背景透明,页面底色直接透出。
  • 需要与主题一致时,用主题生成器确认素材和文字色的搭配。

交互与适配

  • 在 UI 线程创建;父对象负责销毁。
  • 组件只发方向事件,不持有阶段列表,也不自动更新标签。
  • 边界和循环方式由应用决定,组件不做夹取。
  • 点击区是 65 × 65 px,满足腕上点按,但两枚按钮之间只有标签,误触风险低。
  • 行宽固定 328 px,不要放进更窄的卡片容器。

相关组件

设备端入口:device::cards::stepper

大纲