Back to Details

syncfusion-angular-timepicker

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Implementing Syncfusion Angular TimePicker

实现Syncfusion Angular TimePicker

A comprehensive guide for implementing the Syncfusion Essential JS 2 TimePicker component in Angular applications. Learn to create time selection interfaces, manage time inputs, handle events, and customize styling.
本指南全面介绍如何在Angular应用中实现Syncfusion Essential JS 2 TimePicker组件。学习创建时间选择界面、管理时间输入、处理事件以及自定义样式。

TimePicker Overview

TimePicker概述

The Syncfusion Angular TimePicker component is a dedicated time selection widget that provides:
  • Time Selection: Popup list with configurable time intervals for selection
  • Flexible Formatting: Custom time formats, skeleton options, and locale-aware formatting
  • Time Intervals: Configurable step intervals (15, 30, 60 minutes, etc.) for time selection
  • Range Constraints: Min/max time with strict validation and boundary enforcement
  • Comprehensive Event System: change, focus, blur, open, close, created, destroyed, cleared, itemRender events
  • Masked Input Support: Optional masked input format for guided user entry
  • Persistence & RTL: State persistence across reloads and right-to-left language support
  • Advanced Features: Strict mode validation, floating labels, keyboard customization, timezone support
  • Accessibility: Full WCAG 2.2 compliance, keyboard navigation, WAI-ARIA support
  • Theme Support: Material, Bootstrap, Tailwind, Fabric with light/dark variants
  • Mobile Optimized: Full screen mode on mobile devices, touch-friendly interface
Package: 
@syncfusion/ej2-angular-calendars
Syncfusion Angular TimePicker组件是一款专用的时间选择组件，提供以下功能：
  • 时间选择：可配置时间间隔的弹出选择列表
  • 灵活格式化：自定义时间格式、骨架选项及区域感知格式化
  • 时间间隔：可配置时间选择的步长间隔（15、30、60分钟等）
  • 范围约束：带严格验证和边界限制的最小/最大时间设置
  • 完善的事件系统：change、focus、blur、open、close、created、destroyed、cleared、itemRender事件
  • 掩码输入支持：可选的掩码输入格式，引导用户输入
  • 持久化与RTL支持：页面重载时的状态持久化及从右到左语言支持
  • 高级功能：严格模式验证、浮动标签、键盘自定义、时区支持
  • 无障碍访问：完全符合WCAG 2.2标准，支持键盘导航、WAI-ARIA
  • 主题支持：Material、Bootstrap、Tailwind、Fabric主题，含明暗变体
  • 移动端优化：移动端全屏模式、触控友好界面
包依赖：
@syncfusion/ej2-angular-calendars

Documentation Navigation

文档导航

Read the following references based on your specific needs:
根据你的具体需求阅读以下参考文档：

Getting Started

快速入门

📄 Read: references/getting-started.md
  • Package installation via npm and ng add
  • NgModule vs Standalone component setup
  • CSS theme imports and dependencies
  • Basic timepicker implementation
  • Component initialization and running the application
  • Development server setup
📄 阅读：references/getting-started.md
  • 通过npm和ng add安装包
  • NgModule与独立组件设置
  • CSS主题导入及依赖配置
  • 基础时间选择器实现
  • 组件初始化及应用运行
  • 开发服务器设置

Basic Implementation

基础实现

📄 Read: references/basic-implementation.md
  • Simple time picker with ngModel
  • Two-way data binding patterns
  • Readonly and disabled states
  • Basic validation and constraints
  • Event handling fundamentals
  • ViewChild component access
📄 阅读：references/basic-implementation.md
  • 结合ngModel的简单时间选择器
  • 双向数据绑定模式
  • 只读和禁用状态
  • 基础验证与约束
  • 事件处理基础
  • ViewChild组件访问

Time Configuration

时间配置

