Python customTkinter 常用控件速览:按钮、输入框、下拉菜单与开关

pip install customtkinter

pip install Pillow

import customtkinter as ctk
print(ctk.__version__)  # 正常输出版本号就 OK

import customtkinter as ctk

# 全局外观设置——建议放在最开头
ctk.set_appearance_mode("dark")       # 可选 "light" / "dark" / "system"
ctk.set_default_color_theme("blue")   # 内置主题：blue / green / dark-blue

app = ctk.CTk()
app.title("CTk 控件演示")
app.geometry("600x500")

# 控件代码写这里 ↓

app.mainloop()

def on_click():
print("按钮被点了")

btn = ctk.CTkButton(
    master=app,
    text="点我试试",
    command=on_click,
    width=200,
    height=45,
    corner_radius=12,       # 圆角半径，越大越圆
    fg_color="#1f6aa5",     # 按钮背景色
    hover_color="#144870",  # 悬停时的颜色
    text_color="white",
    font=("微软雅黑", 14, "bold")
)
btn.pack(pady=20)

效果出来之后你会发现，corner_radius=12 这个参数是整个"现代感"的核心。圆角越大，越有那种 macOS 风格；设成 0 就是直角，适合工具类软件。

带图标的按钮

这是很多教程跳过的部分——实际项目里，带图标的按钮用得非常多：

from PIL import Image
import customtkinter as ctk

app = ctk.CTk()
app.geometry("400x200")

# 加载图标（建议用 32x32 的 PNG，透明背景）
icon = ctk.CTkImage(
    light_image=Image.open("icon_light.png"),
    dark_image=Image.open("icon_dark.png"),   # 深色模式用不同图标
    size=(24, 24)
)

btn_icon = ctk.CTkButton(
    master=app,
    text="导出报告",
    image=icon,
    compound="left",   # 图标在文字左边
    width=160,
    height=40
)
btn_icon.pack(pady=30)
app.mainloop()

CTkImage 支持分别指定浅色/深色模式下的图片——这个设计真的很贴心，很多开发者在这里踩坑，用普通的 PhotoImage 会导致深色模式下图标发白。

⚠️ 踩坑预警

command 参数只接受无参数函数的引用。如果你想传参数，别这么写：

# ❌ 错误写法——按钮创建时就会立刻执行，而不是点击时执行
btn = ctk.CTkButton(master=app, command=my_func("参数"))

# ✅ 正确写法——用 lambda 包一层
btn = ctk.CTkButton(master=app, command=lambda: my_func("参数"))

我在项目里见过太多次这个错误了，尤其是循环创建按钮的时候，lambda 的闭包陷阱更是经典翻车现场（记得用 lambda i=i: func(i) 来固定变量）。

✏️ CTkEntry：输入框的那些门道

基础输入框

entry = ctk.CTkEntry(
    master=app,
    placeholder_text="请输入用户名",   # 占位符文字
    width=280,
    height=40,
    corner_radius=8,
    border_width=2,
    border_color="#3a7ebf",
    font=("微软雅黑", 13)
)
entry.pack(pady=10)

# 获取内容
content = entry.get()

# 设置内容
entry.insert(0, "默认值")

# 清空
entry.delete(0, "end")

密码输入框

pwd_entry = ctk.CTkEntry(
    master=app,
    placeholder_text="请输入密码",
    show="●",    # 这里控制掩码字符，"*" 也行
    width=280,
    height=40
)
pwd_entry.pack(pady=10)

show 参数是从原生 tkinter 继承来的，"●" 比 "*" 好看很多，这是我在一个内部工具项目里摸索出来的小细节。

实时输入校验

这个需求在表单类应用里非常常见。比如只允许输入数字：

def validate_number(value):
"""只允许输入数字和小数点"""
if value == "" or value == ".":
return True
try:
float(value)
return True
except ValueError:
return False

# 注册校验函数
vcmd = (app.register(validate_number), "%P")

num_entry = ctk.CTkEntry(
    master=app,
    placeholder_text="只能输入数字",
    validate="key",          # 每次按键都触发校验
    validatecommand=vcmd,    # %P 代表输入后的完整字符串
    width=200,
    height=38
)
num_entry.pack(pady=10)

validate="key" 是关键——它让校验在每次键盘输入时触发，而不是失去焦点时才检查。用户体验差别很大。

⚠️ 踩坑预警

placeholder_text 只是视觉上的占位符，不是默认值。直接 entry.get() 在用户没输入时返回的是空字符串，不是占位符文字。很多初学者在这里搞混，导致数据处理逻辑出错。

📋 CTkOptionMenu：下拉菜单的进阶玩法

基础下拉菜单

def on_select(choice):
print(f"用户选了: {choice}")

option_menu = ctk.CTkOptionMenu(
    master=app,
    values=["选项一", "选项二", "选项三", "选项四"],
    command=on_select,
    width=200,
    height=38,
    corner_radius=8,
    fg_color="#2b2b2b",
    button_color="#1f6aa5",
    button_hover_color="#144870",
    dropdown_fg_color="#2b2b2b",      # 下拉列表背景色
    dropdown_hover_color="#1f6aa5",   # 下拉项悬停色
    dropdown_text_color="white",
    font=("微软雅黑", 13),
    dropdown_font=("微软雅黑", 12)
)
option_menu.pack(pady=15)

# 动态修改选项列表
option_menu.configure(values=["新选项A", "新选项B"])

# 获取当前选中值
current = option_menu.get()

# 程序设置选中值
option_menu.set("选项二")

联动下拉菜单（真实业务场景）

这是实际项目里最常见的需求——省市联动、类别子类别联动。

import customtkinter as ctk

# 模拟数据
data = {
"华北地区": ["北京", "天津", "石家庄", "太原"],
"华东地区": ["上海", "南京", "杭州", "合肥"],
"华南地区": ["广州", "深圳", "福州", "南宁"],
}

app = ctk.CTk()
app.geometry("500x300")
app.title("联动下拉菜单")

def on_region_change(region):
"""一级菜单变化时，更新二级菜单"""
    cities = data.get(region, [])
    city_menu.configure(values=cities)
    city_menu.set(cities[0] if cities else "")

# 一级菜单：地区
region_menu = ctk.CTkOptionMenu(
    master=app,
    values=list(data.keys()),
    command=on_region_change,
    width=180,
    height=38,
    font=("微软雅黑", 13)
)
region_menu.pack(pady=20)

# 二级菜单：城市（初始值为第一个地区的城市）
initial_region = list(data.keys())[0]
city_menu = ctk.CTkOptionMenu(
    master=app,
    values=data[initial_region],
    width=180,
    height=38,
    font=("微软雅黑", 13)
)
city_menu.set(data[initial_region][0])
city_menu.pack(pady=10)

app.mainloop()

这段代码在我做一个内部数据录入工具时用到过，逻辑简洁，实测稳定。configure(values=...) 是动态更新选项的核心方法，记住它。

🔄 CTkSwitch：开关控件，比 Checkbox 更有质感

基础开关

def on_toggle():
    state = switch.get()   # 1 = 开，0 = 关
print(f"开关状态: {'开启' if state else '关闭'}")

switch = ctk.CTkSwitch(
    master=app,
    text="启用深色模式",
    command=on_toggle,
    onvalue=1,
    offvalue=0,
    progress_color="#1f6aa5",   # 开启状态的滑轨颜色
    button_color="white",       # 滑块颜色
    button_hover_color="#e0e0e0",
    font=("微软雅黑", 13)
)
switch.pack(pady=15)

# 程序控制开关状态
switch.select()    # 打开
switch.deselect()  # 关闭

实战：用开关控制应用主题切换

这是一个完整的、可以直接运行的示例——开关联动全局主题切换：

import customtkinter as ctk

app = ctk.CTk()
app.geometry("480x320")
app.title("主题切换演示")

ctk.set_appearance_mode("light")
ctk.set_default_color_theme("blue")

def toggle_theme():
if theme_switch.get() == 1:
        ctk.set_appearance_mode("dark")
        theme_switch.configure(text="深色模式 已开启")
else:
        ctk.set_appearance_mode("light")
        theme_switch.configure(text="深色模式 已关闭")

# 标题标签
label = ctk.CTkLabel(
    master=app,
    text="customTkinter 主题演示",
    font=("微软雅黑", 18, "bold")
)
label.pack(pady=30)

# 一个普通按钮，用来观察主题变化效果
demo_btn = ctk.CTkButton(master=app, text="这是一个普通按钮", width=200)
demo_btn.pack(pady=10)

# 一个输入框
demo_entry = ctk.CTkEntry(master=app, placeholder_text="输入点什么...", width=200)
demo_entry.pack(pady=10)

# 主题切换开关
theme_switch = ctk.CTkSwitch(
    master=app,
    text="深色模式 已关闭",
    command=toggle_theme,
    font=("微软雅黑", 13)
)
theme_switch.pack(pady=20)

app.mainloop()

运行这段代码，拨动开关，整个界面的颜色会实时切换——不需要重启，不需要重绘。这是 customTkinter 最让我惊喜的地方之一。

⚠️ 踩坑预警

CTkSwitch 的 get() 返回的是 onvalue 或 offvalue 的值，默认是 1 和 0。但如果你自定义了 onvalue="yes" 这类字符串值，记得在判断时用 == "yes" 而不是 if switch.get()，否则非空字符串的布尔判断会让你困惑半天。

🧩 把四个控件拼在一起：一个完整的设置面板

光看单个控件不过瘾。来一个综合示例——模拟一个软件的"设置界面"：

import customtkinter as ctk

ctk.set_appearance_mode("dark")
ctk.set_default_color_theme("blue")

app = ctk.CTk()
app.geometry("520x480")
app.title("软件设置")

# ---- 标题 ----
ctk.CTkLabel(app, text="⚙️ 软件设置", font=("微软雅黑", 20, "bold")).pack(pady=20)

# ---- 用户名输入 ----
ctk.CTkLabel(app, text="用户名", font=("微软雅黑", 13)).pack(anchor="w", padx=40)
username_entry = ctk.CTkEntry(app, placeholder_text="输入用户名", width=420, height=38)
username_entry.pack(pady=(4, 14), padx=40)

# ---- 语言选择 ----
ctk.CTkLabel(app, text="界面语言", font=("微软雅黑", 13)).pack(anchor="w", padx=40)
lang_menu = ctk.CTkOptionMenu(
    app,
    values=["简体中文", "繁體中文", "English", "日本語"],
    width=420, height=38,
    font=("微软雅黑", 13)
)
lang_menu.pack(pady=(4, 14), padx=40)

# ---- 开关组 ----
auto_update = ctk.CTkSwitch(app, text="自动检查更新", font=("微软雅黑", 13))
auto_update.select()   # 默认开启
auto_update.pack(anchor="w", padx=40, pady=6)

dark_mode = ctk.CTkSwitch(
    app, text="深色模式",
    font=("微软雅黑", 13),
    command=lambda: ctk.set_appearance_mode(
"dark" if dark_mode.get() == 1 else "light"
    )
)
dark_mode.select()
dark_mode.pack(anchor="w", padx=40, pady=6)

# ---- 保存按钮 ----
def save_settings():
    name = username_entry.get()
    lang = lang_menu.get()
    update = "开" if auto_update.get() else "关"
    theme = "深色" if dark_mode.get() else "浅色"
print(f"保存设置 → 用户名:{name} | 语言:{lang} | 自动更新:{update} | 主题:{theme}")

ctk.CTkButton(
    app, text="保存设置",
    command=save_settings,
    width=200, height=44,
    corner_radius=10,
    font=("微软雅黑", 14, "bold")
).pack(pady=28)

app.mainloop()

这个例子把四个控件全部串联起来，点"保存设置"会在控制台打印所有配置项。可以直接拿去改，换成你自己的业务逻辑。

💎 三句话总结

CTkButton 的 corner_radius + hover_color，两个参数让按钮脱胎换骨。

CTkEntry 的 validate 机制，是表单校验的正确姿势，别再用 StringVar trace 凑合了。

CTkSwitch 联动 set_appearance_mode()，三行代码实现专业级主题切换。

🗺️ 学习路线图

掌握这四个控件之后，下一步可以往这几个方向走：

• 布局管理深入：CTkFrame、CTkScrollableFrame 配合 grid 布局，做复杂多列界面
• 数据展示：CTkTable（第三方扩展）或者用 ttk.Treeview 混搭 customTkinter 主题
• 弹窗与对话框：CTkToplevel、CTkInputDialog 的使用
• 打包发布：PyInstaller 打包 customTkinter 应用的正确配置（这里坑很多，值得单独写一篇）

💬 互动一下

你在用 tkinter 或者 customTkinter 做项目的时候，遇到过哪些奇葩的坑？欢迎在评论区聊聊——我见过最离谱的一次，是有人把整个 mainloop 放进了 for 循环里，然后问我为什么窗口一闪而过……

实战小挑战：试着用本文的四个控件，做一个"番茄钟计时器"的设置界面——输入框设置时长，下拉菜单选择提醒音，开关控制是否显示通知，按钮启动计时。做完截图发评论，看看大家的实现风格有多不一样。

觉得这篇有用的话，收藏备用——下次写设置界面的时候，直接翻出来对照代码，比查文档快多了。

#Python桌面开发#customTkinter#GUI编程#Python实战#Windows开发