CustomTkinter 完整指南：3 步把 Tkinter 界面翻新成现代化 Python 桌面风格

CustomTkinter 完整指南：3 步把 Tkinter 界面翻新成现代化 Python 桌面风格

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

CustomTkinter 是基于 Tkinter 的现代化 GUI 库，用 Canvas 自绘控件，让 Python 桌面界面一键拥有明暗主题与 HighDPI 缩放。

解决 Tkinter 界面老旧、跨平台不一致的痛点

传统 Tkinter 控件外观由操作系统决定，Windows、macOS、Linux 各长各的样子，按钮灰扑扑。CustomTkinter 把控件换成 Canvas 自绘版本，统一外观，你只需继承CTk窗口、把控件前缀改成CTk。

三行代码出第一个带按钮的窗口

先跑起来看到效果，再谈参数。把默认Tk换成CTk，按钮用CTkButton：

import customtkinter as ctk app = ctk.CTk() app.geometry("360x200") ctk.CTkButton(app, text="开始", width=140).pack(pady=24) app.mainloop()

窗口标题栏在 macOS/Windows 上自动变深色，按钮带圆角与悬停色，这正是 Tkinter 原生做不到的。

图片、字体、主题 JSON 一次配齐

视觉一致性来自三个配置源，集中定义一次即可全局生效：

CTkImage按当前appearance_mode选图，缺哪张就用另一张兜底：

icon = ctk.CTkImage( light_image=Image.open("home_light.png"), dark_image=Image.open("home_dark.png"), size=(20, 20))

CTkFont的size单位是像素，字号随系统缩放而文字比例不变：

title_font = ctk.CTkFont(size=20, weight="bold") ctk.CTkLabel(app, text="CustomTkinter", font=title_font)

主题 JSON 按控件名分节，颜色写成[亮色, 暗色]列表，完整内置样例见 customtkinter/assets/themes/：

{ "CTkButton": { "corner_radius": 6, "fg_color": ["#3B8ED0", "#1F6AA5"] } }

侧边导航加按钮标签：一个 class 组装完整应用

真实界面是组合出来的。把侧栏、导航按钮、标题标签写进同一个App类，参考仓库 examples/image_example.py 的写法：

class App(ctk.CTk): def __init__(self): super().__init__() self.sidebar = ctk.CTkFrame(self, width=180, corner_radius=0) self.sidebar.pack(side="left", fill="y") ctk.CTkLabel(self.sidebar, text="控制台", font=ctk.CTkFont(size=20, weight="bold")).pack(pady=16) for name in ("仪表盘", "设置"): ctk.CTkButton(self.sidebar, text=name, anchor="w", fg_color="transparent", hover_color=("gray70", "gray30")).pack(fill="x", padx=10, pady=4) ctk.CTkLabel(self, text="主内容区").pack(pady=40) App().mainloop()

侧栏按钮把fg_color设为transparent、hover_color用明暗双值，就得到"选中高亮 + 悬停反馈"的现代导航栏。

运行时切换外观模式与配色主题

外观模式与配色主题分开控制，二者都可在运行时切换，控件会即时重绘：

ctk.set_appearance_mode("System") # "Light" / "Dark" / "System" ctk.set_default_color_theme("blue") # "blue"/"green"/"dark-blue"/"gold" 或自定义 JSON 路径

set_appearance_mode只换明暗，System跟随系统；set_default_color_theme加载内置主题或传入 JSON 路径实现自定义配色。

三个高频踩坑点一次说清

• light/dark 图片写反：CTkImage只按appearance_mode选图，文件名带dark/light容易传错，注意对应关系。
• 不写size：默认按(20, 20)缩放，大图标会显得过小，需手动传显示尺寸。
• 自定义 JSON 缺键：控件初始化直接读theme["CTkButton"]，缺对应键会抛KeyError，改主题前先复制完整内置文件。

现在把窗口基类换成CTk、控件换成CTk前缀版本，你的 Python 桌面界面就完成了现代化改造，仓库地址：git clone https://gitcode.com/gh_mirrors/cu/CustomTkinter

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