Loop 循环数据绑定

📋 更新历史

日期	版本	更新内容
2025-12	v1.2.0	Loop 循环数据绑定语法（增强版）

Loop 循环数据绑定是 PSUIP 1.2.0 引入的强大特性，通过 <loop> 标签实现列表数据的自动循环渲染，支持复杂的数据映射和事件绑定。

什么是 Loop 循环

Loop 循环允许你将一个数据数组自动渲染为多个 UI 元素，每个数组项对应一个UI实例。这在展示评论列表、产品列表、动态信息等场景中非常有用。

基本语法

标准格式


<componentName>
  <title>列表标题</title>
  <subtitle>列表副标题</subtitle>
  <loop data="dataKey" nativeEvent="click">
    <groupName>
      <slotName key="fieldName"></slotName>
      <anotherSlot key="anotherField"></anotherSlot>
    </groupName>
  </loop>
</componentName>

语法说明

属性	必需	说明
`data`	是	指定绑定的数据数组的键名
`nativeEvent`	否	指定原生事件类型（如 `click`）
`key`	是	在插槽标签上使用，指定数据字段映射
`<groupName>`	建议	内部 group 标签，明确指定哪部分是循环模板

简单示例

示例 1：评论列表


<commentStyleListCard>
  <title>项目动态</title>
  <subtitle>最新 3 条更新 · 自动排列列表项</subtitle>
  <loop data="comments" nativeEvent="click">
    <itemContent>
      <avatar src="avatarUrl" key="avatarUrl"></avatar>
      <name key="approveAuditorName"></name>
      <text key="applyDeptName"></text>
      <desc key="orderSummary"></desc>
      <timestamp key="beginTime"></timestamp>
    </itemContent>
  </loop>
</commentStyleListCard>

对应的数据结构：


{
  comments: [
    {
      avatarUrl: "https://example.com/avatar1.jpg",
      approveAuditorName: "张三",
      applyDeptName: "技术部",
      orderSummary: "完成了代码审查",
      beginTime: "2025-03-10 10:30"
    },
    {
      avatarUrl: "https://example.com/avatar2.jpg",
      approveAuditorName: "李四",
      applyDeptName: "产品部",
      orderSummary: "提交了新需求",
      beginTime: "2025-03-10 11:15"
    },
    {
      avatarUrl: "https://example.com/avatar3.jpg",
      approveAuditorName: "王五",
      applyDeptName: "设计部",
      orderSummary: "更新了设计稿",
      beginTime: "2025-03-10 14:20"
    }
  ]
}

渲染结果：

上述 PSUIP 代码会自动生成 3 个评论项，每个项包含头像、姓名、部门、描述和时间戳。

示例 2：简易循环（无 group 标签）


<commentListCard>
  <loop data="loopData" nativeEvent="click">
    <title key="title"></title>
    <desc key="desc"></desc>
  </loop>
</commentListCard>

对应的数据结构：


{
  loopData: [
    {
      title: "项目启动",
      desc: "项目正式启动，团队开始工作"
    },
    {
      title: "需求评审",
      desc: "完成产品需求评审会议"
    },
    {
      title: "设计完成",
      desc: "UI/UX 设计稿已完成"
    }
  ]
}

数据绑定说明

key 属性

key 属性用于指定插槽与数据字段的映射关系：


<name key="userName"></name>
<!-- 从数据对象中取 userName 字段的值 -->

支持的字段类型

字符串字段：key="fieldName"
数字字段：key="count"
URL 字段：key="imageUrl" （配合 src 属性使用）
嵌套字段：key="user.profile.name" （支持点号访问）

src 属性与 key 属性

对于图片和头像，通常需要同时使用 src 和 key：


<avatar src="avatarUrl" key="avatarUrl"></avatar>

src：指定数据字段名
key：指定绑定的数据键（通常与 src 相同）

事件绑定

nativeEvent 属性

通过 nativeEvent 属性为每个循环项添加事件：


<loop data="products" nativeEvent="click">
  <itemContent>
    <title key="productName"></title>
    <price key="productPrice"></price>
  </itemContent>
</loop>

效果：

每个产品项都可以点击
点击时触发相应的事件处理
事件参数包含当前项的数据

支持的事件类型

click - 点击事件
hover - 悬停事件（部分支持）
其他原生事件（根据运行时支持）

Group 标签

为什么需要 Group

Group 标签（如 <itemContent>）明确指定哪部分是循环模板，使结构更清晰：


<loop data="items">
  <itemContent>
    <!-- 这部分会被重复渲染 -->
    <title key="title"></title>
    <desc key="desc"></desc>
  </itemContent>
