当前位置：首页 > news >正文

第四章部件篇之下拉列表部件

news 来源：原创 2025/5/16 7:46:40

第四章部件篇之下拉列表部件

下拉列表部件常用于多选一的场景，其点击后可展开多个选项，用户可以从这些选项中选择一个，一旦选择好后，这些选项会自动收回。

1 下拉列表部件的组成

下拉列表部件由五个部分组成，示意图如下：

        按钮部分：
                ① LV_PART_MAIN：按钮的主体背景；
                ② LV_PART_INDICATOR：指示器，例如上图向下的箭头。
        列表部分：
                ③ LV_PART_SELECTED：当前选中的选项；
                ④ LV_PART_SCROLLBAR：滚动条；
                ⑤ LV_PART_MAIN：列表主体背景。
        注意：用户需要设置上述组成部分的样式，需要先将按钮或列表相关的部分获取回来，关于部件样式设置的内容，在前面第三章 LVGL基础知识（一）中样式属性中有介绍。

2 下拉列表部件的相关知识

2.1 添加选项

用户需要在下拉列表中添加选项，可以使用以下三种方法：
① 调用 lv_dropdown_set_options 函数添加选项，该函数如下所示：

lv_dropdown_set_options(dropdown， "First \n Second \n Third");

在上述的函数中，我们通过字符串传递下拉列表选项，这些选项字符串之间通过‘\n’ 进行分隔。
② 调用 lv_dropdown_add_option 函数添加选项，该函数如下所示：

lv_dropdown_add_option(dropdown， "New option"， pos);

上述的函数只会添加一个选项，其形参 pos 表示添加的位置，注意： 0 表示列表最上面的位置，以此向下类推。

③ 调用 lv_dropdown_set_static_options 函数添加选项，该函数如下所示：

lv_dropdown_set_options_static (dropdown， options);

上述函数所添加的是静态选项，在这种情况下，用户不能再使用 lv_dropdown_add_option函数添加选项，否则有可能会出现问题。
接下来，我们以简单示例来理解下拉列表的选项添加，示例代码如下所示：

void lv_mainstart(void)
{/* 创建一个下拉列表 */lv_obj_t* lv_ddlist1 = lv_dropdown_create(lv_scr_act());/* 方法一 添加多个选项（动态） */lv_dropdown_set_options(lv_ddlist1, "a\nb\nc\nd");lv_obj_set_pos(lv_ddlist1, 100, 100);/* 默认显示的选项 */lv_dropdown_set_selected(lv_ddlist1, 0);lv_obj_t* lv_ddlist2 = lv_dropdown_create(lv_scr_act());/* 方法二 添加单个选项 */lv_dropdown_add_option(lv_ddlist2, "0", 0);lv_dropdown_add_option(lv_ddlist2, "1", 1);lv_dropdown_add_option(lv_ddlist2, "2", 2);lv_dropdown_add_option(lv_ddlist2, "3", 3);/* 默认显示的选项 */lv_dropdown_set_selected(lv_ddlist2, 1);lv_obj_set_pos(lv_ddlist2, 300, 100);lv_obj_t* lv_ddlist3 = lv_dropdown_create(lv_scr_act());/* 方法三 添加多个选项（静态） */lv_dropdown_set_options_static (lv_ddlist3, "1");lv_obj_set_pos(lv_ddlist3, 500, 100);
}

在上述源码中，我们分别使用了三种方法来添加选项，一般情况下，第一种方法用得较多，示例代码可以在 PC 模拟器中运行，效果图如下所示：

2.2 获取当前选中的选项

当用户选中所需的选项之后，如果没有任何反馈，这将无法和其他板块进行交互，因此，我们需要在触发的事件回调中获取当前选中的选项索引和文本，相关函数如下：

lv_dropdown_get_selected(dropdown) /* 获取选中的选项索引 */
lv_dropdown_get_selected_str(dropdown， buf, buf_size)/* 获取选项字符串， 保存到 buf */

上述源码中，第一个函数用于获取选中的选项索引，第二个函数用于获取选中的选项文本，并将其保存到指定的 buf 中。

2.3 设置列表展开方向

在默认的情况下，当用户点击下拉列表后，其都是往下展开的，如果用户想修改列表展开的方向，可以调用以下函数：

lv_dropdown_set_dir(dropdown， LV_DIR_LEFT/RIGHT/UP/BOTTOM) /* 设置展开方向 */

