feat(calendar): add function to support setting start or end of range separately

[shumuuu]

🤔 这个 PR 的性质是？

• 日常 bug 修复
• 新特性提交
• 文档改进
• 演示代码改进
• 组件样式/交互改进
• CI/CD 改进
• 重构
• 代码风格优化
• 测试用例
• 分支合并
• 其他

🔗 相关 Issue

• [calendar] range支持单独设置开始时间或结束时间 tdesign-vue-next#6125
• feat(calendar): support setting start or end of range separately tdesign-vue-next#6211

💡 需求背景和解决方案

单独设置日历范围上/下限本质上为完善对range参数传入值的数据处理，即处理以下情况：

1. 传入非列表值/传入列表值少于两项/传入列表值的两项均非日期格式
2. 传入列表值的两项中有一项符合日期格式，另一项不符合
3. 传入列表值的两项均符合日期格式

以上核心在于判断列表值的两项是否符合日期格式，故首先增加了一个日期格式校验逻辑

// js\calendar\utils.ts L21~35
const parseRangeBoundary = (
  value: CalendarRange['from'] | CalendarRange['to'] | null | undefined
) => {
  if (value === undefined || value === null) {
    return null;
  }
  const parsed = dayjs(value);
  if (!parsed.isValid()) {
    return null;
  }
  return {
    parsed, // dayjs 对象
    original: value as CalendarRange['from'] | CalendarRange['to'], // 原始值
  };
};

然后在解构出列表值的两项后先进行日期格式校验即可直接处理第一种情况。

// js\calendar\utils.ts L41~42
const start = parseRangeBoundary(v1);
const end = parseRangeBoundary(v2);

随后添加fallback逻辑，当出现第二种情况时，为空缺的另外一侧边界填充内置值；若为第三种情况则保持原逻辑不变

// js\calendar\utils.ts L49~72
const fallback = (
  edge: 'from' | 'to'
): { parsed: dayjs.Dayjs; original: string } => {
  let fallbackParsed = dayjs(MIN_YEAR);
  if (edge === 'to') {
    fallbackParsed = createDefaultCurDate();
  }
  return {
    parsed: fallbackParsed,
    original: fallbackParsed.format('YYYY-MM-DD'),
  };
};

let fromBoundary = start ?? fallback('from');
let toBoundary = end ?? fallback('to');

if (fromBoundary.parsed.isAfter(toBoundary.parsed)) {
  [fromBoundary, toBoundary] = [toBoundary, fromBoundary]; // 当前一项日期大于后一项时交换两值以确保边界逻辑正确
}

return {
  from: fromBoundary.original,
  to: toBoundary.original,
};

📝 更新日志

• feat(calendar): 新增calendar组件的公用类型和公用常量

• feat(calendar): 新增range参数处理函数以支持单独设置日历范围上限或下限

• test(calendar): 新增createDefaultCurDate和handleRange的测试案例并提升覆盖率至100%

• 本条 PR 不需要纳入 Changelog

☑️ 请求合并前的自查清单

⚠️ 请自检并全部勾选全部选项。⚠️

• 文档已补充或无须补充
• 代码演示已提供或无须提供
• TypeScript 定义已补充或无须补充
• Changelog 已提供或无须提供

[tdesign-bot]

TDesign Component Repositories CI Test Open

Component	Lint	Test	Build	Preview
tdesign-vue	✅	✅	✅	👀
tdesign-vue-next	✅	✅	✅	👀
tdesign-react	✅	✅	✅	👀
tdesign-web-components	✅	✅	✅	👀
tdesign-mobile-vue	✅	✅	✅	👀
tdesign-mobile-react	✅	✅	✅	👀

[Copilot]

Pull request overview

This PR adds support for setting calendar range boundaries independently by enhancing the range parameter handling in the calendar component. It allows users to specify only a start date (using a fallback for the end) or only an end date (using a fallback for the start), rather than requiring both boundaries to be valid dates.

Key changes:

• New utility function handleRange processes range inputs with flexible boundary validation, using fallback values (1970-01-01 for start, current date for end) when one boundary is invalid
• New type definitions (CalendarValue, CalendarRange) to support string or Date formats for calendar ranges
• Comprehensive test suite with 100% coverage for the new utility functions

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 3 comments.

File	Description
js/calendar/types.ts	Defines CalendarValue and CalendarRange types to support string or Date range boundaries
js/calendar/consts.ts	Exports MIN_YEAR constant (1970) used as fallback for undefined start boundary
js/calendar/utils.ts	Implements handleRange function with boundary validation, fallback logic, and automatic swapping for out-of-order dates
test/unit/calendar/utils.test.js	Adds comprehensive test coverage for createDefaultCurDate and handleRange functions across all scenarios

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.