uni-app 微信小程序 grid-view 组件指南：Skyline 网格与瀑布流布局-育师

uni-app 微信小程序 grid-view 组件指南：Skyline 网格与瀑布流布局

【免费下载链接】uni-appA cross-platform framework using Vue.js项目地址: https://gitcode.com/gh_mirrors/un/uni-app

uni-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 的合法值

| 合法值 | 兼容性 | 描述 | | :- | :-: | :- | | 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 type="aligned" :cross-axis-count="3" :main-axis-gap="8" :cross-axis-gap="8" :padding="[8, 8, 8, 8]" > <view v-for="item in 9" :key="item" class="cell"> <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-count="3"表示三列；main-axis-gap与cross-axis-gap控制行/列间距；padding控制容器内边距；
若需要横向/纵向滚动，请将grid-view放入 scroll-view 中，并配合固定高度使用。

四、实战示例：masonry 瀑布流

masonry模式根据子元素自身高度自动落位，实现错落有致的瀑布流，适合图文卡片流、商品墙、笔记流等“等高不同、宽度一致”的展示场景：

<template> <!-- #ifdef MP-WEIXIN --> <grid-view type="masonry" :cross-axis-count="2" :main-axis-gap="10" :cross-axis-gap="10" :padding="[10, 10, 10, 10]" > <view v-for="(item, index) in list" :key="index" class="card" :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组件的mode="widthFix"）导致高度动态变化，可能出现排版重排，建议为卡片预留固定高度或占位，参考 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是更接近虚拟列表的“构建器”形态：它把数据与子项渲染交给list+child-count驱动，并通过itembuild/itemdispose事件感知每一项的创建与回收，方便开发者做按需渲染与资源清理。因此：

数据量小、追求写法简洁 → 选grid-view；
数据量大、需要回收复用与构建事件管控 → 选grid-builder（可类比 list-view 在列表容器中的角色）。

六、与其他平台的瀑布流：waterflow 对照

若目标平台是 App（Android / iOS）或 HarmonyOS，而不是微信小程序，则网格/瀑布流应使用 waterflow：

waterflow的兼容性为：Android 4.41、iOS 4.41、HarmonyOS(VDOM) 4.81、HarmonyOS(Vapor) 5.02，Web 与微信小程序均不支持——与grid-view恰好互补；
waterflow仅支持flow-item作为子组件，只支持竖向滚动，其cross-axis-count默认 2、main-axis-gap/cross-axis-gap默认 0，padding默认[0,0,0,0]（参见 waterflow 文档）；
底层实现上，waterflow与list-view基本一致，子组件滑出屏幕即回收复用，性能优于scroll-view，适合 App 端多元素瀑布流长列表（waterflow 文档）。

因此，一份需要“微信小程序 + App 双端瀑布流”的代码，通常的做法是：微信小程序端用grid-view（#ifdef MP-WEIXIN），App 端用waterflow（#ifndef MP-WEIXIN），两端共享同一份数据模型与卡片样式。

七、使用前提与常见注意事项

基础库版本：微信小程序基础库需≥ 4.41，低版本不会渲染该组件，务必在项目最低版本设置中同步约束；
Skyline 渲染器：grid-view是 Skyline 能力，需要页面运行在 Skyline 渲染模式下，请在页面 json 中声明"renderer": "skyline"（或全局配置）后再使用；
跨端兼容：除微信小程序外，grid-view在 Web、Android、iOS、HarmonyOS 均不可用，请勿在非微信小程序代码路径中直接引用，避免编译报错或运行空白；
宽度由组件接管：masonry模式下子节点宽度由列数、间距与内边距自动计算，不要为子节点设置宽度，只控制高度即可；
动态高度风险：子节点内容异步加载导致高度突变时，瀑布流可能触发重排，建议固定卡片高度或使用占位图，避免布局抖动；
大列表场景：当列表很长、需要回收复用与构建事件时，优先评估 grid-builder（微信 Skyline）或 waterflow（App），而不是用grid-view硬扛。