在上述函数中，第二个形参代表列表的展开方向，用户可以选择上、下、左、右四个方向。
接下来，我们以简单示例来理解下拉列表的展开方向，示例代码如下所示：

void lv_mainstart(void)
{/* 创建一个下拉列表 */lv_obj_t* lv_ddlist1 = lv_dropdown_create(lv_scr_act());/*添加下拉列表项 */lv_dropdown_set_options(lv_ddlist1, "a\nb\nc\nd");lv_obj_set_pos(lv_ddlist1, 100, 100);/* 默认显示的下拉列表项 */lv_dropdown_set_selected(lv_ddlist1, 0);lv_obj_t* lv_ddlist2 = lv_dropdown_create(lv_scr_act());lv_dropdown_set_dir(lv_ddlist2,LV_DIR_LEFT); /* 设置为左侧展开 *//*添加下拉列表项 */lv_dropdown_add_option(lv_ddlist2, "0", 0);lv_dropdown_add_option(lv_ddlist2, "1", 1);lv_dropdown_add_option(lv_ddlist2, "2", 2);lv_dropdown_add_option(lv_ddlist2, "3", 3);/* 默认显示的下拉列表项 */lv_dropdown_set_selected(lv_ddlist2, 1);lv_obj_set_pos(lv_ddlist2, 300, 100);lv_obj_t* lv_ddlist3 = lv_dropdown_create(lv_scr_act());/*添加下拉列表项 */lv_dropdown_set_options_static(lv_ddlist3, "1");lv_obj_set_pos(lv_ddlist3, 500, 100);
}

由上述源码可知，我们设置了第二个下拉列表（lv_ddlist2）的展开方向为 LV_DIR_LEFT，即向左侧展开，示例代码可以在 PC 模拟器中运行，效果图如下所示：

2.4 设置下拉列表图标

下拉列表的图标箭头默认是向下的，如果用户修改了列表的展开方向，此时的箭头方向和展开方向就对应不上了。为了解决上述的问题， LVGL 提供了相关的图标设置函数：

lv_dropdown_set_symbol(dropdown， LV_SYMBOL_…) /* 设置图标 */

在上述函数中，第二个形参代表的是图标，一般情况下，我们调用内部的字体图标即可满足需求，修改后的图标如下图所示：

2.5 设置列表常显文本

在默认情况下，当用户选中某个选项后，该选项的文本会更新到列表的头部，示意图如下：

在上图中，当用户选中第一个选项，其文本内容（a）将更新到列表头部，如果用户需要设置列表头部的文本为固定内容，可以调用 lv_dropdown_set_text 函数，示例源码如下：

LV_FONT_DECLARE(myFont14)
void lv_mainstart(void)
{/* 创建一个下拉列表 */lv_obj_t* lv_ddlist1 = lv_dropdown_create(lv_scr_act());lv_dropdown_set_text(lv_ddlist1, "dropdown");/*添加下拉列表项 */lv_dropdown_set_options(lv_ddlist1, "a\nb\nc\nd");lv_obj_set_pos(lv_ddlist1, 100, 100);/* 默认显示哪一个下拉列表项 */lv_dropdown_set_selected(lv_ddlist1, 0);lv_obj_t* lv_ddlist2 = lv_dropdown_create(lv_scr_act());lv_dropdown_set_dir(lv_ddlist2,LV_DIR_LEFT);/* 设置下拉方向 *//*添加下拉列表项 */lv_dropdown_add_option(lv_ddlist2, "0", 0);lv_dropdown_add_option(lv_ddlist2, "1", 1);lv_dropdown_add_option(lv_ddlist2, "2", 2);lv_dropdown_add_option(lv_ddlist2, "3", 3);/* 默认显示哪一个下拉列表项 */lv_dropdown_set_selected(lv_ddlist2, 1);lv_obj_set_pos(lv_ddlist2, 300, 100);lv_obj_t* lv_ddlist3 = lv_dropdown_create(lv_scr_act());/*添加下拉列表项 */lv_dropdown_set_options_static(lv_ddlist3, "1");lv_obj_set_pos(lv_ddlist3, 500, 100);
}

在上述源码中，我们调用了 lv_dropdown_set_tex函数，把第一个列表（lv_ddlist1）的头部文本固定为“dropdown” 。示例代码可以在 PC 模拟器中运行，效果图如下所示：

