DynamicRecycler 拓展：高效动态列表

• DynamicRecycler 拓展
• 快速开始（推荐）
  • 一键创建列表
  • 四种一键方法
  • 更新数据
  • 启用智能更新
• 详细用法
  • 网格列表示例
  • 瀑布流示例（不等高图片墙）
  • 多类型列表（聊天界面）
  • 滚动控制
  • 空视图
• 方法
  • 一键 Setup（推荐）
  • 数据操作
  • 滚动
  • 创建和构建（分步方式）
  • 回调设置
  • 布局管理器
  • DiffUtil（高级）
  • 通知更新（不用 DiffUtil 时）
  • 其他
• 属性
  • 便捷属性（作用于最后创建的组件）
  • 常量
• 过程签名参考
• 注意事项
• 版本信息

« 返回首页

DynamicRecycler 拓展

基于 Android RecyclerView 的高效列表渲染组件。相比传统 ListView，支持数千条数据流畅滚动，提供线性、网格、瀑布流等多种布局方式。

核心特性：

• 高效视图回收，轻松处理大量数据
• 三种布局：垂直列表、网格、瀑布流
• DiffUtil 智能差异更新（自动动画）
• 多类型列表支持

• 滚动监听和空视图

• .aix 拓展下载：

cn.fun123.DynamicRecycler.aix

快速开始（推荐）

一键创建列表

使用 SetupVerticalList 等方法，一步完成创建+布局+回调+数据绑定：

当 Screen1.Initialize 时：
  设置 全局变量 dataList 为 [创建列表]("苹果", "香蕉", "橙子", "葡萄")

  // 一键创建垂直列表
  调用 DynamicRecycler1.SetupVerticalList("myList", VerticalArrangement1, "CreateItem", "BindData", 全局变量 dataList, 8)

// 创建列表项视图（过程）
定义过程 CreateItem(id, root, viewType) 返回结果：
  调用 DynamicLabel1.Create("label", root)
  设置 DynamicLabel1.Width 为 -2    // FillParent
  设置 DynamicLabel1.Padding 为 12
  返回 true

// 绑定数据到视图（过程）
定义过程 BindData(id, position, root, viewType)：
  设置 局部变量 text 为 [选择列表项] 全局变量 dataList 索引 position
  调用 DynamicLabel1.UseComponentInContainer("label", root)
  设置 DynamicLabel1.Text 为 text

四种一键方法

更新数据

当 ButtonRefresh.Click 时：
  设置 全局变量 dataList 为 [新数据列表]
  调用 DynamicRecycler1.RefreshData(全局变量 dataList)

启用智能更新

启用后数据更新会自动计算差异并添加动画，无需手动设置比较器：

当 Screen1.Initialize 时：
  调用 DynamicRecycler1.SetupVerticalList("myList", VerticalArrangement1, "CreateItem", "BindData", 全局变量 dataList, 8)
  设置 DynamicRecycler1.SmartUpdate 为 true

// 之后用 RefreshData 更新时自动差异比较+动画

详细用法

网格列表示例

当 Screen1.Initialize 时：
  设置 全局变量 images 为 [创建列表]("img1.png", "img2.png", "img3.png", "img4.png", "img5.png", "img6.png")

  // 一键创建 2 列网格
  调用 DynamicRecycler1.SetupGridList("imageGrid", VerticalArrangement1, 2, "CreateImageItem", "BindImageData", 全局变量 images, 4)

定义过程 CreateImageItem(id, root, viewType) 返回结果：
  调用 DynamicImage1.Create("img", root)
  设置 DynamicImage1.Width 为 -2
  设置 DynamicImage1.Height 为 150
  返回 true

定义过程 BindImageData(id, position, root, viewType)：
  设置 局部变量 path 为 [选择列表项] 全局变量 images 索引 position
  调用 DynamicImage1.UseComponentInContainer("img", root)
  设置 DynamicImage1.Picture 为 path

瀑布流示例（不等高图片墙）

当 Screen1.Initialize 时：
  // 一键创建 3 列瀑布流
  调用 DynamicRecycler1.SetupStaggeredList("photoWall", VerticalArrangement1, 3, "CreatePhoto", "BindPhoto", 全局变量 photos, 4)

多类型列表（聊天界面）

