样式相关函数及其参数、功能和使用场景

以下是对 LVGL 8.2 样式系统的全面总结，覆盖所有样式相关函数及其参数、功能和使用场景。内容分为以下几个部分：

一、样式系统核心机制

LVGL 的样式系统分为两类操作：

1. 直接设置对象的样式属性（快捷方式，无需创建 lv_style_t 对象）
2. 通过样式对象（lv_style_t）复用样式规则

二、直接设置对象样式的函数

这类函数直接修改对象的样式属性，适用于不需要复用样式规则的场景。

1. 通用函数原型

void lv_obj_set_style_<属性名>(lv_obj_t * obj, <类型> value, lv_style_selector_t selector);

参数说明：

• obj: 目标对象指针（例如按钮、标签）
• value: 属性值（如颜色、宽度、字体）
• selector: 样式选择器（由 状态（State） 和 部件（Part） 组合而成）

2. 关键函数列表（常用属性）

背景相关

// 设置背景颜色
void lv_obj_set_style_bg_color(lv_obj_t * obj, lv_color_t color, lv_style_selector_t selector);

// 设置背景透明度 (0-255, 或 LV_OPA_* 宏)
void lv_obj_set_style_bg_opa(lv_obj_t * obj, lv_opa_t opa, lv_style_selector_t selector);

// 设置背景渐变
void lv_obj_set_style_bg_grad_color(lv_obj_t * obj, lv_color_t color, lv_style_selector_t selector);
void lv_obj_set_style_bg_grad_dir(lv_obj_t * obj, lv_grad_dir_t dir, lv_style_selector_t selector);

边框相关

// 设置边框宽度
void lv_obj_set_style_border_width(lv_obj_t * obj, lv_coord_t width, lv_style_selector_t selector);

// 设置边框颜色
void lv_obj_set_style_border_color(lv_obj_t * obj, lv_color_t color, lv_style_selector_t selector);

// 设置边框边 (LV_BORDER_SIDE_LEFT/RIGHT/TOP/BOTTOM/INTERNAL)
void lv_obj_set_style_border_side(lv_obj_t * obj, lv_border_side_t side, lv_style_selector_t selector);

文字相关

// 设置字体
void lv_obj_set_style_text_font(lv_obj_t * obj, const lv_font_t * font, lv_style_selector_t selector);

// 设置文字颜色
void lv_obj_set_style_text_color(lv_obj_t * obj, lv_color_t color, lv_style_selector_t selector);

// 设置文字对齐 (LV_TEXT_ALIGN_LEFT/CENTER/RIGHT)
void lv_obj_set_style_text_align(lv_obj_t * obj, lv_text_align_t align, lv_style_selector_t selector);

布局与尺寸

// 设置内边距 (上下左右)
void lv_obj_set_style_pad_all(lv_obj_t * obj, lv_coord_t value, lv_style_selector_t selector);

// 设置外边框 (Margin)
void lv_obj_set_style_margin_top(lv_obj_t * obj, lv_coord_t value, lv_style_selector_t selector);

// 设置布局类型 (LV_LAYOUT_FLEX/GRID)
void lv_obj_set_style_layout(lv_obj_t * obj, uint16_t layout, lv_style_selector_t selector);

3. 参数宏定义详解

颜色宏

• 调色板宏 (预定义 16 种颜色):

  LV_PALETTE_RED, LV_PALETTE_BLUE, LV_PALETTE_GREEN, ... // 共 16 种
  lv_palette_main(LV_PALETTE_BLUE)      // 获取主色调
  lv_palette_lighten(LV_PALETTE_BLUE, 2) // 调亮
  lv_palette_darken(LV_PALETTE_BLUE, 2)  // 调暗
  

状态宏 (State)

• LV_STATE_DEFAULT: 默认状态
• LV_STATE_PRESSED: 按下状态
• LV_STATE_FOCUSED: 获得焦点
• LV_STATE_CHECKED: 勾选状态（如开关）
• LV_STATE_DISABLED: 禁用状态
• 组合状态: LV_STATE_PRESSED | LV_STATE_FOCUSED

部件宏 (Part)

