简介：tkcalendar是一款面向Python开发者的开源日历小部件模块，基于Tkinter界面库提供日历与日期输入两个组件。日期输入组件类似组合框，下拉列表显示日历，用户点选即可完成日期录入，省去手工输入格式的麻烦；该模块兼容Python 2和3，可跟随系统语言环境显示，并支持颜色自定义。本次分享的压缩包共29个文件，体积约62KB，其中12个Python源码文件实现组件核心功能，10个RST文档涵盖安装、示例与接口说明，另有多个YML、Makefile等构建配置辅助文件，目录结构清晰，便于直接阅读或二次开发。资源已有1902人浏览学习，开发者可据此获取完整源码与文档，研究Tkinter的扩展机制，也能快速将日期选择能力集成到自己的桌面项目中。

1. tkcalendar：Tkinter 生态里的开源日历组件，一条 pip 命令替换手写控件

tkcalendar 是 Tkinter 生态里少有的开源日历组件，一条 pip install 命令就能把 Calendar 和 DateEntry 两个现成部件装进项目。我曾在某企业内部管理系统里画排期日历，起初打算手写月历控件，结果周末配色、跨月补位、禁用区间越写越失控，换成 tkcalendar 后三天工作量缩到半天。

它适合所有用 Tkinter 做桌面程序的开发者——考勤、预约、数据录入，只要界面里需要日期选择，这个开源软件能把几百行手写代码压成两个组件加几行绑定。接下来的章节按选型、参数、事件、业务改造、样式和踩坑的顺序，把这份资源完整拆一遍。

2. 选型与上手：Calendar 和 DateEntry 的区别、参数与事件绑定

2.1 Calendar：月历视图和 selectmode 的用法

先把环境装好。python -m pip install tkcalendar 会从 PyPI 拉取当前发布版本，装完用 import 验证一遍：

import tkcalendar print(tkcalendar.__version__) # 输出当前安装版本，形如 x.y.z

版本号在这类组件里很关键——不同版本在 date_pattern 和 locale 行为上有细微差别，锁定大版本再去查资料，能少踩不少坑。Calendar 组件本身展示的是单个月份的网格，顶部是星期表头和年份月份导航，左右箭头翻月，点击月份名还能下拉跳年。它适合用户需要「看着月份分布去点某一天」的场景，比如排班、会议日程、打卡补录；DateEntry 则适合纯粹录入日期的表单场景，两者不冲突，同一个界面完全可以同时用。

初始化一个最简日历只需要几行：

from tkinter import Tk from tkcalendar import Calendar root = Tk() cal = Calendar(root, selectmode='day') cal.pack(fill='both', expand=True) root.mainloop()

不传 year/month/day 时，日历默认定位到今天所在月份并高亮今天。selectmode 只有两个取值：'day' 表示允许点选日期，'none' 表示做成只读月历，只能翻月不能选。需要强调一点：tkcalendar 没有多选模式，想做区间选择得靠两个组件或事件标记，不要在 selectmode 上找，这是绕不过去的边界。常用参数整理如下：

firstweekday 传的是字符串，不是 0、6 这种数字，写错类型会直接抛异常，这是新手最常见的一个报错。showothermonthdays 设为 True 之后，网格首尾会出现上个月和下个月的补位日期，它们默认用浅色样式区分，但选中逻辑和当月日期完全一致，别按视觉颜色判断日期是否可选。

2.2 DateEntry：带下拉日历的日期输入框

DateEntry 在界面上是一个文本框加一个小按钮，点按钮弹出一个临时日历，选完自动把格式化日期写回文本框。常见做法是把它放在表单里替代手输，避免用户把 2025-04-10 写成 2025/4/10 这类格式混战。

from tkinter import Tk from tkcalendar import DateEntry root = Tk() de = DateEntry( root, date_pattern='yyyy-mm-dd', year=2025, month=4, day=10, width=12, ) de.pack(padx=10, pady=10) def read_selected(event): print(de.get_date(), type(de.get_date())) de.bind('<<DateEntrySelected>>', read_selected) root.mainloop()

date_pattern 控制文本框和下拉日历里日期的显示格式，支持 yyyy、mm、dd 组合，也能写 yyyy/mm/dd、dd/mm/yyyy，甚至 yyyy年mm月dd日 这种带中文的写法。width 的单位是字符，不是像素。state 设为 'readonly' 可以禁止手输，让用户只能从下拉日历里选，在数据录入类界面里配合 mindate 使用效果最好。

一个容易误解的地方：DateEntry 弹出日历默认显示的月份，不是「今天」所在的月份，而是组件当前值所在的月份。初始化时 month=4，点开弹出的就是 4 月。想让它默认弹今天，直接不传 year/month/day，或者每次用 set_date 把值刷新成今天。

