滚动视图¶

在 1.0.4 版本加入.

: ScrollView 控件提供了一个可滚动/可平移的视口，该视口在滚动视图的边界框处被裁剪。

备注

使用 RecycleView 来生成大量控件，以便显示许多数据项。

滚动行为¶

ScrollView 仅接受一个子部件，并根据 scroll_x 和 scroll_y 属性对其应用视口/窗口。触摸事件会被分析以判断用户是想滚动还是以其他方式控制子部件：你不能同时进行这两种操作。为了确定交互是否为滚动手势，会使用以下属性：

scroll_distance：最小滚动距离，默认值为20像素。

scroll_timeout：最大时间周期，默认为55毫秒。

如果触摸在 scroll_timeout 时间段内移动了 scroll_distance 像素，则会被识别为滚动手势，并开始平移（滚动/拖动）。如果超时发生，则触摸按下事件将分发给子组件（不进行平移）。

这些设置的默认值可以在配置文件中更改:

[widgets]
scroll_timeout = 250
scroll_distance = 20

在 1.1.1 版本加入: ScrollView 现在在使用鼠标滚轮时，会在 Y 轴方向对滚动进行动画处理。

限制在X轴或Y轴¶

默认情况下，ScrollView允许沿X轴和Y轴两个方向滚动。您可以通过将:attr:`~ScrollView.do_scroll_x`或:attr:`~ScrollView.do_scroll_y`属性设置为False来显式禁用某个轴上的滚动。

管理内容大小与位置¶

ScrollView 管理其子组件位置的方式与 RelativeLayout 类似，但不使用 size_hint。您必须仔细指定内容的 size，以获得所需的滚动/平移效果。

默认情况下，size_hint 为 (1, 1)，因此内容大小将完全适应您的 ScrollView（您将没有内容可滚动）。您必须至少停用子部件的 size_hint 指令之一（x 或 y）才能启用滚动。将 size_hint_min 设置为非 None 值，当 ScrollView 小于最小尺寸时，也会在该维度上启用滚动。

要使其Y轴/垂直方向滚动一个:class:~kivy.uix.gridlayout.GridLayout，请将子部件的宽度设置为ScrollView的宽度（size_hint_x=1），并将size_hint_y属性设置为None:

from kivy.uix.gridlayout import GridLayout
from kivy.uix.button import Button
from kivy.uix.scrollview import ScrollView
from kivy.core.window import Window
from kivy.app import runTouchApp

layout = GridLayout(cols=1, spacing=10, size_hint_y=None)
# Make sure the height is such that there is something to scroll.
layout.bind(minimum_height=layout.setter('height'))
for i in range(100):
    btn = Button(text=str(i), size_hint_y=None, height=40)
    layout.add_widget(btn)
root = ScrollView(size_hint=(1, None), size=(Window.width, Window.height))
root.add_widget(layout)

runTouchApp(root)

Kv 示例：

ScrollView:
    do_scroll_x: False
    do_scroll_y: True

    Label:
        size_hint_y: None
        height: self.texture_size[1]
        text_size: self.width, None
        padding: 10, 10
        text:
            'really some amazing text\n' * 100

滚动过界效果¶

在 1.7.0 版本加入.

当滚动超出 ScrollView 的边界时，它会使用 ScrollEffect 来处理过度滚动。这些效果可以执行诸如回弹、改变透明度或仅阻止超出正常边界的滚动等操作。请注意，复杂的效果可能涉及大量计算，在性能较弱的硬件上可能会运行缓慢。

您可以通过将 effect_cls 设置为任何效果类来更改所使用的效果。当前选项包括：

ScrollEffect：不允许滚动超出 ScrollView 的边界。

DampedScrollEffect：当前默认效果。允许用户滚动超出正常边界，但在触摸/点击释放后，内容会弹回原位。

OpacityScrollEffect：与 DampedScrollEffect 类似，但在过度滚动时还会降低不透明度。

你也可以通过继承这些类之一来创建自己的滚动效果，然后以相同方式将其作为 effect_cls 传入。

或者，你可以将 effect_x 和/或 effect_y 设置为你想使用的效果的*实例*。这将覆盖在 effect_cls 中设置的默认效果。

所有效果都位于 kivy.effects 模块中。

class kivy.uix.scrollview.ScrollView(**kwargs)[源代码]¶

基类：StencilView

ScrollView 类。更多信息请参阅模块文档。

事件:

on_scroll_start: 当触摸开始滚动时触发的通用事件。
on_scroll_move: 当触摸滚动移动时触发的通用事件。
on_scroll_stop: 当触摸滚动停止时触发的通用事件。

在 1.9.0 版本发生变更: 现在，当滚动以处理嵌套的ScrollViews时，会触发`on_scroll_start`、`on_scroll_move`和`on_scroll_stop`事件。

在 1.7.0 版本发生变更: auto_scroll、scroll_friction、scroll_moves、scroll_stoptime 已被弃用，请改用 effect_cls。

add_widget(widget, *args, **kwargs)[源代码]¶

将一个新部件添加为此部件的子部件。

参数:

