单选列表

在一组卡片中选中一项,选中标记由列表统一同步。

单选列表把若干张单选卡片排成一列,适合振动强度、提醒方式、默认账户这类互斥选项。列表只负责创建卡片和传递索引,当前选中项仍由应用决定;调用 select 后,所有卡片的圆形标记会一起更新。ChoiceList<N> 的 N 是最多生成的选项数,创建时由泛型决定,不会在运行时扩容。

Rust
use aeris_ui::device::choice_list::ChoiceList;
基础用法
use aeris_ui::device::choice_list::ChoiceList;
use canopus_target_private::lvx_event_get_user_data;

let mut choices = unsafe {
    ChoiceList::<3>::new(
        root,
        14,
        102,
        [
            ("Soft", "One pulse"),
            ("Standard", "Two pulses"),
            ("Strong", "Three pulses"),
        ],
        Some(0),
        on_select,
    )
};

extern "C" fn on_select(event: lv::Obj) {
    let index = unsafe { lvx_event_get_user_data(event) };
    app.vibration = index;
    app.choices.select(index);
}

点击回调收到零基索引,应用更新自己的状态后再调用 select。

组件结构

组成说明
选项卡片每项一张 328 × 98 px 卡片,横向位置固定为 4 px。
文字列主标题与副标题,和单张单选一致。
圆形标记右侧 40 px 圆面;选中时变成蓝色,中心出现白色圆点。
点击热区整张卡片可点,事件数据为该行的零基索引。
行距由 step 决定,标准卡片高度下常用 102–112 px。

列表不创建外层容器,卡片直接挂在传入的父对象上。行与行之间不会自动留白,间距全部来自 step。

示例

没有默认选项

selected 传入 None 时所有行都未选中,适合必须让用户主动选择的场景:

无默认选中
let mut choices = unsafe {
    ChoiceList::<2>::new(
        root, 14, 102,
        [("Remind me", "One alert"), ("Stay quiet", "No alert")],
        None,
        on_select,
    )
};

切换选中项

选中第二项
choices.select(1);

select 会遍历所有已创建的卡片,把索引匹配的行设为选中,其余设为未选。索引超出范围时不会报错,结果是全部未选中。

用动画切换

select 直接切换画面,不播放过渡。需要动画时,通过 iter_mut 逐个驱动单选卡片:

带动画
use aeris_ui::device::anim;

for (index, choice) in app.choices.iter_mut() {
    choice.animate_to(index == app.vibration);
}

// 页面刷新时推进;任一行仍在移动就继续请求下一帧。
let mut moving = false;
for (_, choice) in app.choices.iter_mut() {
    moving |= choice.draw(anim::now_ms());
}
if moving {
    wake_next_frame();
}

iter_mut 只返回创建成功的行,失败的卡片会被跳过,索引仍然是原始位置。

放进滚动容器

选项较多时,把列表挂到滚动区域里,而不是继续向下排:

滚动列表
let list = unsafe { page::scroll_in(root, Rect::new(0, 0, page::WIDTH, 312)) };
let mut choices = unsafe {
    ChoiceList::<6>::new(list, 8, 102, options, Some(0), on_select)
};

卡片坐标相对滚动区域,滚动和渐隐仍由滚动容器负责。

状态与交互

状态表现
未选中空心圆环,按下时卡片缩放反馈。
选中圆环内出现蓝色圆点。
列表同步select 一次性更新所有行;None 表示全部未选。
列表动画默认没有;需要时用 iter_mut 调用 animate_to 和 draw。

列表不做互斥推导,也不会在点击时自动取消上一项。点击只把索引交给应用,选中状态必须由应用写回。

接口参考

ChoiceList::new

pub unsafe fn new<'a>(
    parent: Obj,
    top: i32,
    step: i32,
    options: impl IntoIterator<Item = (&'a str, &'a str)>,
    selected: Option<usize>,
    on_select: LvxEventCallback,
) -> Self
参数类型说明
parentObj卡片挂载的父对象。
topi32第一行的纵向位置。
stepi32行距;应不小于卡片高度 98 px。
options(&str, &str) 迭代器每项的标题和副标题;超过 N 的部分被忽略。
selectedOption<usize>初始选中索引;None 表示全不选。
on_selectLvxEventCallback点击回调,事件数据为行索引。

返回列表实例。某一行创建失败时该行保持为空,后续 select 和 iter_mut 会跳过它。

方法

方法返回值说明
select(index)—立即同步所有行,索引相等者为选中。
iter_mut()impl Iterator<Item = (usize, &mut Choice)>逐个访问已创建的行,用于读取或播放动画。
EMPTYSelf所有行都为空的常量,可作为静态初始值。

相关常量

常量值说明
cards::WIDTH328每张卡片的宽度。
card::TRANSITION_MS220单选卡片动画时长。

主题与样式

  • 卡片底面和文字沿用卡片的默认样式,标题使用主文字色,副标题使用次文字色。
  • 选中圆点使用组件内置的蓝色 0x3488FF,不随 Color::Accent 改变。
  • 未选中圆环是白色低透明度描边,深色底上仍有足够对比。
  • 需要整体换色时,先确认素材和语义色的处理方式,见主题生成器。

交互与适配

  • 在 UI 线程创建;父对象销毁时卡片一并删除,列表实例随后失效。
  • 整张卡片是点击热区,行高 98 px,不需要额外扩大触控范围。
  • N 决定最多生成多少行,运行中不能增加;超出部分直接丢弃。
  • select 不做边界检查,越界索引会让所有行变为未选。
  • 行距由调用方负责,过小会重叠,过大则一屏放不下。
  • 列表只处理 UI 状态,持久化和业务校验留给应用。

相关组件

  • 单选:单张卡片上的圆形标记。
  • 复选框:需要多选或部分选中时使用。
  • 步进器:用左右箭头在少量阶段间切换。
  • 滚动容器:选项数量超过一屏时承载列表。

设备端入口:device::choice_list::ChoiceList

大纲