跳转至

版本

发布 0.4.0:新增 tkdeft.extra 与 Material 涟漪效果

0.4.0 是纯加法:核心包一行没改,旧代码原样能跑。新增的是一个可选的子包, 以及里面第一个可以直接拿去用的效果。

tkdeft.extra

核心包继续只提供零件(画布、绘制后端、配置容器);"用零件做出来的东西"以后放 tkdeft.extra,按需加载——import tkdeft 不会顺带把 Pillow 的 ImageTk 拉起来。

from tkdeft import extra          # 懒加载整个子包
from tkdeft.extra.ripple import Ripple

涟漪效果:tkdeft.extra.ripple

它不提供按钮,只提供涟漪本身,所以任何控件都能用:

from tkdeft.extra.ripple import Ripple

self.ripple = Ripple(self, on_frame=self._paint)   # ① 建控制器
self.ripple.start(event.x, event.y)                # ② 点击处起涟漪
self.ripple.paint(color="#000000", opacity=0.12,   # ③ 在重绘里贴一层
                  corner_radius=8)

导出内容:

  • Ripple(widget, on_frame=None, *, duration=500, frame_ms=16) —— 管理状态与计时, 有 start() / paint() / stop() / active / states;
  • ripple_layer() —— 算出某一帧的 RGBA 图层(圆角裁剪 + 抗锯齿 + 半透明);
  • ripple_alpha() / ripple_radius() / ease_out_cubic() —— 浓度、半径、缓动三条曲线。

控制器不碰 canvas item、也不存颜色:贴在哪一层、跟不跟主题换色,都由宿主决定。 不依赖 DDrawWidget 也行,任何有 create_image / winfo_width 的控件都能接。

示例与文档

examples/ripple_button.py 里有一个完整按钮作为接法参照(圆角底色、悬停 / 按压 / 焦点 / 禁用、空格触发、T 换主题),并带非交互自检:

python examples/ripple_button.py --check

新文档页 涟漪效果:给任意控件加一层扩散动画 先讲三步接上,再拆遮罩、曲线、计时与图片保活,最后是三个真实踩过的坑。

升级

无需改代码。想用新功能:

pip install -U tkdeft

0.3.x 的 API 全部保留,tkdeft.extra 只是新目录。

发布 0.3.0:把接口补齐、讲清楚

这一版没有新组件,做的是把 tkdeft 的对外接口补齐、并让 tkfluent 用上它们; 绘制结果与 0.2.0 逐项一致(24 个按钮状态 × 5 引擎的像素差没有变化)。

绘制引擎层

  • 引擎注册表补充 available_engines() / engine_names() / engine_index() / engine_from_index() / describe_engines() / reset_engine() / unregister_engine()
  • 引擎基类新增 render(spec)(按规格类型自动分发)、supports(kind)、info()、index
  • 拼错引擎名不再静默退回慢路径,而是抛 UnknownEngineError (ValueError 子类,带"你是不是想用 …"的提示)
  • 渲染入口新增 render(spec) 与 RENDERERS; 渲染失败可用 last_engine_error() / clear_engine_error() 查询
  • 三种规格补齐 from_box()(按坐标对构造)、pixels、to_dict()、describe()、kind

画布层

  • DCanvas 新增统一绘制入口 draw_roundrect() / draw_track() / draw_thumb(): 有栅格引擎就走位图快速路径,否则自动回退 SVG,返回值一定是 item id
  • 新增可覆盖的 SVG 钩子 draw_roundrect_svg() / draw_track_svg() / draw_thumb_svg() 与 draw_svg_item()——组件不必再抄一遍回退逻辑
  • raster_enabled 属性 / raster=False 参数可以强制走 SVG(做引擎对照时很方便)

绘制后端

  • DSvgDraw 补齐通用图元 create_roundrect() / create_track() / create_thumb()
  • create_svg_image(..., way=None) 默认按当前引擎自动挑 tksvg / Wand
  • tkdeft.svg 新增 svg_paint() / gradient_stop(): None 与 "transparent" 不再让 svgwrite 抛 TypeError—— 以前同一份 RoundRectSpec(outline=None) 在 skia 上正常、换 tksvg 就崩

