uni-app 微信小程序 grid-view 组件指南Skyline 网格与瀑布流布局【免费下载链接】uni-appA cross-platform framework using Vue.js项目地址: https://gitcode.com/gh_mirrors/un/uni-appuni-app 的grid-view是面向微信小程序 Skyline 渲染引擎的网格布局组件用于在单页内以多列方式排列子节点支持等高校对aligned与瀑布流masonry两种布局模式是构建商品卡片墙、图片墙、信息流等双列/多列场景的高性能容器。本文以 grid-view 官方组件文档 为骨架完整展开其兼容性、全部属性与合法值并结合仓库内 grid-builder、waterflow 等相关文档与源码帮助读者理解何时选用grid-view、如何配置属性以及它与其他网格/瀑布流容器grid-builder、waterflow之间的边界。一、组件定位与兼容性在 uni-app 中grid-view被归入微信专用组件 · Skyline分类见 组件文档目录这意味着它只在微信小程序平台生效且依赖 Skyline 渲染架构。其兼容性矩阵来自 grid-view 文档如下| Web | 微信小程序 | Android | iOS | HarmonyOS | | :- | :- | :- | :- | :- | | x | 4.41 | x | x | x |要点解读仅微信小程序可用且基础库版本需 ≥ 4.41。在 Web、Android App、iOS App、HarmonyOS App 上均为x不支持4.41 是微信小程序基础库版本号grid-view属于 Skyline 渲染器提供的新能力因此必须在 Skyline 渲染模式下使用在app.json或页面 json 中配置renderer: skyline由于跨端不通用在实际工程中建议将grid-view的用法放在条件编译#ifdef MP-WEIXIN中其他平台走view flex 布局或 waterflow 等替代方案。二、属性总览grid-view的布局参数全部围绕「主轴main axis与交叉轴cross axis」建模竖向网格中主轴为垂直方向交叉轴为水平方向。全部属性如下表继承自 grid-view 文档| 名称 | 类型 | 兼容性 | 描述 | | :- | :- | :-: | :- | | type | string | 微信小程序: 4.41 | 布局方式合法值为aligned/masonry| | cross-axis-count | number | 微信小程序: 4.41 | 交叉轴元素数量即网格列数 | | max-cross-axis-extent | number | 微信小程序: 4.41 | 交叉轴元素最大范围 | | main-axis-gap | number | 微信小程序: 4.41 | 主轴方向间隔行间距 | | cross-axis-gap | number | 微信小程序: 4.41 | 交叉轴方向间隔列间距 | | padding | Array | 微信小程序: 4.41 | 长度为 4 的数组按 top、right、bottom、left 顺序指定内边距 |type 的合法值| 合法值 | 兼容性 | 描述 | | :- | :-: | :- | | aligned | 微信小程序: 4.41 | 每行高度由同一行中最大高度子节点决定行内等高 | | masonry | 微信小程序: 4.41 | 瀑布流根据子元素高度自动布局经典瀑布墙 |关键属性说明cross-axis-count列数决定交叉轴上排列几个元素。传入 2 即双列网格。此参数与 waterflow 的cross-axis-count默认 2语义一致可视作网格的“列数”main-axis-gap / cross-axis-gap间距分别控制行间距与列间距单位px。二者为 0 时元素紧贴排列需要留白时给出具体数值即可padding内边距长度为 4 的数组顺序固定为top、right、bottom、left。例如padding[10, 5, 10, 5]表示上下 10px、左右 5px 的内边距max-cross-axis-extent交叉轴元素最大范围限制交叉轴方向元素的最大尺寸可用于约束瀑布流中单列子项的最大宽度/高度范围帮助控制整体布局形态。三、实战示例aligned 等高校对网格aligned模式下每行高度由该行中最高子节点决定形成规整的“行内等高”网格适合头像墙、图标矩阵、九宫格等整齐排列场景。声明式用法如下注意以grid-view为容器直接放置子节点template !-- #ifdef MP-WEIXIN -- grid-view typealigned :cross-axis-count3 :main-axis-gap8 :cross-axis-gap8 :padding[8, 8, 8, 8] view v-foritem in 9 :keyitem classcell text{{ item }}/text /view /grid-view !-- #endif -- /template style .cell { height: 120px; background-color: #66ccff; align-items: center; justify-content: center; } /style要点grid-view无需嵌套scroll-view即可完成多列自动排布行数由子节点数量按列数自动推算cross-axis-count3表示三列main-axis-gap与cross-axis-gap控制行/列间距padding控制容器内边距若需要横向/纵向滚动请将grid-view放入 scroll-view 中并配合固定高度使用。四、实战示例masonry 瀑布流masonry模式根据子元素自身高度自动落位实现错落有致的瀑布流适合图文卡片流、商品墙、笔记流等“等高不同、宽度一致”的展示场景template !-- #ifdef MP-WEIXIN -- grid-view typemasonry :cross-axis-count2 :main-axis-gap10 :cross-axis-gap10 :padding[10, 10, 10, 10] view v-for(item, index) in list :keyindex classcard :style{ height: item.height } text{{ item.title }}/text /view /grid-view !-- #endif -- /template script setup const list [ { title: 卡片A, height: 140 }, { title: 卡片B, height: 200 }, { title: 卡片C, height: 120 }, { title: 卡片D, height: 180 } ] /script使用masonry时的注意事项子节点宽度由grid-view按列数自动计算因此不要对子节点设置宽度相关样式只需通过高度或内容撑起各卡片的高度差异瀑布流效果即由高度差呈现高度计算可参考 waterflow 文档 中给出的同源公式((容器宽度 - 左右padding - 左右border) - (cross-axis-count - 1) * cross-axis-gap) / cross-axis-count即每列宽度由容器宽度扣除内边距与列间距后均分若子项中包含异步加载的图片如image组件的modewidthFix导致高度动态变化可能出现排版重排建议为卡片预留固定高度或占位参考 waterflow 文档 中关于动态高度导致布局抖动的同类风险提示。五、与 grid-builder 的对比与选型仓库中与grid-view同属微信 Skyline 系列的还有 grid-builder二者共享几乎相同的布局属性type、cross-axis-count、max-cross-axis-extent、main-axis-gap、cross-axis-gap、padding核心差异在于数据驱动与回收机制| 对比维度 | grid-view | grid-builder | | :- | :- | :- | | 子节点来源 | 直接书写子组件v-for 渲染 | 通过list属性传入数据 | | 数据属性 | 无 |list渲染列表、child-count完整列表长度不传则取list.length | | 回收事件 | 无 |itembuild列表项创建event.detail {index}、itemdispose列表项回收event.detail {index} | | 适用场景 | 中短列表、结构简单 | 长列表、大数据量、需要复用与回收控制的场景 |从 grid-builder 文档 可以看到grid-builder是更接近虚拟列表的“构建器”形态它把数据与子项渲染交给listchild-count驱动并通过itembuild/itemdispose事件感知每一项的创建与回收方便开发者做按需渲染与资源清理。因此数据量小、追求写法简洁 → 选grid-view数据量大、需要回收复用与构建事件管控 → 选grid-builder可类比 list-view 在列表容器中的角色。六、与其他平台的瀑布流waterflow 对照若目标平台是 AppAndroid / iOS或 HarmonyOS而不是微信小程序则网格/瀑布流应使用 waterflowwaterflow的兼容性为Android 4.41、iOS 4.41、HarmonyOS(VDOM) 4.81、HarmonyOS(Vapor) 5.02Web 与微信小程序均不支持——与grid-view恰好互补waterflow仅支持flow-item作为子组件只支持竖向滚动其cross-axis-count默认 2、main-axis-gap/cross-axis-gap默认 0padding默认[0,0,0,0]参见 waterflow 文档底层实现上waterflow与list-view基本一致子组件滑出屏幕即回收复用性能优于scroll-view适合 App 端多元素瀑布流长列表waterflow 文档。因此一份需要“微信小程序 App 双端瀑布流”的代码通常的做法是微信小程序端用grid-view#ifdef MP-WEIXINApp 端用waterflow#ifndef MP-WEIXIN两端共享同一份数据模型与卡片样式。七、使用前提与常见注意事项基础库版本微信小程序基础库需≥ 4.41低版本不会渲染该组件务必在项目最低版本设置中同步约束Skyline 渲染器grid-view是 Skyline 能力需要页面运行在 Skyline 渲染模式下请在页面 json 中声明renderer: skyline或全局配置后再使用跨端兼容除微信小程序外grid-view在 Web、Android、iOS、HarmonyOS 均不可用请勿在非微信小程序代码路径中直接引用避免编译报错或运行空白宽度由组件接管masonry模式下子节点宽度由列数、间距与内边距自动计算不要为子节点设置宽度只控制高度即可动态高度风险子节点内容异步加载导致高度突变时瀑布流可能触发重排建议固定卡片高度或使用占位图避免布局抖动大列表场景当列表很长、需要回收复用与构建事件时优先评估 grid-builder微信 Skyline或 waterflowApp而不是用grid-view硬扛。八、参考资料grid-view 组件文档本文主依据grid-builder 组件文档数据驱动网格构建器waterflow 组件文档App/HarmonyOS 端瀑布流容器组件文档目录grid-view归属「微信专用组件 · Skyline」分类说明以上兼容性、属性与合法值均以当前仓库 grid-view 文档 为准使用前请以项目实际依赖的 uni-app / 微信基础库版本核对。【免费下载链接】uni-appA cross-platform framework using Vue.js项目地址: https://gitcode.com/gh_mirrors/un/uni-app创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考