2.3 事件绑定：CalendarSelected 与 DateEntrySelected 别绑错

两个组件的事件名不一样：Calendar 触发 < >，DateEntry 触发 < >，绑定错了回调永远不会执行，而且不会报错。我常用的写法：

def on_calendar_pick(event): d = cal.get_date() print("已选:", d.strftime("%Y-%m-%d")) cal.bind('<<CalendarSelected>>', on_calendar_pick)

事件回调里用 get_date() 拿当前选中日期，返回的是 datetime.date 对象，可以直接参与运算，比如算两个日期的差值，或者加 30 天自动算出截止日。Calendar 还支持 < > 和 < >，翻月或跳年时触发，适合做右侧列表联动——月份一变，把当月待办事项重新加载一遍。

提示：事件名区分大小写，Calendar 和 DateEntry 的事件不要互相混绑。混绑的表现是静默不触发，调试时先打印事件名确认绑定生效，再往下查。

DateEntry 的下拉日历选完日期后会自动关闭并触发 < >。这里我习惯把读取操作写在事件回调里，而不是依赖文本框内容，因为文本框里可能残留用户手输的半截字符串。get_date() 读的是组件内部状态，不是 Entry 显示文本，这个概念后面几章会反复用到。

3. 业务化改造：日期事件标记、选择范围限制与视图跳转

3.1 calevent 标记机制：在日历上画业务事件

Calendar 自带的 calevent 机制可以在具体日期下挂事件文本和颜色块，业务上常用来标「有评审」「已排班」「截止日」。用法是建事件、绑标签、配样式三件事：

import datetime from tkcalendar import Calendar cal = Calendar(root, selectmode='day') cal.pack() cal.calevent_create( datetime.date(2025, 4, 10), text="项目评审", tags=["meeting"], foreground="white", background="#e74c3c", ) cal.tag_config("meeting", foreground="white", background="#e74c3c")

calevent_create 在指定日期插入一条事件并返回事件 id，text 是显示文本，tags 是标签，可以传一个列表，同一个日期能挂多个不同标签的事件。tag_config 用于统一配置某类标签的样式，先 create 还是先 tag_config 都行，但同一个标签的配置后调用的会覆盖先调用的。

这里有一个隐藏得很深的接口坑：calevent_create 返回的是事件 id，但 calevent_remove 接收的却是标签而不是 id。想删单条事件，不能拿返回值去删，得给每条事件分配唯一标签再按标签清理。我第一次做动态生成事件清理时，在这个接口语义上卡了半小时。

cal.calevent_remove("meeting") # 删除所有带 meeting 标签的事件

配合 calevent_get(date=datetime.date(2025, 4, 10)) 能拿到某一天的全部事件明细，返回的是字典列表，包含 text 和 tags 字段，适合做日期面板联动：点某一天，右侧列表显示该天的所有事件。

3.2 mindate / maxdate：限制可选区间

日期范围限制是业务刚需，比如报销单只能选本月日期。Calendar 和 DateEntry 都支持 mindate、maxdate 参数，传 datetime.date 对象：

from datetime import date from tkcalendar import Calendar cal = Calendar( root, mindate=date(2025, 4, 1), maxdate=date(2025, 4, 30), )

设置后范围外的日期在界面上变灰，点击没反应。注意两个参数必须是 datetime.date，传 '2025-04-01' 这种字符串会在内部做大小比较时报错。另一个容易忽略的点：showothermonthdays 开启后，网格里的补位日期只要落在范围内，仍然可以正常选中，它们视觉上显示的是相邻月份，选择逻辑按真实日期走，别按月份格子判断。

DateEntry 同样支持 mindate / maxdate，下拉日历里会自动置灰。但动态修改不能用 config——DateEntry 是 ttk.Entry 的扩展，运行期配置和构造期参数是两套东西，mindate 只认构造时传入。想动态收紧范围只能重建组件，这个取舍放到第 6 章细说。

3.3 视图跳转：show_date、show_month 与 get_displayed_month

业务经常需要把日历翻到指定月份。比如用户选了开始日期，下一步希望日历自动切到结束日期所在月份。Calendar 提供了一组视图方法：

cal.show_date(datetime.date(2025, 7, 1)) # 跳到 7 月，不改选中日期 cal.show_month(7) # 只改月份，年份不动 cal.show_year(2026) # 只改年份，月份不动

show_date 接收一个 date 对象，把视图切到目标日期所在月份。它不会改变当前选中日期，也不会触发 < >，只是「看过去」。show_month 和 show_year 适合做年月联动下拉框：界面上放两个 Combobox，一个选年一个选月，回调里分别调用这两个方法，比每次重建 Calendar 省心，也不会丢选中状态。

