DevUI 是一个基于 Angular（^18.0.0）的企业级前端组件库，其设计价值观强调高效、开放、可信、乐趣。其中的 TimePicker（时间选择器）组件是一个用于输入或选择时间的重要控件，广泛应用于各种中后台管理系统。本文将以官方演示代码为基础，详细解析 TimePicker 的核心功能、使用方法和代码实现。

1. 组件概述与核心价值

TimePicker 组件允许用户通过直观的界面选择或输入特定的时间点。它源自华为内部大量业务的多年沉淀，旨在满足企业级应用对灵活性、易用性和可配置性的高要求。

该组件支持双向数据绑定、时间格式化、自定义模板等高级特性，并能与 Angular 的表单体系无缝集成，是构建复杂数据录入界面的得力工具。

2. 基本使用示例

TimePicker 提供了三种基础的使用模式，涵盖了最常见的业务场景。

2.1 基础用法

最基本的 TimePicker 包含一个输入框和右侧的时间图标按钮。

<section>
  <div class="row">
    <h5>basic</h5>
    <div class="col-md-6">
      <div class="devui-input-group devui-dropdown-origin" dActiveFormControl>
        <input
          class="devui-input devui-form-control"
          placeholder="y-MM-dd"
          autocomplete="off"
          dTimePicker
          [(ngModel)]="selectedTime1"
          (click)="timePicker1.toggle()"
          #timePicker1="timePicker"
          (selectedTimeChange)="timeChange($event)"
          (ngModelChange)="modelChange($event)"
          [timePickerWidth]="250"
        />
        <div *ngIf="selectedTime1" class="devui-input-group-addon close-icon-wrapper" (click)="timePicker1.clearAll()">
          <i class="icon icon-close"></i>
        </div>
        <div class="devui-input-group-addon" (click)="timePicker1.toggle()">
          <i class="icon icon-time"></i>
        </div>
      </div>
    </div>
  </div>
  <div class="row">
    <h5>default open</h5>
    <div class="col-md-6">
      <div class="devui-input-group devui-dropdown-origin" dActiveFormControl>
        <input
          class="devui-input devui-form-control"
          placeholder="y-MM-dd"
          autocomplete="off"
          dTimePicker
          [(ngModel)]="selectedTime2"
          (click)="timePicker2.toggle()"
          #timePicker2="timePicker"
          (selectedTimeChange)="timeChange($event)"
          (ngModelChange)="modelChange($event)"
          [autoOpen]="true"
        />
        <div *ngIf="selectedTime2" class="devui-input-group-addon close-icon-wrapper" (click)="timePicker2.clearAll()">
          <i class="icon icon-close"></i>
        </div>
        <div class="devui-input-group-addon" (click)="timePicker2.toggle()">
          <i class="icon icon-time"></i>
        </div>
      </div>
    </div>
  </div>
  <div class="row">
    <h5>disabled</h5>
    <div class="col-md-6">
      <div class="devui-input-group devui-dropdown-origin devui-disabled">
        <input
          class="devui-input devui-form-control"
          placeholder="y-MM-dd"
          autocomplete="off"
          dTimePicker
          [(ngModel)]="selectedTime3"
          (click)="timePicker3.toggle()"
          #timePicker3="timePicker"
          (selectedTimeChange)="timeChange($event)"
          (ngModelChange)="modelChange($event)"
          [attr.disabled]="true"
          [disabled]="true"
        />
        <div *ngIf="selectedTime3" class="devui-input-group-addon close-icon-wrapper" (click)="timePicker3.clearAll()">
          <i class="icon icon-close"></i>
        </div>
        <div class="devui-input-group-addon" (click)="timePicker3.toggle()">
          <i class="icon icon-time"></i>
        </div>
      </div>
    </div>
  </div>
</section>

ts代码

import { Component } from '@angular/core';

