引言

在之前的课程中，已经学习了线性布局和基础组件构建登录页、List 组件构建设置页。本节课将学习更多 HarmonyOS UI 组件，实现更丰富的首页页面。通过分析首页结构，使用 Swiper 实现轮播图、Grid 实现网格功能快捷键、List 实现列表内容、Scroll 构建整个可滚动页面，最终整合完成完整的可滚动首页开发。

核心内容

首页页面结构分析

首页整体采用 Column 纵向布局，从上到下依次为：

• 标题“首页”

• 顶部运营推荐轮播区

• 中间网格功能快捷区

• 底部列表标题 + 列表内容区

当内容超出屏幕尺寸时，整个页面需要支持滚动。

组件选型规划：

区域	选用组件
轮播图区域	Swiper
功能快捷键区域	Grid
列表内容区域	List
可滚动页面容器	Scroll

Swiper 轮播组件开发

Swiper 是容器组件，提供滑动轮播展示能力，可放置多个子组件实现轮播效果。实际开发中推荐使用 ForEach 循环渲染轮播内容，减少冗余代码。Swiper 常应用于首页运营推荐位、Banner 图轮播场景。

Swiper 控制器使用

Swiper 构造函数接收可选参数 controller（类型 SwiperController），用于手动控制轮播翻页。

private swiperController: SwiperController = new SwiperController();

Swiper(this.swiperController) {
    // 轮播子组件
}

Row() {
    Button('showNext')
        .onClick(() => {
            this.swiperController.showNext();
        })
    Button('showPrevious')
        .onClick(() => {
            this.swiperController.showPrevious();
        })
}

核心方法：

方法名称	功能说明
showNext()	翻至下一页
showPrevious()	翻至上一页
changeIndex(index: number)	翻至指定页面

核心属性

属性名称	功能说明	默认值
autoPlay	设置子组件是否自动轮播	false
loop	设置是否开启循环轮播	true
interval	设置自动轮播的播放间隔，单位毫秒	3000
indicator	设置导航点指示器样式，可调整位置、尺寸、颜色	-

当 loop 设置为 false 时，轮播到第一页/最后一页后，无法继续向前/向后切换页面；loop 默认开启循环，无需额外设置。

导航点自定义示例

Swiper() {
    // ...
}
.indicator(
    Indicator.dot()
        .left(0)
        .itemWidth(15)
        .itemHeight(15)
        .selectedItemWidth(30)
        .selectedItemHeight(15)
        .color(Color.Red)
        .selectedColor(Color.Blue)
)

首页轮播图实现步骤

1. 在 ViewModel 中创建方法，将需要轮播的图片资源存入数组。

2. 创建 Swiper 容器，通过 ForEach 循环渲染所有图片组件。

3. 设置 autoPlay(true) 开启自动轮播，loop 默认开启无需额外设置，完成轮播区域开发。

Grid 网格容器开发

Grid 是网格布局组件，由行列分割的单元格组成，可通过指定项目单元格位置实现复杂布局。典型场景包括功能快捷键网格、图库、日历、计算器等。

Grid 和 GridItem 的关系：Grid 负责设置网格布局整体参数（行列数、占比、间距），GridItem 是每个网格条目容器，负责定义单个单元格组件的特征。

行列占比设置

通过 columnsTemplate 和 rowsTemplate 设置行列尺寸，参数格式为 数值fr，多个值使用空格分隔。

• fr 的个数等于网格布局的列数/行数，数值决定对应行/列的宽度占比。

Grid() {
    // GridItem 内容
}
.columnsTemplate('1fr 2fr 1fr')  // 水平方向三栏：1:2:1 占比
.rowsTemplate('1fr 1fr 1fr')     // 垂直方向三行：1:1:1 占比

间距设置

属性	说明
rowsGap	设置行间距，单位为 vp
columnsGap	设置列间距，单位为 vp

Grid() {
    // GridItem 内容
}
.columnsTemplate('1fr 1fr 1fr 1fr')
.rowsGap(15)
.columnsGap(15)

对于结构相似的多个 GridItem，推荐使用 ForEach 循环渲染减少重复代码。

首页网格功能区实现步骤

1. 创建 Grid 组件，通过 ForEach 循环渲染功能数据。

2. 每个 GridItem 内部嵌套 Column 容器，放置图标 Image 和功能文本 Text。

3. 设置 columnsTemplate/rowsTemplate 确定行列占比，设置行间距和列间距，完成网格区域开发。

Scroll 可滚动页面开发

