ctk-kit 0.1.0__py3-none-any.whl

ctk_kit/inputs.py

@@ -0,0 +1,160 @@
+"""输入控件：工具栏搜索框、分段选择、表单输入框。
+
+分段选择（CTkSegmentedButton）有几个必须显式指定的参数，否则深浅色的观感
+会不一致：
+
+- ``fg_color`` / ``unselected_color`` 用输入框底色，否则默认是灰色
+- ``selected_color`` 用淡强调色，避免整块高饱和蓝
+- ``dynamic_resizing=False`` 否则切换选项会改控件宽度，把右边的元素挤动
+- 不能传 ``border_width`` / ``border_color``，CTk 会直接抛 ValueError
+
+所有工厂只返回控件，不负责摆位。
+"""
+
+from __future__ import annotations
+
+import tkinter as tk
+from typing import Callable, Optional, Sequence
+
+import customtkinter as ctk
+
+from . import tokens as T
+
+# 分段选择的选中回调：收到被选中的那一段文字。
+SegmentCommand = Optional[Callable[[str], None]]
+# 开关回调：不接收参数（CTk 的约定）。
+SwitchCommand = Optional[Callable[[], None]]
+
+
+def toolbar_entry(master: tk.Misc, placeholder: str, *, height: int = 40) -> ctk.CTkEntry:
+    """页面顶部搜索框：聚焦时描边变强调色。
+
+    参数:
+        master: 父容器。
+        placeholder: 未输入时显示的灰色占位文字。
+        height: 高度（像素），默认 40。
+
+    返回:
+        已经绑好焦点样式、尚未摆位的 ``CTkEntry``。
+    """
+    entry = ctk.CTkEntry(
+        master,
+        placeholder_text=placeholder,
+        placeholder_text_color=T.COLOR_FAINT,
+        height=height,
+        corner_radius=T.RADIUS_LARGE,
+        font=T.FONT_BODY,
+        fg_color=T.COLOR_INPUT,
+        border_color=T.COLOR_BORDER,
+        border_width=1,
+        text_color=T.COLOR_TEXT,
+    )
+    entry.bind("<FocusIn>", lambda _event: entry.configure(border_color=T.COLOR_ACCENT))
+    entry.bind(
+        "<FocusOut>", lambda _event: entry.configure(border_color=T.COLOR_BORDER)
+    )
+    return entry
+
+
+def form_entry(
+    master: tk.Misc,
+    *,
+    show: str = "",
+    placeholder: str = "",
+    height: int = 38,
+    password: bool = False,
+) -> ctk.CTkEntry:
+    """表单里的单行输入。
+
+    ``password=True`` 时用圆点打码。注意 CTkEntry 带了 ``placeholder_text``
+    时，内部 Entry 的 ``show`` 会被占位符机制置空，``cget("show")`` 读到的是
+    空字符串——要判断是否在打码，得自己记住状态，别去读控件。
+
+    参数:
+        master: 父容器。
+        show: 自定义替代字符（例如 ``"*"``），空字符串表示正常显示。
+        placeholder: 未输入时的灰色占位文字。
+        height: 高度（像素），默认 38。
+        password: 为 ``True`` 时用圆点 ``"•"`` 打码，优先级高于 ``show``。
+
+    返回:
+        尚未摆位的 ``CTkEntry``。
+    """
+    return ctk.CTkEntry(
+        master,
+        show=("•" if password else show) or "",
+        placeholder_text=placeholder,
+        placeholder_text_color=T.COLOR_FAINT,
+        height=height,
+        corner_radius=T.RADIUS_SMALL,
+        font=T.FONT_BODY,
+        fg_color=T.COLOR_INPUT,
+        border_color=T.COLOR_BORDER,
+        border_width=1,
+        text_color=T.COLOR_TEXT,
+    )
+
+
+def segmented(
+    master: tk.Misc,
+    values: Sequence[str],
+    command: SegmentCommand = None,
+    *,
+    width: int = 300,
+    height: int = 34,
+    font: T.FontSpec = T.FONT_SMALL,
+) -> ctk.CTkSegmentedButton:
+    """统一样式的分段选择：底色同输入框，选中段淡色高亮。
+
+    参数:
+        master: 父容器。
+        values: 各段文字，按显示顺序排列；非空时默认选中第一项。
+        command: 切换回调，参数是被选中的那一段文字。
+        width: 整体宽度（像素），默认 300；``dynamic_resizing=False`` 保证
+            切换选项时宽度不变。
+        height: 高度（像素），默认 34。
+        font: 字体规格，默认 :data:`tokens.FONT_SMALL`。
+
+    返回:
+        尚未摆位的 ``CTkSegmentedButton``。
+    """
+    button = ctk.CTkSegmentedButton(
+        master,
+        values=values,
+        width=width,
+        height=height,
+        corner_radius=T.RADIUS_SMALL,
+        fg_color=T.COLOR_INPUT,
+        unselected_color=T.COLOR_INPUT,
+        selected_color=T.COLOR_SEG_SELECTED,
+        unselected_hover_color=T.COLOR_SOFT,
+        selected_hover_color=T.COLOR_SEG_SELECTED,
+        text_color=T.COLOR_TEXT,
+        font=font,
+        dynamic_resizing=False,
+        command=command,
+    )
+    if values:
+        # 不留「一段都没选中」的中间态
+        button.set(values[0])
+    return button
+
+
+def switch(master: tk.Misc, command: SwitchCommand = None, *, width: int = 44) -> ctk.CTkSwitch:
+    """设置页的开关：去掉文字，只留轨道，颜色跟随主色。
+
+    参数:
+        master: 父容器。
+        command: 拨动回调，不接收参数；用 ``toggle()`` 或点击都会触发。
+        width: 开关宽度（像素），默认 44；卡片里的紧凑尺寸可以传 60 / 40。
+
+    返回:
+        尚未摆位的 ``CTkSwitch``。
+    """
+    return ctk.CTkSwitch(
+        master,
+        text="",
+        width=width,
+        progress_color=T.COLOR_ACCENT,
+        command=command,
+    )

