LVGL Widgets

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

Widgets 可以有子 widgets，子 widgets 可以是任何其他 widgets。可以将其视为嵌套结构。子 widgets 随父 widget 移动，如果父 widget 被隐藏，其子 widgets 也会被隐藏。

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

通用属性

以下属性对所有 widgets 通用。

配置变量：

id (可选, ID): 手动指定用于代码生成的 ID。
x (可选, int16 或百分比): widget 的水平位置。
y (可选, int16 或百分比): widget 的垂直位置。

NOTE

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

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

height (可选): widget 的高度（像素或百分比），或 SIZE_CONTENT。
width (可选): widget 的宽度（像素或百分比），或 SIZE_CONTENT。

NOTE

大小设置支持一个特殊值：SIZE_CONTENT。这意味着 widget 在相应方向的大小将设置为其子 widgets 的大小。请注意，只会考虑右侧和底部的子 widgets，顶部和左侧的子 widgets 保持裁剪。此限制使行为更可预测。带有 hidden 或 floating 标志的 widgets 将被 SIZE_CONTENT 计算忽略。

类似于 CSS，LVGL 也支持 min_width、max_width、min_height 和 max_height。这些是限制 widget 大小不能小于/大于这些值的限制。当大小通过百分比或 SIZE_CONTENT 设置时特别有用。

min_width, max_width, min_height, max_height (可选, int16 或百分比): 设置最小/最大宽度或最小/最大高度。可以使用像素和百分比值。百分比值相对于父级内容区域的尺寸。默认为 0%。
scrollbar_mode (可选, 字符串): 如果子 widget 在其父内容区域（不含内边距的大小）之外，父级可以变得可滚动（参见 scrollable 标志）。widget 可以水平或垂直一次性滚动。滚动条根据设置显示：
- "OFF" : 从不显示滚动条（使用双引号！）。
- "ON" : 始终显示滚动条（使用双引号！）。
- "ACTIVE" : 当 widget 正在滚动时显示滚动条。
- "AUTO" : 当内容足够大可以滚动时显示滚动条（默认）。
scroll_dir (可选, 字符串): 设置对象允许的滚动方向 - LEFT、RIGHT、BOTTOM、TOP、HOR、VER、ALL 之一（默认）。
scroll_snap_x (可选, 字符串): 对于可滚动对象的子对象，此属性定义子对象在 X 方向的吸附位置。NONE（默认）、START、END、CENTER 之一。
scroll_snap_y (可选, 字符串): 对于可滚动对象的子对象，此属性定义子对象在 Y 方向的吸附位置。NONE（默认）、START、END、CENTER 之一。
align (可选, 枚举): widget 相对于父级的对齐方式。子 widget 被裁剪到其父级边界。不以此 OUT_ 开头的值之一（见下图）。
align_to (可选, 列表): widget 相对于同一级别上另一个 widget 的对齐方式：
- id (必填): 您要对齐到的 widget 的 ID。
- align (必填, 字符串): 所需的对齐方式（以 OUT_ 开头的值之一）。
- x (可选, int16 或百分比): 水平偏移位置。默认 0。
- y (可选, int16 或百分比): 垂直偏移位置。默认 0。

group (可选, 字符串): 将与旋转编码器交互的 widgets 组名称。每个组中始终有一个获得焦点的 widget 接收编码器动作。您需要将输入设备与组关联。一个输入设备只能向一个组发送按键事件，但一个组可以从多个输入设备接收数据。如果没有为 widget 或编码器指定组，将分配一个未命名的默认组，因此在大多数只使用一个编码器的情况下，不需要显式指定组。
layout (可选): 详见布局。默认为 NONE。
styles (可选, ID): 主组件配置中的样式定义 ID，用于覆盖主题样式。
theme (可选, 列表): 要应用到 widget 及其子 widgets 的样式列表。与主组件的配置选项相同。
widgets (可选, 列表): 要作为此 widget 的子 widgets 绘制的 LVGL widgets 列表。与主组件的配置选项相同。

state (可选, 字典): Widgets 或其（子）部件可以有状态，支持单独设置样式。这些状态样式从主题继承，但可以在样式定义中本地设置或覆盖。可以是以下之一：
- checked (可选, 布尔值): 切换或选中状态。
- disabled (可选, 布尔值): 禁用状态（也可用于简写动作 lvgl.widget.enable 和 lvgl.widget.disable）。
- edited (可选, 布尔值): 通过编码器编辑。
- focus_key (可选, 布尔值): 通过键盘或编码器获得焦点，但不是通过触摸屏。
- focused (可选, 布尔值): 通过键盘或编码器获得焦点或通过触摸屏点击。
- pressed (可选, 布尔值): 正在被按下。
- scrolled (可选, 布尔值): 正在被滚动。
- user_1, user_2, user_3, user_4 (可选, 布尔值): 自定义状态。

默认情况下，所有状态都是 false，并且它们是可模板化的。要将样式应用到状态，您需要在上一级指定它们，例如：

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

状态本身可以通过与 widget 交互来更改，或通过 lvgl.widget.update 动作更改。

请参阅 Cover 状态和控制获取一个示例，演示如何使用样式和属性来显示 Home Assistant 实体的不同状态。

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

adv_hittest (可选, 布尔值): 允许执行更精确的命中（点击）测试。例如，可能有助于考虑圆角。
checkable (可选, 布尔值): 点击 widget 时切换选中状态。
click_focusable (可选, 布尔值): 点击时为 widget 添加获得焦点状态。
clickable (可选, 布尔值): 使 widget 可被输入设备点击。默认为 true。如果为 false，它将把点击传递给它后面的 widgets（点击穿透）。
event_bubble (可选, 布尔值): 将事件传播到父级。
floating (可选, 布尔值): 当父级滚动时不滚动 widget 并忽略布局。
gesture_bubble (可选, 布尔值): 将手势传播到父级。
hidden (可选, 布尔值): 使 widget 隐藏（就像它不存在一样），也可用于简写动作 lvgl.widget.show 和 lvgl.widget.hide。隐藏的对象在布局计算中被忽略。默认为 false。
ignore_layout (可选, 布尔值): widget 被布局简单忽略。其坐标可以照常设置。
layout_1, layout_2 (可选, 布尔值): 自定义标志，布局可自由使用。
overflow_visible (可选, 布尔值): 不将子内容裁剪到父级边界。
press_lock (可选, 布尔值): 即使按压从 widget 滑开，也保持 widget 按下状态。
scroll_chain simple (可选, 布尔值): (scroll_chain_hor | scroll_chain_ver) 的打包。
scroll_chain_hor (可选, 布尔值): 允许将水平滚动传播到父级。
scroll_chain_ver (可选, 布尔值): 允许将垂直滚动传播到父级。
scroll_elastic (可选, 布尔值): 允许在内部以较慢速度滚动。
scroll_momentum (可选, 布尔值): 使 widget 在”抛出”时滚动更远。
scroll_on_focus (可选, 布尔值): 获得焦点时自动滚动 widget 使其可见。
scroll_one (可选, 布尔值): 只允许在 snappable 子对象上滚动。
scroll_with_arrow (可选, 布尔值): 允许使用方向键滚动获得焦点的 widget。
scrollable (可选, 布尔值): widget 可以变得可滚动。默认为 true（另请参阅 scrollbar_mode 属性）。
snappable (可选, 布尔值): 如果在父级上启用了滚动吸附，它可以吸附到此 widget。
user_1, user_2, user_3, user_4 (可选, 布尔值): 自定义标志，用户可自由使用。
widget_1, widget_2 (可选, 布尔值): 自定义标志，widget 可自由使用。

