GitHubopen_in_new

TimePicker ​

TimePicker 是独立的时间选择界面。TextField 在 type="time" 时会自动使用它。省略 format 时，组件会采用配置的区域设置或浏览器区域设置所偏好的小时制。

原生弹出层关闭时会触发 update:open(false)。如果清理操作需要等到 TimePicker 自身的视觉退出完成后再执行，请使用 closed。

密度 ​

TimePicker 的数字显示、键盘输入、时段控件及周围间距会继承 --md-density 并随之调整。钟面、时钟标签和指针几何尺寸保持不变，以确保指针选择行为一致。

格式和输入模式 ​

format 选择 12h 或 24h；inputMode 选择 clock 或 keyboard。显式属性优先于 timePickerContextKey 中对应的值。未设置格式偏好时，独立 TimePicker 遵循配置的区域设置或浏览器区域设置，TextField 内嵌的时间选择器使用 24h。未设置输入模式偏好时，12 小时制选择器默认使用时钟，24 小时制选择器默认使用键盘输入。用户可在选择器打开时切换模式。

可通过 M3VuePlugin 设置 timePickerDefaults.format 和 timePickerDefaults.inputMode，或通过上下文配置子树。独立和 TextField 内嵌的时间选择器都会继承这些偏好。详见组件默认值。

示例 ​

默认 ​

24 小时制 ​

键盘输入 ​

参考 ​

结构

元素部件选择器
<div>
root
[data-scope="time-picker"][data-part="root"]
left_click鼠标左键单击复制
<div>
surface
[data-scope="time-picker"][data-part="surface"]
left_click鼠标左键单击复制
<header>
header
[data-scope="time-picker"][data-part="header"]
left_click鼠标左键单击复制
<div>
title
[data-scope="time-picker"][data-part="title"]
left_click鼠标左键单击复制
<div>
display条件显示
[data-scope="time-picker"][data-part="display"]
left_click鼠标左键单击复制
<button>
hour-display
[data-scope="time-picker"][data-part="hour-display"]
left_click鼠标左键单击复制
<span>
display-separator
[data-scope="time-picker"][data-part="display-separator"]
left_click鼠标左键单击复制
<button>
minute-display
[data-scope="time-picker"][data-part="minute-display"]
left_click鼠标左键单击复制
<div>
period-selector条件显示
[data-scope="time-picker"][data-part="period-selector"]
left_click鼠标左键单击复制
<button>
period-option
[data-scope="time-picker"][data-part="period-option"]
left_click鼠标左键单击复制
<div>
clock条件显示
[data-scope="time-picker"][data-part="clock"]
left_click鼠标左键单击复制
<div>
clock-face
[data-scope="time-picker"][data-part="clock-face"]
left_click鼠标左键单击复制
<div>
clock-hand
[data-scope="time-picker"][data-part="clock-hand"]
left_click鼠标左键单击复制
<button>
clock-option
[data-scope="time-picker"][data-part="clock-option"]
left_click鼠标左键单击复制
<div>
inputs
[data-scope="time-picker"][data-part="inputs"]
left_click鼠标左键单击复制
<label>
hour-input-field
[data-scope="time-picker"][data-part="hour-input-field"]
left_click鼠标左键单击复制
<input>
hour-input
[data-scope="time-picker"][data-part="hour-input"]
left_click鼠标左键单击复制
<span>
input-label
[data-scope="time-picker"][data-part="input-label"]
left_click鼠标左键单击复制
<span>
input-error条件显示
[data-scope="time-picker"][data-part="input-error"]
left_click鼠标左键单击复制
<span>
input-separator
[data-scope="time-picker"][data-part="input-separator"]
left_click鼠标左键单击复制
<label>
minute-input-field
[data-scope="time-picker"][data-part="minute-input-field"]
left_click鼠标左键单击复制
<input>
minute-input
[data-scope="time-picker"][data-part="minute-input"]
left_click鼠标左键单击复制
<div>
actions
[data-scope="time-picker"][data-part="actions"]
left_click鼠标左键单击复制
<IconButton>
mode-toggle
[data-scope="time-picker"][data-part="mode-toggle"]
left_click鼠标左键单击复制
<span>
actions-spacer
[data-scope="time-picker"][data-part="actions-spacer"]
left_click鼠标左键单击复制

属性

名称说明默认值控件
shape可选

Corner style; inherits the shared shape default.

M3Shape | undefined
-
-
id可选

Optional explicit id for the popover element.

string | undefined
undefined
-
variant可选

Visual and positioning mode. Auto uses docked layout until a narrow/coarse pointer viewport.

TimePickerVariant | undefined
"auto"
-
anchorName可选

CSS anchor name used to position the docked popover.

string | undefined
undefined
-
anchorElement可选

Element passed to showPopover as the source for focus and dismissal semantics.

HTMLElement | undefined
undefined
-
ariaLabel可选

Accessible label for the picker surface.

string | undefined
undefined
titleText可选

Visible title.

string | undefined
undefined
locale可选

BCP 47 locale used for the default clock format and day-period labels.

string | undefined
undefined
format可选

Clock format. Defaults to the locale's preferred hour cycle.

TimePickerFormat | undefined
undefined
-
inputMode可选

Initial input mode. If omitted, 12h starts in clock mode and 24h starts in keyboard mode.

TimePickerInputMode | undefined
undefined
-
confirmText可选

Text for the confirmation button.

string | undefined
undefined
cancelText可选

Text for the cancel button.

string | undefined
undefined
modelValue可选

-

TimePickerModelValue
-
-
open可选

-

boolean | undefined
false

事件6

名称类型说明
update:open[value: boolean]-
cancel[]-
closed[]-
update:modelValue[value: TimePickerModelValue]-
change[value: TimePickerModelValue]-
confirm[value: TimePickerModelValue]-

样式14

Token说明
--md-time-picker-container-colorColor
回退值var(--md-sys-color-surface-container-high)

Controls container color.

--md-time-picker-container-elevationElevation
回退值var(--md-sys-elevation-level3)

Controls container elevation.

--md-time-picker-container-shapeShape
回退值var(--md-shape-overlay)

Controls container shape.

--md-time-picker-container-widthLayout
回退值22.5rem

Controls container width.

--md-time-picker-clock-dial-container-colorColor
回退值var(--md-sys-color-surface-container-highest)

Controls clock dial container color.

--md-time-picker-clock-hand-colorColor
回退值var(--md-sys-color-primary)

Controls clock hand and selected clock option color.

--md-time-picker-clock-label-text-colorColor
回退值var(--md-sys-color-on-surface)

Controls unselected clock option label color.

--md-time-picker-clock-selected-label-text-colorState
回退值var(--md-sys-color-on-primary)

Controls selected clock option label color.

--md-time-picker-selector-container-colorColor
回退值var(--md-sys-color-surface-container-highest)

Controls time selector field container color.

--md-time-picker-selector-selected-container-colorState
回退值var(--md-sys-color-primary-container)

Controls selected time selector field container color.

--md-time-picker-selector-selected-label-text-colorState
回退值var(--md-sys-color-on-primary-container)

Controls selected time selector field label color.

--md-time-picker-selector-unselected-label-text-colorColor
回退值var(--md-sys-color-on-surface)

Controls unselected time selector field label color.

--md-time-picker-period-selector-outline-colorColor
回退值var(--md-sys-color-outline)

Controls AM/PM selector outline color.

--md-time-picker-title-text-colorColor
回退值var(--md-sys-color-on-surface-variant)

Controls title text color.