Flet 中 Card 控件的完整使用指南：从基础布局到 Material 三种卡片变体

Flet 中 Card 控件的完整使用指南从基础布局到 Material 三种卡片变体【免费下载链接】fletBuild realtime web, mobile and desktop apps in Python only. No frontend experience required.项目地址: https://gitcode.com/gh_mirrors/fl/fletFlet 的Card是遵循 Material Design 的容器型控件用于将相关内容和操作以卡片形式聚合展示具备圆角、阴影与可裁剪的内容区。本文以官方文档 card.md 为主体结合 Python SDK 源码card.py、Flutter 实现card.dart与仓库内可运行示例music_info/main.py系统讲解 Card 的全部属性、三种变体、主题定制方法及实战示例读完即可在自己的 Flet 应用中直接落地使用。1. 认识 Flet 的 Card 控件Card是一个 Material Design 卡片一块带有轻微圆角和投影阴影的面板a panel with slightly rounded corners and an elevation shadow见 card.py。它常用于收纳一组逻辑相关的内容——例如一条音乐信息、一份商品详情、一条用户动态——同时为内容配上操作入口。从源码结构看Card继承自LayoutControl与AdaptiveControl并通过control(Card)装饰器注册为 Flet 控件树中的一个节点control(Card) class Card(LayoutControl, AdaptiveControl):这意味着它天然具备 Flet 布局控件的能力可设置尺寸、边距等也支持在 iOS/Android 上自适应切换平台外观。在 Flutter 端card.dart 中的CardControl将 Flet 侧下发的属性映射为 Flutter 的CardWidget——每次属性变化都会触发debugPrint(Card build: ...)并重建 Widget从而保证响应式更新。一个最小可用示例只需content参数import flet as ft def main(page: ft.Page): page.add( ft.Card( contentft.Container( width400, padding10, contentft.Text(卡片内容), ) ) ) ft.app(main)2. Card 的核心属性详解以下属性均来自 card.py 的类定义参数类型与默认行为以源码为准。2.1 content卡片内容区类型Optional[Control]说明要显示在卡片内部的控件。源码提示Tip需要展示多个子控件时应把它们包进Row、Column或Stack这类接受controls列表的容器控件中因为content只能接收一个控件。2.2 elevation阴影高度类型Optional[Number]数值说明卡片在 z 轴上的高度决定卡片下方阴影的大小。默认值取CardTheme.elevation若主题中也为None则回退到1.0。2.3 bgcolor背景色类型Optional[ColorValue]说明卡片背景颜色。未设置时由主题或 Material 默认色决定。2.4 shadow_color阴影颜色类型Optional[ColorValue]说明绘制在卡片下方阴影的颜色。默认值CardTheme.shadow_color。官方示例中即使用了shadow_colorft.Colors.ON_SURFACE_VARIANT让阴影呈现柔和的表面色。2.5 shape卡片形状类型Optional[OutlinedBorder]说明卡片的形状决定圆角大小、边框样式等。默认值CardTheme.shape若为None回退到RoundedRectangleBorder(radius12.0)即默认 12 逻辑像素的圆角矩形。2.6 clip_behavior内容裁剪方式类型Optional[ClipBehavior]说明content超出卡片边界时的裁剪策略。默认值CardTheme.clip_behavior若为None回退到ClipBehavior.NONE不裁剪。2.7 semantic_container语义容器类型bool默认True说明该卡片是一个整体语义容器适合无障碍朗读时合并成一个节点还是由多个独立语义节点组成的集合。若卡片内部是不同类型的内容可设为False让辅助技术分别读取。2.8 show_border_on_foreground边框绘制层级类型bool默认True说明卡片边框形状绘制在content前面True还是后面False。当边框需要覆盖在内容之上例如带边框的圆角裁剪效果时使用。2.9 variant卡片变体类型CardVariant枚举默认CardVariant.ELEVATED说明选择 Material 卡片视觉预设取值与效果见下表枚举值字符串值视觉特征CardVariant.ELEVATEDelevated标准投影卡片带阴影的默认风格CardVariant.FILLEDfilled填充型卡片强调容器底色弱化阴影CardVariant.OUTLINEDoutlined描边型卡片以可见边框代替阴影2.10 特殊处理margin 被跳过源码init()中有这样一行self._internals[skip_properties] [margin]即 Card 在 Flet 协议层会跳过margin属性的传输卡片外边距由外层容器如Container、SafeArea控制这一点与 Flutter 端CardControl读取margin的行为形成对照——从源码结构看Flutter 端虽接收 margin但 Python 侧默认不通过该路径下发实际排版建议依赖外层布局控件。3. 三种卡片变体CardVariant的实战用法在 Flutter 端card.dart 根据variant分别映射到 Flutter 的Card.outlined()、Card.filled()与标准Card()构造器三种构造器在视觉上对应 Material 3 的 Outlined / Filled / Elevated Card。Flet 侧设置方式完全一致仅需指定variant# 1) Elevated默认 ft.Card( contentft.Text(Elevated Card), ) # 2) Filled底色明显阴影弱 ft.Card( variantft.CardVariant.FILLED, bgcolorft.Colors.SURFACE_VARIANT, contentft.Text(Filled Card), ) # 3) Outlined无阴影但有描边 ft.Card( variantft.CardVariant.OUTLINED, contentft.Text(Outlined Card), )选择建议需要层级感如页面中的主要信息块用ELEVATED需要低调、紧凑的内容块用FILLED需要强边框分割、弱化投影如表单区域用OUTLINED。4. 官方示例逐行解读音乐信息卡片文档通过examples: controls/material/card指向仓库中的示例程序 music_info/main.py它演示了 Card ListTile 操作按钮的经典组合。完整代码如下import flet as ft def main(page: ft.Page): page.title Card Example page.theme_mode ft.ThemeMode.LIGHT page.add( ft.SafeArea( contentft.Card( shadow_colorft.Colors.ON_SURFACE_VARIANT, contentft.Container( width400, padding10, contentft.Column( controls[ ft.ListTile( bgcolorft.Colors.GREY_400, leadingft.Icon(ft.Icons.ALBUM), titleft.Text(The Enchanted Nightingale), subtitleft.Text( Music by Julie Gable. Lyrics by Sidney Stein. ), ), ft.Row( alignmentft.MainAxisAlignment.END, controls[ ft.TextButton(Buy tickets), ft.TextButton(Listen), ], ), ] ), ), ), ) ) if __name__ __main__: ft.run(main)要点拆解SafeArea 包裹让卡片避开系统安全区刘海屏、圆角屏保证内容不被遮挡。Card 外层设置shadow_color自定义阴影色调content传入一个固定宽度 400、内边距 10 的Container。内部多子控件由于content只接受单个控件两个子元素ListTile信息行 Row操作行被包进Column这正是 card.py 文档注释建议的做法。ListTile 信息行leading放专辑图标Icons.ALBUMtitle为歌曲名subtitle为创作者信息bgcolor设置浅灰底。Row 操作行alignmentft.MainAxisAlignment.END将两个TextButtonBuy tickets / Listen靠右对齐形成常见的卡片信息 操作区布局。运行方式该示例依赖flet包开发依赖还包含flet-cli、flet-desktop、flet-web见 pyproject.toml在项目目录执行flet run或直接python main.py即可启动桌面/Web 窗口查看效果。5. 通过 CardTheme 做全局主题定制如果希望所有Card 统一风格而非逐个设置属性可以在page.theme中配置CardTheme。该类的定义位于 theme.py字段与 Card 属性一一对应CardTheme 字段覆盖的 Card 属性说明colorclip_behavior相关文档描述源码注释中此处指向 clip_behavior 的默认值覆盖shadow_colorshadow_color全局阴影色elevationelevation全局阴影高度shapeshape全局形状/圆角clip_behaviorclip_behavior全局裁剪策略marginmargin全局外边距注意Card 自身的elevation、shape、shadow_color、clip_behavior等属性在文档中明确标注Defaults toCardTheme.*即控件级设置优先未设置时才回退到主题值。示例用法def main(page: ft.Page): page.theme ft.Theme( card_themeft.CardTheme( elevation4, shapeft.RoundedRectangleBorder(radius16), shadow_colorft.Colors.GREY_400, ) ) page.add(ft.Card(contentft.Text(应用级默认卡片样式)))这样所有未显式指定elevation/shape/shadow_color的 Card 都会自动套用主题配置便于保持整个应用视觉一致。6. 常见问题与实用建议多子控件报错/只显示一个content只能接收一个控件请务必使用Column、Row或Stack包裹多个子元素源码 card.py 的 Tip 即为此。卡片内按钮需要事件TextButton、IconButton等均支持on_click回调直接在回调中调用page更新即可卡片本身只是布局容器不拦截子控件事件。想点击整张卡片可在content外层套GestureDetector如 gesturedetector.md 所述或用ListTile的on_click作为卡片内主交互入口。阴影不明显提高elevation并确保未设置会覆盖阴影的主题配置FILLED变体天然弱化阴影若需要投影请使用ELEVATED。内容溢出卡片圆角设置clip_behaviorft.ClipBehavior.ANTI_ALIAS或HARD_EDGE即可让内容按shape裁剪。7. 参考资料官方控件文档card.mdPython 控件定义card.py全局主题定义CardThemetheme.pyFlutter 端实现card.dart可运行示例music_info/main.py 及其 pyproject.toml【免费下载链接】fletBuild realtime web, mobile and desktop apps in Python only. No frontend experience required.项目地址: https://gitcode.com/gh_mirrors/fl/flet创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考