tkdeft 0.3.0__tar.gz → 0.4.0__tar.gz

{tkdeft-0.3.0 → tkdeft-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tkdeft
-Version: 0.3.0
+Version: 0.4.0
 Summary: 使用tkinter+tksvg开发的现代化界面库
 Author: XiangQinxi
 Author-email: xiangqinxi@outlook.com
@@ -95,6 +95,30 @@ root.mainloop()
 完整文档（安装 / 快速上手 / 概念与架构 / 指南 / API）：
 <https://tkdeft.netlify.app>
 
+`tkdeft.extra` 里放可以直接用的功能，不是成品控件。目前有一个
+[Material 涟漪效果](tkdeft/extra/ripple.py)：给任意控件加一层从按下处扩散的半透明涟漪，
+圆角裁剪、抗锯齿、按时间算进度都处理好，你的按钮长什么样它不管。
+
+```python
+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)
+```
+
+仓库里的 `examples/ripple_button.py` 是接法演示：圆角按钮、悬停/按压/焦点/禁用、
+`T` 换主题都由示例自己画，涟漪只借 `tkdeft.extra.ripple`；它同时带一个非交互自检：
+
+```bash
+python examples/ripple_button.py            # 自动挑栅格引擎（skia > cairo > pillow）
+python examples/ripple_button.py --check    # 只跑自检，不开窗口
+```
+
+写法讲解见文档站的
+[涟漪按钮：可直接用的成品控件](https://tkdeft.netlify.app/usage/ripple-button)。
+
 ## 绘制引擎
 
 `tkdeft` 把"**画什么**"和"**用什么画**"分开了。组件只需要描述一个
@@ -175,6 +199,7 @@ print(cache_stats())       # 缓存命中率，便于诊断
 
 | 版本 | 一句话 | 发布说明 |
 | --- | --- | --- |
+| `0.4.0` | 新增 `tkdeft.extra`：可复用的 Material 涟漪效果（控制器 + 纯函数） | [2026-10-18](docs/docs/blog/posts/2026-10-18-release.md) |
 | `0.3.0` | 把对外接口补齐：统一绘制入口、引擎查询、`DObject` 补全 | [2026-09-13](docs/docs/blog/posts/2026-09-13.md) |
 | `0.2.0` | 可插拔绘制引擎层 + 进程内栅格引擎 + 规格缓存 | [2026-09-12](docs/docs/blog/posts/2026-09-12.md) |
 | `0.1.0` | 完善功能 | [2025-06-26](docs/docs/blog/posts/2025-06-26.md) |

{tkdeft-0.3.0 → tkdeft-0.4.0}/README.md

@@ -65,6 +65,30 @@ root.mainloop()
 完整文档（安装 / 快速上手 / 概念与架构 / 指南 / API）：
 <https://tkdeft.netlify.app>
 
+`tkdeft.extra` 里放可以直接用的功能，不是成品控件。目前有一个
+[Material 涟漪效果](tkdeft/extra/ripple.py)：给任意控件加一层从按下处扩散的半透明涟漪，
+圆角裁剪、抗锯齿、按时间算进度都处理好，你的按钮长什么样它不管。
+
+```python
+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)
+```
+
+仓库里的 `examples/ripple_button.py` 是接法演示：圆角按钮、悬停/按压/焦点/禁用、
+`T` 换主题都由示例自己画，涟漪只借 `tkdeft.extra.ripple`；它同时带一个非交互自检：
+
+```bash
+python examples/ripple_button.py            # 自动挑栅格引擎（skia > cairo > pillow）
+python examples/ripple_button.py --check    # 只跑自检，不开窗口
+```
+
+写法讲解见文档站的
+[涟漪按钮：可直接用的成品控件](https://tkdeft.netlify.app/usage/ripple-button)。
+
 ## 绘制引擎
 
 `tkdeft` 把"**画什么**"和"**用什么画**"分开了。组件只需要描述一个
@@ -145,6 +169,7 @@ print(cache_stats())       # 缓存命中率，便于诊断
 
 | 版本 | 一句话 | 发布说明 |
 | --- | --- | --- |
+| `0.4.0` | 新增 `tkdeft.extra`：可复用的 Material 涟漪效果（控制器 + 纯函数） | [2026-10-18](docs/docs/blog/posts/2026-10-18-release.md) |
 | `0.3.0` | 把对外接口补齐：统一绘制入口、引擎查询、`DObject` 补全 | [2026-09-13](docs/docs/blog/posts/2026-09-13.md) |
 | `0.2.0` | 可插拔绘制引擎层 + 进程内栅格引擎 + 规格缓存 | [2026-09-12](docs/docs/blog/posts/2026-09-12.md) |
 | `0.1.0` | 完善功能 | [2025-06-26](docs/docs/blog/posts/2025-06-26.md) |

{tkdeft-0.3.0 → tkdeft-0.4.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "tkdeft"
-version = "0.3.0"
+version = "0.4.0"
 description = "使用tkinter+tksvg开发的现代化界面库"
 authors = ["XiangQinxi <xiangqinxi@outlook.com>"]
 readme = "README.md"

{tkdeft-0.3.0 → tkdeft-0.4.0}/tkdeft/__init__.py

@@ -7,6 +7,7 @@
 * :mod:`tkdeft.windows` —— ``DCanvas`` / ``DDraw`` / ``DSvgDraw`` / ``DDrawWidget``
 * :mod:`tkdeft.object` —— ``DObject`` 配置容器
 * :mod:`tkdeft.utility` —— 字体等零碎工具
+* :mod:`tkdeft.extra` —— 可选的附加功能（目前是 Material 涟漪效果）
 
 最常用的东西都从顶层再导出一份，所以下面两种写法等价::
 
@@ -44,8 +45,20 @@
 
     if getattr(tkdeft, "HAS_ENGINES", False):
         from tkdeft.engines import set_engine
+
+附加功能
+--------
+:mod:`tkdeft.extra` 里是可以直接拿去用的小功能，它按需加载（用到时才 import
+Pillow 的 ``ImageTk``）::
+
+    from tkdeft.extra.ripple import Ripple
+    from tkdeft import extra          # 等价，懒加载整个子包
 """
 
+from __future__ import annotations
+
+import importlib
+
 from . import engines, svg, utility, windows
 from .engines import (
     DEFAULT_ENGINE_NAME,
@@ -87,21 +100,38 @@ from .windows import (
 
 #: 版本号。tkfluent 会据此判断环境里的 tkdeft 是否够新。
 #: 注意：需要与 pyproject.toml 里的 version 保持一致。
-__version__ = "0.3.0"
+__version__ = "0.4.0"
 
-#: :data:`__version__` 的数字形式，便于比较：``(0, 3, 0)``
+#: :data:`__version__` 的数字形式，便于比较：``(0, 4, 0)``
 __version_info__ = tuple(int(part) for part in __version__.split(".") if part.isdigit())
 
 #: 是否提供绘制引擎层（tkfluent >= 0.2.0 依赖它）。
 #: 旧版本没有这个子包，用它做能力探测比解析版本号更直接。
 HAS_ENGINES = True
 
+
+def __getattr__(name: str):
+    """按需加载 :mod:`tkdeft.extra`。
+
+    ``import tkdeft`` 不应该顺带把 Pillow 的 ``ImageTk`` 和附加功能拉进来，
+    所以这里只在真的用到时再导入::
+
+        from tkdeft import extra          # 触发 __getattr__
+    """
+    if name == "extra":
+        # 用 import_module 而不是 ``from . import extra``：后者会走
+        # ``_handle_fromlist`` → ``getattr(self, "extra")`` → 又回到本函数，无限递归。
+        return importlib.import_module(".extra", __name__)
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+
 __all__ = [
     # 子包
     "engines",
     "svg",
     "utility",
     "windows",
+    "extra",
     # 版本与能力探测
     "__version__",
     "__version_info__",

tkdeft-0.4.0/tkdeft/extra/__init__.py

@@ -0,0 +1,42 @@
+"""tkdeft.extra —— 用核心零件做的可复用功能（不是成品控件）。
+
+核心包只提供零件（画布、绘制后端、配置容器），这里放**可以直接拿去用的小功能**，
+每个模块自成一体、按需加载。
+
+当前内容：
+
+* :mod:`tkdeft.extra.ripple` —— Material 涟漪效果：一个管理状态与计时的
+  :class:`~tkdeft.extra.ripple.Ripple`，加上算出半透明图层的
+  :func:`~tkdeft.extra.ripple.ripple_layer`。它不提供按钮，
+  你给自己的控件加三行调用就能用::
+
+      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="#000", opacity=0.12)      # ③ 在重绘里贴一层
+"""
+
+from .ripple import (
+    FRAME_MS,
+    RIPPLE_MS,
+    SUPERSAMPLE,
+    Ripple,
+    RippleState,
+    ease_out_cubic,
+    ripple_alpha,
+    ripple_layer,
+    ripple_radius,
+)
+
+__all__ = [
+    "Ripple",
+    "RippleState",
+    "RIPPLE_MS",
+    "FRAME_MS",
+    "SUPERSAMPLE",
+    "ease_out_cubic",
+    "ripple_alpha",
+    "ripple_radius",
+    "ripple_layer",
+]

tkdeft-0.4.0/tkdeft/extra/ripple.py

@@ -0,0 +1,370 @@
+"""Material 涟漪效果的可复用零件：给任意画布控件加一层涟漪。
+
+这里**不含按钮**。控件的外观、状态、文字都由你自己画，只用这里的三样东西：
+
+* :func:`ripple_layer` —— 算出某一帧的 RGBA 图层（圆角裁剪 + 抗锯齿 + 半透明）；
+* :class:`Ripple` —— 管理「谁在扩散、扩散到哪了」，到点回调你重绘；
+* :func:`ease_out_cubic` / :func:`ripple_alpha` —— 想自己控制节奏时改这两条曲线。
+
+接到已有控件上通常只加三处::
+
+    from tkdeft.extra.ripple import Ripple
+
+    class MyButton(DDrawWidget):
+        def __init__(self, master, **kwargs):
+            super().__init__(master, **kwargs)
+            self.ripple = Ripple(self, on_frame=self._paint)
+
+        def _paint(self):
+            self.delete("all")
+            ...画底色...
+            self.ripple.paint(color="#000000", opacity=0.12, corner_radius=8)
+            ...画文字...
+
+        def _event_on_button1(self, event):
+            super()._event_on_button1(event)
+            self.ripple.start(event.x, event.y)
+
+每帧重绘由你决定：``Ripple`` 不碰 canvas item，只在 ``on_frame`` 时叫你一声，
+所以涟漪压在哪一层、和文字谁先谁后，完全由 ``paint()`` 的调用位置决定。
+
+不依赖 ``DDrawWidget`` 也行——任何有 ``create_image`` / ``winfo_width`` 的控件都能用。
+"""
+
+from __future__ import annotations
+
+import math
+import time
+from dataclasses import dataclass
+from typing import Callable, Dict, List, Optional
+
+from PIL import Image, ImageChops, ImageDraw, ImageTk
+
+__all__ = [
+    "RIPPLE_MS",
+    "FRAME_MS",
+    "SUPERSAMPLE",
+    "Ripple",
+    "RippleState",
+    "ease_out_cubic",
+    "ripple_alpha",
+    "ripple_radius",
+    "ripple_layer",
+]
+
+#: 一次涟漪的总时长（毫秒）。Material 规范里大控件约 450–600ms。
+RIPPLE_MS = 500
+
+#: 动画帧间隔。16ms 约等于 60fps；渲染跟不上时 Tk 会自然丢帧。
+FRAME_MS = 16
+
+#: 栅格化涟漪时的超采样倍率（最后缩小，边缘才不锯齿）。
+SUPERSAMPLE = 3
+
+
+# ----------------------------------------------------------------------
+# 数学与图层
+# ----------------------------------------------------------------------
+def ease_out_cubic(progress: float) -> float:
+    """Material 的「减速」曲线：起步快、收尾慢。
+
+    :param progress: ``0``–``1`` 的播放进度（超出范围会被夹到端点上）
+    :returns: ``0``–``1`` 的缓动值
+    """
+    progress = min(1.0, max(0.0, progress))
+    return 1.0 - (1.0 - progress) ** 3
+
+
+def ripple_alpha(progress: float, peak: float = 0.12) -> float:
+    """涟漪的不透明度：前 15% 淡入，之后按幂曲线淡出。
+
+    :param progress: ``0``–``1`` 的播放进度
+    :param peak: 最浓时的 alpha
+    :returns: 该帧的 alpha；进度 0 与 1 都返回 ``0``
+    """
+    if progress <= 0.0 or progress >= 1.0:
+        return 0.0
+    fade_in = min(1.0, progress / 0.15)
+    fade_out = max(0.0, 1.0 - (progress - 0.15) / 0.85) ** 1.2
+    return peak * fade_in * fade_out
+
+
+def ripple_radius(width: float, height: float, x: float, y: float) -> float:
+    """从 ``(x, y)`` 到最远角的距离——涟漪扩到它才算盖满整个控件。
+
+    :param width: 控件宽度
+    :param height: 控件高度
+    :param x: 圆心 x
+    :param y: 圆心 y
+    :returns: 需要扩散到的半径
+    """
+    return max(
+        math.hypot(corner_x - x, corner_y - y)
+        for corner_x, corner_y in ((0, 0), (width, 0), (0, height), (width, height))
+    )
+
+
+def ripple_layer(
+    width: int,
+    height: int,
+    corner_radius: float,
+    x: float,
+    y: float,
+    progress: float,
+    color: str = "#000000",
+    peak_opacity: float = 0.12,
+) -> Image.Image:
+    """算出某一帧的涟漪图层（RGBA，尺寸就是控件尺寸）。
+
+    为什么不用 ``Canvas.create_oval``：Tk 的 canvas item 没有 alpha——
+    给 item 设 ``-alpha`` 是整块位图的透明度，而且**圆角遮不住**。
+    这里改成在 Pillow 里先画「圆 ∩ 圆角矩形」的遮罩，再整体缩小：
+    半透明、圆角裁剪、抗锯齿就都对了。
+
+    :param width: 控件宽度（像素）
+    :param height: 控件高度（像素）
+    :param corner_radius: 控件圆角半径，用来裁剪涟漪（矩形控件传 ``0``）
+    :param x: 涟漪圆心 x（控件坐标）
+    :param y: 涟漪圆心 y
+    :param progress: ``0``–``1`` 的播放进度
+    :param color: 涟漪颜色
+    :param peak_opacity: 最浓时的 alpha
+    :returns: 与控件等大的 RGBA 图层，进度 0/1 时完全透明
+    """
+    width = int(round(width))
+    height = int(round(height))
+    layer = Image.new("RGBA", (max(width, 1), max(height, 1)), (0, 0, 0, 0))
+    opacity = ripple_alpha(progress, peak_opacity)
+    if width <= 0 or height <= 0 or opacity <= 0.0:
+        return layer
+
+    scale = SUPERSAMPLE
+    size = (width * scale, height * scale)
+
+    # 1) 圆角矩形遮罩：涟漪不能漫出圆角
+    clip = Image.new("L", size, 0)
+    ImageDraw.Draw(clip).rounded_rectangle(
+        (0, 0, size[0] - 1, size[1] - 1), radius=corner_radius * scale, fill=255
+    )
+
+    # 2) 当前半径的圆
+    r = ripple_radius(width, height, x, y) * ease_out_cubic(progress) * scale
+    circle = Image.new("L", size, 0)
+    ImageDraw.Draw(circle).ellipse(
+        (x * scale - r, y * scale - r, x * scale + r, y * scale + r), fill=255
+    )
+
+    # 3) 交集 = 圆 ∩ 圆角矩形（darker 逐像素取较小值），再缩小做抗锯齿
+    mask = ImageChops.darker(clip, circle).resize((width, height), Image.LANCZOS)
+    mask = mask.point(lambda value: int(value * opacity))
+
+    layer = Image.new("RGBA", (width, height), color)
+    layer.putalpha(mask)
+    return layer
+
+
+# ----------------------------------------------------------------------
+# 状态与动画
+# ----------------------------------------------------------------------
+@dataclass
+class RippleState:
+    """一次涟漪：圆心、开始时刻，以及「现在播到哪了」。"""
+
+    x: float
+    y: float
+    started: float
+
+    def progress(self, duration: float = RIPPLE_MS) -> float:
+        """当前进度（``0``–``1``），按 ``time.monotonic()`` 现算。"""
+        elapsed_ms = (time.monotonic() - self.started) * 1000.0
+        return min(1.0, max(0.0, elapsed_ms / duration))
+
+
+class Ripple:
+    """把涟漪接到一个控件上：只管状态与计时，绘制时机交给你。
+
+    :param widget: 宿主控件（``DCanvas`` / ``DDrawWidget`` 或任何有
+        ``create_image`` / ``winfo_width`` 的 Tk 控件）；用来取尺寸、贴图层
+    :param on_frame: 每帧回调，通常是宿主自己的重绘方法；``None`` 表示不自动刷新
+    :param duration: 一次涟漪的时长（毫秒），默认 :data:`RIPPLE_MS`
+    :param frame_ms: 帧间隔（毫秒），默认 :data:`FRAME_MS`
+
+    控制器不保存颜色：颜色/浓度/圆角都在 :meth:`paint` 时传进来，所以同一份
+    状态可以跟着主题换色，不需要重建对象。
+    """
+
+    def __init__(
+        self,
+        widget,
+        on_frame: Optional[Callable[[], None]] = None,
+        *,
+        duration: float = RIPPLE_MS,
+        frame_ms: int = FRAME_MS,
+    ):
+        self.widget = widget
+        self.on_frame = on_frame
+        self.duration = duration
+        self.frame_ms = frame_ms
+
+        self._states: List[RippleState] = []
+        self._job: Optional[str] = None
+        self._photos: Dict[int, object] = {}
+
+        # 宿主被销毁时把 after 撤掉，免得回调打到已销毁的控件上
+        try:
+            widget.bind("<Destroy>", self._event_destroy, add="+")
+        except Exception:            # 不是 Tk 控件（测试替身）就跳过
+            pass
+
+    # ------------------------------------------------------------------
+    # 状态
+    # ------------------------------------------------------------------
+    @property
+    def states(self) -> List[RippleState]:
+        """正在播放的涟漪（只读副本，按开始顺序）。"""
+        return list(self._states)
+
+    @property
+    def active(self) -> bool:
+        """是否还有涟漪在播。"""
+        return bool(self._states)
+
+    def start(
+        self,
+        x: Optional[float] = None,
+        y: Optional[float] = None,
+        started: Optional[float] = None,
+    ) -> RippleState:
+        """从 ``(x, y)`` 起播一次涟漪；不传坐标按控件中心算。
+
+        :param x: 圆心 x（控件坐标）
+        :param y: 圆心 y
+        :param started: 起始时刻（``time.monotonic()``）；给自检/截图复现用，
+            传 ``time.monotonic() - 0.2`` 就等于快进到 40% 进度
+        :returns: 新加入的状态，可用它自己算进度
+        """
+        if x is None:
+            x = self.widget.winfo_width() / 2.0
+        if y is None:
+            y = self.widget.winfo_height() / 2.0
+        state = RippleState(
+            float(x), float(y), time.monotonic() if started is None else started
+        )
+        self._states.append(state)
+        self._schedule()
+        return state
+
+    def stop(self) -> None:
+        """立刻停掉所有涟漪并撤掉计时器。"""
+        self._stop_tick()
+        self._states.clear()
+
+    def advance(self) -> None:
+        """丢掉已经播完的涟漪（一般不用手调，内部计时器会做）。"""
+        self._states = [
+            state for state in self._states if state.progress(self.duration) < 1.0
+        ]
+
+    # ------------------------------------------------------------------
+    # 计时
+    # ------------------------------------------------------------------
+    def _schedule(self) -> None:
+        if self._job is None and self._states:
+            self._job = self.widget.after(self.frame_ms, self._tick)
+
+    def _stop_tick(self) -> None:
+        if self._job is not None:
+            self.widget.after_cancel(self._job)
+            self._job = None
+
+    def _tick(self) -> None:
+        self._job = None
+        if not self._states:
+            return
+        self.advance()
+        self._notify()
+        self._schedule()
+
+    def _notify(self) -> None:
+        if self.on_frame is not None:
+            self.on_frame()
+
+    # ------------------------------------------------------------------
+    # 绘制
+    # ------------------------------------------------------------------
+    def paint(
+        self,
+        color: str = "#000000",
+        opacity: float = 0.12,
+        corner_radius: float = 0.0,
+        tag: str = "ripple",
+    ) -> int:
+        """把所有正在播的涟漪画到宿主控件上，返回最后一张图层对应的 item。
+
+        在你自己的 ``_paint`` 里调用——位置决定层级：先画底色再调它，
+        涟漪就在底色之上；之后再画文字，文字就在最上面。
+
+        :param color: 涟漪颜色
+        :param opacity: 最浓时的 alpha
+        :param corner_radius: 控件圆角半径；矩形控件传 ``0``
+        :param tag: 给贴图打的 canvas tag，方便宿主用 ``delete(tag)`` 单独清理
+        :returns: 最后一张图层对应的 canvas item id；没有涟漪时返回 ``0``
+        """
+        self._prune_photos()
+        width = self.widget.winfo_width()
+        height = self.widget.winfo_height()
+        if width <= 1 or height <= 1:
+            return 0
+
+        last = 0
+        for state in self._states:
+            progress = state.progress(self.duration)
+            if progress >= 1.0:
+                continue
+            layer = ripple_layer(
+                width,
+                height,
+                corner_radius,
+                state.x,
+                state.y,
+                progress,
+                color=color,
+                peak_opacity=opacity,
+            )
+            photo = ImageTk.PhotoImage(layer, master=self.widget)
+            item = self.widget.create_image(
+                0, 0, anchor="nw", image=photo, tags=(tag,)
+            )
+            self._keep_photo(item, photo)
+            last = item
+        return last
+
+    def _keep_photo(self, item: int, photo) -> None:
+        """Tk 不会自己保住 PhotoImage：交给 DCanvas 的缓存，否则自己记账。"""
+        keep = getattr(self.widget, "_keep_photo", None)
+        if callable(keep):
+            keep(item, photo)
+            return
+        if hasattr(self.widget, "_photo_refs") and isinstance(
+            self.widget._photo_refs, dict
+        ):
+            self.widget._photo_refs[item] = photo
+            return
+        self._photos[item] = photo
+
+    def _prune_photos(self) -> None:
+        """删掉已被宿主 ``delete`` 过的 item 对应的照片引用。"""
+        if not self._photos:
+            return
+        stale = [item for item in self._photos if not self.widget.type(item)]
+        for item in stale:
+            del self._photos[item]
+
+    # ------------------------------------------------------------------
+    # 生命周期
+    # ------------------------------------------------------------------
+    def _event_destroy(self, event=None) -> None:
+        if event is not None and getattr(event, "widget", None) is not self.widget:
+            return
+        self._stop_tick()
+        self._states.clear()

{tkdeft-0.3.0 → tkdeft-0.4.0}/tkdeft/windows/canvas.py

@@ -99,11 +99,21 @@ class DCanvas(Canvas):
         return item
 
     def _prune_photo_refs(self):
-        """丢掉已经不在画布上的 item 所对应的图片引用。"""
+        """丢掉已经不在画布上的 item 所对应的图片引用。
+
+        .. note::
+           判定"这个 item 还在不在"必须用 ``type()`` 的**返回值**：
+           对已经删除的 item，Tk 返回的是 ``None`` 而不是抛异常。
+           旧实现写成 ``except`` 收集，于是**一个也清不掉**——
+           控件每重绘一次（每次 ``<Configure>``、每帧动画）就往
+           ``_photo_refs`` 里多塞一个引用，直到超过阈值后每次
+           ``_keep_photo`` 都要全表扫一遍，退化成平方复杂度。
+        """
         stale = []
         for item in self._photo_refs:
             try:
-                self.type(item)
+                if not self.type(item):
+                    stale.append(item)
             except Exception:
                 stale.append(item)
         for item in stale: