WebBuilder Wb.View组件标准化开发规范

1. 规范目的

为统一团队 Wb.View 视图组件开发标准，规范列表渲染、布局、分页、交互、安全编码规则，解决项目中组件用法混乱、渲染不统一、存在安全漏洞、交互BUG频发等问题，提升项目交付标准化、规范化、安全性，降低后期维护成本，特制定本开发规范。

适用范围：所有基于WebBuilder平台开发的政企、制造、金融、数字化大屏、OA、CRM等项目，所有使用 Wb.View 组件的页面模块。

2. 组件基础使用规范

2.1 强制使用原则

所有列表、清单、标签、导航、分页数据展示场景，统一优先使用 Wb.View 组件，禁止自定义DIV列表、废弃旧列表组件，保证项目组件统一。

2.2 基础属性规范

• 所有带滚动、分页的View组件，必须配置固定height高度，禁止自适应高度导致功能失效
• 业务页面默认开启 frame 边框，保持页面卡片统一风格
• 所有视图组件必须配置唯一cid，禁止重复、缺失cid
• 公共页面、通用组件开启 resizable 自适应拉伸，提升适配性

3. 模板渲染编码规范

3.1 场景选型规范

• 简单静态列表、单字段展示：使用 itemTpl 模板语法
• 复杂拼接、数据格式化、循环嵌套、动态逻辑：必须使用 itemTplFn 函数渲染

3.2 安全编码强制规范（核心红线）

所有通过函数渲染的动态数据，必须使用 Wb.toHTML() 转义输出，禁止直接拼接变量，杜绝XSS安全漏洞，政企项目上线必须严格执行该标准。

✅ 正确写法：${Wb.toHTML(data.text)}

❌ 禁止写法：${data.text}

3.3 模板语法规范

• 模板循环、条件语法必须成对闭合，{for}/{/for}、{if}/{/if} 不得遗漏
• 嵌套取值必须使用 {[ ]} 包裹，避免解析异常
• 模板内样式统一使用平台内置w-通用样式，禁止大量自定义行内样式

4. 布局标准化规范

5. 分页功能开发规范

• 大数据量远程接口：标准分页栏 pagingBar="true"，pageSize=10
• 低频更新字典数据：开启 cached 缓存分页，优化加载速度
• 静态固定数据：使用 localData 本地分页，无需后端接口
• 信息流、日志动态数据：开启 autoPaging 滚动自动分页

所有分页组件必须配置固定高度，保证分页滚动区域稳定，页面布局不错乱。

6. 交互功能规范

• 批量操作场景统一开启 multiSelect 多选、rectSelect 框选
• 拖拽排序场景必须同时开启 draggable、droppable，绑定唯一拖拽标识
• 动态增删改数据必须使用官方API（addData、insertData、destroy、update），禁止重载页面
• 标签关闭、自定义点击交互统一使用 captureclick 事件捕获，避免冒泡异常

7. 禁止行为规范

• 禁止直接拼接未转义的用户动态数据，杜绝XSS漏洞
• 禁止混用多套布局规则，同页面同类视图组件布局统一
• 禁止无高度配置开启分页、滚动功能
• 禁止大量自定义CSS覆盖平台原生样式，优先使用内置w-样式
• 禁止废弃原生View组件，使用自定义DIV、第三方列表组件

8. 测试验收规范

页面开发完成后，必须完成以下测试方可上线：

1. 空数据、少量数据、大量数据三种场景渲染测试
2. 分页切换、动态增删改、拖拽交互功能测试
3. Chrome、Edge、国产信创浏览器兼容性测试
4. XSS安全漏洞校验，确认所有动态数据已转义
5. 多终端自适应适配测试

9. 通用标准模板

{
  "_icon": "list-view",
  "text": "standardView",
  "cls": "Wb.View",
  "properties": {
    "cid": "standardView",
    "height": "15em",
    "frame": "true",
    "resizable": "true",
    "url": "demo-source?xaction=staffDict",
    "pagingBar": "true",
    "pageSize": "10",
    "itemTplFn": "let text = Wb.toHTML(data.full_name);return `<div class=\"w-padding\">${text}</div>`;"
  },
  "_expanded": true
}