syncfusion-maui-time-picker

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Implementing Syncfusion .NET MAUI TimePicker

实现Syncfusion .NET MAUI TimePicker

The Syncfusion .NET MAUI TimePicker (SfTimePicker) is a powerful control that allows users to select time values through an intuitive scrollable interface. It supports multiple time formats, customizable intervals, dialog modes, time restrictions, and extensive styling options.

Syncfusion .NET MAUI TimePicker（SfTimePicker）是一款功能强大的控件，允许用户通过直观的可滚动界面选择时间值。它支持多种时间格式、可自定义的时间间隔、对话框模式、时间限制以及丰富的样式选项。

When to Use This Skill

何时使用本技能

Use this skill when you need to:

Implement time selection in .NET MAUI applications
Add SfTimePicker controls to XAML or C# code
Configure time formats (12/24 hour, with/without seconds, milliseconds)
Set up dialog or positioned picker modes
Define hour/minute/second intervals for time selection
Restrict selectable times (business hours, appointment slots, blocked times)
Handle time selection events or use MVVM commands
Customize picker appearance (header, footer, selection view, text display)
Implement accessible or localized time pickers
Troubleshoot TimePicker configuration or behavior issues

当你需要以下功能时，可使用本技能：

在.NET MAUI应用中实现时间选择功能
在XAML或C#代码中添加SfTimePicker控件
配置时间格式（12/24小时制、包含/不包含秒数、毫秒）
设置对话框或定位选择器模式
定义时间选择的时/分/秒间隔
限制可选时间（工作时间、预约时段、禁用时间）
处理时间选择事件或使用MVVM命令
自定义选择器外观（页眉、页脚、选择视图、文本显示）
实现无障碍或本地化时间选择器
排查TimePicker配置或行为问题

Component Overview

组件概述

The SfTimePicker provides:

14 predefined time formats supporting 12/24-hour formats with hours, minutes, seconds, and milliseconds
Three picker modes: Default (inline), Dialog (popup), and RelativeDialog (positioned popup)
Time intervals for hours, minutes, seconds, and milliseconds
Time restrictions including minimum/maximum time and blackout times
Looping support for seamless navigation between first and last items
Rich event system with selection changes, dialog lifecycle, and footer button events
MVVM support through commands (SelectionChangedCommand, AcceptCommand, DeclineCommand)
Extensive customization for header, footer, column headers, selection view, and text display modes
Accessibility and localization support for global applications

SfTimePicker提供以下功能：

14种预定义时间格式：支持包含时、分、秒、毫秒的12/24小时制格式
三种选择器模式：默认（内嵌）、Dialog（弹窗）、RelativeDialog（定位弹窗）
时间间隔：支持时、分、秒、毫秒级的间隔设置
时间限制：包括最小/最大时间和禁用时间设置
循环支持：可在首尾项之间无缝导航
丰富的事件系统：包含选择变更、对话框生命周期、页脚按钮事件
MVVM支持：通过命令（SelectionChangedCommand、AcceptCommand、DeclineCommand）实现
全面的自定义选项：支持页眉、页脚、列标题、选择视图和文本显示模式的自定义
无障碍与本地化支持：适配全球应用需求

Documentation and Navigation Guide

文档与导航指南

Getting Started

入门指南

📄 Read: references/getting-started.md

When to read: Setting up TimePicker for the first time, installation, basic implementation.

Coverage:

