Geejing WebBuilder View 列表组件全能力技术分享

前言

在企业管理系统、OA、CRM、生产台账、数据大屏等业务开发中，列表展示是最通用的基础交互场景：人员目录、菜单导航、单据清单、标签分类、分页数据、拖拽看板、多选勾选视图都依赖列表组件实现。传统前端开发实现多样化列表需要手写大量 HTML 模板、分页逻辑、拖拽事件、渲染适配、XSS 转义处理，重复代码多、兼容性差、多场景复用成本高。Geejing WebBuilder 内置统一 view 基础列表组件、listView/iconView/checkView 专用封装视图，一套组件支撑静态本地数据、远程分页接口、自定义模板、拖拽多选、网格流式布局、下拉菜单、动态增删改查等全部业务需求，全部通过可视化配置 + 少量脚本实现，无需手写完整前端渲染逻辑。

本文基于平台官方完整 Demo 源码，从组件分类、模板渲染方案、数据源模式、分页机制、交互能力、业务落地场景六大维度做完整技术拆解，适用于开发人员内部技术培训、组件实操学习、业务模块标准化开发规范制定。

一、View 系列组件整体架构与分类

平台视图组件分为底层通用容器与业务专用封装组件两层，分层清晰、能力互通：

1. 基础通用容器：view 组件

底层万能列表容器，无固定渲染样式，完全通过 itemTpl / itemTplFn 自定义 HTML 模板，支持任意布局：单列纵向、多列网格、横向流式、固定卡片。核心特性：

1. 支持静态本地 data、远程 url 接口双数据源；
2. 两套自定义渲染方案：字符串模板 itemTpl、函数渲染 itemTplFn；
3. 完整交互：单选 / 多选、框选、拖拽排序、右键菜单、动态增删更新；
4. 内置分页：本地缓存分页、远程滚动自动加载、上下反向分页；
5. 布局自由：通过 bodyCls 传入平台内置样式类实现 grid4、w-form、w-row 等流式排版。

2. 业务封装专用视图（开箱即用，无需手写模板）

1. listView 标准列表视图：自动渲染图标、标题、副标题、角标，内置多种展示模式（小列表 / 图标列表 / 大图标），搭配顶部工具栏快速切换视图样式；
2. iconView 图标宫格视图：网格布局图标 + 文字，适合功能导航、菜单模块；
3. checkView 勾选选择视图：单选 / 多选勾选框，适用于权限勾选、浏览器 / 标签多选筛选场景。

二、两种核心渲染模板方案：itemTpl 静态模板 vs itemTplFn 函数渲染

Demo 中完整演示了两套渲染方案，适配简单 / 复杂不同业务场景，同时包含官方强制 XSS 安全规范。

方案 1：itemTpl 字符串模板（轻量化场景首选）

直接书写 HTML 字符串，内置模板语法：变量插值、for 循环、if 判断、内置数据格式化方法，零 JS 函数即可完成简单列表渲染。示例片段：

itemTpl: "<div class="w-item w-border" style="display:grid;grid-template-columns:2em 8em 16em 1fr;padding:1em;gap:.5em">\n  <div>{num}</div>\n  <div>{[data.money.usd]}</div>\n  <div>{[data.date.dateTimeText12]}</div>\n  <div>{for data.array}{if index > 0}<span>, </span>{/if}<span>{[index + 1]}: </span><span>{[value]}</span>{/for}</div>\n</div>"

支持能力：

• 直接 {字段名} 读取数据；
• {[data.属性.方法]} 调用内置格式化（金额、日期）；
• {for} 循环数组、{if} 条件分支；适用场景：简单人员列表、菜单导航、单据简易卡片，快速开发、代码简洁。

方案 2：itemTplFn 函数渲染（复杂逻辑、安全可控推荐）

通过 JS 函数动态拼接 HTML，平台强制要求使用 Wb.toHTML() 对所有输出内容转义，杜绝 XSS 跨站脚本漏洞，企业级系统必备安全规范。核心规范源码示例：

itemTplFn(data, el){
    // 必须使用 Wb.toHTML 转义输出，防止XSS攻击
    let arrayText = '';
    data.array.forEach((item, i) => {
      if (i > 0)
        arrayText += '<span>, </span>';
      arrayText += '<span>' + (i + 1) + ': </span><span>' + Wb.toHTML(item) + '</span>';
    });
    return `<div class="w-item w-border">
      <div>${Wb.toHTML(data.num)}</div>
      <div>${Wb.toHTML(data.money.usd)}</div>
      <div>${arrayText}</div>
    </div>`;
}