配合 get_displayed_month() 可以反查当前视图是几月。它返回 (year, month) 元组，月份从 1 开始，不是 0 开始，这和 Python 标准库 calendar 模块的语义不一样，写换算的时候别顺手减 1。视图控制与选中状态是两套逻辑，先搞清楚这一点，后面做联动才不容易乱。

4. 样式定制与中文本地化：配色参数、locale 与日期格式

4.1 配色参数：一套参数管住日历外观

tkcalendar 把颜色全部暴露成构造参数，不需要去改 ttk 主题。一套完整的配色大概长这样：

cal = Calendar( root, background="#ffffff", # 网格主体背景 foreground="#2c3e50", # 普通日期文字 headersbackground="#34495e", # 星期表头背景 headersforeground="#ecf0f1", # 星期表头文字 selectbackground="#3498db", # 选中日期背景 selectforeground="#ffffff", # 选中日期文字 weekendbackground="#fdf0f0", # 周末背景 weekendforeground="#c0392b", # 周末文字 othermonthbackground="#f5f5f5", # 补位日期背景 othermonthforeground="#bdc3c7", # 补位日期文字 )

这些参数成对出现，foreground 管文字，background 管背景，维度分普通日期、选中态、表头、周末、补位日期五组。参数最终会转成内部样式写入 Calendar 的 ttk 风格里，所以如果项目里套了其它 ttk 主题，注意别让外层样式把实例参数盖掉。想全局统一，可以在创建前配置 ttk.Style，再让各实例的显式参数覆盖默认值。

颜色参数还有一个习惯问题：很多人只调 background，然后发现「没生效」——实际上主体背景是变了，但表头、选中块和周末区域颜色还占着多数视觉面积，看起来像没动过。看效果要把反差最大的 selectbackground 一起调，一眼就能确认参数到底吃没吃进去。

4.2 locale 配置：中文表头与月份名

默认状态下日历表头是英文缩写，月份名也是英文。加一个 locale 参数就能整体切换语言习惯：

cal = Calendar(root, locale='zh_CN') de = DateEntry(root, locale='zh_CN', date_pattern='yyyy年mm月dd日')

locale 传系统地区码，zh_CN 对应简体中文。设置后星期表头变成「一 二 三 四 五 六 日」的对应形式，月份名变成「四月」这类中文表达。Windows 上一般直接可用，Linux 上如果系统没生成 zh_CN 的 locale 数据，会抛 LookupError: unknown locale，这属于操作系统环境问题，不是库的 bug。解决路径是补系统 locale 数据，或者退回 locale='C' 用英文表头，不要在代码里反复设 locale 变量期待能绕过系统。

跨平台分发的程序，我一般会在组件创建前包一个 try/except，locale 初始化失败就降级到英文，宁可表头是英文也不能让程序起不来。

4.3 date_pattern 与 textvariable：显示格式和绑定变量的两侧

date_pattern 是 DateEntry 的核心参数，控制文本框里日期的最终形态。常见格式对照：

格式标记是 tkcalendar 自定义的 yyyy、mm、dd 体系，不是 Python strftime 的 %Y-%m-%d，两者极易混用。写错大小写不会报错，只会原样输出，比如 date_pattern='YYYY-MM-DD'，文本框里就真的显示 "YYYY-04-10"，排查时需要先怀疑格式串本身。

DateEntry 还支持 textvariable 绑定 StringVar，选中日期后变量自动更新为格式化字符串：

from tkinter import StringVar v = StringVar() de = DateEntry(root, textvariable=v, date_pattern='yyyy-mm-dd')

这里有个认知偏差：textvariable 里存的是给人看的字符串，get_date() 返回的是给代码用的 date 对象，两条读取路径各自独立。用户手动改了文本框内容，StringVar 会更新，但组件内部记录的选择日期不会变，此时 get_date() 返回的还是上一次从日历里选的值。想完全统一，就把 DateEntry 设为 readonly 强制走日历选择，否则就要做一次手工回填校验，方向在第 5 章展开。

5. 避坑排查：tkcalendar 五个高频翻车现场

5.1 get_date() 返回的是 date 对象，不是字符串

现象：把 get_date() 的结果直接拼进 SQL 或 f-string 里，控制台打印看着是 "2025-04-10"，但某些地方报 unsupported format character 或类型错误。 原因：get_date() 返回 datetime.date 对象，print 显示和字符串很像，但它不是 str，拿去做字符串拼接、格式化、写入 JSON 时行为完全不同。 解决：需要字符串时显式格式化，f"{d:%Y-%m-%d}" 或 d.strftime("%Y-%m-%d")；需要运算时保留 date 对象。我给自己定的规矩是——凡是和外部接口、数据库交互的日期，一律先转字符串；凡是内部计算的日期，一律保留 date 对象，两者用函数名区分，不混用。

5.2 date_pattern 写成 strftime 风格，日期格式纹丝不动

现象：date_pattern='%Y-%m-%d'，文本框里显示 "%Y-%m-%d"，日期没替换进去。 原因：date_pattern 走的是 tkcalendar 自己的 yyyy、mm、dd 标记，不是 Python 的 %Y %m %d，库没有做兼容转换。 解决：改成 yyyy-mm-dd，大小写也要严格，YYYY、DD 不是合法标记，会被当普通文本原样显示。升级库版本后，先打印一次默认的 date_pattern 确认行为再定制，不要靠记忆写。

5.3 Linux 上 locale 抛 LookupError，程序启动即崩

现象：Calendar(root, locale='zh_CN') 在部分机器上直接抛 LookupError: unknown locale: zh_CN，窗口都起不来。 原因：Python locale 模块依赖操作系统 locale 数据，Linux 发行版默认可能没生成 zh_CN，系统不认这个地区码，库只是把异常透传出来。 解决：先在本机执行 locale -a 看已生成的地区；没有就补系统包或生成数据；不想动系统的就切换 locale='C' 用英文表头，或者包一层 try/except 降级。Windows 一般没这个问题，跨平台项目必须做兜底，不能假设所有机器都准备好了中文地区数据。

5.4 改了 background 参数，视觉上像没生效

现象：构造时传了 background='#333333'，日历网格看起来还是亮底色。 原因：background 管的是网格主体，但选中块、表头、周末区域各有一套独立配色，只改背景时这些区域占掉大部分视觉面积，变化被淹没了。另一个常见误用是写 bg= 简写，这个库只认 background 全称参数名。 解决：按「主体、表头、选中、周末」四组成套传参。验证参数是否生效时，把 selectbackground 和 background 设成反差大的颜色，重开后一秒就能分辨，比盯着代码猜快得多。

5.5 DateEntry 手输文本后 get_date() 返回旧值

现象：用户把文本框里的日期手改为 2025-08-01，get_date() 返回的却是初始化或上次下拉选的日期。 原因：DateEntry 内部维护独立的选择日期，Entry 显示文本只是展示层的一部分。手输只更新了文本框字符串，没有触发日历选中逻辑。 解决：严格模式下把 state 设为 readonly，只允许下拉选择；必须兼容手输时，加一个读取按钮，用 datetime.strptime 解析文本框内容，解析成功再 set_date 回填组件，两端状态就一致了。这个解析函数我后来在多个工具里复用，成了固定套路。

6. 进阶技巧：开始/结束日期联动的公共函数与校验兜底

排期界面最常见的联动是「结束日期不能早于开始日期」。我一般用两个 DateEntry 加两个回调解决：

from tkinter import Tk, messagebox from tkcalendar import DateEntry root = Tk() start_de = DateEntry(root, date_pattern='yyyy-mm-dd', width=12) end_de = DateEntry(root, date_pattern='yyyy-mm-dd', width=12) start_de.pack(side='left', padx=10) end_de.pack(side='left', padx=10) def on_start_selected(event): start = start_de.get_date() if end_de.get_date() < start: end_de.set_date(start) # 旧值早于开始日，强制回填 def on_end_selected(event): start = start_de.get_date() end = end_de.get_date() if end < start: end_de.set_date(start) messagebox.showwarning("日期范围", "结束日期不能早于开始日期") start_de.bind('<<DateEntrySelected>>', on_start_selected) end_de.bind('<<DateEntrySelected>>', on_end_selected) root.mainloop()

回调逻辑分两步：开始日期变化时，如果已有结束日期早于新开始日期，用 set_date 强制回填；结束日期变化时，再做一次同样的校验并弹提示。set_date 只更新组件值和文本框，不触发 < >，所以两个回调不会互相循环，这一条我实测过。

关于能不能让下拉日历里直接把非法日期置灰：DateEntry 的 mindate 只支持构造时传入，运行期没有公开的 setter。要实时置灰就得销毁重建整个 DateEntry，焦点和当前显示月份都会丢，性价比很低。我的取舍是放弃 UI 置灰，把校验集中在回调与保存函数里，逻辑单一也更好测试。

保存前统一读取，解析失败返回 None，保证脏数据不会进库：

def read_range(): """返回 (开始, 结束)；解析失败返回 None""" try: return start_de.get_date(), end_de.get_date() except ValueError: return None, None

从那以后我每次接日期组件，都会先花十分钟把读取、格式化、范围校验三个小函数写掉，再谈界面联动；顺序反了，后面九成要返工重写。希望帮到你。

本文还有配套的精品资源，点击获取