洛汐文档库

外观

LVGL 样式、事件与动画

约 792 字大约 3 分钟

2026-07-15

Style

创建样式：

local style = lvgl.Style {
  bg_color = 0x101010,
  bg_opa = lvgl.OPA(255),
  radius = 20,
  border_width = 0,
  text_color = 0xffffff,
}

object:add_style(style, lvgl.PART.MAIN)

样式对象支持批量 set：

style:set {
  pad_all = 8,
  shadow_width = 12,
  shadow_opa = 80,
}

对象侧的样式方法：

object:add_style(style, part)
object:remove_style(style, part)
object:remove_style_all()
object:set_style(properties [, selector])

selector 由 part 与 state 组合。优先使用固件导出的 lvgl.PART、lvgl.STATE，不要复制桌面版 LVGL 的整数枚举。

常用样式属性

分类属性
尺寸width、height、min_width、max_width、min_height、max_height
背景bg_color、bg_opa、bg_img_src、bg_img_opa、bg_img_recolor、bg_img_tiled
边框border_color、border_width、border_opa、border_side、border_post
外轮廓outline_color、outline_width、outline_opa、outline_pad
阴影shadow_color、shadow_width、shadow_opa、shadow_ofs_x、shadow_ofs_y、shadow_spread
内边距pad_top、pad_bottom、pad_left、pad_right、pad_row、pad_column、pad_all、pad_gap
文本text_color、text_opa、text_font、text_letter_space、text_line_space、text_decor、text_align
图片img_opa、img_recolor、img_recolor_opa
变换transform_zoom、transform_angle、transform_pivot_x、transform_pivot_y、translate_x、translate_y
其他radius、opa、clip_corner、blend_mode、anim_time、anim_speed、transition

状态与标志

object:add_state(lvgl.STATE.CHECKED)
object:clear_state(lvgl.STATE.CHECKED)
local state = object:get_state()

object:add_flag(lvgl.FLAG.CLICKABLE)
object:clear_flag(lvgl.FLAG.SCROLLABLE)

常用 state：CHECKED、FOCUSED、FOCUS_KEY、EDITED、HOVERED、PRESSED、SCROLLED、DISABLED。

常用 flag：HIDDEN、CLICKABLE、CLICK_FOCUSABLE、CHECKABLE、SCROLLABLE、SCROLL_ELASTIC、SCROLL_MOMENTUM、SCROLL_ONE、SCROLL_CHAIN、EVENT_BUBBLE、GESTURE_BUBBLE、IGNORE_LAYOUT、FLOATING、OVERFLOW_VISIBLE。

事件

便捷回调：

object:onPressed(function(target, code)
  print("pressed", target, code)
end)

object:onClicked(function(target, code)
  print("clicked", target, code)
end)

指定事件：

object:onevent(lvgl.EVENT.VALUE_CHANGED, function(target, code)
  print("value changed")
end)

回调执行时对象可能在回调中被删除。删除后不要继续调用 target，也不要在闭包中长期保存已退出页面的 userdata。

控件动画 object:anim

预装脚本使用以下形式：

image:anim {
  property = "x",
  from = -100,
  to = 100,
  duration = 800,
  repeat_count = -1,
  path = "linear",
}

常见字段：

字段类型说明
propertystring要变化的属性，如 x、y、opa、angle、zoom
from / tonumber起始值与结束值
durationinteger单程时长，毫秒
delayinteger开始延迟，毫秒
repeat_countinteger重复次数；-1 表示无限
repeat_delayinteger每轮重复前延迟
playback_durationinteger回放时长
playback_delayinteger回放前延迟
pathstring/function插值路径
ready_cbfunction动画结束回调

停止对象上的动画：

object:remove_all_anim()

Anim 对象

lvgl.Anim(object, options) -> animation
object:Anim(options) -> animation
字段类型说明
start_valueinteger起始值
end_valueinteger结束值
time / durationinteger动画时长，毫秒
delayinteger启动延迟，毫秒
repeat_countinteger重复次数；-1 为无限
repeat_delayinteger重复间延迟
early_applyboolean/integer是否立即应用首帧
playback_timeinteger反向回放时长
playback_delayinteger回放前延迟
pathstringlinear、ease_in、ease_out、ease_in_out、overshoot、bounce 或 step
exec_cbfunctionfunction(object, value)，应用当前值
done_cbfunctionfunction(animation, object)，完成回调
runboolean创建后立即启动

实例方法：

方法说明
animation:set(options)更新参数
animation:start()启动
animation:stop()停止
animation:delete()删除
local animation = object:Anim {
  start_value = 0,
  end_value = 120,
  duration = 1000,
  path = "ease_out",
  exec_cb = function(target, value)
    target:set { x = value }
  end,
  run = true,
}

需要 JSON 状态动画时使用 animengine。

页面生命周期

function pageOnPause()
  object:remove_all_anim()
end

function pageOnResume()
  -- 按当前状态重新建立动画
end

无限动画会持续唤醒 UI 线程。页面隐藏后应停止，回到页面时重新创建。

机型可用性

能力Xiaomi Smart Band 10 ProXiaomi Watch S4 41mm
Style 与对象样式✅✅
对象事件✅✅
对象属性动画✅✅
Anim 对象✅✅

获取源代码