LVGL Widgets

在 LVGL 对象层次结构的下一层是组件，它们直接支持样式设置。它们可以有子部分，可以单独设置样式。通常样式是继承的，但这取决于组件的具体特性或功能。组件及其部分具有状态，可以为不同状态设置不同的样式。

组件可以有子组件，子组件可以是任何其他组件。可以将其视为嵌套结构。子组件随父组件一起移动，如果父组件被隐藏，其子组件也将被隐藏。

默认情况下，LVGL 将新组件绘制在旧组件之上，包括它们的子组件。当组件有子组件时，会发生属性继承。一些属性（通常与文本和透明度相关的属性）可以从父组件的样式继承。当属性可继承时，将搜索父对象以查找为该属性指定值的对象。父对象将使用自己的状态来确定值。例如，如果按钮被按下且文本颜色由”pressed”状态定义，则将使用此”pressed”文本颜色。

组件部分

组件可以由多个部分组成，每个部分都可以独立设置样式。例如，复选框有一个主部分（设置背景和文本标签样式）和一个指示器部分（设置复选框样式）。所有组件都有一个主部分，其他组件的可用部分在组件说明中指定。

可能的部分有：

main（可选，dict）：组件的主部分，即背景。在组件顶层应用的任何样式属性都假定适用于此部分，但也可以在 main 配置键下指定。
scrollbar（可选，dict）：滚动条样式。
indicator（可选，dict）：组件的指示器部分。指示器部分可用于在滑块、条形图或弧线中显示复选框或其他视觉指示器。
knob（可选，dict）：组件的旋钮部分，例如滑块、条形图或弧线中可拖动的项。
selected（可选，dict）：组件当前选定的部分，例如文本或滚轮中选定的项。
items（可选，dict）：组件的项部分，例如滚轮中的项。
ticks（可选，dict）：仪表上的刻度。
cursor（可选，dict）：组件的光标部分，例如数字调节器中的光标。

# 带有旋钮和指示器样式的滑块示例
- slider:
    # main（背景）样式
    align: CENTER
    bg_opa: COVER
    bg_grad: color_bar
    radius: 0
    indicator: # 使指示器部分不可见
      bg_opa: TRANSP
    knob: # 使光标更细
      radius: 2
      pad_left: -4
      pad_right: -4
      bg_color: 0x000000

公共属性

以下属性是所有组件共有的。

配置变量：

id（可选，ID）：手动指定用于代码生成的 ID。
x（可选，int16 或 percentage）：组件的水平位置。
y（可选，int16 或 percentage）：组件的垂直位置。

NOTE

默认情况下，x 和 y 坐标从父对象内容区域的左上角测量。重要：内容区域在内边距之后开始，因此如果父对象有非零的内边距值，位置将相应偏移。百分比值根据父对象内容区域大小计算。

如果指定了 align，x 和 y 可以用作计算位置的偏移量（也可以为负值）。如果在父对象上使用布局，则忽略它们。

height（可选）：组件的高度（像素或百分比），或 SIZE_CONTENT。
width（可选）：组件的宽度（像素或百分比），或 SIZE_CONTENT。

NOTE

大小设置支持特殊值：SIZE_CONTENT。它表示组件在相应方向上的大小将设置为其子组件的大小。注意，仅考虑右侧和底部的子组件，顶部和左侧的子组件将被裁剪。此限制使行为更可预测。带有 hidden 或 floating 标志的组件将被 SIZE_CONTENT 计算忽略。

与 CSS 类似，LVGL 也支持 min_width、max_width、min_height 和 max_height。这些是限制，防止组件大小变得小于/大于这些值。如果大小通过百分比或 SIZE_CONTENT 设置，它们特别有用。

min_width、max_width、min_height、max_height（可选，int16 或 percentage）：设置最小/最大宽度或最小/最大高度。可以使用像素和百分比值。百分比值相对于父对象内容区域的尺寸。默认为 0%。
scrollbar_mode（可选，string）：如果子组件在其父对象内容区域之外（不含内边距的大小），父对象可以变为可滚动（见 scrollable 标志）。组件可以在一次操作中水平或垂直滚动。根据设置可以出现滚动条：
- "OFF"：从不显示滚动条（使用双引号！）。
- "ON"：始终显示滚动条（使用双引号！）。
- "ACTIVE"：在组件被滚动时显示滚动条。
- "AUTO"：当内容足够大可滚动时显示滚动条（默认）。
scroll_dir（可选，string）：设置对象的允许滚动方向——可选 LEFT、RIGHT、BOTTOM、TOP、HOR、VER、ALL（默认）。
scroll_snap_x（可选，string）：对于可滚动对象的子组件，此属性定义子组件在 X 方向上的吸附位置。可选 NONE（默认）、START、END、CENTER。
scroll_snap_y（可选，string）：对于可滚动对象的子组件，此属性定义子组件在 Y 方向上的吸附位置。可选 NONE（默认）、START、END、CENTER。
ext_click_area（可选，int16）：将组件外部响应指针输入（触摸、鼠标等）的区域增加指定数量的像素。与 adv_hittest 标志结合使用，可微调组件周围区域的灵敏度。
align（可选，enum）：组件相对于父对象的对齐方式。子组件将被裁剪到父对象边界。使用不以 OUT_ 开头的值之一（参见下图）。
align_to（可选，list）：组件相对于同一级别另一个组件的对齐方式。注意，调整屏幕大小或包含或引用此指令的组件的大小不会更新位置。
- id（必需）：要对齐到的组件的 ID。
- align（必需，string）：期望的对齐方式（以 OUT_ 开头的值之一）。
- x（可选，int16 或 percentage）：水平偏移位置。默认为 0。
- y（可选，int16 或 percentage）：垂直偏移位置。默认为 0。

group（可选，string）：将与旋转编码器交互的组件组名称。每个组中始终有一个获得焦点的组件，接收编码器操作。你需要将输入设备与组关联。输入设备只能向一个组发送按键事件，但一个组可以从多个输入设备接收数据。如果组件或编码器未指定组，则将分配一个未命名的默认组，因此在大多数仅使用一个编码器的情况下，无需显式指定组。
layout（可选）：详情参见布局。默认为 NONE。
styles（可选，ID）：主组件配置中样式定义的 ID，用于覆盖主题样式。
theme（可选，list）：要应用于组件和子组件的样式列表。与主组件相同的配置选项。
widgets（可选，list）：要作为此组件的子组件绘制的 LVGL 组件列表。与主组件相同的配置选项。

state（可选，dict）：组件或其（子）部分可以有状态，支持单独的样式设置。这些状态样式从主题继承，但可以在样式定义中局部设置或覆盖。可选：
- checked（可选，boolean）：切换或选中状态。
- disabled（可选，boolean）：禁用状态（也可与简写操作 lvgl.widget.enable 和 lvgl.widget.disable 配合使用）。
- edited（可选，boolean）：通过编码器编辑。
- focus_key（可选，boolean）：通过键盘或编码器聚焦，但不是通过触摸屏聚焦。
- focused（可选，boolean）：通过键盘或编码器聚焦或通过触摸屏点击聚焦。
- pressed（可选，boolean）：正在被按下。
- scrolled（可选，boolean）：正在被滚动。
- user_1、user_2、user_3、user_4（可选，boolean）：自定义状态。

默认情况下，所有状态均为 false，且是可模板化的。要为状态应用样式，需要在上一级别指定，例如：

- button:
    checkable: true
    state:
      checked: true # 在此处激活启动时使用的状态
    checked:
      bg_color: 0x00FF00 # 在此处应用处于相应状态时的样式

状态本身可以通过与组件交互或通过带有 lvgl.widget.update 的操作来更改。

查看遮盖状态和控制食谱示例，该示例展示了如何使用样式和属性显示 Home Assistant 实体的不同状态。

除视觉样式外，每个组件还支持一些布尔标志来影响行为：

adv_hittest（可选，boolean）：允许执行更精确的命中（点击）测试。例如，可通过考虑圆角来提供帮助。在适用时进一步阅读。
checkable（可选，boolean）：点击组件时切换选中状态。
click_focusable（可选，boolean）：点击组件时为其添加聚焦状态。
clickable（可选，boolean）：使组件可被输入设备点击。默认为 true。如果为 false，则会将点击传递给其后面的组件（穿透点击）。
event_bubble（可选，boolean）：将事件传播给父对象。
floating（可选，boolean）：在父对象滚动时不滚动组件，并忽略布局。
gesture_bubble（可选，boolean）：将手势传播给父对象。
hidden（可选，boolean）：隐藏组件（就像它根本不存在一样），也可与简写操作 lvgl.widget.show 和 lvgl.widget.hide 配合使用。隐藏的对象在布局计算中被忽略。默认为 false。
ignore_layout（可选，boolean）：组件被布局简单忽略。其坐标可以照常设置。
layout_1、layout_2（可选，boolean）：自定义标志，布局可自由使用。
overflow_visible（可选，boolean）：不将子组件的内容裁剪到父对象边界。
press_lock（可选，boolean）：即使按压从组件上滑开，也保持组件处于按下状态。
scroll_chain（可选，boolean）：scroll_chain_hor | scroll_chain_ver 的打包。
scroll_chain_hor（可选，boolean）：允许将水平滚动传播给父对象。
scroll_chain_ver（可选，boolean）：允许将垂直滚动传播给父对象。
scroll_elastic（可选，boolean）：允许在内部滚动，但速度较慢。
scroll_momentum（可选，boolean）：使组件在被”抛出”时滚动更远。
scroll_on_focus（可选，boolean）：当组件获得焦点时自动滚动使其可见。
scroll_one（可选，boolean）：仅允许在 snappable 子组件上滚动。
scroll_with_arrow（可选，boolean）：允许使用箭头键滚动获得焦点的组件。
scrollable（可选，boolean）：组件可以变为可滚动的。默认为 true（另见 scrollbar_mode 属性）。
send_draw_task_events（可选，boolean）：启用为自定义渲染发送绘制任务事件。
snappable（可选，boolean）：如果父对象启用了滚动吸附，可以吸附到此组件。
user_1、user_2、user_3、user_4（可选，boolean）：自定义标志，用户可自由使用。
widget_1、widget_2（可选，boolean）：自定义标志，组件可自由使用。

NOTE

LVGL 仅为数值 value 支持整数。可视化组件无法直接显示浮点数，但它们允许按 10 的倍数缩放。食谱中的一些示例涵盖了如何做到这一点。

TIP

默认情况下，组件只能在其边界区域内被点击。然而，特别是对于小组件，扩大组件的”可点击”区域可能会有帮助。你可以通过 ext_click_area 样式属性指定像素数量来扩展组件周围的可点击区域。

组件特定属性

一些组件具有特定于该组件的属性。例如，label 有一个 text 属性。特定于组件的属性在下面各部分中描述。其中一些属性也可以通过相应的 lvgl.<widget_type>.update 操作更新，例如 lvgl.label.update 允许更新不仅限于公共样式属性，还包括标签的 text 属性。

文本属性

几个组件有一个 text 属性，指定该属性的所有可能方式对所有 text 属性都是通用的。文本可以是 Unicode 字符串或其他可转换为字符串的常量；如果字符串用双引号 "" 括起来，则标准转义序列（如换行符 \n 和 Unicode 码点）将被转换。文本值也可以是返回 std::string 的 lambda，或者可以使用 format 属性配合 printf 风格格式化来指定。还有一个 time_format 选项，允许使用 strftime 格式。

