LVGL Pro 使用指南[04]LVGL XML-组件

本文说明如何使用 LVGL XML 中创建和使用组件。

概述 链接到标题

组件其英文是 Component，在 LVGL XML 是创建新 UI 元素的主要构建块之一。使用组件的目的是为了让同类型的 UI 构建可以在不同的地方复用。例如你需要 3 个按钮组（一组有 4 个按钮），你只需要定义一个按钮组组件，在 Screen 中直接添加 3 次这个组件，而不需要在 screen 中添加 12 个按钮。

组件的 XML 文件内容被包裹在 <component> XML 根元素中

<component> 支持以下子 XML 标签：

组件主要功能特点

  • 扩展另一个组件 (Component) 或控件 (Widget)
  • 组件可以由控件和其他组件组合构建
  • 可以定义自定义 API
  • 可自定义局部样式，可使用全局样式
  • 可自定义局部常量，可使用全局常量
  • 可添加函数调用，使用数据绑定，添加 screen 加载/创建事件
  • 可通过<previews>在 XML Editor 中为组件设置不同的预览。

当创建一个组件时，可以从另一个组件或控件 (Widget) 扩展，例如 <view extends="lv_slider"> 。从控件扩展而来的组件可以使用 控件 的 API，例如 <view extends="lv_slider" min_value="20"> 中的min_value=20。从组件扩展而来的组件可以使用原组件 <api> 属性： <view extends="my_button" button_text="Apply"> 中的button_text="Apply"，关于 API 你可以理解为是组件的对外接口，之后有文章专门介绍。

组件可以无需导出为 C 编译到固件中，LVGL 有 XML 解析器，在运行时可以直接加载运行组件的 XML 文件。当然也可以通过 Editor 导出组件 XML 为 C 代码，编译到固件中。

本文只说明如何在 XML 中创建组件和使用组件。不说明手写代码如何在运行时加载使用 XML 文件中的组件。

XML 链接到标题

创建组件 链接到标题

在 XML Editor 中创建组件时，一般是放到components目录下，每个组件有一个独立的 XML 文件，文件名就是组件的名称。如果你的组件比较复杂或者有分类需求，可以在components目录下创建子目录，将相关的组件放到子目录下。

扩展方式 链接到标题

可以通过<view>标签的extends属性扩展控件或者组件的方式创建一个组件，例如下面的 my_button.xml 创建一个组件，扩展自lv_button控件，添加了一个lv_label标签。

<component>
	<view extends="lv_button" flex_flow="row">
		<lv_label text="name:" style_text_color="0xFF0000" />
	</view>
</component>

组合方式 链接到标题

通过在<view>标签下添加多个组件或者控件，将它们组合起来，形成一个新的组件。例如下面的 my_group_button.xml 创建一个组件，包含 3 个按钮。

<component>
	<view width="content" height="content" flex_flow="row">
		<lv_button style_bg_color="0xFF0000" />
		<lv_button style_bg_color="0x00FF00" />
		<lv_button style_bg_color="0x0000FF" />
	</view>
</component>

可以通过预览界面看到组件的效果 group_button

可以通过<view>标签的其它属性对其子元素的布局，大小进行控制，例如width和height属性控制组件的大小，flex_flow="row"属性控制子元素的布局方式为水平方向。

使用组件 链接到标题

在 XML 中使用组件非常简单，在其他组件、screen 和控件的 <view> 中将组件名作为 XML 标签使用即可。请记住组件名就是组件的文件名。

<screen permanent="true">
	<view>
		<lv_button align="center">
			<lv_label text="Hello LVGL XML Editor" />
		</lv_button>
		<my_group_button />
	</view>
</screen>

通过 XML Editor 的预览界面可以看到效果 use

组件属性 链接到标题

在组件中可以在 <api> 标签中添加自定义属性。在子元素中通过使用 $ 引用这些属性。例如下面的 my_button.xml 组件，添加了一个my_name属性，在子元素中通过$my_name引用这个属性。

<component>
	<api>
		<prop name="my_name" type="string" />
	</api>
	<view extends="lv_button" flex_flow="row">
		<lv_label text="name:" style_text_color="0xFF0000" />
		<lv_label text="$my_name" />
	</view>
</component>

可以在预览界面看到效果如下，因为第二个lv_label标签引用了my_name属性，在组件预览中只会显示为"Text"。

也可以在使用组件的时候，直接通过my_name属性设置组件的文本，例如下面的代码：

<screen permanent="true">
	<view flex_flow="column">
		<lv_button align="center" floating="true">
			<lv_label text="Hello LVGL XML Editor" />
		</lv_button>
		<my_group_button />
		<my_button my_name="Frank" width="200"></my_button>
	</view>
</screen>

因为my_name属性被设置为"Frank"，所以组件的文本也被设置为"Frank"。

可以直接在引用组件时调整子元素的属性，例如上面的my_button组件，通过width="200"属性将按钮的宽度设置为 200 像素。

以上的整体效果如下： preview

参考 链接到标题

https://docs.lvgl.io/master/details/xml/ui_elements/components.html