2.6 打开、开闭下拉列表

当用户需要直接打开或者关闭下拉列表时，可以直接调用以下函数：

lv_dropdown_open(dropdown) /* 打开下拉列表 */
lv_dropdown_close(dropdown) /* 关闭下拉列表 */

3 下拉列表部件的 API 函数

LVGL 官方提供了一些与下拉列表部件相关 API，如下表所示：

函数	描述
lv_dropdown_create()	创建下拉列表
lv_dropdown_set_text()	设置下拉列表按钮的文本（常显文本）
lv_dropdown_set_options()	添加选项（动态）
lv_dropdown_set_options_static()	添加选项（静态）
lv_dropdown_add_option()	添加单个选项
lv_dropdown_clear_options()	清除所有选项
lv_dropdown_set_selected()	设置当前所选项
lv_dropdown_set_dir()	设置展开方向
lv_dropdown_set_symbol()	设置图标
lv_dropdown_set_selected_highlight()	设置当前选中的选项是否高亮
lv_dropdown_get_list()	获取下拉列表，以设置样式或进行其他修改
lv_dropdown_get_text()	获取下拉列表按钮的文本
lv_dropdown_get_options()	获取下拉列表的选项
lv_dropdown_get_selected()	获取所选选项的索引
lv_dropdown_get_option_cnt()	获取选项的总数
lv_dropdown_get_selected_str()	获取当前选中的选项文本
lv_dropdown_get_symbol()	获取图标
lv_dropdown_get_selected_highlight()	判断当前选中的选项是否高亮
lv_dropdown_get_dir()	获取展开方向
lv_dropdown_open()	打开下拉列表
lv_dropdown_close()	关闭下拉列表

4 下拉列表部件的实验

本实验基于VSCode+LVGL平台主要测试基础对象 API 函数的使用，实验现象：开机后，屏幕上显示五个下拉列表部件，用户可以切换它们的所选项，左侧的下拉列表与标签关联，它的所选项文本会更新到标签当中。

1. 程序解析