📄 Read: references/time-configuration.md
  • Time format customization (format property)
  • TimeFormatObject and skeleton options
  • Step intervals and time granularity
  • Min/max time constraints
  • ScrollTo position for time scrolling
  • Popup list configuration
📄 阅读：references/time-configuration.md
  • 时间格式自定义（format属性）
  • TimeFormatObject及骨架选项
  • 步长间隔与时间粒度
  • 最小/最大时间约束
  • 时间滚动的ScrollTo位置
  • 弹出列表配置

Events & Callbacks

事件与回调

📄 Read: references/events-and-callbacks.md
  • Change event with ChangeEventArgs
  • Focus/blur event handling
  • Open/close popup events
  • Created/destroyed lifecycle events
  • Cleared event when clear button is used
  • ItemRender for custom time formatting
📄 阅读：references/events-and-callbacks.md
  • 带ChangeEventArgs的change事件
  • Focus/blur事件处理
  • 弹出框打开/关闭事件
  • Created/destroyed生命周期事件
  • 点击清除按钮时的cleared事件
  • 用于自定义时间格式化的ItemRender

Methods & Imperative Access

方法与命令式访问

📄 Read: references/methods-and-imperative-access.md
  • ViewChild access and component references
  • show() to open the time popup
  • hide() to close the time popup
  • focusIn/focusOut for focus management
  • getPersistData() for state persistence
📄 阅读：references/methods-and-imperative-access.md
  • ViewChild访问与组件引用
  • show()方法打开时间弹出框
  • hide()方法关闭时间弹出框
  • focusIn/focusOut用于焦点管理
  • getPersistData()实现状态持久化

Advanced Features

高级功能

📄 Read: references/advanced-features.md
  • Masked input mode with mask placeholders
  • State persistence across page reloads
  • RTL (Right-to-Left) language support
  • Floating label types and behavior
  • Strict mode validation and error states
  • Keyboard shortcuts and key configuration
  • Timezone offset handling
  • Full screen mode for mobile devices
  • Clear button visibility and behavior
  • OpenOnFocus popup trigger
📄 阅读：references/advanced-features.md
  • 带掩码占位符的掩码输入模式
  • 页面重载时的状态持久化
  • RTL（从右到左）语言支持
  • 浮动标签类型及行为
  • 严格模式验证与错误状态
  • 键盘快捷键与按键配置
  • 时区偏移处理
  • 移动端全屏模式
  • 清除按钮可见性及行为
  • OpenOnFocus弹出框触发方式

Styling & Customization

样式与自定义

📄 Read: references/styling-and-customization.md
  • CSS class customization (cssClass property)
  • Theme selection and switching
  • Dark mode implementation
  • Component width and z-index configuration
  • HTML attribute injection (htmlAttributes)
  • Placeholder and enabled state styling
  • Disabled date styling and appearance
📄 阅读：references/styling-and-customization.md
  • CSS类自定义（cssClass属性）
  • 主题选择与切换
  • 深色模式实现
  • 组件宽度与z-index配置
  • HTML属性注入（htmlAttributes）
  • 占位符及启用状态样式
  • 禁用日期的样式与外观

Accessibility & Globalization

无障碍访问与全球化

📄 Read: references/accessibility-and-globalization.md
  • WCAG 2.2 and Section 508 compliance standards
  • WAI-ARIA attributes and roles
  • Keyboard navigation (arrows, enter, space, escape)
  • Screen reader compatibility and announcements
  • Localization and locale property usage
  • Time format variations
  • RTL text direction support
📄 阅读：references/accessibility-and-globalization.md
  • WCAG 2.2及Section 508合规标准
  • WAI-ARIA属性与角色
  • 键盘导航（箭头、回车、空格、ESC）
  • 屏幕阅读器兼容性与提示
  • 本地化与locale属性使用
  • 时间格式变体
  • RTL文本方向支持

API Reference

API参考