基础件

  • DObject 补全 dget / dhas / dkeys / dvalues / ditems / dcopy / dreset, dcget(key, default) 可给默认值;实例现在拥有自己的属性字典,不再共享类级默认值
  • 顶层 tkdeft 再导出常用名字;新增 __version_info__

文档

tkfluent 同步

9 个组件里"栅格优先 + SVG 回退"的样板代码收敛到 tkdeft (button / badge / togglebutton / entry / text / listbox / frame / scrollbar / slider, 净删约 400 行)。同时修掉两个被回归漏掉的缺陷:

  • FluListBox.theme() 用参数 style 判断分支 → 点"切换主题"直接崩;
  • --check 自检用 except AttributeError: continue 跳过"没有钩子"的组件, 把钩子内部的 AttributeError 一起吞了——这也是上面那个 bug 一直没被发现的原因。

升级建议

0.3.0 是纯加法:旧代码原样能跑。想顺手改的地方见 从 0.2 升级到 0.3。

发布 0.2.0:可插拔的绘制引擎层

这一版把"画什么"和"用什么画"彻底分开了,并修掉一批长期存在的真实缺陷。

新东西

  • 新增 tkdeft.engines 绘制引擎层,可插拔切换 tksvg / wand / skia / pillow / cairo
  • 新增三个进程内栅格引擎(skia-python / Pillow / pycairo),完全不落盘; 其中 Pillow 引擎零额外依赖、永远可用
  • 新增按规格的图片缓存:RoundRectSpec 是不可变的,同尺寸同配色的一组控件 共用同一张 PhotoImage
  • 新增 SVG 形状助手 tkdeft.svg,统一并修正圆角矩形几何

修掉的缺陷

问题 影响
DSvgDraw.temppath() 每帧 mkstemp() 且从不关闭 fd 每绘制一帧泄漏一个句柄 + 一个残留文件
DDrawWidget.__init__ 一次性建 4 个临时文件 每个控件创建即泄漏 4 个句柄
只把图片存进 self._tkimg 同一画布上多张图片时,除最后一张外都会被 GC,画布 item 变空白
RenderManager 调用 widget.winfo_zorder() tkinter 没有这个方法,有脏控件就抛 AttributeError
svgwrite 矩形用 translate(0.5,0.5) + 整宽整高 描边中心线压在画布边界上,外侧半个线宽被裁掉

细节见常见问题与排查。

性能

栅格引擎配合规格缓存后,按钮重绘快约 39 倍、hover 往返约 52 倍 (本机 120×32 圆角矩形实测)。复现:python benchmarks/run_all.py。

发布 0.1.0

完善功能。这一版之后,tkdeft 的定位开始明确为"tkfluent 的底层零件库": 只提供把矢量图变成 Tkinter 控件所需的零件,不含具体组件。

发布 0.0.9

一些小修改。

早期版本回顾(0.0.1 – 0.0.7)

这几版是 tkdeft 起步阶段的记录,日期沿用最早那份更新日志。

版本 内容
0.0.7 模板库 Fluent 拆出去,成为独立的 tkfluent
0.0.6 模板组件 DBadge 增加 style=accent,调整自定义窗口
0.0.5 主题改为 theme(mode=..., style=...),不再需要 DDarkButton 这类成对的组件;新增 DWindow.wincustom 自定义窗口(仅 Windows)
0.0.3 / 0.0.4 补依赖(两次)
0.0.2 补充模板组件 DEntry、DFrame、DText、DBadge(详见 2024-01-25)
0.0.1 首个版本,模板组件 DButton

从这里开始,tkdeft 的方向就定下来了:用矢量绘图生成图片,再交给 Canvas / Label 显示, 具体走 SVG 还是进程内栅格化,交给可插拔的引擎决定。