当格式化单个浮点值时，可以提供替换字符串，在值为 nan 或 inf 时使用。替换字符串通过 if_nan 选项指定。

文本也可以通过在映射组件中查找来获取，方法是指定 mapping ID 和 value（查找键）。映射的 to 类型必须为 string。value 可以是字面量或 lambda，并且应与映射的 from 类型匹配。

mapping（必需，ID）：to 类型为 string 的 mapping 组件的 ID。
value（必需，templatable）：在映射中查找的键。

示例：

# 标签示例
- label:
    id: label_id
    text: "Text string"
- checkbox:
    id: checkbox_id
    text: "\uF00C"  # Unicode 复选标记

on_...:
  - lvgl.label.update:
      id: label_id
      text:
        format: "%d bells, %d things"
        args: [x, 10]  # x 是来自外部触发器的值。
  - lvgl.label.update:
      id: label_id
      text: !lambda return id(text_sensor).state;
  - lvgl.label.update:
      id: label_id
      text:
        time_format: "%c"   # 使用默认时间组件
  - lvgl.checkbox.update:
      id: checkbox_id
      text:
        time_format: "%c"
        time: sntp_id
  - lvgl.label.update:
      id: label_id
      text:
        time_format: "%c"
        time: !lambda return id(sntp_id).utcnow();
  - lvgl.label.update:
      id: value_id
      text:
        format: "%.1f"
        args: [id(sensor_id).state]
        if_nan: "N/A"
  - lvgl.label.update:
      id: label_id
      text:
        mapping: string_map    # 一个带有 `to: string` 的映射组件
        value: 2               # 字面键
  - lvgl.label.update:
      id: label_id
      text:
        mapping: string_map
        value: !lambda return id(my_sensor).state;

有关文本样式，请参见 label 组件的属性。

组件

`animimg`

动画图像与普通的 image 组件类似。主要区别在于，不设置一个源图像，而是设置多个源图像列表。你还可以指定持续时间和重复次数。

配置变量：

src（必需，list of images）：现有图像配置 ID 的列表，将作为动画帧加载。
auto_start（可选，boolean）：启动时自动开始播放动画。默认为 true。
duration（必需，Time）：播放周期的总持续时间（每帧显示相同的时间）。
repeat_count（可选，int16 或 forever）：播放应重复的次数。默认为 forever。
样式属性中背景矩形的某些样式选项，使用典型的背景样式属性，以及图像本身使用图像样式属性。

操作：

lvgl.animimg.start 操作以 auto_start 为 false 显示后或 repeat_count 过期后启动动画播放。
- id（必需）：要启动的 animimg 组件的 ID 或 ID 列表。
lvgl.animimg.stop 操作停止动画播放。
- id（必需）：要停止的 animimg 组件的 ID 或 ID 列表。
lvgl.animimg.update 操作可用于更改 repeat_count 和 duration，就像使用 lvgl.widget.update 操作处理通用样式、状态或标志一样。
- id（必需）：要更新的 animimg 组件的 ID 或 ID 列表。
- src（可选，list of images）：现有图像配置 ID 的列表，将作为动画帧加载。
- auto_start（可选，boolean）：更新后自动开始播放动画。默认为 true。
- duration（可选，Time）：播放周期的总持续时间（每帧显示相同的时间）。这将在下一次播放循环时生效。
- repeat_count（可选，int16 或 forever）：播放应重复的次数。默认为 forever。
- 样式属性中背景矩形的某些样式选项，使用典型的背景样式属性，以及图像本身使用图像样式属性。

触发器：

交互 LVGL 事件触发器。

示例：

# 组件示例：
- animimg:
    align: CENTER
    id: anim_id
    src: [ cat_image, cat_image_bowtie ]
    duration: 1000ms

# 操作示例：
on_...:
  - lvgl.animimg.update:
      id: anim_id
      repeat_count: 100
      duration: 300ms

查看食谱中的电池充电动画以获取更详细的示例。

`arc`

弧线由背景和前景弧组成。指示器前景可以通过旋钮触摸调整。

配置变量：

adjustable（可选，boolean）：添加一个用户可以移动来更改值的旋钮。默认为 false。
arc_color（可选，color）：绘制弧线使用的颜色。
arc_opa（可选，opacity）：弧线的透明度。
arc_rounded（可选，boolean）：将弧线的端点设为圆角。true 为圆角，false 为垂直线结尾。
arc_width（可选，int16）：以像素为单位设置弧线的宽度。
change_rate（可选，uint16）：限制触摸或拖动时弧线值变化的速度。变化率以度/秒定义。默认为 720。
end_angle（可选，0-360）：弧线背景的结束角度（见注释）。默认为 45。
indicator（可选，list）：指示器部分的设置，用于显示值。支持样式列表和基于状态的样式来自定义。使用弧样式属性绘制另一条弧。其内边距值是相对于背景弧解释的。
knob（可选，list）：旋钮部分的设置，用于控制值。支持样式列表和基于状态的样式来自定义。使用所有背景属性和内边距值在指示器末端绘制一个手柄。零内边距时旋钮大小与指示器宽度相同。较大的内边距使其更大，较小的内边距使其更小。
max_value（可选，int16）：指示器的最大值。默认为 100。
min_value（可选，int16）：指示器的最小值。默认为 0。
mode（可选，string）：NORMAL：指示器从最小值绘制到当前值。REVERSE：指示器从最大值逆时针绘制到当前值。SYMMETRICAL：指示器从中间点绘制到当前值。默认为 NORMAL。
rotation（可选，0-360）：相对于 0 度位置的偏移。默认为 0.0。
start_angle（可选，0-360）：弧线背景的起始角度（见注释）。默认为 135。
value（可选，int16）：启动时指示器的实际值，在 0 - 100 范围内。默认为 0。
任何样式和基于状态的选项，用于覆盖从父对象继承的样式。弧线的大小和位置将遵循内边距样式属性。

默认情况下，组件的整个区域都是可交互的。如果启用了 adv_hittest 标志，则弧线可以从中间点击穿透。点击仅在背景弧的环上被识别。如果这太窄，可以使用 ext_click_area 样式属性增加弧线附近的敏感区域。

NOTE

零度位置在组件的正右方（3 点钟方向），度数从那里顺时针增加。角度在 0 - 360 范围内指定。

操作：

lvgl.arc.update 操作根据上述特定选项更新组件样式和属性，就像使用 lvgl.widget.update 操作处理通用样式、状态或标志一样。
- id（必需）：要更新的 arc 组件的 ID 或 ID 列表。
- change_rate（可选，uint16）：新的变化率（度/秒）。
- end_angle（可选，0-360）：弧线背景的新结束角度。
- max_value（可选，int16）：指示器的新最大值。
- min_value（可选，int16）：指示器的新最小值。
- mode（可选，string）：新的指示器模式。
- rotation（可选，0-360）：相对于 0 度位置的新偏移。
- start_angle（可选，0-360）：弧线背景的新起始角度。
- value（可选，int16）：指示器的新值。
- 任何样式和基于状态的选项，用于覆盖从父对象继承的样式。弧线的大小和位置将遵循内边距样式属性。

触发器：

on_value 触发器在弧线值更改时激活，无论是用户交互还是编程更改。新值在变量 x 中返回。
on_change 触发器在弧线值通过用户交互更改时激活。新值在变量 x 中返回。
on_update 触发器在弧线值通过编程更改时激活（例如，通过 lvgl.arc.update）。新值在变量 x 中返回。
交互同样在 x 中返回值的 LVGL 事件触发器。

示例：

# 组件示例：
- arc:
    align: CENTER
    id: arc_id
    value: 75
    min_value: 0
    max_value: 100
    adjustable: true

# 操作示例：
on_...:
  - lvgl.arc.update:
      id: arc_id
      knob:
        bg_color: 0x00FF00
      value: 55

# 触发器示例：
- arc:
    ...
    on_value:
      - logger.log:
          format: "Arc value is: %.0f"
          args: [ 'x' ]

NOTE

on_value 和 on_change 触发器在拖动弧线旋钮或使用按键更改时发送。事件在拖动弧线旋钮期间持续发送；这通常会对性能产生负面影响。为缓解此问题，考虑使用像 on_release 这样的通用交互触发器，在交互完成后获取一次 x 变量。

arc 还可以集成为 Number 或 Sensor 组件。

查看灯光亮度滑块和媒体播放器音量滑块以了解如何使用滑块（或弧线）控制 Home Assistant 中实体的示例。

`bar`

条形组件具有背景和指示器前景。指示器的大小根据条形的当前 value 设置。

如果宽度小于高度，则可以创建垂直条形。

不仅可以设置条形的结束值，还可以设置起始值，这将更改指示器的起始位置。

配置变量：

animated（可选，boolean）：在启动时以动画方式将指示器移动到起始值。默认为 true。
indicator（可选，int）：指示器部分的设置，用于显示值。支持样式列表和基于状态的样式来自定义，使用所有典型的背景属性。
max_value（可选，int）：指示器的最大值。默认为 100。
min_value（可选，int）：指示器的最小值。默认为 0。
mode（可选，string）：条形的模式。默认为 NORMAL。
- NORMAL：指示器从最小值绘制到当前值。
- RANGE：指示器从起始值绘制到当前值。
- SYMMETRICAL：指示器对称地从中间点绘制到当前值。
start_value（可选，int）：对于 RANGE 模式，指示器的起始值。默认为 0。
value（可选，int）：指示器结束的值，在 min_value - max_value 范围内。默认为 0。
样式属性中的样式选项。条形的背景使用典型的背景样式属性。添加内边距将使指示器变小或变大。

操作：

lvgl.bar.update 操作根据上述特定选项更新组件样式和属性，就像使用 lvgl.widget.update 操作处理通用样式、状态或标志一样。
- id（必需）：要更新的 bar 组件的 ID 或 ID 列表。
- 上述任何条形选项。
- 样式属性中的样式选项。条形的背景使用典型的背景样式属性。添加内边距将使指示器变小或变大。

触发器：

交互 LVGL 事件触发器。

示例：

# 组件示例：
- bar:
    align: CENTER
    id: bar_id
    value: 75
    min_value: 1
    max_value: 100

# 操作示例：
on_...:
  - lvgl.bar.update:
      id: bar_id
      value: 55

bar 还可以集成为 Number 或 Sensor 组件。

`button`

简单的按压（瞬时）或切换（双状态）按钮。

按钮本身没有内容，因此需要添加子组件。作为带单个文本标签的按钮的简写，可以使用 text: 选项添加一个 label 子组件，否则必须使用 widgets: 键在按钮内部添加其他组件。

按钮默认是瞬时的，具有 pressed 状态。如果设置了 checkable 标志，它就变成切换按钮，还具有 checked 状态。

配置变量：

checkable（可选，boolean）：制作切换按钮的重要标志（报告其 checked 状态）。默认为 false。
text（可选，string）：要显示在按钮上的文本。这将创建并添加一个标签组件到按钮。不可与 widgets: 键一起使用。
样式属性中按钮背景的样式选项。使用典型的背景样式属性。

一个值得注意的状态是 checked（布尔值），可以应用不同的样式。

触发器：

on_change 触发器在点击后激活。如果 checkable 为 true，表示选中状态的布尔变量 x 可供此触发器中的 lambda 使用。
on_value 触发器在选中值更改时激活，无论是用户交互还是编程更改。新值在变量 x 中返回。
on_update 触发器在选中值通过编程更改时激活（例如，通过 lvgl.widget.update）。新值在变量 x 中返回。
交互 LVGL 事件触发器。