使用分步方式 + SetViewTypeProvider：

当 Screen1.Initialize 时：
  设置 全局变量 messages 为 [创建列表](
    [创建列表]("receive", "你好！"),
    [创建列表]("send", "你好，有什么可以帮你的？"),
    [创建列表]("receive", "想了解一下产品信息")
  )

  // 步骤 1: 创建 RecyclerView
  调用 DynamicRecycler1.Create("chat", VerticalArrangement1)

  // 步骤 2: 设置从末尾堆叠的线性布局
  设置 DynamicRecycler1.LayoutManager 为 调用 DynamicRecycler1.CreateLinearManager(false, false, true, 4)

  // 步骤 3: 设置多类型回调
  设置 DynamicRecycler1.ViewProvider 为 "CreateChatItem"
  设置 DynamicRecycler1.ViewEditor 为 "BindChatItem"
  调用 DynamicRecycler1.SetViewTypeProvider(调用 DynamicRecycler1.GetLastComponent, "GetChatType")

  // 步骤 4: 构建
  调用 DynamicRecycler1.Build(调用 DynamicRecycler1.GetLastComponent, 全局变量 messages)

定义过程 GetChatType(id, position) 返回结果：
  设置 局部变量 msg 为 [选择列表项] 全局变量 messages 索引 position
  如果 [选择列表项] msg 索引 1 = "send" 那么：
    返回 1
  否则：
    返回 2

定义过程 CreateChatItem(id, root, viewType) 返回结果：
  调用 DynamicLabel1.Create("bubble", root)
  设置 DynamicLabel1.Padding 为 12
  如果 viewType = 1 那么：
    设置 DynamicLabel1.BackgroundColor 为 [蓝色]
    设置 DynamicLabel1.TextColor 为 [白色]
  否则：
    设置 DynamicLabel1.BackgroundColor 为 [浅灰色]
    设置 DynamicLabel1.TextColor 为 [黑色]
  返回 true

定义过程 BindChatItem(id, position, root, viewType)：
  设置 局部变量 msg 为 [选择列表项] 全局变量 messages 索引 position
  调用 DynamicLabel1.UseComponentInContainer("bubble", root)
  设置 DynamicLabel1.Text 为 [选择列表项] msg 索引 2

滚动控制

// 滚动到指定位置（作用于最后创建的组件）
DynamicRecycler1.ScrollToPosition(5)
// 平滑滚动（带动画）
DynamicRecycler1.SmoothScrollTo(1)
// 使用滚动监听
DynamicRecycler1.SetScrollStateListener(DynamicRecycler1.GetLastComponent, "OnScroll")
procedure OnScroll(id, scrollState) {
  if scrollState == DynamicRecycler1.ScrollStateIdle {
    标签1.Text = "滚动停止"
  }
}

空视图

DynamicRecycler1.SetEmptyComponent(DynamicRecycler1.GetLastComponent, LabelEmpty)
// 当数据为空时自动显示 LabelEmpty，有数据时自动隐藏

方法

一键 Setup（推荐）

SetupVerticalList(id, parent, viewProvider, viewEditor, data, spacing)

一键创建垂直列表。id: 唯一标识; parent: 父容器; viewProvider: 创建视图的过程名; viewEditor: 绑定数据的过程名（可为空）; data: 数据列表; spacing: 间距(dp)

SetupHorizontalList(id, parent, viewProvider, viewEditor, data, spacing)

一键创建水平滚动列表。参数同上

SetupGridList(id, parent, columns, viewProvider, viewEditor, data, spacing)

一键创建网格列表。columns: 列数

SetupStaggeredList(id, parent, columns, viewProvider, viewEditor, data, spacing)

一键创建瀑布流列表。columns: 列数

数据操作

RefreshData(newData)

更新数据列表（作用于最后创建的组件），自动检测智能更新模式

UpdateData(component, newData)

更新数据列表（指定组件）

EnableSmartUpdate(component)

启用智能差异更新（DiffUtil），无需手动设置比较器

滚动

ScrollToPosition(position)

滚动到指定位置（从 1 开始，作用于最后创建的组件），无动画

SmoothScrollToPosition(position)

平滑滚动到指定位置（从 1 开始，作用于最后创建的组件），带动画

ScrollTo(component, position)

滚动到指定位置（指定组件）

