CustomTkinter 综合项目实战：从 0 到 1 仿制完整 App 界面（侧边栏+标签页+滚动列表）

CustomTkinter 综合项目实战：从 0 到 1 仿制完整 App 界面（侧边栏+标签页+滚动列表）

【免费下载链接】CustomTkinterA modern and customizable python UI-library based on Tkinter项目地址: https://gitcode.com/gh_mirrors/cu/CustomTkinter

CustomTkinter 是一款基于 Tkinter 的现代化 Python GUI 库，提供全新的、可完全自定义的控件，并自动适配深色/浅色模式与高 DPI 缩放。本实战教程带你从 0 到 1 仿制一个完整的 App 界面：带图标的侧边栏导航、多标签页内容区、可滚动的长列表，最终效果如下（官方 complex_example.py 在 Windows 11 深色模式下的运行截图）：

一、环境准备：一条命令安装 CustomTkinter

CustomTkinter 通过 pip 分发，Python 3.7+ 均可使用，30 秒完成安装：

pip3 install customtkinter

想对照源码学习的话，可以克隆本仓库查看完整实现：

git clone https://gitcode.com/gh_mirrors/cu/CustomTkinter

📦 库内置 4 套主题文件，全部位于 customtkinter/assets/themes/：blue.json（默认蓝）、dark-blue.json、green.json、gold.json（CHANGELOG.md 记录 6.0 版新增）。

二、第一步：跑通最小窗口，验证环境就绪

写完整界面之前，先用一个按钮确认环境正常——所有 CustomTkinter 控件的用法与标准 Tkinter 几乎一致：

import customtkinter as ctk ctk.set_appearance_mode("dark") # System / dark / light ctk.set_default_color_theme("blue") # 主题：blue / green / dark-blue app = ctk.CTk() app.geometry("400x240") button = ctk.CTkButton(app, text="CTkButton") button.place(relx=0.5, rely=0.5, anchor=ctk.CENTER) app.mainloop()

三、第二步：打造侧边栏导航（CTkFrame + grid 布局）

侧边栏的本质就是一个固定宽度、直角边框的CTkFrame，配合grid布局把控件从上到下排好。核心就三步：

1. corner_radius=0让框架四边直角，贴合窗口边缘；
2. sticky="nsew"+grid_rowconfigure让侧边栏随窗口拉伸；
3. 用透明按钮（fg_color="transparent"）做出"选中高亮"的导航效果。

# 左侧导航栏：固定宽 140，直角边框 sidebar = ctk.CTkFrame(app, width=140, corner_radius=0) sidebar.grid(row=0, column=0, rowspan=4, sticky="nsew") sidebar.grid_rowconfigure(4, weight=1) # 底部留白自动撑满 logo = ctk.CTkLabel(sidebar, text="MyApp", font=ctk.CTkFont(size=20, weight="bold")) logo.grid(row=0, column=0, padx=20, pady=(20, 10)) home_btn = ctk.CTkButton(sidebar, text="Home", fg_color="transparent", anchor="w") home_btn.grid(row=1, column=0, sticky="ew")

完整实现（含 Logo 图片与浅色/深色双套图标）见 examples/image_example.py，运行效果：

四、第三步：用 CTkTabview 组织标签页

标签页控件CTkTabview（源码 customtkinter/windows/widgets/ctk_tabview.py）内部基于分段按钮实现，每个标签页都是一个独立的 grid 容器，可以随意嵌入其他控件：

tabview = ctk.CTkTabview(app, width=250) tabview.grid(row=0, column=1, padx=(20, 0), pady=(20, 0), sticky="nsew") tabview.add("Dashboard") tabview.add("Settings") # 每个标签页单独配置 grid 布局 tabview.tab("Dashboard").grid_columnconfigure(0, weight=1)

⚠️ 注意：tabview.add()的参数是标签名，后续要用tabview.tab("标签名")访问页内空间——这一细节是 examples/complex_example.py#L57-L63 中最容易踩的坑。

五、第四步：CTkScrollableFrame 实现可滚动列表

内容超过窗口高度时，CTkScrollableFrame（源码 customtkinter/windows/widgets/ctk_scrollable_frame.py）是标准解法。6.0 版已修复鼠标悬停时滚轮滚动的问题，体验顺滑：

scroll_frame = ctk.CTkScrollableFrame(app, label_text="Notifications") scroll_frame.grid(row=1, column=1, padx=(20, 0), pady=(20, 0), sticky="nsew") scroll_frame.grid_columnconfigure(0, weight=1) for i in range(100): ctk.CTkSwitch(scroll_frame, text=f"Item {i}") \ .grid(row=i, column=0, padx=10, pady=(0, 20))

💡 进阶技巧：把CTkScrollableFrame当基类继承，封装add_item()/remove_item()/get_checked_items()方法，就能得到可动态增删的自定义列表组件，完整示例见 examples/scrollable_frame_example.py。

六、主题与外观模式：一键切换深色 / 浅色

CustomTkinter 的最大卖点之一：所有控件颜色自动跟随系统外观。两行 API 即可控制：

ctk.set_appearance_mode("System") # 跟随系统，也可设 "dark" / "light" ctk.set_default_color_theme("blue")

在界面上放一个CTkOptionMenu下拉菜单，就能让用户实时切换主题（写法见 examples/complex_example.py#L36-L43）。切换后的浅色模式效果：

想换配色风格？只需修改主题 JSON 中的色值数组（第一个值是浅色模式色，第二个是深色模式色），参考 customtkinter/assets/themes/dark-blue.json。

七、完整示例与扩展练习

直接运行官方综合示例，即可看到本文全部成果合体：

python examples/complex_example.py

想一次性浏览全部控件，官方 6.0 版提供了内置展示应用，一条命令启动：

import customtkinter as ctk ctk.run_showroom()

🚀课后练习清单（难度递增）：

小结：本教程的布局公式可以复用任何桌面应用——CTkFrame固定侧边栏 +grid划分区域 +CTkTabview管理页面 +CTkScrollableFrame承载长列表。掌握这四个控件的组合，你就能用 Python 快速仿制任何现代 App 界面 🎨

【免费下载链接】CustomTkinterA modern and customizable python UI-library based on Tkinter项目地址: https://gitcode.com/gh_mirrors/cu/CustomTkinter