示例：

# 带文本的组件示例：
- button:
    id: btn_id
    text: "Click me!"

要创建图像按钮，请向其添加子 image 组件：

# 带图像的切换按钮示例：
- button:
    id: btn_id
    align: CENTER
    checkable: true
    widgets:
      - image:
          src: my_image_id

# 触发器示例：
- button:
    ...
    on_value:
      - logger.log:
          format: "Button checked state: %d"
          args: [ x ]

button 还可以集成为 Binary Sensor 或 Switch 组件。

NOTE

连接到按钮的二进制传感器报告其 pressed 状态，而连接到按钮的开关报告其 checked 状态。

查看远程灯光按钮以了解如何使用可切换按钮操作 Home Assistant 服务的示例。

操作：

lvgl.button.update 操作可用于在运行时更新按钮样式。如果按钮有 text: 选项，也可以通过此操作更新。
- id（必需）：要更新的 button 组件的 ID 或 ID 列表。
- text（可选，string）：更新按钮的文本（仅当按钮配置了 text: 选项时）。
- 样式属性中按钮背景的样式选项。
NOTE

当添加其他组件作为子组件时，必须直接更新它们。

# 文本更新示例
- button:
    id: btn_id
    text: "Click me!"
    on_click:
      lvgl.button.update:
        id: btn_id
        text: "Clicked"

`buttonmatrix`

按钮矩阵组件是一种轻量级的多按钮行列显示方式。它轻量是因为按钮实际上没有被创建，而是简单地即时绘制。这将每个按钮的内存占用从大约 200 字节（按钮及其标签组件各占用）减少到仅 8 字节。

配置变量：

rows（必需，list）：按钮行的列表：
- buttons（必需，list）：一行中的按钮列表：
  - id（可选）：矩阵中按钮的 ID。
  - key_code（可选，string）：按键时作为键码发送到 Key collector 组件的一个字符，而不是 text。
  - selected（可选，boolean）：将按钮设为最近释放或聚焦的。默认为 false。
  - text（可选，Text property）：按钮上显示的文本。
  - width（可选）：相对于同一行中其他按钮的宽度。必须在 1 到 15 之间；默认为 1（例如，给定一行有两个按钮，一个为 width: 1，另一个为 width: 2，第一个将是 33% 宽，第二个将是 66% 宽）。
  - control（可选）：控制按钮行为的二进制标志（默认均为 false）：
    - checkable（可选，boolean）：启用按钮切换，checked 状态将在点击按钮时添加/移除。
    - checked（可选，boolean）：使按钮被选中。将 checked 样式应用于按钮。
    - click_trig（可选，boolean）：控制如何触发 on_value：如果为 true 则在点击时，如果为 false 则在按下时。
    - custom_1 和 custom_2（可选，boolean）：自定义标志，可自由使用。
    - disabled（可选，boolean）：将 disabled 样式应用于按钮。
    - hidden（可选，boolean）：隐藏按钮（隐藏的按钮在布局中仍占用空间，只是不可见或不可点击）。
    - no_repeat（可选，boolean）：长按时禁用重复。
    - popover（可选，boolean）：按此按钮时在弹出框中显示按钮标签。
    - recolor（可选，boolean）：使用 # 启用按钮文本的重新着色。例如：It's #FF0000 red#
items（可选，list）：项部分的设置，按钮使用文本和典型的背景样式属性，但排除转换和变换。
one_checked（可选，boolean）：一次只允许一个按钮被选中（即单选按钮）。默认为 false。
样式属性中按钮矩阵背景的样式选项，使用典型的背景样式属性。pad_row 和 pad_column 设置按钮之间的间距。

操作：

lvgl.buttonmatrix.update 操作更新特定 state、items 选项中指定的项样式和属性。
- id（必需）：要更新的 buttonmatrix 组件的 ID 或 ID 列表。
- 上述 state、items 选项中的组件样式或属性，要更新的。
lvgl.matrix.button.update 操作更新特定 control、width 和 selected 选项中指定的按钮样式和属性。
- id（必需）：要更新的矩阵按钮的 ID 或 ID 列表。
- 上述 control、width 和 selected 选项中的组件样式或属性，要更新的。

触发器：

on_value 和交互触发器可以为每个按钮配置，在点击后激活。如果 checkable 为 true，表示选中状态的布尔变量 x 可供此触发器中的 lambda 使用。
交互 LVGL 事件触发器可以为主组件配置，它们将按下的按钮 ID（或无按钮时为 null）作为变量 x（指向 uint16_t 的指针，保存按钮的索引号）传递。

示例：

# 组件示例：
- buttonmatrix:
    x: 10
    y: 40
    width: 220
    items:
      pressed:
        bg_color: 0xFFFF00
    id: matrix_id
    rows:
      - buttons:
        - id: button_1
          text: "\uF04B"
          control:
            checkable: true
        - id: button_2
          text: "\uF04C"
          control:
            checkable: true
      - buttons:
        - id: button_3
          text: "A"
          control:
            popover: true
        - id: button_4
          text: "B"
          control:
            disabled: true
      - buttons:
        - id: button_5
          text: "It's #ff0000 red#"
          width: 2
          control:
            recolor: true

# 操作示例：
on_...:
  - lvgl.matrix.button.update:
      id: button_1
      width: 1
      selected: true
      control:
        checkable: false
  - lvgl.buttonmatrix.update:
      id: matrix_id
      state:
        disabled: true
      items:
        bg_color: 0xf0f0f0

# 触发器示例：
- buttonmatrix:
    ...
    rows:
      - buttons:
        ...
        - id: button_2
          ...
          control:
            checkable: true
          on_value: # 单个按钮的触发器，返回选中状态
            - logger.log:
                format: "Button 2 checked: %d"
                args: [ x ]
    on_press: # 矩阵的触发器，确定按下了哪个按钮。
      - logger.log:
          format: "Matrix button pressed: %d"
          args: ["x"]  # 如果 x 为 65535，则是容器（或穿透已禁用的按钮）。
    on_click:
      - logger.log:
          format: "Matrix button clicked: %d, is button_2 = %u"
          args: ["x", "id(button_2) == x"]

TIP

按钮矩阵组件支持 Key collector 组件，可将按钮按下收集为按键序列以用于进一步自动化。查看数字输入键盘以获取示例。

`canvas`

画布组件为自定义绘制操作提供表面。它允许你绘制形状、文本、图像并执行像素级操作。所有选项都是可模板化的。需要点列表时，可以以字典列表形式提供（每个字典包含可模板化的 x 和 y 键），或以 x,y 简写对提供（仅限常量整数）。

配置变量：

width（必需，int）：画布的宽度（像素）。
height（必需，int）：画布的高度（像素）。
transparent（可选，boolean）：启用 alpha 通道支持。默认为 false。

操作：

lvgl.canvas.fill 用颜色填充整个画布：
- id（必需）：画布组件的 ID。
- color（必需，color）：填充颜色。
- opa（可选，opacity）：填充的透明度。默认为 COVER。
lvgl.canvas.set_pixels 设置单个像素：
- id（必需）：画布组件的 ID。
- color（必需，color）：像素颜色。
- opa（可选，opacity）：像素的透明度。默认为 COVER。
- points（必需，list）：要设置的点列表，每个点包含：
  - x（必需，int）：X 坐标。
  - y（必需，int）：Y 坐标。
lvgl.canvas.draw_rectangle 绘制矩形：
- id（必需）：画布组件的 ID。
- x（必需，int）：X 坐标。
- y（必需，int）：Y 坐标。
- width（必需，int）：宽度（像素）
- height（必需，int）：高度（像素）
- radius（可选，int）：圆角半径。
- bg_color（可选，color）：背景颜色。
- bg_opa（可选，opacity）：背景透明度。默认为 COVER。
- border_color（可选，color）：边框颜色。
- border_width（可选，int）：边框宽度。
- border_opa（可选，opacity）：边框透明度。默认为 COVER。
- outline_color（可选，color）：轮廓颜色。
- outline_width（可选，int）：轮廓宽度。
- outline_opa（可选，opacity）：轮廓透明度。默认为 COVER。
- outline_pad（可选，int）：轮廓内边距。默认为 0。
- shadow_color（可选，color）：阴影颜色。
- shadow_width（可选，int）：阴影宽度。
- shadow_opa（可选，opacity）：阴影透明度。默认为 COVER。
- shadow_offset_x（可选，int）：阴影 X 偏移。
- shadow_offset_y（可选，int）：阴影 Y 偏移。
- shadow_spread（可选，int）：阴影扩散。
lvgl.canvas.draw_polygon 绘制多边形：
- id（必需）：画布组件的 ID。
- points（必需，list）：构成多边形顶点的点列表。
- 与 lvgl.canvas.draw_rectangle 相同的其他选项。
lvgl.canvas.draw_text 绘制文本：
- id（必需）：画布组件的 ID。
- x（必需，int）：X 坐标。
- y（必需，int）：Y 坐标。
- text（必需，string）：要绘制的文本。
- max_width（必需，int）：最大宽度（像素）。
- align（可选，enum）：文本相对于 x 和 max_width 的对齐方式。可选 LEFT、CENTER、RIGHT、AUTO。
- color（可选，color）：文本颜色。
- opa（可选，opacity）：文本透明度。默认为 COVER。
- font（可选，string）：使用的字体。
- decor（可选，list）：选择文本的装饰：NONE、UNDERLINE、STRIKETHROUGH（可以 YAML 列表形式指定多个）。默认为 NONE。
- letter_space（可选，int16）：文本的额外字符间距。默认为 0。
- line_space（可选，int16）：文本的行间距。默认为 0。
lvgl.canvas.draw_line 绘制线条：
- id（必需）：画布组件的 ID。
- points（必需，list）：构成线条的点列表，每个点包含：
  - x（必需，int）：X 坐标。
  - y（必需，int）：Y 坐标。
- color（可选，color）：线条颜色。
- width（可选，int）：线条宽度。
- opa（可选，opacity）：线条透明度。默认为 COVER。
- round_start（可选，boolean）：将线条起点设为圆角。默认为 false。
- round_end（可选，boolean）：将线条终点设为圆角。默认为 false。
lvgl.canvas.draw_arc 绘制弧线：
- id（必需）：画布组件的 ID。
- x（必需，int）：中心 X 坐标。
- y（必需，int）：中心 Y 坐标。
- radius（必需，int）：弧线半径。
- start_angle（必需，0-360）：起始角度。
- end_angle（必需，0-360）：结束角度。
- color（可选，color）：弧线颜色。
- width（可选，int）：弧线线宽。
- opa（可选，opacity）：弧线透明度。默认为 COVER。
- rounded（可选，boolean）：将弧线起点/终点设为圆角。
lvgl.canvas.draw_image 绘制图像：
- id（必需）：画布组件的 ID。
- x（必需，int）：X 坐标。
- y（必需，int）：Y 坐标。
- src（必需，string）：图像源。
- rotation（可选，0-360）：旋转角度。（已弃用的名称 angle 也可接受。）
- scale（可选，float）：均匀缩放因子 0.1-10.0（默认 1.0）。（已弃用的名称 zoom 也可接受。）
- scale_x（可选，float）：水平缩放因子 0.1-10.0。
- scale_y（可选，float）：垂直缩放因子 0.1-10.0。
- skew_x（可选，0-360）：水平倾斜角度。
- skew_y（可选，0-360）：垂直倾斜角度。
- pivot_x（可选，int）：旋转的 X 轴枢轴点。
- pivot_y（可选，int）：旋转的 Y 轴枢轴点。

