Semi Design 日期选择器(DatePicker)组件深度解析

Semi Design 日期选择器(DatePicker)组件深度解析

semi-design 🚀A modern, comprehensive, flexible design system and React UI library. 🎨 Provide more than 2800+ Design Tokens, easy to build your design system. Make Semi Design to Any Design. 🧑🏻‍💻 Design to Code in one click 项目地址: https://gitcode.com/gh_mirrors/se/semi-design

概述

Semi Design 的 DatePicker 日期选择器是一个功能强大的组件，用于帮助用户选择符合要求的日期或时间范围。它提供了多种日期选择模式，包括单日期选择、日期范围选择、时间选择等，并支持高度自定义。

基本使用

安装与引入

首先需要确保项目中已经安装了 Semi Design 组件库，然后可以通过以下方式引入 DatePicker 组件：

import { DatePicker } from '@douyinfe/semi-ui';

最简单的日期选择

最基本的 DatePicker 使用方式如下：

<DatePicker onChange={(date, dateString) => console.log(dateString)} />

这个最简单的实现会渲染一个日期选择输入框，当用户选择日期后会触发 onChange 回调，返回 Date 对象和格式化后的日期字符串。

核心功能详解

1. 日期选择类型

DatePicker 支持多种日期选择类型，通过 type 属性控制：

• date：默认值，选择单个日期
• dateTime：选择日期和时间
• dateRange：选择日期范围
• dateTimeRange：选择日期时间范围
• month：选择年月
• monthRange：选择年月范围

// 日期时间选择
<DatePicker type="dateTime" />

// 日期范围选择
<DatePicker type="dateRange" style={{ width: 260 }} />

2. 尺寸控制

通过 density 属性可以控制日期面板的尺寸：

• default：默认尺寸
• compact：紧凑尺寸

<DatePicker type="dateTime" density="compact" />

3. 多日期选择

设置 multiple 属性为 true 可以实现多日期选择：

<DatePicker multiple={true} style={{ width: 240 }} />

4. 内嵌输入框

从 v2.7.0 开始支持 insetInput 属性，可以在日期面板中内嵌输入框：

<DatePicker type="dateTime" insetInput />

内嵌输入框特别适合以下场景：

• 日期时间选择时直接修改时间
• 范围选择时单独修改开始/结束日期

5. 周选择功能

结合 startDateOffset 和 endDateOffset 可以实现周选择功能：

<DatePicker
  type="dateRange"
  startDateOffset={date => dateFns.startOfWeek(date, { weekStartsOn: 1 })}
  endDateOffset={date => dateFns.endOfWeek(date, { weekStartsOn: 1 })}
/>

6. 确认选择模式

对于日期时间选择，可以启用确认选择模式：

<DatePicker
  type="dateTime"
  needConfirm={true}
  onConfirm={(...args) => console.log('Confirmed: ', ...args)}
  onCancel={(...args) => console.log('Canceled: ', ...args)}
/>

高级功能

1. 禁用特定日期/时间

通过 disabledDate 和 disabledTime 可以禁用特定日期和时间：

// 禁用今天下午5-6点
<DatePicker 
  type="dateTime" 
  disabledTime={date => 
    dateFns.isToday(date) ? { disabledHours: () => [17, 18] } : null
  } 
/>

2. 自定义显示格式

使用 format 属性可以自定义日期显示格式：

<DatePicker format="yyyy年MM月dd日 HH:mm" type="dateTime" />

3. 自定义触发器

通过 triggerRender 可以完全自定义触发器：

<DatePicker
  triggerRender={({ placeholder }) => (
    <Button theme={'light'} icon={date ? <IconClose /> : <IconChevronDown />}>
      {date ? dateFns.format(date, formatToken) : placeholder}
    </Button>
  )}
/>

4. 快捷选择面板

使用 presets 属性可以添加快捷选择项：

const presets = [
  { text: 'Today', start: new Date(), end: new Date() },
  { text: 'Tomorrow', start: new Date(new Date().valueOf() + 1000 * 3600 * 24) }
];

<DatePicker type="dateTime" presets={presets} />

最佳实践

1. 范围选择的注意事项

• 只有开始和结束日期都选择后才会触发 onChange
• 可以使用 syncSwitchMonth 同步切换双面板月份
• 可以通过 onPanelChange 监听面板月份切换

2. 时区处理

当使用 timeZone 属性时：

• disabledDate 和 disabledTime 的第一个参数是选择时区下的时间
• onChange 返回的 Date 对象也会考虑时区

3. 性能优化

对于复杂的自定义渲染，建议使用 useMemo 和 useCallback 优化性能：

const disabledDate = useMemo(() => 
  activeTab === '1' ? uedDisabledDate : testDisabledDate
, [activeTab]);

总结

Semi Design 的 DatePicker 组件提供了丰富的日期选择功能，从简单的日期选择到复杂的范围选择、时间选择都支持良好。通过灵活使用各种属性和回调函数，可以满足绝大多数业务场景的需求。特别是其内嵌输入框、自定义触发器等高级功能，为开发者提供了极大的灵活性。

semi-design 🚀A modern, comprehensive, flexible design system and React UI library. 🎨 Provide more than 2800+ Design Tokens, easy to build your design system. Make Semi Design to Any Design. 🧑🏻‍💻 Design to Code in one click 项目地址: https://gitcode.com/gh_mirrors/se/semi-design