Python/Kivy中如何实现子元素同步裁剪的圆角ScrollView？

核心结论 #

原生ScrollView不内置支持radius属性，两种常见无效方案的根本原因如下：

• 直接在ScrollView配置radius属于无效属性：原生ScrollView类未定义radius相关的渲染绑定逻辑，写在kv规则中不会触发任何效果。
• 仅在canvas.before绘制RoundedRectangle只能实现圆角外观，不会修改控件的默认裁剪规则。Kivy控件默认按自身矩形边界裁剪子元素，因此滚动内容会溢出圆角范围。

可行实现方案 #

通过替换ScrollView默认的矩形裁剪模板为圆角矩形，即可同时实现圆角外观+子元素按圆角边界同步裁剪，不需要额外嵌套冗余控件，实现代码如下：

# 自定义可配置圆角的ScrollView
<RoundedScrollView@ScrollView>:
    radius: [dp(10),] # 配置默认圆角值
    canvas.before:
        StencilPush
        RoundedRectangle:
            pos: self.pos
            size: self.size
            radius: self.radius
        StencilUse
    canvas.after:
        StencilUnUse
        StencilPop
        # 此处可自定义ScrollView背景
        Color:
            rgba: 1, 0, 0, 1
        RoundedRectangle:
            pos: self.pos
            size: self.size
            radius: self.radius

调用示例 #

Screen:
    RoundedScrollView:
        do_scroll: [False, True]
        radius: [0, 0, dp(80), 0] # 按需传入圆角参数即可
        MDList:
            id: list
            # 内部子元素无需配置任何radius属性，裁剪逻辑由父容器统一处理

注意事项 #

• 实现逻辑依赖Kivy的Stencil裁剪机制：StencilPush和StencilUse之间定义的图形会作为裁剪蒙版，所有子元素内容仅会在蒙版覆盖区域内显示，刚好替换ScrollView原生的矩形裁剪逻辑，从根源上解决子元素溢出问题。
• 自定义类调用时注意拼写：类名为RoundedScrollView，漏写字母c写成RoundedSrollView会导致自定义规则完全不生效。
• 不需要给内部MDList等子元素单独配置radius，子元素本身是滚动内容，自身的radius属性只会修改自身外观，不会影响父容器的裁剪范围。

内容的提问来源于stack exchange，提问作者Hugo Cezar