# 组件示例：
- canvas:
    id: my_canvas
    align: CENTER
    width: 140
    height: 80
    transparent: false

# 绘制操作示例，带延迟执行：
on_...:
  - lvgl.canvas.fill: # 用灰色填充画布
      id: my_canvas
      color: gray
  - delay: 1s
  - lvgl.canvas.draw_rectangle: # 绘制一个蓝色矩形
      id: my_canvas
      x: 10
      y: 10
      width: 110
      height: 50
      bg_color: blue
  - delay: 1s
  - lvgl.canvas.draw_text: # 绘制一些红色文本
      id: my_canvas
      x: 20
      y: 20
      text: "Hello World"
      max_width: 100
      color: red

`checkbox`

复选框组件内部由复选框和标签组成。点击复选框时，复选框的 checked 状态将被切换。

配置变量：

indicator（可选，list）：指示器部分的设置，用于显示值。支持样式列表和基于状态的样式来自定义。“复选框”是一个使用所有典型背景样式属性的正方形。默认情况下，其大小等于主部分字体的高度。内边距属性在相应方向上使复选框变大。
样式属性中组件背景的样式选项，使用文本和所有典型的背景样式属性。pad_column 调整复选框与标签之间的间距。

操作：

lvgl.checkbox.update 操作根据上述特定选项更新组件样式和属性，就像使用 lvgl.widget.update 操作处理通用样式、状态或标志一样。
- id（必需）：要更新的 checkbox 组件的 ID 或 ID 列表。
- text（可选，Text property）：复选框旁边显示的文本。
- 样式属性中组件背景的样式选项，使用文本和所有典型的背景样式属性。pad_column 调整复选框与标签之间的间距。

触发器：

on_change 触发器在交互切换复选框时激活。表示复选框状态的布尔变量 x 可供此触发器中的 lambda 使用。
on_value 触发器在复选框被切换时激活，无论是用户交互还是编程更改。新值在变量 x 中返回。
on_update 触发器在复选框通过编程切换时激活（例如，通过 lvgl.checkbox.update）。新值在变量 x 中返回。
交互同样在 x 中返回值的 LVGL 事件触发器。

示例：

# 组件示例：
- checkbox:
    align: CENTER
    id: checkbox_id
    text: Checkbox

# 操作示例：
on_...:
  - lvgl.checkbox.update:
      id: checkbox_id
      state:
        checked: true
      text: Checked

# 触发器示例：
- checkbox:
    ...
    on_value:
      - logger.log:
          format: "Checkbox state: %d"
          args: [ x ]

NOTE

如果在主部分将 default_font 配置为自定义字体，则复选框处于选中状态时复选标记将无法正确显示。查看恢复复选框标记以了解如何轻松解决此问题。

checkbox 还可以集成为 Switch 组件。

`container`

container 是一个无样式的组件，顾名思义，旨在作为其他组件的容器。它在功能上与 obj 相同，但没有应用任何样式，因此没有任何样式或组件时是不可见的。其默认宽度和高度为 100%。

配置变量：

样式属性中的样式选项。

触发器：

交互 LVGL 事件触发器。

示例：

# 组件示例：
- container:
    align: CENTER
    outline_width: 1 # 临时设置以查看其位置
    width: 80%
    height: 80%
    widgets:
      - ...

`dropdown`

下拉组件允许用户从列表中选择一个值。

下拉列表默认关闭并显示单个值。激活时（通过点击下拉列表），将绘制一个列表，用户可以从中选择一个选项。当用户选择新值时，列表将从屏幕中删除。

下拉组件内部由按钮部分和列表部分组成（两者都与同名的实际组件无关）。

配置变量：

dir（可选，str）：下拉的列表部分相对于按钮部分创建的位置。LEFT、RIGHT、BOTTOM、TOP，默认为 BOTTOM。
dropdown_list（可选，dict）：包含项的列表的设置。支持样式列表来自定义。值得注意的是 text_line_space 和 pad_all 用于列表项的间距，text_font 用于分别更改列表中的字体。部分 main、scrollbar 和 selected 可以自定义。注意，更改选定项的样式应在 selected 部分中使用 checked 状态完成。max_height 可用于限制列表的高度。
indicator（可选，dict）：下拉符号的样式。
options（必需，list）：下拉列表中可用选项的列表。
selected_index（可选，int8）：你希望选中的项的索引。
selected_text（可选，string）：你希望选中的项的文本。
symbol（可选，dict）：下拉列表中显示符号（通常为下拉箭头）。如果下拉列表的 dir 为 LEFT，符号将显示在左侧，否则显示在右侧。从内置或自定义字体中选择一个不同的符号。
样式属性中按钮背景的样式选项。使用典型的背景属性和 label 文本属性。text_font 可用于设置按钮部分（包括符号）的字体。

操作：

lvgl.dropdown.update 操作根据上述特定选项更新组件样式和属性，就像使用 lvgl.widget.update 操作处理通用样式、状态或标志一样。
- id（必需）：要更新的 dropdown 组件的 ID 或 ID 列表。
- dir（可选，str）：下拉的列表部分相对于按钮部分创建的位置。LEFT、RIGHT、BOTTOM、TOP。
- options（可选，list）：下拉列表中可用选项的列表。
- 上述所有其他配置变量均为可选，且功能与此前描述相同。

触发器：

on_change 触发器仅在用户从列表中选择项时激活。新选定的索引在变量 x 中返回。交互 LVGL 事件触发器也适用，它们也在 x 中返回选定索引。
on_value 触发器在选择更改时激活，无论是用户交互还是编程更改。新值在变量 x 中返回。
on_update 触发器在选择通过编程更改时激活（例如，通过 lvgl.dropdown.update）。新值在变量 x 中返回。
on_cancel 触发器在关闭下拉列表而未从列表中选择项时激活。当前选定的索引在变量 x 中返回。
交互同样在 x 中返回值的 LVGL 事件触发器。

示例：

# 组件示例：
- dropdown:
    id: dropdown_id
    width: 100
    align: CENTER
    y: -40
    options:
      - Violin
      - Piano
      - Bassoon
      - Chello
      - Drums
    selected_index: 2
    dropdown_list:
      selected:
        checked:
          text_color: 0xFF0000

# 操作示例：
on_...:
  - lvgl.dropdown.update:
      id: dropdown_id
      selected_index: 4

# 触发器示例：
- dropdown:
    ...
    on_value:
      - logger.log:
          format: "Selected index is: %d"
          args: [ x ]
    on_cancel:
      - logger.log:
          format: "Dropdown closed. Selected index is: %d"
          args: [ x ]

dropdown 还可以集成为 Select 组件。

`image`

图像是用于显示图像的基本组件。

配置变量：

src（必需）：要显示的图像。可以通过两种方式之一指定：
- 指向现有图像配置的 Image ID。
- Mapping 查找，通过提供具有以下键的字典。引用的映射必须具有 to 类型为 image。
  - mapping（必需，ID）：to 类型为 image 的 mapping 组件的 ID。
  - value（必需，templatable）：在映射中查找的键。
rotation（可选，0-360）：图像的旋转角度。默认为 0.0。（已弃用的名称 angle 也可接受。）
antialias（可选）：旋转或缩放变换的质量。启用抗锯齿时，变换质量更高但速度更慢。默认为 false。
offset_x（可选）：为图像位置添加水平偏移。
offset_y（可选）：为图像位置添加垂直偏移。
pivot_x（可选）：旋转枢轴点的水平位置，以像素为单位，相对于图像的左上角。默认为图像中心。必须与 pivot_y 一起指定。
pivot_y（可选）：旋转枢轴点的垂直位置，以像素为单位，相对于图像的左上角。默认为图像中心。必须与 pivot_x 一起指定。
scale（可选，0.1-10）：图像的缩放。已弃用的名称 zoom 也可接受。
image_recolor（可选，color）：与图像每个像素混合的颜色。注意 image_recolor_opa 默认为 TRANSP，因此也必须设置它。
image_recolor_opa（可选，opacity）：图像重新着色的透明度。
bitmap_mask_src（可选，image）：现有 grayscale 类型图像配置的 ID，用作为此组件创建的层的 A8 位图掩码。
样式属性中背景矩形的某些样式选项，使用典型的背景样式属性，以及图像本身使用图像样式属性。

操作：

lvgl.image.update 操作根据上述特定选项更新组件样式和属性，就像使用 lvgl.widget.update 操作处理通用样式、状态或标志一样。
- id（必需）：要更新的 image 组件的 ID 或 ID 列表。
- 上述所有其他配置变量均为可选，且功能与此前描述相同。更新 src 选项将在运行时更改图像。

触发器：

交互 LVGL 事件触发器。

示例：

# 组件示例：
- image:
    align: CENTER
    src: cat_image
    id: img_id
    radius: 11
    clip_corner: true

# 操作示例：
on_...:
  - lvgl.image.update:
      id: img_id
      src: cat_image_bowtie
  # 通过映射组件查找选择图像
  - lvgl.image.update:
      id: img_id
      src:
        mapping: image_map     # 一个带有 `to: image` 的映射组件
        value: 0               # 字面键；也可以是 lambda

NOTE

当前支持 RGB565 类型图像，透明度通过设置可选参数 transparency 实现。查看图像以了解如何在 ESPHome 中加载图像进行渲染。 [!TIP] 当组件大小设置为小于图像源大小时，offset_x 和 offset_y 可能会有用。可以通过动画化这些值来创建”奔跑图像”效果。

`keyboard`

键盘组件是一种特殊的按钮矩阵，具有预定义的键映射和其他功能，可显示屏幕键盘，用于向 textarea 输入文本。

样式设置方面，keyboard 组件使用与 buttonmatrix 相同的设置。

配置变量：

textarea（可选）：要与键盘关联的 textarea 的 ID。如果提供，所有键输入都将记录在 textarea 中。
mode（可选，enum）：要使用的键盘布局。每个 TEXT_ 布局都包含一个按钮，允许用户在 TEXT_ 布局之间切换。
- TEXT_LOWER：显示小写字母（默认）。
- TEXT_UPPER：显示大写字母。
- TEXT_SPECIAL：显示特殊字符。
- NUMBER：显示数字、+/- 符号和小数点。

操作：

lvgl.keyboard.update 操作更新上述特定选项中的属性，以及来自 lvgl.widget.update 的任何属性。
- id（必需）：要更新的 keyboard 组件的 ID 或 ID 列表。
- mode（可选，enum）：要使用的键盘布局。
- 上述所有其他配置变量均为可选，且功能与此前描述相同。

触发器：

on_ready 触发器在按下复选标记键时激活。
on_cancel 触发器在按下包含键盘图标的键时激活。

示例：

# 组件示例：
- keyboard:
    id: keyboard_id
    textarea: textarea_1
    mode: TEXT_UPPER

# 操作示例：
on_focus:
  - lvgl.keyboard.update:
      id: keyboard_id
      mode: NUMBER
      textarea: textarea_2

# 触发器示例：
- keyboard:
    ...
    on_ready:
      - logger.log: Keyboard is ready
    on_cancel:
      - logger.log: Keyboard cancelled

TIP

键盘组件支持 Key collector 组件，可将按钮按下收集为按键序列以用于进一步自动化。

NOTE

ESPHome 中的键盘组件不支持弹出框或自定义布局。

`label`

标签是用于显示文本的基本组件类型。

配置变量：