widget：Widget
要添加到我们子控件列表中的控件。

index：整数，默认值为0
在列表中插入控件的索引。请注意，默认值0意味着控件被插入到列表的开头，因此会绘制在其他同级控件之上。关于索引和控件层次结构的完整讨论，请参阅控件编程指南。

在 1.0.5 版本加入.

canvas：字符串，默认为 None
用于添加控件画布的Canvas。可以是'before'、'after'或None（默认画布）。

在 1.9.0 版本加入.

>>> from kivy.uix.button import Button
>>> from kivy.uix.slider import Slider
>>> root = Widget()
>>> root.add_widget(Button())
>>> slider = Slider()
>>> root.add_widget(slider)

always_overscroll¶

确保用户即使在内容不足以需要滚动的情况下，也能进行过度滚动。

如果你希望在过度滚动时触发某些操作，但内容并不总是足够以触发该操作，那么这个功能会很有用。

always_overscroll 是一个 BooleanProperty，默认值为 True。

在 2.0.0 版本加入.

该选项已添加并默认启用，设置为False可恢复之前的行为，即仅在内容足够多可滚动时才允许过度滚动。

bar_color¶

水平/垂直滚动条的颜色，采用RGBA格式。

在 1.2.0 版本加入.

bar_color 是一个 ColorProperty，默认值为 [.7, .7, .7, .9]。

在 2.0.0 版本发生变更: 从 ListProperty 更改为 ColorProperty。

bar_inactive_color¶

水平/垂直滚动条在未发生滚动时的颜色（RGBA格式）。

在 1.9.0 版本加入.

bar_inactive_color 是一个 ColorProperty，默认值为 [.7, .7, .7, .2]。

在 2.0.0 版本发生变更: 从 ListProperty 更改为 ColorProperty。

bar_margin¶

绘制水平/垂直滚动条时，滚动视图底部/右侧的边距。

在 1.2.0 版本加入.

bar_margin 是一个 NumericProperty，默认值为 0。

bar_pos¶

滚动视图中每个条应放置在的侧边。

bar_pos 是 (bar_pos_x, bar_pos_y) 的 ReferenceListProperty。

bar_pos_x¶

ScrollView 的水平滚动条应位于哪一侧。可选值为 'top' 和 'bottom'。

在 1.8.0 版本加入.

bar_pos_x 是一个 OptionProperty，默认值为 'bottom'。

bar_pos_y¶

ScrollView 的垂直滚动条应位于哪一侧。可选值为 'left' 和 'right'。

在 1.8.0 版本加入.

bar_pos_y 是一个 OptionProperty，默认值为 'right'。

bar_width¶

水平/垂直滚动条的宽度。对于水平滚动条，该宽度被解释为高度。

在 1.2.0 版本加入.

bar_width 是一个 NumericProperty，默认值为 2。

convert_distance_to_scroll(dx, dy)[源代码]¶

根据内容大小和滚动视图大小，将像素距离转换为滚动距离。

结果将是一个滚动距离的元组，可添加到 scroll_x 和 scroll_y 中。

do_scroll¶

允许在X或Y轴上滚动。

do_scroll 是 (do_scroll_x + do_scroll_y) 的 AliasProperty。

do_scroll_x¶

允许在X轴上滚动。

do_scroll_x 是一个 BooleanProperty，默认值为 True。

do_scroll_y¶

允许在Y轴上滚动。

do_scroll_y 是一个 BooleanProperty，默认值为 True。

effect_cls¶

用于X轴和Y轴实例化的类效果。

在 1.7.0 版本加入.

effect_cls 是一个 ObjectProperty，默认值为 DampedScrollEffect。

在 1.8.0 版本发生变更: 如果你设置一个字符串，将使用 Factory 来解析该类。

effect_x¶

应用于X轴的效果。如果设置为None，将创建:attr:`effect_cls`的一个实例。

在 1.7.0 版本加入.

effect_x 是一个 ObjectProperty，默认值为 None。

effect_y¶

应用于Y轴的效果。如果设置为None，将创建:attr:`effect_cls`的一个实例。

在 1.7.0 版本加入.

effect_y 是一个 ObjectProperty，默认值为 None，且为只读属性。

hbar¶

返回水平滚动条的位置和尺寸元组。

在 1.2.0 版本加入.

位置和大小在0-1之间归一化，表示当前滚动视图高度的比例。此属性在内部用于绘制滚动时的小水平条。

hbar 是一个 AliasProperty，只读。

on_motion(etype, me)[源代码]¶

当接收到一个运动事件时调用。

参数:

etype：str: 事件类型，取值为"begin"、"update"或"end"之一。
me: MotionEvent: 收到运动事件

返回:

bool 类型，设为 True 可停止事件分发。

在 2.1.0 版本加入.

警告

此方法目前仍处于实验阶段，只要此警告存在，它就一直保持实验状态。

on_touch_down(touch)[源代码]¶

接收触摸按下事件。

参数:

touch：MotionEvent 类: 收到触摸事件。该触摸位于父级坐标系中。关于坐标系统的讨论，请参阅 relativelayout。

