HarmonyOS WindowUtil 窗口背景色设置：setWindowBackgroundColor 颜色格式与透明效果详解

文章目录

• • 背景
  • • 方法总览
    • setWindowBackgroundColor — 设置窗口背景色
    • 颜色格式说明
    • 透明窗口的应用场景
    • setWindowBackgroundColor 是同步方法
    • 和 isTransparent() 配合使用
    • 实际使用建议
    • 写在最后

背景

近期发现一款很有意思的HarmonyOS 三方库, 地址 @pura/harmony-utils(V1.4.0) , 作者是"桃花镇童长老", 我这里也是直接通过该作者公布的源码进行案例编写进行,写了到目前写了一部分demo ,感觉确实很有帮助,这里呢也是开始写一个系列的演示demo 供大家参考。如有帮助可以在OpenHarmony中进行下载安装进行使用哦

案例demo导航展示

↓↓↓↓↓↓接下来言归正传 ↓↓↓

做 HarmonyOS 应用的时候，有时候需要让窗口背景色和页面内容完美融合，或者做半透明、全透明效果的弹窗。

WindowUtil.setWindowBackgroundColor() 专门处理这个需求。

方法总览

setWindowBackgroundColor — 设置窗口背景色

// 设置白色背景
Button('#FFFFFFFF').layoutWeight(1).height(36).fontSize(12).fontColor('#333')
.backgroundColor('#FFFFFFFF').borderRadius(6)
.onClick(() => {
try {
WindowUtil.setWindowBackgroundColor('#FFFFFFFF');
this.addLog('setWindowBackgroundColor("#FFFFFFFF")');
} catch (e) { this.addLog(`Error: ${e}`); }
})

// 设置深色背景
Button('#FF2C3E50').layoutWeight(1).height(36).fontSize(12).fontColor('#fff')
.backgroundColor('#2C3E50').borderRadius(6)
.onClick(() => {
try {
WindowUtil.setWindowBackgroundColor('#FF2C3E50');
this.addLog('setWindowBackgroundColor("#FF2C3E50") 深色');
} catch (e) { this.addLog(`Error: ${e}`); }
})

// 设置全透明背景
Button('#00000000').layoutWeight(1).height(36).fontSize(12).fontColor('#333')
.backgroundColor('#F0F0F0').borderRadius(6).border({ width: 1, color: '#ddd' })
.onClick(() => {
try {
WindowUtil.setWindowBackgroundColor('#00000000');
this.addLog('setWindowBackgroundColor("#00000000") 全透明');
} catch (e) { this.addLog(`Error: ${e}`); }
})

颜色格式说明

setWindowBackgroundColor 接受 #AARRGGBB 格式的颜色字符串：

常用颜色值速查：

透明窗口的应用场景

设置 #00000000（全透明）后，窗口背景完全透明，可以看到后面的内容。

这在以下场景很有用：

• 悬浮窗：窗口内容悬浮在其他应用上方，背景不遮挡
• 弹窗效果：结合遮罩层做自定义弹窗
• 动画过渡：页面切换动画时临时透明

setWindowBackgroundColor 是同步方法

注意这个方法是同步的，不需要 .then()：

try {
WindowUtil.setWindowBackgroundColor('#FFFFFFFF');
// 执行到这里说明设置成功
} catch (e) {
// 设置失败，比如颜色格式不对
console.error('设置背景色失败:', e);
}

如果传入的颜色格式不正确，会抛出异常，所以记得包 try/catch。

和 isTransparent() 配合使用

设置透明背景后，可以用 isTransparent() 验证：

// 先设置透明
WindowUtil.setWindowBackgroundColor('#00000000');

// 再查询是否透明
try {
this.addLog(`isTransparent() → ${WindowUtil.isTransparent()}`);
} catch (e) {
this.addLog(`Error: ${e}`);
}

实际使用建议

1. 亮色/暗色模式适配

// 根据系统主题设置背景色
const isDarkMode = (getContext() as common.UIAbilityContext).config.colorMode ===
ConfigurationConstant.ColorMode.COLOR_MODE_DARK;

if (isDarkMode) {
WindowUtil.setWindowBackgroundColor('#FF1A1A2E');
} else {
WindowUtil.setWindowBackgroundColor('#FFFFFFFF');
}

2. 页面切换时的背景色

有些页面需要特殊背景色（比如深色视频播放页），进入时设置，离开时恢复：

aboutToAppear() {
try {
WindowUtil.setWindowBackgroundColor('#FF000000'); // 黑色背景
} catch (e) {}
}

aboutToDisappear() {
try {
WindowUtil.setWindowBackgroundColor('#FFFFFFFF'); // 恢复白色
} catch (e) {}
}

写在最后

setWindowBackgroundColor 看起来简单，但颜色格式容易记混。

记住关键点：格式是 #AARRGGBB，AA 是透明度，FF=不透明，00=全透明。

全透明 #00000000 是最常用的特殊值，用于做悬浮效果；白色 #FFFFFFFF 是默认值，深色 #FF000000 或 #FF1A1A2E 用于暗色主题页面。