text（可选，Text property）：标签上显示的文本。
text_font（可选，font）：用于渲染文本或符号的字体的 ID。从父对象继承。
text_align（可选，enum）：组件中文本的对齐方式——它不对齐对象本身，仅对齐其中的行。当组件 width 设置为不同于文本宽度时生效。可选 LEFT、CENTER、RIGHT、AUTO。从父对象继承。默认为 AUTO，检测文本基本方向并使用左对齐或右对齐。
text_opa（可选，opacity）：文本的透明度。从父对象继承。默认为 COVER。
text_color（可选，color）：渲染文本的颜色。从父对象继承。默认为 0（黑色）。
text_decor（可选，list）：选择文本的装饰：NONE、UNDERLINE、STRIKETHROUGH（可以 YAML 列表形式指定多个）。从父对象继承。默认为 NONE。
text_letter_space（可选，int16）：文本的额外字符间距。从父对象继承。默认为 0。
text_line_space（可选，int16）：文本的行间距。从父对象继承。默认为 0。
long_mode（可选，list）：默认情况下，标签的宽度和高度设置为 SIZE_CONTENT。因此，标签的大小会自动扩展到文本大小。否则，如果明确设置了 width 或 height（或通过布局设置），比标签宽度更宽的行可以根据以下长模式策略进行操作。这些策略可以在文本高度大于标签高度时应用。
- WRAP：换行过长的行。如果高度为 SIZE_CONTENT，标签高度将扩展，否则文本将被裁剪（默认）。
- DOT：用点替换标签右下角的最后 3 个字符。
- SCROLL：如果文本比标签更宽，则水平来回滚动文本。如果更高，则垂直滚动。文本仅在一个方向滚动；水平滚动优先级更高。
- SCROLL_CIRCULAR：如果文本比标签更宽，则持续水平滚动文本。如果更高，则垂直滚动。文本仅在一个方向滚动；水平滚动优先级更高。
- CLIP：简单地裁剪标签外的文本部分。
recolor（可选，boolean）：使用 # 启用文本的内联重新着色。这使得可以通过在要重新着色的文本前加上 #RRGGBB 十六进制颜色代码，后跟一个空格，最后用单个哈希 # 标签关闭来单独设置文本中字符的颜色。例如：Write a #FF0000 red# word。
scrollbar（可选，list）：当文本大于组件大小时显示的滚动条的设置。支持样式列表和基于状态的样式来自定义。
selected（可选，list）：选中文本的样式设置。只能使用 text_color 和 bg_color 样式属性。
样式属性中的样式选项。使用所有典型的背景属性和文本属性。内边距值可用于在文本和背景之间添加空间。

NOTE

换行转义序列由标签组件自动处理。可以使用 \n 进行换行。例如："line1\nline2\n\nline4"。要使换行等转义序列生效，必须用双引号括起字符串。

操作：

lvgl.label.update 操作根据上述特定选项更新组件样式和属性，就像使用 lvgl.widget.update 操作处理通用样式、状态或标志一样。
- id（必需）：要更新的 label 组件的 ID 或 ID 列表。
- text（可选，Text property）：标签上显示的新文本。
- 上述所有其他配置变量均为可选，且功能与此前描述相同。

触发器：

交互 LVGL 事件触发器。

示例：

# 组件示例：
- label:
    align: CENTER
    id: lbl_id
    recolor: true
    text: "#FF0000 write# #00FF00 colored# #0000FF text#"

- label:
    align: TOP_MID
    id: lbl_symbol
    text_font: montserrat_28
    text: "\uF013"

# 操作示例（使用传感器值更新标签）：
on_...:
  - lvgl.label.update:
      id: lbl_id
      text:
        format: "%.0fdBm"
        args: [ 'id(wifi_signal_db).get_state()' ]

label 还可以集成为 Text 或 Text Sensor 组件。

`led`

LED 组件是圆形或矩形组件，其亮度可调。随着亮度降低，颜色会变暗。

配置变量：

brightness（可选，percentage）：LED 颜色的亮度，其中 0% 对应黑色，100% 对应上述颜色的全亮度。
color（可选，color）：组件背景、边框和阴影的颜色。
样式属性中的样式选项，使用所有典型的背景样式属性。

操作：

lvgl.led.update 操作根据上述特定选项更新组件样式和属性，就像使用 lvgl.widget.update 操作处理通用样式、状态或标志一样。
- id（必需）：要更新的 led 组件的 ID 或 ID 列表。
- 上述所有其他配置变量均为可选，且功能与此前描述相同。

触发器：

交互 LVGL 事件触发器。

示例：

# 组件示例：
- led:
    id: led_id
    align: CENTER
    color: 0xFF0000
    brightness: 70%

# 操作示例：
on_...:
  - lvgl.led.update:
      id: led_id
      color: 0x00FF00

led 还可以集成为 Light 组件。

NOTE

如果配置为灯组件，启动时 color 和 brightness 将根据其 restore_mode 设置被灯覆盖。

查看食谱中的数字输入键盘以了解如何从自动化中更改 led 样式属性的示例。

`line`

线条组件能够在一系列点之间绘制直线。点以相对于组件左上角的像素或百分比表示。线条按照在配置中定义它们顺序的点绘制。线条组件可用于绘制像三角形或矩形等简单形状，也可绘制像多边形或锯齿线等更复杂的形状。

配置变量：

line_color（可选，color）：线条的颜色。
line_width（可选，int16）：以像素为单位设置线条的宽度。
points（必需，list）：点坐标的 x, y 对列表（原点从父对象的左上角开始）
line_rounded（可选，boolean）：将线条的端点设为圆角。true 为圆角，false 为垂直线结尾。
line_dash_gap（可选，int16）：以像素为单位设置线条中虚线段之间间隙的宽度。
line_dash_width（可选，int16）：以像素为单位设置线条中虚线段的宽度。
样式属性中的样式选项，所有典型的背景属性和线条样式属性。

默认情况下，线条组件的宽度和高度尺寸设置为 SIZE_CONTENT，这意味着它将自动调整大小以容纳所有点。如果明确设置了大小，线条在组件区域外的部分将被裁剪。明确设置大小还允许你在点列表中使用百分比值。在不设置大小的情况下使用百分比将不会绘制任何有用的内容。

点列表可以以 x, y 形式的常量定义，或以带有 x 和 y 键的字典列表定义。后者允许更复杂的点定义，例如使用 lambda 函数计算坐标。

操作：

lvgl.line.update 操作更新点和任何样式属性。
- id（必需）：要更新的线条的 ID 或 ID 列表。
- points（必需）：如上所述的点列表。

示例：

# 组件示例：
- line:
    width: 100%
    height: 100%
    points:
      - 5%, 5%
      - 70, 70
      - 120, 10
      - x: !lambda return random_uint32() % 100;
        y: !lambda return random_uint32() % 100;
      - 230, 15
    line_width: 8
    line_color: 0x0000FF
    line_rounded: true

`meter`

仪表组件可以非常灵活地可视化数据。它可以使用弧线、指针、刻度、线条和/或标签。

配置变量：

scales（必需，list）：要添加到仪表的刻度列表（任意数量）。
- angle_range（必需）：刻度起始和结束之间的角度。默认为 270。
- indicators（必需，list）：要添加到刻度的指示器列表。每种可以添加多个。它们的值在刻度范围内解释：
  - arc（可选）：为刻度添加背景弧：
    - color：用于绘制弧线的Color。默认为 0（黑色）。
    - start_value：开始绘制弧线的刻度范围值。
    - end_value：结束绘制弧线的刻度范围值。
    - width：弧线宽度（像素）。默认为 4。
    - rounded（可选，boolean）：如果为 true，弧线端点将为圆角。默认为 false。
    - padding：以该数量调整弧线相对于刻度半径的位置（可以为负）。默认为 0。（已弃用的名称 r_mod 也可接受。）
    - opa：弧线的透明度。
  - image（可选）：为刻度添加旋转的指针图像：
    - id：手动指定用于在运行时更新指示器值的 ID。
    - pivot_x：旋转枢轴点的水平位置，以像素为单位，相对于图像的左上角。默认为 0。
    - pivot_y：旋转枢轴点的垂直位置，以像素为单位，相对于图像的左上角。默认为图像的垂直中心。
    - src：现有图像配置的 ID，表示一个指向右侧的指针，如 -o--->。
    - value：启动时要显示的刻度范围值。
    - opa：图像的透明度。默认为 100%。
  - line（可选）：为刻度添加指针线。默认情况下，线的长度与刻度半径相同：
    - color：指针线的 Color。默认为 0（黑色）。
    - id：手动指定用于在运行时更新指示器值的 ID。
    - width：指针线宽度（像素）。默认为 4。
    - length：指针长度，以百分比（如 80%）或像素表示。默认为刻度半径的 100%。（已弃用的名称 r_mod 也可接受。）
    - radial_offset：指针相对于刻度中心的偏移量，以百分比或像素表示。默认为 0。
    - value：启动时要显示的刻度范围值。默认为 0。
    - rounded：将指针线端点设为圆角。true 为圆角，false 为垂直线结尾。
    - dash_width：以像素为单位设置指针线中虚线段的宽度。
    - dash_gap：以像素为单位设置线条中虚线段之间间隙的宽度。
    - opa：指针的透明度。默认为 100%。
  - tick_style（可选）：添加刻度样式修改：
    - width：修改刻度线的 width。
    - color_start：刻度渐变的起始 Color。
    - color_end：刻度渐变的结束 Color。
    - start_value：开始修改刻度的刻度范围值。
    - end_value：结束修改刻度的刻度范围值。
    - local：如果为 true，刻度的颜色将从上述指定的起始和结束值之间的 color_start 淡出到 color_end。如果为 false，color_start 和 color_end 将映射到整个刻度范围（并且在指示器的起始和结束值范围内只能看到该颜色渐变的一部分）。默认为 false。
- draw_ticks_on_top（可选）：如果为 true，刻度及其标签将在指示器上方绘制，否则在指示器下方绘制。默认为 true。
- range_from（必需）：刻度的最小值。默认为 0。
- range_to（必需）：刻度的最大值。默认为 100。
- rotation（可选）：刻度的旋转角度偏移。
- ticks（可选，list）：刻度可以有次要和主要刻度以及主要刻度上的标签。要添加次要刻度：
  - color（可选，color）：绘制刻度的颜色。如果 count 大于 0 则为必需。默认为 0x808080。
  - count（必需）：刻度上的刻度数量。默认为 12，且必须不小于 2。
  - width（可选）：刻度线宽度（像素）。如果 count 大于 0 则为必需。默认为 2。
  - length（可选）：刻度线长度（像素）。如果 count 大于 0 则为必需。默认为 10。
  - radial_offset（可选）：刻度相对于外边缘的径向偏移（像素）。默认为 0。
  - major（可选，list）：如果要显示主要刻度和值标签：
    - width：刻度线宽度（像素）。默认为 5。
    - length：刻度线长度（像素或百分比）。默认为 15%。
    - color：绘制主要刻度的 Color。默认为 0（黑色）。
    - label_gap：标签与刻度的距离，文本与刻度线的值成比例。默认为 4。
    - radial_offset（可选）：主要刻度相对于外边缘的径向偏移（像素）。默认为 0。
    - stride：添加主要刻度时跳过的次要刻度数量。默认为 3。
  - 样式属性中刻度线和标签的样式选项，使用 line 和 label 文本样式属性。
