进度环

用预渲染圆弧呈现 0–256 的环形进度。

进度环由四段圆弧和圆头端点拼成,适合放在计时按钮或详情页中央。它只负责画当前进度,不推动时间,也不播放过渡;计时状态变化时由应用调用 set。

Rust
use aeris_ui::{device::progress_ring::Ring, progress_ring::STEPS};

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

基础用法
use aeris_ui::{
    device::{assets, lv, progress_ring::Ring},
    progress_ring::STEPS,
};

unsafe { lv::image_child(root, assets::TIMER_DETAIL_TRACK, 6, 8) };
if let Some(mut ring) = unsafe { Ring::detail(root, 6, 8) } {
    ring.set_color(0x5EE7FE);
    ring.set(STEPS / 4);
}

STEPS 为 256,进度是整数。set 会夹到上限,大于 256 的值显示为满环;小于 0 的 u32 不存在,所以只需处理上限。

组件结构

组成说明
四段弧身按象限裁切的圆弧位图。
起点圆头进度从 0 开始时显示的圆头。
终点圆头跟随当前进度的圆头,从图集中选帧。
底轨独立素材,需要另行放置,组件不自动绘制。

Ring::detail 的外框为 324 × 324 px,Ring::card 为 70 × 70 px。两者使用不同的素材组和帧表,不能互换位置。

示例

详情页大环

带底轨
use aeris_ui::{
    device::{assets, lv, progress_ring::Ring},
    progress_ring::STEPS,
};

unsafe { lv::image_child(root, assets::TIMER_DETAIL_TRACK, 6, 8) };
if let Some(mut ring) = unsafe { Ring::detail(root, 6, 8) } {
    ring.set(STEPS / 2);
}

底轨和环的位置保持一致,通常都是 (6, 8)。底轨是独立图片,不随环的进度变化。

按钮上的小环

70 px 环
use aeris_ui::{device::{assets, progress_ring::Ring}, progress_ring::STEPS};

let button = unsafe { lv::image(root, assets::CARD_TIMER_START, 244, 14) };
if !button.is_null() {
    if let Some(mut ring) = unsafe { Ring::card(button) } {
        ring.set(STEPS * 3 / 4);
    }
}

Ring::card 直接以父对象左上角为原点创建 70 × 70 px 的环,适合计时卡的圆形按钮。

更新颜色

按主题或状态换色
ring.set_color(0x5EE7FE);

set_color 同时给弧身、起点圆头和终点圆头染色,保留素材的透明度。

归零与满环

重置
ring.set(0);
ring.set(STEPS);

进度为 0 时只显示底轨;满环时四个象限全部显示。

接口参考

构造

方法返回值说明
Ring::card(parent)Option<Ring>在父对象原点创建 70 × 70 px 小环。
Ring::detail(parent, x, y)Option<Ring>在指定位置创建 324 × 324 px 大环。

方法

方法返回值说明
set(steps)—设置 0–256 的进度,超出上限按满环处理。
set_color(color)—用 0xRRGGBB 给弧身和圆头染色。

常量

常量值说明
STEPS256进度总数。
小环尺寸70 × 70 pxRing::card。
大环尺寸324 × 324 pxRing::detail。

主题与样式

  • 环默认使用素材原色,调用 set_color 后覆盖为指定色值。
  • 组件不读取 Color::Accent,主题换色不会自动改变进度颜色。
  • 底轨是独立素材,颜色和透明度由素材决定。
  • 需要跟随主题时,在创建后调用 set_color(Color::Accent.resolve())。

交互与适配

  • 在 UI 线程创建和更新;父对象负责销毁。
  • 没有回调和动画,进度变化立即重绘。
  • 大环和小环的素材组不同,选错会明显偏大或偏小。
  • set 不会调用 draw,没有逐帧成本。
  • 底轨要单独放置,组件不会替你补一层轨道。

相关组件

设备端入口:device::progress_ring::Ring

大纲