Semantics 继承自：Control, BaseControl

为控件树提供语义标注，描述控件的含义和用途。

这些标注会被无障碍工具、搜索引擎和语义分析软件使用，以便更好地理解应用的结构和功能。

示例

import flet as ft


def main(page: ft.Page):
    def handle_gain_accessibility_focus(e: ft.Event[ft.Semantics]):
        print("focus gained")

    def handle_lose_accessibility_focus(e: ft.Event[ft.Semantics]):
        print("focus lost")

    page.add(
        ft.SafeArea(
            content=ft.Column(
                controls=[
                    ft.Semantics(
                        label="Input your occupation",
                        on_did_gain_accessibility_focus=handle_gain_accessibility_focus,
                        on_did_lose_accessibility_focus=handle_lose_accessibility_focus,
                        content=ft.TextField(
                            label="Occupation",
                            hint_text="Use 20 words or less",
                            value="What is your occupation?",
                        ),
                    ),
                    ft.Icon(ft.Icons.SETTINGS, color="#c1c1c1"),
                ]
            ),
        )
    )


if __name__ == "__main__":
    ft.run(main)

属性

名称	类型	默认值	说明
content	Optional[Control]	None	要标注的 Control。
label	Optional[str]	None	content 的文本描述。
expanded	Optional[bool]	None	此子树是否表示某个可以处于「展开」或「折叠」状态的内容。
hidden	Optional[bool]	None	此子树当前是否隐藏。
selected	Optional[bool]	None	此子树是否表示某个可以处于选中或未选中状态的内容，以及它当前处于什么状态。
button	Optional[bool]	None	此子树是否表示一个按钮。
obscured	Optional[bool]	None	value 是否应被遮蔽。
multiline	Optional[bool]	None	value 是否来自一个支持多行文本编辑的字段。
focusable	Optional[bool]	None	该节点是否能够持有输入焦点。
read_only	Optional[bool]	None	此子树是否为只读。
focus	Optional[bool]	None	该节点当前是否持有输入焦点。
slider	Optional[bool]	None	此子树是否表示一个滑块。
tooltip	Optional[str]	None	该 widget 工具提示的文本描述。
badge	Optional[BadgeValue]	None	待定
toggled	Optional[bool]	None	此子树是否表示一个带有「开启」状态的开关或类似 widget，以及它当前处于什么状态。
max_value_length	Optional[Number]	None	可输入到可编辑文本字段中的最大字符数。
checked	Optional[bool]	None	此子树是否表示一个带有「已勾选」状态的复选框或类似 widget，以及它当前处于什么状态。
value	Optional[str]	None	content 控件 value 的文本描述。
increased_value	Optional[str]	None	语义节点在被增加时表示的值。
decreased_value	Optional[str]	None	语义节点在被减少时表示的值。
hint_text	Optional[str]	None	对 content 控件执行某个操作的结果的简要文本描述。
current_value_length	Optional[int]	None	当前已输入到可编辑文本字段中的字符数。
heading_level	Optional[int]	None	DOM 文档结构中的标题层级。
exclude_semantics	bool	False	是否应排除来自 content 的语义信息。 当为 True 时，只暴露在此 Semantics 包装器上配置的语义。
mixed	Optional[bool]	None	此子树是否表示一个带有「半勾选」状态的复选框或类似控件，以及它当前是否处于该半勾选状态。
container	bool	False	此语义节点是否应引入自己的语义容器。 容器会把其子树的语义归组到一个独立的节点中，而不是始终与周围的语义合并。
live_region	Optional[bool]	None	此子树是否应被视为实时区域（live region）。
textfield	Optional[bool]	None	此子树是否表示一个文本字段。
link	Optional[bool]	None	此子树是否表示一个链接。
header	Optional[bool]	None	此子树是否表示一个页眉。
image	Optional[bool]	None	该节点是否表示一张图片。
expand	Annotated[Optional[Union[bool, int]], V.instance_of((bool, int))]	None	指定此控件是否／如何扩展以填满父布局中的可用空间。 更多信息见此处。 注意： 仅当此控件的直接父级是以下控件或其子类时才生效：Column、Row、View、Page。 抛出异常： ValueError：如果它不是 bool 或 int 类型。
expand_loose	bool	False	允许控件在主轴方向有可用空间时扩展，但不要求它填满所有可用空间。 更多信息见此处。 注意： 如果 expand_loose 为 True，则仅在以下条件满足时才生效： - expand 不为 None，且 - 此控件的直接父级是以下控件或其子类之一：Column、Row、View、Page。
col	ResponsiveNumber	12	如果此控件的父级是 ResponsiveRow，则此属性决定该控件在屏幕上跨越多少虚拟列。 可以是一个数字，也可以是一个按断点配置不同值的字典，例如 col={"sm": 6}。 值为 0 时会在该断点隐藏控件，因此它不会占用父级 ResponsiveRow 中的任何列。 此控件默认跨越 12 个虚拟列。 | 断点 | 尺寸 | |---|---| | xs | <576px | | sm | ≥576px | | md | ≥768px | | lg | ≥992px | | xl | ≥1200px | | xxl | ≥1400px |
opacity	Annotated[Number, V.between(0.0, 1.0)]	1.0	定义控件的透明度。 取值范围从 0.0（完全透明）到 1.0（完全不透明，无任何透明感）。 抛出异常： ValueError：如果它不在 0.0 到 1.0（含）之间。
visible	bool	True	每个控件都有 visible 属性，默认为 True —— 控件会渲染在页面上。将 visible 设为 False 会彻底阻止控件（及其所有子控件，如果有）渲染到页面画布上。隐藏的控件无法通过键盘或鼠标获得焦点或选中，也不会触发任何事件。
disabled	bool	False	每个控件都有 disabled 属性，默认为 False —— 控件及其所有子控件都处于启用状态。 注意： 此属性的值会递归向下传播到所有子控件。 示例： 例如，如果你有一个包含多个输入控件的表单，可以通过禁用容器来一并禁用它们： python ft.Column( disabled = True, controls=[ ft.TextField(), ft.TextField() ] )
rtl	bool	False	控件的文本方向是否为从右到左（RTL）。
data	Any	skip_	任意类型的自定义数据。
key	Optional['KeyValue']	None	用于在更新之间保持控件标识稳定的键。