📄 Read: references/api-reference.md
  • Complete property reference with types and defaults
  • All method signatures with parameters and return types
  • All events with event argument types
  • Property descriptions and use cases
  • Method examples and common patterns
  • Type interfaces and enums
  • Key configuration for keyboard shortcuts
  • Comprehensive property-by-property guide
📄 阅读：references/api-reference.md
  • 完整的属性参考，含类型与默认值
  • 所有方法签名，含参数与返回类型
  • 所有事件及事件参数类型
  • 属性描述与使用场景
  • 方法示例与常见模式
  • 类型接口与枚举
  • 键盘快捷键的按键配置
  • 全面的逐属性指南

Quick Start Example

快速入门示例

typescript
// app.component.ts
import { Component } from '@angular/core';
import { ChangeEventArgs } from '@syncfusion/ej2-calendars';

@Component({
  selector: 'app-root',
  templateUrl: './app.component.html',
  styleUrls: ['./app.component.css']
})
export class AppComponent {
  // Simple time value
  timeValue: Date = new Date();
  
  // Configuration
  minTime: Date = new Date(2026, 2, 24, 8, 0);   // 8:00 AM
  maxTime: Date = new Date(2026, 2, 24, 20, 0);  // 8:00 PM
  format: string = 'hh:mm a';
  step: number = 30;  // 30-minute intervals
  
  // Event handler
  onTimeChange(args: ChangeEventArgs): void {
    console.log('Selected Time:', args.value);
    console.log('Selected Text:', args.text);
    console.log('Is User Interaction:', args.isInteracted);
  }
  
  onPopupOpen(): void {
    console.log('Time popup opened');
  }
  
  onPopupClose(): void {
    console.log('Time popup closed');
  }
}
html
<!-- app.component.html -->
<div style="padding: 20px;">
  <h2>Select a Time</h2>
  
  <ejs-timepicker
    id="timepicker"
    [value]="timeValue"
    [format]="format"
    [min]="minTime"
    [max]="maxTime"
    [step]="step"
    placeholder="Select time"
    (change)="onTimeChange($event)"
    (open)="onPopupOpen()"
    (close)="onPopupClose()">
  </ejs-timepicker>
  
  <p *ngIf="timeValue">
    Selected Time: {{ timeValue | date:'shortTime' }}
  </p>
</div>
typescript
// app.component.ts
import { Component } from '@angular/core';
import { ChangeEventArgs } from '@syncfusion/ej2-calendars';

@Component({
  selector: 'app-root',
  templateUrl: './app.component.html',
  styleUrls: ['./app.component.css']
})
export class AppComponent {
  // Simple time value
  timeValue: Date = new Date();
  
  // Configuration
  minTime: Date = new Date(2026, 2, 24, 8, 0);   // 8:00 AM
  maxTime: Date = new Date(2026, 2, 24, 20, 0);  // 8:00 PM
  format: string = 'hh:mm a';
  step: number = 30;  // 30-minute intervals
  
  // Event handler
  onTimeChange(args: ChangeEventArgs): void {
    console.log('Selected Time:', args.value);
    console.log('Selected Text:', args.text);
    console.log('Is User Interaction:', args.isInteracted);
  }
  
  onPopupOpen(): void {
    console.log('Time popup opened');
  }
  
  onPopupClose(): void {
    console.log('Time popup closed');
  }
}
html
<!-- app.component.html -->
<div style="padding: 20px;">
  <h2>Select a Time</h2>
  
  <ejs-timepicker
    id="timepicker"
    [value]="timeValue"
    [format]="format"
    [min]="minTime"
    [max]="maxTime"
    [step]="step"
    placeholder="Select time"
    (change)="onTimeChange($event)"
    (open)="onPopupOpen()"
    (close)="onPopupClose()">
  </ejs-timepicker>
  
  <p *ngIf="timeValue">
    Selected Time: {{ timeValue | date:'shortTime' }}
  </p>
</div>

Common Patterns

常见模式

Pattern 1: Business Hours Time Selection

