Flet 视频全屏按钮 VideoFullscreenButton内置按钮栏项的参数定制与全屏模式实战指南【免费下载链接】fletBuild realtime web, mobile and desktop apps in Python only. No frontend experience required.项目地址: https://gitcode.com/gh_mirrors/fl/fletflet-video 是 Flet 生态中基于media_kit的跨平台视频播放器扩展包其内置播放控制条由若干VideoBarItem按钮项组装而成VideoFullscreenButton正是其中负责进入/退出全屏的按钮项。本文围绕flet_video.VideoFullscreenButton的完整 API继承关系、icon/icon_size/icon_color三个可配置参数、它在两套内置控制条中的默认位置、如何用VideoControlsMode实现“普通模式与全屏模式使用不同按钮栏”并结合仓库源码与官方示例给出可直接运行的组装代码帮助你在纯 Python 的 Flet 应用中快速定制视频全屏交互。VideoFullscreenButton 在控件体系中的位置在 flet-video 包中视频播放控制条并非一个固定整体而是由可替换的按钮项列表组装而成。所有内置按钮项的公共基类是VideoBarItem它只持有一个由具体子类固定写死的_type字段用于标识“该调用内置的哪种按钮项”。VideoFullscreenButton的类定义位于 sdk/python/packages/flet-video/src/flet_video/types.pyft.value class VideoFullscreenButton(VideoBarItem): A built-in fullscreen button item. _type: str field(defaultfullscreenButton, initFalse, reprFalse) Identifies this item as a built-in fullscreen button. icon: Optional[ft.Control] None Icon displayed by the button. If omitted, the default fullscreen icon is used. icon_size: Optional[ft.Number] None Overrides the icon size. icon_color: Optional[ft.ColorValue] None Overrides the icon color. 从源码结构可以梳理出该类的三个关键事实它属于ft.value值对象与VideoMedia、VideoControls等一样VideoFullscreenButton不是独立渲染的 Flet 控件ft.Control而是描述按钮项配置的值对象最终由底层 Flutter 端media_kit 的 Material 控制条渲染为真实按钮。_type固定为fullscreenButton这是 Dart 端识别按钮类型的“协议标识”由类定义写死、不可通过构造参数修改initFalse文档页面中也不会暴露该字段。继承自VideoBarItem因此它可以与VideoPlayOrPauseButton、VideoSkipNextButton、VideoSpacer、VideoVolumeButton等同构地混排在primary_button_bar、top_button_bar、bottom_button_bar列表中。对应类型定义文件__all__中已导出VideoFullscreenButton见 types.py并在 flet_video/init.py 中公开因此使用方式是flet_video.VideoFullscreenButton或import flet_video as ftv后写作ftv.VideoFullscreenButton。参数详解icon、icon_size、icon_colorVideoFullscreenButton的全部可配置参数只有三个且均为可选默认值为None含义清晰参数类型默认值作用iconOptional[ft.Control]None自定义按钮图标。传入任意ft.Control如ft.Icon省略时使用默认全屏图标icon_sizeOptional[ft.Number]None覆盖图标尺寸省略时跟随控制条统一样式icon_colorOptional[ft.ColorValue]None覆盖图标颜色省略时跟随控制条统一样式自定义图标icon当需要把默认全屏图标替换为业务语义更明确的图标时传入一个ft.Icon即可。官方示例 sdk/python/examples/extensions/video/button_bars/main.py 展示了在顶部按钮栏放置全屏按钮的做法ftv.VideoFullscreenButton(icon_colorft.Colors.AMBER)统一尺寸与配色icon_size、icon_color控制条按钮栏提供了全局统一样式属性MaterialVideoControls.button_bar_button_size与button_bar_button_color桌面版为MaterialDesktopVideoControls.button_bar_button_size与button_bar_button_color而icon_size与icon_color的作用正是针对单个按钮做局部覆盖。例如在播放/暂停按钮放大到 40 的同时让全屏按钮保持小尺寸并换成品牌色ftv.MaterialDesktopVideoControls( primary_button_bar[ ftv.VideoSkipPreviousButton(icon_colorft.Colors.CYAN), ftv.VideoPlayOrPauseButton(icon_size40, icon_colorft.Colors.CYAN), ftv.VideoSkipNextButton( iconft.Icon(ft.Icons.FAST_FORWARD), icon_colorft.Colors.CYAN ), ], top_button_bar[ ft.Text(Top button bar, stylelabel_style), ftv.VideoSpacer(), ftv.VideoFullscreenButton( iconft.Icon(ft.Icons.FULLSCREEN_EXIT), icon_size18, icon_colorft.Colors.AMBER, ), ], )它在默认按钮栏中的位置两套内置控制条VideoFullscreenButton不需要显式配置就会出现在内置控制条的默认布局中具体取决于你选用哪套控制条MaterialVideoControls触屏/移动端在 types.py 中MaterialVideoControls.bottom_button_bar的默认值为[ ftv.VideoPositionIndicator(), ftv.VideoSpacer(), ftv.VideoFullscreenButton(), ]即全屏按钮默认位于底部按钮栏最右侧紧跟在播放位置指示器之后。MaterialDesktopVideoControls桌面端桌面版默认布局更长见 types.py[ ftv.VideoSkipPreviousButton(), ftv.VideoPlayOrPauseButton(), ftv.VideoSkipNextButton(), ftv.VideoSpacer(), ftv.VideoPositionIndicator(), ftv.VideoFullscreenButton(), ftv.VideoVolumeButton(), ]全屏按钮位于底部按钮栏倒数第二位右侧是音量按钮VideoVolumeButton目前仅由MaterialDesktopVideoControls渲染见其类注释 types.py。覆盖规则把bottom_button_bar或其他按钮栏设为自定义列表可整体替换默认布局设为空列表[]可隐藏该按钮栏设为None则恢复原生默认值——VideoFullscreenButton也会随默认布局一同回归。完整组装示例把全屏按钮放进播放器下面是一个可直接运行的完整示例将VideoFullscreenButton与播放/暂停、跳转、位置指示器等按钮项组合成一套定制控制条示例改编自官方示例 button_bars/main.pyimport flet as ft import flet_video as ftv def main(page: ft.Page): label_style ft.TextStyle( size12, colorft.Colors.WHITE, weightft.FontWeight.BOLD, ) page.add( ft.SafeArea( expandTrue, contentftv.Video( expandTrue, playlist[ ftv.VideoMedia(video-sample.mp4), ], controlsftv.MaterialDesktopVideoControls( visible_on_mountTrue, primary_button_bar[ ftv.VideoSkipPreviousButton(icon_colorft.Colors.CYAN), ftv.VideoPlayOrPauseButton( icon_size40, icon_colorft.Colors.CYAN, ), ftv.VideoSkipNextButton( iconft.Icon(ft.Icons.FAST_FORWARD), icon_colorft.Colors.CYAN, ), ], top_button_bar[ ft.Text(Top button bar, stylelabel_style), ftv.VideoSpacer(), ftv.VideoFullscreenButton(icon_colorft.Colors.AMBER), ], bottom_button_bar[ ft.Text(Bottom button bar, stylelabel_style), ftv.VideoSpacer(), ftv.VideoPositionIndicator( text_styleft.TextStyle( size13, colorft.Colors.WHITE, ) ), ftv.VideoVolumeButton( slider_width96, icon_colorft.Colors.AMBER, ), ], ), ), ) ) if __name__ __main__: ft.run(main)其中ftv.Video的controls参数接受VideoControls值对象MaterialVideoControls/MaterialDesktopVideoControls/AdaptiveVideoControls、自定义ft.Control或None隐藏控制条详见 video.py。若希望移动端与桌面端各自适配可直接使用默认值AdaptiveVideoControls()——它会按Page.platform在运行时自动选择 Material 或 Material Desktop 控制条。进阶用 VideoControlsMode 区分普通与全屏两套按钮栏全屏按钮的真正价值在于与“全屏模式”联动。Video.controls还支持传入一个以VideoControlsMode为键的字典从而在普通模式与全屏模式下呈现不同的按钮栏NORMAL非全屏时使用的控制条FULLSCREEN全屏时使用的控制条DEFAULT兜底控制条当某一模式未提供时使用。规则见 video.py 的 docstring若未提供NORMAL则用DEFAULT若未提供FULLSCREEN则先复用NORMAL再回退到DEFAULT某个模式值为None表示仅在该模式下隐藏控制条。官方示例 controls_mode/main.py 展示了将全屏按钮作为普通/全屏两套布局切换点的用法controls{ ftv.VideoControlsMode.NORMAL: ftv.MaterialDesktopVideoControls( visible_on_mountTrue, bottom_button_bar[ ftv.VideoPlayOrPauseButton(), ftv.VideoSpacer(), ft.Text(NORMAL Mode, weightft.FontWeight.BOLD), ftv.VideoFullscreenButton(), ], ), ftv.VideoControlsMode.FULLSCREEN: ftv.MaterialDesktopVideoControls( visible_on_mountTrue, bottom_button_bar[ ftv.VideoFullscreenButton(), ftv.VideoSpacer(), ft.Text(FULLSCREEN Mode, weightft.FontWeight.BOLD), ftv.VideoPlayOrPauseButton(), ], ), },全屏模式下按钮布局镜像翻转全屏按钮被放到左侧此时它充当“退出全屏”入口播放/暂停按钮与状态文案排布在右侧。底层实现Dart 端如何渲染与联动Python 端的_type: fullscreenButton会随控制条配置一起序列化到 Flutter 端。在 flet_video/lib/src/utils/video.dart 中parseVideoControlsBarItem对fullscreenButton的映射为case fullscreenButton: return materialDesktop ? MaterialDesktopFullscreenButton( icon: icon, iconSize: iconSize, iconColor: iconColor, ) : MaterialFullscreenButton( icon: icon, iconSize: iconSize, iconColor: iconColor, );可以看到icon、icon_size、icon_color三个字段被逐一透传给 media_kit 的MaterialFullscreenButton移动端或MaterialDesktopFullscreenButton桌面端组件其余按钮项playOrPauseButton、skipNextButton等同理均在同一个 switch 中分发。与全屏按钮联动的是Video控件自身的fullscreen属性布尔值可编程方式进入/退出全屏见 video.py以及on_enter_fullscreen、on_exit_fullscreen两个事件回调video.py可用于在全屏状态切换时更新业务状态。此外桌面控制条默认开启toggle_fullscreen_on_double_pressTrue双击画面切换全屏见 types.py与全屏按钮互为补充。快速接入与平台注意点安装扩展包pip install flet-video或uv add flet-video详见 video/index.md。平台依赖Linux 需要系统安装libmpvsudo apt install libmpv-dev mpvWindows/macOS/iOS/Android 使用内置 mpv 后端Android 默认--vogpu、--hwdecauto-safeWeb 端使用浏览器原生播放能力无需额外配置详见 videoconfiguration 类型文档 与 video/index.md。不依赖任何权限VideoFullscreenButton仅是控制条按钮项全屏能力由Video控件本身提供不涉及系统权限申请。延伸阅读仓库内路径类型定义与全部内置按钮项sdk/python/packages/flet-video/src/flet_video/types.pyVideoFullscreenButton见 L229-L253Video控件属性与事件sdk/python/packages/flet-video/src/flet_video/video.pyFlutter 端按钮项分发实现flet_video/lib/src/utils/video.dart可运行示例button_bars/main.py、controls_mode/main.py官方文档入口video/index.md【免费下载链接】fletBuild realtime web, mobile and desktop apps in Python only. No frontend experience required.项目地址: https://gitcode.com/gh_mirrors/fl/flet创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
