跳转至

tkfluent ( tkflu )

tkfluent 是现代化 tkinter 第三方界面库，设计采用 winui3 的 sunvalley（或 fluent）设计。

前身

tkfluent 原本是 tkdeft 的默认模板界面库，后面又单独移出

点击查阅 tkdeft 文档

组件画廊

把全部组件摆在一起的画廊：python -m tkflu（浅色主题）

先看这里

  • 安装与第一个窗口

    两条命令就能跑起来

    开始使用

  • 组件总览

    有哪些组件、各自的关键参数与外观

    组件总览

  • 它是怎么搭起来的

    分层、组件内部结构、事件与主题的走向

    架构说明

  • 运行演示

    python -m tkflu 把所有组件摆在一起

    运行演示

  • 渲染引擎与性能

    切换 skia / pillow / cairo，按钮重绘快约 39 倍

    渲染引擎

  • 出问题了

    14 条真实踩过的坑，按症状查

    常见问题

所有组件一眼看完

组件图鉴

组件图鉴（浅色）：每一格都是从真实运行的组件上截下来的， 完整版与深色版见 组件总览

支持的组件

组件 简述 可用程度
FluBadge（FluChip） 徽章组件 ✅完善
FluButton（FluPushButton） 按钮组件 ✅完善
FluCheckBox（FluCheckbox） 多选框组件（含不确定态） ✅完善
FluRadioBox（FluRadioButton） 单选框组件（支持分组） ✅完善
FluEntry（FluTextInput） 输入框组件 ✅较为完善
FluFrame（FluPanel） 容器组件 ✅较为完善
FluImage 图片组件 ✅完善
FluLabel 标签组件 ✅完善
FluLiteNav（FluNavigationView） 轻量导航栏 ✅完善
FluListBox 列表组件（虚拟滚动 / 多选 / 键盘） ✅完善
FluMenuBar 菜单栏组件 ✅较为完善
FluMenu 嵌套在菜单栏的菜单组件 ⚠较为不足
FluPopupMenu 弹出菜单组件 ✅较为完善
FluPopupWindow 弹出窗口 ✅较为完善
FluScrollBar 滚动条组件 ✅较为完善
FluSlider 滑块组件（横向 / 纵向） ✅完善
FluText（FluTextBox） 文本编辑框 ✅较为完善
FluToggleButton 切换按钮组件 ✅完善
FluToolTip 工具提示组件 ✅较为完善
FluToplevel（FluSubWindow） 子窗口组件 ✅较为完善
FluWindow（FluMainWindow） 主窗口组件 ✅较为完善

组件能力边界

  • FluListBox 从 0.4.0 起是真正的列表：条目数据、单选/多选/扩展选择、 键盘导航、滚轮与可拖动的滚动条都由它自己绘制。 想沿用 0.3.0 之前那种"一个圆角矩形 + 居中文字"的老外观， 只传 text= 即可（列表为空时它就是空状态提示）。
  • FluMenu 仍是这一组里最弱的一环：没有键盘导航，accelerator 只是收下不用。
  • FluCheckBox / FluRadioBox 在 0.4.0 之前根本没有实现（前者是个 0 字节 文件，后者连文件都没有），文档里一直标着"暂未开始制作"，现在补齐了。

快速示例

import tkflu

root = tkflu.FluWindow(mode="light")
root.geometry("360x260")

frame = tkflu.FluFrame(root, width=320, height=220)
frame.pack(fill="both", expand=True, padx=15, pady=15)

tkflu.FluLabel(frame, text="你好，tkfluent").pack(anchor="w", padx=10, pady=(10, 4))
tkflu.FluButton(frame, text="点我", command=lambda: print("clicked")).pack(
    fill="x", padx=10, pady=4
)
tkflu.FluEntry(frame, width=280).pack(fill="x", padx=10, pady=4)

root.mainloop()

文档结构

章节 内容
Get Started 开始 安装、上手、第一个应用
Guide 指南 组件总览、架构说明、主题与配色、运行演示、常见问题排查
Tutorial 教程 渲染引擎、主题切换、提示气泡
API 文档 由源码 docstring 自动生成
更新日志 每个版本新增/修复了什么（也在这里发开发记录）

版本与状态
当前版本 0.3.0（与底层 tkdeft 同步发版）
底层依赖 tkdeft >= 0.2.0（渲染引擎层）
无界面自检 python -m tkflu --check（退出码 0 = 通过，CI 可用）
变更记录 更新日志

完整的版本变更（新增了什么、修掉了什么、升级要注意什么）都在 更新日志里，按时间倒序排列。