ctk_kit/layout.py

@@ -0,0 +1,194 @@
+"""页面骨架：页头、分区卡片、分隔线、滚动容器、空状态。
+
+一套页面按这个顺序搭出来，视觉就不会散：
+
+    page_header  →  section(title)  →  card 里的若干行  →  divider  →  footer
+
+除滚动容器外，这里的工厂都会顺手 ``pack``（``fill="x"``），因为它们的位置
+在页面骨架里是固定的；按钮、输入框这类需要自己摆位。
+"""
+
+from __future__ import annotations
+
+import tkinter as tk
+
+import customtkinter as ctk
+
+from . import tokens as T
+
+
+def page_header(master: tk.Misc, title: str) -> tuple[ctk.CTkFrame, ctk.CTkLabel]:
+    """页面顶部：左边标题，右边统计信息。
+
+    返回 ``(容器, 信息标签)``，调用方拿到信息标签后自己 ``configure(text=...)``，
+    容器已经 ``pack(fill="x")``。
+
+    参数:
+        master: 父容器。
+        title: 左侧大标题。
+
+    返回:
+        ``(head, info)``：``head`` 是透明容器，``info`` 是右侧灰色小字标签。
+    """
+    head = ctk.CTkFrame(master, fg_color="transparent")
+    head.pack(fill="x")
+    ctk.CTkLabel(head, text=title, font=T.FONT_TITLE, text_color=T.COLOR_TEXT).pack(
+        side="left"
+    )
+    info = ctk.CTkLabel(
+        head, text="", font=T.FONT_TINY, text_color=T.COLOR_MUTED, anchor="e"
+    )
+    info.pack(side="right", pady=(9, 0))
+    return head, info
+
+
+def section_title(master: tk.Misc, text: str) -> ctk.CTkLabel:
+    """分区标题（设置页的「外观」「备份」这一层）。
+
+    参数:
+        master: 父容器。
+        text: 标题文字。
+
+    返回:
+        已 ``pack(fill="x", pady=(16, 6))`` 的标签。
+    """
+    label = ctk.CTkLabel(
+        master, text=text, font=T.FONT_SECTION, text_color=T.COLOR_TEXT, anchor="w"
+    )
+    label.pack(fill="x", pady=(T.SPACE_LG, T.SPACE_SM - 2))
+    return label
+
+
+def card(master: tk.Misc) -> ctk.CTkFrame:
+    """圆角卡片容器：内容都往这里放。
+
+    参数:
+        master: 父容器。
+
+    返回:
+        已 ``pack(fill="x")`` 的卡片 Frame（1px 边框、10 圆角）。
+    """
+    frame = ctk.CTkFrame(
+        master,
+        fg_color=T.COLOR_CARD,
+        border_width=1,
+        border_color=T.COLOR_BORDER,
+        corner_radius=T.RADIUS_MEDIUM,
+    )
+    frame.pack(fill="x")
+    return frame
+
+
+def divider(master: tk.Misc, *, pady: tuple[int, int] = (T.SPACE_MD, 0)) -> ctk.CTkFrame:
+    """1px 分隔线；用 Frame 而不是 ttk.Separator，颜色好控制。
+
+    参数:
+        master: 父容器。
+        pady: ``(上, 下)`` 外边距，默认 ``(12, 0)``。
+
+    返回:
+        已 ``pack(fill="x")`` 的 1px 高 Frame。
+    """
+    line = ctk.CTkFrame(master, height=1, fg_color=T.COLOR_BORDER)
+    line.pack(fill="x", pady=pady)
+    return line
+
+
+def style_scrollable(frame: ctk.CTkScrollableFrame) -> ctk.CTkScrollableFrame:
+    """把 CTkScrollableFrame 的滚动条调成窄条淡色。
+
+    CTkScrollableFrame 的滚动条藏在 ``_scrollbar`` 私有属性里，只能这样拿；
+    CTk 升级时如果改名，这里会静默失效（不报错，只是回到默认样式）。
+
+    参数:
+        frame: ``CTkScrollableFrame`` 实例；传入其它控件时原样返回。
+
+    返回:
+        同一个 ``frame``，方便链式调用。
+    """
+    bar = getattr(frame, "_scrollbar", None)
+    if bar is not None:
+        bar.configure(
+            width=T.SCROLLBAR_WIDTH,
+            fg_color="transparent",
+            button_color=T.COLOR_SCROLLBAR,
+            button_hover_color=T.COLOR_SCROLLBAR_HOVER,
+        )
+    return frame
+
+
+def scrollable(master: tk.Misc) -> ctk.CTkScrollableFrame:
+    """已经配好滚动条样式的滚动容器（透明底）。
+
+    参数:
+        master: 父容器。
+
+    返回:
+        尚未摆位的 ``CTkScrollableFrame``；由调用方决定 ``pack`` 还是 ``grid``。
+    """
+    return style_scrollable(ctk.CTkScrollableFrame(master, fg_color="transparent"))
+
+
+def empty_hint(master: tk.Misc, title: str, detail: str = "") -> ctk.CTkFrame:
+    """居中的空状态：一行主提示 + 一行补充说明。
+
+    参数:
+        master: 父容器。
+        title: 主提示（如「这里还没有内容」）。
+        detail: 补充说明；为空时只显示一行。
+
+    返回:
+        透明容器，已经装好 1~2 行灰色文字；摆放由调用方决定。
+    """
+    box = ctk.CTkFrame(master, fg_color="transparent")
+    ctk.CTkLabel(box, text=title, font=T.FONT_BODY, text_color=T.COLOR_MUTED).pack()
+    if detail:
+        ctk.CTkLabel(
+            box,
+            text=detail,
+            font=T.FONT_SMALL,
+            text_color=T.COLOR_MUTED,
+            justify="center",
+        ).pack(pady=(6, 0))
+    return box
+
+
+def field_label(master: tk.Misc, text: str, *, width: int = 112) -> ctk.CTkLabel:
+    """卡片内左对齐的字段名，宽度固定让右边控件能对齐成一列。
+
+    参数:
+        master: 父容器。
+        text: 字段名。
+        width: 固定宽度（像素），默认 112。
+
+    返回:
+        尚未摆位的 ``CTkLabel``（``anchor="w"``）。
+    """
+    return ctk.CTkLabel(
+        master,
+        text=text,
+        font=T.FONT_SMALL,
+        text_color=T.COLOR_MUTED,
+        width=width,
+        anchor="w",
+    )
+
+
+def hint_label(master: tk.Misc, text: str) -> ctk.CTkLabel:
+    """字段下方的说明文字。
+
+    参数:
+        master: 父容器。
+        text: 说明内容，支持 ``\\n`` 换行。
+
+    返回:
+        尚未摆位的 ``CTkLabel``（左对齐、多行左对齐）。
+    """
+    return ctk.CTkLabel(
+        master,
+        text=text,
+        font=T.FONT_SMALL,
+        text_color=T.COLOR_MUTED,
+        anchor="w",
+        justify="left",
+    )