NOTE

LVGL 只支持整数作为数值 value。可视化 widgets 不能直接显示浮点数，但它们允许按 10 倍缩放。Cookbook 中的一些示例介绍了如何做到这一点。

Widgets 可以有多个部件，每个部件可以独立设置样式。例如，复选框有一个 main 部件用于设置背景和文本标签样式，还有一个 indicator 部件用于设置勾选框样式。所有 widgets 都有一个 main 部件，其他 widget 的可用部件在 widget 描述中指定。

可能的部件有：

main (可选, 字典): widget 的主要部分，即背景。在 widget 顶层应用的任何样式属性都假定为应用于此部件，但也可以在 main 配置键下指定。
scrollbar (可选, 字典): 滚动条样式。
indicator (可选, 字典): widget 的指示器部件。指示器部件可用于显示滑块、条或弧线中的勾选框或其他视觉指示器。
knob (可选, 字典): widget 的旋钮部件，例如滑块、条或弧线中可拖动的项目。
selected (可选, 字典): widget 当前选中的部分，例如文本或滚轮中选中的项目。
items (可选, 字典): widget 的项目部件，例如滚轮中的项目。
ticks (可选, 字典): 仪表刻度上的刻度线。
cursor (可选, 字典): widget 的光标部件，例如数字输入框中的光标。

# 带旋钮和指示器样式的滑块示例
- slider:
    # main（背景）样式
    bg_opa: cover
    bg_grad: color_bar
    radius: 0
    indicator:
      bg_opa: transp    # 使指示器部件不可见
    knob:
      radius: 1
      width: 4
      height: 10%
      bg_color: 0x000000

某些 widgets 具有该 widget 特有的属性。例如 label 有一个 text 属性。widget 特有的属性在下面的每个部分中描述。其中一些属性也可以通过相应的 lvgl.<widget_type>.update 动作更新，例如 lvgl.label.update 允许更新标签的 text 属性以及通用样式属性。

文本属性

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

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

示例：

# 示例标签
- 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"

`animimg`

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

配置变量：

src (必填, 图像列表): 要作为动画帧加载的现有图像配置 ID 列表。
auto_start (可选, 布尔值): 启动时自动开始动画播放。默认为 true。
duration (必填, 时间): 一个播放周期的总持续时间（每帧显示相等的时间）。
repeat_count (可选, int16 或 forever): 播放应重复的次数。默认为 forever。
来自样式属性的一些样式选项，用于使用典型背景样式属性的背景矩形和使用图像样式属性的图像本身。

动作：

lvgl.animimg.start 动作如果动画以 auto_start false 显示或在 repeat_count 到期后，启动动画播放。
- id (必填): 您要启动的 animimg widget 的 ID 或 ID 列表。
lvgl.animimg.stop 动作停止动画播放。
- id (必填): 您要停止的 animimg widget 的 ID 或 ID 列表。
lvgl.animimg.update 动作可用于更改 repeat_count 和 duration，就像 lvgl.widget.update 动作用于通用样式、状态或标志一样。
- id (必填): 要更新的 animimg widget 的 ID 或 ID 列表。
- src (可选, 图像列表): 要作为动画帧加载的现有图像配置 ID 列表。
- auto_start (可选, 布尔值): 更新后自动开始动画播放。默认为 true。
- duration (可选, 时间): 一个播放周期的总持续时间（每帧显示相等的时间）。这将应用于下一个播放循环。
- repeat_count (可选, int16 或 forever): 播放应重复的次数。默认为 forever。
- 来自样式属性的一些样式选项，用于使用典型背景样式属性的背景矩形和使用图像样式属性的图像本身。

触发器：

交互 LVGL 事件触发器。

示例：

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

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

请参阅 Cookbook 中的电池充电动画获取更详细的示例。

`arc`

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

配置变量：

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

如果启用了 adv_hittest 标志，弧线可以在中间点击穿透。只有在背景弧线的环上才能识别点击。

NOTE

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

动作：

lvgl.arc.update 动作从上述特定选项更新 widget 样式和属性，就像 lvgl.widget.update 动作用于通用样式、状态或标志一样。
- id (必填): 要更新的弧线 widget 的 ID 或 ID 列表。
- change_rate (可选, uint16): 新的变化率（度/秒）。
- end_angle (可选, 0-360): 弧线背景的新结束角度。
- max_value (可选, int16): 指示器的新最大值。
- min_value (可选, int16): 指示器的新最小值。
- mode (可选, 字符串): 新的指示器模式。
- rotation (可选, 0-360): 0 度位置的新偏移量。
- start_angle (可选, 0-360): 弧线背景的新起始角度。
- value (可选, int16): 指示器的新值。
- 任何样式和基于状态的选项，用于覆盖从父级继承的样式。弧线的大小和位置将尊重内边距样式属性。

触发器：

on_value 触发器当弧线值更改时激活，无论是通过用户交互还是编程方式。新值在变量 x 中返回。
on_change 触发器当弧线值通过用户交互更改时激活。新值在变量 x 中返回。
交互 LVGL 事件触发器，也在 x 中返回值。

示例：

# 示例 widget：
- arc:
    x: 10
    y: 10
    id: arc_id
    value: 75
    min_value: 0
    max_value: 100
    adjustable: true

# 示例动作：
on_...:
  then:
    - 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 也可以集成为数字或传感器组件。

请参阅灯光亮度滑块和媒体播放器音量滑块获取示例，演示如何使用滑块（或弧线）控制 Home Assistant 中的实体。

`bar`

条形 widget 有一个背景和上面的指示器前景。指示器的大小根据条的当前 value 设置。

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

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

配置变量：

animated (可选, 布尔值): 启动时将指示器动画到起始值。默认为 true。
indicator (可选, int): 指示器部件的设置，用于显示值。支持样式列表和基于状态的样式进行自定义，所有典型背景属性。
max_value (可选, int): 指示器的最大值。默认为 100。
min_value (可选, int): 指示器的最小值。默认为 0。
mode (可选, 字符串): 条的模式。默认为 NORMAL。
- NORMAL：指示器从最小值绘制到当前值。
- RANGE：指示器从起始值绘制到当前值。
- SYMMETRICAL：指示器从中点对称绘制到当前值。
start_value (可选, int): 对于 RANGE 模式，指示器的起始值。默认为 0。
value (可选, int): 指示器末端的值，在 min_value-max_value 范围内。默认为 0。
来自样式属性的样式选项。条的背景使用典型背景样式属性。添加内边距将使指示器变小或变大。

