本文介绍如何在 kivy 中构建一个高度占窗口 75%、支持垂直滚动的 5 列动态图片卡片网格，每张卡片包含标题按钮和等比缩放的图片，并确保布局自适应且无拉伸失真。
本文介绍如何在 kivy 中构建一个高度占窗口 75%、支持垂直滚动的 5 列动态图片卡片网格，每张卡片包含标题按钮和等比缩放的图片，并确保布局自适应且无拉伸失真。
在 Kivy 中实现「固定可视区域 + 可滚动内容」的网格布局，关键在于正确组合 ScrollView 与 GridLayout 的尺寸约束逻辑。原代码中 ScrollView 虽启用了滚动，但未限制其自身高度，导致整个网格被强制压缩进窗口；同时 GridLayout 缺少 size_hint_y: None 和 height: self.minimum_height，使其无法随子项增长，从而剥夺了 ScrollView 的滚动依据。
以下是推荐的结构化实现方案（基于 KV 语言 + Python 逻辑分离）：
✅ 核心要点解析：
-
ScrollView.size_hint_y: 0.75：明确限定滚动区域高度为窗口高度的 75%，剩余空间可留给其他 UI 元素（如标题栏、搜索框等）。 -
GridLayout.size_hint: (1, None)+height: self.minimum_height：告知网格不继承父容器高度，而是根据子项总高自动扩展——这是启用滚动的必要前提。 - 每个
Card（BoxLayout）必须设置size_hint_y: None和固定height（如150），否则minimum_height无法准确计算；其中Button和Image通过size_hint_y按比例分配高度（如0.25和0.75），保证图文比例稳定。 - 图片使用
texture属性而非source，便于复用缓存纹理（如你的image_cache.get_image(uuid)），避免重复加载。
? 完整可运行示例：
# kv 字符串定义（或保存为 .kv 文件）
ScrollView:
size_hint_y: 0.75
do_scroll_x: False
do_scroll_y: True
smooth_scroll_end: 15
scroll_wheel_distance: 20
GridLayout:
id: grid
cols: 5
spacing: [8, 12] # 列间距、行间距
padding: 10
size_hint: 1, None
height: self.minimum_height
<card>:
orientation: 'vertical'
size_hint: 1, None
height: 160 # 总高度 = 标题区 + 图片区（建议 ≥140，留出内边距）
Button:
text: root.text
font_size: '14sp'
size_hint_y: 0.25
background_normal: ''
background_color: 0.95, 0.95, 0.95, 1
color: 0, 0, 0, 1
Image:
texture: root.texture
size_hint_y: 0.75
allow_stretch: False # 严格保持原始宽高比
keep_ratio: True</card>
from kivy.app import App
from kivy.clock import Clock
from kivy.lang import Builder
from kivy.properties import StringProperty, ObjectProperty
from kivy.uix.boxlayout import BoxLayout
from kivy.core.image import Image as CoreImage
from kivy.uix.image import Image
# 示例：模拟从缓存加载纹理（替换为你的真实 image_cache）
def mock_image_cache(uuid):
# 实际中应返回 Texture 对象，此处用占位图示意
return CoreImage('icon.png', keep_data=True).texture
class Card(BoxLayout):
text = StringProperty('')
texture = ObjectProperty(None)
class MyApp(App):
def build(self):
# 延迟填充数据，确保 KV 已加载、root 已构建
Clock.schedule_once(self.fill_grid)
return Builder.load_string(kv)
def fill_grid(self, _dt):
grid = self.root.ids.grid
# 替换为你真实的 records.items() 循环
for idx in range(30): # 模拟 30 张卡片
uuid = f"item_{idx}"
record_name = f"Item {idx}"
# 真实项目中：texture = image_cache.get_image(uuid)
texture = mock_image_cache(uuid)
grid.add_widget(Card(text=record_name, texture=texture))
if __name__ == '__main__':
MyApp().run()
⚠️ 注意事项：
- 若图片源为网络或大文件，请务必在后台线程加载并绑定到主线程更新，避免阻塞 UI；可结合
kivy.clock.CyClockBase.create_trigger或asyncio实现异步纹理加载。 -
allow_stretch: False和keep_ratio: True是保持图像不失真的黄金组合，切勿省略。 -
GridLayout.spacing和Card.padding可提升视觉呼吸感，避免卡片紧贴边缘。 - 如需响应式列数（如横屏自动变为 6 列），可通过
Window.bind(size=self.on_window_resize)动态重设grid.cols并触发grid.fbind('minimum_height', ...)重排。
该方案兼顾性能、可维护性与视觉一致性，是 Kivy 中构建媒体画廊、商品列表等场景的推荐实践。
