CustomTkinter基础控件使用详解
项目地址: https://gitcode.com/gh_mirrors/cu/CustomTkinter 本文全面介绍了CustomTkinter库中核心控件的使用方法，包括CTkButton按钮控件、CTkEntry输入框、CTkLabel标签控件、CTkCheckBox复选框、CTkRadioButton单选按钮以及CTkSwitch开关控件。文章详细解析了每个控件的构造函数参数、配置选项、事件处理机制和实际应用场景，通过丰富的代码示例展示了如何创建现代化、主题适配的GUI界面组件。
CTkButton按钮控件的完整配置指南
CustomTkinter的CTkButton是一个现代化的按钮控件，提供了丰富的自定义选项和优雅的视觉效果。作为Tkinter标准按钮的升级替代品，CTkButton支持圆角、边框、悬停效果、图像支持、点击命令和文本变量等功能，能够完美适配系统的明暗主题模式。
基础创建与核心属性
CTkButton的构造函数提供了丰富的参数配置选项，让开发者可以精细控制按钮的外观和行为：
import customtkinter
# 基本按钮创建
button = customtkinter.CTkButton(
master=parent_window, # 父容器
text="点击我", # 按钮文本
command=button_callback # 点击回调函数
)
尺寸与形状控制
# 尺寸和形状配置示例
button = customtkinter.CTkButton(
master=root,
width=160, # 按钮宽度（像素）
height=32, # 按钮高度（像素）
corner_radius=8, # 圆角半径
border_width=2, # 边框宽度
border_spacing=4 # 边框间距
)
颜色配置体系
CTkButton提供了完整的颜色配置系统，支持明暗主题自适应：
button = customtkinter.CTkButton(
master=root,
fg_color=("#3B8ED0", "#1F6AA5"), # 前景色（亮色模式，暗色模式）
hover_color=("#36719F", "#144870"), # 悬停颜色
border_color=("#3E454A", "#949A9F"), # 边框颜色
text_color=("#DCE4EE", "#DCE4EE"), # 文本颜色
text_color_disabled=("gray74", "gray60") # 禁用状态文本颜色
)
文本与字体配置
from customtkinter import CTkFont
# 自定义字体配置
custom_font = CTkFont(
family="Roboto",
size=14,
weight="bold",
slant="italic"
)
button = customtkinter.CTkButton(
master=root,
text="自定义按钮", # 按钮文本
font=custom_font, # 字体对象
textvariable=text_var, # 文本变量（动态更新）
compound="top", # 图文组合方式：left, right, top, bottom
anchor="center" # 内容对齐：n, e, s, w, ne, nw, se, sw, center
)
图像集成功能
CTkButton支持图像显示，可以与文本组合使用：
from customtkinter import CTkImage
from PIL import Image
# 创建支持明暗主题的图像
light_image = Image.open("light_icon.png")
dark_image = Image.open("dark_icon.png")
button_image = CTkImage(
light_image=light_image,
dark_image=dark_image,
size=(24, 24)
)
button = customtkinter.CTkButton(
master=root,
text="带图标的按钮",
image=button_image,
compound="left", # 图像在文本左侧
anchor="w" # 内容左对齐
)
状态与交互控制
button = customtkinter.CTkButton(
master=root,
state="normal", # 状态：normal, disabled
hover=True, # 是否启用悬停效果
command=on_button_click # 点击事件回调
)
# 动态状态切换
button.configure(state="disabled") # 禁用按钮
button.configure(state="normal") # 启用按钮
高级渲染选项
# 高级渲染配置
button = customtkinter.CTkButton(
master=root,
background_corner_colors=(
"#FF0000", "#00FF00", "#0000FF", "#FFFF00"
), # 四角背景色
round_width_to_even_numbers=True, # 宽度取偶优化
round_height_to_even_numbers=True # 高度取偶优化
)
配置方法详解
CTkButton提供了灵活的配置方法，支持运行时动态修改：
configure() 方法
# 动态修改按钮属性
button.configure(
text="新的文本",
fg_color="red",
corner_radius=12,
state="normal"
)
# 批量配置示例
new_config = {
"text": "更新后的按钮",
"hover_color": "#FF5733",
"border_width": 3,
"font": ("Arial", 16, "bold")
}
button.configure(**new_config)
cget() 方法
# 获取按钮当前配置
current_text = button.cget("text")
current_color = button.cget("fg_color")
corner_radius = button.cget("corner_radius")
button_state = button.cget("state")
完整的配置选项表格
下表列出了CTkButton所有可配置的属性和其默认值：
| 属性名称 | 类型 | 默认值 | 描述 |
|---|---|---|---|
| width | int | 140 | 按钮宽度（像素） |
| height | int | 28 | 按钮高度（像素） |
| corner_radius | int | None | 圆角半径（自动适配主题） |
| border_width | int | None | 边框宽度（自动适配主题） |
| border_spacing | int | 2 | 边框间距 |
| fg_color | str/tuple | None | 前景色（自动适配主题） |
| hover_color | str/tuple | None | 悬停颜色（自动适配主题） |
| border_color | str/tuple | None | 边框颜色（自动适配主题） |
| text_color | str/tuple | None | 文本颜色（自动适配主题） |
| text_color_disabled | str/tuple | None | 禁用状态文本颜色 |
| text | str | "CTkButton" | 按钮显示文本 |
| font | tuple/CTkFont | None | 字体配置 |
| textvariable | tkinter.Variable | None | 文本变量 |
| image | CTkImage/PhotoImage | None | 按钮图像 |
| state | str | "normal" | 按钮状态 |
| hover | bool | True | 是否启用悬停效果 |
| command | Callable | None | 点击回调函数 |
| compound | str | "left" | 图文组合方式 |
| anchor | str | "center" | 内容对齐方式 |
实战示例代码
import customtkinter
from customtkinter import CTkFont, CTkImage
from PIL import Image
class AdvancedButtonExample:
def __init__(self):
self.root = customtkinter.CTk()
self.root.title("CTkButton高级示例")
self.root.geometry("400x300")
# 创建自定义字体
bold_font = CTkFont(size=14, weight="bold")
# 创建图像
icon_image = CTkImage(
light_image=Image.open("icon_light.png"),
dark_image=Image.open("icon_dark.png"),
size=(20, 20)
)
# 创建主要功能按钮
self.primary_button = customtkinter.CTkButton(
master=self.root,
text="主要操作",
image=icon_image,
font=bold_font,
fg_color=("#2563EB", "#1D4ED8"),
hover_color=("#1D4ED8", "#1E40AF"),
corner_radius=8,
height=40,
command=self.on_primary_click
)
self.primary_button.pack(pady=20)
# 创建次要功能按钮
self.secondary_button = customtkinter.CTkButton(
master=self.root,
text="次要操作",
fg_color="transparent",
border_width=2,
border_color=("#2563EB", "#1D4ED8"),
text_color=("#2563EB", "#1D4ED8"),
hover_color=("#EFF6FF", "#1E3A8A"),
corner_radius=8,
height=36,
command=self.on_secondary_click
)
self.secondary_button.pack(pady=10)
# 创建禁用状态按钮
self.disabled_button = customtkinter.CTkButton(
master=self.root,
text="禁用按钮",
state="disabled",
fg_color=("#9CA3AF", "#4B5563"),
corner_radius=8,
height=36
)
self.disabled_button.pack(pady=10)
def on_primary_click(self):
print("主要按钮被点击")
# 动态修改按钮状态
self.primary_button.configure(
text="已点击",
state="disabled"
)
def on_secondary_click(self):
print("次要按钮被点击")
# 启用主要按钮
self.primary_button.configure(
text="主要操作",
state="normal"
)
def run(self):
self.root.mainloop()
# 运行示例
if __name__ == "__main__":
app = AdvancedButtonExample()
app.run()
主题适配与最佳实践
CTkButton自动适配系统明暗主题，但也可以通过代码强制指定：
CTkEntry输入框与CTkLabel标签控件
CustomTkinter作为现代Python UI库，提供了丰富且美观的控件组件。CTkEntry和CTkLabel作为最基础且常用的控件，在用户界面设计中扮演着至关重要的角色。这两个控件不仅继承了Tkinter的核心功能，还通过现代化的设计语言和主题系统，为开发者提供了更加优雅和一致的视觉体验。
CTkEntry输入框控件详解
CTkEntry是CustomTkinter中的文本输入控件，它提供了圆角边框、占位符文本、主题适配等现代化特性，同时保持了与标准Tkinter Entry控件的完全兼容性。
基本用法与参数配置
CTkEntry的构造函数提供了丰富的参数选项，让开发者能够精细控制输入框的外观和行为：
import customtkinter
# 创建基本输入框
entry = customtkinter.CTkEntry(
master=root, # 父容器
width=140, # 宽度
height=28, # 高度
corner_radius=10, # 圆角半径
border_width=2, # 边框宽度
fg_color="#FFFFFF", # 前景色
border_color="#CCCCCC", # 边框颜色
text_color="#333333", # 文本颜色
placeholder_text="请输入内容", # 占位符文本
placeholder_text_color="#999999", # 占位符颜色
font=("Arial", 12), # 字体
state="normal" # 状态：normal/disabled
)
核心特性与功能
CTkEntry控件支持以下重要特性：
占位符文本功能：当输入框为空时显示提示文本，获得焦点时自动隐藏
entry = customtkinter.CTkEntry(
placeholder_text="用户名/邮箱",
placeholder_text_color="#888888"
)
文本变量绑定：支持与Tkinter变量绑定，实现数据同步
import tkinter as tk
text_var = tk.StringVar()
entry = customtkinter.CTkEntry(
textvariable=text_var
)
# 监听文本变化
text_var.trace_add("write", lambda *args: print(f"输入内容: {text_var.get()}"))
密码输入模式：支持隐藏输入内容
password_entry = customtkinter.CTkEntry(
show="*", # 显示为星号
placeholder_text="请输入密码"
)
方法调用与交互
CTkEntry提供了完整的文本操作方法：
# 插入文本
entry.insert(0, "默认文本")
# 获取内容
content = entry.get()
# 清空内容
entry.delete(0, tk.END)
# 选择文本
entry.select_range(0, tk.END)
entry.select_clear()
# 设置焦点
entry.focus_set()
事件处理与绑定
支持标准的事件绑定机制：
def on_entry_change(event):
print(f"输入内容变化: {entry.get()}")
entry.bind("<KeyRelease>", on_entry_change)
def on_focus_in(event):
print("输入框获得焦点")
def on_focus_out(event):
print("输入框失去焦点")
entry.bind("<FocusIn>", on_focus_in)
entry.bind("<FocusOut>", on_focus_out)
CTkLabel标签控件详解
CTkLabel是用于显示文本或图像的标签控件，支持圆角背景、多行文本、图像组合等高级特性。
基本用法与参数配置
label = customtkinter.CTkLabel(
master=root, # 父容器
width=200, # 宽度（0表示自适应）
height=40, # 高度
corner_radius=8, # 圆角半径
fg_color="#F0F0F0", # 前景色（None表示透明）
text_color="#333333", # 文本颜色
text="欢迎使用CustomTkinter", # 显示文本
font=("Arial", 14, "bold"), # 字体
anchor="w", # 文本对齐：center/n/e/s/w
wraplength=180, # 自动换行宽度
compound="left" # 图文组合方式
)
图像显示功能
CTkLabel支持显示图像，包括静态图像和主题适配的双色图像：
from PIL import Image
import customtkinter
# 创建图像对象
image = customtkinter.CTkImage(
light_image=Image.open("light_icon.png"),
dark_image=Image.open("dark_icon.png"),
size=(24, 24)
)
# 创建带图像的标签
image_label = customtkinter.CTkLabel(
text="带图标的标签",
image=image,
compound="left", # 图像在文本左侧
padx=10
)
文本格式化与布局
支持多种文本布局选项：
# 多行文本与自动换行
multi_line_label = customtkinter.CTkLabel(
text="这是一个很长的文本内容，将会自动换行显示",
wraplength=150, # 换行宽度
justify="left" # 对齐方式
)
# 不同对齐方式
left_label = customtkinter.CTkLabel(text="左对齐", anchor="w")
center_label = customtkinter.CTkLabel(text="居中", anchor="center")
right_label = customtkinter.CTkLabel(text="右对齐", anchor="e")
动态内容更新
支持动态更新文本内容和样式：
# 创建标签
status_label = customtkinter.CTkLabel(text="就绪")
# 更新文本
def update_status(message, color="#333333"):
status_label.configure(text=message, text_color=color)
# 使用示例
update_status("正在处理...", "#007ACC")
update_status("完成", "#107C10")
update_status("错误", "#D83B01")
控件组合使用示例
CTkEntry和CTkLabel通常组合使用，创建完整的表单界面：
import customtkinter as ctk
class LoginForm(ctk.CTkFrame):
def __init__(self, master, **kwargs):
super().__init__(master, **kwargs)
# 标题标签
self.title_label = ctk.CTkLabel(
self,
text="用户登录",
font=ctk.CTkFont(size=18, weight="bold"),
height=40
)
self.title_label.pack(pady=20)
# 用户名输入区域
self.username_label = ctk.CTkLabel(
self,
text="用户名:",
anchor="w"
)
self.username_label.pack(fill="x", padx=20, pady=(10, 5))
self.username_entry = ctk.CTkEntry(
self,
placeholder_text="请输入用户名",
width=250,
height=35
)
self.username_entry.pack(fill="x", padx=20, pady=(0, 15))
# 密码输入区域
self.password_label = ctk.CTkLabel(
self,
text="密码:",
anchor="w"
)
self.password_label.pack(fill="x", padx=20, pady=(10, 5))
self.password_entry = ctk.CTkEntry(
self,
placeholder_text="请输入密码",
show="*",
width=250,
height=35
)
self.password_entry.pack(fill="x", padx=20, pady=(0, 20))
# 状态显示
self.status_label = ctk.CTkLabel(
self,
text="",
text_color="#666666",
height=20
)
self.status_label.pack(pady=10)
主题适配与样式控制
CTkEntry和CTkLabel都支持CustomTkinter的主题系统，能够自动适应明暗主题：
import customtkinter as ctk
# 设置主题
ctk.set_appearance_mode("system") # 跟随系统
ctk.set_default_color_theme("blue") # 蓝色主题
# 创建控件时会自动应用当前主题
entry = ctk.CTkEntry(placeholder_text="主题适配输入框")
label = ctk.CTkLabel(text="主题适配标签")
# 手动创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
