阅读时长约 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 BuilderBuilderFeatureGrid(){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 数据驱动的优势优势说明可扩展新增功能只需修改 features 数组可维护数据与 UI 解耦可测试数组易于断言三、Grid 容器详解3.1 Grid 关键属性Grid(){...}.columnsTemplate(1fr 1fr 1fr).rowsGap(12).columnsGap(12).width(100%).height(280)属性值含义columnsTemplate1fr 1fr 1fr三列等分rowsGap12行间距 12vpcolumnsGap12列间距 12vpwidth100%占满父容器宽度height280固定高度 280vp3.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 与 columnsGapcolumnsGap 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 单元格样式属性值含义width100%占满 GridItemheight80固定高度 80vpjustifyContentFlexAlign.Center内容垂直居中backgroundColorColors.BG_CARD卡片背景border{ width: 1, color: BG_CARD_BORDER, radius: 12 }边框borderRadius12圆角五、onClick 路由跳转5.1 跳转实现.onClick((){router.pushUrl({url:item.page});})每个功能入口点击后调用router.pushUrl跳转到对应页面。5.2 九宫格路由映射名称路由星宿pages/mansion/MansionListPage周易pages/yijing/YijingHomePage命理pages/mingli/BaziInputPage风水pages/fengshui/FengshuiHomePage节气pages/astronomy/SolarTermsPage月相pages/astronomy/MoonPhasesPage乐律pages/music/MusicTwelveLawsPage地理pages/geography/NineProvincesPage取名pages/naming/AiNamingPage六、九宫格布局视觉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圆角12vp9.3 可扩展性新增功能无需修改build方法只需修改features数组。十、Grid 与 List 的选择10.1 Grid 适用场景固定列数的网格布局功能入口、相册、商品展示10.2 List 适用场景单列或多列流式布局长列表、聊天记录玄象项目九宫格列数固定为 3使用Grid最合适。九、Grid 常见问题9.1 Grid 与 List 的性能对比场景GridList玄象项目选择固定列数网格✓ 最优需手动计算Grid九宫格长列表滚动不支持✓ 最优List星宿列表混合列数不支持✓ 灵活List9.2 Grid 的响应式适配玄象项目的 Grid 使用1fr单位实现等分列宽Grid().columnsTemplate(1fr 1fr 1fr)// 三列等分.rowsGap(12).columnsGap(12)若需适配不同屏幕宽度可动态计算列数privategetColumns():string{constscreenWidththis.getScreenWidth();if(screenWidth720)return1fr 1fr 1fr 1fr;// 平板if(screenWidth400)return1fr 1fr 1fr;// 手机return1fr 1fr;// 小屏手机}9.3 GridItem 的点击反馈玄象项目九宫格单元点击后跳转至对应功能页。未来可增加点击状态反馈点击时缩放动画scale属性从 1 到 0.95点击时背景色变化从BG_CARD到BG_CARD_HIGHLIGHT点击后路由跳转至目标页面9.4 Grid 的视觉设计建议设计维度玄象项目取值最佳实践建议列数3 列不超过 4 列行间距12vp8~16vp列间距12vp8~16vp单元格高度80vp64~96vp圆角12vp8~16vp总结本篇以玄象项目九宫格功能入口为蓝本深入剖析了 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