[comp: TimePicker] add TimePicker component

[jackson-yyy]

• I have searched the issues of this repository and believe that this is not a duplicate.

What problem does this feature solve?

TimePicker

What does the proposed API look like?

timePicker props

名称	说明	类型	默认值	全局配置	备注
v-model:value	当前选择的时间	Date	-	-	-
control	控件控制器	string|AbstractControl	-	-	当存在 control 时, 控件将由 AbstractControl 完全控制，此时 value 会失效
format	展示的格式	string	HH:mm:ss	-	1. format的格式参考dayjs 2.如果传入的值有小写的h，如hh:mm:ss、hh:mm，会自动在后面加上a，变成hh:mm:ss a和hh:mm a，代表开启12小时进制 3. 会根据format的内容进行选项的展示，如HH:mm则不展示秒的选项
placeholder	值为空时展示的提示	string	请选择时间	-	-
disabled	禁用全部操作	boolean	false	-	-
readonly	只读状态	boolean	false	-	-
clearable	是否展示清除按钮	boolean	true	✅	-
autofocus	自动获取焦点	boolean	false	-	-
borderless	是否为无边框	boolean	false	✅	-
suffix	后缀图标	string	clock-circle	✅	-
clearIcon	清除按钮图标	string	close-circle	✅	-
clearText	hover到clearIcon上，显示的title	string	clear	✅	-
size	尺寸大小	large|medium|small	medium	✅	-
v-model:open	是否打开picker	boolean	false	-	-
disabledHours	禁用部分小时选项	()=>number[]	() => []	-	-
disabledMinutes	禁用部分分钟选项	(selectedHour: number)=>number[]	() => []	-	-
disabledSeconds	禁用部分秒选项	(selectedHour: number, selectedMinute: number)=>number[]	() => []	-	-
hideDisabledOptions	隐藏禁止选择的options	boolean	false	-	-
hourStep	小时选项的间隔	number	1	-	-
minuteStep	分钟选项的间隔	number	1	-	-
secondStep	秒选项的间隔	number	1	-	-
defalutPickerValue	打开面板时默认高亮的值	Date	-	-	如果value不为空，则高亮value的值
overlayClassName	浮层的类名	string	-	-	-

timePicker slots

名称	说明	备注
suffix	后缀图标	-
clearIcon	清空图标	-
pickerFooter	自定义选择面板底部内容	-

timePicker events

名称	说明	参数类型	备注
change	选择的值发生改变	(time: Date) => void	-
clear	点击清空图标后	(evt: MouseEvent) => void	-
focus	focus时触发	() => void	-
blur	blur时触发	() => void	-

timeRangePicker props

timeRangePicker拥有timePicker的所有props、events、slots，只有下面的内容有所区别

名称	说明	类型	默认值	全局配置	备注
v-model:value	当前选择的时间范围	[Date, Date]	-	-	-
defaultPickerValue	打开面板时默认高亮的值	[Date, Date]	-	-	如果value不为空，则高亮value的值
separator	分割符号	string	至	✅	-
placeholder	选择器没有值的时候展示的提示	[string, string]	[开始时间，结束时间]	-	-
disabled	设置选择器为禁用，可选择设置开始方或者结束方	boolean | [boolean, boolean]	false	-	-
readonly	设置选择器为只读状态，可选择设置开始方或者结束方	boolean | [boolean, boolean]	false	-	-

组件架构设计：

[danranVm]

re #153

[LaamGinghong]

这个是只有timePicker还是包含 timeRangePicker

[jackson-yyy]

这个是只有timePicker还是包含 timeRangePicker

Antd react是单独暴露了一个rangePicker的组件
Antd vue没有提供range的组件或者配置
Element是提供了配置isRange

我们可以讨论下业务场景的需要，看range需要怎么做，个人可能更倾向于单独暴露一个range的组件，代码耦合性会比较低，使用上可能会比较舒服

[LaamGinghong]

我更建议拆开，公用的类型采用继承的方式

[jackson-yyy]

我更建议拆开，公用的类型采用继承的方式

嗯嗯跟我的想法一致，具体实现的话，可以抽离公用的计算逻辑
那我就按照这样去设计吧

[LaamGinghong]

我更建议拆开，公用的类型采用继承的方式

嗯嗯跟我的想法一致，具体实现的话，可以抽离公用的计算逻辑
那我就按照这样去设计吧

某些公用的方法可以通过实现一个自定义hook来实现

[jackson-yyy]

