CustomTkinter 实用指南：三步把 Python 应用变成现代化桌面界面

CustomTkinter 实用指南：三步把 Python 应用变成现代化桌面界面

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

CustomTkinter 是基于 Tkinter 构建的 Python GUI 库，针对传统版本外观陈旧、界面不跟随系统明暗模式这两个问题。如果你要用 Python 发布现代化桌面应用，又不想逐个控件手工绘制外观，它就是可选方案之一。本文以"搭一个带侧边导航的应用"为主线，按装库、跑模板、加侧边栏与自适应图片、统一风格并跟随系统的顺序，把从空窗口到成品界面的过程拆开讲。

装好库，跑通第一个窗口

执行pip install customtkinter完成安装，图片部分还需要 PIL（pip install pillow）。下面的最小模板只有一个按钮，但开头两行配置已经决定了全局的外观模式与颜色主题，效果与传统 Tkinter 完全不同：

import customtkinter customtkinter.set_appearance_mode("System") customtkinter.set_default_color_theme("blue") app = customtkinter.CTk() app.title("我的应用") app.geometry("400x300") customtkinter.CTkButton(app, text="开始", width=120).pack(pady=40) app.mainloop()

保存为 main.py 并运行，会得到一个带圆角按钮和主题背景色的窗口。set_appearance_mode接受 "Light"、"Dark"、"System" 三个值，set_default_color_theme内置 "blue"、"green"、"dark-blue" 三套颜色主题，之后几节都在这副骨架上添组件。

打开示例工程，看清控件全集

仓库自带 5 个可运行示例，覆盖大部分控件，其中 complex_example.py 最能体现完整效果：CTkTabview、CTkEntry、CTkOptionMenu、CTkSlider 等按 4×4 网格排布，左侧导航栏可以直接当侧边栏参考，整份代码不到 200 行，读一遍就知道各控件的默认观感。

examples/ 里的其余几个示例也建议逐个运行，先混个脸熟，不必先读懂全部代码。

先搭出侧边导航栏

侧边栏本质上是一个 CTkFrame：width 设 140~180，corner_radius 设为 0，让它贴住左缘不留圆角。内部自上而下放一个标题 CTkLabel 和若干 CTkButton 作为导航入口，用 grid 按行排布，grid_rowconfigure(4, weight=1)在底部留出一片可拉伸空间，窗口拉高时按钮不会散开。

跨平台字体不用自己安装

默认字体由主题文件决定：Windows 与 Linux 用 Roboto（字体文件随库打包在 assets 目录里），macOS 用 SF Display。想让标题字体有别于正文，建一个 CTkFont 即可，例如customtkinter.CTkFont(size=20, weight="bold")，把它作为 font 参数传给 CTkLabel，其余控件同理。

让导航图标跟着主题变

纯文字按钮可用，但图标更贴近成品观感。仓库示例图片本身就有明暗两套（见 examples/test_images/），CTkImage 一次传入明暗两张图，控件会按当前外观模式显示对应的那张：

from PIL import Image import customtkinter home_image = customtkinter.CTkImage( light_image=Image.open("examples/test_images/home_dark.png"), dark_image=Image.open("examples/test_images/home_light.png"), size=(20, 20) ) customtkinter.CTkButton( master, text="首页", image=home_image, anchor="w", fg_color="transparent", hover_color=("gray70", "gray30") ).pack()

两张图任一可以是 None，库会用另一张替补，所以只准备一套图也能运行。按钮主体设fg_color="transparent"，hover_color 写成（浅色值, 深色值）的二元组，悬停色也会跟着主题走。

上面这张截图来自 image_example.py 示例，侧边栏的图标按钮全部由 CTkImage 渲染。

用一个 JSON 统一整体外观

所有控件的样式集中定义在 JSON 里，位于 customtkinter/assets/themes/ 下的 blue.json、green.json、dark-blue.json，启动时set_default_color_theme("blue")传名字即可生效。结构是"每个控件一组"，颜色值清一色写成 [浅色模式, 深色模式] 的二元数组：

{ "CTkButton": { "corner_radius": 6, "fg_color": ["#3B8ED0", "#1F6AA5"], "hover_color": ["#36719F", "#144870"], "text_color": ["#DCE4EE", "#DCE4EE"] }, "CTkFont": { "Windows": { "family": "Roboto", "size": 13, "weight": "normal" }, "macOS": { "family": "SF Display", "size": 13, "weight": "normal" } } }

CTkFont 分组同样解释了字体差异：库读取当前系统取对应 family。想整体换风格，就复制一份 JSON 改掉颜色，再把 set_default_color_theme 指向新文件；个别控件想单独覆盖，则用 CTkFont 和各控件的颜色参数。

一键跟随系统主题

set_appearance_mode("System")让应用跟随操作系统：Windows 读取个性化设置里的明暗选项，其他平台检测系统主题。若希望用户运行时切换，仓库示例的做法是在侧边栏放一个 CTkOptionMenu，values 设为 ["Light", "Dark", "System"]，command 回调里把选中值直接传给 set_appearance_mode。所有 CTk 控件都监听外观模式，切换后各自重绘，CTkImage 也会同步换图，不需要你手动刷新任何一个控件。

跑通官方示例，扩展成自己的应用

到这里的主线是三步：装库跑模板、加侧边栏与自适应图片、用 JSON 统一风格并跟随系统。其余控件（滚动框架、滑条、进度条、选项卡）的接法都相同。克隆仓库：

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

克隆后先运行python examples/complex_example.py，挑需要的部分拷进自己的项目。若还想给应用加可滚动的内容区，从 scrollable_frame_example.py 入手即可：

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