复选框

用一张卡片呈现未选、部分选中和已选三种状态。

复选框适合独立的多选项,也可以用来显示一组子项的汇总状态。方形底板在三种状态间过渡颜色和透明度,勾号或减号从中心缩放出现,卡片和文字保持原位。

Rust
use aeris_ui::{
    device::{anim, checkbox::{self, Checkbox, State}, lv},
    geometry::Rect,
};
基础用法
use aeris_ui::{
    device::{anim, checkbox::{self, Checkbox, State}, lv},
    geometry::Rect,
};

let mut checkbox = unsafe {
    Checkbox::create(
        root,
        Rect::new(4, 108, 328, checkbox::HEIGHT),
        "Custom",
        "Use your own key",
        State::Mixed,
    )
};
if let Some(row) = &checkbox {
    lv::bind(row.root(), on_toggle, 0);
}

// 回调中推进状态,再逐帧调用 draw。
if let Some(row) = checkbox.as_mut() {
    row.animate_cycle(anim::now_ms());
}

状态只决定首帧。点击不会自动改变状态,调用方要在回调里选择 animate_cycle、animate_toggle 或 animate_to,再把同一时钟的毫秒值交给 draw。

组件结构

组成说明
卡片底面高度 100 px 的圆角底板,宽高由 area 决定。
标题25 px 中等字重,主文字色。
副标题25 px 常规字重,次文字色。
方形底板40 × 40 px,圆角 10 px,颜色随状态插值。
图标32 px 勾号或减号,从中心缩放。

方形底板和图标是同级对象,缩放只作用于图标,不会改变标签排版。

示例

三态列表

三种状态
use aeris_ui::{
    device::{anim, checkbox::{self, Checkbox, State}, lv},
    geometry::Rect,
};

const STEP: i32 = checkbox::HEIGHT + 8;
for (index, state) in [State::Unchecked, State::Mixed, State::Checked]
    .into_iter()
    .enumerate()
{
    let area = Rect::new(4, 8 + index as i32 * STEP, 328, checkbox::HEIGHT);
    let row = unsafe {
        Checkbox::create(root, area, "Custom", "Use your own key", state)
    };
    if let Some(row) = &row {
        lv::bind(row.root(), on_toggle, index);
    }
}

普通复选

两态切换
extern "C" fn on_toggle(event: lv::Obj) {
    let index = unsafe { lvx_event_get_user_data(event) };
    let now = anim::now_ms();
    app.rows[index].animate_toggle(now);
}

animate_toggle 在未选和已选之间切换,部分选中会变为已选。

三态循环

未选 → 部分 → 已选
app.row.animate_cycle(anim::now_ms());

适用于“全选”汇总项:未选表示全未选,部分选中表示有子项选中,已选表示全部选中。组件不会根据子项推导状态,汇总值要由应用算好再传入。

立即同步

不做动画
app.row.set_state(State::Checked);

批量恢复设置或首次渲染时可以直接落位。toggle() 也会立即切换,不播放过渡。

状态与动效

状态底板图标
未选主文字色,约 10% 不透明度无
部分选中强调色,约 50% 不透明度减号
已选强调色,完全不透明勾号

过渡时长 220 ms,使用三次缓出曲线。动画途中再次切换会从当前画面转向新目标,不会回到起点重播。

接口参考

Checkbox::create

pub unsafe fn create(
    parent: Obj,
    area: Rect,
    title: &str,
    subtitle: &str,
    state: State,
) -> Option<Self>
参数类型说明
parentObj卡片挂载的父对象。
areaRect位置与尺寸,高度至少 100 px。
title&str主标题。
subtitle&str副标题。
stateState初始状态。

宽度不足、父对象无效或素材创建失败时返回 None。

State

值说明
Unchecked未选。
Mixed部分选中。
Checked已选。

方法

方法返回值说明
root()Obj卡片根对象,用于绑定点击。
state()State当前状态。
set_state(state)—立即切换并停止动画。
toggle()State立即切换两态,部分选中变为已选。
animate_to(state, now)—从当前画面过渡到目标状态。
animate_toggle(now)State带动画地切换两态。
animate_cycle(now)State按未选、部分、已选的顺序循环并返回目标。
draw(now)bool推进动画,返回是否还需要下一帧。

尺寸

常量值说明
checkbox::HEIGHT100卡片高度。
方形底板40 × 40圆角 10 px。
图标32 × 32勾号或减号。

主题与样式

  • 未选底板使用 Color::PrimaryText,部分和已选使用 Color::Accent。
  • 标题使用主文字色,副标题使用次文字色。
  • 卡片底面是低透明度主文字色叠加在页面上,没有独立卡面素材。
  • 强调色可通过主题生成器调整。

交互与适配

  • 在 UI 线程创建;父对象负责销毁。
  • 整张卡片是点击热区,不需要额外扩大范围。
  • 行距由调用方控制,标准高度 100 px,常用间距 8 px。
  • 三态循环和两态切换是两个入口,调用前先确认业务语义。
  • 动画只在 draw 时推进,页面不可见时停止调用即可。

相关组件

  • 开关:简单的布尔设置。
  • 单选:互斥选项的圆形标记。
  • 单选列表:一组互斥选项的整组管理。

设备端入口:device::checkbox::Checkbox

大纲