NuGet package installation (Syncfusion.Maui.Picker)
Handler registration (ConfigureSyncfusionCore in MauiProgram.cs)
Basic SfTimePicker initialization (XAML and C#)
Setting header and footer views
Configuring height and width
Using SelectedTime property
Clear selection support

📄 阅读： references/getting-started.md

阅读时机： 首次设置TimePicker、安装、基础实现阶段。

涵盖内容：

NuGet包安装（Syncfusion.Maui.Picker）
处理器注册（MauiProgram.cs中的ConfigureSyncfusionCore）
SfTimePicker基础初始化（XAML和C#）
设置页眉和页脚视图
配置高度和宽度
使用SelectedTime属性
清除选择支持

Time Formatting

时间格式化

📄 Read: references/formatting.md

When to read: Configuring how time is displayed (12/24 hour, including/excluding seconds, milliseconds).

Coverage:

Format property overview
14 predefined time formats:
- ```
H_mm
```
  ,
```
H_mm_ss
```
  (24-hour without leading zero)
- ```
HH_mm
```
  ,
```
HH_mm_ss
```
  ,
```
HH_mm_ss_fff
```
  (24-hour with leading zero)
- ```
h_mm_tt
```
  ,
```
h_mm_ss_tt
```
  (12-hour without leading zero + AM/PM)
- ```
hh_mm_tt
```
  ,
```
hh_mm_ss_tt
```
  ,
```
hh_mm_ss_fff_tt
```
  ,
```
hh_tt
```
  (12-hour with leading zero + AM/PM)
- ```
mm_ss
```
  ,
```
mm_ss_fff
```
  ,
```
ss_fff
```
  (minute/second combinations)
- ```
Default
```
  (culture-based format)
Format usage examples and switching between formats

📄 阅读： references/formatting.md

阅读时机： 配置时间显示方式（12/24小时制、包含/排除秒数、毫秒）。

涵盖内容：

Format属性概述
14种预定义时间格式：
- ```
H_mm
```
  、
```
H_mm_ss
```
  （无前导零的24小时制）
- ```
HH_mm
```
  、
```
HH_mm_ss
```
  、
```
HH_mm_ss_fff
```
  （有前导零的24小时制）
- ```
h_mm_tt
```
  、
```
h_mm_ss_tt
```
  （无前导零的12小时制+AM/PM）
- ```
hh_mm_tt
```
  、
```
hh_mm_ss_tt
```
  、
```
hh_mm_ss_fff_tt
```
  、
```
hh_tt
```
  （有前导零的12小时制+AM/PM）
- ```
mm_ss
```
  、
```
mm_ss_fff
```
  、
```
ss_fff
```
  （分/秒组合格式）
- ```
Default
```
  （基于文化的格式）
格式使用示例及格式切换

Picker Modes and Display

选择器模式与显示

📄 Read: references/picker-modes.md

When to read: Configuring how the picker is displayed (inline, popup dialog, positioned dialog).

Coverage:

Mode property (Default, Dialog, RelativeDialog)
Dialog mode configuration
IsOpen property for programmatic picker control
RelativeDialog mode for positioned popups
RelativePosition options (8 alignment positions):
- AlignTop, AlignBottom, AlignToLeftOf, AlignToRightOf
- AlignTopLeft, AlignTopRight, AlignBottomLeft, AlignBottomRight
RelativeView property for positioning relative to specific controls
Custom popup size (PopupWidth, PopupHeight properties)
Code examples for each mode

📄 阅读： references/picker-modes.md

阅读时机： 配置选择器的显示方式（内嵌、弹窗对话框、定位对话框）。

涵盖内容：

Mode属性（Default、Dialog、RelativeDialog）
Dialog模式配置
IsOpen属性：程序化控制选择器显示
RelativeDialog模式：定位弹窗
RelativePosition选项（8种对齐位置）：
- AlignTop、AlignBottom、AlignToLeftOf、AlignToRightOf
- AlignTopLeft、AlignTopRight、AlignBottomLeft、AlignBottomRight
RelativeView属性：相对于特定控件定位
自定义弹窗尺寸（PopupWidth、PopupHeight属性）
各模式代码示例

Time Intervals and Looping

时间间隔与循环

📄 Read: references/time-intervals-looping.md

When to read: Setting intervals between time values or enabling continuous looping.

Coverage:

HourInterval property (e.g., show every 2 hours)
MinuteInterval property (e.g., show every 5, 10, 15 minutes)
SecondInterval property (e.g., show every 10 seconds)
MilliSecondInterval property for precise time selection
EnableLooping property for seamless first ↔ last item navigation
Combining intervals with different time formats
Practical scenarios (appointment booking, time tracking)

📄 阅读： references/time-intervals-looping.md

阅读时机： 设置时间值之间的间隔或启用连续循环功能。

涵盖内容：

HourInterval属性（例如：每2小时显示一次）
MinuteInterval属性（例如：每5、10、15分钟显示一次）
SecondInterval属性（例如：每10秒显示一次）
MilliSecondInterval属性：精确时间选择
EnableLooping属性：首尾项无缝导航
时间间隔与不同时间格式的组合
实际场景（预约预订、时间追踪）

Time Restrictions

时间限制

📄 Read: references/time-restrictions.md

When to read: Limiting selectable times (business hours, min/max ranges, blocked times).

Coverage:

MinimumTime property to set earliest selectable time
MaximumTime property to set latest selectable time
BlackoutTimes collection to disable specific times
Time range validation rules
Use cases (business hours: 9 AM - 5 PM, appointment slots, blocked lunch hours)
Combining restrictions with formats and intervals

📄 阅读： references/time-restrictions.md

阅读时机： 限制可选时间（工作时间、最小/最大范围、禁用时间）。

涵盖内容：

MinimumTime属性：设置最早可选时间
MaximumTime属性：设置最晚可选时间
BlackoutTimes集合：禁用特定时间
时间范围验证规则
使用场景（工作时间：上午9点-下午5点、预约时段、午餐禁用时间）
限制与格式、间隔的组合

Events and Commands

事件与命令

📄 Read: references/events-commands.md

When to read: Handling time selection changes, dialog lifecycle, or using MVVM commands.

Coverage:

SelectionChanged event
- TimePickerSelectionChangedEventArgs with NewValue and OldValue
- IsSelectionImmediate behavior (immediate vs deferred selection)
Dialog mode events:
- Opened event (when picker opens)
- Closing event with CancelEventArgs (can cancel closing)
- Closed event (after picker closes)
Footer view events:
- OkButtonClicked event
- CancelButtonClicked event
MVVM Commands:
- SelectionChangedCommand
- AcceptCommand (OK button)
- DeclineCommand (Cancel button)
Event usage patterns and best practices

📄 阅读： references/events-commands.md

阅读时机： 处理时间选择变更、对话框生命周期或使用MVVM命令。

涵盖内容：

SelectionChanged事件
- TimePickerSelectionChangedEventArgs包含NewValue和OldValue
- IsSelectionImmediate行为（即时选择 vs 延迟选择）
Dialog模式事件：
- Opened事件（选择器打开时触发）
- Closing事件：带CancelEventArgs（可取消关闭）
- Closed事件（选择器关闭后触发）
页脚视图事件：
- OkButtonClicked事件
- CancelButtonClicked事件
MVVM命令：
- SelectionChangedCommand
- AcceptCommand（确定按钮）
- DeclineCommand（取消按钮）
事件使用模式与最佳实践

Customization and Styling

自定义与样式

📄 Read: references/customization.md

When to read: Customizing picker appearance (colors, fonts, header/footer, visual effects).

Coverage:

Header view customization
- Text, Height, Background, TextStyle properties
Footer view customization
- OkButtonText, CancelButtonText
- ShowOkButton, Height, Background, TextStyle
Column header view customization
- Text, Height, TextStyle per column
Selection view customization
- Background, Stroke, StrokeThickness, CornerRadius, TextStyle
TextDisplayMode options:
- Default, Fade, Shrink, FadeAndShrink
Liquid glass effect for modern UI
Item text styling
Complete customization examples

📄 阅读： references/customization.md

阅读时机： 自定义选择器外观（颜色、字体、页眉/页脚、视觉效果）。

涵盖内容：

页眉视图自定义
- Text、Height、Background、TextStyle属性
页脚视图自定义
- OkButtonText、CancelButtonText
- ShowOkButton、Height、Background、TextStyle
列标题视图自定义
- 每列的Text、Height、TextStyle
选择视图自定义
- Background、Stroke、StrokeThickness、CornerRadius、TextStyle
TextDisplayMode选项：
- Default、Fade、Shrink、FadeAndShrink
液态玻璃效果：打造现代UI
项文本样式
完整自定义示例

Accessibility and Localization

无障碍与本地化

📄 Read: references/accessibility-localization.md

When to read: Implementing accessible controls or supporting multiple languages/cultures.

Coverage:

WCAG compliance features
Screen reader support
Keyboard navigation
Semantic properties for accessibility
Localization configuration
Culture-specific time formatting
RTL (right-to-left) language support
Multi-language implementation examples

📄 阅读： references/accessibility-localization.md

阅读时机： 实现无障碍控件或支持多语言/文化。

涵盖内容：

WCAG合规特性
屏幕阅读器支持
键盘导航
无障碍语义属性
本地化配置
基于文化的时间格式化
RTL（从右到左）语言支持
多语言实现示例