前端UI组件【免费下载链接】react-toolboxA set of React components implementing Googles Material Design specification with the power of CSS Modules项目地址https://gitcode.com/gh_mirrors/re/react-toolbox点击查看免费下载导读TimePicker 是 react-toolbox 组件库中遵循 Google Material Design 规范实现的时间选择hours:minutes对话框组件用于在表单场景中让用户以时钟拨盘方式选取一天中的某个时刻当前选中的时间通过表针末端的实心圆点knob标出。本文以 components/time_picker/readme.md 为主体完整讲解其属性Props与主题Theme契约并结合 TimePicker.js、TimePickerDialog.js、Clock.js 及配套样式源码深入拆解输入框 对话框 表盘拨号的分层实现与交互原理。读完本文你将掌握 TimePicker 的受控用法、24 小时制与 AM/PM 制切换、外部受控打开对话框、readonly 只读模式以及如何通过 Theme 主题对象深度定制表盘样式。组件定位与 Material Design 依据TimePicker 是一个dialog picker对话框选择器其交互形态参考了 Material Design 规范中的 time pickers 一节用户点击/聚焦文本输入框后弹出对话框在圆形表盘上拖动指针或点击刻度数字来完成小时 分钟的选择被选中的时间由表针末端填充的实心圆点明确指示The selected time is indicated by the filled circle at the end of the clock hand。在 react-toolbox 中TimePicker 与 DatePicker 同属选择器家族可共同构成完整的日期时间录入方案。官方演示spec/components/pickers.js同时展示了 DatePicker 与 TimePicker 的组合使用。组件架构分层从源码结构看TimePicker 并非单个组件而是一组分层协作的模块文件职责TimePicker.js顶层入口组件渲染只读文本输入框管理对话框开合状态TimePickerDialog.js对话框容器渲染头部小时/分钟显示 AM/PM 切换与时钟管理先选小时再选分钟的两步流程Clock.js时钟容器测量表盘尺寸、计算圆心与半径用 CSS 过渡在小时面/分钟面之间切换ClockFace.js圆形刻度盘按三角函数把数字摆放到圆周位置ClockHours.js / ClockMinutes.js小时盘与分钟盘的具体数字布局、24hr 内外圈逻辑ClockHand.js可拖拽表针把鼠标/触摸位置换算成角度并取整到刻度theme.module.css默认主题样式含表盘、表针、头部、对话框入口文件 index.js 通过themr(TIME_PICKER, theme)将默认主题注入组件而标识符常量TIME_PICKER RTTimePicker定义在 components/identifiers.js这正是文档中所说通过 context 提供主题时组件 key 为RTTimePicker的实现来源。快速上手受控组件基础用法TimePicker 是受控组件value接收一个Date对象onChange回调把用户选中的新时间回传给调用方。官方文档给出的最小示例见 components/time_picker/readme.md如下import TimePicker from react-toolbox/lib/time_picker; let time new Date(); time.setHours(17); time.setMinutes(28); class TimePickerTest extends React.Component { state {time}; handleChange (time) { this.setState({time}); }; render () { return ( TimePicker labelFinishing time onChange{this.handleChange} value{this.state.time} / ); } }要点说明初值通过new Date()后调用setHours/setMinutes构造示例演示了下午 5 点 28 分17:28的初始化方式value始终是完整的Date实例见 TimePicker.js 中value: PropTypes.instanceOf(Date)组件内部通过time.formatTime(value, format)见 components/utils/time.js把它格式化为只读输入框显示的文本onChange收到的是新的 Date 对象与事件对象见 TimePicker.js 中onChange(value, event)的调用签名。对外部提供的value的响应从 TimePickerDialog.js 的componentWillReceiveProps可以确认当外部传入的value时间戳变化时对话框内部的displayTime会同步为新的值保证外部状态变化能正确反映到表盘上。组件属性Props全解下表完整继承自官方文档并补充了源码可确认的类型约束与默认值对应 TimePicker.d.ts 的 TypeScript 声明名称类型默认值说明activeBooleanfalse允许从外部控制选择器是否弹出。注意当对话框被关闭时你需要自行更新该属性。classNameString空该 class 会被放置到TimePickerDialog组件顶层用于提供自定义样式。errorString—提供错误文本显示在输入字段下方。inputClassNameString—应用到 TimePicker 内部Input组件上的 class。formatString24hr时钟显示格式可取24hr或ampm。labelString—输入组件中浮动标签元素使用的文本字符串。onChangeFunction—选择器值发生变化时调用的回调。readonlyBoolean—输入元素将变为只读并呈现禁用外观。valueDate—当前选中时间的 Datetime 对象。文档之外的完整 Props 清单查阅 TimePicker.js 的 propTypes 可以发现文档表格之外组件还支持以下属性均透传给内部 Dialog 或 Input名称类型说明cancelLabelString取消按钮文案默认Cancel见 TimePickerDialog.jsokLabelString确认按钮文案默认OknameString输入框的 name 属性同时被用于确认按钮onClickFunction输入框点击回调onDismissFunction对话框关闭后触发的回调onEscKeyDownFunction对话框激活时按下 ESC 键的回调onKeyPressFunction输入框按键回调onOverlayClickFunction点击对话框遮罩层时的回调其中cancelLabel、okLabel、onEscKeyDown、onOverlayClick等会在 TimePicker.js 的render中透传给TimePickerDialog。交互行为细节源码佐证点击/聚焦输入框弹出handleInputFocus、handleInputClick都会events.pauseEvent(event)并置active: true按回车键event.charCode 13同样会打开对话框TimePicker.js。外部受控打开active属性通过componentWillReceiveProps同步到内部 stateTimePicker.js因此父组件可以通过把active置为true主动弹出对话框——这也是文档中Beware you should update the prop when the Dialog is closed对话框关闭后需要你自行把active复位对应的约束。取消与确认取消走onDismiss内部handleDismiss会把active置回false并触发onDismiss回调确认走handleSelect把当前displayTime通过onSelect提交给上层handleSelect再由外层调用onChange并关闭对话框TimePicker.js。格式化的差异format24hr时输入框显示17:28形式的两位补零文本formatampm时则显示5:28 pm分钟为00时省略分钟部分具体逻辑见 components/utils/time.js 的formatTime实现。两种时间格式24hr 与 ampmformat属性控制三个层面的行为输入框显示文本、表盘数字布局与头部 AM/PM 切换。24hr 格式外圈 内圈双层表盘ClockHours.js 定义了小时盘的数字常量const outerNumbers [0, ...range(13, 24)]; // 外圈0、13~24 const innerNumbers [12, ...range(1, 12)]; // 内圈12、1~1124hr 模式下表盘同时渲染**外圈13–24 与 0和内圈1–12**两个刻度环用户把指针拖到靠近圆心radius radius - spacing * innerSpacing的内侧区域时组件通过setState({ inner: currentInner })在内圈/外圈之间切换并根据valueFromDegrees换算为对应的小时数ClockHours.js24hr 模式下所有数字补零显示为两位twoDigits见 ClockFace.js 的(0 number).slice(-2)。ampm 格式单圈 12 小时 AM/PM 切换ampm 模式下小时盘只渲染内圈 12 个数字且当前选中值会按selected % 12 || 12换算到 12 小时制ClockHours.js对话框头部右上角出现AM/PM两个标签TimePickerDialog.js点击任一标签调用toggleTimeMode——底层通过 components/utils/time.js 的toggleTimeMode把小时数在 12 小时范围内翻转头部小时显示同样适配 ampmformatHours()中getHours() % 12 || 12保证 12 点显示为12而非0TimePickerDialog.js。底层时间工具 components/utils/time.js 还提供了getTimeMode(d)hours 12 ? pm : am来判断当前时间所属时段该函数被TimePickerDialog用于给对话框追加amFormat/pmFormat主题类见下文 Theme 说明。两步选择流程先小时、后分钟TimePickerDialog 内部维护display状态初始为hours构成先选小时、再选分钟的两步流程对话框打开时默认显示小时盘用户拖拽表针选中小时并松手handleHandMoved后display自动切换为minutesTimePickerDialog.js分钟选择完成后点击头部时间显示或对话框右下角的 OK 按钮确认。与此同时对话框头部会高亮当前正在选择的单位选小时时.hoursDisplay类作用于对话框选分钟时.minutesDisplay类生效见 TimePickerDialog.js 的类名拼接。头部的小时与分钟文本本身也是可点击的点击即可在两种显示之间手动切换switchDisplay见 TimePickerDialog.js。时钟盘之间的切换由 Clock.js 配合react-transition-group完成以display作为TransitionGroup的 key根据切换方向选用zoomOut/zoomIn动画类过渡时长 500ms动画类定义见 theme.module.css。表盘与指针的几何计算原理TimePicker 的时钟盘完全由几何计算驱动不依赖任何图片资源这是其源码实现最值得学习的地方圆心与半径测量Clock 挂载后在componentDidMount中监听window.resize并调用handleCalculateShape通过placeholderNode.getBoundingClientRect()计算时钟占位元素的中心点(x, y)与半径radius width / 2Clock.js数字定位ClockFace.numberStyle使用三角函数sin/cos(angle)把 12/24 个数字均匀摆放在圆周上ClockFace.js其中angle 360°/12 * (num - 1)配合spacingradius * 0.18留出内外圈间距表针角度Hand组件把鼠标/触摸点相对圆心的位置换算成角度再按step小时盘 30°、分钟盘 6°取整对齐刻度trimAngleToValue保证指针总是精确指向有效刻度ClockHand.js表针长度与拖拽表针长度由radius - spacing以及小时盘内外圈切换后的内圈半径决定通过prefixer生成带厂商前缀的transform: rotate(angle)样式拖拽通过把mousemove/mouseup、touchmove/touchend事件挂到document上实现ClockHand.js分钟刻度细化分钟盘以 5 分钟为间隔渲染0, 5, ..., 55的两位数数字但当选中的分钟数不是 5 的倍数时例如 28 分表针末端会套用theme.small样式——这正是文档 Theme 表中small: Added to the knob when no round number is selected的含义ClockMinutes.js。通过 Theme 主题定制组件样式两种注入方式文档明确指出If you want to provide a theme via context, the component key isRTTimePicker. 对应实现组件通过themr(TIME_PICKER, theme)包裹index.jsTIME_PICKER常量值为RTTimePickercomponents/identifiers.js。因此你可以全局注入通过ThemeProvider提供包含RTTimePicker键的主题对象与 react-css-themr 的 context 机制配合局部注入直接给TimePicker theme{myTheme} /传theme属性其中包含下述各主题类名到实际 CSS class 的映射。主题类全表下表完整继承自官方文档 Theme 表格名称说明active添加到表盘上处于激活状态的数字上amAM/PM 模式下对话框头部中的 AM 标签amFormat当前选中格式为 AM 时添加到对话框ampmAM/PM 模式下头部 AM 与 PM 标签的包裹容器button对话框内按钮使用的样式clock时钟根元素类clockWrapper用于时钟正确定位的包裹元素container选择器的包裹元素dialog对话框组件使用的样式face用于样式化表盘面hand时钟表针样式header对话框头部包裹类hours对话框头部的小时显示hoursDisplay当前正在选择小时时添加到对话框input用于打开选择器的 Input 元素knob表针末端的实心圆点minutes对话框头部的分钟显示minutesDisplay当前正在选择分钟时添加到对话框number表盘上的每个数字placeholder对话框内时钟的占位容器内层包裹pmAM/PM 模式下头部中的 PM 标签pmFormat当前选中格式为 PM 时添加到对话框separator头部小时与分钟之间的:分隔符small未选中整 5 分钟刻度时添加到表针圆点上默认主题实现参考这些主题键在 theme.module.css 中均有默认实现可作定制起点.header使用--timepicker-primary-color背景与对比色文字头部整体居中.hours/.minutes默认透明度 0.6通过.dialog.hoursDisplay .hours等组合选择器在当前选中单位时恢复完全不透明theme.module.css.clockWrapper为圆形背景border-radius: 50%.face同样圆形并绝对居中定位.number使用user-select: none与pointer-events: none避免拖拽表针时误选数字theme.module.css.hand与.knob以--clock-primary-color上色.hand::before绘制表针根部的圆点.small状态下圆点切换为内嵌小圆点的样式theme.module.css。尺寸与配色变量集中在 components/time_picker/config.module.css 中包括--timepicker-dialog-width对话框宽度默认 30 个--unit、--clock-number-size数字尺寸、--clock-knob-size圆点尺寸等全部基于 react-toolbox 的全局--unit与--color-primary派生可通过修改 CSS 变量实现主题化。只读模式与错误提示readonly置为true时输入框呈现禁用外观且不可编辑但组件仍可正常弹出对话框查看/选择disabled{readonly}只是禁用了输入框的文本编辑见 TimePicker.js。官方演示 spec/components/pickers.js 中Finishing time (Read Only)即为典型用法。error传入错误文本后显示在输入框下方用于表单校验反馈。官方示例场景一览在 spec/components/pickers.js 中可以看到 TimePicker 与 DatePicker 组合的完整演示formatampmlabelStart timeAM/PM 格式的基础用法同时演示onEscKeyDown与onOverlayClick回调formatampmreadonly只读模式的 AM/PM 用法。总结react-toolbox 的 TimePicker 是一个完全源码驱动、无需任何图片素材的 Material Design 时间选择器外层是带浮动标签的只读输入框中层是支持外部受控的 Dialog 容器内层是由几何计算驱动、支持鼠标/触摸拖拽的圆形表盘。掌握其 Props 契约特别是active的外部受控语义与format双格式、RTTimePicker主题注入方式以及表盘拖拽与两步选择的状态流就足以在 react-toolbox 项目中高效落地时间录入场景并定制出符合业务视觉风格的时钟选择器。赞分享前端UI组件【免费下载链接】react-toolboxA set of React components implementing Googles Material Design specification with the power of CSS Modules项目地址https://gitcode.com/gh_mirrors/re/react-toolbox点击查看免费下载相关推荐Ant Design TimePicker 组件完全指南时间选择与时间范围选择的配置实战Ant Design TimePicker 组件完全指南时间选择与时间范围选择的配置实战 本文以 Ant Design 仓库中 TimePicker 官方文档前端UI组件设计系统ssd_keras数据增强全攻略5种数据增强链实战教程ssd_keras数据增强全攻略5种数据增强链实战教程 ssd_keras是一个基于Keras实现的Single Shot MultiBox Detector前端UI组件移动开发material-components-android 时间选择器MaterialTimePicker开发实战从拨盘到键盘输入的完整指南material components android 时间选择器MaterialTimePicker开发实战从拨盘到键盘输入的完整指南 Time picUI组件移动开发设计系统上一篇Electric Streams Durable Proxy让 AI 流式 API 具备可恢复、可重连能力下一篇SwiftUI弹簧动画最佳实践10个提升用户体验的弹簧动画技巧创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考