Ant Design DatePicker 设计规范基于行为模式的日期选择场景、交互变体与纯面板实现【免费下载链接】ant-designAn enterprise-class UI design language and React UI library项目地址: https://gitcode.com/gh_mirrors/ant/ant-designAnt Design 的 DatePicker 组件设计文档components/date-picker/index.$tab-design.zh-CN.md围绕一个核心命题展开DatePicker 的本质是选择输入日期型数据。该文档以行为模式Behavior Pattern为骨架把选日期这一模糊需求拆解为时间点 / 时间段 / 快捷选择 / 附属信息四类可枚举的行为场景并为每个场景给出对应的纯面板Pure Panel示例。本文完整继承原文档的组件定义、12 种基础使用场景与 3 种交互变体并结合仓库源码剖析每种场景背后的 prop 机制与纯面板的底层实现帮助你在业务中按规范正确选型、复用与扩展 DatePicker。一、组件定义选择日期数据的行为模式树原文档首先给出 DatePicker 的本质定义并通过一张行为模式地图BehaviorMap把选择输入日期数据这个顶层行为拆解为四个子行为选择时间点MVP 行为选择某天、选择某周、选择某月、选择某季度、选择某年、选择某时间共 6 个原子场景选择时间段MVP 行为选择某天至某天、某周至某周、某月至某月、某季度至某季度、某年至某年、某时间至某时间共 6 个范围场景快捷选择日期数据扩展行为快捷选择时间点、快捷选择时间段查看日期附属信息扩展行为在日期单元格上叠加业务信息。这张行为树在源码中直接体现为 behavior-pattern.tsx。它通过.dumi主题提供的BehaviorMap组件渲染数据是一棵带id、label、targetTypemvp表示核心必备行为extension表示扩展增强行为和children的树。每个叶子节点的link字段如date-picker-index-tab-design-zh-cn-demo-pick-date对应文档中各 demo 的锚点 id从而把设计规范中的行为与可运行的代码示例一一绑定。这种行为 → 场景 → 代码的三层映射是 Ant Design 组件设计文档的典型组织方式。从这份行为树可以提炼出一条选型原则先判断用户输入的是时间点还是时间段再判断其时间粒度天/周/月/季/年/含时刻六个粒度维度在两种形态下构成 12 个基础场景。二、基础使用12 个场景的纯面板实现文档基础使用一节列出 12 个 demo每个 demo 都附带一句何时使用的判定标准这是选型时最实用的依据行为场景何时使用对应 demo选择某天用户仅需要输入非常具体的日期信息时使用pick-date.tsx选择某周用户仅需输入年份 周信息时使用pick-week.tsx选择某月用户仅需输入年份 月份信息时使用pick-month.tsx选择某季度用户仅需输入年份 季度信息时使用pick-quarter.tsx选择某年用户仅需输入年份时使用pick-year.tsx选择某时刻用户需输入年份月份日期时间信息时使用pick-time.tsx选择某天至某天用于具体日期范围的选择pick-date-range.tsx选择某周至某周用于周范围的选择pick-week-range.tsx选择某月至某月用于月范围的选择pick-month-range.tsx选择某季度至某季度用于季度范围的选择pick-quarter-range.tsx选择某年至某年用于年范围的选择pick-year-range.tsx选择某时刻至某时刻用于具体时刻范围的选择pick-time-range.tsx这 12 个示例共享同一套实现模式全部使用 DatePicker 挂载的纯面板内部组件而非完整的带输入框的 Picker。以选择某天为例pick-date.tsx 的完整代码如下import React from react; import { DatePicker } from antd; const { _InternalPanelDoNotUseOrYouWillBeFired: PureDatePicker } DatePicker; const Demo: React.FC () PureDatePicker /; export default Demo;其余 11 个场景只是在这行PureDatePicker //PureRangePicker /上叠加不同的 prop可以归纳为三条规则规则一粒度由pickerprop 控制单点形态。时间粒度场景各自只改动一个 propPureDatePicker pickerweek / // 选择某周 PureDatePicker pickermonth / // 选择某月 PureDatePicker pickerquarter / // 选择某季度 PureDatePicker pickeryear / // 选择某年规则二含时刻的选择由showTime开启。不需要改动picker直接在日期面板上叠加时间列PureDatePicker showTime / // 选择某时刻 PureRangePicker showTime / // 选择某时刻至某时刻规则三时间段形态统一替换为纯范围面板_InternalRangePanelDoNotUseOrYouWillBeFired。例如选择某周至某周pick-week-range.tsx为PureRangePicker pickerweek /选择某年至某年为PureRangePicker pickeryear /。纯面板组件的来源genPurePanel 机制这两个以_Internal...DoNotUseOrYouWillBeFired命名的组件可以在 components/date-picker/index.tsx 中找到完整定义import genPurePanel from ../_util/PurePanel; import generatePicker from ./generatePicker; import { transPlacement2DropdownAlign } from ./util; const DatePicker generatePickerDayjs(dayjsGenerateConfig); // We don care debug panel const PurePanel genPurePanel(DatePicker, picker, null, postPureProps); (DatePicker as DatePickerType)._InternalPanelDoNotUseOrYouWillBeFired PurePanel; const PureRangePanel genPurePanel(DatePicker.RangePicker, picker, null, postPureProps); (DatePicker as DatePickerType)._InternalRangePanelDoNotUseOrYouWillBeFired PureRangePanel;这里有几个值得注意的实现事实DatePicker 本体由generatePickerDayjs(dayjsGenerateConfig)工厂生成基于rc-picker/lib/generate/dayjs即以 dayjs 作为日期库绑定generatePicker工厂位于 components/date-picker/generatePicker/index.tsx其类型定义在 components/date-picker/generatePicker/interface.ts。纯面板通过通用工具 components/_util/PurePanel.tsx 的genPurePanel从完整 Picker 中剥离出来——保留面板本体、去掉输入框与弹层逻辑因此设计稿中演示的是面板本身而非输入控件这与组件定义中DatePicker 的本质是选择输入日期型数据相呼应设计阶段关注的是选择面板的行为而非输入交互。纯面板会经过postPureProps后处理调用 components/date-picker/util.ts 中的transPlacement2DropdownAlign把placement转换为dropdownAlign并将adjustY、adjustX强制置为false即纯面板不做弹层位置自适应修正——这正是面板固定在页面内演示所需要的行为。组件名中的 DoNotUseOrYouWillBeFired 是 Ant Design 的命名惯例表明它们是供内部/演示使用的非稳定 API业务代码应使用正式的DatePicker、DatePicker.RangePicker等导出或generatePicker定制日期库。三、交互变体快捷预置与日期附属信息文档交互变体一节定义了两种在基础行为之上的扩展交互均属于行为树中标记为extension的场景。1. 快捷选择时间点 / 快捷选择时间段presets原文档的说明是通过面板左侧区域提供的预置项帮助用户快速完成时间点的选择时间段同理并给出两条设计约束tip根据希克定律Hicks Law建议快捷选项的个数不超过 8 个。希克定律描述的是选项数量越多决策时间越长因此预置项过多反而会拖慢高频操作路径上限 8 条是该文档明确给出的经验值。单点形态的预置项在 preset-time.tsx 中实现presets接收{ label, value }数组value为 dayjs 对象PureDatePicker presets{[ { label: Yesterday, value: dayjs().add(-1, d) }, { label: Last Week, value: dayjs().add(-7, d) }, { label: Last Month, value: dayjs().add(-1, month) }, ]} /时间段形态在 preset-range.tsx 中实现类型使用TimeRangePickerProps[presets]value为[起, 止]的 dayjs 二元组import type { TimeRangePickerProps } from antd; const rangePresets: TimeRangePickerProps[presets] [ { label: Last 7 Days, value: [dayjs().add(-7, d), dayjs()] }, { label: Last 14 Days, value: [dayjs().add(-14, d), dayjs()] }, { label: Last 30 Days, value: [dayjs().add(-30, d), dayjs()] }, { label: Last 90 Days, value: [dayjs().add(-90, d), dayjs()] }, ]; PureRangePicker presets{rangePresets} /两条示例共同印证了设计模式预置项 语义化标签 相对当前时刻动态计算的目标值而不是写死的日期这样最近 7 天在任何打开面板的时刻都成立。2. 查看日期附属信息dateRender文档对该场景的定义是通过定义日期单元格内容及样式为用户展示更多业务场景相关信息作为选择参考。这是 122 个场景中实现复杂度最高的一个date-extra-info.tsx 用同一套dateRender机制演示了三种业务场景办公场景预览节假日信息—— 周末日期current.day()为 6 或 0整格标红电商场景预览销售额信息—— 单元格在日期下方追加一行销售额数字并加宽单元格尺寸大数据场景预览数据波动—— 在日期下方追加环比涨跌百分比正负值分别用绿/红色区分。其实现要点可拆为三层结构层dateRender返回的节点必须保留ant-picker-cell-inner类名示例中使用classNames(ant-picker-cell-inner, ...)保证否则单元格布局会破坏数据层示例用 30 个随机种子seeds模拟日期 → 业务数值的映射getSales、getData生产环境中替换为真实的节假日表、销售 API 或指标数据即可接口形态不变样式层附属小字用transform: scale(10/12)从 12px 缩放到 10px 视觉大小并随单元格状态变色——默认token.colorTextQuaternary当前月ant-picker-cell-in-view提升为token.colorTextSecondary选中态ant-picker-cell-selected反白为#fff保证信息在三种状态下都可读。加宽单元格还需通过popupClassName放开面板的定宽const detailedPicker css .ant-picker-date-panel { width: auto; .ant-picker-content { width: auto; } } ; PureDatePicker dateRender{saleDateRender} popupClassName{styles.detailedPicker} /这组示例同时展示了 Ant Design 的主题 tokentoken.colorTextQuaternary等如何参与自定义渲染属于用主题变量写业务样式的规范做法。四、规范要点回顾把这份设计文档的脉络收敛为可执行的检查清单先定形态用户要的是时间点还是时间段时间段一律走RangePicker纯面板场景用_InternalRangePanelDoNotUseOrYouWillBeFired再定粒度天 / 周 / 月 / 季度 / 年由picker属性表达含时刻追加showTime两者正交组合覆盖全部 12 个基础场景高频路径加预置用presets提供昨天、最近一周类快捷项数量不超过 8 个希克定律决策辅助上信息需要用户在面板内获得业务上下文节假日、销量、涨跌时用dateRender重写单元格内容保留ant-picker-cell-inner类名并处理 in-view / selected 两种状态的颜色设计稿演示用纯面板DatePicker._InternalPanelDoNotUseOrYouWillBeFired/_InternalRangePanelDoNotUseOrYouWillBeFired由 genPurePanel 生成并禁用弹层自适应仅供演示与调试业务集成请使用正式导出的DatePicker系列组件。以上所有行为场景与交互变体的完整定义见 components/date-picker/index.$tab-design.zh-CN.md行为树数据见 components/date-picker/design/behavior-pattern.tsx组件导出与纯面板挂载逻辑见 components/date-picker/index.tsx。【免费下载链接】ant-designAn enterprise-class UI design language and React UI library项目地址: https://gitcode.com/gh_mirrors/ant/ant-design创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考