返回:

bool 如果为 True，触摸事件的派发将停止。如果为 False，事件将继续派发到控件树的其余部分。

on_touch_move(touch)[源代码]¶

接收触摸移动事件。触摸坐标位于父级坐标系中。

更多信息请参阅 on_touch_down()。

on_touch_up(touch)[源代码]¶

接收触摸抬起事件。触摸坐标位于父级坐标系中。

更多信息请参阅 on_touch_down()。

remove_widget(widget, *args, **kwargs)[源代码]¶

从该部件的子部件中移除一个部件。

参数:

widget：Widget
要从我们的子控件列表中移除的控件。

>>> from kivy.uix.button import Button
>>> root = Widget()
>>> button = Button()
>>> root.add_widget(button)
>>> root.remove_widget(button)

scroll_distance¶

滚动 ScrollView 前需要移动的距离，单位为像素。一旦达到该距离，ScrollView 将开始滚动，且触摸事件将不再传递给子组件。建议您根据目标设备屏幕的 dpi 来设定此值。

scroll_distance 是一个 NumericProperty，根据用户配置中的默认值，其默认值为 20（像素）。

scroll_timeout¶

允许触发 scroll_distance 的超时时间，单位为毫秒。如果用户在此超时时间内未移动 scroll_distance，滚动将被禁用，触摸事件将传递给子组件。

scroll_timeout 是一个 NumericProperty，根据用户配置中的默认值，其默认值为 55（毫秒）。

在 1.5.0 版本发生变更: 默认值已从250改为55。

scroll_to(widget, padding=10, animate=True)[源代码]¶: 滚动视口以确保给定的小部件可见，可选择添加内边距和动画。如果 animate 为 True`（默认值），则将使用默认的动画参数。否则，它应为一个字典，包含传递给 :class:`~kivy.animation.Animation 构造函数的参数。

在 1.9.1 版本加入.

scroll_type¶

设置滚动视图内容所使用的滚动类型。可用选项有：['content']、['bars']、['bars', 'content']。

['内容']	内容通过直接拖拽或滑动内容进行滚动。
['bars']	内容通过拖拽或滑动滚动条进行滚动。
['bars', 'content']	内容通过上述任一方法进行滚动。

在 1.8.0 版本加入.

scroll_type 是一个 OptionProperty，默认值为 ['content']。

scroll_wheel_distance¶

鼠标滚轮滚动时的移动距离。建议您根据目标设备屏幕的dpi来设定此值。

在 1.8.0 版本加入.

scroll_wheel_distance 是一个 NumericProperty ，默认值为 20 像素。

scroll_x¶

X 滚动值，范围在 0 到 1 之间。如果为 0，内容的左侧将紧贴 ScrollView 的左侧。如果为 1，内容的右侧将紧贴右侧。

该属性仅在 do_scroll_x 为 True 时由 ScrollView 控制。

scroll_x 是一个 NumericProperty，默认值为 0。

scroll_y¶

Y 滚动值，范围在 0 到 1 之间。如果为 0，内容的底部将与 ScrollView 的底部接触。如果为 1，内容的顶部将与顶部接触。

该属性仅在 do_scroll_y 为 True 时由 ScrollView 控制。

scroll_y 是一个 NumericProperty，默认值为 1。

smooth_scroll_end¶

是否应在使用鼠标滚轮滚动时启用平滑滚动结束，以及将滚动距离转换为速度的因子。此选项还启用了速度累加，意味着如果你滚动更多，滚动将更快、更远。推荐值为 10。速度计算方式为 scroll_wheel_distance * smooth_scroll_end。

在 1.11.0 版本加入.

smooth_scroll_end 是一个 NumericProperty，默认值为 None。

to_local(x, y, **k)[源代码]¶

将父级坐标转换为本地（当前控件）坐标。

关于坐标系的详细信息，请参阅 relativelayout。

参数:

relative：布尔值，默认为False: 如果你想要将坐标转换为相对于部件的坐标，请将其设置为True。

to_parent(x, y, **k)[源代码]¶

将本地（当前控件）坐标转换为父控件坐标。

关于坐标系的详细信息，请参阅 relativelayout。

参数:

relative：布尔值，默认为False: 如果你想要将控件的相对位置转换为其父坐标，请将其设为True。

update_from_scroll(*largs)[源代码]¶

根据 scroll_x 和 scroll_y 的当前值，强制重新定位内容。

当 scroll_x、scroll_y、pos 或 size 属性发生变化，或内容尺寸改变时，此方法会被自动调用。

vbar¶

返回垂直滚动条的（位置，尺寸）元组。

在 1.2.0 版本加入.

位置和大小在0-1之间归一化，表示当前滚动视图高度的比例。此属性在内部用于绘制滚动时的小垂直条。

vbar 是一个 AliasProperty，只读。

viewport_size¶: （内部）内部视口的大小。这是滚动视图中唯一子项的大小。

« 屏幕管理器

设置 »

Version

Quick search

目录

滚动视图¶

滚动行为¶

限制在X轴或Y轴¶

管理内容大小与位置¶

滚动过界效果¶