模式1：营业时间选择

Select time within business hours (9 AM - 6 PM):
typescript
export class AppComponent {
  minTime: Date = new Date(2026, 2, 24, 9, 0);   // 9:00 AM
  maxTime: Date = new Date(2026, 2, 24, 18, 0);  // 6:00 PM
  timeValue: Date = new Date(2026, 2, 24, 10, 0);
  format: string = 'hh:mm a';
  step: number = 15;  // 15-minute intervals
}
html
<ejs-timepicker
  [value]="timeValue"
  [min]="minTime"
  [max]="maxTime"
  [step]="step"
  [format]="format"
  placeholder="Select appointment time">
</ejs-timepicker>
在营业时间内选择时间（上午9点 - 下午6点）：
typescript
export class AppComponent {
  minTime: Date = new Date(2026, 2, 24, 9, 0);   // 9:00 AM
  maxTime: Date = new Date(2026, 2, 24, 18, 0);  // 6:00 PM
  timeValue: Date = new Date(2026, 2, 24, 10, 0);
  format: string = 'hh:mm a';
  step: number = 15;  // 15-minute intervals
}
html
<ejs-timepicker
  [value]="timeValue"
  [min]="minTime"
  [max]="maxTime"
  [step]="step"
  [format]="format"
  placeholder="Select appointment time">
</ejs-timepicker>

Pattern 2: 24-Hour Format

模式2：24小时制格式

Display time in 24-hour military format:
typescript
export class AppComponent {
  timeValue: Date = new Date();
  format: string = 'HH:mm';  // 24-hour format
  step: number = 30;
}
html
<ejs-timepicker
  [value]="timeValue"
  [format]="format"
  [step]="step"
  placeholder="Select time (24-hour)">
</ejs-timepicker>
以24小时制显示时间：
typescript
export class AppComponent {
  timeValue: Date = new Date();
  format: string = 'HH:mm';  // 24-hour format
  step: number = 30;
}
html
<ejs-timepicker
  [value]="timeValue"
  [format]="format"
  [step]="step"
  placeholder="Select time (24-hour)">
</ejs-timepicker>

Pattern 3: Masked Input for Guided Entry

模式3：掩码输入引导

Use masked input to guide users through time entry:
typescript
export class AppComponent {
  timeValue: Date;
  enableMask: boolean = true;
  maskPlaceholder = {
    hour: 'hh',
    minute: 'mm',
    second: 'ss'
  };
  format: string = 'hh:mm:ss a';
}
html
<ejs-timepicker
  [value]="timeValue"
  [enableMask]="enableMask"
  [maskPlaceholder]="maskPlaceholder"
  format="hh:mm:ss a">
</ejs-timepicker>
使用掩码输入引导用户输入时间：
typescript
export class AppComponent {
  timeValue: Date;
  enableMask: boolean = true;
  maskPlaceholder = {
    hour: 'hh',
    minute: 'mm',
    second: 'ss'
  };
  format: string = 'hh:mm:ss a';
}
html
<ejs-timepicker
  [value]="timeValue"
  [enableMask]="enableMask"
  [maskPlaceholder]="maskPlaceholder"
  format="hh:mm:ss a">
</ejs-timepicker>

Pattern 4: Reactive Forms Integration

模式4：响应式表单集成

Integrate timepicker with Angular Reactive Forms:
typescript
import { FormBuilder, FormGroup, Validators } from '@angular/forms';

export class AppComponent {
  appointmentForm: FormGroup;
  
  constructor(private fb: FormBuilder) {
    this.appointmentForm = this.fb.group({
      appointmentTime: [
        new Date(),
        [Validators.required]
      ]
    });
  }
  
  submitForm(): void {
    if (this.appointmentForm.valid) {
      console.log(this.appointmentForm.value);
    }
  }
}
html
<form [formGroup]="appointmentForm">
  <ejs-timepicker
    formControlName="appointmentTime"
    format="hh:mm a"
    placeholder="Select time">
  </ejs-timepicker>
  
  <button (click)="submitForm()" [disabled]="!appointmentForm.valid">
    Submit
  </button>