@danranVm @LaamGinghong
做了一版api的设计，有空review一下，看有没有啥问题
format那个字段的功能设计看是否合理，antd是用use12Hours+format去判断是否是12小时进制以及控制选项列的展示，我这里将功能融合到了一起

[danranVm]

@jackson-yyy 好的，我晚上看一下。对了，我们日期处理库用 day.js

[jackson-yyy]

@jackson-yyy 好的，我晚上看一下。对了，我们日期处理库用 day.js

嗯嗯 我也设计的用dayjs

[danranVm]

• 新增一个 props: open, 表示 overlay 的打开状态，支持 v-model
• 新增两个 method: focus, blur
• toggle-picker => openChange, emits 也全部用小驼峰命名
• pickerBottom => pickerFooter, 或者其他更好点的名字？
• prefix 是否有必要？
• valueFormat 是 props ? 用来做什么的，没明白你的意图。

[danranVm]

@danranVm @LaamGinghong
做了一版api的设计，有空review一下，看有没有啥问题
format那个字段的功能设计看是否合理，antd是用use12Hours+format去判断是否是12小时进制以及控制选项列的展示，我这里将功能融合到了一起

format 的我觉得没问题，我们尽可能的跟 day.js 的 API 保持一致。

[jackson-yyy]

• 新增一个 props: open, 表示 overlay 的打开状态，支持 v-model
• 新增两个 method: focus, blur
• toggle-picker => openChange, emits 也全部用小驼峰命名
• pickerBottom => pickerFooter, 或者其他更好点的名字？
• prefix 是否有必要？
• valueFormat 是 props ? 用来做什么的，没明白你的意图。

1. open的这个prop，我考虑过是否需要，因为有事件抛出了，业务里应该是可以自己实现的
2. prefix的话，可能有些业务喜欢在前面加icon？
3. pickerBottom => pickerFooter我觉得可
4. valueFormat是表明value的格式，比如你value传了20:00:01，valueFormat传HH:mm:ss，我就会按照HH:mm:ss的格式input出去，value传了20:02，valueFormat传HH:mm，我就会按照HH:mm的格式input出去，同理，value给了一个13位的时间戳，valueFormat就传给我timestamp，我就会处理成时间戳再input出去，主要就是保证value输入输出的格式一致，只能确定一种格式的value可能不是特别灵活，业务里可能还得做一次转换处理（这个valueFormat我看很多组件库都会搞，antd、element等等）

[danranVm]

@jackson-yyy

• 如果用户想手动控制 picker 的显示和隐藏怎么办？ 事件回调做不到吧。
• prefix 有实际应用场景吗？ 我看其他库都没有这个 API 吧，
• ok
• 4, 明白了。我在想这个通常来说是不是就是和 format 是一个值？

[jackson-yyy]

@jackson-yyy

• 如果用户想手动控制 picker 的显示和隐藏怎么办？ 事件回调做不到吧。
• prefix 有实际应用场景吗？ 我看其他库都没有这个 API 吧，
• ok
• 4, 明白了。我在想这个通常来说是不是就是和 format 是一个值？

@danranVm

1. 明白你说的场景了，open的确有必要，那openChange还需要不，我感觉可以业务里自己监听open的值了。。
2. 就是在想有没有项目是喜欢用前缀图标的，多一个prefix有备无患？（实在不要也ok
3. format和valueFormat不一样，format是展示出来的格式，valueFormat是数据的格式，我可以value是13位时间戳，但是展示出来是20:00:01，这样format就是HH:mm:ss，而valueFormat是timestamp

[danranVm]

@jackson-yyy

• 如果用户想手动控制 picker 的显示和隐藏怎么办？ 事件回调做不到吧。
• prefix 有实际应用场景吗？ 我看其他库都没有这个 API 吧，
• ok
• 4, 明白了。我在想这个通常来说是不是就是和 format 是一个值？

@danranVm

1. 明白你说的场景了，open的确有必要，那openChange还需要不，我感觉可以业务里自己监听open的值了。。
2. 就是在想有没有项目是喜欢用前缀图标的，多一个prefix有备无患？（实在不要也ok
3. format和valueFormat不一样，format是展示出来的格式，valueFormat是数据的格式，我可以value是13位时间戳，但是展示出来是20:00:01，这样format就是HH:mm:ss，而valueFormat是timestamp

• openChange 要吧，跟其他组件保持一致（其实我不是很喜欢这个 API）。
• 暂时不加 prefix 吧，保持克制。
• 🆗

[jackson-yyy]

@jackson-yyy