只读属性

名称	类型	默认值	说明
parent	Optional['BaseControl']	—	此控件的直接祖先（父级）。 默认为 None，只有在此控件被挂载（加入页面树）后才有值。 Page 控件（页面树的根）是个例外 —— 它的 parent 始终为 None。
page	'Page'	—	此控件所属的页面。

事件

名称	类型	默认值	说明
on_tap_hint_text	Optional[str]	None	描述用户激活 on_tap 时会发生什么的提示。 辅助技术可以将它与 hint_text 一起播报，使点击操作更具体。
on_long_press_hint_text	Optional[str]	None	描述用户激活 on_long_press 时会发生什么的提示。
on_tap	Optional[ControlEventHandler['Semantics']]	None	当此控件被点击时调用。
on_double_tap	Optional[ControlEventHandler['Semantics']]	None	为语义双击操作预留。 警告： 此事件当前运行时实现尚未接线，在该控件实现加入支持之前不会触发。
on_increase	Optional[ControlEventHandler['Semantics']]	None	当语义节点所表示的值被增加时调用。
on_decrease	Optional[ControlEventHandler['Semantics']]	None	当语义节点所表示的值被减少时调用。
on_dismiss	Optional[ControlEventHandler['Semantics']]	None	当该节点被关闭（dismiss）时调用。
on_scroll_left	Optional[ControlEventHandler['Semantics']]	None	当用户在屏幕上从右向左移动手指时调用。
on_scroll_right	Optional[ControlEventHandler['Semantics']]	None	当用户在屏幕上从左向右移动手指时调用。
on_scroll_up	Optional[ControlEventHandler['Semantics']]	None	当用户在屏幕上从下向上移动手指时调用。
on_scroll_down	Optional[ControlEventHandler['Semantics']]	None	当用户在屏幕上从上向下移动手指时调用。
on_copy	Optional[ControlEventHandler['Semantics']]	None	当当前选区被复制到剪贴板时调用。
on_cut	Optional[ControlEventHandler['Semantics']]	None	当当前选区被剪切到剪贴板时调用。
on_paste	Optional[ControlEventHandler['Semantics']]	None	当剪贴板的当前内容被粘贴时调用。
on_long_press	Optional[ControlEventHandler['Semantics']]	None	当该节点被长按时调用（用手指按压并保持屏幕数秒而不移动）。
on_move_cursor_forward_by_character	Optional[ControlEventHandler['Semantics']]	None	当光标向前移动一个字符时调用。
on_move_cursor_backward_by_character	Optional[ControlEventHandler['Semantics']]	None	当光标向后移动一个字符时调用。
on_did_gain_accessibility_focus	Optional[ControlEventHandler['Semantics']]	None	当该节点获得无障碍焦点时调用。
on_did_lose_accessibility_focus	Optional[ControlEventHandler['Semantics']]	None	当该节点失去无障碍焦点时调用。
on_set_text	Optional[ControlEventHandler['Semantics']]	None	当用户想用新文本替换文本字段中的当前文本时调用。 语音访问用户可以在 Android 设备上说出「type <text>」来触发此处理器。

方法

名称	类型	默认值	说明
is_isolated	—	—	返回此控件是否被标记为隔离。 隔离控件会被排除在父级驱动的更新遍历之外，并需要自行管理更新边界。
init	—	—	在控件实例初始化之后、第一次 build / 更新循环之前调用。 重写此钩子以执行依赖于已初始化字段的轻量级设置。不要在此处调用 update()。
build	—	—	在控件初始化期间调用一次，用于定义其子控件。在此方法中 page 属性可用。
before_update	—	—	每当此控件被更新时都会调用此方法。 注意： 务必不要在此处调用或请求 update()。
before_event	—	—	在事件处理器执行之前拦截事件。 返回 False 可取消分发。返回 True 或 None 则继续正常的事件处理。
did_mount	—	—	在控件挂载到页面树之后调用。 重写此方法以启动需要已挂载页面的资源，例如订阅、定时器或服务监听器。
will_unmount	—	—	在控件从页面树移除之前调用。 重写此方法以释放 did_mount() 中创建的资源，例如订阅、定时器或外部句柄。
get_data_channel	—	—	解析为此 widget 在 Dart 侧分配的 [DataChannel]。模式： on_data_channel_open: Optional[ft.EventHandler[DataChannelOpenEvent]] = None def init(self): self.on_data_channel_open = self._on_open def _on_open(self, e): self._channel = self.get_data_channel(e.channel_id) 幂等 —— 底层的 Connection 会按 id 缓存 DataChannel，因此重复调用会返回同一实例。没有错误路径：该 id 始终来自框架触发的事件，所以当此方法运行时，通道在两端都已存在。
update	None	—	为此控件请求一次 UI 更新。 在更改控件状态或属性后调用。控件必须已挂载到页面且未被标记为冻结。