</loop>

完整示例

招聘推荐列表


<layout:row>
  <layout:column flex="2">
    <hiringNewTitleCard>
      <title>人才筛选详情</title>
      <desc>负责核心算法模型的设计、优化与落地</desc>
      <badge>算法工程师</badge>
    </hiringNewTitleCard>
    
    <commentStyleListCard>
      <title>推荐候选人</title>
      <subtitle>系统匹配的优质人才</subtitle>
      <loop data="candidates" nativeEvent="click">
        <itemContent>
          <avatar src="avatar" key="avatar"></avatar>
          <name key="name"></name>
          <text key="university"></text>
          <desc key="reason"></desc>
          <badge key="matchScore"></badge>
        </itemContent>
      </loop>
    </commentStyleListCard>
  </layout:column>
  
  <layout:column flex="1">
    <hiringNewPersonCard>
      <title>杭州电子科技大学</title>
      <name>张忠元</name>
      <badge>推荐原因</badge>
      <desc>他具备扎实的数学与计算机基础，对机器学习、深度学习及优化算法有系统掌握...</desc>
    </hiringNewPersonCard>
  </layout:column>
</layout:row>

数据：


{
  candidates: [
    {
      avatar: "https://images.unsplash.com/photo-1.jpg",
      name: "张逸杰",
      university: "清华大学",
      reason: "他在算法优化与模型调参方面有出色表现",
      matchScore: "95分"
    },
    {
      avatar: "https://images.unsplash.com/photo-2.jpg",
      name: "李明",
      university: "北京大学",
      reason: "多年深度学习项目经验，擅长模型优化",
      matchScore: "92分"
    },
    {
      avatar: "https://images.unsplash.com/photo-3.jpg",
      name: "王芳",
      university: "浙江大学",
      reason: "在NLP和计算机视觉领域有突出成果",
      matchScore: "90分"
    }
  ]
}

最佳实践

1. 明确数据结构

在使用 Loop 前，先明确数据结构：


// 好：清晰的数据结构
{
  products: [
    { name: "产品A", price: 99 },
    { name: "产品B", price: 199 }
  ]
}
 
// 不好：结构不一致
{
  products: [
    { name: "产品A", price: 99 },
    { title: "产品B", cost: 199 }  // 字段名不一致
  ]
}

2. 使用有意义的 key 名称


<!-- 好 -->
<name key="userName"></name>
<desc key="userBio"></desc>
 
<!-- 不推荐 -->
<name key="n"></name>
<desc key="d"></desc>

3. 合理使用 Group

对于复杂组件，使用 Group 使结构清晰：


<!-- 推荐 -->
<loop data="items">
  <itemContent>
    <title key="title"></title>
    <desc key="desc"></desc>
  </itemContent>
</loop>
 
<!-- 简单场景可以省略 -->
<loop data="items">
  <title key="title"></title>
</loop>

4. 添加必要的事件

根据交互需求添加事件：


<!-- 可点击的列表项 -->
<loop data="items" nativeEvent="click">
  ...
</loop>
 
<!-- 仅展示的列表 -->
<loop data="items">
  ...
</loop>

5. 控制循环数量

避免一次渲染过多项，影响性能：


// 好：合理的数量
{
  items: [...20_items]  // 适中
}
 
// 不推荐：数量过多
{
  items: [...1000_items]  // 可能影响性能
}

对于大量数据，考虑：

分页加载
虚拟滚动
懒加载

常见错误

1. data 属性拼写错误


<!-- 错误 -->
<loop date="items">
  ...
</loop>
 
<!-- 正确 -->
<loop data="items">
  ...
</loop>

2. key 字段不存在


<!-- 数据中没有 productTitle 字段 -->
<loop data="products">
  <title key="productTitle"></title>  <!-- 错误 -->
</loop>
 
<!-- 正确：使用存在的字段 -->
<loop data="products">
  <title key="name"></title>
</loop>

3. 忘记闭合 loop 标签


<!-- 错误 -->
<loop data="items">
  <title key="title"></title>
 
<!-- 正确 -->
<loop data="items">
  <title key="title"></title>
</loop>

4. Group 标签名称错误


<!-- 错误：组件不支持此 group 名称 -->
<loop data="items">
  <wrongGroupName>
    ...
  </wrongGroupName>
</loop>
 
<!-- 正确：使用组件支持的名称 -->
<loop data="items">
  <itemContent>
    ...
  </itemContent>
</loop>

Loop 循环让列表数据的渲染变得简单而强大！