Flet flet-video 的 VideoSpacer 控件栏弹性间隔布局指南

• 前端
• 跨平台
• 桌面应用
• 移动开发

导读

VideoSpacer是 Flet 官方视频扩展包flet-video提供的按钮栏布局工具，用于在视频播放器的**主按钮栏（primary button bar）、顶部按钮栏（top button bar）和底部按钮栏（bottom button bar）**中插入可伸缩的空白间隔，从而精确控制按钮之间的对齐与留白。本文将从源码定义、Flutter 端渲染原理、内置默认布局到真实示例代码，完整讲解如何使用VideoSpacer定制 Flet 视频播放器的控制栏。

VideoSpacer 是什么

VideoSpacer定义于flet-video包的 types.py，其官方文档位于 videospacer.md。它继承自按钮栏项基类VideoBarItem，是一类"占位型"内置控件：

@ft.value class VideoSpacer(VideoBarItem): """A built-in spacer item for video controls button bars.""" _type: str = field(default="spacer", init=False, repr=False) """ Identifies this item as a built-in spacer. """ flex: int = 1 """ The flex factor to use for the spacer. """

从源码结构可以推断，VideoSpacer本身不渲染任何可见的按钮或图标，它的职责是在按钮栏中占据一块按比例分配的弹性空白区域，起到分隔和对齐其他按钮项的作用。整个VideoBarItem家族（播放/暂停、上一曲、下一曲、全屏、音量、进度指示器等）都通过_type字段标识自己在 Flutter 端的渲染类型，VideoSpacer的_type固定为"spacer"。

flet-video包的公开导出见init.py，使用时通过import flet_video as ftv即可访问ftv.VideoSpacer。

flex 参数：控制弹性空间的权重

VideoSpacer只有一个对外可配置的参数flex：

flex决定该间隔在按钮栏剩余空间中分配到的比例。按钮栏使用 Flutter 的弹性布局模型：栏内所有设置了flex的弹性项（包括VideoSpacer）会按 flex 数值比例瓜分未被固定尺寸内容占用的剩余宽度。数值越大，该间隔占据的空间越大；flex=0或负值则不会参与弹性分配（从实现上对应 FlutterSpacer的规则）。

典型用法：

ftv.VideoSpacer() # flex=1，普通弹性间隔 ftv.VideoSpacer(flex=2) # flex=2，占据两倍于普通间隔的空间

Flutter 端渲染原理：映射为 Spacer

flet-video是纯 Python 包，底层通过 Flet 协议将控件描述发送给 Flutter 客户端渲染。VideoSpacer的 Flutter 端实现位于 video.dart：

case "spacer": return Spacer(flex: parseInt(value["flex"], 1)!);

当 Flutter 端解析按钮栏项时，遇到_type == "spacer"的分支，会把 Python 侧传来的flex值解析为整数（缺省为1），并直接构造一个 Flutter 的Spacerwidget。也就是说，VideoSpacer在渲染层就是标准的弹性空白组件，其行为与 FlutterRow/Column中的Spacer完全一致。

同时可以看到，parseVideoControlsBarItem会先尝试把该项当作普通 Flet 控件解析，只有当它不是自定义控件、且_type命中内置类型时才会走spacer分支——这意味着你也可以在按钮栏中混用内置项与任意自定义 Flet 控件（如ft.Text、ft.Icon）。

内置默认按钮栏中的 VideoSpacer

flet-video的两套内置控件MaterialVideoControls与MaterialDesktopVideoControls的默认按钮栏布局中都大量使用了VideoSpacer，理解默认布局是自定义的前提。

MaterialVideoControls 主按钮栏默认值

定义于 types.py。当primary_button_bar=None时，原生默认布局为：

[ ftv.VideoSpacer(flex=2), ftv.VideoSkipPreviousButton(), ftv.VideoSpacer(), ftv.VideoPlayOrPauseButton(icon_size=48.0), ftv.VideoSpacer(), ftv.VideoSkipNextButton(), ftv.VideoSpacer(flex=2), ]

可以看到，播放/暂停按钮（icon_size=48.0的大按钮）被三个普通VideoSpacer夹在中间，而两侧用flex=2的加宽间隔将整组按钮推入按钮栏中央，实现"按钮组水平居中、四周留白均匀"的效果。

MaterialVideoControls 底部按钮栏默认值