</form>
将时间选择器与Angular响应式表单集成：
typescript
import { FormBuilder, FormGroup, Validators } from '@angular/forms';

export class AppComponent {
  appointmentForm: FormGroup;
  
  constructor(private fb: FormBuilder) {
    this.appointmentForm = this.fb.group({
      appointmentTime: [
        new Date(),
        [Validators.required]
      ]
    });
  }
  
  submitForm(): void {
    if (this.appointmentForm.valid) {
      console.log(this.appointmentForm.value);
    }
  }
}
html
<form [formGroup]="appointmentForm">
  <ejs-timepicker
    formControlName="appointmentTime"
    format="hh:mm a"
    placeholder="Select time">
  </ejs-timepicker>
  
  <button (click)="submitForm()" [disabled]="!appointmentForm.valid">
    Submit
  </button>
</form>

Pattern 5: Time Range Selection

模式5：时间范围选择

Select start and end times for a duration:
typescript
export class AppComponent {
  startTime: Date = new Date();
  endTime: Date = new Date(Date.now() + 3600000);  // +1 hour
  
  onStartTimeChange(args: ChangeEventArgs): void {
    // Ensure end time is after start time
    if (args.value && this.endTime <= args.value) {
      this.endTime = new Date(args.value.getTime() + 3600000);  // +1 hour
    }
  }
}
html
<div>
  <label>Start Time:</label>
  <ejs-timepicker
    [value]="startTime"
    format="hh:mm a"
    (change)="onStartTimeChange($event)">
  </ejs-timepicker>
  
  <label>End Time:</label>
  <ejs-timepicker
    [value]="endTime"
    [min]="startTime"
    format="hh:mm a">
  </ejs-timepicker>
</div>
选择时间段的开始和结束时间：
typescript
export class AppComponent {
  startTime: Date = new Date();
  endTime: Date = new Date(Date.now() + 3600000);  // +1 hour
  
  onStartTimeChange(args: ChangeEventArgs): void {
    // Ensure end time is after start time
    if (args.value && this.endTime <= args.value) {
      this.endTime = new Date(args.value.getTime() + 3600000);  // +1 hour
    }
  }
}
html
<div>
  <label>Start Time:</label>
  <ejs-timepicker
    [value]="startTime"
    format="hh:mm a"
    (change)="onStartTimeChange($event)">
  </ejs-timepicker>
  
  <label>End Time:</label>
  <ejs-timepicker
    [value]="endTime"
    [min]="startTime"
    format="hh:mm a">
  </ejs-timepicker>
</div>

Key Properties Reference

关键属性参考

PropertyTypePurpose
value
DateSelected time value for two-way binding
format
stringTime display format (e.g., 'hh:mm a')
min
DateMinimum selectable time
max
DateMaximum selectable time
step
numberTime interval in minutes (15, 30, 60)
enabled
booleanEnable/disable the component
readonly
booleanMake input readonly (select from popup only)
placeholder
stringPlaceholder text in input
enableMask
booleanEnable masked input mode
strictMode
booleanEnforce valid values only
enableRtl
booleanRight-to-left language support
enablePersistence
booleanPersist value across page reloads
scrollTo
DateDefault scroll position in time list
locale
stringLocale for formatting (e.g., 'en-US', 'de-DE')
cssClass
stringCustom CSS class for styling
width
stringComponent width
zIndex
numberZ-index for popup
showClearButton
booleanShow/hide clear icon
openOnFocus
booleanOpen popup on input focus
floatLabelType
stringFloating label behavior (Never/Always/Auto)
属性类型用途
value
Date用于双向绑定的选中时间值
format
string时间显示格式（例如：'hh:mm a'）
min
Date可选的最小时间
max
Date可选的最大时间
step
number时间间隔（分钟）（15、30、60）
enabled
boolean启用/禁用组件
readonly
boolean设置输入框只读（仅可通过弹出框选择）
placeholder
string输入框占位文本
enableMask
boolean启用掩码输入模式
strictMode
boolean仅允许有效值
enableRtl
boolean启用从右到左语言支持
enablePersistence
boolean页面重载时持久化值
scrollTo
Date时间列表中的默认滚动位置
locale
string格式化使用的区域设置（例如：'en-US'、'de-DE'）
cssClass
string自定义CSS类用于样式设置
width
string组件宽度
zIndex
number弹出框的z-index值
showClearButton
boolean显示/隐藏清除图标
openOnFocus
boolean输入框获焦时打开弹出框
floatLabelType
string浮动标签行为（Never/Always/Auto）