动作：

lvgl.bar.update 动作从上述特定选项更新 widget 样式和属性，就像 lvgl.widget.update 动作用于通用样式、状态或标志一样。
- id (必填): 要更新的条形 widget 的 ID 或 ID 列表。
- 上面列出的任何条形选项。
- 来自样式属性的样式选项。条的背景使用典型背景样式属性。添加内边距将使指示器变小或变大。

触发器：

交互 LVGL 事件触发器。

示例：

# 示例 widget：
- bar:
    x: 10
    y: 100
    id: bar_id
    value: 75
    min_value: 1
    max_value: 100

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

bar 也可以集成为数字或传感器组件。

`button`

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

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

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

配置变量：

checkable (可选, 布尔值): 一个重要的标志，用于制作切换按钮（报告其 checked 状态）。默认为 false。
text (可选, 字符串): 要在按钮上显示的文本。这将创建并向按钮添加单个标签 widget。不能与 widgets: 键一起使用。
来自样式属性的样式选项，用于按钮的背景。使用典型背景样式属性。

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

触发器：

on_change 触发器在点击后激活。如果 checkable 为 true，表示选中状态的布尔变量 x 可以在此触发器内的 lambdas 中使用。
on_value 触发器当选中值更改时激活，无论是通过用户交互还是编程方式。新值在变量 x 中返回。
交互 LVGL 事件触发器。

示例：

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

要创建图像按钮，向其添加子 image widget：

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

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

button 也可以集成为二进制传感器或开关组件。

NOTE

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

请参阅远程灯光按钮获取示例，演示如何使用可选中按钮来操作 Home Assistant 服务。

动作：

lvgl.button.update 动作可用于在运行时更新按钮样式。如果按钮有 text: 选项，也可以用此动作更新。
- id (必填): 要更新的按钮 widget 的 ID 或 ID 列表。
- text (可选, 字符串): 更新按钮的文本（仅当按钮配置了 text: 选项时）。
- 来自样式属性的样式选项，用于按钮的背景。
NOTE

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

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

`buttonmatrix`

按钮矩阵 widget 是一种以行和列显示多个按钮的轻量级方式。它之所以轻量，是因为按钮实际上并没有创建，而只是在运行时绘制。这将每个按钮的内存占用从大约 200 字节（包括按钮及其标签 widget）减少到仅 8 字节。

配置变量：

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

动作：

lvgl.buttonmatrix.update 动作更新特定 state、items 选项中指定的项目样式和属性。
- id (必填): 要更新的按钮矩阵 widget 的 ID 或 ID 列表。
- 来自上面 state、items 选项的 widget 样式或属性，用于更新。
lvgl.matrix.button.update 动作更新特定 control、width 和 selected 选项中指定的按钮样式和属性。
- id (必填): 要更新的矩阵按钮的 ID 或 ID 列表。
- 来自上面 control、width 和 selected 选项的 widget 样式或属性，用于更新。

触发器：

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

示例：

# 示例 widget：
- 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_...:
  then:
    - 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: # 单个按钮的触发器，返回选中状态
            then:
              - 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

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

`canvas`

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

配置变量：

width (必填, int): 画布的宽度（像素）。
height (必填, int): 画布的高度（像素）。
transparent (可选, 布尔值): 启用 alpha 通道支持。默认为 false。

动作：

lvgl.canvas.fill 用颜色填充整个画布：
- id (必填): 画布 widget 的 ID。
- color (必填, 颜色): 填充颜色。
- opa (可选, 不透明度): 填充的不透明度。默认为 COVER。
lvgl.canvas.set_pixels 设置单个像素：
- id (必填): 画布 widget 的 ID。
- color (必填, 颜色): 像素颜色。
- opa (可选, 不透明度): 像素的不透明度。默认为 COVER。
- points (必填, 列表): 要设置的点列表，每个包含：
  - x (必填, int): X 坐标。
  - y (必填, int): Y 坐标。
lvgl.canvas.draw_rectangle 绘制矩形：
- id (必填): 画布 widget 的 ID。
- x (必填, int): X 坐标。
- y (必填, int): Y 坐标。
- width (必填, int): 宽度（像素）
- height (必填, int): 高度（像素）
- radius (可选, int): 圆角半径。
- bg_color (可选, 颜色): 背景颜色。
- bg_opa (可选, 不透明度): 背景不透明度。默认为 COVER。
- border_color (可选, 颜色): 边框颜色。
- border_width (可选, int): 边框宽度。
- border_opa (可选, 不透明度): 边框不透明度。默认为 COVER。
- outline_color (可选, 颜色): 轮廓颜色。
- outline_width (可选, int): 轮廓宽度。
- outline_opa (可选, 不透明度): 轮廓的不透明度。默认为 COVER。
- outline_pad (可选, int): 轮廓的内边距。默认为 0。
- shadow_color (可选, 颜色): 阴影颜色。
- shadow_width (可选, int): 阴影宽度。
- shadow_opa (可选, 不透明度): 阴影的不透明度。默认为 COVER。
- shadow_offset_x (可选, int): 阴影 X 偏移。
- shadow_offset_y (可选, int): 阴影 Y 偏移。
- shadow_spread (可选, int): 阴影扩展。
lvgl.canvas.draw_polygon 绘制多边形：
- id (必填): 画布 widget 的 ID。
- points (必填, 列表): 形成多边形顶点的点列表。
- 其他选项同 lvgl.canvas.draw_rectangle。
lvgl.canvas.draw_text 绘制文本：
- id (必填): 画布 widget 的 ID。
- x (必填, int): X 坐标。
- y (必填, int): Y 坐标。
- text (必填, 字符串): 要绘制的文本。
- max_width (必填, int): 最大宽度（像素）。
- align (可选, 枚举): 文本相对于 x 和 max_width 的对齐方式。LEFT、CENTER、RIGHT、AUTO 之一。
- color (可选, 颜色): 文本颜色。
- opa (可选, 不透明度): 文本不透明度。默认为 COVER。
- font (可选, 字符串): 要使用的字体。
- decor (可选, 列表): 选择文本装饰：NONE、UNDERLINE、STRIKETHROUGH（可以 YAML 列表形式指定多个）。默认为 NONE。
- letter_space (可选, int16): 文本的额外字符间距。默认为 0。
- line_space (可选, int16): 文本的行间距。默认为 0。
lvgl.canvas.draw_line 绘制线条：
- id (必填): 画布 widget 的 ID。
- points (必填, 列表): 形成线条的点列表，每个包含：
  - x (必填, int): X 坐标。
  - y (必填, int): Y 坐标。
