HarmonyOS应用《玄象》开发实战：九宫格功能入口：Grid / GridItem / columnsTemplate(‘1fr 1fr 1fr‘)

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

前言

九宫格是移动端首页的经典布局——玄象项目首页用 3×3 网格展示星宿、周易、命理、风水、节气、月相、乐律、地理、取名 9 大功能入口。这套视觉通过 ArkUI 的Grid容器配合columnsTemplate('1fr 1fr 1fr')等分三列实现。本篇将深入剖析玄象项目FeatureGrid的实现细节：从features数据数组、Grid/GridItem容器关系、columnsTemplate等分模板、rowsGap/columnsGap间距控制，到数据驱动的功能入口设计。掌握这套九宫格布局方法论，您就能为任何 HarmonyOS 应用打造规整的功能入口。

提示：玄象项目九宫格采用"数据驱动渲染"模式——所有功能项定义在数组中，UI 通过ForEach自动渲染。新增功能只需修改数组。

一、FeatureGrid 完整源码

1.1 features 数组定义

interfaceFeatureItem{name:string;icon:string;page:string;}privatefeatures:FeatureItem[]=[{name:'星宿',icon:'',page:'pages/mansion/MansionListPage'},{name:'周易',icon:'☰',page:'pages/yijing/YijingHomePage'},{name:'命理',icon:'◈',page:'pages/mingli/BaziInputPage'},{name:'风水',icon:'◎',page:'pages/fengshui/FengshuiHomePage'},{name:'节气',icon:'节',page:'pages/astronomy/SolarTermsPage'},{name:'月相',icon:'☽',page:'pages/astronomy/MoonPhasesPage'},{name:'乐律',icon:'',page:'pages/music/MusicTwelveLawsPage'},{name:'地理',icon:'⊕',page:'pages/geography/NineProvincesPage'},{name:'取名',icon:'名',page:'pages/naming/AiNamingPage'}];

1.2 FeatureGrid Builder

@BuilderFeatureGrid(){Grid(){ForEach(this.features,(item:FeatureItem)=>{GridItem(){Column({space:8}){Text(item.icon).fontSize(28).fontColor(Colors.PRIMARY_GOLD)Text(item.name).fontSize(16).fontColor(Colors.PRIMARY_GOLD)}.width('100%').height(80).justifyContent(FlexAlign.Center).backgroundColor(Colors.BG_CARD).border({width:1,color:Colors.BG_CARD_BORDER,radius:12}).borderRadius(12).onClick(()=>{router.pushUrl({url:item.page});})}},(item:FeatureItem)=>item.name)}.columnsTemplate('1fr 1fr 1fr').rowsGap(12).columnsGap(12).width('100%').height(280)}

二、FeatureItem 接口设计

2.1 接口定义

