Flet v0.24.0 版本发布详解新控件、破坏性变更与迁移指南【免费下载链接】fletBuild realtime web, mobile and desktop apps in Python only. No frontend experience required.项目地址: https://gitcode.com/gh_mirrors/fl/fletFlet 0.24.0 是一次功能密集的版本发布带来了InteractiveViewer与Placeholder两个新控件、覆盖十余个既有控件的新属性、事件打印输出的增强以及 Tooltip、InputFilter、事件回调订阅等多项破坏性变更。本文以官方发布公告为主体结合当前仓库中 sdk/python/packages/flet 的 Python 源码实现逐项拆解新增能力、参数细节、底层实现与迁移路径帮助你在升级后快速适配自己的 Flet 应用。发布概述Flet 0.24.0 是 Flet 1.0 时代之前的一个重要里程碑版本公告称其包含一长串 bug 修复、多项增强与新特性。该版本的核心变化集中在新增 2 个控件InteractiveViewer、Placeholder为AudioRecorder、Video、InputFilter、Geolocator、图表控件、Container、Page/View、TextField、Markdown、Tabs等补充大量新属性引入若干破坏性变更Tooltip 由控件改为 dataclass、InputFilter.regex_string需要锚定正则、事件处理器只保留最后一个回调清理了一批弃用 API并宣布在 0.27.0 中移除。新控件InteractiveViewer 与 PlaceholderInteractiveViewer平移、缩放与旋转InteractiveViewer允许用户对content进行平移pan、缩放scale和旋转rotate其 Python 实现位于 interactive_viewer.py。从源码看它是一个LayoutControl核心属性与行为如下属性默认值说明content必填被变换的控件必须可见否则抛出ValueErrorpan_enabledTrue是否允许平移scale_enabledTrue是否允许缩放trackpad_scroll_causes_scaleFalse触控板上下滑动是否触发缩放而不是平移constrainedTrue是否对 content 施加正常尺寸约束设为False时 content 获得无限约束适合内容大于视口、需要平移查看的场景min_scale0.8最小缩放比例必须大于 0 且不大于max_scalemax_scale2.5最大缩放比例必须大于 0 且不小于min_scalescale_factor200每次指针滚轮缩放的比例量增大值会让缩放变慢减小则变快仅影响指针滚轮不影响双指捏合interaction_end_friction_coefficient0.0000135手势结束后减速行为clip_behaviorClipBehavior.HARD_EDGE内容裁剪方式设为NONE时内容可视觉溢出但手势仍只在控件区域内生效boundary_marginMargin.all(0)内容可见边界的外边距传无限值可消除所有边界interaction_update_interval200on_interaction_update事件的触发间隔毫秒on_interaction_start/on_interaction_update/on_interaction_endNone平移/缩放手势开始、更新、结束时触发的事件源码同时暴露了 4 个编程式方法reset、save_state、restore_state、zoom、pan它们通过_invoke_method调用底层实现reset(animation_durationNone)将当前变换矩阵重置为单位矩阵可传入动画时长实现平滑过渡save_state()/restore_state()保存/恢复当前变换矩阵快照zoom(factor)按倍数缩放相对当前比例结果会被夹在min_scale与max_scale之间pan(dx, dy, dz0)按逻辑像素平移平移范围同样受交互边界约束。一个典型的用法是把大图包在InteractiveViewer中并配合constrainedFalse让用户自由拖动查看超出视口的部分。Placeholder占位框Placeholder提供一个可视的占位盒子常用于布局开发阶段预留区域实现位于 placeholder.py源码 docstring 给出了最小示例ft.Placeholder( expandTrue, colorft.Colors.RED_500, )其属性包括content可选占位框内显示的控件、color默认Colors.BLUE_GREY_700、fallback_height/fallback_width默认 400.0用于无界高度/宽度场景、stroke_width默认 2.0线条宽度。开发阶段用它代替尚未实现的模块可以直观看到页面布局的骨架。新增属性一览与源码佐证媒体与定位类AudioRecorder.cancel_recording()新增取消录音的方法Video新增on_completed播放完成、on_track_changed轨道切换事件Geolocator新增on_error、on_position_change后者支持位置流式监听——只要定义了该事件就可以在位置变化发生时实时收听。图表 Tooltip 系列BarChart与LineChart一次性新增了 10 个 tooltip 定制属性tooltip_border_side、tooltip_direction、tooltip_fit_inside_horizontally、tooltip_fit_inside_vertically、tooltip_horizontal_offset、tooltip_margin、tooltip_max_content_width、tooltip_padding、tooltip_rounded_radius、tooltip_rotate_angle可以精确控制数据点提示框的边框、方向、内缩、偏移、圆角与旋转角度。装饰与背景Container新增decoration、foreground_decoration、ignore_interactions和imagePage、View同样新增decoration、foreground_decoration。其中image的类型是DecorationImage定义于 box.py。源码显示它支持srcURL、资源路径、base64 字符串或原始字节、color_filter、fit、alignment、repeat、scale、opacity、filter_quality默认MEDIUM、invert_colors、anti_alias等属性。这意味着为整个应用或某个页面设置背景图片/渐变已经成为简单易用的一等公民能力公告中引用的 PR #3820 正是这项需求。文本输入类CupertinoTextFieldenable_scribble、image、obscuring_character、padding、scroll_padding、on_clickTextFieldcounter、disabled_hint_content、options_fill_horizontallyInputFilterunicode、case_sensitive、dot_all、multiline详见下文迁移部分DataTableheading_row_alignmentExpansionTilemin_tile_height、show_trailing_icon。其余控件Markdownfit_content、img_error_content、md_style_sheet、shrink_wrap、soft_line_break、on_selection_changeMenuItemButtonautofocus、overflow_axis、semantic_labelTabslabel_padding、label_text_style、padding、splash_border_radius、unselected_label_text_style、on_click。此外还新增了大量枚举、dataclass、事件类集中在 reference 文档中。增强功能盘点事件打印输出事件对象在print时的字符串输出更友好便于调试时直接打印事件内容。图片过滤质量默认值调整Image.filter_quality默认值从FilterQuality.LOW改为FilterQuality.MEDIUM对缩小显示的图片是更优的默认选择。这一默认值在DecorationImage.filter_quality上同样保持一致。AppBar 自适应模式下 actions 的展示当AppBar.adaptiveTrue且在 Apple 平台运行时AppBar.actions中的控件现在会被包进一个Row再显示此前只会显示列表中的第一项。Markdown 能力增强Markdown控件得到显著改进现在可以渲染 SVG 图片并支持更丰富的自定义例如通过md_style_sheet定制代码样式等。RTL 支持扩展rtlright-to-left从右到左属性被加入更多控件NavigationRailDestination、NavigationRail、AppBar、CupertinoAppBar、NavigationDrawer以改善对从右到左文字方向的支持。构建命令新增--no-rich-outputflet build命令新增--no-rich-output标志用于关闭控制台中的富文本输出主要是 emoji方便在 CI 等对终端输出要求严格的场景中使用。类型提示大幅改进事件处理器属性的类型提示得到显著提升在 PyCharm、VSCode 等现代 IDE 中只需悬停事件即可查看事件参数的类型当你访问事件参数上不存在的属性时IDE 会直接标红提示从源头上减少运行时错误。Bug 修复清单本次发布修复了一批影响较大的问题编号为公告引用的 issue/PR 编号#3769InputFilter在输入非法字符时清空TextField全部文本#3770Theme.floating_action_button_theme不存在#3734确保Dropdown.alignment生效#3730在 Windows 打包时抛出UnicodeEncodeError#2160Markdown无法渲染 SVG 图片#2158Markdown在图片找不到时崩溃#3679Dismissible损坏#3670Switch.height、Switch.width不生效#3612、#3566OnScrollEvent损坏#3564TextField.capitalization损坏#3649CupertinoPicker在部分平台滚动跳动#3557Impeller 在 mac Intel 上导致白屏#3574Geolocator在 Android 设备上无法工作#3505WindowEventType缺少 fullscreen 相关事件。弃用项将于 0.27.0 移除本次发布宣布的弃用项将在0.27.0中被彻底移除升级时应尽早完成迁移ThemeVisualDensity弃用更名为VisualDensityCupertinoButton.disabled_color弃用更名为disabled_bgcolor更贴切地反映其用途Markdown.code_style弃用应改为通过code_style_sheet.code_text_style访问Container的image_fit、image_opacity、image_repeat、image_src、image_src_base64弃用应统一改为使用image属性类型为DecorationImage来表达。破坏性变更与迁移指南Tooltip从控件变为 dataclass这是 0.24.0 最直观的破坏性变更Tooltip不再是 Flet 控件而是一个简单的 Python dataclass几乎所有控件的tooltip属性现在同时支持字符串和Tooltip对象。当前仓库中 tooltip.py 的实现印证了这一点并且它还通过TooltipValue Union[str, Tooltip]类型别名显式声明了两种合法取值。迁移前后的对比如下# 迁移前Tooltip 作为独立控件添加到页面 page.add( ft.Tooltip( messageThis is tooltip, contentft.Text(Hover to see tooltip), padding20, border_radius10, ) ) # 迁移后Tooltip 作为 dataclass 挂到控件的 tooltip 属性上 page.add( ft.Text( Hover to see tooltip, tooltipft.Tooltip( messageThis is tooltip, padding20, border_radius10, ) ) )新Tooltipdataclass 提供了远超简单字符串的定制能力包括decoration背景装饰默认随明暗主题自动选择、enable_feedback声音/触感反馈、vertical_offset、margin、padding移动端默认Padding.symmetric(horizontal16, vertical4)桌面端为Padding.symmetric(horizontal8, vertical4)、bgcolor、text_style、text_align、prefer_below、show_duration、wait_duration、exit_duration、tap_to_dismiss、exclude_from_semantics、trigger_modeMANUAL/TAP/LONG_PRESS、mouse_cursor、size_constraints等。TextField 的 InputFilter正则需要锚定InputFilter.regex_string的内部处理方式被修改升级后可能需要在正则中添加锚点即用^起始和$结束约束整个输入串。# 迁移前 filter ft.InputFilter(regex_stringr[0-9]) # 迁移后锚定整个输入 filter ft.InputFilter(regex_stringr^[0-9]$)注意r^[0-9]$会带来一个新问题文本字段的最后一个字符无法被删除。解决方案是在正则中加入*表示匹配零个或多个数字包括空字符串filter ft.InputFilter(regex_stringr^[0-9]*$)源码层面InputFilter定义于 textfield.py当前实现还支持allowTrue允许匹配、False拒绝匹配、replacement_string替换被禁止模式的字符串、multiline是否多行匹配决定^/$匹配行首行尾还是整个输入的开头结尾、case_sensitive、unicode、dot_all等参数。迁移时可以借助 AI 工具使用这样的提示词update the following regex pattern: #### ensuring that the entire string matches the pattern and it allows for an empty string。事件处理器订阅一个事件只保留一个回调0.24.0 移除了为同一个事件处理器订阅多个回调的能力此前只对部分控件可用存在不一致。从 0.24.0 起一个事件 一个回调只有最后订阅的回调会被执行import flet as ft def main(page: ft.Page): def print_one(e): print(1) def print_two(e): print(2) def print_three(e): print(3) c ft.Container( bgcolorft.Colors.random_color(), width300, height300, ) # 0.24.0 之前三个回调都会执行打印 1、2、3 # 0.24.0 起只有最后一个回调执行打印 3 c.on_tap_down print_one c.on_tap_down print_two c.on_tap_down print_three page.add(c) ft.run(main)如果希望保留多个回调的效果可以创建一个聚合回调在其中依次调用其他回调def main(page: ft.Page): # ...其他代码 def print_all(e): print_one(e) print_two(e) print_three(e) c ft.Container( bgcolorft.Colors.random_color(), width300, height300, on_tap_downprint_all, ) # 或者 # c.on_tap_down print_all结语与升级建议Flet 0.24.0 在带来InteractiveViewer、Placeholder两个新控件和大量属性增强的同时也引入了 Tooltip 用法、InputFilter 正则写法、事件订阅行为三处需要动手修改的破坏性变更并预告了 0.27.0 将移除一批弃用 API。建议升级后重点检查所有把Tooltip当作控件添加的代码、所有未锚定的InputFilter.regex_string、以及所有对同一事件重复赋值的回调逻辑。逐项对照本文的迁移示例完成适配即可平滑过渡到新版本。【免费下载链接】fletBuild realtime web, mobile and desktop apps in Python only. No frontend experience required.项目地址: https://gitcode.com/gh_mirrors/fl/flet创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考