• LV_PART_MAIN: 主体部分（所有对象都有）
• LV_PART_SCROLLBAR: 滚动条
• LV_PART_INDICATOR: 指示器（如滑块）
• LV_PART_KNOB: 旋钮（如开关）
• LV_PART_SELECTED: 选中部分（如表格单元格）

示例：选择器组合

// 设置按钮按下时的背景色（仅作用于主体部分）
lv_obj_set_style_bg_color(btn, lv_palette_main(LV_PALETTE_RED), LV_STATE_PRESSED | LV_PART_MAIN);

三、通过样式对象（lv_style_t）复用样式

适用于需要多个对象共享相同样式的场景。

1. 核心函数

初始化与释放

lv_style_t style;
lv_style_init(&style);  // 初始化样式
lv_style_reset(&style); // 重置样式（释放内存）

设置属性

lv_style_set_bg_color(&style, lv_color_hex(0xFF0000)); // 设置背景色
lv_style_set_text_font(&style, &lv_font_montserrat_16); // 设置字体

应用样式到对象

lv_obj_add_style(obj, &style, LV_STATE_DEFAULT); // 添加样式
lv_obj_remove_style(obj, &style, LV_STATE_DEFAULT); // 移除样式

2. 样式继承规则

• 优先级: 后添加的样式覆盖先前的
• 状态匹配: LVGL 会自动选择最匹配当前状态的样式

四、高级功能：过渡动画（Transition）

实现状态切换时的平滑动画效果。

1. 函数原型

void lv_style_set_transition(lv_style_t * style, const lv_style_transition_dsc_t * trans);

2. 参数配置

lv_style_transition_dsc_t trans;
static const lv_style_prop_t props[] = {LV_STYLE_BG_COLOR, LV_STYLE_BORDER_WIDTH}; // 监听的属性

// 初始化过渡描述
lv_style_transition_dsc_init(&trans, 
    props,                // 属性数组
    lv_anim_path_ease_out, // 动画曲线
    300,                   // 持续时间（ms）
    50,                    // 延迟时间（ms）
    NULL                   // 用户数据（可选）
);

lv_style_set_transition(&style, &trans);

3. 动画曲线宏

• lv_anim_path_linear: 线性变化
• lv_anim_path_ease_in: 缓入
• lv_anim_path_ease_out: 缓出
• lv_anim_path_ease_in_out: 缓入缓出

五、完整代码示例

示例1：直接设置按钮样式

lv_obj_t * btn = lv_btn_create(lv_scr_act());

// 默认状态样式
lv_obj_set_style_bg_color(btn, lv_palette_main(LV_PALETTE_BLUE), LV_PART_MAIN | LV_STATE_DEFAULT);
lv_obj_set_style_radius(btn, 10, LV_PART_MAIN | LV_STATE_DEFAULT);

// 按下状态样式
lv_obj_set_style_bg_color(btn, lv_palette_darken(LV_PALETTE_BLUE, 2), LV_PART_MAIN | LV_STATE_PRESSED);

示例2：通过样式对象复用

lv_style_t style_btn;
lv_style_init(&style_btn);
lv_style_set_bg_color(&style_btn, lv_palette_main(LV_PALETTE_RED));
lv_style_set_border_width(&style_btn, 2);

lv_obj_t * btn1 = lv_btn_create(lv_scr_act());
lv_obj_add_style(btn1, &style_btn, LV_PART_MAIN | LV_STATE_DEFAULT);

lv_obj_t * btn2 = lv_btn_create(lv_scr_act());
lv_obj_add_style(btn2, &style_btn, LV_PART_MAIN | LV_STATE_DEFAULT);

六、最佳实践

1. 性能优化:

   • 优先使用 lv_style_t 复用样式，减少重复属性设置
   • 避免在频繁调用的函数（如事件回调）中动态修改样式

2. 主题兼容性:

   • 自定义样式会覆盖当前主题的默认设置
   • 使用 lv_theme_set_apply_cb() 可深度定制主题

3. 调试技巧:

   • 使用 LV_LOG_TRACE 输出样式匹配过程
   • 通过 lv_obj_get_style_<属性名> 获取当前生效的样式值