优势：

1. 支持复杂循环、分支、数据预处理逻辑；
2. 统一 XSS 转义，符合政企等保、金融安全开发标准；
3. 可动态拼接 class、内联样式、自定义属性；适用场景：带复杂计算的财务单据、带操作按钮 / 右键菜单的业务列表、带多层数组嵌套的台账卡片。

模板开发选型规范

1. 简单静态菜单、基础人员清单 → itemTpl；
2. 财务数值、用户输入内容、带操作按钮、复杂嵌套数据 → itemTplFn；
3. 所有用户可输入展示字段，必须通过 Wb.toHTML() 转义输出。

三、三大数据源模式：本地静态 / 远程接口 / 缓存分页

View 组件统一兼容三类数据源，覆盖全部业务数据来源，切换仅需修改配置，无需重构渲染模板。

1. 本地静态数据 data /localData

页面初始化固定字典、导航菜单、固定选项使用，在 initialize 事件预加载全局数据，直接绑定至 view 组件。Demo 导航菜单示例：

initialize(options){
  Wb.apply(app, {
    viewData: [
      { icon: 'user', text: 'User Management' },
      { icon: 'support', text: 'Support Service' }
    ]
  });
}

优势：无接口请求、页面秒渲染，适合功能导航、固定分类标签。

2. 远程接口 url 动态拉取业务数据

对接服务端 serverScript 接口，通过 xaction 执行 SQL 查询，返回标准数组列表，适用于员工档案、客户台账、采购单据等动态业务数据。

url: "demo-source?xaction=staffDict"

配套分页参数：pageSize 每页条数、pagingBar 分页栏、autoPaging 滚动自动加载下一页。

3. cached 本地缓存分页

开启 cached:true 后，首次请求全部远程数据缓存至前端，分页在本地完成，减少重复接口请求，适合数据量不大、频繁切换分页的档案查询页面，提升页面响应速度。

分页四种业务实现方案

1. 标准底部分页栏 pagingBar:true；
2. 页码数字分页 pagingBar:"pageNums"；
3. 滚动到底自动加载 autoPaging:true（移动端外勤列表常用）；
4. 倒序加载（消息、日志）reverseData:true 滚动到顶部加载历史数据。

四、丰富交互能力：多选、拖拽、右键菜单、动态增删改

Demo 完整覆盖企业系统高频交互，全部配置化 + 少量事件脚本实现，无需底层封装。

1. 选择模式

• 单选：默认模式，点击条目选中；
• multiSelect:true 多选，支持 Ctrl 批量点选；
• rectSelect:true 鼠标框选批量条目，批量删除、批量导出场景；
• stickSelect:true 保持选中高亮，多表单联动筛选常用。

2. 条目右键操作菜单

监听条目内按钮点击，动态弹出 Menu 右键菜单，示例为每条右侧三点操作按钮：编辑、删除、详情。核心事件 click 判断点击目标 cid，获取当前行数据后弹出菜单：

events: {
  click(e, options){
    let view = this, target = e.target;
    if (target.closest('[cid=menu-btn]')) {
      let menu = app.viewContextMenu ??= new Wb.Menu({
        items: [{text: 'Item 1', handler(){Wb.tip(app.currentWrapViewData.text);}}]
      });
      app.currentWrapViewData = target.getClosestComp().data;
      menu.showBy(target);
    }
  }
}

3. 拖拽能力（看板、流程拖拽排序）

开启 draggable:true、droppable 跨容器拖拽，监听 itemdrop 事件获取拖拽源与目标数据，用于工单拖拽分配、分类看板、物料排序场景。

4. 动态增删改条目（顶部工具栏操作）

内置 API 极简操作列表数据，无需重新请求接口刷新：

1. addData({})：末尾新增条目；
2. insertData(index, {})：指定位置插入；
3. item.set('key',value) / item.update({})：修改当前行字段；
4. item.destroy() 单条删除、destroySelections() 批量删除选中项；对应 Demo 顶部工具栏 “新增 / 插入 / 更新 / 删除选中” 完整演示。

5. 条目内捕获点击（关闭标签、图标点击）

