HarmonyOS6 ArkTS List 设置边缘渐隐
文章目录
- 一、功能概述
- 二、 API
- fadingEdge(value: boolean, option?: FadingEdgeOption)
- 参数说明
- 三、完整可运行代码
- 四、代码核心配置解析
- 1. 开启边缘渐隐
- 2. 配置渐隐长度（官方标准写法）
- 3. 生效规则
- 总结
一、功能概述
边缘渐隐（Fading Edge）是 List 组件的官方视觉增强属性，用于在列表顶部、底部（垂直列表）或左侧、右侧（水平列表）生成自然的渐变透明效果，让列表滚动边界更柔和、更具层次感，避免列表内容生硬截断。
- 核心属性：
fadingEdge - 作用：为 List 滚动边缘添加渐隐效果
- 适用场景：长列表、滚动容器、卡片列表
- 支持版本：API 15+ / HarmonyOS 6
二、 API
fadingEdge(value: boolean, option?: FadingEdgeOption)
为 List 组件开启/关闭边缘渐隐。
参数说明
value: boolean
true：开启边缘渐隐false：关闭边缘渐隐（默认）
option?: FadingEdgeOption（可选配置）
fadingEdgeLength: LengthMetrics：设置渐隐区域长度- 单位推荐使用
LengthMetrics.vp(数值)进行标准化设置
三、完整可运行代码
import { LengthMetrics } from '@kit.ArkUI' import { ListDataSource } from './ListDataSource'; @Entry @Component struct ListExample { private arr: ListDataSource=new ListDataSource([0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11]); scrollerForList: Scroller = new Scroller(); build() { Column() { List({ space: 20, initialIndex: 0, scroller: this.scrollerForList }) { LazyForEach(this.arr, (item: number) => { ListItem() { Text('' + item) .width('100%').height(100).fontSize(16) .textAlign(TextAlign.Center).borderRadius(10).backgroundColor(0xFFFFFF) } }, (item: number) => item.toString()) } .fadingEdge(true, { fadingEdgeLength: LengthMetrics.vp(80) }) } .width('100%') .height('100%') .backgroundColor(0xDCDCDC) .padding({ top: 5 }) } }运行效果如图：
当鼠标拖动向上时：
四、代码核心配置解析
1. 开启边缘渐隐
.fadingEdge(true)直接启用列表默认边缘渐隐效果。
2. 配置渐隐长度（官方标准写法）
.fadingEdge(true, { fadingEdgeLength: LengthMetrics.vp(80) })- LengthMetrics.vp(80)：设置渐隐长度为 80vp
- 数值越大，渐隐区域越长，过渡越柔和
3. 生效规则
- 垂直列表：渐隐效果出现在顶部 + 底部
- 水平列表：渐隐效果出现在左侧 + 右侧
- 内容未超出容器时，渐隐自动不显示
- 滚动时渐隐自动显示
总结
- 必须给 List 设置明确高度/宽度，否则无法滚动，渐隐不生效。
- 必须使用 LengthMetrics定义渐隐长度，符合鸿蒙标准化语法。
- 渐隐效果由系统渲染，不影响布局、不影响事件。
- 配合长列表使用，视觉体验最优。
fadingEdge是 HarmonyOS6 官方提供的List 边缘渐隐标准属性，能够快速实现滚动边界的柔和渐变效果，提升应用视觉品质。
只需一行代码即可开启：
.fadingEdge(true, { fadingEdgeLength: LengthMetrics.vp(80) })如果这篇文章对你有帮助，欢迎点赞、收藏、关注，你的支持是持续创作的动力！