20260720172840

This commit is contained in:
oneao committed 2026-07-20 17:28:47 +08:00
1 parent cda7f16d3a
commit 94207c77ff
3117 files changed
+201407 -1236

No files matched your search

@@ -0,0 +1,23 @@
# 12 hours
## Description (en-US)
TimePicker of 12 hours format, with default format `h:mm:ss a`.
## Source
```vue
<script setup lang="ts">
function onChange(time: any, timeString: string) {
console.log(time, timeString)
}
</script>
<template>
<a-space wrap>
<a-time-picker use12-hours @change="onChange" />
<a-time-picker use12-hours format="h:mm:ss A" @change="onChange" />
<a-time-picker use12-hours format="h:mm a" @change="onChange" />
</a-space>
</template>
```
@@ -0,0 +1,71 @@
# _semantic
## Source
```vue
<script setup lang="ts">
import { SmileOutlined } from '@antdv-next/icons'
import { computed, ref } from 'vue'
import { SemanticPreview } from '@/components/semantic'
import { useComponentLocale } from '@/composables/use-locale'
import { locales } from '../locales'
const { t } = useComponentLocale(locales)
const semantics = computed(() => [
{ name: 'root', desc: t('root') },
{ name: 'prefix', desc: t('prefix') },
{ name: 'input', desc: t('input') },
{ name: 'suffix', desc: t('suffix') },
{ name: 'popup.root', desc: t('popup') },
{ name: 'popup.container', desc: t('popup.container') },
{ name: 'popup.content', desc: t('popup.content') },
{ name: 'popup.item', desc: t('popup.item') },
{ name: 'popup.footer', desc: t('popup.footer') },
])
const type = ref<'Single' | 'Multiple'>('Single')
const divRef = ref<HTMLDivElement | null>(null)
</script>
<template>
<SemanticPreview
:component-name="type === 'Single' ? 'TimePicker' : 'TimePicker.RangePicker'"
:semantics="semantics"
>
<template #default="{ classes }">
<a-flex ref="divRef" vertical :style="{ alignSelf: 'flex-start' }" gap="middle" align="center">
<a-segmented
:options="['Single', 'Multiple']"
:value="type"
@change="(val: 'Single' | 'Multiple') => type = val"
/>
<a-time-picker
v-if="type === 'Single'"
:z-index="1"
open
:get-popup-container="() => divRef!"
need-confirm
:classes="classes"
>
<template #prefix>
<SmileOutlined />
</template>
</a-time-picker>
<a-time-range-picker
v-else
:z-index="1"
open
:get-popup-container="() => divRef!"
need-confirm
:classes="classes"
>
<template #prefix>
<SmileOutlined />
</template>
</a-time-range-picker>
</a-flex>
</template>
</SemanticPreview>
</template>
```
@@ -0,0 +1,36 @@
# Addon
## Description (en-US)
Render addon contents to time picker panel's bottom.
## Source
```vue
<script setup lang="ts">
import { ref } from 'vue'
const open = ref(false)
function handleOpenChange(val: boolean) {
open.value = val
}
function handleClose() {
open.value = false
}
</script>
<template>
<a-time-picker
:open="open"
@open-change="handleOpenChange"
>
<template #renderExtraFooter>
<a-button size="small" type="primary" @click="handleClose">
OK
</a-button>
</template>
</a-time-picker>
</template>
```
@@ -0,0 +1,30 @@
# Basic
## Description (en-US)
Click `TimePicker`, and then we could select or input a time in panel.
## Source
```vue
<script setup lang="ts">
import dayjs from 'dayjs'
import customParseFormat from 'dayjs/plugin/customParseFormat'
import { shallowRef } from 'vue'
dayjs.extend(customParseFormat)
const value = shallowRef()
function onChange(time: any, timeString: string) {
console.log(time, timeString)
}
</script>
<template>
<a-time-picker
v-model:value="value"
@change="onChange"
/>
</template>
```
@@ -0,0 +1,19 @@
# Change on scroll
## Description (en-US)
Use `changeOnScroll` and `needConfirm` to change the value when scrolling.
## Source
```vue
<script setup lang="ts">
function onChange(time: any, timeString: string) {
console.log(time, timeString)
}
</script>
<template>
<a-time-picker change-on-scroll :need-confirm="false" @change="onChange" />
</template>
```
@@ -0,0 +1,21 @@
# disabled
## Description (en-US)
A disabled state of the `TimePicker`.
## Source
```vue
<script setup lang="ts">
import dayjs from 'dayjs'
import customParseFormat from 'dayjs/plugin/customParseFormat'
dayjs.extend(customParseFormat)
const defaultValue = dayjs('12:08:23', 'HH:mm:ss')
</script>
<template>
<a-time-picker :default-value="defaultValue" disabled />
</template>
```
@@ -0,0 +1,20 @@
# Hour and minute
## Description (en-US)
While part of `format` is omitted, the corresponding column in panel will disappear, too.
## Source
```vue
<script setup lang="ts">
import dayjs from 'dayjs'
const format = 'HH:mm'
const defaultValue = dayjs('12:08', format)
</script>
<template>
<a-time-picker :default-value="defaultValue" :format="format" />
</template>
```
@@ -0,0 +1,16 @@
# interval option
## Description (en-US)
Show stepped options by `hourStep` `minuteStep` `secondStep`.
## Source
```vue
<script setup lang="ts">
</script>
<template>
<a-time-picker :minute-step="15" :second-step="10" :hour-step="1" />
</template>
```
@@ -0,0 +1,19 @@
# Need Confirm
## Description (en-US)
TimePicker will automatically determine whether to show a confirm button according to the `picker` property. You can also set the `needConfirm` property to determine whether to show a confirm button. When `needConfirm` is set, the user must click the confirm button to complete the selection. Otherwise, the selection will be submitted when the picker loses focus or select a time.
## Source
```vue
<script setup lang="ts">
function onChange(time: any, timeString: string) {
console.log(time, timeString)
}
</script>
<template>
<a-time-picker need-confirm @change="onChange" />
</template>
```
@@ -0,0 +1,20 @@
# Time Range Picker
## Description (en-US)
Use time range picker with `TimePicker.RangePicker`.
## Source
```vue
<script setup lang="ts">
import dayjs from 'dayjs'
const format = 'HH:mm:ss'
const defaultValue = [dayjs('12:08:23', 'HH:mm:ss'), dayjs('12:08:23', 'HH:mm:ss')]
</script>
<template>
<a-time-range-picker :default-value="defaultValue" :format="format" />
</template>
```
@@ -0,0 +1,23 @@
# Three Sizes
## Description (en-US)
The input box comes in three sizes: large, middle and small. Large is used in the form, while the medium size is the default.
## Source
```vue
<script setup lang="ts">
import dayjs from 'dayjs'
const defaultValue = dayjs('12:08:23', 'HH:mm:ss')
</script>
<template>
<a-space wrap>
<a-time-picker :default-value="defaultValue" size="large" />
<a-time-picker :default-value="defaultValue" />
<a-time-picker :default-value="defaultValue" size="small" />
</a-space>
</template>
```
@@ -0,0 +1,21 @@
# Status
## Description (en-US)
Add status to TimePicker with `status`, which could be `error` or `warning`.
## Source
```vue
<script setup lang="ts">
</script>
<template>
<a-space vertical>
<a-time-picker status="error" />
<a-time-picker status="warning" />
<a-time-range-picker status="error" />
<a-time-range-picker status="warning" />
</a-space>
</template>
```
@@ -0,0 +1,56 @@
# Custom semantic dom styling
## Description (en-US)
## Source
```vue
<script setup lang="ts">
import type { TimePickerProps } from 'antdv-next'
import { theme } from 'antdv-next'
const { useToken } = theme
const { token } = useToken()
const customClasses = {
root: 'custom-timepicker-root',
}
const stylesObject: TimePickerProps['styles'] = {
root: {
borderColor: '#d9d9d9',
},
}
const stylesFn: TimePickerProps['styles'] = (info) => {
if (info.props.size === 'large') {
return {
root: {
borderColor: '#722ed1',
},
suffix: {
color: '#722ed1',
},
popup: {
container: { border: '1px solid #722ed1', borderRadius: '8px' },
},
}
}
return {}
}
</script>
<template>
<a-flex vertical gap="middle">
<a-time-picker :classes="customClasses" :styles="stylesObject" placeholder="Object" />
<a-time-picker :classes="customClasses" :styles="stylesFn" placeholder="Function" size="large" />
</a-flex>
</template>
<style scoped>
.custom-timepicker-root {
border: 1px solid v-bind('token.colorPrimary');
width: 150px;
}
</style>
```
@@ -0,0 +1,46 @@
# Prefix and Suffix
## Description (en-US)
Custom `prefix` and `suffixIcon`.
## Source
```vue
<script setup lang="ts">
import { SmileOutlined } from '@antdv-next/icons'
import dayjs from 'dayjs'
import customParseFormat from 'dayjs/plugin/customParseFormat'
dayjs.extend(customParseFormat)
const defaultOpenValue = dayjs('00:00:00', 'HH:mm:ss')
function onChange(time: any, timeString: string) {
console.log(time, timeString)
}
</script>
<template>
<a-space vertical :size="12">
<a-time-picker
:default-open-value="defaultOpenValue"
@change="onChange"
>
<template #suffixIcon>
<SmileOutlined />
</template>
</a-time-picker>
<a-time-picker>
<template #prefix>
<SmileOutlined />
</template>
</a-time-picker>
<a-time-range-picker>
<template #prefix>
<SmileOutlined />
</template>
</a-time-range-picker>
</a-space>
</template>
```
@@ -0,0 +1,40 @@
# Value Format
## Description (en-US)
Use `valueFormat` to define the time value format. With it, `v-model:value` can directly use string values.
## Source
```vue
<script setup lang="ts">
import { shallowRef } from 'vue'
const singleValue = shallowRef<string | null>('12:08:23')
const rangeValue = shallowRef<[string | null, string | null] | null>(['09:30:00', '18:00:00'])
</script>
<template>
<a-space vertical :size="12">
<a-space>
<a-time-picker
v-model:value="singleValue"
value-format="HH:mm:ss"
format="HH:mm:ss"
allow-clear
/>
<span>value: {{ singleValue ?? 'null' }}</span>
</a-space>
<a-space>
<a-time-range-picker
v-model:value="rangeValue"
value-format="HH:mm:ss"
format="HH:mm:ss"
allow-clear
/>
<span>value: {{ rangeValue ? `${rangeValue[0]} ~ ${rangeValue[1]}` : 'null' }}</span>
</a-space>
</a-space>
</template>
```
@@ -0,0 +1,20 @@
# Under Control
## Description (en-US)
`value` and `onChange` should be used together,
## Source
```vue
<script setup lang="ts">
import type { Dayjs } from 'dayjs'
import { shallowRef } from 'vue'
const value = shallowRef<Dayjs>()
</script>
<template>
<a-time-picker v-model:value="value" />
</template>
```
@@ -0,0 +1,33 @@
# Variants
## Description (en-US)
Variants of TimePicker, there are four variants: `outlined` `filled` `borderless` and `underlined`.
## Source
```vue
<script setup lang="ts">
</script>
<template>
<a-flex vertical :gap="12">
<a-flex :gap="8">
<a-time-picker placeholder="Outlined" />
<a-time-range-picker :placeholder="['Outlined Start', 'Outlined End']" />
</a-flex>
<a-flex :gap="8">
<a-time-picker variant="filled" placeholder="Filled" />
<a-time-range-picker variant="filled" :placeholder="['Filled Start', 'Filled End']" />
</a-flex>
<a-flex :gap="8">
<a-time-picker variant="borderless" placeholder="Borderless" />
<a-time-range-picker variant="borderless" :placeholder="['Borderless Start', 'Borderless End']" />
</a-flex>
<a-flex :gap="8">
<a-time-picker variant="underlined" placeholder="Underlined" />
<a-time-range-picker variant="underlined" :placeholder="['Underlined Start', 'Underlined End']" />
</a-flex>
</a-flex>
</template>
```
@@ -0,0 +1,126 @@
---
title: TimePicker
description: To select/input a time.
---
## When To Use
By clicking the input box, you can select a time from a popup panel.
## Examples
## Demos
| Demo | Path |
| --- | --- |
| Basic | demo/basic.md |
| Under Control | demo/value.md |
| Value Format | demo/value-format.md |
| Three Sizes | demo/size.md |
| Need Confirm | demo/need-confirm.md |
| disabled | demo/disabled.md |
| Hour and minute | demo/hide-column.md |
| interval option | demo/interval-options.md |
| Addon | demo/addon.md |
| 12 hours | demo/12hours.md |
| Change on scroll | demo/change-on-scroll.md |
| Time Range Picker | demo/range-picker.md |
| Variants | demo/variant.md |
| Status | demo/status.md |
| Prefix and Suffix | demo/suffix.md |
| Custom semantic dom styling | demo/style-class.md |
## API
Common props ref:[Common props](../../docs/vue/common-props.md)
### TimePicker
| Property | Description | Type | Default | Version | [Global Config](../config-provider/docs.md#component-config) |
| --- | --- | --- | --- | --- | --- |
| allowClear | Customize clear icon | boolean \| \{ clearIcon?: VueNode \} | true | 5.8.0: Support object type | ✓ |
| cellRender | Custom rendering function for picker cells | (current: number, info: \{ originNode: VueNode, today: dayjs, range?: 'start' \| 'end', subType: 'hour' \| 'minute' \| 'second' \| 'meridiem' \}) => VueNode | - | 5.4.0 | × |
| changeOnScroll | Trigger selection when scroll the column | boolean | false | 5.14.0 | × |
| defaultValue | To set default time | [dayjs](http://day.js.org/) | - | | × |
| disabled | Determine whether the TimePicker is disabled | boolean | false | | × |
| disabledTime | To specify the time that cannot be selected | [DisabledTime](#disabledtime) | - | 4.19.0 | × |
| format | To set the time format | string | `HH:mm:ss` | | × |
| valueFormat | Set the binding value format. After setting, `value`, `defaultValue`, and `v-model:value` can use formatted strings, and `change` returns strings in the same format. Demo: [Value Format](#time-picker-demo-value-format) | string | - | | × |
| getPopupContainer | To set the container of the floating layer, while the default is to create a div element in body | function(trigger) | - | | × |
| hideDisabledOptions | Whether hide the options that can not be selected | boolean | false | | × |
| hourStep | Interval between hours in picker | number | 1 | | × |
| inputReadOnly | Set the `readonly` attribute of the input tag (avoids virtual keyboard on touch devices) | boolean | false | | × |
| minuteStep | Interval between minutes in picker | number | 1 | | × |
| needConfirm | Need click confirm button to trigger value change | boolean | - | 5.14.0 | × |
| open | Whether to popup panel | boolean | false | | × |
| placeholder | Display when there's no value | string \| \[string, string] | `Select a time` | | × |
| placement | The position where the selection box pops up | `bottomLeft` `bottomRight` `topLeft` `topRight` | bottomLeft | | × |
| ~~popupClassName~~ | The className of panel, please use `classes.popup` instead | string | - | | × |
| ~~popupStyle~~ | The style of panel, please use `styles.popup` instead | CSSProperties | - | | × |
| prefix | The custom prefix | VueNode | - | 5.22.0 | × |
| previewValue | When the user selects the time hover option, the value of the input field undergoes a temporary change | false \| hover | hover | 6.0.0 | × |
| renderExtraFooter | Called from time picker panel to render some addon to its bottom | () => VueNode | - | | × |
| secondStep | Interval between seconds in picker | number | 1 | | × |
| showNow | Whether to show `Now` button on panel | boolean | - | 4.4.0 | × |
| size | To determine the size of the input box, the height of `large` and `small`, are 40px and 24px respectively, while default size is 32px | `large` \| `middle` \| `small` | - | | × |
| status | Set validation status | 'error' \| 'warning' \| 'success' \| 'validating' | - | 4.19.0 | × |
| suffixIcon | The custom suffix icon | VueNode | - | | ✓ |
| use12Hours | Display as 12 hours format, with default format `h:mm:ss a` | boolean | false | | × |
| value | To set time, support `v-model:value` | [dayjs](http://day.js.org/) | - | | × |
| variant | Variants of picker | `outlined` \| `borderless` \| `filled` \| `underlined` | `outlined` | 5.13.0 \| `underlined`: 5.24.0 | ✓ |
| onChange | A callback function, can be executed when the selected time is changing | function(time: dayjs, timeString: string): void | - | | × |
| onOpenChange | A callback function which will be called while panel opening/closing | (open: boolean) => void | - | | × |
#### DisabledTime
```typescript
type DisabledTime = (now: Dayjs) => {
disabledHours?: () => number[]
disabledMinutes?: (selectedHour: number) => number[]
disabledSeconds?: (selectedHour: number, selectedMinute: number) => number[]
disabledMilliseconds?: (
selectedHour: number,
selectedMinute: number,
selectedSecond: number,
) => number[]
}
```
Note: `disabledMilliseconds` is added in `5.14.0`.
## Methods
| Name | Description | Version |
| ------- | ------------ | ------- |
| blur() | Remove focus | |
| focus() | Get focus | |
### RangePicker
Same props from [RangePicker](../date-picker/docs.md/#rangepicker) of DatePicker. And includes additional props:
| Property | Description | Type | Default | Version |
| --- | --- | --- | --- | --- |
| disabledTime | To specify the time that cannot be selected | [RangeDisabledTime](#rangedisabledtime) | - | 4.19.0 |
| order | Order start and end time | boolean | true | 4.1.0 |
### RangeDisabledTime
```typescript
type RangeDisabledTime = (
now: Dayjs,
type = 'start' | 'end',
) => {
disabledHours?: () => number[]
disabledMinutes?: (selectedHour: number) => number[]
disabledSeconds?: (selectedHour: number, selectedMinute: number) => number[]
}
```
## Semantic DOM
| _semantic | demo/_semantic.md |
## FAQ
- [How to use TimePicker with customize date library like dayjs](../../docs/vue/use-custom-date-library.md#timepicker)
@@ -0,0 +1,67 @@
# time-picker Token
Use these variables through `theme.components.DatePicker`. This document lists definitions only and does not include values.
This directory reuses the `DatePicker` component theme configuration.
```vue
<a-config-provider
:theme="{
token: {
// Global token configuration
},
components: {
DatePicker: {
// Token name: value
},
},
}"
>
...
</a-config-provider>
```
## Token List
| Token | Type | Description |
| --- | --- | --- |
| `presetsWidth` | `number` | Width of preset area |
| `presetsMaxWidth` | `number` | Max width of preset area |
| `zIndexPopup` | `number` | z-index of popup |
| `paddingInline` | `number` | Horizontal padding of input |
| `paddingInlineSM` | `number` | Horizontal padding of small input |
| `paddingInlineLG` | `number` | Horizontal padding of large input |
| `paddingBlock` | `number` | Vertical padding of input |
| `paddingBlockSM` | `number` | Vertical padding of small input |
| `paddingBlockLG` | `number` | Vertical padding of large input |
| `addonBg` | `string` | Background color of addon |
| `hoverBorderColor` | `string` | Hover border color |
| `activeBorderColor` | `string` | Active border color |
| `activeShadow` | `string` | Box-shadow when active |
| `errorActiveShadow` | `string` | Box-shadow when active in error status |
| `warningActiveShadow` | `string` | Box-shadow when active in warning status |
| `hoverBg` | `string` | Background color when the input box hovers |
| `activeBg` | `string` | Background color when the input box is activated |
| `inputFontSize` | `number` | Font size |
| `inputFontSizeLG` | `number` | Font size of large |
| `inputFontSizeSM` | `number` | Font size of small |
| `cellHoverBg` | `string` | Background color of cell hover state |
| `cellActiveWithRangeBg` | `string` | Background color of cell in range |
| `cellHoverWithRangeBg` | `string` | Background color of hovered cell in range |
| `cellBgDisabled` | `string` | Background color of disabled cell |
| `cellRangeBorderColor` | `string` | Border color of cell in range when picking |
| `timeColumnWidth` | `number` | Width of time column |
| `timeColumnHeight` | `number` | Height of time column |
| `timeCellHeight` | `number` | Height of time cell |
| `cellHeight` | `number` | Height of cell |
| `cellWidth` | `number` | Width of cell |
| `textHeight` | `number` | Height of cell text |
| `withoutTimeCellHeight` | `number` | Height of decade/year/quarter/month/week cell |
| `multipleItemBg` | `string` | Background color of multiple tag |
| `multipleItemBorderColor` | `string` | Border color of multiple tag |
| `multipleItemHeight` | `number` | Height of multiple tag |
| `multipleItemHeightSM` | `number` | Height of multiple tag with small size |
| `multipleItemHeightLG` | `number` | Height of multiple tag with large size |
| `multipleSelectorBgDisabled` | `string` | Background color of multiple selector when disabled |
| `multipleItemColorDisabled` | `string` | Text color of multiple tag when disabled |
| `multipleItemBorderColorDisabled` | `string` | Border color of multiple tag when disabled |