syncfusion-angular-datetimepicker

实现 Syncfusion Angular 日期时间选择器

本指南全面介绍如何在 Angular 应用中实现 Syncfusion Essential JS 2 日期时间选择器组件。了解如何创建日期和时间选择界面、管理日历和时间选择器、处理事件以及自定义样式。

日期时间选择器概述

Syncfusion Angular 日期时间选择器组件是一个组合式日期和时间选择控件，提供以下功能：

• 集成日期和时间选择： 日期使用日历弹出窗口，时间使用时间选择器下拉列表
• 灵活的格式设置： 自定义日期格式和时间格式，并支持符合区域设置的格式
• 日历视图： 月（默认）、年和十年视图，并支持流畅导航
• 时间间隔： 可配置时间选择步长间隔（15、30、60 分钟等）
• 范围约束： 最小/最大日期和最小/最大时间，并进行严格验证
• 完善的事件系统： change、focus、blur、open、close、created、destroyed、navigated、renderDayCell 事件
• 掩码输入支持： 可选的掩码输入格式，引导用户输入
• 持久化和 RTL： 跨重新加载的状态持久化，以及从右向左语言支持
• 高级功能： 严格模式验证、浮动标签、键盘自定义、时区支持
• 无障碍访问： 完全符合 WCAG 2.2 标准，支持键盘导航和 WAI-ARIA
• 主题支持： Material、Bootstrap、Tailwind、Fabric，并提供浅色/深色变体
• 针对移动设备优化： 在移动设备上使用全屏模式，并提供适合触控的界面

包： @syncfusion/ej2-angular-datetimepickers

文档导航

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

开始使用

📄 阅读： references/getting-started.md

• 通过 npm 和 ng add 安装包
• NgModule 与 Standalone 组件设置
• CSS 主题导入和依赖项
• 基本日期时间选择器实现
• 组件初始化和应用运行
• 开发服务器设置

基本实现

📄 阅读： references/basic-implementation.md

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

日期和时间配置

📄 阅读： references/date-time-configuration.md

• 日期格式自定义（format 属性）
• 时间格式配置（timeFormat 属性）
• ISO 日期字符串处理
• 日期范围约束（最小/最大日期）
• 时间范围约束（minTime/maxTime）
• 解析多种输入格式（inputFormats）

日历和时间视图

📄 阅读： references/calendar-and-time-views.md

• 日历视图模式（月、年、十年）
• 用于控制视图的 start 和 depth 属性
• 时间选择器弹出窗口配置
• 时间步长间隔和粒度
• 时间滚动的 ScrollTo 位置
• “今天”按钮和清除按钮的行为

事件和回调

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

• 搭配 ChangedEventArgs 的 Change 事件
• Focus/blur 事件处理
• 弹出窗口的打开/关闭事件
• Created/destroyed 生命周期事件
• 用于日历导航的 Navigate 事件
• 用于自定义日期样式的 RenderDayCell
• 使用清除按钮时触发的 Cleared 事件

方法和命令式访问

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

• ViewChild 访问和组件引用
• 使用 currentView() 获取当前日历视图
• 使用 navigateTo() 进行编程式导航
• 使用 focusIn/focusOut 管理焦点
• 使用 destroy() 清理并释放资源
• 使用 getPersistData() 持久化状态

高级功能

📄 阅读： references/advanced-features.md

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

样式与自定义

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

• CSS 类自定义（cssClass 属性）
• 主题选择与切换
• 深色模式实现
• 组件宽度和 z-index 配置
• HTML 属性注入（htmlAttributes）
• 日历模式选择（公历或伊斯兰历）
• 日期标题格式选项
• 禁用日期和样式状态

无障碍与全球化

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

• 符合 WCAG 2.2 和 Section 508 标准
• WAI-ARIA 属性和角色
• 键盘导航（方向键、回车、空格、Esc）
• 兼容屏幕阅读器并提供提示
• 本地化和 locale 属性用法
• 日期标题格式变化
• 自定义每周第一天
• 周数和周规则
• 支持 RTL 文本方向

API 参考

📄 阅读： references/api-reference.md

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

快速入门示例

// app.component.ts
import { Component } from '@angular/core';
import { ChangedEventArgs } from '@syncfusion/ej2-datetimepickers';

@Component({
  selector: 'app-root',
  templateUrl: './app.component.html',
  styleUrls: ['./app.component.css']
})
export class AppComponent {
  // Simple datetime value
  dateTimeValue: Date = new Date();
  
  // Configuration
  minDate: Date = new Date(2020, 0, 1);
  maxDate: Date = new Date(2030, 11, 31);
  dateFormat: string = 'dd/MM/yyyy hh:mm a';
  timeFormat: string = 'hh:mm a';
  
  // Event handler
  onDateTimeChange(args: ChangedEventArgs): void {
    console.log('Selected DateTime:', args.value);
    console.log('Event Type:', args.type);
  }
  
  onPopupOpen(): void {
    console.log('Popup opened');
  }
  
  onPopupClose(): void {
    console.log('Popup closed');
  }
}

<div style="padding: 20px;">
  <h2>Select Date & Time</h2>
  
  <ejs-datetimepicker
    id="datetimepicker"
    [value]="dateTimeValue"
    [format]="dateFormat"
    [timeFormat]="timeFormat"
    [min]="minDate"
    [max]="maxDate"
    placeholder="Select date and time"
    (change)="onDateTimeChange($event)"
    (open)="onPopupOpen()"
    (close)="onPopupClose()">
  </ejs-datetimepicker>
  
  <p *ngIf="dateTimeValue">
    Selected: {{ dateTimeValue | date:'medium' }}
  </p>
