syncfusion-angular-timepicker

实现 Syncfusion Angular TimePicker

本指南全面介绍如何在 Angular 应用中实现 Syncfusion Essential JS 2 TimePicker 组件。了解如何创建时间选择界面、管理时间输入、处理事件并自定义样式。

TimePicker 概述

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

文档导航

根据具体需求阅读以下参考文档：

入门指南

📄 阅读： references/getting-started.md

• 通过 npm 和 ng add 安装软件包
• NgModule 与独立组件设置
• CSS 主题导入和依赖项
• 基本 TimePicker 实现
• 组件初始化和运行应用
• 开发服务器设置

基本实现

📄 阅读： references/basic-implementation.md

• 使用 ngModel 创建简单的时间选择器
• 双向数据绑定模式
• 只读和禁用状态
• 基本验证和限制
• 事件处理基础知识
• ViewChild 组件访问

时间配置

📄 阅读： references/time-configuration.md

• 自定义时间格式（format 属性）
• TimeFormatObject 和骨架选项
• 步长间隔和时间粒度
• 最小/最大时间限制
• 时间滚动的 ScrollTo 位置
• 弹出列表配置

事件与回调

📄 阅读： references/events-and-callbacks.md

• 使用 ChangeEventArgs 的 Change 事件
• 焦点/失焦事件处理
• 打开/关闭弹窗事件
• Created/destroyed 生命周期事件
• 使用清除按钮时触发的 Cleared 事件
• 用于自定义时间格式的 ItemRender

方法与命令式访问

📄 阅读： references/methods-and-imperative-access.md

• ViewChild 访问和组件引用
• 使用 show() 打开时间弹窗
• 使用 hide() 关闭时间弹窗
• 使用 focusIn/focusOut 管理焦点
• 使用 getPersistData() 持久化状态

高级功能

📄 阅读： references/advanced-features.md

• 带掩码占位符的掩码输入模式
• 跨页面重新加载的状态持久化
• RTL（从右到左）语言支持
• 浮动标签类型和行为
• 严格模式验证和错误状态
• 键盘快捷键和按键配置
• 时区偏移处理
• 移动设备全屏模式
• 清除按钮的显示和行为
• OpenOnFocus 弹窗触发器

样式与自定义

📄 阅读： references/styling-and-customization.md

• CSS 类自定义（cssClass 属性）
• 主题选择与切换
• 深色模式实现
• 组件宽度和 z-index 配置
• HTML 属性注入（htmlAttributes）
• 占位符和启用状态样式
• 禁用日期的样式与外观

无障碍与全球化

📄 阅读： references/accessibility-and-globalization.md

• 符合 WCAG 2.2 和 Section 508 标准
• WAI-ARIA 属性和角色
• 键盘导航（方向键、Enter、空格、Escape）
• 兼容屏幕阅读器并提供播报
• 本地化和 locale 属性的用法
• 时间格式变体
• 支持 RTL 文本方向

API 参考

📄 阅读： references/api-reference.md

• 完整的属性参考，包含类型和默认值
• 所有方法签名，包含参数和返回类型
• 所有事件，包含事件参数类型
• 属性说明和使用场景
• 方法示例和常见模式
• 类型接口和枚举
• 键盘快捷键的关键配置
• 全面的逐属性指南

快速入门示例

// 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');
  }
}

<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>

常见模式

模式 1：工作时间选择

在工作时间（上午 9 点至下午 6 点）内选择时间：

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
}

<ejs-timepicker
  [value]="timeValue"
  [min]="minTime"
  [max]="maxTime"
  [step]="step"
  [format]="format"
  placeholder="Select appointment time">
</ejs-timepicker>

模式 2：24 小时制格式

以 24 小时制显示时间：

export class AppComponent {
  timeValue: Date = new Date();
  format: string = 'HH:mm';  // 24-hour format
  step: number = 30;
}

<ejs-timepicker
  [value]="timeValue"
  [format]="format"
  [step]="step"
  placeholder="Select time (24-hour)">
</ejs-timepicker>

模式 3：用于引导输入的掩码输入

使用掩码输入引导用户输入时间：

export class AppComponent {
  timeValue: Date;
  enableMask: boolean = true;
  maskPlaceholder = {
    hour: 'hh',
    minute: 'mm',
    second: 'ss'
  };
  format: string = 'hh:mm:ss a';
}

<ejs-timepicker
  [value]="timeValue"
  [enableMask]="enableMask"
  [maskPlaceholder]="maskPlaceholder"
  format="hh:mm:ss a">
</ejs-timepicker>

模式 4：响应式表单集成

将时间选择器集成到 Angular 响应式表单中：

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);
    }
  }
}

<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>

模式 5：时间范围选择

选择某个时长的开始和结束时间：

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
    }
  }
}

<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>

关键属性参考

属性	类型	用途
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）

常见用例

预约系统

• 从列表中选择可用时段
• 通过最小/最大时间限制在工作时间内
• 使用 15 分钟或 30 分钟的时间间隔
• 使用必填验证器处理表单验证
• 显示所选时间的确认信息

班次管理

• 选择班次开始和结束时间
• 应用班次时间限制
• 支持多个时区偏移量
• 处理跨午夜的班次切换
• 以 ISO 格式导出时间

会议安排

• 在工作时间限制内选择会议时间
• 使用 30 分钟的时间间隔设置标准时长
• 按用户的区域设置格式显示时间
• 通过验证防止重复预订
• 与日历组件同步以查询可用时段

时间跟踪

• 记录签到和签退时间
• 限定在工作时间内
• 使用掩码输入，快速录入
• 持久化保存时间记录，以便审计追踪
• 导出时间记录，以便与薪资系统集成

活动报名

• 选择活动参与的时间段
• 显示可用的时间范围
• 使用清除按钮进行更正
• 支持多种时间格式
• 支持辅助技术，确保无障碍访问

后续步骤

1. 从入门指南开始 → 安装并配置组件
2. 构建基础实现 → 创建简单的时间选择器
3. 添加事件处理 → 响应用户交互
4. 实现高级功能 → 添加掩码输入、持久化和 RTL
5. 自定义外观 → 应用主题和自定义样式
6. 确保无障碍访问 → 支持键盘和屏幕阅读器
7. 查阅 API → 根据需要参考完整的 API 文档

---

准备好开始了吗？ 请从 references/getting-started.md 开始，查看安装和设置说明。