样式属性中仪表背景的样式选项，使用典型的背景属性。
ticks（可选，dict）：刻度部分的样式选项，将使用标准的线条和标签样式应用于刻度线和标签。
indicator（可选，dict）：指示器部分的样式选项，将使用标准的线条和图像样式应用于指针线或图像。在此处应用的背景属性将设置枢轴（仪表中间的圆点）的样式，例如，要隐藏枢轴，请在 indicator 样式中使用 bg_opa: transp。
items（可选，dict）：项部分的设置，将应用于弧线。

NOTE

零度位置在组件的正右方（3 点钟方向），度数从那里顺时针增加。角度在 0 - 360 范围内指定。

操作：

lvgl.indicator.update 操作更新下面的指示器选项。lvgl.widget.update 操作可用于仪表组件的通用样式、状态或标志。
- id（必需）：要更新的指示器的 ID 或 ID 列表。
- start_value（可选）：开始绘制弧线的刻度范围值。
- end_value（可选）：结束绘制弧线的刻度范围值。
- opa（可选）：指示器的透明度。

触发器：

交互 LVGL 事件触发器。

示例：

# 组件示例：
- meter:
    align: CENTER
    pad_all: 3
    scales:
      range_from: -10
      range_to: 40
      angle_range: 240
      rotation: 150
      ticks:
        count: 51
        length: 3
        major:
          stride: 5
          length: 7
          label_gap: 6
      indicators:
        - line:
            id: temperature_needle
            width: 2
            color: 0xFF0000
            length: 90%
        - tick_style:
            start_value: -10
            end_value: 40
            color_start: 0x0000BD
            color_end: 0xBD0000

# 操作示例：
on_...:
  - lvgl.indicator.update:
      id: temperature_needle
      value: 3

查看食谱中的半圆仪表、温度计和模拟时钟以了解如何有效使用此组件的示例。

`msgboxes`

消息框充当弹出窗口。它们由背景容器、标题、可选的关闭按钮、文本和可选按钮组成。

文本将自动分成多行，高度将自动设置以包含文本和按钮。消息框是模态的（在关闭前阻止点击屏幕的其他部分）。

配置变量：

msgboxes（可选，list）：要使用的消息框列表。此选项仅在 LVGL 组件配置的顶层可用。每个列表条目可以具有以下选项：
- title（必需，string）：要显示在消息框顶部的字符串。
- body（可选，dict）：消息框正文的内容：
  - text（可选，Text property）：消息框正文中显示的文本。
  - 样式属性中的样式选项。使用所有典型的背景属性和文本属性。
- buttons（可选，list）：要在消息框底部显示的页脚按钮列表。每个按钮是一个独立的组件（不是按钮矩阵），支持完整的组件样式：
  - text（可选，Text property）：按钮上显示的文本。
  - 任何 button 组件的样式选项和触发器。
- header_buttons（可选，list）：要在消息框标题区域显示的图像按钮列表：
  - src（必需，image）：要显示在标题按钮上的图像的 ID。
  - 任何 button 组件的样式选项和触发器。
- button_style（可选，dict）：已弃用——请直接设置按钮样式。
- close_button（可选，boolean）：控制消息框右上角关闭按钮的存在。默认为 true。

操作：

配置的消息框默认隐藏。可以使用 lvgl.widget.show 和 lvgl.widget.hide 操作分别显示和隐藏它们。

示例：

# 组件示例：
lvgl:
  ...
  msgboxes:
    - id: message_box
      close_button: true
      title: Message box
      body:
        text: "This is a sample message box."
        bg_color: 0x808080
      buttons:
        - id: msgbox_apply
          text: "Apply"
        - id: msgbox_close
          text: "\uF00D"
          on_click:
            - lvgl.widget.hide: message_box

TIP

你可以使用全屏幕尺寸、半透明的 obj 并在其上放置任意子组件来创建更复杂的对话框，默认将 hidden 标志设为 true。对于非模态对话框，只需在其上将 clickable 标志设为 false。

`obj`

基础对象只是一个简单的空组件。默认情况下，它不过是一个圆角矩形：

你可以将其作为其他组件的父容器使用。默认情况下，它捕获触摸。由于 obj 应用了默认样式，如果角色仅仅是分组其他组件，你可以选择使用 container。

配置变量：

样式属性中的样式选项。

触发器：

交互 LVGL 事件触发器。

示例：

# 组件示例：
- obj:
    align: CENTER
    width: 80%
    height: 80%
    widgets:
      - ...

`qrcode`

使用此组件在运行时生成并显示包含字符串的 QR 码。

配置变量：

text（可选，Text property）：要编码在 QR 码中的文本。
size（必需，int16）：设置 QR 码的期望大小（像素）。数据较少的 QR 码较小，但通过整数倍缩放以最好地适应给定大小。
light_color（可选，color）：QR 码浅色区域的颜色。默认为白色。
dark_color（可选，color）：QR 码深色区域的颜色。默认为黑色。
样式属性中的样式选项。

操作：

lvgl.qrcode.update 操作更新组件属性以显示新的 QR 码。
- id（必需）：要更新的 qrcode 组件的 ID。
- text（可选，Text property）：要编码在 QR 码中的新文本。
- size（可选，int16）：QR 码的新大小。
- dark_color（可选，color）：深色区域的新颜色。
- light_color（可选，color）：浅色区域的新颜色。
- 样式属性中的样式选项。

触发器：

交互 LVGL 事件触发器。

示例：

# 组件示例：
- qrcode:
    id: lv_qr
    size: 100
    light_color: whitesmoke
    dark_color: steelblue
    text: esphome.io

# 操作示例：
on_...:
  - lvgl.qrcode.update:
      id: lv_qr
      text: home-assistant.io

`roller`

滚轮允许你通过滚动简单地从列表中选择一个选项。

配置变量：

anim_duration（可选，Time）：当滚轮滚动且没有精确停在某个选项上时，它将在该时间量内自动滚动到最近的合法选项。
mode（可选，enum）：使滚轮循环的选项。NORMAL 或 INFINITE，默认为 NORMAL。
options（必需，list）：滚轮中可用选项的列表。
selected_index（可选，int8）：你希望选中的项的索引。
selected_text（可选，string）：你希望选中的项的文本。
selected（可选，list）：选定的部分的设置，用于显示值。支持样式列表和基于状态的样式来自定义。中间选定选项。除了典型的背景属性外，它还使用 label 文本样式属性来更改选定区域中文本的外观。
visible_row_count（可选，int8）：可见行的数量。
样式属性中的样式选项。滚轮的背景使用所有典型的背景属性和 label 样式属性。text_line_space 调整选项之间的间距。

操作：

lvgl.roller.update 操作根据上述特定选项更新组件样式和属性，就像使用 lvgl.widget.update 操作处理通用样式、状态或标志一样。
id（必需）：要更新的 roller 组件的 ID 或 ID 列表。
animated（可选，boolean）：以动画方式将指示器移动到新的选定值。默认为 true。
上述所有其他滚轮选项。

触发器：

on_change 触发器仅在用户从列表中选择项时激活。新选定的索引在变量 x 中返回。交互 LVGL 事件触发器也适用，它们也在 x 中返回选定索引。
on_value 触发器在选择更改时激活，无论是用户交互还是编程更改。新值在变量 x 中返回。
on_update 触发器在选择通过编程更改时激活（例如，通过 lvgl.roller.update）。新值在变量 x 中返回。
交互同样在 x 中返回选定索引的 LVGL 事件触发器。

示例：

# 组件示例：
- roller:
    align: CENTER
    id: roller_id
    options:
      - Violin
      - Piano
      - Bassoon
      - Chello
      - Drums

# 操作示例：
on_...:
  - lvgl.roller.update:
      id: roller_id
      selected_index: 4

# 触发器示例：
- roller:
    ...
    on_value:
      - logger.log:
          format: "Selected index is: %d, text is: %s"
          args: [x, text.c_str()]

roller 还可以集成为 Select 组件。

`slider`

滑块组件看起来像一个带旋钮的条形。用户可以拖动旋钮来设置值。与条形一样，滑块可以是垂直或水平的。指示器前景的大小和旋钮位置根据滑块的当前 value 设置。

配置变量：

anim_duration（可选，Time）：如果通过 animated: true 设置值，则设置动画时间。
animated（可选，boolean）：在启动时以动画方式将指示器移动到起始值。默认为 true。
indicator（可选，list）：指示器部分的设置，用于显示值。支持样式列表和基于状态的样式来自定义。指示器显示滑块的当前状态。也使用所有典型的背景样式属性。
knob（可选，list）：旋钮部分的设置，用于控制值。支持样式列表和基于状态的样式来自定义。在当前值处绘制一个矩形（或圆形）。也使用所有典型的背景属性来描述旋钮。默认情况下，旋钮是正方形（可选圆角半径），边长等于滑块的较小边。可以使用内边距值使旋钮变大。内边距值可以不对称。
max_value（可选，int8）：指示器的最大值。默认为 100。
min_value（可选，int8）：指示器的最小值。默认为 0。
value（可选，int8）：启动时指示器的实际值，在 min_value - max_value 范围内。默认为 0。
滑块背景的任意样式和基于状态的选项。使用所有典型的背景样式属性。内边距使指示器在相应方向上变小。

通常，滑块可以通过拖动旋钮或点击滑条来调整。在后一种情况下，旋钮移动到点击点，滑块值相应更改。在某些情况下，希望滑块仅在拖动旋钮时响应。可以通过启用 adv_hittest 标志来启用此功能。

如果滑块较窄，可以使用 ext_click_area 样式属性增加其周围的敏感区域，而不影响其视觉效果。

操作：

lvgl.slider.update 操作根据上述特定选项更新组件样式和属性，就像使用 lvgl.widget.update 操作处理通用样式、状态或标志一样。
- id（必需）：要更新的 slider 组件的 ID 或 ID 列表。
- animated（可选，boolean）：以动画方式将指示器移动到新值。默认为 true。
- value（可选，int8）：指示器的新值。
- 滑块背景的任意样式和基于状态的选项。使用所有典型的背景样式属性。内边距使指示器在相应方向上变小。

触发器：

on_value 触发器在滑块值更改时激活，无论是用户交互还是编程更改。新值在变量 x 中返回。
on_change 触发器在滑块值通过用户交互更改时激活。新值在变量 x 中返回。
on_update 触发器在滑块值通过编程更改时激活（例如，通过 lvgl.slider.update）。新值在变量 x 中返回。
交互同样在 x 中返回值的 LVGL 事件触发器。

示例：

# 组件示例：
- slider:
    align: CENTER
    id: slider_id
    value: 75
    min_value: 0
    max_value: 100

# 操作示例：
on_...:
  - lvgl.slider.update:
      id: slider_id
      knob:
        bg_color: 0x00FF00
      value: 55

# 触发器示例：
- slider:
    ...
    on_value:
      - logger.log:
          format: "Slider value is: %.0f"
          args: [ 'x' ]

NOTE

on_value 触发器在拖动滑块或使用按键更改时发送。事件在拖动滑块期间持续发送；这通常会对性能产生负面影响。为缓解此问题，考虑使用像 on_release 这样的通用交互触发器，在交互完成后获取一次 x 变量。

slider 还可以集成为 Number 或 Sensor 组件。

查看灯光亮度滑块和媒体播放器音量滑块以了解如何使用滑块控制 Home Assistant 中实体的示例。

`spinbox`

数字调节器包含一个数值（作为文本），可以通过操作增加或减少。例如，你可以使用带有加号和减号标签的按钮来调用增加或减少值的操作。

配置变量：

