Python Kivy如何实现图片按钮并保持原始图片比例？

直接用Button的background_normal显示图片会导致图片被拉伸填充整个按钮区域，这是因为Kivy默认会将背景图强制拉伸匹配按钮尺寸。要实现类似手机相册的方形预览且保持图片比例，你需要用Image控件配合Button，通过控制Image的缩放模式来实现，以下是具体方案：

方案1：自定义方形图片按钮（推荐） #

创建继承自Button的自定义控件，内部嵌入Image来控制图片显示，同时保证按钮始终为方形：

from kivy.uix.button import Button
from kivy.uix.image import Image
from kivy.uix.gridlayout import GridLayout
from kivy.app import App

class SquareImageButton(Button):
    def __init__(self, img_path, **kwargs):
        super().__init__(**kwargs)
        # 禁用size_hint自动缩放，手动控制尺寸
        self.size_hint = (None, None)
        # 绑定宽度变化时同步高度，保持方形
        self.bind(width=self._sync_height)

        # 初始化图片控件，设置比例保持模式
        self.img = Image(
            source=img_path,
            keep_ratio=True,    # 强制保持图片原始比例
            allow_stretch=False, # 禁止拉伸变形
            fit_mode='cover'     # 图片覆盖按钮区域（裁剪多余部分，类似相册预览）
                                 # 若要留白显示完整图片，改为fit_mode='contain'
        )
        # 让图片尺寸跟随按钮尺寸变化
        self.bind(size=self.img.setter('size'))
        self.add_widget(self.img)

    def _sync_height(self, instance, new_width):
        self.height = new_width

class GalleryApp(App):
    def build(self):
        # 3列网格布局，间距和内边距按需调整
        grid = GridLayout(cols=3, spacing=8, padding=10)
        
        # 替换为你的图片路径列表
        img_list = ['photo1.jpg', 'photo2.jpg', 'photo3.jpg', 'photo4.jpg']
        for img_path in img_list:
            # 设置按钮初始宽度，GridLayout会自动适配列宽
            btn = SquareImageButton(img_path, width=120)
            # 绑定点击事件（示例）
            btn.bind(on_press=lambda x, path=img_path: print(f"点击了图片: {path}"))
            grid.add_widget(btn)
        return grid

if __name__ == '__main__':
    GalleryApp().run()

关键说明 #

1. 为什么不用Button背景图？
   Button的background_normal是作为背景填充层设计的，会强制拉伸匹配按钮的宽高，无法单独控制图片比例，因此必须用独立的Image控件来托管图片。

2. 图片缩放模式参数

   • keep_ratio=True：锁定图片宽高比例，避免变形
   • fit_mode='cover'：让图片填满方形按钮，超出部分自动裁剪（相册预览常用）
   • fit_mode='contain'：完整显示图片，按钮空白区域留空

3. GridLayout适配
   给按钮设置size_hint=(None, None)后，可通过width指定初始尺寸，GridLayout会根据列数自动排列；如果希望按钮随窗口大小自适应，可将size_hint_x=1，然后绑定width到self.parent.width / cols来动态调整。

兼容旧版Kivy（<2.0） #

如果你的Kivy版本低于2.0，没有fit_mode属性，可以通过手动调整Image的位置和尺寸实现类似效果：

# 在SquareImageButton的__init__中替换Image的初始化代码
self.img = Image(source=img_path, keep_ratio=True, allow_stretch=False)
# 绑定按钮尺寸变化时，重新计算图片的显示区域
self.bind(size=self._adjust_img_pos)

def _adjust_img_pos(self, instance, new_size):
    # 计算图片在方形按钮中的最优尺寸
    img_ratio = self.img.texture.width / self.img.texture.height
    btn_ratio = new_size[0] / new_size[1]
    
    if img_ratio > btn_ratio:
        # 图片更宽，按按钮高度缩放，左右裁剪
        self.img.height = new_size[1]
        self.img.width = self.img.height * img_ratio
        self.img.x = (new_size[0] - self.img.width) / 2
        self.img.y = 0
    else:
        # 图片更高，按按钮宽度缩放，上下裁剪
        self.img.width = new_size[0]
        self.img.height = self.img.width / img_ratio
        self.img.y = (new_size[1] - self.img.height) / 2
        self.img.x = 0

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