@Component({
  selector: 'd-basic-demo',
  styleUrls: ['./basic.component.scss'],
  templateUrl: './basic.component.html'
})
export class BasicComponent {
  selectedTime1;
  selectedTime2 = '22:32:58';
  selectedTime3;

  timeChange($event) {
    console.log('change', $event);
  }

  modelChange($event) {
    console.log('model', $event);
  }
}

css代码

.devui-input-group {
  width: 184px;
}

.devui-input-group-addon {
  cursor: pointer;
  vertical-align: middle;

  .icon {
    vertical-align: middle;
  }
}

.close-icon-wrapper {
  padding: 0;
}

关键代码解析：

• dTimePicker 指令：这是核心指令，用于将普通输入框转换为时间选择器。
• [(ngModel)]="selectedTime1"：Angular 的双向数据绑定，将输入框的值与组件类中的 selectedTime1 属性同步。
• #timePicker1="timePicker"：模板引用变量，可通过它调用时间选择器实例的方法（如 toggle()、clearAll()）。
• [timePickerWidth]="250"：设置时间选择面板的宽度为 250 像素。

2.2 默认打开状态

有时我们希望时间选择器在页面加载或获得焦点时自动展开面板。

<input
  dTimePicker
  [(ngModel)]="selectedTime2"
  #timePicker2="timePicker"
  [autoOpen]="true" <!-- 核心属性：控制自动展开 -->
/>

通过设置 [autoOpen]="true" 属性，时间选择面板将在组件初始化后自动展开，无需用户点击，提升了操作效率。

2.3 禁用状态

在某些业务逻辑下（如查看模式、条件禁用），需要禁止用户操作时间选择器。

<div class="devui-input-group devui-dropdown-origin devui-disabled">
  <input
    ...
    dTimePicker
    [(ngModel)]="selectedTime3"
    #timePicker3="timePicker"
    [attr.disabled]="true" <!-- HTML标准disabled属性 -->
    [disabled]="true" <!-- Angular指令disabled状态 -->
  />
  ...
</div>

实现方式：

1. 在包裹容器上添加 devui-disabled 类，实现视觉上的禁用样式。
2. 在 input 元素上同时设置 [attr.disabled]="true" 和 [disabled]="true"，前者是 HTML 标准属性，后者是 Angular 指令对禁用状态的控制。

3. 进阶功能与配置

3.1 时间格式化与范围限制

在实际业务中，我们经常需要控制时间的显示格式以及可选时间范围。

<!-- 格式选择器 -->
<div class="input-group">
  <d-select [(ngModel)]="format" [options]="formatOptions"></d-select>
</div>

<!-- 时间选择器 -->
<input
  ...
  dTimePicker
  [(ngModel)]="selectedTime1"
  #timePicker1="timePicker"
  [format]="format" <!-- 动态绑定时间格式 -->
  [minTime]="'10:23:34'" <!-- 设置可选最小时间 -->
  [maxTime]="'22:30:56'" <!-- 设置可选最大时间 -->
/>

组件类中的相关代码：

// 时间格式选项
formatOptions = [
  { label: 'HH:mm:ss', value: 'HH:mm:ss' },
  { label: 'hh:mm:ss a', value: 'hh:mm:ss a' },
  { label: 'HH时mm分ss秒', value: 'HH时mm分ss秒' }
];

// 当前选中的格式
format = 'HH:mm:ss';

// 时间变化处理函数
timeChange(event) {
  console.log('选择的时间已改变：', event);
}

modelChange(event) {
  console.log('模型数据已更新：', event);
}

核心属性说明：

• [format]：控制时间的显示格式。支持多种格式字符串，如 HH:mm:ss（24小时制）、hh:mm:ss a（12小时制带上午/下午标识）。
• [minTime] 和 [maxTime]：分别设置用户可选择的最小和最大时间。超出此范围的时间将被禁用，无法选择。

3.2 自定义视图模板

