前端UI组件小程序设计系统移动开发【免费下载链接】tdesign-miniprogramWechat MiniProgram and Uniapp UI components lib for TDesign项目地址https://gitcode.com/gh_mirrors/tde/tdesign-miniprogram点击查看免费下载导读Calendar是 TDesign 小程序组件库tdesign-miniprogram中用于按照日历形式展示数据或日期的容器的组件支持单选、多选、区间选择三种模式并提供翻页切换、自定义格式化、国际化等能力。本文将基于官方文档packages/components/calendar/README.en-US.md结合组件源码与测试用例完整讲解组件的引入方式、全部 Props / Events / Slots / CSS Variables 的配置含义并给出可直接运行的代码示例帮助你在微信小程序中快速落地日期选择功能。说明Calendar 组件自0.22.0版本上线渲染框架支持情况为 WebView。以下所有版本号标记如1.11.2、0.34.0均取自官方文档表示该能力引入的版本。一、组件引入全局与局部两种方式Calendar 组件与其他 TDesign 组件一样可通过全局或局部方式注册全局引入在 miniprogram 根目录下的app.json中配置usingComponents局部引入在需要使用日历的页面或组件的index.json中配置。usingComponents: { t-calendar: tdesign-miniprogram/calendar/calendar }组件内部依赖t-popup、t-button、t-icon三个子组件在 calendar.json 中已声明styleIsolation: apply-shared。引入后即可在 WXML 中直接使用t-calendar。从源码结构看Calendar 组件由以下文件组成便于后续深度阅读组件逻辑calendar.ts属性声明props.ts类型定义type.ts模板calendar.wxml、template.wxml、calendar-header.wxml样式calendar.less底层算法common/shared/calendar/index.ts二、Calendar Props完整配置参数解析下表完整列出组件所有属性与官方文档一致并在其后补充源码层面的实现说明。| name | type | default | description | required | | -- | -- | -- | -- | -- | | style | Object | - | 样式 | N | | custom-style | Object | - | 样式一般用于开启虚拟化组件节点场景 | N | | allow-same-day | Boolean | false |1.11.2。是否允许区间选择日历的起止时间相同仅当typerange时有效 | N | | auto-close | Boolean | true |0.34.0。自动关闭在点击关闭按钮、确认按钮、遮罩层时自动关闭不需要手动设置 visible | N | | confirm-btn | String / Object | | 确认按钮。值为 null 则不显示确认按钮值为字符串则自定义按钮文本值为 Object 则透传 Button 组件属性 | N | | first-day-of-week | Number | 0 | 第一天从星期几开始默认 0 周日 | N | | format | Function | - | 用于格式化日期的函数 | N | | locale-text | Object | - | 国际化文案 | N | | max-date | Number | - | 最大可选的日期不传则默认半年后 | N | | min-date | Number | - | 最小可选的日期不传则默认今天 | N | | readonly | Boolean | - |1.9.7。是否只读只读状态下不能选择日期 | N | | switch-mode | String | none |1.8.2。切换模式none 平铺所有月份month 按月切换year-month 既按年也按月切换 | N | | title | String | - | 标题不传默认为请选择日期 | N | | type | String | single | 选择类型single 单选multiple 多选range 区间选择 | N | | use-popup | Boolean | true |0.32.0。是否使用弹出层包裹日历 | N | | using-custom-navbar | Boolean | false | 是否使用了自定义导航栏 | N | | value | Number / Array | - | 当前选择的日期不传则选用 minDate 或今天优先级 minDate todaytype 为 multiple 或 range 时传数组 | N | | default-value | Number / Array | undefined | 同上非受控属性 | N | | visible | Boolean | false | 是否显示日历usePopup 为 true 时有效 | N |2.1 选择类型 typesingle / multiple / rangetype控制日历的核心行为对应 type.ts 中TdCalendarProps.type的类型single | multiple | range默认single。三种模式的差异在底层算法类 common/shared/calendar/index.ts 的select与calcType中体现single点击即选中value为单个时间戳multiple点击切换选中/取消value为时间戳数组源码中用isSameDate判断是否已选中已选中则从数组移除否则追加range第一次点击作为起点第二次点击作为终点value为[start, end]数组若点击日期早于起点则重新以该日期为起点。当起止日期相同且allowSameDay为 false 时区间会被重置为仅含起点。区间模式下的日期状态由calcType计算得出起点为start、终点为end、中间日期为centre起止相同且allowSameDay时为start-end。2.2 翻页切换 switch-modenone / month / year-monthswitch-mode用于控制月份/年份的切换方式1.8.2引入none默认平铺展示minDate到maxDate之间的所有月份滚动查看month一次展示一个月头部提供前后月份切换按钮year-month在month基础上增加前后年份切换按钮。从 calendar-header.wxml 可以看到year-month模式会渲染chevron-left-double/chevron-right-double按年切换与chevron-left/chevron-right按月切换图标且切换按钮的禁用状态由 calendar.ts 中updateActionButton依据minDate/maxDate计算。切换行为定义在handleSwitchModeChange其底层月份/年份偏移逻辑见 utils.tsgetPrevMonth/getNextMonth/getPrevYear/getNextYear。2.3 日期范围 min-date / max-date 与默认值规则minDate最小可选日期不传默认今天底层 common/shared/date.ts 的getDate()maxDate最大可选日期不传默认半年后getDate(6)即当前日期 6 个月value不传时初始值优先取minDate否则取今天 0 点的时间戳range模式会将终点初始化为起点次日见 calendar.tsinitialValue。超出范围、早于minDate或晚于maxDate的日期会被标记为disabled不可点击。2.4 确认按钮 confirm-btn 的三种形态confirm-btn支持字符串 / 对象 /null三种取值默认值为null不显示确认按钮此时typesingle或区间已选满rawValue.length 2时选择完即自动关闭并触发change事件值为字符串自定义按钮文本如confirm-btn好的值为对象透传 Button 组件属性例如{ content: ok, theme: danger }。测试用例test/index.test.js 中的:custom button用例验证了confirmBtn: { content: ok }时按钮文本为ok:without-button用例验证了confirm-btn{{null}}时点击日期立即返回结果。在组件内部confirmBtn的 observer 会将字符串转为{ content }对象将slot特殊值交给插槽渲染见 calendar.ts 的confirmBtnobserver。2.5 格式化函数 format为日期附加文字format是形如(day: TDate) TDate的函数CalendarFormatType定义见 type.ts其中type TDateType selected | disabled | start | start-end | centre | end | ; interface TDate { date: Date; day: number; type: TDateType; className?: string; prefix?: string; suffix?: string; }它会在每个日期格子渲染前被调用返回值可修改prefix格子上方文字、suffix格子下方文字与className。模板 template.wxml 中prefix与suffix分别渲染在日期上下方suffix的状态色选中/起点/终点为反色禁用为弱色在 calendar.less 中定义。官方示例 custom-text/index.js 展示了两种典型用法singleFormat(day) { day.suffix ¥60; return day; }, format(day) { const { date } day; const year date.getFullYear(); const month date.getMonth() 1; const curDate date.getDate(); day.suffix ¥60; if (year 2022) { if (month 2) { const map { 1: 初一, 2: 初二, 3: 初三, 14: 情人节, 15: 元宵节 }; if (curDate in map) { day.prefix map[curDate]; // 格子上方文字 day.suffix ¥100; // 格子下方文字 day.className is-holiday; // 附加样式类 } } } return day; },2.6 国际化 locale-textlocaleText的 TS 类型为CalendarLocaleTextinterface CalendarLocaleText { title?: string; // 标题文案 weekdays?: string[]; // 星期表头长度为 7 的数组 monthTitle?: string; // 月份标题模板支持 {year} / {month} 占位符 months?: string[]; // 12 个月的名称数组 confirm?: string; // 确认按钮文案 }组件内置中文语言包locale/zh_CN.tstitle: 请选择日期、weekdays: [日,一,...]、monthTitle: {year} 年 {month}、months: [1 月, ...]、confirm: 确认。月份标题中的{year}/{month}占位符由 calendar.wxs 的getMonthTitle完成替换月份自动补零。官方国际化示例 local-text/index.js 配置了英文文案localeText: { title: Select Date, weekdays: [Sun, Mon, Tue, Wed, Thu, Fri, Sat], monthTitle: {month} {year}, confirm: Confirm, months: [January, February, /* ... */ December], },组件通过 using-config.ts 的usingConfigBehavior 订阅全局语言包当通过config-provider修改全局locale时组件会自动刷新文案。localeText与全局配置的合并逻辑由 config-provider/use-config.ts 处理localeText的优先级更高。2.7 弹层与可见性use-popup / visible / auto-closeusePopup默认true为 true 时日历由底部弹层t-popupplacementbottom包裹模板见 calendar.wxml为 false 时日历直接平铺在页面中官方示例 without-popup/index.wxml 即展示内嵌用法visible控制弹层显隐仅在usePopup为 true 时有效默认 falseautoClose默认true点击关闭按钮、确认按钮、遮罩层时自动关闭弹层。组件 calendar.ts 的close(trigger)方法会在autoClose为 true 时主动将visible置为 false并触发close事件usingCustomNavbar页面使用自定义导航栏时置为 true弹层会避开自定义导航栏区域。三、Calendar Events事件体系与触发时机| name | params | description | | -- | -- | -- | | change |(value: timestamp)|0.28.0。不显示 confirm-btn 时完成选择时触发暂不支持 type multiple | | close |(trigger: CalendarTrigger)|0.34.0。关闭时触发trigger取值见下方类型定义 | | confirm |(value: timestamp)| 点击确认按钮时触发 | | panel-change |(detail: { year, month })|1.8.4。切换月或年时触发switch-mode 不为 none 时有效 | | scroll |({scrollLeft, scrollTop, scrollHeight, scrollWidth, deltaX, deltaY})|1.4.6。滚动时触发 | | select |(value: timestamp)|0.28.0。点击日期时触发 |close事件的CalendarTrigger类型为type CalendarTrigger close-btn | confirm-btn | overlay | auto-close;对应四种关闭来源点击关闭按钮、点击确认按钮、点击遮罩层、自动关闭。从源码看事件触发链路selecthandleSelect中点击有效日期后触发若readonly或日期为disabled则直接返回见 calendar.tshandleSelectconfirmonTplButtonTap中读取当前值后触发同时关闭弹层close(confirm-btn)change在不显示确认按钮confirmBtn null且单选或区间已选满时选择完成即触发并关闭弹层注意文档说明change暂不支持 type multiplepanel-changehandleSwitchModeChange在切换月份/年份时触发回调参数month为 1 起始源码中month 1scroll由scroll-view的bindscroll直接转发事件详情。value是受控属性controlledProps将value绑定到confirm与change事件同时提供非受控的defaultValue属性二者用法与文档中value的默认值规则一致。测试用例test/index.test.js 验证了关键行为点击 disabled 日期不改变 value、点击普通日期不立即触发 confirm需点击确认按钮、关闭按钮触发close等。四、Calendar Slots自定义插槽| name | Description | | -- | -- | | confirm-btn | 确认按钮 | | title | 标题 |title插槽替换日历顶部标题配合title属性使用不传插槽时展示title属性或语言包文案confirm-btn插槽完全自定义确认按钮区域。使用插槽前需将confirm-btn设置为字符串slot组件内部 calendar.ts 的confirmBtnobserver 会将slot值识别为插槽渲染模式插槽内容仅在usePopup为 true 时渲染见 template.wxml。五、CSS Variables主题定制组件提供以下 CSS 变量用于自定义样式默认值取自 TDesign 设计令牌| Name | Default Value | Description | | -- | -- | -- | | --td-calendar-active-color | brand-color | 选中态背景色 | | --td-calendar-bg-color | bg-color-container | 日历背景色 | | --td-calendar-days-color | text-color-secondary | 星期表头文字色 | | --td-calendar-item-centre-color | brand-color-light | 区间中间日期背景色 | | --td-calendar-item-disabled-color | text-color-disabled | 禁用日期文字色 | | --td-calendar-item-suffix-color | text-color-placeholder | 日期下方文字色 | | --td-calendar-radius | radius-extraLarge | 弹层圆角 | | --td-calendar-selected-border-radius | radius-default | 选中格子圆角 | | --td-calendar-selected-color | text-color-anti | 选中态文字色 | | --td-calendar-switch-mode-icon-color | text-color-secondary | 翻页图标颜色 | | --td-calendar-switch-mode-icon-disabled-color | text-color-disabled | 翻页图标禁用色 | | --td-calendar-title-color | text-color-primary | 标题文字色 | | --td-calendar-title-font | font-title-large | 标题字体 |这些变量在 calendar.less 中逐一声明为 Less 变量并使用例如calendar-active-color: var(--td-calendar-active-color, brand-color);因此在业务页面中可通过page或组件外层作用域直接覆盖变量例如page { --td-calendar-active-color: #00a870; --td-calendar-radius: 24rpx; }六、完整可运行示例区间选择日历综合以上知识点一个完整的区间选择日历示例对应官方示例 range/index.wxml 与 range/index.js如下WXMLt-calendar visible{{visible}} value{{value}} minDate{{minDate}} maxDate{{maxDate}} typerange bind:confirmhandleConfirm / view classwrapper bind:taphandleCalendar view classwrapper__left{{_this.formatTimestamp(value[0])}}/view t-icon classwrapper__center nameswap-right size40rpx / view classwrapper__right{{_this.formatTimestamp(value[1])}}/view /viewJSComponent({ data: { visible: false, value: [new Date(2024, 11, 5).getTime(), new Date(2024, 11, 10).getTime()], minDate: new Date(2024, 10, 1).getTime(), maxDate: new Date(2024, 12, 1).getTime(), }, methods: { handleCalendar() { this.setData({ visible: true }); }, handleConfirm(e) { this.setData({ value: e.detail.value }); }, }, });示例中时间戳格式化工具函数见 _example/calendar.wxs 的formatTimestamp演示了如何在 WXML 层将时间戳转换为YYYY-MM-DD字符串多选/区间场景以、拼接。七、底层原理月份渲染与日期状态计算Calendar 的日期算法被抽离为独立的纯类TCalendarcommon/shared/calendar/index.ts组件实例在created生命周期中初始化this.base new TCalendar(this.properties)后续所有选择、月份计算均委托给该类getMonths()从minDate到maxDate逐月生成数据每项包含year、month、months该月每日的TDate数组含type状态与weekdayOfFirstDay首日星期几用于 WXML 中补齐前导空格calcType()根据当前type与已选值判定每日状态selected/disabled/start/centre/end/start-end并调用format函数加工prefix/suffix/classNameselect()处理三种类型的选择逻辑单选覆盖、多选增删、区间两点选法getDays(weekdays)根据firstDayOfWeek重排星期表头顺序。月份切换的边界控制由 calendar.ts 的updateActionButton完成将目标月份与minDate/maxDate所在月份做时间戳比较越界时置灰对应翻页按钮。switchMode为none时全部月份一次性渲染进scroll-view并利用scrollIntoView定位到当前值所在月份为month/year-month时仅渲染currentMonth单月面板。快照测试位于test/snapshots覆盖基础、多选、区间、翻页、国际化、自定义文案、自定义范围、不使用弹层等 8 个示例场景见test/demo.test.js 的 mapper 列表可作为理解组件渲染结果的参考。八、常见使用要点小结最小可用t-calendar visible{{visible}} bind:confirmonConfirm /即可得到一个默认单选、弹层展示、自动关闭的日历隐藏确认按钮confirm-btn{{null}}单选或区间选满后自动完成并触发change嵌入页面use-popup{{false}}将日历平铺在页面配合bind:select使用只读readonly1.9.7起禁止点击选择区间同日typerange且需要允许起止同日时开启allow-same-day1.11.2起翻页联动switch-modeyear-month并监听panel-change获取当前年月的回调自定义文字通过format为每个日期追加prefix/suffix/className多语言全局走config-provider切换locale局部覆盖用locale-text。如需进一步了解组件在全局配置、弹层、按钮、图标等基础设施上的实现可继续阅读 config-provider、popup、button、icon 等目录下的对应文档与源码。赞分享前端UI组件小程序设计系统移动开发【免费下载链接】tdesign-miniprogramWechat MiniProgram and Uniapp UI components lib for TDesign项目地址https://gitcode.com/gh_mirrors/tde/tdesign-miniprogram点击查看免费下载相关推荐TDesign Uniapp Calendar 日历组件全解析API 配置、事件体系与源码实现原理TDesign Uniapp Calendar 日历组件全解析API 配置、事件体系与源码实现原理 本文以 TDesign 开源仓库中 packages/un前端UI组件小程序设计系统移动开发终极指南wx-calendar微信小程序日历组件从零到精通实战终极指南wx calendar微信小程序日历组件从零到精通实战 在日常的小程序开发中你是否遇到过这样的场景需要为用户展示一个可交互的日历界面让用户能够轻UI组件移动开发TDesign 小程序骨架屏 Skeleton 组件完全指南从配置到源码实现TDesign 小程序骨架屏 Skeleton 组件完全指南从配置到源码实现 TDesign 小程序tdesign miniprogram的 Skelet前端UI组件小程序设计系统移动开发创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考