- color (可选, 颜色): 线条颜色。
- width (可选, int): 线条宽度。
- opa (可选, 不透明度): 线条不透明度。默认为 COVER。
- round_start (可选, 布尔值): 圆化线条起点。默认为 false。
- round_end (可选, 布尔值): 圆化线条终点。默认为 false。
lvgl.canvas.draw_arc 绘制弧线：
- id (必填): 画布 widget 的 ID。
- x (必填, int): 中心 X 坐标。
- y (必填, int): 中心 Y 坐标。
- radius (必填, int): 弧线半径。
- start_angle (必填, 0-360): 起始角度。
- end_angle (必填, 0-360): 结束角度。
- color (可选, 颜色): 弧线颜色。
- width (可选, int): 弧线线宽。
- opa (可选, 不透明度): 弧线不透明度。默认为 COVER。
- rounded (可选, 布尔值): 圆化弧线的起点/终点。
lvgl.canvas.draw_image 绘制图像：
- id (必填): 画布 widget 的 ID。
- x (必填, int): X 坐标。
- y (必填, int): Y 坐标。
- src (必填, 字符串): 图像源。
- angle (可选, 0-360): 旋转角度。
- zoom (可选, float): 缩放因子 0.1-10.0（默认 1.0）
- pivot_x (可选, int): 旋转的 X 轴点。
- pivot_y (可选, int): 旋转的 Y 轴点。

# 示例 widget：
- canvas:
    id: my_canvas
    width: 240
    height: 240
    transparent: false

# 示例绘图动作，在启动时执行：
    on_boot:
      then:
        # 用白色填充画布
        - lvgl.canvas.fill:
            id: my_canvas
            color: white
        # 绘制蓝色矩形
        - lvgl.canvas.draw_rectangle:
            id: my_canvas
            x: 10
            y: 10
            width: 100
            height: 50
            bg_color: blue
        # 绘制一些红色文本
        - lvgl.canvas.draw_text:
            id: my_canvas
            x: 20
            y: 20
            text: "Hello World"
            max_width: 100
            color: red

`checkbox`

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

配置变量：

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

动作：

lvgl.checkbox.update 动作从上述特定选项更新 widget 样式和属性，就像 lvgl.widget.update 动作用于通用样式、状态或标志一样。
- id (必填): 要更新的复选框 widget 的 ID 或 ID 列表。
- text (可选, 文本属性): 复选框旁显示的文本。
- 来自样式属性的样式选项，用于 widget 的背景，使用文本和所有典型背景样式属性。pad_column 调整勾选框和标签之间的间距。

触发器：

on_change 触发器在交互式切换复选框时激活。表示复选框状态的布尔变量 x 可以在此触发器内的 lambdas 中使用。
on_value 触发器在复选框被切换时激活，无论是通过用户交互还是编程方式。新值在变量 x 中返回。
交互 LVGL 事件触发器，也在 x 中返回值。

示例：

# 示例 widget：
- checkbox:
    x: 10
    y: 10
    id: checkbox_id
    text: Checkbox

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

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

NOTE

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

checkbox 也可以集成为开关组件。

`container`

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

配置变量：

来自样式属性的样式选项。

触发器：

交互 LVGL 事件触发器。

示例：

# 示例 widget：
- container:
    x: 10
    y: 10
    width: 220
    height: 300
    widgets:
      - ...

`dropdown`

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

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

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

配置变量：

dir (可选, str): 下拉列表的列表部件相对于按钮部件的创建位置。LEFT、RIGHT、BOTTOM、TOP，默认为 BOTTOM。
dropdown_list (可选, 字典): 带项目的列表的设置。支持样式列表进行自定义。值得注意的是 text_line_space 和 pad_all 用于列表项目的间距，以及 text_font 用于单独更改列表中的字体。main、scrollbar 和 selected 部件可以自定义。请注意，更改选中项目的样式应在 selected 部件的 checked 状态中进行。max_height 可用于限制列表的高度。
indicator (可选, 字典): 下拉符号的样式。
options (必填, 列表): 下拉列表中的可用选项列表。
selected_index (可选, int8): 您希望选中的项目的索引。
selected_text (可选, 字符串): 您希望选中的项目的文本。
symbol (可选, 字典): 下拉列表中显示一个符号（通常是尖角）。如果下拉列表的 dir 为 LEFT，符号将显示在左侧，否则在右侧。从内置的或您自己的自定义字体中选择不同的符号。
来自样式属性的样式选项，用于按钮的背景。使用典型背景属性和 label 文本属性用于上面的文本。text_font 可用于设置按钮部件的字体，包括符号。

动作：

lvgl.dropdown.update 动作从上述特定选项更新 widget 样式和属性，就像 lvgl.widget.update 动作用于通用样式、状态或标志一样。
- id (必填): 要更新的下拉 widget 的 ID 或 ID 列表。
- dir (可选, str): 下拉列表的列表部件相对于按钮部件的创建位置。LEFT、RIGHT、BOTTOM、TOP。
- options (可选, 列表): 下拉列表中的可用选项列表。
- 所有其他上述配置变量都是可选的，功能与之前描述相同。

触发器：

on_change 触发器仅在用户从列表中选择项目时激活。新选中的索引在变量 x 中返回。交互 LVGL 事件触发器也适用，它们也在 x 中返回选中的索引。
on_value 触发器在选择更改时激活，无论是通过用户交互还是编程方式。新值在变量 x 中返回。
on_cancel 触发器也在您不从列表中选择项目而关闭下拉列表时激活。当前选中的索引在变量 x 中返回。
交互 LVGL 事件触发器，也在 x 中返回值。

示例：

# 示例 widget：
- dropdown:
    id: dropdown_id
    width: 90
    align: CENTER
    options:
      - Violin
      - Piano
      - Bassoon
      - Chello
      - Drums
    selected_index: 2
    dropdown_list:
      selected:
        checked:
          text_color: 0xFF0000

# 示例动作：
on_...:
  then:
    - 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 也可以集成为选择组件。

`image`

图像是用于显示图像的基本 widgets。

配置变量：

src (必填, 图像): 现有图像配置的 ID。
angle (可选, 0-360): 图像的旋转。默认为 0.0。
antialias (可选): 角度或缩放变换的质量。启用抗锯齿时，变换质量更高但速度更慢。默认为 false。
mode (可选): REAL 或 VIRTUAL。使用 VIRTUAL 时，当图像缩放或旋转时，图像对象的实际坐标不会改变。更大的内容简单地溢出对象的边界。这也意味着布局不受变换影响。使用 REAL 时，如果对象的宽度/高度设置为 SIZE_CONTENT，对象的大小将设置为缩放和旋转后的大小。如果设置了显式大小，溢出的内容将被裁剪。默认为 VIRTUAL。
offset_x (可选): 为图像位置添加水平偏移。
offset_y (可选): 为图像位置添加垂直偏移。
pivot_x (可选): 旋转轴点的水平位置（像素），相对于图像左上角。默认为图像中心。必须与 pivot_y 一起指定。
pivot_y (可选): 旋转轴点的垂直位置（像素），相对于图像左上角。默认为图像中心。必须与 pivot_x 一起指定
zoom (可选, 0.1-10): 图像的缩放。
image_recolor (可选, 颜色): 与图像每个像素混合的颜色。请注意 image_recolor_opa 默认为 TRANSP，因此也必须设置。
image_recolor_opa (可选, 不透明度): 图像重新着色的不透明度。
来自样式属性的一些样式选项，用于使用典型背景样式属性的背景矩形和使用图像样式属性的图像本身。