ctk_kit/scroll_list.py

@@ -0,0 +1,332 @@
+"""懒加载滚动列表。
+
+为什么不用 ``CTkScrollableFrame`` 直接塞卡片：上百张卡片时，一次建完要几秒，
+切页面会明显卡住。这里的分批策略是——
+
+1. 首屏只建 ``first_batch`` 张，先把页面显示出来；
+2. 滚到接近底部、且手停下来 ``load_delay_ms`` 之后，再补 ``load_more`` 张；
+3. 首屏没铺满窗口时自动补，直到铺满或补完。
+
+滚动条的两个坑（都踩过）：
+
+- ``CTkScrollbar.set()`` 内部会调 ``update_idletasks()``，而它**会立刻执行
+  idle 回调**——所以加载任务必须用 ``after(1, ...)`` 定时器，不能用
+  ``after_idle``，否则会在 ``set()`` 里递归建卡。
+- scrollregion 变化后 Tk 会回放一次 ``yscrollcommand(0, 1)``，用回调参数判断
+  「滚到底」会误判，必须读 ``canvas.yview()`` 的真实值。
+
+滚动条外观：内容不足一屏时把滑块涂成背景色（视觉上消失，但**布局宽度不变**）。
+不要用 ``grid_remove`` 隐藏——canvas 会变宽，卡片跟着拉伸一下，看起来像抖。
+"""
+
+from __future__ import annotations
+
+import tkinter as tk
+from typing import Any, Callable, Optional
+
+import customtkinter as ctk
+
+from . import tokens as T
+from .layout import empty_hint
+from .theme import color_of, repaint_native
+
+# ``render_card(parent, item)``：建一张卡片并返回其顶层控件。
+RenderCard = Callable[[tk.Misc, Any], tk.Misc]
+# ``key_of(item) -> 可哈希的签名``：用于判断数据是否变化。
+KeyOf = Callable[[Any], Any]
+
+
+class LazyList(tk.Frame):
+    """竖向懒加载列表。
+
+    参数:
+        master: 父容器。
+        render_card: 回调 ``render_card(parent, item) -> widget``，返回一张卡片
+            的顶层控件。卡片自己要负责外观，这里只负责把它 ``pack`` 进列表。
+        key_of: ``key_of(item) -> tuple``，用于判断数据是否变化。默认取
+            ``repr``；数据量大时建议换成
+            ``lambda item: (item["id"], item["updated_at"])``。
+        first_batch: 首屏一次建多少张，默认 12。
+        load_more: 每次追加多少张，默认 8。
+        load_delay_ms: 滚到底后等多久再追加（毫秒），默认 90——让手停下来。
+        load_threshold: 可滚动区滚到多少比例触发追加，默认 0.92。
+        gap: 卡片上下的外边距，默认 ``(0, 10)``。
+        padx: 卡片左右留白（给滚动条让位），默认 ``(0, 8)``。
+    """
+
+    def __init__(
+        self,
+        master: tk.Misc,
+        render_card: RenderCard,
+        *,
+        key_of: Optional[KeyOf] = None,
+        first_batch: int = 12,
+        load_more: int = 8,
+        load_delay_ms: int = 90,
+        load_threshold: float = 0.92,
+        gap: tuple[int, int] = (0, 10),
+        padx: tuple[int, int] = (0, 8),
+    ) -> None:
+        super().__init__(master, bg=color_of(T.COLOR_BG), highlightthickness=0)
+        self.render_card: RenderCard = render_card
+        self.key_of: KeyOf = key_of or repr
+        self.first_batch: int = first_batch
+        self.load_more: int = load_more
+        self.load_delay_ms: int = load_delay_ms
+        self.load_threshold: float = load_threshold
+        self.gap: tuple[int, int] = gap
+        self.padx: tuple[int, int] = padx
+
+        self._items: list[Any] = []
+        self._shown: int = 0
+        self._loading: bool = False
+        self._load_job: Optional[str] = None
+        self._suppress: bool = False
+        self._signature: Optional[tuple] = None
+        self._empty_box: Optional[tk.Frame] = None
+        self._scrollbar_visible: Optional[bool] = None
+
+        self.grid_rowconfigure(0, weight=1)
+        self.grid_columnconfigure(0, weight=1)
+
+        self.canvas: tk.Canvas = tk.Canvas(
+            self, highlightthickness=0, bg=color_of(T.COLOR_BG), bd=0
+        )
+        self.canvas.grid(row=0, column=0, sticky="nsew")
+        self.scrollbar: ctk.CTkScrollbar = ctk.CTkScrollbar(
+            self,
+            command=self.canvas.yview,
+            width=T.SCROLLBAR_WIDTH,
+            fg_color="transparent",
+            button_color=T.COLOR_SCROLLBAR,
+            button_hover_color=T.COLOR_SCROLLBAR_HOVER,
+        )
+        self.scrollbar.grid(row=0, column=1, sticky="ns")
+        self.canvas.configure(yscrollcommand=self._on_scroll)
+
+        self.inner: tk.Frame = tk.Frame(self.canvas, bg=color_of(T.COLOR_BG))
+        self._window: int = self.canvas.create_window(
+            (0, 0), window=self.inner, anchor="nw"
+        )
+
+        self.inner.bind("<Configure>", self._sync_scrollregion)
+        self.canvas.bind("<Configure>", self._on_canvas_resize)
+
+        # 滚轮：控件在 canvas 里是独立窗口，事件不会冒泡到父容器，
+        # 所以统一在 toplevel 上挂一个，按指针位置判断该不该由自己滚动。
+        self._alive: bool = True
+        self.bind_all("<MouseWheel>", self._on_wheel, add="+")
+
+    # ------------------------------------------------------------------ #
+    #  对外接口
+    def render(
+        self,
+        items: list[Any],
+        *,
+        empty_title: str = "这里还没有内容",
+        empty_detail: str = "",
+        force: bool = False,
+    ) -> None:
+        """重画列表。数据没变时直接返回，避免每次切页都重建控件。
+
+        参数:
+            items: 数据列表，原样交给 ``render_card``。
+            empty_title: 列表为空时的主提示。
+            empty_detail: 列表为空时的补充说明。
+            force: 为 ``True`` 时忽略签名缓存，强制重建。
+        """
+        signature = (ctk.get_appearance_mode(), tuple(self.key_of(i) for i in items))
+        if not force and signature == self._signature:
+            return
+        self._signature = signature
+        self._items = list(items)
+        self._shown = 0
+        self._suppress = True
+        self._refresh_colors()
+        self._clear_cards()
+
+        if not items:
+            self._suppress = False
+            box = empty_hint(self.inner, empty_title, empty_detail)
+            box.pack(pady=70)
+            self._empty_box = box
+            return
+
+        self._append(self.first_batch)
+        self._suppress = False
+        # 滚动条位置留到下一帧再算：set() 会同步布局，放在这里会拖慢首帧
+        self.after(1, self._refresh_scroll)
+
+    def show_hint(self, title: str, detail: str = "") -> None:
+        """只显示一条提示（例如「还没有备份」），不占列表数据。
+
+        参数:
+            title: 主提示。
+            detail: 补充说明，可为空。
+        """
+        signature = ("hint", ctk.get_appearance_mode(), title)
+        if signature == self._signature:
+            return
+        self._signature = signature
+        self._items = []
+        self._shown = 0
+        self._suppress = True
+        self._refresh_colors()
+        self._clear_cards()
+        self._empty_box = empty_hint(self.inner, title, detail)
+        self._empty_box.pack(pady=70)
+        self.canvas.yview_moveto(0)
+        self._suppress = False
+
+    def invalidate(self) -> None:
+        """丢掉缓存标记，下次 render 一定重建（主题切换后调用）。"""
+        self._signature = None
+
+    @property
+    def cards(self) -> list[tk.Misc]:
+        """当前已建出的卡片控件（副本，改动它不会影响列表）。"""
+        return list(self.inner.winfo_children())
+
+    def flush(self) -> None:
+        """一次性补齐所有卡片（测试、导出时用）。"""
+        self._cancel_load()
+        self._append(len(self._items) - self._shown)
+
+    def scroll_units(self, steps: int) -> None:
+        """按「行」滚动；steps>0 向下，steps<0 向上。"""
+        self.canvas.yview_scroll(steps * 3, "units")
+
+    def _on_wheel(self, event: tk.Event) -> Optional[str]:
+        """只滚动指针所在的列表；其它区域的滚轮不归这里管。"""
+        if not self._alive or not self._owns(event.widget):
+            return None
+        self.scroll_units(-1 if event.delta > 0 else 1)
+        return "break"
+
+    def _owns(self, widget: Optional[tk.Misc]) -> bool:
+        """``widget`` 是否在本列表的控件树里。"""
+        node: Optional[tk.Misc] = widget
+        while node is not None:
+            if node is self:
+                return True
+            node = getattr(node, "master", None)
+        return False
+
+    def destroy(self) -> None:
+        """停止滚轮绑定后销毁。"""
+        self._alive = False
+        super().destroy()
+
+    # ------------------------------------------------------------------ #
+    #  内部
+    def _append(self, count: int) -> None:
+        """从 ``_shown`` 处继续建 ``count`` 张卡。"""
+        end = min(self._shown + count, len(self._items))
+        if end <= self._shown:
+            return
+        # 建卡期间暂停滚动回调：每加一张都会触发 scrollregion 变化，而
+        # CTkScrollbar 每次 set 都要整条重绘（实测是布局耗时的大头）。
+        self._loading = True
+        self.canvas.configure(yscrollcommand="")
+        for item in self._items[self._shown : end]:
+            card = self.render_card(self.inner, item)
+            card.pack(fill="x", pady=self.gap, padx=self.padx)
+        self._shown = end
+        self._sync_scrollregion()
+        self.canvas.configure(yscrollcommand=self._on_scroll)
+        self.after(1, self._refresh_scroll)
+
+    def _refresh_scroll(self) -> None:
+        """同步滚动条位置，并在空闲后检查要不要补卡。"""
+        first, last = self.canvas.yview()
+        self.scrollbar.set(first, last)
+        self._sync_scrollbar()
+        self._loading = False
+        self.after(150, self._check_fill)
+
+    def _sync_scrollbar(self) -> None:
+        """内容装得下时把滑块涂成背景色（布局宽度不变）。"""
+        box = self.canvas.bbox("all")
+        content = (box[3] - box[1]) if box else 0
+        visible = content > self.canvas.winfo_height() + 1
+        if visible == self._scrollbar_visible:
+            return
+        self._scrollbar_visible = visible
+        bg = color_of(T.COLOR_BG)
+        self.scrollbar.configure(
+            fg_color=bg,
+            button_color=color_of(T.COLOR_SCROLLBAR) if visible else bg,
+            button_hover_color=color_of(T.COLOR_SCROLLBAR_HOVER) if visible else bg,
+        )
+
+    def _check_fill(self) -> None:
+        """窗口较高、首屏没铺满时补一批。
+
+        放在定时器里：Tk 要跑完一次事件循环才会更新内层 Frame 的尺寸，
+        这时 bbox 才是准的。
+        """
+        if self._shown >= len(self._items):
+            return
+        box = self.canvas.bbox("all")
+        content = (box[3] - box[1]) if box else 0
+        # 差得多才补：多建一批要重新布局整页，代价比底部一小条空白高得多
+        if content > self.canvas.winfo_height() * 0.8:
+            return
+        self._append(self.load_more)
+
+    def _load_more(self) -> None:
+        """定时器回调：追加下一批。"""
+        self._load_job = None
+        self._append(self.load_more)
+
+    def _on_scroll(self, first: str, last: str) -> None:
+        """canvas 的 yscrollcommand 回调。"""
+        if self._suppress:
+            return
+        self.scrollbar.set(first, last)
+        if self._loading or self._shown >= len(self._items):
+            return
+        # 不信回调参数：scrollregion 刚变时会回放一次 (0, 1)
+        current = self.canvas.yview()
+        if float(current[1]) < self.load_threshold:
+            return
+        self._schedule_load()
+
+    def _schedule_load(self) -> None:
+        """滚到底后等手停下再补下一批，避免边滚边排版造成顿挫。"""
+        if self._load_job is not None:
+            self.after_cancel(self._load_job)
+        self._load_job = self.after(self.load_delay_ms, self._load_more)
+
+    def _cancel_load(self) -> None:
+        """取消还没触发的追加任务。"""
+        if self._load_job is not None:
+            self.after_cancel(self._load_job)
+            self._load_job = None
+
+    def _clear_cards(self) -> None:
+        """清空内层卡片并复位滚动位置。"""
+        self._loading = False
+        self._cancel_load()
+        for child in self.inner.winfo_children():
+            child.destroy()
+        self._empty_box = None
+        self.canvas.yview_moveto(0)
+        self._sync_scrollregion()
+
+    def _refresh_colors(self) -> None:
+        """主题切换后刷新原生 tk 控件的底色（见 theme.repaint_native）。"""
+        bg = color_of(T.COLOR_BG)
+        for widget in (self, self.canvas, self.inner):
+            repaint_native(widget, bg)
+        self._scrollbar_visible = None
+        self._sync_scrollbar()
+
+    def _sync_scrollregion(self, _event: Optional[tk.Event] = None) -> None:
+        """把 canvas 的可滚动区域更新为内容包围盒。"""
+        self.canvas.configure(scrollregion=self.canvas.bbox("all"))
+
+    def _on_canvas_resize(self, event: tk.Event) -> None:
+        """canvas 宽度变化时让内层 Frame 跟着变宽。"""
+        self.canvas.itemconfigure(self._window, width=event.width)
+        self.after(1, self._sync_scrollbar)