anim_duration（可选，Time）：设置光标的闪烁时间。
decimal_places（可选，0..6）：小数点后的位数。如果为 0，则不显示小数点。默认为 0。
digits（可选，1..10）：数字位数（不包括小数分隔符和符号字符）。默认为 4。
range_from（可选，float）：允许将数字调节器设置的最小值。默认为 0。
range_to（可选，float）：允许将数字调节器设置的最大值。默认为 100。
rollover（可选，boolean）：在增加或减少值时，如果启用了此选项，当达到最小值或最大值时，值将更改为另一个极限。如果禁用，值将保持在最小值或最大值。默认为 false。
selected_digit（可选，int）：初始聚焦的数字的序号。默认为 0，表示最低有效位。当调用 increment 或 decrement 操作时，此数字将增加或减少一。
value（可选，float）：启动时数字调节器显示的实际值。默认为 0。

NOTE

仅当设置的范围包含负数时，才显示符号字符。

操作：

lvgl.spinbox.update 操作根据上述特定选项更新组件样式和属性，就像使用 lvgl.widget.update 操作处理通用样式、状态或标志一样。
- id（必需）：要更新的 spinbox 组件的 ID 或 ID 列表。
- value（必需，float）：数字调节器的新值。
lvgl.spinbox.increment 操作将一个 step 增加值（如上配置）。
- id（必需）：要递增的 spinbox 组件的 ID。
lvgl.spinbox.decrement 操作将一个 step 减少值（如上配置）。
- id（必需）：要递减的 spinbox 组件的 ID。

触发器：

on_value 触发器在数字调节器值更改时激活，无论是用户交互还是编程更改。新值在变量 x 中返回。
on_update 触发器在数字调节器值通过编程更改时激活（例如，通过 lvgl.spinbox.update）。新值在变量 x 中返回。
交互同样在 x 中返回值的 LVGL 事件触发器。

示例：

# 组件示例：
- spinbox:
    align: CENTER
    id: spinbox_id
    text_align: CENTER
    range_from: -10
    range_to: 40
    selected_digit: 2
    digits: 3
    decimal_places: 1

# 操作示例：
on_...:
  - lvgl.spinbox.decrement: spinbox_id
on_...:
  - lvgl.spinbox.update:
      id: spinbox_id
      value: 25.5

# 触发器示例：
- spinbox:
    ...
    on_value:
      - logger.log:
          format: "Spinbox value is %f"
          args: [ x ]

spinbox 还可以集成为 Number 或 Sensor 组件。

查看气候控制以了解如何使用数字调节器实现恒温器控制的示例。

`spinner`

Spinner 组件是一个在环形上旋转的弧线。

配置变量：

arc_color（可选，color）：绘制弧线的颜色。
arc_length（可选，0-360）：旋转弧线的角度长度。默认为 200。
arc_opa（可选，opacity）：弧线的透明度。
arc_rounded（可选，boolean）：将弧线端点设为圆角。true 为圆角，false 为垂直线结尾。
arc_width（可选，int16）：以像素为单位设置弧线的宽度。
indicator（可选，list）：指示器部分的设置，用于显示值。支持样式列表和基于状态的样式来自定义。使用弧样式属性绘制另一条弧。其内边距值是相对于背景弧解释的。
spin_time（可选，Time）：旋转一个周期的持续时间。默认为 2s。
样式属性中的样式选项。

操作：

lvgl.spinner.update 操作，就像使用 lvgl.widget.update 操作处理通用样式、状态或标志一样。
- id（必需）：要更新的 spinner 组件的 ID 或 ID 列表。
- 上述和样式属性中的样式选项。

触发器：

交互 LVGL 事件触发器。

示例：

# 组件示例：
- spinner:
    align: CENTER
    spin_time: 2s
    arc_length: 60deg
    id: spinner_id
    indicator:
      arc_color: 0x18bcf2

# 操作示例：
on_...:
  - lvgl.spinner.update:
      id: spinner_id
      spin_time: 500ms
      arc_color: 0x31de70
      indicator:
        arc_color: 0xffbc02

`switch`

开关看起来像一个小的滑块，可用于打开或关闭某些东西。

配置变量：

indicator（可选，list）：指示器部分的设置，即开关处于 checked 状态时显示的旋钮下方前景区域。支持样式列表和基于状态的样式来自定义。
knob（可选，list）：旋钮部分的设置，用于控制值。支持样式列表和基于状态的样式来自定义。
样式属性中的样式选项。

触发器：

on_value 触发器在开关值更改时激活，无论是用户交互还是编程更改。新值在变量 x 中返回。
on_change 触发器在开关值通过用户交互更改时激活。新值在变量 x 中返回。
on_update 触发器在开关值通过编程更改时激活（例如，通过 lvgl.widget.update）。新值在变量 x 中返回。
交互同样在 x 中返回值的 LVGL 事件触发器。

示例：

# 组件示例：
- switch:
    align: CENTER
    id: switch_id

# 触发器示例：
- switch:
    ...
    on_value:
      - logger.log:
          format: "Switch state: %d"
          args: [ x ]

switch 还可以集成为 Switch 组件。

查看本地灯光开关以了解如何使用开关操作本地组件的示例。

`tabview`

选项卡视图对象可用于将内容组织为选项卡。

选项卡按其在配置文件中出现的顺序进行索引（从 0 开始）。可以通过点击选项卡按钮、在内容上水平滑动或通过 lvgl.tabview.select 操作（指定选项卡的索引）来选择新选项卡。

配置变量：

position（可选，enum）：选项卡选择按钮的位置。可选 TOP、BOTTOM、LEFT、RIGHT。默认为 TOP。
size（可选，percentage）：选项卡按钮的高度（在 TOP、BOTTOM 情况下）或宽度（在 LEFT、RIGHT 情况下）。默认为 10%。
tabs（必需，list）：要添加到 tabview 的选项卡列表（任意数量）。
- name（必需）：要显示在对应于选项卡的按钮上的文本。
- id（可选）：选项卡本身的 ID。
- widgets（必需，list）：要在选项卡上作为子组件绘制的组件列表。
tab_style（可选）：选项卡栏的样式设置。
- items（可选，dict）：应用于每个单独选项卡按钮的样式设置。
content_style（可选）：内容区域的样式设置。

操作：

lvgl.tabview.select 操作跳转到目标选项卡：
- id（必需）：接收此操作的 tabview 的 ID。
- index（必需）：要跳转到的选项卡的（从 0 开始的）索引。
- animated（可选，boolean）：为移动设置动画。默认为 false。

触发器：

on_value 触发器在选项卡值更改时激活，无论是用户交互还是编程更改。新选项卡的 ID 在变量 tab 中返回。
on_change 触发器在选项卡值通过用户交互更改时激活。新选项卡的 ID 在变量 tab 中返回。
on_update 触发器在选项卡通过编程更改时激活（例如，通过 lvgl.tabview.select）。新选项卡的 ID 在变量 tab 中返回。
交互 LVGL 事件触发器。

示例：

# 组件示例：
- tabview:
    id: tabview_id
    position: top
    tab_style:
      border_color: 0x18bcf2
      border_width: 3
      height: 40
      items:
        text_color: 0xff0000
    tabs:
      - name: Dog
        id: tabview_tab_1
        widgets:
          - image:
              src: dog_img
          ...
      ...

# 操作示例：
on_...:
  - lvgl.tabview.select:
      id: tabview_id
      index: 1
      animated: true

# 触发器示例：
- tabview:
    ...
    on_value:
      - if:
          condition:
            lambda: return tab == id(tabview_tab_1);
          then:
            - logger.log: "Dog tab is now showing"

`textarea`

文本区域是一个扩展的标签组件，显示光标并允许用户输入文本。长行会换行，当文本足够长时，文本区域可以滚动。它支持单行模式和密码模式，在密码模式中，输入的字符在视觉上被替换为项目符号或星号。

配置变量：

accepted_chars（可选，string）：可以设置一个可接受的字符列表，其他字符将被忽略。
max_length（可选，int）：将字符的最大数量限制为此值。
one_line（可选，boolean）：文本区域可以限制为仅允许单行文本。在这种情况下，高度将自动设置为适应单行，换行符将被忽略，单词换行将被禁用。
password_mode（可选，boolean）：文本区域支持密码模式。默认情况下，如果字体中存在 •（项目符号，0x2022）字形，则输入的字符会在一段时间后或输入新字符时转换为其。如果字体中缺少 •，则将使用 *（星号）。
text（可选，Text property）：文本区域的初始内容。
placeholder_text（可选，Text property）：可以指定占位符文本，当文本区域为空时显示。
文本区域背景的任意样式和基于状态的选项。使用所有典型的背景样式属性和与文本/标签相关的样式属性。

操作：

lvgl.textarea.update 操作更新组件的 text 属性，以替换整个文本内容。
- id（必需）：要更新的 textarea 组件的 ID 或 ID 列表。
- text（可选，Text property）：替换文本区域内容的文本。
- 上述所有其他配置变量均为可选，且功能与此前描述相同。

触发器：

on_value 触发器在每次按键时激活。
on_update 触发器在文本通过编程更改时激活（例如，通过 lvgl.textarea.update）。
on_ready 触发器在 one_line 配置为 true 且收到换行符时激活（键盘上的 Enter/Ready 键）。
交互 LVGL 事件触发器。

对于上述两个触发器，触发时，变量 text（std::string 类型）可供这些触发器中的 lambda 使用，它将包含文本区域的整个内容。

示例：

# 组件示例：
- textarea:
    id: textarea_id
    one_line: true
    placeholder_text: "Enter text here"

# 操作示例：
on_...:
  - lvgl.textarea.update:
      id: textarea_id
      text: "Hello World!"

# 触发器示例：
- textarea:
    ...
    on_value:
      - logger.log:
          format: "Textarea changed to: %s"
          args: [ text.c_str() ]
    on_ready:
      - logger.log:
          format: "Textarea ready: %s"
          args: [ text.c_str() ]

textarea 还可以集成为 Text 或 Text Sensor 组件。

`tileview`

Tileview 是一个容器对象，其元素（称为 tile）可以以网格形式排列。用户可以通过拖动或滑动在 tile 之间导航。可以单独在每个 tile 上禁用任何方向，以不允许从一个 tile 移动到另一个 tile。

如果 tileview 与屏幕同尺寸，用户界面类似于智能手表上的界面。Tileview 有 main 和 scrollbar 部分。

配置变量：

tiles（必需，list）：要添加到 tileview 的 tile 列表（任意数量）。
- column（必需）：tile 在 tileview 网格中的垂直位置。
- row（必需）：tile 在 tileview 网格中的水平位置。
- dir（可选）：通过滑动/拖动启用向给定方向的相邻 tile 移动。可选 LEFT、RIGHT、TOP、BOTTOM、HOR、VER、ALL（一个或多个，作为 YAML 列表）。默认为 ALL。
- id（可选）：与 lvgl.tileview.select 操作一起使用的 tile ID。
- widgets（可选，list）：要在 tile 上作为子组件绘制的组件列表。

操作：

lvgl.tileview.select 操作将 tileview 跳转到目标 tile：
- animated（可选，boolean）：为移动设置动画。默认为 false。
- column（可选）：要跳转到的 tile 的垂直位置。如果不指定 tile_id，则为必需。
- row（可选）：要跳转到的 tile 的水平位置。如果不指定 tile_id，则为必需。
- id（必需）：接收此操作的 tileview 的 ID。
- tile_id（可选）：要跳转到的 tile 的 ID（来自 tileview 内部）。如果不指定 row 和 column，则为必需。

触发器：

