页面预览

阅读时长：约 19 分钟　|　难度：★★★★☆　|　篇章：第 3 篇 · 首页与功能导航
对应源码：entry/src/main/ets/pages/HomePage.ets

Scroll弹性滚动布局图

前言

玄象项目首页需要容纳"今日天地"卡片与九宫格功能入口两大内容区，同时底部导航栏固定。玄象项目通过 Scroll 容器搭配 layoutWeight 弹性布局实现了"上下可滚动、底部固定"的标准布局。本篇将深入剖析玄象项目首页弹性滚动布局的实现：从 Scroll 滚动容器、layoutWeight 弹性占位、scrollBar 隐藏、height 自适应，到 Column 嵌套布局与 padding 边距控制。掌握这套弹性滚动布局方法论，您就能为任何 HarmonyOS 应用打造适配不同屏幕的首页布局。

提示：layoutWeight 是 ArkUI 弹性布局的核心——它让 Scroll 在 Column 中自动填充剩余空间。

一、首页布局结构

1.1 完整布局

build() {
  Column() {
    // 顶部标题栏
    Row() { ... }
    .padding({ left: 16, right: 16, top: 50, bottom: 12 })

    // 主内容区域（可滚动）
    Scroll() {
      Column({ space: 20 }) {
        this.TodayHeavenCard()    // "今日天地"卡片
        this.FeatureGrid()        // 九宫格功能入口
      }
      .padding({ left: 16, right: 16, bottom: 80 })
    }
    .layoutWeight(1)              // ← 弹性填充剩余空间
    .scrollBar(BarState.Off)       // ← 隐藏滚动条

    // 底部导航栏
    this.BottomNavBar()
  }
  .width('100%')
  .height('100%')
  .backgroundColor(Colors.BG_DARK)
}

1.2 三层结构

Column (全屏)
  ├── Row (顶部标题栏)          ← 固定高度（约 100vp）
  ├── Scroll (主内容)           ← 弹性填充剩余空间
  │     └── Column (内容区)
  │           ├── TodayHeavenCard
  │           └── FeatureGrid
  └── BottomNavBar (底部导航栏)  ← 固定高度（60vp）

二、Scroll 容器详解

2.1 Scroll 基本用法

Scroll() {
  Column({ space: 20 }) {
    // 可滚动内容
  }
}
.layoutWeight(1)
.scrollBar(BarState.Off)

2.2 Scroll 关键属性

属性 值 含义
layoutWeight 1 弹性填充剩余空间
scrollBar BarState.Off 隐藏滚动条
scrollable ScrollDirection.Vertical 垂直滚动（默认）

2.3 Scrolled 方向的配置

Scroll() {
  // 内容
}
.scrollable(ScrollDirection.Vertical)  // 垂直滚动

ScrollDirection 枚举：

值 含义
Vertical 垂直滚动（默认）
Horizontal 水平滚动
Both 双向滚动
None 禁止滚动

三、layoutWeight 弹性布局

3.1 layoutWeight 的作用

layoutWeight 是 ArkUI 的弹性权重属性，让组件按比例分配父容器的剩余空间。

Column() {
  Row()             // 固定高度
  Scroll()          // layoutWeight(1) → 占满剩余空间
  BottomNavBar()    // 固定高度 60vp
}

3.2 计算公式

Scroll 高度 = Column 高度 - 顶部标题栏高度 - 底部导航栏高度

3.3 自适应优势

layoutWeight 让玄象项目首页在不同屏幕尺寸上自动适配：

  • 小屏（320vp）：Scroll 区域较小，可滚动
  • 大屏（414vp）：Scroll 区域较大，内容完整展示
  • 折叠屏：自动适配展开/折叠状态

四、scrollBar 滚动条控制

4.1 scrollBar 配置

.scrollBar(BarState.Off)

BarState 枚举：

值 含义
On 始终显示
Off 始终隐藏
Auto 滚动时显示，停止后隐藏

4.2 玄象项目选择 Off 的原因

玄象项目首页选择隐藏滚动条（BarState.Off），原因：

  1. 视觉整洁：深色主题下滚动条影响视觉完整性。
  2. 用户直觉：现代移动端用户习惯"滑动交互"，不需要滚动条提示。
  3. 内容长度适中：首页内容（卡片 + 九宫格）约 500vp，用户可直觉感知可滚动。

五、Column 内容布局

5.1 内容区 Column

Column({ space: 20 }) {
  this.TodayHeavenCard()
  this.FeatureGrid()
}
.padding({ left: 16, right: 16, bottom: 80 })

5.2 space 参数

Column({ space: 20 })

20vp 间距让"今日天地"卡片与九宫格保持视觉间距。

5.3 padding 底部留白

.padding({ left: 16, right: 16, bottom: 80 })
  • left: 16 / right: 16：左右边距与顶部标题栏对齐。
  • bottom: 80：底部预留 80vp，避免内容被底部导航栏遮挡。

提示：玄象项目 bottom: 80 为底部导航栏（60vp）留出空间，并额外提供 20vp 的视觉缓冲。

六、Scroll 内容高度计算

6.1 内容总高度

玄象项目首页滚动内容总高度：

TodayHeavenCard 高度 ≈ 400vp
  + FeatureGrid 高度 = 280vp
  + space = 20vp
  + padding top/bottom ≈ 80vp
  = 约 780vp

6.2 不同屏幕下的滚动行为

设备 屏幕高度 内容是否可滚动
手机（414×896） 896vp 约 1 屏，略微可滚动
手机（360×780） 780vp 刚好一屏
折叠屏（展开） 约 1200vp 完整展示，无需滚动

