布局与渲染

VirtualViewList 支持三种布局模式，提供灵活的渲染方向和间距配置，满足各类 UI 设计需求。

布局模式

1. 垂直布局（VERTICAL）

配置项	说明	推荐值
layoutType	ViewLayoutType.VERTICAL	-
verticalRenderDirection	渲染方向	TOP_TO_BOTTOM
itemSpacing	项间距	10
paddingTop / paddingBottom	上下内边距	10 / 10

适用场景：排行榜、消息列表、背包、设置页

渲染方向：

• TOP_TO_BOTTOM：从上往下（常用）
• BOTTOM_TO_TOP：从下往上（聊天窗口、评论区）

2. 水平布局（HORIZONTAL）

配置项	说明	推荐值
layoutType	ViewLayoutType.HORIZONTAL	-
horizontalRenderDirection	渲染方向	LEFT_TO_RIGHT
itemSpacing	项间距	10
paddingLeft / paddingRight	左右内边距	10 / 10

适用场景：轮播图、关卡选择、横向标签页

渲染方向：

• LEFT_TO_RIGHT：从左往右（常用）
• RIGHT_TO_LEFT：从右往左（阿拉伯语等 RTL 布局）

3. 网格布局（GRID）

垂直滚动网格（常用）

配置项	说明	推荐值
layoutType	ViewLayoutType.GRID	-
scrollDirection	ScrollDirection.VERTICAL	-
cols	列数	3
girdVertRowsSpacing	行间距	10
girdVertColsSpacing	列间距	10
paddingTop / paddingBottom	上下内边距	10 / 10

适用场景：商品网格、图片墙、图标选择器

水平滚动网格

配置项	说明	推荐值
layoutType	ViewLayoutType.GRID	-
scrollDirection	ScrollDirection.HORIZONTAL	-
rows	行数	2
girdHoriRowsSpacing	行间距	10
girdHoriColsSpacing	列间距	10
paddingLeft / paddingRight	左右内边距	10 / 10

适用场景：横向推荐卡片、多行关卡选择

快速配置指南

场景 1：聊天消息列表

Layout Type: VERTICAL
Vertical Render Direction: BOTTOM_TO_TOP
Item Spacing: 8
Padding Top: 20
Padding Bottom: 20
Cache Ratio: 0.2（消息较多时）

场景 2：商店商品网格（3 列）

Layout Type: GRID
Scroll Direction: VERTICAL
Cols: 3
Gird Vert Rows Spacing: 15
Gird Vert Cols Spacing: 10
Padding Top: 10
Padding Bottom: 10
Cache Ratio: 0.2

场景 3：横向关卡选择（2 行）

Layout Type: GRID
Scroll Direction: HORIZONTAL
Rows: 2
Gird Hori Rows Spacing: 10
Gird Hori Cols Spacing: 20
Padding Left: 20
Padding Right: 20
Cache Ratio: 0.15

动态尺寸支持

单项尺寸调整

非网格模式下，支持单独调整每项的尺寸（垂直布局调整高度，水平布局调整宽度）：

// 动态调整第 5 项的高度为 150
list.UpdateItemSize(5, 150);

// 会自动重新布局后续项

批量自定义尺寸

在加载数据时指定每项的尺寸：

// 数据类型列表
const types = Array(100).fill('default');

// 自定义每项高度（垂直布局）或宽度（水平布局）
const customSizes = [
  80,   // 第 0 项高度 80
  120,  // 第 1 项高度 120
  100,  // 第 2 项高度 100
  // ...
];

list.ReloadData(types, customSizes);

适用场景：

• 聊天消息（文字长度不同）
• 动态高度列表（内容展开/收起）
• 图片瀑布流

注意事项：

• 网格模式下所有项尺寸必须相同，不支持自定义
• 动态尺寸会略微增加计算开销，数据量 > 10000 时需注意性能

间距配置详解

垂直/水平布局

┌─────────────────────────────────┐
│ paddingTop                      │
│  ┌─────────────────────────┐   │
│  │      Item 0             │   │
│  └─────────────────────────┘   │
│           itemSpacing           │
│  ┌─────────────────────────┐   │
│  │      Item 1             │   │
│  └─────────────────────────┘   │
│ paddingBottom                   │
└─────────────────────────────────┘

网格布局（垂直滚动）

┌──────────────────────────────────────┐
│ paddingTop                           │
│  ┌────┐ colSpacing ┌────┐ ┌────┐   │
│  │ 0  │            │ 1  │ │ 2  │   │
│  └────┘            └────┘ └────┘   │
│         rowSpacing                  │
│  ┌────┐            ┌────┐ ┌────┐   │
│  │ 3  │            │ 4  │ │ 5  │   │
│  └────┘            └────┘ └────┘   │
│ paddingBottom                        │
└──────────────────────────────────────┘

配置更新

修改布局配置后，需手动触发更新：

// 修改配置
list['itemSpacing'] = 20;
list['paddingTop'] = 30;

// 方式 1：重新加载数据（推荐）
list.ReloadData(types);

// 方式 2：手动刷新布局
list.Refresh();

性能建议

布局类型	推荐 cacheRatio	说明
垂直列表	0.1 - 0.2	普通列表
水平列表	0.15 - 0.25	横向滚动速度通常较快
网格布局	0.2 - 0.3	单屏项数多，建议更大缓冲
动态高度	0.15 - 0.2	计算开销较大，适度缓存

更多性能优化技巧请参考 性能优化。