HarmonyOS 6 TextClock 组件使用文档

TextClock是鸿蒙基础文本时钟组件，用于实时展示系统本地时间，组件内部自动定时刷新，无需手动定时器；
支持自定义时间格式、时区、文字样式、阴影、字体特性，搭配TextClockController可实现时钟手动启动、停止控制，满足首页时间、状态栏时钟、计时展示等业务需求。

完整示例

// xxx.ets @Entry @Component struct TextClockFullDemo { // 控制器：控制时钟启停 private controller: TextClockController = new TextClockController(); // 文字阴影配置 private shadowStyle: ShadowOptions = { radius: 5, color: '#33000000', offsetX: 2, offsetY: 2 }; build() { Column({ space: 15 }) { // 标题 Text("TextClock 完整功能演示") .fontSize(22) .fontWeight(FontWeight.Bold) .margin({ top: 10 }); // 1. 默认样式时钟 Text("1. 默认样式（系统时间）").fontSize(14).fontColor('#666'); TextClock() .fontSize(20); // 2. 自定义时间格式 Text("2. 自定义格式（年月日 星期 时分秒）").fontSize(14).fontColor('#666'); TextClock() .format('yyyy-MM-dd EEEE HH:mm:ss') .fontSize(18); // 3. 12小时制 + 前导零 Text("3. 12小时制（带前导零）").fontSize(14).fontColor('#666'); TextClock() .format('aa hh:mm:ss') .dateTimeOptions({ hour: '2-digit' }) .fontSize(20) .fontColor('#007DFF'); // 4. 24小时制（去掉前导零） Text("4. 24小时制（无前置零）").fontSize(14).fontColor('#666'); TextClock() .format('HH:mm:ss') .dateTimeOptions({ hour: 'numeric' }) .fontSize(20) .fontColor('#FF7D00'); // 5. 字体样式 + 阴影 Text("5. 字体加粗 + 斜体 + 阴影").fontSize(14).fontColor('#666'); TextClock() .format('HH:mm:ss') .fontSize(26) .fontWeight(FontWeight.Bold) .fontStyle(FontStyle.Italic) .textShadow(this.shadowStyle) .fontColor('#182431'); // 6. 控制器启停 + 时间变化回调 Text("6. 启停控制 + 时间监听").fontSize(14).fontColor('#666'); TextClock({ controller: this.controller }) .format('HH:mm:ss') .fontSize(24) .fontColor('#009955') .onDateChange((timestamp: number) => { console.info('当前时间戳（秒）：', timestamp.toString()); }); // 控制按钮 Row({ space: 15 }) { Button('启动时钟') .onClick(() => { this.controller.start(); }) .backgroundColor('#007DFF'); Button('停止时钟') .onClick(() => { this.controller.stop(); }) .backgroundColor('#FF4444'); } // 7. 等宽数字效果（fontFeature） Text("7. 等宽数字时钟（fontFeature）").fontSize(14).fontColor('#666'); TextClock() .format('HH:mm:ss') .fontSize(22) .fontFeature('"ss01" on') .fontColor('#6200EE'); } .width('100%') .padding(15) .backgroundColor('#F5F5F5') .height('100%'); } }

运行效果如图：

核心功能模块解析

1 基础默认用法

不配置任何格式化参数时，TextClock自动跟随系统默认时间格式展示，开箱即用：

TextClock().fontSize(20);

2 format 自定义时间格式

通过format属性自定义时间模板，支持年、月、日、时、分、秒、星期、上/下午标识组合：

• yyyy：四位年份
• MM：两位月份
• dd：日期
• EEEE：完整星期
• HH：24小时制
• hh：12小时制
• aa：上/下午标识

示例：

TextClock().format('yyyy-MM-dd EEEE HH:mm:ss')

3 dateTimeOptions 数字格式化

用于控制时间数字展示规则，常用配置：

• hour: '2-digit'：小时补前导零
• hour: 'numeric'：小时不补零

适配 12小时制、24小时制差异化展示需求。

4 文字样式与阴影定制

复用通用文本类属性，快速美化时钟样式：

• 基础样式：fontSize、fontColor、fontWeight、fontStyle
• 高级样式：textShadow配置文字阴影，增强视觉层次感

5 TextClockController 控制器

通过构造实例绑定组件，实现时钟生命周期控制：

• start()：开启时间自动刷新
• stop()：暂停时间刷新
  适合需要定时开关、页面销毁暂停时钟的业务场景。

6 onDateChange 时间回调

时间每一次刷新都会触发onDateChange回调，返回时间戳，可用于：

• 日志打印时间
• 联动其他组件更新
• 业务时间逻辑判断

7 fontFeature 高级字体特性

通过fontFeature配置字体特性，示例中开启等宽数字，解决时间数字跳动、宽度不一致问题，提升UI美观度。

核心对象与类型说明

1. TextClockController
   时钟控制器，提供启停能力，为组件双向控制核心类。
2. ShadowOptions
   阴影配置对象，包含模糊半径、颜色、X/Y轴偏移量，统一管理文字阴影样式。

运行效果说明

1. 页面垂直排列 7 种不同类型的 TextClock 展示案例；
2. 涵盖默认样式、全量日期时间、12/24小时制、阴影美化、可控时钟、等宽数字；
3. 点击按钮可手动启动/停止时钟刷新；
4. 时间变化实时打印日志，便于调试与二次开发。

总结

1. TextClock是鸿蒙轻量高效的实时时间展示组件，原生自动刷新；
2. 支持格式自定义、样式美化、状态控制、事件监听全场景能力；
3. 示例代码覆盖官方文档主流示例用法，可直接复制到项目中运行复用；
4. 组件扩展性强，可快速集成到首页、个人中心、状态栏等需要展示实时时间的页面。

如果这篇文章对你有帮助，欢迎点赞、收藏、关注，你的支持是持续创作的动力