定义于 types.py：

[ ftv.VideoPositionIndicator(), ftv.VideoSpacer(), ftv.VideoFullscreenButton(), ]

这里VideoSpacer()位于进度指示器与全屏按钮之间，把全屏按钮推到按钮栏最右侧。

MaterialDesktopVideoControls 底部按钮栏默认值

定义于 types.py：

[ ftv.VideoSkipPreviousButton(), ftv.VideoPlayOrPauseButton(), ftv.VideoSkipNextButton(), ftv.VideoSpacer(), ftv.VideoPositionIndicator(), ftv.VideoFullscreenButton(), ftv.VideoVolumeButton(), ]

桌面端默认将传输控制（上一曲/播放暂停/下一曲）放在左侧，VideoSpacer负责把进度指示器与右侧的全屏、音量按钮推向右端，形成"左控制、右辅助"的经典桌面播放器布局。

实战：用 VideoSpacer 定制按钮栏

基础示例：分隔自定义文本与按钮

仓库官方示例 controls_mode/main.py 演示了在不同全屏模式下用VideoSpacer分隔普通 Flet 控件与内置按钮：

import flet as ft import flet_video as ftv def main(page: ft.Page): page.add( ft.SafeArea( expand=True, content=ftv.Video( expand=True, playlist=[ ftv.VideoMedia( "https://user-images.githubusercontent.com/28951144/229373720-14d69157-1a56-4a78-a2f4-d7a134d7c3e9.mp4" ), ], 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(), ], ), }, ), ) ) if __name__ == "__main__": ft.run(main)

关键点：

• controls属性可接收以VideoControlsMode为键的字典，为普通模式与全屏模式分别配置按钮栏；
• ft.Text(...)是普通 Flet 控件，可以与VideoSpacer、VideoPlayOrPauseButton等内置项混排；
• 这里的VideoSpacer()让中间的ft.Text与左右按钮保持等距留白，文本天然居中。

进阶示例：三个按钮栏的完整定制

仓库官方示例 button_bars/main.py 同时定制了主、顶部、底部三个按钮栏，是VideoSpacer最完整的用法参考：

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)

示例要点：

• 未设置primary_button_bar时使用原生默认布局（其中包含VideoSpacer）；
• top_button_bar中，VideoSpacer()将ft.Text("Top button bar")与全屏按钮分离，使全屏按钮右对齐；
• bottom_button_bar中，VideoSpacer()在文本标签与进度指示器之间撑开空白，避免两者紧贴。

使用建议与注意事项

1. 对称布局用flex配比：需要让按钮组水平居中时，仿照默认主按钮栏的做法，左右各放一个VideoSpacer(flex=2)，中间放普通间隔，即可获得对称留白。
2. 弹性项会共享剩余空间：VideoSpacer不占据固定宽度，多个VideoSpacer会按flex比例共同分配剩余空间；若按钮栏空间紧张，间隔会被压缩，因此不要把需要固定留白的区域寄托在flex上，可改用自定义ft.Container设置固定width。
3. flex建议使用正整数：源码类型标注为int，Flutter 端解析时若缺失会回退到默认值1（见 video.dart）；使用非正数可能导致间隔不参与分配，行为与 FlutterSpacer一致。
4. 与自定义 Flet 控件混用：三个按钮栏属性primary_button_bar、top_button_bar、bottom_button_bar的类型均为list[Union[ft.Control, VideoBarItem]]，因此VideoSpacer既可以与内置按钮项搭配，也可以与任意ft.Control（如ft.Text、ft.Icon）混合布局。
5. 用空列表隐藏按钮栏：将对应按钮栏属性设为[]可隐藏该栏；设为None则使用上述内置默认布局（默认布局本身包含VideoSpacer）。

总结

VideoSpacer是flet-video按钮栏布局中不可或缺的"弹性空白"工具，通过单一flex参数即可控制间隔在剩余空间中的分配权重。它在 Python 端由 types.py 定义、在 Flutter 端映射为原生Spacerwidget，并已内置于MaterialVideoControls与MaterialDesktopVideoControls的多套默认按钮栏中。掌握了VideoSpacer的用法，你就能像仓库示例 button_bars/main.py 那样，自由拼装出左中右对齐、留白均匀的自定义视频控制栏。

• 前端
• 跨平台
• 桌面应用
• 移动开发