​
App Inventor 2 ListView列表自定义教程

覆盖：简单列表、图文列表、多行布局、动态数据绑定、搜索过滤。

​
一、ListView两种数据方式

方式适用场景支持图片
元素字串（ElementsFromString）简单文字列表❌
列表数据（ListData）+ 布局图文列表、多行✅

​
二、简单文字列表

​
2.1 静态设置

// 方式一：逗号分隔字符串
设置 列表显示框1.元素字串 = "苹果,香蕉,橙子,葡萄,西瓜"

// 方式二：列表
设置 列表显示框1.元素 = 创建列表("苹果", "香蕉", "橙子", "葡萄", "西瓜")

​
2.2 动态加载

初始化全局变量 商品列表 = []

当 Screen1.初始化 时
  // 从网络加载数据
  调用 Web客户端1.发送GET请求("https://api.example.com/products")

当 Web客户端1.获得文本 时（URL, 响应码, 响应类型, 响应内容）
  初始化局部变量 数据 = 调用 字典.JSON转字典(响应内容)
  初始化局部变量 列表 = 获取键的值(数据, "items", [])
  
  // 提取名称列表
  初始化局部变量 名称列表 = []
  对于 每个 项 在 列表 中
    调用 追加列表项(名称列表, 获取键的值(项, "name", ""))
  
  设置 全局变量 商品列表 = 列表
  设置 列表显示框1.元素 = 名称列表

// 点击列表项
当 列表显示框1.选择完成 时
  初始化局部变量 索引 = 列表显示框1.选择索引
  初始化局部变量 选中项 = 选择列表项(全局变量 商品列表, 索引)
  
  // 跳转到详情页
  调用 打开另一屏幕并传值("DetailScreen",
    调用 字典.字典转JSON(选中项))

​
三、图文列表（高级布局）

​
3.1 布局类型

布局名称显示效果
MainText单行文字
MainText,DetailText(vertical)主标题 + 副标题（上下）
MainText,DetailText(horizontal)主标题 + 副标题（左右）
Image,MainText左图 + 右文字
Image,MainText,DetailText左图 + 右侧主副标题

​
3.2 代码块设置图文列表

当 Screen1.初始化 时
  // 设置布局类型
  设置 列表显示框1.列表视图布局 = "Image,MainText,DetailText"
  
  // 构建列表数据（JSON格式）
  初始化局部变量 列表数据 = []
  
  // 添加每一项
  调用 追加列表项(列表数据, 创建字典(
    键值对("Image1", "apple.png"),       // 图片（项目内媒体文件名）
    键值对("MainText", "苹果"),           // 主标题
    键值对("DetailText", "新鲜进口，¥5.8/斤")  // 副标题
  ))
  调用 追加列表项(列表数据, 创建字典(
    键值对("Image1", "banana.png"),
    键值对("MainText", "香蕉"),
    键值对("DetailText", "产地：广西，¥3.2/斤")
  ))
  
  // 设置列表数据
  设置 列表显示框1.列表数据 = 调用 字典.字典转JSON(列表数据)

​
3.3 从网络API加载图文列表

当 Web客户端1.获得文本 时（URL, 响应码, 响应类型, 响应内容）
  初始化局部变量 API数据 = 调用 字典.JSON转字典(响应内容)
  初始化局部变量 商品列表 = 获取键的值(API数据, "products", [])
  
  初始化局部变量 列表数据 = []
  对于 每个 商品 在 商品列表 中
    调用 追加列表项(列表数据, 创建字典(
      键值对("Image1", 获取键的值(商品, "image_url", "")),
      键值对("MainText", 获取键的值(商品, "name", "")),
      键值对("DetailText", 合并字符串(
        "¥", 获取键的值(商品, "price", "0"),
        "  库存：", 获取键的值(商品, "stock", "0")
      ))
    ))
  
  设置 列表显示框1.列表数据 = 调用 字典.字典转JSON(列表数据)

​
四、列表样式自定义

// 背景色
设置 列表显示框1.背景颜色 = 白色

// 分割线
设置 列表显示框1.分割线颜色 = 0xFFEEEEEE    // 浅灰色
设置 列表显示框1.分割线厚度 = 1

// 元素圆角
设置 列表显示框1.元素圆角半径 = 8

// 元素边距
设置 列表显示框1.元素边距宽度 = 8

// 字体大小
设置 列表显示框1.字体大小 = 16
设置 列表显示框1.详细文本字体大小 = 13

// 文字颜色
设置 列表显示框1.文字颜色 = 黑色
设置 列表显示框1.详细文本颜色 = 0xFF757575    // 灰色

// 选中颜色
设置 列表显示框1.选中颜色 = 0xFFE3F2FD    // 浅蓝色

​
五、搜索过滤

初始化全局变量 全量数据 = []    // 保存完整数据
初始化全局变量 过滤数据 = []    // 当前显示数据

// 搜索框输入时过滤
当 文本输入框_搜索.文本改变 时
  初始化局部变量 关键词 = 转换为小写(文本输入框_搜索.文本)
  
  如果 关键词 = "" 则
    设置 全局变量 过滤数据 = 全局变量 全量数据
  否则
    设置 全局变量 过滤数据 = []
    对于 每个 项 在 全局变量 全量数据 中
      初始化局部变量 名称 = 转换为小写(获取键的值(项, "name", ""))
      如果 在文本中查找(名称, 关键词) > 0 则
        调用 追加列表项(全局变量 过滤数据, 项)
  
  调用 刷新列表显示(全局变量 过滤数据)

// 刷新列表显示
定义 刷新列表显示(数据列表)
  初始化局部变量 列表数据 = []
  对于 每个 项 在 数据列表 中
    调用 追加列表项(列表数据, 创建字典(
      键值对("MainText", 获取键的值(项, "name", "")),
      键值对("DetailText", 获取键的值(项, "desc", ""))
    ))
  设置 列表显示框1.列表数据 = 调用 字典.字典转JSON(列表数据)

​
六、常见问题

​
Q1：ListView在可滚动Screen中不显示？

官方警告：不要在可滚动Screen中将ListView高度设为”充满父级”。 解决方案：
  • 给ListView设置固定高度
  • 或关闭Screen的可滚动属性，改用垂直布局的可滚动

​
Q2：图片不显示？

  • 图片文件必须添加到项目媒体资源中
  • 网络图片URL需要以 http:// 或 https:// 开头
  • 检查图片格式（支持PNG、JPG、GIF）

​
Q3：如何获取点击项的完整数据？

当 列表显示框1.选择完成 时
  初始化局部变量 索引 = 列表显示框1.选择索引
  // 从原始数据列表中取对应项
  初始化局部变量 选中数据 = 选择列表项(全局变量 全量数据, 索引)

​
参考资料

文档版本：2026.03 | 作者：App Inventor 2 中文网 www.fun123.cn

​
参考资料与版权声明

​
原文来源

​
版权声明

本文档基于 MIT App Inventor 官方文档及社区资源整理，版权归原作者所有：
  • MIT App Inventor 官方文档采用 CC BY-SA 4.0 授权
  • MIT App Inventor Community 帖子版权归原作者所有
本文档由 ai2claw 🐝 整理，仅供学习参考，如有侵权请联系删除。