动作：

lvgl.image.update 动作从上述特定选项更新 widget 样式和属性，就像 lvgl.widget.update 动作用于通用样式、状态或标志一样。
- id (必填): 要更新的图像 widget 的 ID 或 ID 列表。
- 所有其他上述配置变量都是可选的，功能与之前描述相同。更新 src 选项会在运行时更改图像。

触发器：

交互 LVGL 事件触发器。

示例：

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

# 示例动作：
on_...:
  then:
    - lvgl.image.update:
        id: img_id
        src: cat_image_bowtie

NOTE

目前支持 RGB565 类型图像，使用可选参数 transparency 设置透明度。请参阅图像了解如何加载图像以在 ESPHome 中渲染。 [!TIP] offset_x 和 offset_y 在 widget 大小设置为小于图像源大小时很有用。可以通过动画这些值创建”跑步图像”效果。

`keyboard`

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

对于样式，keyboard widget 使用与 buttonmatrix 相同的设置。

配置变量：

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

动作：

lvgl.keyboard.update 动作从上述特定选项更新属性，以及 lvgl.widget.update 中的任何选项。
- id (必填): 您要更新的键盘 widget 的 ID 或 ID 列表。
- mode (可选, 枚举): 要使用的键盘布局。
- 所有其他上述配置变量都是可选的，功能与之前描述相同。

触发器：

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

示例：

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

# 示例动作：
on_focus:
  then:
    - lvgl.keyboard.update:
        id: keyboard_id
        mode: number
        textarea: textarea_2

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

TIP

键盘 widget 支持按键收集器组件，将按钮按下作为按键序列收集以进行进一步自动化。

NOTE

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

`label`

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

配置变量：

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

NOTE

换行转义序列由标签 widget 自动处理。您可以使用 \n 进行换行。例如："line1\nline2\n\nline4"。要翻译换行符等转义序列，请将字符串用双引号括起来。

动作：

lvgl.label.update 动作从上述特定选项更新 widget 样式和属性，就像 lvgl.widget.update 动作用于通用样式、状态或标志一样。
- id (必填): 要更新的标签 widget 的 ID 或 ID 列表。
- text (可选, 文本属性): 标签上显示的新文本。
- 所有其他上述配置变量都是可选的，功能与之前描述相同。

触发器：

交互 LVGL 事件触发器。

示例：

# 示例 widget：
- 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_...:
  then:
    - lvgl.label.update:
        id: lbl_id
        text:
          format: "%.0fdBm"
          args: [ 'id(wifi_signal_db).get_state()' ]

label 也可以集成为文本或文本传感器组件。

`led`

LED widgets 是圆形或矩形 widgets，其亮度可以调整。随着亮度降低，颜色变暗。

配置变量：

brightness (可选, 百分比): LED 颜色的亮度，其中 0% 对应黑色，100% 对应上述指定颜色的全亮度。
color (可选, 颜色): widget 的背景、边框和阴影的颜色。
来自样式属性的样式选项，使用所有典型背景样式属性。

动作：

lvgl.led.update 动作从上述特定选项更新 widget 样式和属性，就像 lvgl.widget.update 动作用于通用样式、状态或标志一样。
- id (必填): 要更新的 LED widget 的 ID 或 ID 列表。
- 所有其他上述配置变量都是可选的，功能与之前描述相同。

触发器：

交互 LVGL 事件触发器。

示例：

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

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

led 也可以集成为灯光组件。

NOTE

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

查看 Cookbook 中的数字输入键盘获取示例，演示如何从自动化更改 led 样式属性。

`line`

线条 widget 能够在一组点之间绘制直线。

配置变量：

line_color (可选, 颜色): 线条的颜色。
line_dash_gap (可选, int16): 设置线条中虚线之间间隙的宽度（像素）。
line_dash_width (可选, int16): 设置线条中虚线的宽度（像素）。
line_rounded (可选, 布尔值): 使线条端点圆角。true 圆角，false 垂直线端点。
line_width (可选, int16): 设置线条的宽度（像素）。
points (必填, 列表): 点坐标的 x, y 整数对列表（原点从父级左上角开始）
来自样式属性的样式选项，所有典型背景属性和线条样式属性。

默认情况下，线条 widget 的宽度和高度尺寸设置为 SIZE_CONTENT。这意味着它会自动设置大小以适应所有点。如果显式设置大小，部分线条可能不可见。

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

动作：

lvgl.line.update 动作更新点和任何样式属性。
- id (必填): 要更新的线条的 ID 或 ID 列表。
- points (必填): 如上所述的点列表。

示例：

