ant-design TimePicker 基础用法指南点击选择或输入时间的完整实践【免费下载链接】ant-designAn enterprise-class UI design language and React UI library项目地址: https://gitcode.com/gh_mirrors/ant/ant-design导读本篇文章以 ant-design 仓库中 TimePicker 组件的基础示例components/time-picker/demo/basic.md为骨架系统讲解点击 TimePicker 输入框在浮层面板中选择或直接输入某一时间这一最核心交互的完整实现路径。读完本文你将掌握 TimePicker 的最小可用写法、与 dayjs 的配合方式、onChange回调的双参数语义、defaultOpenValue等关键属性的作用以及受控用法、12 小时制、步长选项、选择确认、RangePicker 等进阶实践的源码级原理。一、示例文档原文与最小可运行代码basic.md对基本用法的描述非常凝练点击 TimePicker然后可以在浮层中选择或者输入某一时间英文原文 ClickTimePicker, and then we could select or input a time in panel。其配套的完整示例代码位于 components/time-picker/demo/basic.tsx是全仓库所有 TimePicker 用例中最小、最基础的入口import React from react; import type { TimePickerProps } from antd; import { TimePicker } from antd; import dayjs from dayjs; import customParseFormat from dayjs/plugin/customParseFormat; dayjs.extend(customParseFormat); const onChange: TimePickerProps[onChange] (time, timeString) { console.log(time, timeString); }; const App: React.FC () ( TimePicker onChange{onChange} defaultOpenValue{dayjs(00:00:00, HH:mm:ss)} / ); export default App;这段代码浓缩了 TimePicker 基础使用的全部要点下面逐项拆解。二、dayjsTimePicker 的时间值载体2.1 为什么必须引入 dayjs从 components/time-picker/index.zh-CN.md 的 API 表可以看到value、defaultValue等与时间相关的属性类型统一为 dayjs 对象而不是原生Date或字符串。ant-design 5.x 的 TimePicker 在底层完全基于 dayjs 构建因此使用前需要import dayjs from dayjs;2.2 customParseFormat 插件的作用示例代码中特意执行了dayjs.extend(customParseFormat)。这一步并非多余dayjs 默认只能解析 ISO 8601 格式的字符串而 TimePicker 场景中我们经常要按自定义格式如HH:mm:ss解析时间字符串。加载customParseFormat插件后dayjs(00:00:00, HH:mm:ss)才能按模板正确解析出零点零分零秒否则会返回 Invalid Date。这一点在index.zh-CN.md的 API 快速示例中也有同样的写法印证import dayjs from dayjs; import customParseFormat from dayjs/plugin/customParseFormat dayjs.extend(customParseFormat) TimePicker defaultValue{dayjs(13:30:56, HH:mm:ss)} /;三、onChange 回调双参数的取值约定const onChange: TimePickerProps[onChange] (time, timeString) { console.log(time, timeString); };onChange是时间发生变化时的回调签名定义在 API 表中为参数类型说明onChangefunction(time: dayjs, timeString: string): void时间发生变化的回调两个参数分别代表time选中或输入后的时间类型为dayjs.Dayjs对象适合直接存入状态或传给后端做进一步处理timeString按当前format格式化后的字符串例如默认格式HH:mm:ss下的14:30:00适合直接展示或提交表单。建议像示例一样用TimePickerProps[onChange]类型标注回调从而获得完整的参数类型推导。该回调会在用户从浮层面板选择某一项或直接在输入框中键入合法时间失焦/确认后时触发。四、defaultOpenValue面板未选值时的占位时间TimePicker onChange{onChange} defaultOpenValue{dayjs(00:00:00, HH:mm:ss)} /defaultOpenValue决定浮层面板在还没有任何选择时默认高亮/定位的时间。它与defaultValue的区别在于defaultValue会真正写入输入框作为初始值而defaultOpenValue只影响面板打开时的默认定位示例设为00:00:00即打开面板默认从零点开始浏览输入框本身仍可保持为空。这在输入框留空、但希望用户打开面板时从某个时间起点开始选择的场景下非常实用。五、TimePicker 的底层实现它是 DatePicker 的特化从 components/time-picker/index.tsx 的源码可以看到TimePicker 并不是从零实现的独立组件而是对 DatePicker 的封装特化const { TimePicker: InternalTimePicker, RangePicker: InternalRangePicker } DatePicker;其中 RangePicker 通过显式指定pickertime来获得时间选择形态const RangePicker React.forwardRefPickerRef, TimeRangePickerProps((props, ref) ( InternalRangePicker {...props} pickertime mode{undefined} ref{ref} / ));同时TimePicker 主组件在内部做了两件关键事情兼容旧属性addon开发环境下会对仍在使用addon的代码发出deprecated警告建议迁移到renderExtraFooter见 index.tsx形态variant合并通过useVariant(timePicker, variant, bordered)将variant与旧版bordered属性归一支持outlined/borderless/filled三种形态。理解这层封装关系有助于排错TimePicker 的浮层、聚焦、失焦等行为本质来自 rc-picker 与 DatePicker 共享的能力。六、浮层中的两种操作选择与输入基础文档描述的核心交互包含两条路径点击弹出浮层选择点击输入框后弹出时分秒列表面板逐列点选小时、分钟、秒选择即时生效未开启needConfirm时。onChange随即触发。直接在输入框键入聚焦输入框后可直接键盘输入如14:30输入符合format的时间后失焦即完成选择。inputReadOnly可设为true强制只读避免移动端弹出虚拟键盘。浮层位置默认在bottomLeft可通过placement调整为bottomLeft | bottomRight | topLeft | topRight浮层默认挂载在 body 新建的 div 上也可用getPopupContainer自定义挂载容器。七、基础之上的高频进阶实践basic.md只是起点仓库 components/time-picker/demo 下围绕同一交互提供了大量可运行示例以下是与你主题强相关的几个7.1 受控组件value 与 onChange 配合使用value.tsx 演示受控用法其说明文档 value.md 强调value 和 onChange 需要配合使用const [value, setValue] useStateDayjs | null(null); const onChange (time: Dayjs) { setValue(time); }; return TimePicker value{value} onChange{onChange} /;7.2 选择确认needConfirmneed-confirm.tsx5.14.0 新增通过needConfirm开启确认按钮此时点选时间不会立即提交需点击确定才触发onChange设为false时失去焦点即代表选择。changeOnScroll5.14.0 新增则可在滚动滚轮时直接改变选择值与needConfirm{false}组合可获得滚动即生效的流畅体验参见 change-on-scroll.tsx。7.3 步长选项hourStep / minuteStep / secondStepinterval-options.tsx 演示了限制面板选项间隔的写法TimePicker minuteStep{15} secondStep{10} hourStep{1} /默认三者均为1业务中常用minuteStep{15}生成 00/15/30/45 的分钟选项。7.4 只选时分hide-column 与 formathide-column.tsx 通过format控制展示粒度const format HH:mm; TimePicker defaultValue{dayjs(12:08, format)} format{format} /;format默认HH:mm:ss当需要只选择时分时同时调整format与defaultValue的解析模板即可。7.5 12 小时制use12Hours12hours.tsx 演示use12Hours开启 12 小时制自动带上 meridiem 上下午列开启时format默认为h:mm:ss a也可自定义为h:mm:ss A或h:mm a。7.6 时间范围RangePickerTimePicker 命名空间下还挂载了TimePicker.RangePicker见 index.tsx其属性与 DatePicker 的 RangePicker 相同额外支持order始末时间是否自动排序默认true与disabledTime。典型用法TimePicker.RangePicker onChange{(times, timeStrings) console.log(times, timeStrings)} /八、禁选时间的类型定义DisabledTime若需要禁止某些时间段例如午休时间不可预约可使用disabledTime属性其类型定义位于 index.zh-CN.mdtype DisabledTime (now: Dayjs) { disabledHours?: () number[]; disabledMinutes?: (selectedHour: number) number[]; disabledSeconds?: (selectedHour: number, selectedMinute: number) number[]; disabledMilliseconds?: ( selectedHour: number, selectedMinute: number, selectedSecond: number, ) number[]; };其中disabledMilliseconds为 5.14.0 新增。RangePicker 对应使用RangeDisabledTime其回调额外携带type: start | end参数以区分起始与结束时间的禁选规则。九、基础 API 速查表结合 components/time-picker/index.zh-CN.md 的官方 API 表与基础用法最相关的核心参数整理如下参数说明类型默认值allowClear自定义清除按钮boolean \| { clearIcon?: ReactNode }true5.8.0 起支持对象autoFocus自动获取焦点booleanfalsedefaultValue默认时间dayjs-disabled禁用全部操作booleanfalsedisabledTime不可选择的时间DisabledTime-format展示的时间格式stringHH:mm:sshourStep / minuteStep / secondStep时分秒选项间隔number1inputReadOnly输入框只读避免移动端弹虚拟键盘booleanfalseneedConfirm是否需要确认按钮boolean-5.14.0open面板是否打开booleanfalseplaceholder无值时的占位文案string \| [string, string]请选择时间placement浮层弹出位置bottomLeft \| bottomRight \| topLeft \| topRightbottomLeftrenderExtraFooter浮层底部自定义内容() ReactNode-showNow是否显示此刻按钮boolean-4.4.0size输入框尺寸large 40px / middle 32px / small 24pxlarge \| middle \| small-status校验状态error \| warning-4.19.0suffixIcon自定义后缀图标ReactNode-use12Hours使用 12 小时制format默认h:mm:ss abooleanfalsevalue当前时间受控dayjs-variant形态变体outlined \| borderless \| filledoutlined5.13.0onChange时间变化回调function(time: dayjs, timeString: string): void-onOpenChange面板开关回调(open: boolean) void-组件实例还暴露focus()与blur()两个方法可用于手动控制焦点。十、测试与更多资料基础示例通过 components/time-picker/tests/demo.test.tsx 等测试文件持续回归验证保证示例代码可运行完整的 API 定义、主题变量与 FAQ 见 components/time-picker/index.zh-CN.md 与 components/time-picker/index.en-US.md若需在 TimePicker 中使用自定义日期库如 Moment.js可参考 docs/react/use-custom-date-library 中关于 TimePicker 的说明。小结从 components/time-picker/demo/basic.tsx 这一最小示例出发你已掌握 TimePicker 的完整使用链路dayjs 与 customParseFormat 的初始化 →onChange双参数取值 →defaultOpenValue的面板定位 → 选择/输入两种交互 → 受控、步长、12 小时制、确认选择、RangePicker 等进阶能力以及其底层DatePicker 特化封装的实现本质。以此为基础即可在真实业务中构建从简单选时到复杂时段禁选的各种时间录入场景。【免费下载链接】ant-designAn enterprise-class UI design language and React UI library项目地址: https://gitcode.com/gh_mirrors/ant/ant-design创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 ant-design TimePicker 基础用法指南：点击选择或输入时间的完整实践
ant-design TimePicker 基础用法指南点击选择或输入时间的完整实践【免费下载链接】ant-designAn enterprise-class UI design language and React UI library项目地址: https://gitcode.com/gh_mirrors/ant/ant-design导读本篇文章以 ant-design 仓库中 TimePicker 组件的基础示例components/time-picker/demo/basic.md为骨架系统讲解点击 TimePicker 输入框在浮层面板中选择或直接输入某一时间这一最核心交互的完整实现路径。读完本文你将掌握 TimePicker 的最小可用写法、与 dayjs 的配合方式、onChange回调的双参数语义、defaultOpenValue等关键属性的作用以及受控用法、12 小时制、步长选项、选择确认、RangePicker 等进阶实践的源码级原理。一、示例文档原文与最小可运行代码basic.md对基本用法的描述非常凝练点击 TimePicker然后可以在浮层中选择或者输入某一时间英文原文 ClickTimePicker, and then we could select or input a time in panel。其配套的完整示例代码位于 components/time-picker/demo/basic.tsx是全仓库所有 TimePicker 用例中最小、最基础的入口import React from react; import type { TimePickerProps } from antd; import { TimePicker } from antd; import dayjs from dayjs; import customParseFormat from dayjs/plugin/customParseFormat; dayjs.extend(customParseFormat); const onChange: TimePickerProps[onChange] (time, timeString) { console.log(time, timeString); }; const App: React.FC () ( TimePicker onChange{onChange} defaultOpenValue{dayjs(00:00:00, HH:mm:ss)} / ); export default App;这段代码浓缩了 TimePicker 基础使用的全部要点下面逐项拆解。二、dayjsTimePicker 的时间值载体2.1 为什么必须引入 dayjs从 components/time-picker/index.zh-CN.md 的 API 表可以看到value、defaultValue等与时间相关的属性类型统一为 dayjs 对象而不是原生Date或字符串。ant-design 5.x 的 TimePicker 在底层完全基于 dayjs 构建因此使用前需要import dayjs from dayjs;2.2 customParseFormat 插件的作用示例代码中特意执行了dayjs.extend(customParseFormat)。这一步并非多余dayjs 默认只能解析 ISO 8601 格式的字符串而 TimePicker 场景中我们经常要按自定义格式如HH:mm:ss解析时间字符串。加载customParseFormat插件后dayjs(00:00:00, HH:mm:ss)才能按模板正确解析出零点零分零秒否则会返回 Invalid Date。这一点在index.zh-CN.md的 API 快速示例中也有同样的写法印证import dayjs from dayjs; import customParseFormat from dayjs/plugin/customParseFormat dayjs.extend(customParseFormat) TimePicker defaultValue{dayjs(13:30:56, HH:mm:ss)} /;三、onChange 回调双参数的取值约定const onChange: TimePickerProps[onChange] (time, timeString) { console.log(time, timeString); };onChange是时间发生变化时的回调签名定义在 API 表中为参数类型说明onChangefunction(time: dayjs, timeString: string): void时间发生变化的回调两个参数分别代表time选中或输入后的时间类型为dayjs.Dayjs对象适合直接存入状态或传给后端做进一步处理timeString按当前format格式化后的字符串例如默认格式HH:mm:ss下的14:30:00适合直接展示或提交表单。建议像示例一样用TimePickerProps[onChange]类型标注回调从而获得完整的参数类型推导。该回调会在用户从浮层面板选择某一项或直接在输入框中键入合法时间失焦/确认后时触发。四、defaultOpenValue面板未选值时的占位时间TimePicker onChange{onChange} defaultOpenValue{dayjs(00:00:00, HH:mm:ss)} /defaultOpenValue决定浮层面板在还没有任何选择时默认高亮/定位的时间。它与defaultValue的区别在于defaultValue会真正写入输入框作为初始值而defaultOpenValue只影响面板打开时的默认定位示例设为00:00:00即打开面板默认从零点开始浏览输入框本身仍可保持为空。这在输入框留空、但希望用户打开面板时从某个时间起点开始选择的场景下非常实用。五、TimePicker 的底层实现它是 DatePicker 的特化从 components/time-picker/index.tsx 的源码可以看到TimePicker 并不是从零实现的独立组件而是对 DatePicker 的封装特化const { TimePicker: InternalTimePicker, RangePicker: InternalRangePicker } DatePicker;其中 RangePicker 通过显式指定pickertime来获得时间选择形态const RangePicker React.forwardRefPickerRef, TimeRangePickerProps((props, ref) ( InternalRangePicker {...props} pickertime mode{undefined} ref{ref} / ));同时TimePicker 主组件在内部做了两件关键事情兼容旧属性addon开发环境下会对仍在使用addon的代码发出deprecated警告建议迁移到renderExtraFooter见 index.tsx形态variant合并通过useVariant(timePicker, variant, bordered)将variant与旧版bordered属性归一支持outlined/borderless/filled三种形态。理解这层封装关系有助于排错TimePicker 的浮层、聚焦、失焦等行为本质来自 rc-picker 与 DatePicker 共享的能力。六、浮层中的两种操作选择与输入基础文档描述的核心交互包含两条路径点击弹出浮层选择点击输入框后弹出时分秒列表面板逐列点选小时、分钟、秒选择即时生效未开启needConfirm时。onChange随即触发。直接在输入框键入聚焦输入框后可直接键盘输入如14:30输入符合format的时间后失焦即完成选择。inputReadOnly可设为true强制只读避免移动端弹出虚拟键盘。浮层位置默认在bottomLeft可通过placement调整为bottomLeft | bottomRight | topLeft | topRight浮层默认挂载在 body 新建的 div 上也可用getPopupContainer自定义挂载容器。七、基础之上的高频进阶实践basic.md只是起点仓库 components/time-picker/demo 下围绕同一交互提供了大量可运行示例以下是与你主题强相关的几个7.1 受控组件value 与 onChange 配合使用value.tsx 演示受控用法其说明文档 value.md 强调value 和 onChange 需要配合使用const [value, setValue] useStateDayjs | null(null); const onChange (time: Dayjs) { setValue(time); }; return TimePicker value{value} onChange{onChange} /;7.2 选择确认needConfirmneed-confirm.tsx5.14.0 新增通过needConfirm开启确认按钮此时点选时间不会立即提交需点击确定才触发onChange设为false时失去焦点即代表选择。changeOnScroll5.14.0 新增则可在滚动滚轮时直接改变选择值与needConfirm{false}组合可获得滚动即生效的流畅体验参见 change-on-scroll.tsx。7.3 步长选项hourStep / minuteStep / secondStepinterval-options.tsx 演示了限制面板选项间隔的写法TimePicker minuteStep{15} secondStep{10} hourStep{1} /默认三者均为1业务中常用minuteStep{15}生成 00/15/30/45 的分钟选项。7.4 只选时分hide-column 与 formathide-column.tsx 通过format控制展示粒度const format HH:mm; TimePicker defaultValue{dayjs(12:08, format)} format{format} /;format默认HH:mm:ss当需要只选择时分时同时调整format与defaultValue的解析模板即可。7.5 12 小时制use12Hours12hours.tsx 演示use12Hours开启 12 小时制自动带上 meridiem 上下午列开启时format默认为h:mm:ss a也可自定义为h:mm:ss A或h:mm a。7.6 时间范围RangePickerTimePicker 命名空间下还挂载了TimePicker.RangePicker见 index.tsx其属性与 DatePicker 的 RangePicker 相同额外支持order始末时间是否自动排序默认true与disabledTime。典型用法TimePicker.RangePicker onChange{(times, timeStrings) console.log(times, timeStrings)} /八、禁选时间的类型定义DisabledTime若需要禁止某些时间段例如午休时间不可预约可使用disabledTime属性其类型定义位于 index.zh-CN.mdtype DisabledTime (now: Dayjs) { disabledHours?: () number[]; disabledMinutes?: (selectedHour: number) number[]; disabledSeconds?: (selectedHour: number, selectedMinute: number) number[]; disabledMilliseconds?: ( selectedHour: number, selectedMinute: number, selectedSecond: number, ) number[]; };其中disabledMilliseconds为 5.14.0 新增。RangePicker 对应使用RangeDisabledTime其回调额外携带type: start | end参数以区分起始与结束时间的禁选规则。九、基础 API 速查表结合 components/time-picker/index.zh-CN.md 的官方 API 表与基础用法最相关的核心参数整理如下参数说明类型默认值allowClear自定义清除按钮boolean \| { clearIcon?: ReactNode }true5.8.0 起支持对象autoFocus自动获取焦点booleanfalsedefaultValue默认时间dayjs-disabled禁用全部操作booleanfalsedisabledTime不可选择的时间DisabledTime-format展示的时间格式stringHH:mm:sshourStep / minuteStep / secondStep时分秒选项间隔number1inputReadOnly输入框只读避免移动端弹虚拟键盘booleanfalseneedConfirm是否需要确认按钮boolean-5.14.0open面板是否打开booleanfalseplaceholder无值时的占位文案string \| [string, string]请选择时间placement浮层弹出位置bottomLeft \| bottomRight \| topLeft \| topRightbottomLeftrenderExtraFooter浮层底部自定义内容() ReactNode-showNow是否显示此刻按钮boolean-4.4.0size输入框尺寸large 40px / middle 32px / small 24pxlarge \| middle \| small-status校验状态error \| warning-4.19.0suffixIcon自定义后缀图标ReactNode-use12Hours使用 12 小时制format默认h:mm:ss abooleanfalsevalue当前时间受控dayjs-variant形态变体outlined \| borderless \| filledoutlined5.13.0onChange时间变化回调function(time: dayjs, timeString: string): void-onOpenChange面板开关回调(open: boolean) void-组件实例还暴露focus()与blur()两个方法可用于手动控制焦点。十、测试与更多资料基础示例通过 components/time-picker/tests/demo.test.tsx 等测试文件持续回归验证保证示例代码可运行完整的 API 定义、主题变量与 FAQ 见 components/time-picker/index.zh-CN.md 与 components/time-picker/index.en-US.md若需在 TimePicker 中使用自定义日期库如 Moment.js可参考 docs/react/use-custom-date-library 中关于 TimePicker 的说明。小结从 components/time-picker/demo/basic.tsx 这一最小示例出发你已掌握 TimePicker 的完整使用链路dayjs 与 customParseFormat 的初始化 →onChange双参数取值 →defaultOpenValue的面板定位 → 选择/输入两种交互 → 受控、步长、12 小时制、确认选择、RangePicker 等进阶能力以及其底层DatePicker 特化封装的实现本质。以此为基础即可在真实业务中构建从简单选时到复杂时段禁选的各种时间录入场景。【免费下载链接】ant-designAn enterprise-class UI design language and React UI library项目地址: https://gitcode.com/gh_mirrors/ant/ant-design创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考