Flet 视频全屏按钮 VideoFullscreenButton：内置按钮栏项的参数定制与全屏模式实战指南-港品优选

Flet 视频全屏按钮 VideoFullscreenButton：内置按钮栏项的参数定制与全屏模式实战指南

【免费下载链接】fletBuild realtime web, mobile and desktop apps in Python only. No frontend experience required.项目地址: https://gitcode.com/gh_mirrors/fl/flet

flet-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.py：

@ft.value class VideoFullscreenButton(VideoBarItem): """A built-in fullscreen button item.""" _type: str = field(default="fullscreenButton", init=False, repr=False) """ 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 端识别按钮类型的“协议标识”，由类定义写死、不可通过构造参数修改（init=False），文档页面中也不会暴露该字段。
继承自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_color

VideoFullscreenButton的全部可配置参数只有三个，且均为可选（默认值为None），含义清晰：

参数	类型	默认值	作用
`icon`	`Optional[ft.Control]`	`None`	自定义按钮图标。传入任意`ft.Control`（如`ft.Icon`）；省略时使用默认全屏图标
`icon_size`	`Optional[ft.Number]`	`None`	覆盖图标尺寸，省略时跟随控制条统一样式
`icon_color`	`Optional[ft.ColorValue]`	`None`	覆盖图标颜色，省略时跟随控制条统一样式

自定义图标（icon）

当需要把默认全屏图标替换为业务语义更明确的图标时，传入一个ft.Icon即可。官方示例 sdk/python/examples/extensions/video/button_bars/main.py 展示了在顶部按钮栏放置全屏按钮的做法：

ftv.VideoFullscreenButton(icon_color=ft.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_color=ft.Colors.CYAN), ftv.VideoPlayOrPauseButton(icon_size=40, icon_color=ft.Colors.CYAN), ftv.VideoSkipNextButton( icon=ft.Icon(ft.Icons.FAST_FORWARD), icon_color=ft.Colors.CYAN ), ], top_button_bar=[ ft.Text("Top button bar", style=label_style), ftv.VideoSpacer(), ftv.VideoFullscreenButton( icon=ft.Icon(ft.Icons.FULLSCREEN_EXIT), icon_size=18, icon_color=ft.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.py）：

import flet as ft import flet_video as ftv def main(page: ft.Page): label_style = ft.TextStyle( size=12, color=ft.Colors.WHITE, weight=ft.FontWeight.BOLD, ) page.add( ft.SafeArea( expand=True, content=ftv.Video( expand=True, playlist=[ ftv.VideoMedia("video-sample.mp4"), ], controls=ftv.MaterialDesktopVideoControls( visible_on_mount=True, primary_button_bar=[ ftv.VideoSkipPreviousButton(icon_color=ft.Colors.CYAN), ftv.VideoPlayOrPauseButton( icon_size=40, icon_color=ft.Colors.CYAN, ), ftv.VideoSkipNextButton( icon=ft.Icon(ft.Icons.FAST_FORWARD), icon_color=ft.Colors.CYAN, ), ], top_button_bar=[ ft.Text("Top button bar", style=label_style), ftv.VideoSpacer(), ftv.VideoFullscreenButton(icon_color=ft.Colors.AMBER), ], bottom_button_bar=[ ft.Text("Bottom button bar", style=label_style), ftv.VideoSpacer(), ftv.VideoPositionIndicator( text_style=ft.TextStyle( size=13, color=ft.Colors.WHITE, ) ), ftv.VideoVolumeButton( slider_width=96, icon_color=ft.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_mount=True, bottom_button_bar=[ ftv.VideoPlayOrPauseButton(), ftv.VideoSpacer(), ft.Text("NORMAL Mode", weight=ft.FontWeight.BOLD), ftv.VideoFullscreenButton(), ], ), ftv.VideoControlsMode.FULLSCREEN: ftv.MaterialDesktopVideoControls( visible_on_mount=True, bottom_button_bar=[ ftv.VideoFullscreenButton(), ftv.VideoSpacer(), ft.Text("FULLSCREEN Mode", weight=ft.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_press=True（双击画面切换全屏，见 types.py），与全屏按钮互为补充。

快速接入与平台注意点

安装扩展包：pip install flet-video（或uv add flet-video），详见 video/index.md。
平台依赖：Linux 需要系统安装libmpv（sudo apt install libmpv-dev mpv）；Windows/macOS/iOS/Android 使用内置 mpv 后端（Android 默认--vo=gpu、--hwdec=auto-safe），Web 端使用浏览器原生播放能力，无需额外配置（详见 videoconfiguration 类型文档与 video/index.md）。
不依赖任何权限：VideoFullscreenButton仅是控制条按钮项，全屏能力由Video控件本身提供，不涉及系统权限申请。

企业官网建设流程全解析