# 示例 widget：
- line:
    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`

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

配置变量：

scales (必填, 列表): 要添加到仪表的（任意数量的）刻度列表。
- angle_range (必填): 刻度线刻度的起始和结束之间的角度。默认为 270。
- indicators (必填, 列表): 要添加到刻度的指示器列表。每种可以添加多个。它们的值在刻度范围内解释：
  - arc (可选): 添加背景弧线到刻度：
    - color: 绘制弧线的颜色。默认为 0（黑色）。
    - end_value: 刻度范围内结束绘制弧线的值。
    - r_mod: 用此量调整弧线位置与刻度半径的距离（可以为负）。默认为 0。
    - start_value: 刻度范围内开始绘制弧线的值。
    - width: 弧线宽度（像素）。默认为 4。
    - opa: 弧线的不透明度。默认为 100%。
  - image (可选): 添加旋转指针图像到刻度：
    - id: 手动指定用于在运行时更新指示器值的 ID。
    - pivot_x: 旋转轴点的水平位置（像素），相对于图像左上角。
    - pivot_y: 旋转轴点的垂直位置（像素），相对于图像左上角。
    - src: 现有图像配置的 ID，表示指向右侧的指针，如 -o--->。
    - value: 刻度范围内启动时显示的值。
    - opa: 图像的不透明度。默认为 100%。
  - line (可选): 添加指针线到刻度。默认情况下，线的长度与刻度的半径相同：
    - color: 指针线的颜色。默认为 0（黑色）。
    - id: 手动指定用于在运行时更新指示器值的 ID。
    - r_mod: 用此量调整指针长度与刻度半径的距离（可以为负）。默认为 0。
    - value: 刻度范围内启动时显示的值。
    - width: 指针线宽度（像素）。默认为 4。
    - opa: 指针的不透明度。默认为 100%。
  - tick_style (可选): 添加刻度样式修改：
    - color_end: 刻度线渐变末端的颜色。
    - color_start: 刻度线渐变起始的颜色。
    - end_value: 刻度范围内修改刻度线的结束值。
    - local: 如果为 true，刻度线的颜色将在上面指定的起始和结束值之间从 color_start 渐变到 color_end。如果为 false，color_start 和 color_end 将映射到整个刻度范围（只有该颜色渐变的一部分会在指示器的起始和结束值范围内可见）。默认为 false。
    - start_value: 刻度范围内修改刻度线的起始值。
    - width: 修改刻度线的 width。
- range_from (必填): 刻度线刻度的最小值。默认为 0。
- range_to (必填): 刻度线刻度的最大值。默认为 100。
- rotation (可选): 刻度线刻度的旋转角度偏移。
- ticks (必填, 列表): 刻度可以有次刻度线和主刻度线以及主刻度线上的标签。添加次刻度线：
  - color (可选, 颜色): 绘制刻度线的颜色。如果 count 大于 0 则必需。默认为 0x808080。
  - count (必填): 刻度上的刻度线数量。默认为 12。
  - length (可选): 刻度线长度（像素）。如果 count 大于 0 则必需。默认为 10。
  - width (可选): 刻度线宽度（像素）。如果 count 大于 0 则必需。默认为 2。
  - major (可选, 列表): 如果您想显示主刻度线和值标签：
    - color: 绘制主刻度线的颜色。默认为 0（黑色）。
    - label_gap: 标签与刻度线的距离，文本与刻度线的值成比例。默认为 4。
    - length: 刻度线长度（像素或百分比）。默认为 15%。
    - stride: 添加主刻度线时跳过多少次刻度线。默认为 3。
    - width: 刻度线宽度（像素）。默认为 5。
  - 来自样式属性的样式选项，用于刻度线和标签，使用 line 和 label 文本样式属性。
来自样式属性的样式选项，用于仪表的背景，使用典型背景属性。
ticks (可选, 字典): 刻度部件的样式选项，将使用标准线条和标签样式应用于刻度线和标签。
indicator (可选, 字典): 指示器部件的样式选项，将使用标准线条和图像样式应用于指针线或图像。此处应用的背景属性将样式化轴点（仪表中间的点），例如要隐藏轴点，在 indicator 样式中使用 bg_opa: transp。
items (可选, 字典): 项目部件的设置，将应用于弧线。

NOTE

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

动作：

lvgl.indicator.update 动作更新指示器选项如下。lvgl.widget.update 动作用于仪表 widget 的通用样式、状态或标志。
- id (必填): 要更新的指示器的 ID 或 ID 列表。
- end_value (可选): 刻度范围内结束绘制弧线的值。
- start_value (可选): 刻度范围内开始绘制弧线的值。
- opa (可选): 指示器的不透明度。

触发器：

交互 LVGL 事件触发器。

示例：

# 示例 widget：
- meter:
    align: center
    scales:
      range_from: -10
      range_to: 40
      angle_range: 240
      rotation: 150
      ticks:
        count: 51
        length: 3
        major:
          stride: 5
          length: 13
          label_gap: 13
      indicators:
        - line:
            id: temperature_needle
            width: 2
            color: 0xFF0000
            r_mod: -4
        - tick_style:
            start_value: -10
            end_value: 40
            color_start: 0x0000bd #FF0000
            color_end: 0xbd0000 #0000FF

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

请参阅 Cookbook 中的半圆形仪表、温度计和模拟时钟获取示例，演示如何有效使用此 widget。

`msgboxes`

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

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

配置变量：

msgboxes (可选, 列表): 要使用的消息框列表。此选项仅在 LVGL 组件配置的顶层可用。每个列表条目可以有以下选项：
- title (必填, 字符串): 在消息框顶部显示的字符串。
- body (可选, 字典): 消息框正文的内容：
  - text (可选, 文本属性): 在消息框正文中显示的文本。
  - 来自样式属性的样式选项。使用所有典型背景属性和文本属性。
- buttons (可选, 列表): 在消息框底部显示的按钮列表：
  - text (可选, 文本属性): 按钮上显示的文本。
  - 其他按钮选项见 buttonmatrix。
- button_style (可选, 字典): 应用于按钮的样式。使用所有典型样式属性。按钮无法单独设置样式，因为它们是 buttonmatrix 的一部分。
- close_button (可选, 布尔值): 控制消息框右上角关闭按钮的存在。默认为 true

动作：

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

示例：

# 示例 widget：
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:
            then:
              - lvgl.widget.hide: message_box

TIP

您可以使用全屏大小、半透明的 obj 创建自己的更复杂对话框，上面有任意子 widgets，默认设置 hidden 标志为 true。对于非模态对话框，只需在其上设置 clickable 标志为 false。

`obj`

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

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

配置变量：

来自样式属性的样式选项。

触发器：

交互 LVGL 事件触发器。

示例：

# 示例 widget：
- obj:
    x: 10
    y: 10
    width: 220
    height: 300
    widgets:
      - ...

`qrcode`

使用此 widget 在运行时生成并显示包含字符串的二维码。

配置变量：

text (可选, 文本属性): 要编码到二维码中的文本。
size (必填, int16): 设置二维码的所需大小（像素）。数据较少的二维码较小，但它们会按整数倍缩放以最适应给定大小。
light_color (可选, 颜色): 二维码亮区的颜色。默认为白色。
dark_color (可选, 颜色): 二维码暗区的颜色。默认为黑色。
来自样式属性的样式选项。

动作：

lvgl.qrcode.update 动作更新 widget 的 text 属性以显示新的二维码。
- id (必填): 要更新的二维码 widget 的 ID。
- text (可选, 文本属性): 要编码到二维码中的新文本。
- 来自样式属性的样式选项。

触发器：

交互 LVGL 事件触发器。

示例：

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

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

`roller`

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

配置变量：

anim_time (可选, 时间): 当滚轮滚动且未完全停在一个选项上时，它将在此时间内自动滚动到最近的有效选项。
mode (可选, 枚举): 使滚轮循环的选项。NORMAL 或 INFINITE，默认为 NORMAL。
options (必填, 列表): 滚轮中的可用选项列表。
selected_index (可选, int8): 您希望选中的项目的索引。
selected_text (可选, 字符串): 您希望选中的项目的文本。
selected (可选, 列表): 选中部件的设置，用于显示值。支持样式列表和基于状态的样式进行自定义。中间选中的选项。除了典型背景属性外，它使用 label 文本样式属性更改选中区域的文本外观。
visible_row_count (可选, int8): 可见行数。
来自样式属性的样式选项。滚轮的背景使用所有典型背景属性和 label 样式属性。text_line_space 调整选项之间的间距。

动作：

lvgl.roller.update 动作从上述特定选项更新 widget 样式和属性，就像 lvgl.widget.update 动作用于通用样式、状态或标志一样。
id (必填): 要更新的滚轮 widget 的 ID 或 ID 列表。
animated (可选, 布尔值): 将指示器动画到新选中的值。默认为 true。
所有其他上述滚轮选项。

触发器：

on_change 触发器仅在用户从列表中选择项目时激活。新选中的索引在变量 x 中返回。交互 LVGL 事件触发器也适用，它们也在 x 中返回选中的索引。
on_value 触发器在选择更改时激活，无论是通过用户交互还是编程方式。新值在变量 x 中返回。
交互 LVGL 事件触发器，也在 x 中返回选中的索引。

示例：

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

# 示例动作：
on_...:
  then:
    - 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 也可以集成为选择组件。

`slider`

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

配置变量：

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

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

动作：

lvgl.slider.update 动作从上述特定选项更新 widget 样式和属性，就像 lvgl.widget.update 动作用于通用样式、状态或标志一样。
- id (必填): 要更新的滑块 widget 的 ID 或 ID 列表。
- animated (可选, 布尔值): 将指示器动画到新值。默认为 true。
- value (可选, int8): 指示器的新值。
- 任何样式和基于状态的选项，用于滑块的背景。使用所有典型背景样式属性。内边距使指示器在相应方向变小。

触发器：

on_value 触发器当滑块值更改时激活，无论是通过用户交互还是编程方式。新值在变量 x 中返回。
on_change 触发器当滑块值通过用户交互更改时激活。新值在变量 x 中返回。
交互 LVGL 事件触发器，也在 x 中返回值。

示例：

# 示例 widget：
- slider:
    x: 10
    y: 10
    width: 220
    id: slider_id
    value: 75
    min_value: 0
    max_value: 100

# 示例动作：
on_...:
  then:
    - 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 也可以集成为数字或传感器组件。

请参阅灯光亮度滑块和媒体播放器音量滑块获取示例，演示如何使用滑块控制 Home Assistant 中的实体。

`spinbox`

数字输入框包含一个数值（作为文本），可以通过动作增加或减少。例如，您可以使用带有加号和减号标签的按钮来调用按需增加或减少值的动作。

配置变量：

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

NOTE

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

动作：

lvgl.spinbox.update 动作从上述特定选项更新 widget 样式和属性，就像 lvgl.widget.update 动作用于通用样式、状态或标志一样。
- id (必填): 要更新的数字输入框 widget 的 ID 或 ID 列表。
- value (必填, float): 数字输入框的新值。
lvgl.spinbox.increment 动作将值增加上面配置的一个 step。
- id (必填): 您要递增的数字输入框 widget 的 ID。
lvgl.spinbox.decrement 动作将值减少上面配置的一个 step。
- id (必填): 您要递减的数字输入框 widget 的 ID。

触发器：

on_value 触发器当数字输入框值更改时激活，无论是通过用户交互还是编程方式。新值在变量 x 中返回。
交互 LVGL 事件触发器，也在 x 中返回值。

示例：

# 示例 widget：
- spinbox:
    id: spinbox_id
    text_align: center
    range_from: -10
    range_to: 40
    selected_digit: 2
    digits: 3
    decimal_places: 1

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

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

spinbox 也可以集成为数字或传感器组件。

请参阅温控器控制获取示例，演示如何使用数字输入框实现恒温器控制。

`spinner`

旋转器 widget 是环上旋转的弧线。

配置变量：

arc_color (可选, 颜色): 绘制弧线的颜色。
arc_length (必填, 0-360): 旋转弧线的长度（度）。
arc_opa (可选, 不透明度): 弧线的不透明度。
arc_rounded (可选, 布尔值): 使弧线端点圆角。true 圆角，false 垂直线端点。
arc_width (可选, int16): 设置弧线的宽度（像素）。
indicator (可选, 列表): 指示器部件的设置，用于显示值。支持样式列表和基于状态的样式进行自定义。使用弧线样式属性绘制另一条弧线。其内边距值相对于背景弧线解释。
spin_time (必填, 时间): 一次旋转周期的持续时间。
来自样式属性的样式选项。

动作：

lvgl.spinner.update 动作，就像 lvgl.widget.update 动作用于通用样式、状态或标志一样。
- id (必填): 要更新的旋转器 widget 的 ID 或 ID 列表。
- 来自样式属性的样式选项。

触发器：

交互 LVGL 事件触发器。

示例：

# 示例 widget：
- spinner:
    align: center
    spin_time: 2s
    arc_length: 60deg
    id: spinner_id
    indicator:
      arc_color: 0xd4d4d4

# 示例动作：
on_...:
  then:
    - lvgl.spinner.update:
        id: spinner_id
        arc_color: 0x31de70

`switch`

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

配置变量：

indicator (可选, 列表): 指示器部件的设置，当开关处于 checked 状态时旋钮下方的前景区域。支持样式列表和基于状态的样式进行自定义。
knob (可选, 列表): 旋钮部件的设置，用于控制值。支持样式列表和基于状态的样式进行自定义。
来自样式属性的样式选项。

触发器：

on_value 触发器当开关值更改时激活，无论是通过用户交互还是编程方式。新值在变量 x 中返回。
on_change 触发器当开关值通过用户交互更改时激活。新值在变量 x 中返回。
交互 LVGL 事件触发器，也在 x 中返回值。

示例：

# 示例 widget：
- switch:
    x: 10
    y: 10
    id: switch_id

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

switch 也可以集成为开关组件。

请参阅本地灯光开关获取示例，演示如何使用开关操作本地组件。

`tabview`

标签视图对象可用于在标签页中组织内容。标签按钮内部使用 buttonmatrix 生成。

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

配置变量：

position (可选, 枚举): 标签选择按钮的位置。TOP、BOTTOM、LEFT、RIGHT 之一。默认为 TOP。
size (可选, 百分比): 标签按钮的高度（对于 TOP、BOTTOM）或宽度（对于 LEFT、RIGHT）。默认为 10%。
tabs (必填, 列表): 要添加到标签视图的（任意数量的）标签页列表。
- name (必填): 与标签页对应的按钮上显示的文本。
- id (可选): 标签页本身的 ID。
- widgets (必填, 列表): 要作为子 widgets 绘制在标签页上的 Widgets 列表。
tab_style (可选): 标签页的样式设置。
- items (可选, 字典): 项目部件的设置，按钮都使用文本和典型背景样式属性，除了转换和变换。
content_style (可选): 内容区域的样式设置。

动作：

lvgl.tabview.select 动作将视图跳转到所需的标签页：
- id (必填): 接收此动作的标签视图的 ID。
- index (必填): 要跳转到的标签页的（从零开始）索引。
- animated (可选, 布尔值): 是否动画移动。默认为 false。

触发器：

on_value 触发器当标签值更改时激活，无论是通过用户交互还是编程方式。新值在变量 x 中返回。
on_change 触发器当标签值通过用户交互更改时激活。新值在变量 x 中返回。
交互 LVGL 事件触发器。

示例：

# 示例 widget：
- tabview:
    id: tabview_id
    position: top
    tab_style:
      border_color: 0x00FF00
      border_width: 6
      items:
        text_color: 0x0000FF
    tabs:
      - name: Dog
        id: tabview_tab_1
        widgets:
          - image:
              src: dog_img
          ...
      ...

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

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

`textarea`

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

配置变量：

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

动作：

lvgl.textarea.update 动作更新 widget 的 text 属性，替换整个文本内容。
- id (必填): 要更新的文本区域 widget 的 ID 或 ID 列表。
- text (可选, 文本属性): 替换文本区域内容的文本。
- 所有其他上述配置变量都是可选的，功能与之前描述相同。

触发器：

on_value 触发器在每次按键时激活。
on_ready 触发器当 one_line 配置为 true 且收到换行符（键盘上的 Enter/Ready 键）时激活。
交互 LVGL 事件触发器。

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

示例：

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

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

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

textarea 也可以集成为文本或文本传感器组件。

`tileview`

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

如果瓦片视图是屏幕大小的，用户界面类似于您可能在智能手表上看到的。瓦片视图有 main 和 scrollbar 部件。

配置变量：

tiles (必填, 列表): 要添加到瓦片视图的（任意数量的）瓦片列表。
- column (必填): 瓦片在瓦片视图网格中的垂直位置。
- row (必填): 瓦片在瓦片视图网格中的水平位置。
- dir (可选): 通过滑动/拖动启用向相邻瓦片在给定方向移动。LEFT、RIGHT、TOP、BOTTOM、HOR、VER、ALL 之一（或多个作为 YAML 列表）。默认为 ALL。
- id (可选): 用于 lvgl.tileview.select 动作的瓦片 ID。
- widgets (可选, 列表): 要作为子 widgets 绘制在瓦片上的 Widgets 列表。

动作：

lvgl.tileview.select 动作将 tileview 跳转到所需的瓦片：
- animated (可选, 布尔值): 是否动画移动。默认为 false。
- column (可选): 要跳转到的瓦片的垂直位置。如果不指定 tile_id 则必需。
- row (可选): 要跳转到的瓦片的水平位置。如果不指定 tile_id 则必需。
- id (必填): 接收此动作的瓦片视图的 ID。
- tile_id (可选): 要跳转到的瓦片（来自瓦片视图内）的 ID。如果不指定 row 和 column 则必需。

触发器：

on_value 触发器当显示的瓦片更改时激活。新值在变量 tile 中作为现在可见的瓦片的 ID 返回。
交互 LVGL 事件触发器。

示例：

# 示例 widget：
- tileview:
    id: tiv_id
    tiles:
      - id: cat_tile
        row: 0
        column: 0
        dir: VER
        widgets:
          - image:
              src: cat_image
          - ...
      - ...

# 示例动作：
on_...:
  then:
    - 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"

自动化

动作

如上各节所述，每种 widget 类型支持其自己独特的几个动作。还有一些通用动作可用于所有 widgets，下面将概述。

`lvgl.widget.update` 动作

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

id (必填): LVGL 中配置的要更新的 widget 的 ID 或 ID 列表。
widget 的通用样式属性、状态（可模板化）或标志。

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

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

查看 Cookbook 中的远程灯光按钮获取示例，演示如何使用模板更新状态。

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

这些动作是切换任何 widget 的 hidden 标志的简写。

id (必填): 您要隐藏或显示的 LVGL 中配置的 widget 的 ID 或 ID 列表。

on_...:
  then:
    - lvgl.widget.hide: my_label_id                # 单个 widget
    - lvgl.widget.show: [my_button_1, my_button_2] # widget 列表
    - 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` 动作