七、Scroll 的性能优化

7.1 懒加载

玄象项目首页内容较少，无需懒加载。若后续增加内容，可使用 LazyForEach：

Scroll() {
  LazyForEach(this.dataSource, (item: DataItem) => {
    // 项渲染
  }, (item: DataItem) => item.id)
}

7.2 避免嵌套滚动

玄象项目首页仅在 Scroll 中滚动，不嵌套其他滚动容器：

// 正确：单层 Scroll
Scroll() {
  Column() {
    // 内容
  }
}

// 错误：嵌套 Scroll
Scroll() {
  Scroll() {  // ← 嵌套，导致滚动冲突
    // ...
  }
}

7.3 使用 NestedScroll

若确实需要嵌套滚动，可使用 NestedScroll：

Scroll() {
  List() {
    // ...
  }
  .nestedScroll({
    scrollForward: NestedScrollMode.SELF_FIRST,
    scrollBackward: NestedScrollMode.PARENT_FIRST
  })
}

八、玄象项目首页布局总结

8.1 布局层次

Column (占满全屏)
  ├── 顶部标题栏（固定高度）
  ├── Scroll（layoutWeight 弹性填充）
  │     └── 内容区（可滚动）
  └── 底部导航栏（固定高度 60vp）

8.2 关键属性

组件 属性 值
Column width/height '100%'
Scroll layoutWeight 1
Scroll scrollBar BarState.Off
内容 Column padding { left: 16, right: 16, bottom: 80 }
底部导航栏 height 60

8.3 弹性布局模板

Column() {
  // 顶部（固定）
  Header()

  // 中间（弹性）
  Scroll() {
    // 内容
  }
  .layoutWeight(1)

  // 底部（固定）
  Footer()
}
.width('100%')
.height('100%')

九、弹性滚动布局的扩展

9.1 下拉刷新

Scroll() {
  // 内容
}
.pullToRefresh(true)
.onRefresh(() => {
  // 刷新数据
})

9.2 上拉加载

Scroll() {
  // 内容
}
.onReachEnd(() => {
  // 加载更多
})

9.3 自定义滚动条

Scroll() {
  // 内容
}
.scrollBar(BarState.Auto)
.scrollBarWidth(4)
.scrollBarColor(Colors.PRIMARY_GOLD)

十、玄象项目首页布局设计原则

10.1 固定 + 弹性 + 固定

玄象项目首页采用"顶固定 + 中弹性 + 底固定"的经典布局模式。

10.2 内容自适应

  • 内容区通过 layoutWeight 弹性填充。
  • 内容超出时自动滚动。
  • 内容不足时整体占满屏幕。

10.3 边距一致

  • 左右边距统一为 16vp。
  • 顶部标题栏与内容区对齐。

九、Scroll 常见问题

9.1 Scroll 嵌套滚动冲突

ArkUI 中嵌套 Scroll 容器会导致滚动冲突。玄象项目的解决方案是避免嵌套，使用 NestedScroll 模式：

Scroll() {
  List() {
    // 列表项
  }
  .nestedScroll({
    scrollForward: NestedScrollMode.SELF_FIRST,
    scrollBackward: NestedScrollMode.PARENT_FIRST
  })
}

9.2 layoutWeight 与固定高度的配合

容器 高度策略 玄象项目值
顶部标题栏 固定高度（padding 计算） ~100vp
Scroll layoutWeight(1) 弹性填充
底部导航栏 固定高度 60vp

9.3 Scroll 性能优化建议

  1. 固定高度：给 Scroll 子元素固定高度，减少布局计算
  2. 懒加载：使用 LazyForEach 延迟渲染不可见项
  3. 避免过度绘制：减少 Scroll 内不必要的 Canvas 动画

9.4 Scroll 的滚动行为控制

滚动行为 配置方式 玄象项目设置
滚动条显示 scrollBar BarState.Off
滚动方向 scrollable ScrollDirection.Vertical
边缘回弹 edgeEffect 默认
滚动到边缘 onReachStart / onReachEnd 未使用

总结

本篇以玄象项目首页布局为蓝本，深入剖析了 ArkUI 弹性滚动布局的实现：从 Scroll 滚动容器、layoutWeight 弹性占位、scrollBar 隐藏控制，到 Column 嵌套布局、padding 边距控制、layoutWeight 弹性布局公式。掌握这套弹性滚动布局方法论，您就能为任何 HarmonyOS 应用打造适配不同屏幕的首页布局。

下一篇：《29 · LunarCalendar.getTodayHeavenlyStems 干支计算在首页的接入》，将带您深入玄象项目首页干支数据的计算与展示。

如果这篇文章对你有帮助，欢迎点赞👍、收藏⭐、关注🔔，你的支持是我持续创作的动力！

相关资源：

# 鸿蒙
Logo
HarmonyOS开发者社区

讨论HarmonyOS开发技术，专注于API与组件、DevEco Studio、测试、元服务和应用上架分发等。

更多推荐

cover

【开发者故事】集成 HarmonyOS App Linking 能力，搜觅 App 重塑高效专注搜索新体验

avatar HarmonyOS开发者社区
cover

HarmonyOS UIAbility 启动参数丢失怎么办：Want 和页面路由怎么接住

avatar HarmonyOS开发者社区

HarmonyOS应用实战-启示散页-42-收藏导出别混进私密问题：导出前先做字段筛选和用户确认

它可能含来源题库 id、用户自定义题库名称、答案文本、内部时间戳，未来还会添加诊断字段。直接看似方便，却把“存什么”与“允许分享什么”绑死了。

avatar HarmonyOS开发者社区