ScrollableControl 继承自： Control, BaseControl

为暴露可滚动视口的控件提供共享的滚动行为。

这个 mixin 风格的控件被 Column、Row、ResponsiveRow、View、ListView 和 GridView 等控件继承，它提供了一套通用 API：

• 通过 scroll 启用／禁用滚动以及滚动条可见性；
• 通过 on_scroll 和 scroll_interval 接收节流的滚动通知；
• 通过 scroll_to 以命令式方式改变位置。

属性

名称	类型	默认值	说明
scroll	Optional[Union[ScrollMode, Scrollbar]]	None	Defines the scroll bar configuration of this control. Can be a Scrollbar instance for full control over the appearance of the scrollbar, or a ScrollMode value, for ready-made scrollbar behaviors.
auto_scroll	bool	False	Whether to automatically move the scroll position to the end when the content changes. This keeps the view pinned to the end as new children are added and as existing content grows in place (e.g. text streamed into an existing child). Pinning is suspended while the user has scrolled away from the end, and resumes once they scroll back. Note: Must be False for scroll_to method to work.
auto_scroll_animation	Optional[AnimationValue]	None	Animation used when auto_scroll moves the view to the end. Accepts an Animation (duration + curve), an int duration in milliseconds, or True. Defaults to a 1 second ease animation; set a duration of 0 for an instant jump (recommended when following fast, token-by-token streaming so the view stays tightly pinned).
scroll_interval	Number	10	Throttling in milliseconds for on_scroll event.
expand	Annotated[Optional[Union[bool, int]], V.instance_of((bool, int))]	None	指定此控件是否/如何扩展以填充父布局中的可用空间。 详见 此处. Note: Has effect only if the direct parent of this control is one of the following controls, or their subclasses: Column, Row, View, Page. Raises: ValueError: If it is not of type bool or int.
expand_loose	bool	False	允许控件在主轴方向上有可用空间时扩展，但不要求填满所有可用空间。 详见 此处. Note: 若 expand_loose 为 True，则仅当同时满足以下条件时生效： - expand 不为 None，且 - the direct parent of this control is one of the following controls, or their subclasses: Column, Row, View, Page.
col	ResponsiveNumber	12	若此控件的父控件是 ResponsiveRow，此属性用于决定该控件横跨多少个虚拟列。 可以是数字，也可以是为不同断点配置不同值的字典，例如 col={"sm": 6}。 0 表示在该断点下隐藏控件，不占用任何列。 默认横跨 12 个虚拟列。 \
opacity	Annotated[Number, V.between(0.0, 1.0)]	1.0	定义控件的透明度，取值范围 0.0（完全透明）到 1.0（完全不透明）。 抛出异常：ValueError：若不在 0.0 到 1.0 的闭区间内。
tooltip	Optional[TooltipValue]	None	鼠标悬停时显示的 tooltip。
badge	Optional[BadgeValue]	None	显示在控件顶部的徽标。
visible	bool	True	Every control has visible property which is True by default - control is rendered on the page. Setting visible to False 完全阻止该控件（及其所有子控件）渲染到页面画布上. 隐藏的控件不能通过键盘或鼠标聚焦或选中，也不会触发任何事件。
disabled	bool	False	Every control has disabled property which is False by default - control and all its children are enabled. Note: The value of this property will be propagated down to all children controls recursively. Example: For example, if you have a form with multiple entry controls you can disable them all together by disabling container: python ft.Column( disabled = True, controls=[ ft.TextField(), ft.TextField() ] )
rtl	bool	False	控件的文字方向是否为从右到左（RTL）。
data	Any	skip_	任意类型的自定义数据。
key	Optional['KeyValue']	None	用于在更新之间保持控件身份稳定的 key。

只读属性

名称	类型	默认值	说明
parent	Optional['BaseControl']	—	The direct ancestor(parent) of this control. It defaults to None and will only have a value when this control is mounted (added to the page tree). Page 控件（树的根）为例外 —— 它始终 parent=None。
page	'Page'	—	此控件所属的页面。

事件

名称	类型	默认值	说明
on_scroll	Optional[EventHandler[OnScrollEvent]]	None	Called when scroll position is changed by a user.

方法

名称	类型	默认值	说明
scroll_to	—	—	Moves the scroll position. Args: offset: Absolute scroll target in pixels. A negative value is interpreted relative to the end (e.g. -1 to jump to the very end). delta: Relative scroll change in pixels. Positive values scroll forward, negative values scroll backward. scroll_key: Key of the target control to scroll to. duration: The scroll animation duration. curve: The scroll animation curve. Notes: - Exactly one of offset, delta or scroll_key should be provided. - auto_scroll must be False. - This method is ineffective for controls (e.g. ListView, GridView) that build items dynamically. Examples: python await products.scroll_to(offset=100, duration=1000) await products.scroll_to(offset=-1, duration=1000) # to the end await products.scroll_to(delta=50) # forward 50px await products.scroll_to(scroll_key="item_20", duration=500)
is_isolated	—	—	Return whether this control is marked as isolated. 被隔离的控件不会参与父级驱动的更新遍历，需要自行管理更新边界。
init	—	—	Called after control instance initialization and before the first build / update cycle. 可重写此钩子执行依赖于已初始化字段的轻量设置。 不要在这里调用 update()。
build	—	—	在控件初始化期间调用一次，用于定义其子控件。 page 属性在此方法中可用。
before_update	—	—	每次控件即将更新时调用。 Note: 不要在此处调用 update()。
before_event	—	—	在事件处理器执行前拦截事件。 返回 False 取消分发，返回 True 或 None 则继续正常的事件处理。
did_mount	—	—	在控件挂载到页面树之后调用。 可重写以启动需要已挂载页面的资源，例如订阅、定时器或服务监听。
will_unmount	—	—	在控件从页面树移除之前调用。 可重写以释放 did_mount() 中创建的资源，例如订阅、定时器或外部句柄。
get_data_channel	—	—	Resolve the [DataChannel] allocated on the Dart side for this widget. Pattern: 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) Idempotent — the underlying Connection caches DataChannels by id, so repeated calls return the same instance. No error path: the id always comes from a framework-fired event, so by the time this runs the channel exists on both sides.
update	None	—	请求更新该控件的 UI。 在修改控件状态或属性后调用。 控件必须已挂载到页面，并且未被冻结。