Common Use Cases

常见使用场景

Appointment Booking System

预约预订系统

  • Select available time slots from a list
  • Restrict to business hours with min/max time
  • Use 15 or 30-minute step intervals
  • Handle form validation with required validators
  • Display selected time confirmation
  • 从列表中选择可用时间段
  • 通过最小/最大时间限制在营业时间内选择
  • 使用15或30分钟的步长间隔
  • 结合必填验证器处理表单验证
  • 显示选中时间确认信息

Shift Management

班次管理

  • Select shift start and end times
  • Apply shift time constraints
  • Support multiple timezone offsets
  • Handle shift transitions (spanning midnight)
  • Export times in ISO format
  • 选择班次开始和结束时间
  • 应用班次时间约束
  • 支持多时区偏移
  • 处理跨午夜的班次转换
  • 以ISO格式导出时间

Meeting Scheduling

会议安排

  • Select meeting time with business hours constraint
  • Use 30-minute step intervals for standard durations
  • Display time in user's locale format
  • Prevent double bookings with validation
  • Sync with calendar component for availability
  • 在营业时间约束下选择会议时间
  • 使用30分钟步长间隔对应标准时长
  • 以用户区域格式显示时间
  • 通过验证防止重复预订
  • 与日历组件同步查看可用性

Time Tracking

时间跟踪

  • Record clock-in and clock-out times
  • Restrict to business hours
  • Use masked input for quick entry
  • Persist times for audit trail
  • Export times for payroll integration
  • 记录打卡和退卡时间
  • 限制在营业时间内操作
  • 使用掩码输入快速录入
  • 持久化时间用于审计追踪
  • 导出时间用于薪资集成

Event Registration

活动注册

  • Select event attendance time slot
  • Show available time ranges
  • Use clear button for corrections
  • Support multiple time formats
  • Accessibility for assistive technologies
  • 选择活动参与时间段
  • 显示可用时间范围
  • 使用清除按钮修正选择
  • 支持多种时间格式
  • 为辅助技术提供无障碍访问支持

Next Steps

后续步骤

  1. Start with Getting Started → Install and configure the component
  2. Build Basic Implementation → Create simple time pickers
  3. Add Event Handling → Respond to user interactions
  4. Implement Advanced Features → Add masked input, persistence, RTL
  5. Customize Appearance → Apply themes and custom styles
  6. Ensure Accessibility → Support keyboard and screen readers
  7. Reference API → Consult complete API documentation as needed
Ready to get started? Begin with references/getting-started.md for installation and setup instructions.
  1. 从快速入门开始 → 安装并配置组件
  2. 构建基础实现 → 创建简单的时间选择器
  3. 添加事件处理 → 响应用户交互
  4. 实现高级功能 → 添加掩码输入、持久化、RTL支持
  5. 自定义外观 → 应用主题和自定义样式
  6. 确保无障碍访问 → 支持键盘和屏幕阅读器
  7. 参考API文档 → 根据需要查阅完整的API文档
准备开始了？ 从references/getting-started.md开始，获取安装和设置说明。