← 中文资源

简体中文版本

面向前端的月历网格构建器

为任意月份生成七列日历网格,支持配置每周起始日,并用空值补齐前后空白单元格。

阅读英文原文

功能说明

日历组件需要把某个月的日期排成七列网格,并补齐前后空白。该函数按 UTC 构造月份第一天,计算相对周起始日的偏移,再生成总长度为 7 的倍数的单元格数组。返回对象包含年份、月份、周起始日和 cells,前端可以直接按索引渲染。

关键代码

weekStartsOn 默认为 0 表示周日,可设为 1 表示周一。offset 用加 7 再取模保证非负。总单元格数向上取整到整周。day 为 1 到当月天数时填入日期,否则填 null。所有日期计算使用 UTC,避免本地时区把月初推到前一天。

const offset = (first.getUTCDay() - weekStartsOn + 7) % 7;
const totalCells = Math.ceil((offset + daysInMonth) / 7) * 7;

使用注意

该网格只包含日期数字,不包含相邻月份日期,需要显示灰色补位时应由 UI 自行计算。weekStartsOn 必须在 0 到 6。返回的 cells 长度可能是 28、35 或 42。年份范围与月份范围会被校验,非法值抛 RangeError。

验证方式

断言 2026 年 10 月以周日开始时 cells 长度为 35,前四个单元格为 null,且包含 1 到 31。weekStartsOn 为 1 时偏移应改变。cells 长度始终能被 7 整除。非法月份、年份或周起始日抛 RangeError。二月闰年应生成 29 个非空日期。