SmoothScrollTo(component, position)

平滑滚动到指定位置（指定组件）

创建和构建（分步方式）

Create(id, parent)

创建 RecyclerView 实例并添加到父容器

Build(component, dataList)

构建 RecyclerView 并绑定数据（必须先设置 ViewProvider 和 LayoutManager）

GetLastComponent()

获取最后创建的组件

回调设置

SetViewProvider(component, procedureName)

设置视图提供者过程。签名: procedure(id, root, viewType) — 在 root 容器中创建列表项视图

SetViewEditor(component, procedureName)

设置视图编辑器过程。签名: procedure(id, position, root, viewType) — 绑定数据到视图

SetViewTypeProvider(component, procedureName)

设置视图类型提供者（多类型列表）。签名: procedure(id, position) — 返回类型编号

布局管理器

SetLayoutManager(component, layoutManager)

设置布局管理器

CreateLinearManager(horizontal, reverseLayout, stackFromEnd, spacing)

创建线性布局管理器。stackFromEnd: 从末尾堆叠（适合聊天）

CreateGridManager(spanCount, horizontal, reverseLayout, spacing)

创建网格布局管理器

CreateStaggeredGridManager(spanCount, horizontal, reverseLayout, spacing)

创建瀑布流布局管理器

DiffUtil（高级）

SetContentComparator(component, procedureName)

设置内容比较器过程。签名: procedure(id, oldItem, newItem) — 返回 Boolean

SetItemComparator(component, procedureName)

设置项目比较器过程。签名: procedure(id, oldItem, newItem) — 返回 Boolean

UseDiffUtil(component, useDiffUtil)

启用/禁用 DiffUtil

通知更新（不用 DiffUtil 时）

NotifyDataSetChanged(component)

通知全部数据已变更

NotifyItemChanged(component, position)

通知指定位置已变更（从 1 开始）

NotifyItemInserted(component, position)

通知插入了新项（从 1 开始）

NotifyItemRemoved(component, position)

通知移除了项（从 1 开始）

其他

SetHasFixedSize(component, hasFixedSize)

设置固定大小（优化性能）

SetEmptyComponent(component, emptyComponent)

设置数据为空时显示的组件

GetComponentPosition(component, childComponent)

获取子组件在列表中的位置（从 1 开始）

CanScrollVertically(component, direction)

检查是否可以垂直滚动。direction: -1=上, 1=下

CanScrollHorizontally(component, direction)

检查是否可以水平滚动。direction: -1=左, 1=右

SetScrollStateListener(component, procedureName)

设置滚动状态监听器。签名: procedure(id, scrollState)

SetScrollChangedListener(component, procedureName)

设置滚动位置监听器。签名: procedure(id, x, y)

属性

便捷属性（作用于最后创建的组件）

ViewProvider

视图提供者过程名

ViewEditor

视图编辑器过程名

ViewTypeProvider

视图类型提供者过程名

LayoutManager

布局管理器

SmartUpdate

启用智能差异更新

DiffUtils

启用/禁用 DiffUtil

HasFixedSize

是否固定大小

EmptyComponent

空视图组件

常量

ScrollStateIdle

滚动状态：空闲，值为 0

ScrollStateDragging

滚动状态：拖拽中，值为 1

ScrollStateSettling

滚动状态：惯性滑动中，值为 2

Left

方向常量：左，值为 -1

Right

方向常量：右，值为 1

Top

方向常量：上，值为 -1

Bottom

方向常量：下，值为 1

过程签名参考

注意事项

• ViewProvider 过程中创建的动态组件 ID 在每个列表项内必须唯一
• 使用 UseComponentInContainer(id, root) 在 ViewEditor 中定位列表项内的组件
• 启用 SmartUpdate 后无需手动设置 ContentComparator
• spacing 参数单位为 dp，会自动转换为像素
• 位置参数（position）统一从 1 开始（符合 App Inventor 习惯）

版本信息

• 当前版本：1.0
• 功能：线性/网格/瀑布流布局、DiffUtil 智能更新、多类型列表、滚动监听、空视图
• 新增：SetupVerticalList/SetupGridList/SetupStaggeredList/SetupHorizontalList 一键方法、SmartUpdate 智能更新、RefreshData 简化更新
• 兼容性：App Inventor 2