#include "lvgl/lvgl.h"/* 获取当前活动屏幕的宽高 */
#define scr_act_width() lv_obj_get_width(lv_scr_act())
#define scr_act_height() lv_obj_get_height(lv_scr_act())static lv_obj_t *label;                                             /* 当前选项标签 */
static const lv_font_t *dropdown_font;                              /* 定义字体 */
static int16_t dropdown_width;                                      /* 列表宽度 *//* 下拉列表的选项 */
static const char *options =    "option 1\n""option 2\n""option 3\n""option 4\n""option 5\n""option 6\n""option 7\n""option 8\n";/*** @brief  下拉列表事件回调* @param  无* @return 无*/
static void dropdown_event_cb(lv_event_t* e)
{lv_event_code_t code = lv_event_get_code(e);                    /* 获取事件类型 */lv_obj_t *dropdown = lv_event_get_target(e);                    /* 获取触发源 */if (LV_EVENT_VALUE_CHANGED == code)                             /* 判断事件类型 */{char buf[10];lv_dropdown_get_selected_str(dropdown, buf, sizeof(buf));   /* 获取当前选项文本 */lv_label_set_text(label, buf);                              /* 显示当前选项文本 */}
}/*** @brief  例1* @param  无* @return 无*/
static void lv_example_dropdown_1(void)
{/* 根据屏幕宽度选择字体和列表宽度 */if (scr_act_width() <= 320) {dropdown_font = &lv_font_montserrat_14;dropdown_width = 90;}else if (scr_act_width() <= 480) {dropdown_font = &lv_font_montserrat_18;dropdown_width = 120;}else {dropdown_font = &lv_font_montserrat_22;dropdown_width = 150;}lv_obj_t* dropdown = lv_dropdown_create(lv_scr_act());                                      /* 定义并创建下拉列表 */lv_dropdown_set_options_static(dropdown, options);                                          /* 添加下拉列表选项 */lv_obj_set_style_text_font(dropdown, dropdown_font, LV_PART_MAIN);                          /* 设置下拉列表字体 */lv_obj_set_width(dropdown, dropdown_width);                                                 /* 设置下拉列表宽度 */lv_obj_align(dropdown, LV_ALIGN_CENTER, -scr_act_width() / 3, 0);                           /* 设置下拉列表位置 */label = lv_label_create(lv_scr_act());                                                      /* 定义并创建标签 */lv_obj_set_style_text_font(label, dropdown_font, LV_PART_MAIN);                             /* 设置标签表字体 */lv_obj_set_width(label, dropdown_width);                                                    /* 设置标签宽度 */lv_obj_align_to(label, dropdown, LV_ALIGN_OUT_TOP_MID, 15, -scr_act_height() / 8);          /* 设置标签位置 */lv_label_set_text(label, "option 1");                                                       /* 设置标签文本 */lv_obj_add_event_cb(dropdown, dropdown_event_cb, LV_EVENT_VALUE_CHANGED, NULL);             /* 添加下拉列表回调 */
}/*** @brief  例2* @param  无* @return 无*/
static void lv_example_dropdown_2(void)
{lv_obj_t* dropdown;                                                                         /* 定义下拉列表 */dropdown = lv_dropdown_create(lv_scr_act());                                                /* 创建下拉列表 */lv_dropdown_set_options_static(dropdown, options);                                          /* 添加下拉列表选项 */lv_obj_set_style_text_font(dropdown, dropdown_font, LV_PART_MAIN);                          /* 设置下拉列表字体 */lv_obj_set_width(dropdown, dropdown_width);                                                 /* 设置下拉列表宽度 */lv_dropdown_set_dir(dropdown, LV_DIR_BOTTOM);                                               /* 设置下拉列表方向 */lv_dropdown_set_symbol(dropdown, LV_SYMBOL_DOWN);                                           /* 设置下拉列表符号 */lv_obj_align(dropdown, LV_ALIGN_CENTER, scr_act_width() / 8, -3 * scr_act_height() / 8);    /* 设置下拉列表位置 */dropdown = lv_dropdown_create(lv_scr_act());                                                /* 创建下拉列表 */lv_dropdown_set_options_static(dropdown, options);                                          /* 添加下拉列表选项 */lv_obj_set_style_text_font(dropdown, dropdown_font, LV_PART_MAIN);                          /* 设置下拉列表字体 */lv_obj_set_width(dropdown, dropdown_width);                                                 /* 设置下拉列表宽度 */lv_dropdown_set_dir(dropdown, LV_DIR_LEFT);                                                 /* 设置下拉列表方向 */lv_dropdown_set_symbol(dropdown, LV_SYMBOL_LEFT);                                           /* 设置下拉列表符号 */lv_obj_align(dropdown, LV_ALIGN_CENTER, scr_act_width() / 8, -1 * scr_act_height() / 8);    /* 设置下拉列表位置 */dropdown = lv_dropdown_create(lv_scr_act());                                                /* 创建下拉列表 */lv_dropdown_set_options_static(dropdown, options);                                          /* 添加下拉列表选项 */lv_obj_set_style_text_font(dropdown, dropdown_font, LV_PART_MAIN);                          /* 设置下拉列表字体 */lv_obj_set_width(dropdown, dropdown_width);                                                 /* 设置下拉列表宽度 */lv_dropdown_set_dir(dropdown, LV_DIR_RIGHT);                                                /* 设置下拉列表方向 */lv_dropdown_set_symbol(dropdown, LV_SYMBOL_RIGHT);                                          /* 设置下拉列表符号 */lv_obj_align(dropdown, LV_ALIGN_CENTER, scr_act_width() / 8, 1 * scr_act_height() / 8);     /* 设置下拉列表位置 */dropdown = lv_dropdown_create(lv_scr_act());                                                /* 创建下拉列表 */lv_dropdown_set_options_static(dropdown, options);                                          /* 添加下拉列表选项 */lv_obj_set_style_text_font(dropdown, dropdown_font, LV_PART_MAIN);                          /* 设置下拉列表字体 */lv_obj_set_width(dropdown, dropdown_width);                                                 /* 设置下拉列表宽度 */lv_dropdown_set_dir(dropdown, LV_DIR_TOP);                                                  /* 设置下拉列表方向 */lv_dropdown_set_symbol(dropdown, LV_SYMBOL_UP);                                             /* 设置下拉列表符号 */lv_obj_align(dropdown, LV_ALIGN_CENTER, scr_act_width() / 8, 3 * scr_act_height() / 8);     /* 设置下拉列表位置 */
}/*** @brief  LVGL演示* @param  无* @return 无*/
void lv_dropdown_demo(void)
{lv_example_dropdown_1();lv_example_dropdown_2();
}

2. 实现现象