TextClock
TextClock组件通过文本将当前系统时间显示在设备上。支持不同时区的时间显示,最高精度到秒级。
说明:
该组件从API Version 8开始支持。后续版本如有新增内容,则采用上角标单独标记该内容的起始版本。
子组件
无
接口
TextClock(options?: { timeZoneOffset?: number, controller?: TextClockController })
卡片能力: 从API version 11开始,该接口支持在ArkTS卡片中使用。
原子化服务API: 从API version 11开始,该接口支持在原子化服务中使用。
系统能力: SystemCapability.ArkUI.ArkUI.Full
参数:
参数名 | 参数类型 | 必填 | 参数描述 |
---|---|---|---|
timeZoneOffset | number | 否 | 设置时区偏移量。 取值范围为[-14, 12],表示东十二区到西十二区,其中负值表示东时区,正值表示西时区,比如东八区为-8。设置值为该取值范围内的浮点数时会进行取整,舍弃小数部分。 对横跨国际日界线的国家或地区,用-13(UTC+13)和-14(UTC+14)来保证整个国家或者区域处在相同的时间,当设置的值不在取值范围内时,将使用当前系统的时区偏移量。 默认值:当前系统的时区偏移量 从API version 11开始,设置值为{ 9.5, 3.5, -3.5, -4.5, -5.5, -5.75, -6.5, -9.5, -10.5, -12.75 }集合中的浮点数时不再进行取整。 |
controller | TextClockController | 否 | 绑定一个控制器,用来控制文本时钟的状态。 |
属性
除支持通用属性和文本通用属性的fontColor、fontSize、fontStyle、fontWeight、fontFamily外,还支持以下属性:
format
format(value: string)
设置显示时间格式,如“yyyy/mm/dd”、“yyyy-mm-dd”。
y:年(yyyy表示完整年份,yy表示年份后两位)
M:月(若想使用01月则使用MM)
d:日(若想使用01日则使用dd)
E:星期(若想使用星期六则使用EEEE,若想使用周六则使用E、EE、EEE)H:小时(24小时制) h:小时(12小时制)
m:分钟
s:秒
SS:厘秒(format中S个数<3,全部按厘秒处理)
SSS:毫秒(format中S个数>=3,全部按毫秒处理)
a:上午/下午(当设置小时制式为H时,该参数不生效)
日期间隔符:“年月日”、“/”、“-”、“.”(可以自定义间隔符样式,间隔符不可以为字母,汉字则作为间隔符处理)
允许自行拼接组合显示格式,即:年、月、日、星期、时、分、秒、毫秒可拆分为子元素,可自行排布组合。时间更新频率最高为一秒一次,不建议单独设置厘秒和毫秒格式。
当设置无效字母时(非上述字母被认为是无效字母),该字母会被忽略。如果format全是无效字母时,显示格式跟随系统语言和系统小时制。例如系统语言为中文时,12小时制显示格式为yyyy/MM/dd aa hh:mm:ss.SSS,24小时制显示格式为yyyy/MM/dd HH:mm:ss.SSS。
若format为空或者undefined,则使用默认值。
非卡片中默认值:12小时制:aa hh:mm:ss,24小时制:HH:mm:ss。
卡片中默认值:12小时制:hh:mm,24小时制:HH:mm 。
卡片中使用时,最小时间单位为分钟。如果设置格式中有秒或厘秒按默认值处理。
卡片能力: 从API version 11开始,该接口支持在ArkTS卡片中使用。
原子化服务API: 从API version 11开始,该接口支持在原子化服务中使用。
系统能力: SystemCapability.ArkUI.ArkUI.Full
参数:
参数名 | 类型 | 必填 | 说明 |
---|---|---|---|
value | string | 是 | 显示时间格式。 |
以下是format输入的格式样式及对应的显示效果:
输入格式 | 显示效果 |
---|---|
yyyy年M月d日 EEEE | 2023年2月4日 星期六 |
yyyy年M月d日 | 2023年2月4日 |
M月d日 EEEE | 2月4日 星期六 |
M月d日 | 2月4日 |
MM/dd/yyyy | 02/04/2023 |
EEEE MM月dd日 | 星期六 02月04日 |
yyyy(完整年份) | 2023年 |
yy(年份后两位) | 23年 |
MM(完整月份) | 02月 |
M(月份) | 2月 |
dd(完整日期) | 04日 |
d(日期) | 4日 |
EEEE(完整星期) | 星期六 |
E、EE、EEE(简写星期) | 周六 |
yyyy年M月d日 | 2023年2月4日 |
yyyy/M/d | 2023/2/4 |
yyyy-M-d | 2023-2-4 |
yyyy.M.d | 2023.2.4 |
HH:mm:ss(时:分:秒) | 17:00:04 |
aa hh:mm:ss(时:分:秒) | 上午 5:00:04 |
hh:mm:ss(时:分:秒) | 5:00:04 |
HH:mm(时:分) | 17:00 |
aa hh:mm(时:分) | 上午 5:00 |
hh:mm(时:分) | 5:00 |
mm:ss(分:秒) | 00:04 |
mm:ss.SS(分:秒.厘秒) | 00:04.91 |
mm:ss.SSS(分:秒.毫秒) | 00:04.536 |
hh:mm:ss aa | 5:00:04 上午 |
HH | 17 |
textShadow11+
textShadow(value: ShadowOptions | Array<ShadowOptions>)
设置文字阴影效果。该接口支持以数组形式入参,实现多重文字阴影。不支持fill字段, 不支持智能取色模式。
卡片能力: 从API version 11开始,该接口支持在ArkTS卡片中使用。
原子化服务API: 从API version 12开始,该接口支持在原子化服务中使用。
系统能力: SystemCapability.ArkUI.ArkUI.Full
参数:
参数名 | 类型 | 必填 | 说明 |
---|---|---|---|
value | ShadowOptions | Array<ShadowOptions> | 是 | 文字阴影效果。 |
fontFeature11+
fontFeature(value: string)
设置文字特性效果,比如数字等宽的特性。
格式为:normal | <feature-tag-value>
<feature-tag-value>的格式为:<string> [ <integer> | on | off ]
<feature-tag-value>的个数可以有多个,中间用’,'隔开。
例如,使用等宽时钟数字的输入格式为:“ss01” on。
卡片能力: 从API version 11开始,该接口支持在ArkTS卡片中使用。
原子化服务API: 从API version 12开始,该接口支持在原子化服务中使用。
系统能力: SystemCapability.ArkUI.ArkUI.Full
参数:
参数名 | 类型 | 必填 | 说明 |
---|---|---|---|
value | string | 是 | 文字特性效果。 |
contentModifier12+
contentModifier(modifier: ContentModifier<TextClockConfiguration>)
定制TextClock内容区的方法。
系统能力: SystemCapability.ArkUI.ArkUI.Full
参数:
参数名 | 类型 | 必填 | 说明 |
---|---|---|---|
modifier | ContentModifier<TextClockConfiguration> | 是 | 在TextClock组件上,定制内容区的方法。 modifier: 内容修改器,开发者需要自定义class实现ContentModifier接口。 |
事件
除支持通用事件外,还支持以下事件:
onDateChange
onDateChange(event: (value: number) => void)
提供时间变化回调,该事件回调间隔为秒。
组件不可见时不回调。
非卡片中使用时,该事件回调间隔为秒。
卡片中使用时,该事件回调间隔为分钟。
卡片能力: 从API version 11开始,该接口支持在ArkTS卡片中使用。
原子化服务API: 从API version 11开始,该接口支持在原子化服务中使用。
系统能力: SystemCapability.ArkUI.ArkUI.Full
参数:
参数名 | 类型 | 必填 | 说明 |
---|---|---|---|
value | number | 是 | Unix Time Stamp,即自1970年1月1日(UTC)起经过的秒数。 |
TextClockController
TextClock容器组件的控制器,可以将该控制器绑定到TextClock组件,通过它控制文本时钟的启动与停止。一个TextClock组件仅支持绑定一个控制器。
卡片能力: 从API version 11开始,该接口支持在ArkTS卡片中使用。
原子化服务API: 从API version 11开始,该接口支持在原子化服务中使用。
系统能力: SystemCapability.ArkUI.ArkUI.Full
导入对象
controller: TextClockController = new TextClockController();
ts
start
start()
启动文本时钟。
卡片能力: 从API version 11开始,该接口支持在ArkTS卡片中使用。
原子化服务API: 从API version 11开始,该接口支持在原子化服务中使用。
系统能力: SystemCapability.ArkUI.ArkUI.Full
stop
stop()
停止文本时钟。
卡片能力: 从API version 11开始,该接口支持在ArkTS卡片中使用。
原子化服务API: 从API version 11开始,该接口支持在原子化服务中使用。
系统能力: SystemCapability.ArkUI.ArkUI.Full
TextClockConfiguration12+对象说明
开发者需要自定义class实现ContentModifier接口。
系统能力: SystemCapability.ArkUI.ArkUI.Full
参数名 | 类型 | 默认值 | 说明 |
---|---|---|---|
timeZoneOffset | number | - | 当前文本时钟时区偏移量。 |
started | boolean | true | 指示文本时钟是否启动。 |
timeValue | number | - | 当前文本时钟时区的UTC秒数。 |
示例
示例1
@Entry
@Component
struct Second {
@State accumulateTime: number = 0
// 导入对象
controller: TextClockController = new TextClockController()
build() {
Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) {
Text('Current milliseconds is ' + this.accumulateTime)
.fontSize(20)
// 以12小时制显示东八区的系统时间,精确到秒。
TextClock({ timeZoneOffset: -8, controller: this.controller })
.format('aa hh:mm:ss')
.onDateChange((value: number) => {
this.accumulateTime = value
})
.margin(20)
.fontSize(30)
Button("start TextClock")
.margin({ bottom: 10 })
.onClick(() => {
// 启动文本时钟
this.controller.start()
})
Button("stop TextClock")
.onClick(() => {
// 停止文本时钟
this.controller.stop()
})
}
.width('100%')
.height('100%')
}
}
ts
示例2
@Entry
@Component
struct TextClockExample {
@State textShadows : ShadowOptions | Array<ShadowOptions> = [{ radius: 10, color: Color.Red, offsetX: 10, offsetY: 0 },{ radius: 10, color: Color.Black, offsetX: 20, offsetY: 0 },
{ radius: 10, color: Color.Brown, offsetX: 30, offsetY: 0 },{ radius: 10, color: Color.Green, offsetX: 40, offsetY: 0 },
{ radius: 10, color: Color.Yellow, offsetX: 100, offsetY: 0 }]
build() {
Column({ space: 8 }) {
TextClock().fontSize(50).textShadow(this.textShadows)
}
}
}
ts
示例3
该示例实现了自定义文本时钟样式的功能,自定义样式实现了一个时间选择器组件:通过文本时钟的时区偏移量与UTC秒数,来动态改变时间选择器的选中值,实现时钟效果。同时,根据文本时钟的启动状态,实现文本选择器的12小时制与24小时制的切换。
class MyTextClockStyle implements ContentModifier<TextClockConfiguration> {
currentTimeZoneOffset: number = new Date().getTimezoneOffset() / 60
title: string = ''
constructor(title: string) {
this.title = title
}
applyContent(): WrappedBuilder<[TextClockConfiguration]> {
return wrapBuilder(buildTextClock)
}
}
@Builder
function buildTextClock(config: TextClockConfiguration) {
Row() {
Column() {
Text((config.contentModifier as MyTextClockStyle).title)
.fontSize(20)
.margin(20)
TimePicker({
selected: (new Date(config.timeValue * 1000 + ((config.contentModifier as MyTextClockStyle).currentTimeZoneOffset - config.timeZoneOffset) * 60 * 60 * 1000)),
format: TimePickerFormat.HOUR_MINUTE_SECOND
})
.useMilitaryTime(!config.started)
}
}
}
@Entry
@Component
struct TextClockExample {
@State accumulateTime1: number = 0
@State timeZoneOffset: number = -8
controller1: TextClockController = new TextClockController()
controller2: TextClockController = new TextClockController()
build() {
Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) {
Text('Current milliseconds is ' + this.accumulateTime1)
.fontSize(20)
.margin({ top: 20 })
TextClock({ timeZoneOffset: this.timeZoneOffset, controller: this.controller1 })
.format('aa hh:mm:ss')
.onDateChange((value: number) => {
this.accumulateTime1 = value
})
.margin(20)
.fontSize(30)
TextClock({ timeZoneOffset: this.timeZoneOffset, controller: this.controller2 })
.format('aa hh:mm:ss')
.fontSize(30)
.contentModifier(new MyTextClockStyle('ContentModifier:'))
Button("start TextClock")
.margin({ top: 20, bottom: 10 })
.onClick(() => {
// 启动文本时钟
this.controller1.start()
this.controller2.start()
})
Button("stop TextClock")
.margin({ bottom: 30 })
.onClick(() => {
// 停止文本时钟
this.controller1.stop()
this.controller2.stop()
})
}
.width('100%')
.height('100%')
}
}
ts
最后
有很多小伙伴不知道学习哪些鸿蒙开发技术?不知道需要重点掌握哪些鸿蒙应用开发知识点?而且学习时频繁踩坑,最终浪费大量时间。所以有一份实用的鸿蒙(HarmonyOS NEXT)资料用来跟着学习是非常有必要的。
这份鸿蒙(HarmonyOS NEXT)资料包含了鸿蒙开发必掌握的核心知识要点,内容包含了(ArkTS、ArkUI开发组件、Stage模型、多端部署、分布式应用开发、音频、视频、WebGL、OpenHarmony多媒体技术、Napi组件、OpenHarmony内核、OpenHarmony南向开发、鸿蒙项目实战等等)鸿蒙(HarmonyOS NEXT)技术知识点。
希望这一份鸿蒙学习资料能够给大家带来帮助,有需要的小伙伴自行领取,限时开源,先到先得~无套路领取!!
获取这份完整版高清学习路线,请点击→纯血版全套鸿蒙HarmonyOS NEXT学习资料
鸿蒙(HarmonyOS NEXT)最新学习路线
-
HarmonOS基础技能
- HarmonOS就业必备技能
- HarmonOS多媒体技术
- 鸿蒙NaPi组件进阶
- HarmonOS高级技能
- 初识HarmonOS内核
- 实战就业级设备开发
有了路线图,怎么能没有学习资料呢,小编也准备了一份联合鸿蒙官方发布笔记整理收纳的一套系统性的鸿蒙(OpenHarmony )学习手册(共计1236页)与鸿蒙(OpenHarmony )开发入门教学视频,内容包含:ArkTS、ArkUI、Web开发、应用模型、资源分类…等知识点。
获取以上完整版高清学习路线,请点击→纯血版全套鸿蒙HarmonyOS NEXT学习资料
《鸿蒙 (OpenHarmony)开发入门教学视频》
《鸿蒙生态应用开发V2.0白皮书》
《鸿蒙 (OpenHarmony)开发基础到实战手册》
OpenHarmony北向、南向开发环境搭建
《鸿蒙开发基础》
- ArkTS语言
- 安装DevEco Studio
- 运用你的第一个ArkTS应用
- ArkUI声明式UI开发
- .……
《鸿蒙开发进阶》
- Stage模型入门
- 网络管理
- 数据管理
- 电话服务
- 分布式应用开发
- 通知与窗口管理
- 多媒体技术
- 安全技能
- 任务管理
- WebGL
- 国际化开发
- 应用测试
- DFX面向未来设计
- 鸿蒙系统移植和裁剪定制
- ……
《鸿蒙进阶实战》
- ArkTS实践
- UIAbility应用
- 网络案例
- ……
获取以上完整鸿蒙HarmonyOS学习资料,请点击→纯血版全套鸿蒙HarmonyOS NEXT学习资料
总结
总的来说,华为鸿蒙不再兼容安卓,对中年程序员来说是一个挑战,也是一个机会。只有积极应对变化,不断学习和提升自己,他们才能在这个变革的时代中立于不败之地。