# TimePicker

时间选择器，支持时分和时分秒两种模式，可通过高阶函数自定义图标。

## 适用场景

- 表单中选择具体时间点（时:分 或 时:分:秒）
- 需要自定义触发图标的时间选择场景
- 需要不同尺寸的时间输入控件

## Props

### TimePicker Props

| 名称 | 类型 | 默认值 | 必填 | 说明 |
|------|------|--------|------|------|
| className | `string` | `-` | 否 | 自定义 class |
| value | `TimeValue` | `-` | 否 | 当前时间，使用 `TimePicker.TimeValue` 创建 |
| defaultValue | `TimeValue` | `-` | 否 | 默认时间，使用 `TimePicker.TimeValue` 创建 |
| popupClassName | `string` | `-` | 否 | 时间选择器面板的额外 className |
| size | `"xs" \| "sm" \| "md" \| "lg" \| "xl"` | `-` | 否 | 尺寸 |
| showSecond | `boolean` | `-` | 否 | 是否显示秒 |
| onChange | `(value: TimeValue) => void` | `-` | 否 | 值变化时的回调 |
| clearable | `boolean` | `-` | 否 | 是否可清除（有值时是否显示清除按钮） |
| onFocus | `(e: FocusEvent<Element, Element>) => void` | `-` | 否 | 聚焦回调 |
| onBlur | `(e: FocusEvent<Element, Element>) => void` | `-` | 否 | 失焦回调 |
| iconSvg | `FC<{}>` | `-` | 否 | 自定义图标 SVG 组件 |
| iconNode | `ReactNode` | `-` | 否 | 自定义图标节点 |
| disabled | `boolean` | `-` | 否 | 是否禁用 |
| status | `"normal" \| "error"` | `-` | 否 | 状态 |
| placeholder | `string` | `"请选择时间"` | 否 | 占位提示文字 |

### UiTimePanel Props

> 时间选择面板的 UI 子组件，可单独使用。

| 名称 | 类型 | 默认值 | 必填 | 说明 |
|------|------|--------|------|------|
| className | `string` | `-` | 否 | 自定义 class |
| hour | `number` | `-` | 否 | 小时值 |
| minute | `number` | `-` | 否 | 分钟值 |
| second | `number` | `-` | 否 | 秒值 |
| onChange | `(propName: "hour" \| "minute" \| "second", value: number) => void` | `-` | 是 | 值变化回调 |
| onClick | `MouseEventHandler<Element>` | `-` | 否 | 点击回调 |
| onMouseEnter | `MouseEventHandler<Element>` | `-` | 否 | 鼠标进入回调 |
| onMouseLeave | `MouseEventHandler<Element>` | `-` | 否 | 鼠标离开回调 |
| getDisabledRangeList | `() => TypeRange[]` | `-` | 否 | 获取禁用范围列表 |
| getDisabledRange | `() => TypeRange` | `-` | 否 | 获取禁用范围 |
| showSecond | `boolean` | `false` | 否 | 是否显示秒列 |
| refWrapper | `(node: HTMLDivElement) => void` | `-` | 否 | 容器 ref 回调 |

## 典型用法

### 基础用法

```tsx
import { useState } from 'react'
import { TimePicker, TimeValue } from '@befe/brick'

// 非控制，时分模式
<TimePicker
    onChange={value => console.log(value.toText())}
    placeholder="请选择一个时间"
/>

// 非控制，时分秒模式，有初始值
<TimePicker
    defaultValue={new TimePicker.TimeValue(5)}
    showSecond
/>

// 控制型，时分模式
const [value, setValue] = useState<TimeValue>(new TimePicker.TimeValue(1, 0))
<TimePicker value={value} status="error" onChange={setValue} />

// 禁用
<TimePicker disabled placeholder="禁用状态" />
```

### 尺寸

```tsx
<TimePicker size="lg" />
<TimePicker size="md" />
<TimePicker size="sm" />
<TimePicker size="xs" />
<TimePicker size="md" showSecond />
```

### 取消清除按钮

```tsx
<TimePicker
    defaultValue={new TimePicker.TimeValue(2)}
    showSecond
    clearable={false}
/>
```

### 高阶组件替换图标

```tsx
import { createTimePicker } from '@befe/brick'
import { SvgLink, SvgFolder } from '@befe/brick-icon'

// 通过 createTimePicker 创建自定义图标的变体
const CustomTimePicker = createTimePicker({ iconSvg: SvgLink })
const CustomTimePicker2 = createTimePicker({ iconNode: <div>TXT</div> })

<CustomTimePicker onChange={handleChange} />
<CustomTimePicker2 onChange={handleChange} />

// 也可在运行时覆盖图标
<CustomTimePicker onChange={handleChange} iconSvg={SvgFolder} />
```

## 注意事项

- 时间值须使用 `TimePicker.TimeValue` 创建，例如 `new TimePicker.TimeValue(hour, minute, second)`
- `showSecond` 控制是否显示秒列，不设置时为时分两列模式
- `clearable={false}` 可隐藏有值时的清除按钮
- 可通过 `createTimePicker({ iconSvg, iconNode })` 预设图标，创建自定义 TimePicker 变体