对于高度定制化的需求，TimePicker 提供了强大的模板自定义功能。

<!-- 时间选择器，接入自定义模板 -->
<input
  ...
  dTimePicker
  [(ngModel)]="selectedTime1"
  #timePicker1="timePicker"
  [customViewTemplate]="myCustomView" <!-- 绑定自定义模板 -->
/>

<!-- 自定义模板定义 -->
<ng-template #myCustomView 
             let-chooseTime="chooseTime" 
             let-confirmTime="confirmTime" 
             let-hide="hide" 
             let-timePicker>
  <!-- "选择当前时间"链接 -->
  <a class="devui-link" (click)="choose(timePicker1)">choose now</a>
  <br />
  <!-- "选择22:00"链接 -->
  <a class="devui-link" (click)="confirmTime({ time: '22', type: 'hh' })">choose 22:00</a>
</ng-template>

组件类中的处理函数：

// 选择当前时间
choose(timePickerInstance) {
  const now = new Date();
  const timeString = `${now.getHours()}:${now.getMinutes()}:${now.getSeconds()}`;
  timePickerInstance.chooseTime(timeString);
}

// 模板上下文说明：
// - chooseTime: 函数，用于触发时间选择
// - confirmTime: 函数，用于确认选择特定时间
// - hide: 函数，用于隐藏时间选择面板
// - timePicker: 时间选择器组件实例

自定义模板的优势：

1. 业务逻辑封装：可以将特定的时间选择逻辑（如"选择当前时间"、“选择整点”）直接集成到时间选择器中。
2. 界面定制自由：完全控制时间选择面板的部分或全部显示内容。
3. 上下文数据传递：通过模板变量可以获取时间选择器的状态和方法，实现深度交互。

4. 核心 API 与事件详解

4.1 输入属性（Input Properties）

属性名	类型	默认值	说明
format	string	'HH:mm:ss'	时间显示格式
minTime	string	-	允许选择的最小时间
maxTime	string	-	允许选择的最大时间
autoOpen	boolean	false	是否自动展开时间选择面板
disabled	boolean	false	是否禁用时间选择器
timePickerWidth	number	-	时间选择面板的宽度
customViewTemplate	TemplateRef	-	自定义视图模板

4.2 输出事件（Output Events）

事件名	返回值类型	触发时机
selectedTimeChange	string	用户选择时间后触发
ngModelChange	string	模型值发生变化时触发

4.3 组件实例方法

通过模板引用变量可调用的方法：

• toggle()：切换时间选择面板的展开/收起状态
• clearAll()：清除当前选择的时间值

5. 使用建议与最佳实践

1. 格式统一：在整个应用中保持时间格式的一致性，避免不同页面使用不同的时间格式。

2. 范围验证：对于有业务时间限制的场景（如营业时间），务必使用 minTime 和 maxTime 属性，提供明确的视觉反馈。

3. 移动端适配：在移动设备上，时间选择器会自动优化交互方式，但建议在真机上进行测试。

4. 无障碍访问：确保为时间选择器提供清晰的标签（label）和说明，方便辅助技术用户理解和使用。

5. 性能考虑：在大型表单或多实例场景中，注意监听函数的性能影响，必要时使用防抖或节流技术。

6. 总结

DevUI 的 TimePicker 组件是一个功能全面、配置灵活的时间选择解决方案。它既提供了开箱即用的基础功能，又通过自定义模板等特性支持深度定制，完美契合企业级应用对稳定性和灵活性的双重需求。

无论是简单的单时间点选择，还是复杂的带范围限制和自定义交互的时间选择场景，TimePicker 都能提供优雅的解决方案。结合 DevUI 设计体系的高效、开放理念，该组件能显著提升开发效率和用户体验。

参考文档

MateChat ：https://gitcode.com/DevCloudFE/MateChat

MateChat 官网 ：https://matechat.gitcode.com

DevUI官网：https://devui.design/home