• 如果用户想手动控制 picker 的显示和隐藏怎么办？ 事件回调做不到吧。
• prefix 有实际应用场景吗？ 我看其他库都没有这个 API 吧，
• ok
• 4, 明白了。我在想这个通常来说是不是就是和 format 是一个值？

@danranVm

1. 明白你说的场景了，open的确有必要，那openChange还需要不，我感觉可以业务里自己监听open的值了。。
2. 就是在想有没有项目是喜欢用前缀图标的，多一个prefix有备无患？（实在不要也ok
3. format和valueFormat不一样，format是展示出来的格式，valueFormat是数据的格式，我可以value是13位时间戳，但是展示出来是20:00:01，这样format就是HH:mm:ss，而valueFormat是timestamp

• openChange 要吧，跟其他组件保持一致（其实我不是很喜欢这个 API）。
• 暂时不加 prefix 吧，保持克制。
• ok

行 我晚点更新一下
到时候把timeRangePicker的api一起给出来

[jackson-yyy]

@danranVm @LaamGinghong

timePicker的api已经修改完成
timeRange的api也设计了一版
有空review一下🤓

[LaamGinghong]

大哥，你咋不用表格啊

[LaamGinghong]

数据格式统一采用 date 格式，减少用户心智负担

[LaamGinghong]

有点越权了，组件不应该控制value的格式
如果上面用了Date格式，那这里就不需要控制了

[LaamGinghong]

这个control的作用是？

[LaamGinghong]

这里我个人不建议再次封装，直接用dayjs的format，避免增加心智负担

[LaamGinghong]

既然我们的场景更多是允许清楚，那么这里的prop应该修改为 disableClear，尽可能让我们的调用方不需要写 prop = false这种代码

[jackson-yyy]

我更喜欢change而不是input，因为input代表的是一个行为，而change表示数据变化的监听

这个ok

[jackson-yyy]

这个不要，你在写的时候用 Portal 包裹，组件传递到哪个真实节点没必要交给调用方控制

这个我看挺多组件库都有类似的？

[danranVm]

既然我们的场景更多是允许清楚，那么这里的prop应该修改为 disableClear，尽可能让我们的调用方不需要写 prop = false这种代码

这个props 还是叫 clearable 吧，与其他组件保持一致，
至于是否可以考虑默认为 false？

PS： 以后还是不要用 xmind 了，看着太累。。。:cry:

[LaamGinghong]

漏了前缀

这个前缀是？

props里面有prefix，但是slot没有

[LaamGinghong]

这个不要，你在写的时候用 Portal 包裹，组件传递到哪个真实节点没必要交给调用方控制

这个我看挺多组件库都有类似的？

我个人觉得没有必要，使用的场景感觉比较少

[jackson-yyy]

漏了前缀

这个前缀是？

props里面有prefix，但是slot没有

这个删掉了，没有前缀的icon了，props那边删漏了

[jackson-yyy]

既然我们的场景更多是允许清楚，那么这里的prop应该修改为 disableClear，尽可能让我们的调用方不需要写 prop = false这种代码

这个props 还是叫 clearable 吧，与其他组件保持一致，
至于是否可以考虑默认为 false？

PS： 以后还是不要用 xmind 了，看着太累。。。

其实timePicker默认可以清除会比较舒服一点，感觉用到的大多数都有这个需求，每次使用还得加上clearable，不太友好

[jackson-yyy]

这个不要，你在写的时候用 Portal 包裹，组件传递到哪个真实节点没必要交给调用方控制

这个我看挺多组件库都有类似的？

我个人觉得没有必要，使用的场景感觉比较少

@danranVm 看下这个有没有必要，感觉各大组件库都支持了，应该还是有使用场景的，或者暂时先不支持也可以

[danranVm]

这个不要，你在写的时候用 Portal 包裹，组件传递到哪个真实节点没必要交给调用方控制

这个我看挺多组件库都有类似的？

我个人觉得没有必要，使用的场景感觉比较少

@danranVm 看下这个有没有必要，感觉各大组件库都支持了，应该还是有使用场景的，或者暂时先不支持也可以

暂时不支持吧，如果有需求，到时候有好几个组件可以统一支持，

[danranVm]

既然我们的场景更多是允许清楚，那么这里的prop应该修改为 disableClear，尽可能让我们的调用方不需要写 prop = false这种代码

这个props 还是叫 clearable 吧，与其他组件保持一致，
至于是否可以考虑默认为 false？
PS： 以后还是不要用 xmind 了，看着太累。。。

