我想做的效果很简单：底悬浮栏是胶囊或圆形样式，列表从它底下滚过去的时候，胶囊上能透出下面内容的颜色，并在边缘折射，也就是很多原生鸿蒙HAP自带的光感视效，Wow，Amazing~

依旧DevEco Studio 26.0.0.851，SDK API 26，真机 SGT-AL10，HarmonyOS 7.0.0.109

下面所有结论都是这台机器上跑出来的，模拟器上有些表现会不一样。

 是我第一个想到的。它确实会把背后的东西糊掉，但只糊不染色。浅色底上看着跟一块半透明白塑料没区别，列表滚过去，胶囊还是那个胶囊，颜色一点没动。

。文档写得很像正解，任何组件都能挂。真机上它渲染成了一层几乎全透明的白，同时把组件的 backgroundColor、border、shadow 全接管了，最后什么都没画出来。卡片边界直接消失。我盯着屏幕看了半天，以为是自己参数给错了。

 的 titleBar 材质。它只覆盖标题栏那一条，标题栏还是浮层，内容不给它占位，实际效果是压着内容，还顶穿状态栏。

 打开之后，内容会延伸到 bar 底下，再配上 

 这一行不能省。不写它，胶囊会变成贴在内容下面的实心条，材质挂上去也看不出任何效果，因为底下根本没有东西可透。

import {
  HdsTabs, HdsTabsController, SystemMaterialParams, hdsMaterial
} from '@kit.UIDesignKit';

private tabCtl: HdsTabsController = new HdsTabsController();
private barMat: SystemMaterialParams = {
  materialType: hdsMaterial.MaterialType.ADAPTIVE,
  materialLevel: hdsMaterial.MaterialLevel.ADAPTIVE
};

// build 里
HdsTabs({ barPosition: BarPosition.End, controller: this.tabCtl }) {
  TabContent() {
    List() { /* ... */ }
      .contentStartOffset(this.barH() + 6)
      .contentEndOffset(130)
  }
  .tabBar(new BottomTabBarStyle({
    normal: new SymbolGlyphModifier($r('sys.symbol.ellipsis_message_1')),
    selected: new SymbolGlyphModifier($r('sys.symbol.ellipsis_message_1'))
  }, '会话'))
}
.barOverlap(true)
.barFloatingStyle({
  barSideMargin: 10,
  barBottomMargin: 16,
  systemMaterialEffect: this.barMat
})

材质参数我先按系统自适应写的。

，跟着设备算力和系统三档走，不用自己写死。

 的注释只有一句 follow system material level policy，具体按什么规则降档我没测出来，只知道这么写换机器不用改代码。

两个 margin 管胶囊离左右边和底部的距离。10 和 16 是我照着系统底部导航比着写的，没有严格设计依据，你按自己界面调。内容区还得让位，

 给胶囊留 130。不让位的话，列表最后几项永远压在胶囊底下，滚到底也点不到。

 会报 missing 219 properties。还有状态字段别叫 

效果出来了，但深色壁纸上胶囊底部有一圈白毛边，整块材质像被一层白色磨砂塑料盖住。

我当时的判断很明确，材质类型选错了。ADAPTIVE 跟着系统三档走，深色背景下它自适应成了白磨砂，换成 IMMERSIVE 应该就正常。

到这一步我才开始怀疑问题不在材质上。两种材质表现完全不同，但都不对，说明还有第三个东西在参与。我去翻 

。文档原文写的是，不设置高度的话，蒙版高度取组件高度加 32vp。

也就是说，HdsTabs 默认会在胶囊底下垫一层渐变蒙版。这层蒙版挡在玻璃和壁纸之间，把颜色吃掉了。深色壁纸透过它显白，浅色壁纸透出来发灰，底部那一圈就是蒙版的边缘。

材质是无辜的。我换成 IMMERSIVE 之后光感全灭，是因为蒙版一直还在，换了材质只是又少掉一层本来就不厚的透明感。

把蒙版颜色设成透明就解决了。

import { HdsTabsBackgroundStyle } from '@kit.UIDesignKit';

.barFloatingStyle({
  barSideMargin: 10,
  barBottomMargin: 16,
  systemMaterialEffect: this.barMat,        // 材质回到 ADAPTIVE
  gradientMask: { maskColor: Color.Transparent }
})

这一处改完，白毛边没了，材质也回去了。

材质参数决定玻璃有多透明、边缘怎么过渡，它决定不了玻璃上出现什么颜色。颜色只能来自背后滑过去的内容。背景是纯色，透出来还是纯色。背后没有东西滚过，再好的材质也只能透出一片白。

所以背景层得有色彩密度。我用的是几团色斑，半径控制在 300 以内，透明度不超过 0.35，blur 给到 66 到 78。太小太浓会糊成一坨污渍，太大太淡则透不出颜色。这两个边界我都踩过，中间那一版被骂过「背景改得乱七八糟」。

浅色主题下系统玻璃天生就淡，这是系统行为，不是参数没调对。想要强对比，先切深色模式，或者让背后本身就有高饱和的内容。官方示例图能那么透，是因为它背后压着的是一张游戏画面。

现在这套东西在真机上跑着，胶囊滑动时会跟着卡片变色。

回头看，整件事的转折点是我换完 IMMERSIVE、发现光感全灭的那一刻。之前所有时间都花在挑材质类型上，而挡住光感的其实是那层我一直没看见的蒙版。

SDK 里这种带默认值的兜底设计不少。它们平时帮你把界面撑住，一旦视觉效果不对，它们也是第一个该被怀疑的对象。

光感视效的正确打开方式

一个直连自有 HTTP 服务的鸿蒙 App，在 curl 里全部正常，装到真机却连撞仨坑。http 请求莫名返回 501，DELETE 在本地抛 401，bindSheet 点了没反应。三个坑代码层面都看不出问题。本文记录每个坑的定位路径、根因与可复用修复代码

软件测试工程师

编程语言

在HarmonyOS真机上实现底部悬浮胶囊的光感视效，关键在于正确配置HdsTabs的barOverlap(true)与barFloatingStyle。核心坑点是默认gradientMask蒙版会阻挡透出效果，需将maskColor设为透明。材质选ADAPTIVE类型配合透明蒙版，内容区通过contentEndOffset预留130vp，背景用高饱和色斑可增强透色效果。

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

在HarmonyOS真机上实现底部悬浮胶囊的光感视效，关键在于正确配置HdsTabs的barOverlap(true)与barFloatingStyle。核心坑点是默认gradientMask蒙版会阻挡透出效果，需将maskColor设为透明。材质选ADAPTIVE类型配合透明蒙版，内容区通过contentEndOff...

光感视效的正确打开方式

光感视效的正确打开方式

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