on_value 触发器在显示的 tile 更改时激活。新值在变量 tile 中返回，作为当前可见 tile 的 ID。
on_update 触发器在 tile 通过编程更改时激活（例如，通过 lvgl.tileview.select）。新值在变量 tile 中返回。
交互 LVGL 事件触发器。

示例：

# 组件示例：
- tileview:
    id: tiv_id
    tiles:
      - id: cat_tile
        row: 0
        column: 0
        widgets:
          - image:
              src: cat_image
          - ...
      - ...

# 操作示例：
on_...:
  - lvgl.tileview.select:
      id: tiv_id
      tile_id: cat_tile
      animated: true

# 触发器示例：
- tileview:
    ...
    on_value:
      - if:
          condition:
            lambda: return tile == id(cat_tile);
          then:
            - logger.log: "Cat tile is now showing"

操作

如上各部分所述，每种组件类型都支持几个自己独有的操作。此外，还可为所有组件使用几个通用操作，下面进行了概述。

`lvgl.widget.hide` / `lvgl.widget.show` 操作

这些操作是切换任何组件的 hidden 标志的简写。

id（必需）：LVGL 中配置的组件的 ID 或 ID 列表，你希望隐藏或显示它们。

on_...:
  - lvgl.widget.hide: my_label_id                # 单个组件
  - lvgl.widget.show: [my_button_1, my_button_2] # 组件列表
  - delay: 0.5s
  - lvgl.widget.show:
      id: my_label_id
  - lvgl.widget.hide:
      id: [my_button_1, my_button_2]

`lvgl.widget.disable` / `lvgl.widget.enable` 操作

这些操作是切换任何组件的 disabled 状态的简写（控制主题中相应disabled样式集的外观）：

id（必需）：LVGL 中配置的组件的 ID 或 ID 列表，你希望禁用或启用它们。

on_...:
  - lvgl.widget.disable:
      - my_button_1
      - my_button_2

on_...:
  - lvgl.widget.enable:
      - id: my_button_1
      - id: my_button_2

`lvgl.widget.update` 操作

此强大的操作允许即时更改/更新任何组件的通用样式属性、状态（可模板化）或标志。

id（必需）：LVGL 中配置的组件的 ID 或 ID 列表，要更新的组件。
组件的通用样式属性、状态（可模板化）或标志。
layout（可选）：更新组件的布局选项。只能更改布局选项；布局类型和网格结构在组件创建时固定。

# 更新样式（在状态中）示例：
on_...:
  - lvgl.widget.update:
      id: my_button_id
      bg_color: 0xFF0000
      state:
        disabled: true

# 更新标志示例：
on_...:
  - lvgl.widget.update:
      id: my_label_id
      hidden: true

# 更新布局选项示例：
on_...:
  - lvgl.widget.update:
      id: my_container_id
      layout:
        flex_flow: column

查看食谱中的远程灯光按钮以了解如何使用模板更新状态的示例。

`lvgl.widget.redraw` 操作

此操作重绘整个屏幕，或可选地仅重绘选定的组件。它不更改任何组件属性。主要用于从暂停状态恢复 LVGL 后重绘屏幕。

id（可选）：要重绘的 LVGL 中配置的组件的 ID（或 ID 列表）；如果省略，将重绘整个屏幕。
lvgl_id（可选）：要重绘的 LVGL 实例的 ID。

on_...:
  - lvgl.widget.redraw:
      lvgl_id: lvgl1  # 仅配置一个 LVGL 实例时为可选

`lvgl.widget.refresh` 操作

此操作重新评估指定组件配置中所有使用 lambda 指定的属性。这提供了一种使用 lvgl.widget.update 操作（更新指定属性）的替代技术。

id（必需）：要刷新的 LVGL 中配置的组件的 ID（也可以是组件列表）。

仅刷新具有 lambda 的属性。如果组件没有 lambda 属性，将在构建时引发错误。

widgets:
  - label:
      id: label1
      text: !lambda return id(text_sensor).state;

on_...:
  - lvgl.widget.refresh: label1 # 使用 lambda 更新标签文本。

`lvgl.widget.focus` 操作

此操作将输入焦点移动到指定组件。主要用于编码器输入以选择特定组件接收输入事件。它还可以允许焦点冻结在该组件上，或可用于将焦点移动到焦点组中的下一个或上一个组件。

所需的配置选项有几种形式：

id（必需）：要给予焦点的组件的 ID。
freeze（可选，boolean）：如果为 true，将锁定焦点到该组件。
editing（可选，boolean）：设置组件的编辑模式，即编码器旋转将更改组件的值，而不是移动焦点。默认为 false。

或

action（必需）：应为 next、previous、mark 或 restore 之一。
group（可选）：在其中移动焦点的组的 ID。如果未指定，将使用默认组。
freeze（可选，boolean）：如果为 true，将锁定焦点到当前选定的组件。

next 和 previous 操作将在组内将焦点移动到下一个或上一个组件。 mark 操作将保存组内当前获得焦点的组件，并在触发 restore 操作时恢复它。

on_...:
  - lvgl.widget.focus:
      id: my_button
      freeze: true

on_...:
  - lvgl.widget.focus: my_button

on_...:
  - lvgl.widget.focus:
      group: encoder_group
      action: next
      freeze: true

on_...:
  - lvgl.widget.focus: previous

触发器

除某些组件可用的特定触发器（如 on_value）外，以下是可用的完整触发器列表。这些触发器可以附加到任何组件，但仅当组件支持相应事件时才会激活。

输入设备事件

on_press：组件已被按下。
on_pressing：组件正在被按下（按下期间持续发送）。
on_press_lost：组件仍在被按下，但光标/手指从组件上滑开。
on_short_click：组件被短暂按下，然后释放。如果滚动了则不调用。
on_single_click：在短距离和短时间内发送第一次短点击。
on_double_click：在短距离和短时间内发送第二次短点击。
on_triple_click：在短距离和短时间内发送第三次短点击。
on_long_press：组件已被按下至少输入设备配置中指定的 long_press_time。如果滚动了则不调用。
on_long_press_repeat：在 long_press_time 之后，每隔 long_press_repeat_time ms 调用一次。如果滚动了则不调用。
on_click：在释放时调用，如果组件未滚动（不管是否长按）。
on_release：在任何情况下组件被释放时调用。
on_scroll_begin：组件滚动开始。
on_scroll_throw_begin：滚动投掷（动量）开始。
on_scroll_end：组件滚动结束。
on_scroll：组件被滚动。
on_gesture：检测到手势。
on_key：向组件发送按键。
on_rotary：编码器或滚轮被旋转。
on_focus：组件获得焦点。
on_defocus：组件失去焦点。
on_leave：组件失去焦点但仍被选中。
on_hit_test：执行高级命中测试。
on_indev_reset：输入设备已被重置。
on_hover_over：输入设备正悬停在组件上方。
on_hover_leave：输入设备停止悬停在组件上方。
on_swipe_left：检测到向左滑动手势。
on_swipe_right：检测到向右滑动手势。
on_swipe_up：检测到向上滑动手势。
on_swipe_down：检测到向下滑动手势。
on_swipe_top：on_swipe_up 的同义词。
on_swipe_bottom：on_swipe_down 的同义词。

绘制事件

on_cover_check：检查组件是否完全覆盖某个区域。
on_refr_ext_draw_size：获取组件周围所需额外绘制区域（例如，用于阴影）。
on_draw_main_begin：开始主绘制阶段。
on_draw_main：执行主绘制。
on_draw_main_end：完成主绘制阶段。
on_draw_post_begin：开始绘制后阶段（所有子组件绘制完毕时）。
on_draw_post：执行绘制后阶段（所有子组件绘制完毕时）。
on_draw_post_end：完成绘制后阶段（所有子组件绘制完毕时）。
on_draw_task_add：正在添加绘制任务。

特殊事件

on_change：组件的值已更改（即滑块移动）。
on_update：组件的值已通过编程更改（例如，通过 lvgl.*.update 操作）。仅适用于具有值的组件。
on_insert：文本已插入到组件中。
on_refresh：通知组件刷新某些内容。
on_ready：进程已完成。
on_cancel：进程已取消。
on_state_change：组件的状态已更改。

其他事件

on_create：组件正在创建。
on_delete：组件正在删除。
on_child_change：子组件被移除、添加或其大小/位置已更改。
on_child_create：子组件已创建（向所有父对象冒泡）。
on_child_delete：子组件已删除（向所有父对象冒泡）。
on_screen_unload_start：屏幕卸载开始。
on_screen_load_start：屏幕加载开始。
on_screen_load：屏幕已加载。
on_screen_unload：屏幕已卸载。
on_size_change：组件的坐标/大小已更改。
on_style_change：组件的样式已更改。
on_layout_change：由于布局重新计算，子组件的位置已更改。
on_get_self_size：获取组件的内部大小。

元数据

on_all_events：将在发送给组件的任何事件上触发——主要用于调试。

这些触发器可以直接应用于 LVGL 配置中的任何组件。传递给触发器的参数取决于事件类型。这些参数可用于那些触发器中定义的 lambda，包括文本格式参数。

对于具有值的任何组件，其所有触发器都会在参数 x（float）中接收当前组件值。

没有值的任何组件将接收参数 obj，它是一个指向接收事件的组件的 LVGL C 类型 lv_obj_t 的指针。

与触摸事件相关的触发器（on_press、on_release 和 on_pressing）还在参数 point（lv_point_t 类型，包含成员 x 和 y）中接收事件的坐标。

最后，每个触发器都接收一个 event 参数，它是一个指向 LVGL C 类型 lv_event_t 的指针。

页面还有额外的触发器——每个页面可以有一个 on_load 和 on_unload 触发器。它们将在页面分别变为活动或非活动时调用。

# 触发器示例：
- button:
    ...
    on_short_click:
      - lvgl.page.show: main_page
    on_long_press:
      - light.toggle: display_backlight

- slider:
    ...
    on_release:
      - logger.log:
          format: "Slider released at value: %.0f, coordinates: (%d, %d)"
          args: [x, point.x, point.y]
      - light.turn_on:
          id: display_backlight
          transition_length: 0ms
          brightness: !lambda return x / 100;

LVGL Widgets

组件部分

公共属性

组件特定属性

文本属性

组件

animimg

arc

bar

button

buttonmatrix

canvas

checkbox

container

dropdown

image

keyboard

label

led

line

meter

msgboxes

obj

qrcode

roller

slider

spinbox

spinner

switch

tabview

textarea

tileview

操作

lvgl.widget.hide / lvgl.widget.show 操作

lvgl.widget.disable / lvgl.widget.enable 操作

lvgl.widget.update 操作

lvgl.widget.redraw 操作

lvgl.widget.refresh 操作

lvgl.widget.focus 操作

触发器

输入设备事件

绘制事件

特殊事件

其他事件

元数据

参见

`animimg`

`arc`

`bar`

`button`

`buttonmatrix`

`canvas`

`checkbox`

`container`

`dropdown`

`image`

`keyboard`

`label`

`led`

`line`

`meter`

`msgboxes`

`obj`

`qrcode`

`roller`

`slider`

`spinbox`

`spinner`

`switch`

`tabview`

`textarea`

`tileview`

`lvgl.widget.hide` / `lvgl.widget.show` 操作

`lvgl.widget.disable` / `lvgl.widget.enable` 操作

`lvgl.widget.update` 操作

`lvgl.widget.redraw` 操作

`lvgl.widget.refresh` 操作

`lvgl.widget.focus` 操作