这些动作是切换任何 widget 的 disabled 状态的简写（控制主题的相应禁用样式集的外观）：

id (必填): 您要禁用或启用的 LVGL 中配置的 widget 的 ID 或 ID 列表。

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

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

触发器

特定触发器如 on_value 和 on_change 可用于某些 widgets；它们在上面各自的章节中描述。一些通用触发器也可用于所有 widgets：

ESPHome 实现以下 LVGL 生成的交互事件作为通用触发器：

on_press：widget 已被按下。
on_long_press：widget 已被按下至少输入设备配置中指定的 long_press_time。如果滚动则不调用。
on_long_press_repeat：在 long_press_time 后每隔 long_press_repeat_time 毫秒调用一次。如果滚动则不调用。
on_short_click：widget 被按下短时间后释放。如果滚动或长按则不调用。
on_click：如果 widget 没有滚动则释放时调用（无论是否长按）。
on_release：widget 释放时每种情况都会调用。
on_scroll_begin：widget 的滚动开始。
on_scroll_end：widget 的滚动结束。
on_scroll：widget 被滚动。
on_focus：widget 获得焦点。
on_defocus：widget 失去焦点。
on_gesture：检测到滑动手势
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_all_events：将在 widget 收到的任何事件时触发 - 这对于调试很有用。