interfaceFeatureItem{name:string;// 功能名称icon:string;// 图标（emoji 或字符）page:string;// 跳转页面路由}

2.2 数据驱动的优势

三、Grid 容器详解

3.1 Grid 关键属性

Grid(){...}.columnsTemplate('1fr 1fr 1fr').rowsGap(12).columnsGap(12).width('100%').height(280)

3.2 columnsTemplate 等分模板

'1fr 1fr 1fr'表示三列，每列占 1 份（fraction）。

┌─────┬─────┬─────┐ │ 1fr │ 1fr │ 1fr │ └─────┴─────┴─────┘

3.3 其他模板示例

// 两列等分.columnsTemplate('1fr 1fr')// 四列等分.columnsTemplate('1fr 1fr 1fr 1fr')// 固定宽度列.columnsTemplate('100px 1fr 100px')// 比例列.columnsTemplate('1fr 2fr 1fr')

3.4 rowsGap 与 columnsGap

columnsGap = 12 rowsGap = 12 ↓ ↓ ┌──┬12┬──┬12┬──┐ │ │ │ │ │ │ ← row 1 └──┴──┴──┴──┴──┘ ↑ 12 ↑ ↑ ┌──┬──┬──┬──┬──┐ │ │ │ │ │ │ ← row 2 └──┴──┴──┴──┴──┘

四、GridItem 单元格

4.1 GridItem 容器

GridItem(){Column({space:8}){// 单元格内容}}

GridItem是Grid的子元素，每个GridItem占一个网格单元。

4.2 单元格内容

Column({space:8}){Text(item.icon).fontSize(28).fontColor(Colors.PRIMARY_GOLD)Text(item.name).fontSize(16).fontColor(Colors.PRIMARY_GOLD)}.width('100%').height(80).justifyContent(FlexAlign.Center).backgroundColor(Colors.BG_CARD).border({width:1,color:Colors.BG_CARD_BORDER,radius:12}).borderRadius(12)

4.3 单元格样式

五、onClick 路由跳转

5.1 跳转实现

.onClick(()=>{router.pushUrl({url:item.page});})

每个功能入口点击后调用router.pushUrl跳转到对应页面。

5.2 九宫格路由映射

六、九宫格布局视觉

6.1 完整布局

┌────────┬────────┬────────┐ │ 星宿 │ 周易 │ 命理 │ ├────────┼────────┼────────┤ │ 风水 │ 节气 │ 月相 │ ├────────┼────────┼────────┤ │ 乐律 │ 地理 │ 取名 │ └────────┴────────┴────────┘

6.2 尺寸计算

Grid 宽度 = 100% (假设屏幕宽 360vp) Grid 高度 = 280vp columnsGap = 12vp, rowsGap = 12vp 每列宽度 = (360 - 24) / 3 = 112vp 每行高度 = (280 - 24) / 3 = 85.33vp 单元格 height = 80vp（小于行高）

七、ForEach 数据驱动渲染

7.1 ForEach 在 Grid 中的应用

Grid(){ForEach(this.features,(item:FeatureItem)=>{GridItem(){...}},(item:FeatureItem)=>item.name)}

7.2 渲染流程

features 数组 (9 项) ↓ ForEach 遍历 ↓ 为每个 item 生成 GridItem ↓ Grid 按列模板排列 ↓ 3×3 网格呈现

八、九宫格的扩展方向

8.1 添加更多功能

privatefeatures:FeatureItem[]=[// 原有 9 项{name:'AI助手',icon:'🤖',page:'pages/assistant/AiAssistantPage'}// 第 10 项];

新增第 10 项后，Grid 自动变为 4×3 + 1 布局。

8.2 添加角标

Badge({count:this.notificationCount,position:BadgePosition.RightTop}){Text(item.icon)...}

8.3 添加长按菜单

Text(item.icon).gesture(LongPressGesture().onAction(()=>{this.showFeatureMenu(item);}))

九、玄象项目九宫格设计要点

9.1 数据驱动

玄象项目所有功能入口定义在features数组中，UI 自动渲染。

9.2 一致性

所有九宫格单元遵循统一视觉规范：

• 字体颜色：Colors.PRIMARY_GOLD
• 背景：Colors.BG_CARD
• 边框：Colors.BG_CARD_BORDER
• 圆角：12vp

9.3 可扩展性

新增功能无需修改build方法，只需修改features数组。

十、Grid 与 List 的选择

10.1 Grid 适用场景

• 固定列数的网格布局
• 功能入口、相册、商品展示

10.2 List 适用场景

• 单列或多列流式布局
• 长列表、聊天记录

玄象项目九宫格列数固定为 3，使用Grid最合适。

九、Grid 常见问题

9.1 Grid 与 List 的性能对比

9.2 Grid 的响应式适配

玄象项目的 Grid 使用1fr单位实现等分列宽：

Grid().columnsTemplate('1fr 1fr 1fr')// 三列等分.rowsGap(12).columnsGap(12)

若需适配不同屏幕宽度，可动态计算列数：

privategetColumns():string{constscreenWidth=this.getScreenWidth();if(screenWidth>720)return'1fr 1fr 1fr 1fr';// 平板if(screenWidth>400)return'1fr 1fr 1fr';// 手机return'1fr 1fr';// 小屏手机}

9.3 GridItem 的点击反馈

玄象项目九宫格单元点击后跳转至对应功能页。未来可增加点击状态反馈：

1. 点击时缩放动画：scale属性从 1 到 0.95
2. 点击时背景色变化：从BG_CARD到BG_CARD_HIGHLIGHT
3. 点击后路由跳转至目标页面

9.4 Grid 的视觉设计建议

总结

本篇以玄象项目九宫格功能入口为蓝本，深入剖析了 ArkUI 网格布局：从features数据数组、FeatureItem接口设计、Grid容器、GridItem单元格、columnsTemplate('1fr 1fr 1fr')等分模板、rowsGap/columnsGap间距控制，到onClick路由跳转与数据驱动渲染。掌握这套九宫格布局方法论，您就能为任何 HarmonyOS 应用打造规整的功能入口。

下一篇：《26 · router.pushUrl 路由跳转与 main_pages.json 路由表注册》，将带您深入玄象项目路由跳转的核心机制。

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

相关资源：

• HarmonyOS 官方文档：Grid 组件
• HarmonyOS 官方文档：GridItem 组件
• HarmonyOS 官方文档：columnsTemplate
• 开源鸿蒙跨平台社区：https://openharmonycrossplatform.csdn.net