captureClass 捕获条目内部指定 class 元素点击，不触发整行选中，如标签右上角关闭按钮，直接销毁当前标签条目，适用于筛选标签组件。

五、多布局模式适配不同业务页面

通过 layout、bodyCls、自定义 item 内联 style 快速切换排版，一套组件适配导航、台账、卡片、标签四大布局。

1. column 单列纵向：标准单据列表、人员台账；
2. grid4 四列等宽宫格：功能导航、图标菜单 iconView；
3. w-form 自动换行流式：标签、筛选条目自适应换行；
4. w-row 横向不换行：横向滚动工单、多分类横向卡片；
5. 自定义固定宽度：item 模板内 style="width:10em" 统一卡片尺寸，保证布局整齐。

六、专用封装视图快速落地业务（listView /iconView/checkView）

无需手写 itemTpl，配置少量字段即可快速生成标准业务视图，开发效率大幅提升。

1. listView 通用业务清单指定 textField 主标题、subtextField 副标题，自动渲染图标、角标、状态标记，顶部工具栏切换大 / 小 / 图标多种展示样式，适用于客户列表、员工档案、设备台账。
2. iconView 功能导航宫格iconField 绑定图标字段，grid 网格布局，OA 首页功能菜单、系统模块导航首选。
3. checkView 多选勾选视图内置勾选框，value 双向绑定选中数组，用于权限配置、数据筛选、多选导出条件面板。

七、业务落地标准化场景总结

结合 View 组件完整能力，对应企业系统开发高频场景，给出标准化开发方案：

业务场景	推荐组件	核心配置方案
系统首页功能导航菜单	iconView + 本地静态 data	grid4 四列布局，静态预加载菜单数据
员工 / 客户 / 供应商台账列表	view /listView + url 远程接口	itemTplFn 渲染，分页栏，支持批量多选删除
工单拖拽看板、分类排序	view + draggable + droppable	开启拖拽监听 drop 事件，存储排序至后端
筛选标签、已选条件展示	view + captureClass 关闭按钮	w-form 自动换行布局，点击关闭删除条目
移动端外勤滚动加载清单	view + autoPaging 自动分页	单列 column 布局，滚动加载下一页
权限多选、分类筛选勾选面板	checkView	multiSelect 双向绑定 value 数组
财务单据卡片、带金额格式化	view + itemTplFn	Wb.toHTML 转义，内置金额 date 格式化
消息 / 操作日志倒序列表	view + reverseData	滚动到顶部加载历史数据

八、开发避坑与企业级规范

1. XSS 安全强制规范所有页面展示的用户输入内容，必须使用 Wb.toHTML() 转义，禁止直接拼接 data 文本，金融、政企系统上线前必须检查所有 itemTplFn。
2. 分页性能优化数据量小于 50 条开启 cached 本地缓存分页；上万条业务台账使用远程分页 + 滚动自动加载，避免一次性拉取大量数据卡顿。
3. 模板复用规范通用人员卡片、单据卡片抽离公共 itemTpl 字符串，在 module 初始化统一定义全局变量，多处 view 复用，减少重复代码。
4. 交互性能优化大量条目列表关闭不必要的框选、拖拽，仅保留业务必需交互；频繁刷新列表使用局部 item.update()，不重载全量数据。
5. 国产化多端适配View 组件渲染引擎原生适配国产浏览器、移动端，一套模板 PC / 手机自动适配，无需单独编写两套渲染模板。

九、总结

Geejing WebBuilder 的 View 系列视图组件实现了一套底层能力覆盖全行业列表类业务，统一解决传统前端开发列表渲染、分页、交互、安全、多布局的重复编码痛点：

1. 两种渲染模板兼顾简单快速开发与复杂安全业务场景；
2. 静态 / 远程 / 缓存三大数据源适配全部业务数据来源；
3. 内置多选、框选、拖拽、右键、动态增删全套交互，无需自研底层逻辑；
4. 配套 listView/iconView/checkView 封装组件，导航、台账、勾选场景开箱即用；
5. 浏览器一站式配置开发，无需本地前端环境，修改模板、分页、交互即时预览生效。

在 OA、CRM、进销存、政企台账、数据大屏、移动端外勤填报系统开发中，标准化使用 View 组件能够统一项目列表交互规范、减少自定义 JS 代码量、降低后期维护成本，同时满足金融、政企等行业安全合规、信创多端适配要求，是平台低代码开发中使用率最高的核心基础组件