这些触发器可以直接应用于 LVGL 配置中的任何 widget，前提是 widget 本身支持生成此类事件。对于有值的 widgets，触发器在变量 x 中返回当前值；此变量可在这些触发器内定义的 lambdas 中使用。

每个触发器还传递一个 event 参数，它是指向 LVGL C 类型 lv_event_t 的指针。这可在这些触发器内定义的 lambdas 中使用。请参阅 LVGL 文档了解更多信息。

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

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

- slider:
    ...
    on_release:
      then:
        - light.turn_on:
            id: display_backlight
            transition_length: 0ms
            brightness: !lambda return x / 100;

`on_boot`

此触发器在 LVGL 设置完成后触发。它在 lvgl 组件和任何 widget 上可用，可用于执行任何无法通过静态配置完成的 LVGL 相关设置。在 widget 上使用时，它不会专门作用于该 widget，但可用于将与该 widget 相关的动作与其配置放在一起。

LVGL Widgets

通用属性

Widget 部件

Widget 特有属性

文本属性

`animimg`

`arc`

`bar`

`button`

`buttonmatrix`

`canvas`

`checkbox`

`container`

`image`

`keyboard`

`label`

`led`

`line`

`meter`

`msgboxes`

`obj`

`qrcode`

`roller`

`slider`

`spinbox`

`spinner`

`switch`

`tabview`

`textarea`

`tileview`

自动化

动作

`lvgl.widget.update` 动作

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

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

触发器

`on_boot`

另见

LVGL Widgets

通用属性

Widget 部件

Widget 特有属性

文本属性

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.update 动作

lvgl.widget.hide / lvgl.widget.show 动作

lvgl.widget.disable / lvgl.widget.enable 动作

触发器

on_boot

另见

`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.update` 动作

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

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

`on_boot`