Scroll 是可滚动容器组件，当内部子组件尺寸超过父组件尺寸时，提供滚动查看能力，用于构建超出一屏的可滚动页面。

滚动控制器 Scroller

Scroll 接收可选参数 scrollController，用于手动控制滚动位置。

private scroller: Scroller = new Scroller();

Scroll(this.scroller) {
    // 页面内容
}

// 滚动控制
this.scroller.scrollTo(100);           // 滑动到指定偏移位置
this.scroller.scrollEdge(Edge.Top);    // 滚动到页面顶部
this.scroller.scrollPage({ next: true }); // 滚动到下一页

核心方法：

方法名称	功能说明
scrollTo(value: number)	滑动到指定偏移位置
scrollEdge(target: Edge)	滚动到页面边缘（顶部/底部）
scrollPage(options: ScrollPageOptions)	滚动到下一页/上一页

核心属性

属性名称	功能说明	默认值
scrollable	设置滚动方向	ScrollDirection.Vertical（垂直滚动）
scrollBar	设置滚动条显示状态	BarState.Auto（触摸显示，2秒后消失）
scrollBarColor	设置滚动条颜色	系统默认
scrollBarWidth	设置滚动条宽度	系统默认

scrollBar 的三种状态：

• BarState.Auto：触摸显示，2秒后自动消失

• BarState.On：常驻显示

• BarState.Off：隐藏不显示

首页开发中通常设置 scrollBar(BarState.Off) 隐藏滚动条，保证页面美观。

完整首页整合步骤

1. 将开发完成的 Swiper 轮播、Grid 网格、List 列表从上到下放入 Column 纵向容器。

2. 将 Column 整体放入 Scroll 容器中。

3. 根据需求设置 Scroll 属性（如隐藏滚动条），当内容超出屏幕后即可滚动展示，完成完整首页开发。

@Entry
@Component
struct HomePage {
    private swiperController: SwiperController = new SwiperController();

    build() {
        Scroll() {
            Column() {
                // 标题
                Text('首页')
                    .fontSize(24)
                    .fontWeight(FontWeight.Bold)
                    .padding(16)

                // 轮播图区域
                Swiper(this.swiperController) {
                    ForEach(this.bannerData, (item: Resource) => {
                        Image(item)
                            .width('100%')
                            .height(180)
                    })
                }
                .autoPlay(true)
                .loop(true)
                .interval(3000)

                // 网格功能区
                Grid() {
                    ForEach(this.functionData, (item: FunctionItem) => {
                        GridItem() {
                            Column() {
                                Image(item.icon)
                                    .width(40)
                                    .height(40)
                                Text(item.title)
                                    .fontSize(12)
                            }
                        }
                    })
                }
                .columnsTemplate('1fr 1fr 1fr 1fr')
                .rowsGap(15)
                .columnsGap(15)
                .padding(16)

                // 列表内容区
                List() {
                    ForEach(this.listData, (item: ListItem) => {
                        ListItem() {
                            Row() {
                                Image(item.icon)
                                    .width(40)
                                    .height(40)
                                Column() {
                                    Text(item.title)
                                    Text(item.desc)
                                        .fontSize(12)
                                        .fontColor('#999')
                                }
                                .layoutWeight(1)
                                .margin({ left: 12 })
                                Image($r('app.media.ic_arrow'))
                                    .width(16)
                                    .height(16)
                            }
                            .padding(16)
                            .width('100%')
                        }
                    })
                }
            }
            .width('100%')
        }
        .scrollBar(BarState.Off)
        .width('100%')
        .height('100%')
    }
}

总结

本节课学习了 HarmonyOS 首页开发中三个核心组件的用法：

1. Swiper 轮播组件：容器组件，提供滑动轮播展示能力。通过 SwiperController 控制翻页（showNext、showPrevious、changeIndex）；核心属性包括 autoPlay（自动轮播）、loop（循环轮播）、interval（播放间隔）、indicator（导航点样式）。

2. Grid 网格组件：由行列分割的单元格组成。通过 columnsTemplate 和 rowsTemplate 设置行列占比（fr 单位），通过 rowsGap 和 columnsGap 设置间距，GridItem 定义单个单元格特征。

3. Scroll 滚动组件：可滚动容器，用于构建超出一屏的页面。通过 Scroller 控制器控制滚动位置（scrollTo、scrollEdge、scrollPage）；核心属性包括 scrollable（滚动方向）、scrollBar（滚动条状态）。

4. 首页整合：将 Swiper、Grid、List 放入 Column 容器，再将整体放入 Scroll 容器，设置滚动属性，完成可滚动首页开发。