harmonyOS6 opacity 透明度通用属性使用指南
文章目录
一、属性概述
opacity 是HarmonyOS ArkTS框架中的通用属性，用于设置组件的透明度，支持所有可显示的UI组件。该属性取值范围为 [0, 1]，超出范围会自动修正为边界值；API 18及以上版本支持传入 undefined，可恢复组件默认透明度（不透明）。
核心特性
- 透明度取值：
0（完全透明）~1（完全不透明）； - 父子组件透明度会叠加计算：最终透明度 = 父组件透明度 × 子组件透明度；
- 透明度为0时，组件仅视觉不可见，仍占据布局空间，与
visibility属性区分； - 支持
number类型和Resource资源类型传参； - API 18+ 支持
undefined，可重置为默认透明度。
二、适用环境
- 支持API版本：基础功能 API 7+，
undefined特性 API 18+； - 适配设备：手机、平板、二合一设备、PC、智慧屏、穿戴设备等全设备类型。
三、语法定义
1. 基础语法
opacity(value:number| Resource |undefined):void2. 参数说明
| 参数类型 | 说明 |
|---|---|
| number | 透明度数值，范围 [0, 1]，超出范围自动修正 |
| Resource | 资源文件定义的透明度值（float 类型资源） |
| undefined | 仅API 18+支持，重置为默认透明度（1） |
四、完整使用示例
基于官方规范，提供可直接运行的ArkTS代码示例，覆盖基础取值、父子叠加、API 18+新特性三大核心场景：
// OpacityCompleteExample.ets @Entry @Component struct OpacityCompleteExample { // 定义API18+测试的可选透明度值 @State optionalOpacity: Optional<number> = undefined; build() { Column({ space: 20 }) { // 区域1：基础透明度取值展示 Text('基础透明度取值(0~1)').fontSize(16).fontWeight(FontWeight.Bold).width('90%') Column({ space: 8 }) { this.createOpacityItem(1, '不透明(1)') this.createOpacityItem(0.7, '半透明(0.7)') this.createOpacityItem(0.4, '低透明度(0.4)') this.createOpacityItem(0.1, '微透明(0.1)') this.createOpacityItem(0, '完全透明(0，占位不显示)') this.createOpacityItem(1.5, '超出上限(1.5→自动修正为1)') this.createOpacityItem(-0.3, '超出下限(-0.3→自动修正为0)') }.width('90%') // 区域2：父子组件透明度叠加 Text('父子组件透明度叠加').fontSize(16).fontWeight(FontWeight.Bold).width('90%').margin(10) Column({ space: 10 }) { Text('子组件无单独设置(继承父0.3)').fontColor(Color.White).fontSize(12) Text('子组件设置0.8(实际0.3*0.8=0.24)').fontColor(Color.White).fontSize(12).opacity(0.8) } .alignItems(HorizontalAlign.Center) .width('90%') .height(120) .backgroundColor(0x1E90FF) .opacity(0.3) .justifyContent(FlexAlign.Center) // 区域3：API18+ undefined 恢复透明度 Text('API18+：undefined恢复默认透明度').fontSize(16).fontWeight(FontWeight.Bold).width('90%').margin(10) Column({ space: 10 }) { Text('可选透明度值测试').fontColor(Color.White).fontSize(14) Text(`当前值：${this.optionalOpacity ?? 'undefined'}`).fontColor(Color.White).fontSize(12) .opacity(this.optionalOpacity) Button('切换为0.5') .width(120) .onClick(() => { this.optionalOpacity = 0.5; }) Button('恢复为undefined') .width(120) .onClick(() => { this.optionalOpacity = undefined; }) } .alignItems(HorizontalAlign.Center) .width('90%') .height(150) .backgroundColor(0xFF6347) .justifyContent(FlexAlign.Center) } .width('100%') .height('100%') .padding(20) .backgroundColor(0xF5F5F5) } // 封装透明度展示项 @Builder createOpacityItem(opacityValue: number, desc: string) { Column({ space: 4 }) { Text(desc).fontSize(10).fontColor(0x666666).width('100%') Text('') .width('100%') .height(40) .backgroundColor(0xAFEEEE) .opacity(opacityValue) } } } 运行效果如图：
五、场景说明
场景1：基础透明度取值
opacity(1)：组件完全不透明，为默认状态；opacity(0.5)：组件半透明，视觉效果柔和；opacity(0)：组件完全透明，仅隐藏视觉效果，保留布局占位；- 非法取值：
1.5自动修正为1，-0.3自动修正为0。
场景2：父子组件透明度叠加
- 父组件设置透明度后，未单独设置透明度的子组件会继承父组件透明度；
- 子组件单独设置透明度时，最终透明度为父子透明度相乘；
- 示例：父透明度
0.3+ 子透明度0.8= 最终透明度0.24。
场景3：API 18+ undefined 重置透明度
- 当透明度值设置为
undefined时，组件会恢复为默认不透明状态； - 适用于动态切换透明度的场景，无需手动赋值为
1。
总结
opacity 是HarmonyOS开发中高频使用的视觉属性，通过简单的数值配置即可实现组件透明效果，支持基础取值、父子叠加、动态重置等核心能力。遵循官方规范使用该属性，可保证全设备、全版本的兼容性，适用于UI美化、交互动效等开发场景。
如果这篇文章对你有帮助，欢迎点赞、收藏、关注，你的支持是持续创作的动力！
