文档知识库教程OpenHarmony【免费下载链接】CangjieCorpus本仓库为仓颉编程语言语料库聚焦 仓颉编程语言 核心知识体系整合官方开发指南、API 文档、典型代码示例及语法规范等多维度资源经结构化处理与专业标注构建为支持 RAG检索增强生成技术 的高质量知识基座适配智能编码助手、学习辅助工具等应用开发需求。 欢迎开发者基于本语料库构建仓颉语言智能应用推动鸿蒙开发生态智能化升级项目地址https://gitcode.com/Cangjie/CangjieCorpus点击查看免费下载导读GridItem 是仓颉 ArkUI 网格布局中“网格容器内单项内容”的容器组件是构建九宫格、日历、图片墙、服务入口等二维网格界面的基础单元。本文以 OpenHarmony 仓颉 ArkUI 官方参考文档为核心完整解析 GridItem 的两种构造方式、rowStart / rowEnd / columnStart / columnEnd 四个位置属性及其取值约束并结合 Grid 容器、ForEach 循环渲染与 LazyForEach 懒加载的配合方式给出可直接运行的仓颉示例代码与源码级实现依据。读完本文你将掌握如何让单个网格项横跨多行多列、如何编排网格自身的行列布局以及在大数据量网格场景下的性能优化手段。GridItem 组件定位与使用前提GridItem 是网格容器 Grid 中承载单项内容的容器组件。它本身不负责网格的行列划分而是与 Grid 容器配合完成“由行和列分割的单元格”式二维布局——Grid 负责行列数量、尺寸占比、间距与滚动方向GridItem 负责单个单元格内的内容组织及其在网格中的位置与跨行跨列范围。依据官方参考文档GridItem 的使用存在以下强约束仅支持作为 Grid 组件的子组件使用不能脱离 Grid 独立存在当 GridItem 配合 LazyForEach 使用时GridItem 子组件在 GridItem创建时即创建当 GridItem 配合 if/else、ForEach 使用或 GridItem 的父组件为 Grid 时GridItem 子组件在GridItem 布局时创建。这一创建时机的差异直接影响数据量较大场景下的性能使用 LazyForEach 时按需创建、滑出可视区即回收而使用 ForEach 时则会一次性展开全部子组件。可参考 创建网格Grid/GridItem 中的说明网格布局由“行”和“列”分割的单元格组成通过指定“项目”所在单元格即可做出灵活多样的布局典型场景包括九宫格图片展示、日历、计算器等。导入模块GridItem 归属于 ArkUI 声明式组件体系使用前需导入模块import kit.ArkUI.*子组件规则GridItem 内可以包含单个子组件。也就是说一个 GridItem 只能承载一个直接子组件如 Text、Image 或自定义组件若需在单元格内呈现多个元素应通过 Column / Row / Stack 等布局容器将其包裹为一个根组件。创建组件两种构造方式GridItem 提供两个构造函数重载均要求系统能力SystemCapability.ArkUI.ArkUI.Full起始版本为22。init()public init()创建一个不包含子组件的网格单项内容组件。此构造用于仅需占位、或后续再动态填充内容的场景。init(() - Unit)public init(child: () - Unit)创建一个可包含子组件的网格单项内容组件参数说明如下参数名类型必填默认值说明child() - Unit是-GridItem 容器的子组件。child为尾随闭包形式的组件构建函数在其中声明 GridItem 的唯一子组件例如GridItem() { Text(会议) }。组件属性网格项的跨行跨列定位GridItem 通过rowStart、rowEnd、columnStart、columnEnd四个属性定义自身在网格中的位置与所占行列范围四者均返回This以支持链式调用且都要求系统能力SystemCapability.ArkUI.ArkUI.Full、起始版本 22。参数类型统一为?Int32可空 Int32必填。func columnEnd(?Int32)public func columnEnd(value: ?Int32): This设置当前元素终点列号与columnStart配套使用。参数名类型必填默认值说明value?Int32是-当前元素终点列号与 columnStart 配套使用。取值范围[0, 总列数-1]。初始值0func columnStart(?Int32)public func columnStart(value: ?Int32): This设置当前元素起始列号与columnEnd配套使用。参数名类型必填默认值说明value?Int32是-当前元素起始列号与 columnEnd 配套使用。取值范围[0, 总列数-1]。初始值0func rowEnd(?Int32)public func rowEnd(value: ?Int32): This设置当前元素终点行号与rowStart配套使用。参数名类型必填默认值说明value?Int32是-当前元素终点行号与 rowStart 配套使用。取值范围[0, 总行数-1]。初始值0func rowStart(?Int32)public func rowStart(value: ?Int32): This设置当前元素起始行号与rowEnd配套使用。参数名类型必填默认值说明value?Int32是-当前元素起始行号与 rowEnd 配套使用。取值范围[0, 总行数-1]。初始值0使用要点行号、列号均从0开始计数最大值受 Grid 当前布局的总行数、总列数约束如总列数为 5则合法列号区间为 04四个属性必须成对使用才能准确表达跨行跨列范围横向跨度由columnStart与columnEnd共同界定纵向跨度由rowStart与rowEnd共同界定对于需要指定 GridItem 起始行列号和所占行列数的场景官方文档推荐改用 Grid 的 layoutOptions 参数GridLayoutOptions以便在网格容器层统一管理各单项的位置与跨度而非在每个 GridItem 上逐个设置属性GridItem 同样支持全部通用属性与通用事件例如.id()、.backgroundColor()、.width()、.height()、.textAlign()等可与位置属性自由组合。示例代码GridItem 设置自身位置官方示例演示了如何通过rowStart/rowEnd/columnStart/columnEnd让单个网格项跨越多行或多列同时用 ForEach 循环渲染其余网格项整体可运行于仓颉 ArkUI 工程包名ohos_app_cangjie_entrypackage ohos_app_cangjie_entry import kit.ArkUI.* import ohos.arkui.state_macro_manage.* import std.collection.{ArrayList, HashMap} Entry Component class EntryView { let scroller Scroller() State var numbers: ArrayListString ArrayList([0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15]) func build() { Column() { Grid { //指定当前GridItem组件的起始行号为1终点行号为4 GridItem { Text(4) .fontSize(16) .backgroundColor(0xFAEEE0) .width(100.percent) .height(100.percent) .textAlign(TextAlign.Center) .id(gridItem1) }.rowStart(1).rowEnd(4) //循环渲染Griditem标记为0-15 ForEach( this.numbers, itemGeneratorFunc: { num: String, idx: Int64 GridItem { Text(num) .fontSize(16) .backgroundColor(0xF9CF93) .width(100.percent) .height(100.percent) .textAlign(TextAlign.Center) } } ) //指定当前GridItem组件的起始列号为1终点列号为5 GridItem { Text(5) .fontSize(16) .backgroundColor(0xDBD0C0) .width(100.percent) .height(100.percent) .textAlign(TextAlign.Center) .id(gridItem2) }.columnStart(1).columnEnd(5) } .columnsTemplate(1fr 1fr 1fr 1fr 1fr) .rowsTemplate(1fr 1fr 1fr 1fr 1fr) .width(90.percent) .backgroundColor(0xFAEEE0) .height(300) }.width(100.percent).margin(top: 5) } }示例要点拆解网格规模Grid 通过.columnsTemplate(1fr 1fr 1fr 1fr 1fr)与.rowsTemplate(1fr 1fr 1fr 1fr 1fr)声明了一个5 行 5 列的网格且行列同时设置时 Grid 固定展示该范围内的元素、不可滚动纵向跨行编号为gridItem1的 GridItem 设置了.rowStart(1).rowEnd(4)在列位置默认 0 的前提下占据第 14 行、第 0 列形成 4 行高的纵向长条横向跨列编号为gridItem2的 GridItem 设置了.columnStart(1).columnEnd(5)在行位置默认 0 的前提下占据第 15 列、第 0 行形成 5 列宽的横向长条循环渲染剩余编号 015 的网格项由 ForEach 基于numbers数组循环生成itemGeneratorFunc的itemGeneratorFunc参数接收数组元素与索引num: String, idx: Int64返回的组件必须为 GridItemForEach 的父容器为 Grid返回子组件须是 Grid 允许的子组件单元格内容每个 GridItem 内的 Text 子组件通过.width(100.percent).height(100.percent)填满单元格.textAlign(TextAlign.Center)实现文字居中。与 Grid 容器协同行列模板与布局模式GridItem 的位置属性取值总列数、总行数由 Grid 的行列模板决定。Grid 支持 columnsTemplate / rowsTemplate 与columnsGap/rowsGap等属性其中columnsTemplate/rowsTemplate为形如1fr 1fr 2fr的字符串fr个数即列行数数值用于计算各列行在网格宽度高度上的占比。根据两者的设置组合Grid 呈现三种布局模式直接影响 GridItem 的排布与 Grid 的滚动能力行列模板同时设置Grid 只展示固定行列数的元素其余元素不展示Grid 不可滚动GridItem 默认填满网格大小仅设置其一元素沿设置的方向排布超出显示区域的元素可通过滚动展示——设置columnsTemplate时滚动方向为垂直设置rowsTemplate时滚动方向为水平两者均不设置行列数由 Grid 高度、首个元素高度、rowsGap等共同决定超出行列容纳范围的元素不展示且不可滚动。当需要构建可滚动的网格如文件管理、购物、视频列表页时建议只设置行列模板之一详见 创建网格Grid/GridItem 中的“构建可滚动的网格布局”一节该指南中的示例还展示了通过 Scroller 绑定 Grid 并调用scrollPage实现日历翻页等滚动位置控制。大数据量网格的性能优化LazyForEach 与 cachedCount对于内容结构相似的多个 GridItem官方建议使用 ForEach 循环渲染以减少重复代码但当构建具有大量网格项的可滚动网格时应改用 数据懒加载 LazyForEach 实现按需迭代加载。二者的取舍在 GridItem 的创建时机上体现得尤为明显ForEach 在首次渲染时为数据源每个数组项生成唯一键值并创建对应组件数据量大时一次性创建开销较高LazyForEach 仅在滚动容器的可视区域内按需创建 GridItem组件滑出可视区外即被销毁回收从而降低内存占用。配合 LazyForEachGrid 提供cachedCount属性设置预加载的 GridItem 数量初始值 1仅对 LazyForEach 生效设置后会在 Grid 显示区域上下各缓存cachedCount × 列数个 GridItem减少滑动白块超出显示与缓存范围的 GridItem 会被释放。典型用法Grid() { LazyForEach(this.dataSource, itemGeneratorFunc: {dataSource: T, _: Int64 GridItem() { // 单元格内容 } }) } .cachedCount(3)说明cachedCount的增加会增大 UI 的 CPU、内存开销使用时需结合实际数据量、滚动体验与设备性能综合权衡。同时注意 LazyForEach 的使用限制只有 List、Grid、Swiper 支持数据懒加载LazyForEach 的键值生成器必须为每个数据生成唯一值每次迭代必须且只允许创建一个子组件且该子组件必须是父容器Grid允许的子组件——在网格场景下即 GridItem。总结GridItem 是仓颉 ArkUI 网格布局中不可替代的“单项容器”结构约束仅能作为 Grid 的子组件且仅承载单个子组件创建方式init()与init(child)两种构造后者用于声明单元格内容定位能力通过rowStart/rowEnd/columnStart/columnEnd成对设置实现单网格项跨多行多列取值受 Grid 总行列数约束[0, 总行列数-1]初始值 0需统一管理单项位置时推荐改用 Grid 的 layoutOptions 参数配合使用静态小数据量用 ForEach 循环渲染动态大数据量用 LazyForEach cachedCount实现按需加载与预缓存。掌握 GridItem 的位置属性与 Grid 行列模板的协同关系即可在仓颉 ArkUI 中高效构建从九宫格、日历到可滚动网格列表等各类二维布局页面。相关文档Grid 网格容器行列模板、间距、cachedCount 与 GridLayoutOptions创建网格Grid/GridItem网格布局开发指南与完整示例ForEach 循环渲染数组数据循环生成 GridItemLazyForEach 数据懒加载大数据量网格按需渲染与回收赞分享文档知识库教程OpenHarmony【免费下载链接】CangjieCorpus本仓库为仓颉编程语言语料库聚焦 仓颉编程语言 核心知识体系整合官方开发指南、API 文档、典型代码示例及语法规范等多维度资源经结构化处理与专业标注构建为支持 RAG检索增强生成技术 的高质量知识基座适配智能编码助手、学习辅助工具等应用开发需求。 欢迎开发者基于本语料库构建仓颉语言智能应用推动鸿蒙开发生态智能化升级项目地址https://gitcode.com/Cangjie/CangjieCorpus点击查看免费下载相关推荐仓颉 ArkUI MenuItemGroup 组件详解菜单 MenuItem 分组的创建、参数配置与实战示例仓颉 ArkUI MenuItemGroup 组件详解菜单 MenuItem 分组的创建、参数配置与实战示例 本篇文章聚焦仓颉Cangjie语言 ArkU文档知识库教程OpenHarmonyArkUI 网格布局实战在仓颉应用中用 Grid/GridItem 构建自适应网格ArkUI 网格布局实战在仓颉应用中用 Grid/GridItem 构建自适应网格 网格布局Grid/GridItem是 ArkUI 声明式 UI 中最常文档知识库教程OpenHarmony仓颉 ArkUI-CJ 图形绘制指南Circle 圆形组件详解与实战示例仓颉 ArkUI CJ 图形绘制指南Circle 圆形组件详解与实战示例 本文面向使用仓颉Cangjie语言进行 OpenHarmony 应用 UI 开发文档知识库教程OpenHarmony上一篇如何用开源工具实现40平台7×24小时直播自动录制DouyinLiveRecorder深度解析下一篇如何用AlienFX Tools掌控你的Alienware灯光、风扇、性能一体化控制终极指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考