</div>

常见模式

模式 1：日期时间范围选择

为预约、预订或活动选择开始和结束日期时间：

export class AppComponent {
  startDateTime: Date = new Date();
  endDateTime: Date = new Date(Date.now() + 3600000); // +1 hour
  
  onStartChange(args: ChangedEventArgs): void {
    // Ensure end is after start
    if (this.endDateTime <= args.value) {
      this.endDateTime = new Date((args.value as Date).getTime() + 3600000);
    }
  }
}

模式 2：仅限营业时间

将时间选择限制在营业时间内（上午 9 点至下午 5 点）：

export class AppComponent {
  minTime: Date = new Date(2026, 2, 24, 9, 0);  // 9:00 AM
  maxTime: Date = new Date(2026, 2, 24, 17, 0); // 5:00 PM
  
  datetimeValue: Date = new Date(2026, 2, 24, 10, 0);
}

<ejs-datetimepicker
  [value]="datetimeValue"
  [minTime]="minTime"
  [maxTime]="maxTime"
  timeFormat="hh:mm a">
</ejs-datetimepicker>

模式 3：通过掩码输入引导填写

使用掩码输入引导用户填写日期时间格式：

export class AppComponent {
  datetimeValue: Date;
  maskPlaceholder = {
    day: 'dd',
    month: 'mm',
    year: 'yyyy',
    hour: 'hh',
    minute: 'mm',
    second: 'ss'
  };
}

<ejs-datetimepicker
  [value]="datetimeValue"
  [enableMask]="true"
  [maskPlaceholder]="maskPlaceholder"
  format="dd/MM/yyyy hh:mm:ss">
</ejs-datetimepicker>

模式 4：响应式表单集成

将 datetimepicker 与 Angular 响应式表单集成：

import { FormBuilder, FormGroup, Validators } from '@angular/forms';

export class AppComponent {
  appointmentForm: FormGroup;
  
  constructor(private fb: FormBuilder) {
    this.appointmentForm = this.fb.group({
      appointmentDateTime: [
        new Date(),
        [Validators.required]
      ]
    });
  }
  
  submitForm(): void {
    if (this.appointmentForm.valid) {
      console.log(this.appointmentForm.value);
    }
  }
}

<form [formGroup]="appointmentForm">
  <ejs-datetimepicker
    formControlName="appointmentDateTime"
    format="dd/MM/yyyy hh:mm a">
  </ejs-datetimepicker>
  
  <button (click)="submitForm()" [disabled]="!appointmentForm.valid">
    Submit
  </button>
</form>

模式 5：禁用日期

禁用周末和指定日期：

export class AppComponent {
  datetimeValue: Date;
  
  onRenderDayCell(args: RenderDayCellEventArgs): void {
    // Disable weekends (0 = Sunday, 6 = Saturday)
    if ((args.date as Date).getDay() === 0 || (args.date as Date).getDay() === 6) {
      args.isDisabled = true;
    }
    
    // Disable specific dates
    const disabledDates = [5, 15, 25]; // 5th, 15th, 25th of each month
    if (disabledDates.includes((args.date as Date).getDate())) {
      args.isDisabled = true;
    }
  }
}

<ejs-datetimepicker
  [value]="datetimeValue"
  (renderDayCell)="onRenderDayCell($event)">
</ejs-datetimepicker>

关键属性参考

属性	类型	用途
value	Date	双向绑定的已选日期时间值
format	string	日期显示格式（例如，'dd/MM/yyyy hh:mm a'）
timeFormat	string	弹出窗口中的时间显示格式（例如，'hh:mm a'）
min	Date	可选的最早日期
max	Date	可选的最晚日期
minTime	Date	可选的最早时间
maxTime	Date	可选的最晚时间
step	number	时间间隔（分钟）（15、30、60）
enabled	boolean	启用/禁用组件
readonly	boolean	将输入设为只读（仅从弹出窗口选择）
placeholder	string	输入框中的占位文本
enableMask	boolean	启用掩码输入模式
strictMode	boolean	仅允许有效值
enableRtl	boolean	支持从右到左的语言
enablePersistence	boolean	页面重新加载后保留值
start	CalendarView	初始日历视图（月/年/十年）
depth	CalendarView	日历视图的最高级别
locale	string	格式化所用的区域设置（例如，'en-US'、'de-DE'）

常见用例

预约系统

• 使用日期范围选择，并限制在营业时间内
• 根据最早/最晚时间显示可用时段
• 使用必填验证器处理表单验证
• 显示已选日期时间确认信息

活动安排

• 选择活动的开始和结束日期时间
• 使用 renderDayCell 禁用周末日期
• 使用常用时长的步长间隔（30、60 分钟）
• 格式化输出，以便提交到 API

班次管理

• 选择班次的开始和结束时间
• 应用班次时间限制（最早/最晚时间）
• 处理日期切换（跨午夜的班次）
• 支持多个时区偏移量

账单与发票

• 选择发票日期和时间
• 仅允许选择过去的日期
• 按用户所在地区的格式显示
• 使用 ISO 格式导出

后续步骤

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

---

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