其实timePicker默认可以清除会比较舒服一点，感觉用到的大多数都有这个需求，每次使用还得加上clearable，不太友好

支持全局配置，默认 false 或者 true 都行吧。名字还是叫 clearable

[danranVm]

@jackson-yyy valueFormat 想了想，还是不支持吧，你这样会修改用户的原始值？

[jackson-yyy]

@jackson-yyy valueFormat 想了想，还是不支持吧，你这样会修改用户的原始值？

格式不一致会报warn
使用者肯定得确定一个格式的数据吧，如果他value给的Date格式，valueFomat又给了其他格式，那这个没有办法的，只能按照valueFormat的格式抛出，这些肯定都是建立在使用者有这个认知在的

如果使用者不想用valueFormat，那就默认给Date格式数据就行了，这个没啥问题吧……

正常的场景，这种形式肯定是能覆盖的，只是提供了更多的选择而已，不然这个组件跟其他组件库相比，就逊色了

业务中对于时间格式的要求应该是统一的，这个valueFormat可以做成globalConfig，业务里其实都不必关心这个字段了

如果只支持Date格式的数据，业务里还得想办法做处理，用起来会比较难受吧

[danranVm]

@jackson-yyy

valueFormat 讨论后暂不支持，后续有需求再考虑添加

另外 rangePicker 的 API 没什么问题，注意下一些静态文案的 i18n

[jackson-yyy]

@jackson-yyy

valueFormat 讨论后暂不支持，后续有需求再考虑添加

另外 rangePicker 的 API 没什么问题，注意下一些静态文案的 i18n

好的👌🏻

[LaamGinghong]

整体再用表格列一下，思维导图不方便看

[jackson-yyy]

整体再用表格列一下，思维导图不方便看

嗯好

[LaamGinghong]

另外我还是不建议value使用除Date以外的格式，比如你用了dayjs，但是调用方可能用的是moment，这就造成了一定的冲突

[jackson-yyy]

另外我还是不建议value使用除Date以外的格式，比如你用了dayjs，但是调用方可能用的是moment，这就造成了一定的冲突

暂时不支持valueFormat，那么value也会固定为Date格式，这个不用担心

就算支持了valueFormat，也不会有这个问题，他可以传入时间戳，字符串等格式，dayjs只用做组件内部流通

[LaamGinghong]

那我没什么问题了，两个组件整理成多个表格，期待你的实现

[jackson-yyy]

@danranVm @LaamGinghong
api已更新，有空可以再过一遍
同时还有一个疑问，既然我们 open 这个prop要做成双向绑定的，也就是说组件肯定会暴露update:open这个事件，那openChange事件是不是有点多余？

[danranVm]

@danranVm @LaamGinghong
api已更新，有空可以再过一遍
同时还有一个疑问，既然我们 open 这个prop要做成双向绑定的，也就是说组件肯定会暴露update:open这个事件，那openChange事件是不是有点多余？

针对支持 v-model 的 props 的一个 API 设计原则：

• 所有表单组件，需要支持 v-model:value 或者 v-model:checked， 同时提供 change 的 emit
• 其他的 v-model:xxx 不需要额外提供 xxxChange 事件。

[LaamGinghong]

我看到你的props里面存在两个互斥的prop，不知道vue3的函数组件是否支持重载，可以尝试一下

[jackson-yyy]

我看到你的props里面存在两个互斥的prop，不知道vue3的函数组件是否支持重载，可以尝试一下

是指哪两个？

[LaamGinghong]

control 和 v-model:update

[jackson-yyy]

control 和 v-model:update

这个所有表单项都有的，存在control就走control那套，没有就走vmodel这套，这个会有什么问题吗？

[LaamGinghong]

我的意思是用重载，这样类型校验的时候会避免这两个props同时存在，避免调用方传了value又传control

[jackson-yyy]

我的意思是用重载，这样类型校验的时候会避免这两个props同时存在，避免调用方传了value又传control

奥明白你意思了，我到时候注意下

[danranVm]

我的意思是用重载，这样类型校验的时候会避免这两个props同时存在，避免调用方传了value又传control

奥明白你意思了，我到时候注意下

应该不行，参考下 input 组件，使用 useValueAccessor 就可以管理 value 和 control

[jackson-yyy]

我的意思是用重载，这样类型校验的时候会避免这两个props同时存在，避免调用方传了value又传control

奥明白你意思了，我到时候注意下

应该不行，参考下 input 组件，使用 useValueAccessor 就可以管理 value 和 control

好，我直接参考input组件写吧