引言
OneCode 框架中的 List 组件作为数据展示的核心载体,通过灵活的继承体系和可定制化设计,满足了从简单列表到复杂交互界面的多样化需求。本文将系统剖析 xui.UI.List
基类的设计思想,完整梳理其所有子类的功能特性,并深入探讨 OneCode 组件化架构的优势与扩展实践。
一、基类设计:xui.UI.List 的核心能力
1.1 数据管理与状态控制
xui.UI.List
基类通过 _setCtrlValue
方法实现了单选/多选模式的统一处理,支持 valueSeparator
配置实现多选值的格式化输出。代码中设计了完善的选中状态管理机制:
javascript
// ... existing code ...
_setCtrlValue: function(value, isLoad){
var p = this.properties,
items = p.items || [],
separator = p.valueSeparator || ',',
values = xui.isArray(value) ? value : (value + '').split(separator),
changed = false;
// 清除之前选中状态
xui.arr.each(items, function(item){
if(item.checked){
item.checked = false;
changed = true;
}
});
// 设置新选中状态
xui.arr.each(values, function(v){
var item = xui.arr.query(items, function(it){
return it.value == v;
});
if(item && !item.checked){
item.checked = true;
changed = true;
}
});
if(changed && !isLoad) this._onChange();
return changed;
}
// ... existing code ...
1.2 布局与样式系统
基类通过 adjustSize
方法实现内容自适应,结合 maxHeight
属性控制容器尺寸。模板系统采用分层结构设计,包含 LABEL
、ITEMS
容器及 ITEM
、MARK
、ICON
、CAPTION
等子元素,支持灵活的样式定制:
javascript
// ... existing code ...
Static: {
_DIRTYKEY: ['value', 'disabled', 'readonly', 'items', 'label', 'visible'],
Appearances: {
LABEL: {
position: 'absolute',
overflow: 'hidden',
'text-align': 'right',
'white-space': 'nowrap'
},
ITEMS: {
position: 'relative',
overflow: 'auto',
'overflow-x': 'hidden'
},
ITEM: {
display: xui.$inlineBlock,
border: '1px solid transparent',
padding: '.25em .5em',
cursor: 'default',
'vertical-align': 'middle'
},
MARK: {
margin: '0 .25em 0 0',
'vertical-align': 'middle'
},
CAPTION: {
'vertical-align': 'middle'
}
}
}
// ... existing code ...
1.3 交互能力
基类实现了完整的事件处理体系,包括:
- 鼠标事件:点击、双击、悬停、右键菜单
- 键盘导航:上下键切换焦点、回车键选中
- 选择模式:支持单选、多选(含 Shift/Ctrl 辅助)
- 命令按钮:内置 OPT 选项按钮和 CMD 命令按钮处理
二、子类继承体系与功能解析
2.1 继承关系总览
scss
┌───────────────── xui.UI.List ─────────────────┐
│ │
├───────┬───────┬───────┬───────┬───────┬───────┤
│ │ │ │ │ │ │
▼ ▼ ▼ ▼ ▼ ▼ ▼
Status Folding Gallery RadioBox Content Opinion Button Title Info
Buttons List Block Layout Block Block
│
▼
IOTGallery
2.2 核心子类功能详解
2.2.1 状态按钮组件:StatusButtons
功能定位:实现带状态指示的按钮组
核心特性:
- 通过
_autoColor
方法实现自动颜色分配,支持图标、字体和背景色的自动循环 - 支持连接样式(connected),实现按钮组无缝拼接
- 内置文本、按钮、下拉按钮三种类型
javascript
// ... existing code ...
_autoColor: function (item, index, p) {
index = index || 0;
if (p.autoFontColor || item.fontColor) {
var fontColors = this._initIconColors('font', p);
while (index && index > (fontColors.length - 1)) {
index = index - fontColors.length;
}
item.fontColor = item.fontColor || fontColors[index];
item._fontColor = item.fontColor ? ";color:" + item.fontColor : ''
}
// ... 类似处理 iconColor 和 itemColor ...
}
// ... existing code ...
2.2.2 可折叠列表:FoldingList
功能定位:实现层级化内容展示
核心特性:
- 三部分结构:HEAD(标题区)、BODY(内容区)、TAIL(尾饰区)
- 通过
toggle
方法控制内容展开/折叠 - 支持默认展开最后一项(activeLast 属性)
- 自定义内容加载回调
onGetContent
javascript
// ... existing code ...
HEAD: {
onClick:function(profile, e, src){
profile.boxing().toggle(profile.getItemIdByDom(src));
return false;
}
},
toggle: function(id){
var item = this.getItem(id),
profile = this.profile;
if(item._show){
item._show = false;
item._checked = '';
item._fi_tlg = 'xui-uicmd-toggle';
}else{
item._show = true;
item._checked = profile.getClass('ITEM','-checked');
item._fi_tlg = 'xuifont-checked xui-uicmd-toggle xui-uicmd-toggle-checked';
if(!item._fill) this.fillContent(id);
}
this.refresh(id);
}
// ... existing code ...
2.2.3 图片画廊组件:Gallery & IOTGallery
功能定位:媒体资源展示与物联网设备状态监控
Gallery 核心特性:
- 支持图片自动尺寸调整(autoImgSize)
- 图片加载状态管理(loading/loaded/error)
- 支持图标模式(iconOnly)和图文混合模式
- 滑动手势支持(swipeleft/swiperight)
IOTGallery 扩展特性:
- 设备状态指示(iotStatus:on/off/alarm/none)
- 状态颜色映射(绿色-在线、灰色-离线、红色-告警)
- 背景位置动态调整
javascript
// ... existing code ...
switch (item.iotStatus) {
case 'on':
item._position = 'background-position: right center';
item._color = ' color:#00d265';
break;
case 'off' :
item._position = 'background-position: left center';
item._color = ' color: #d7d7d7';
break;
case 'alarm' :
item._position = 'background-position: center center';
item._color = ' color:red';
break;
// ... 其他状态 ...
}
// ... existing code ...
2.2.4 单选/多选框组件:RadioBox
功能定位:表单选择控件
核心特性:
- 支持单选按钮(默认)和复选框模式(checkBox: true)
- 自定义选中标记样式
- 精简的模板结构,专注选择功能
javascript
// ... existing code ...
DataModel:{
checkBox:{
ini:false,
action:function(v){
this.getSubNode('MARK',true).replaceClass(
v ? /(uicmd-radio)|(\s+uicmd-radio)/g : /(^uicmd-check)|(\s+uicmd-check)/g ,
v ? ' xui-uicmd-check' : ' xui-uicmd-radio'
);
}
}
},
_prepareItem:function(profile, item){
item._fi_markcls = profile.properties.checkBox?'xui-uicmd-check':'xui-uicmd-radio';
item._itemRow = profile.properties.itemRow?'xui-item-row':'';
}
// ... existing code ...
2.2.5 内容块组件:ContentBlock
功能定位:信息展示卡片
核心特性:
- 支持标题、内容、日期、更多按钮布局
- 图片加载与错误处理
- 滑动手势与触摸事件支持
- 自动颜色分配系统
javascript
// ... existing code ...
TITLE: {
onClick: function (profile, e, src) {
var item = profile.getItemByDom(src),
box = profile.boxing();
if (profile.onTitleClick) {
box.onTitleClick(profile, item, e, src);
return false;
}
}
},
MORE: {
onClick: function (profile, e, src) {
// ... 更多按钮点击处理 ...
}
}
// ... existing code ...
2.2.6 评论组件:Opinion
功能定位:用户评论展示
核心特性:
- 作者头像、名称、日期布局
- 评论内容格式化展示
- 支持评论标记(flag)
- 图片加载优化
2.2.7 按钮布局组件:ButtonLayout
功能定位:多按钮排列布局
核心特性:
- 支持行列布局配置(columns/rows)
- 图标与文字组合
- 触摸反馈与状态管理
- 自动尺寸调整
2.2.8 标题块组件:TitleBlock
功能定位:带图标的标题区域
核心特性:
- 大图标+标题布局
- 右侧操作区(MORE)
- 背景色自动分配
- 点击事件支持
2.2.9 信息块组件:InfoBlock
功能定位:数据指标展示
核心特性:
- 数值与单位分离展示
- 状态颜色编码
- 紧凑布局优化
- 自动颜色循环
三、OneCode 组件设计优势
3.1 继承式架构设计
OneCode 采用「基类抽象+子类特化」的继承体系,xui.UI.List
定义核心数据结构与基础行为,子类通过重写模板、样式和特定方法实现差异化。这种设计带来:
- 代码复用率提升:基础功能无需重复实现
- 接口一致性:所有列表组件遵循相同的数据交互方式
- 扩展便捷性:新增列表类型只需关注差异化逻辑
3.2 声明式配置系统
组件采用「属性驱动」的声明式设计,通过配置项而非代码修改实现功能切换:
javascript
// 声明式配置示例
var list = xui.create('xui.UI.List', {
selMode: 'multiple', // 多选模式
valueSeparator: ';', // 值分隔符
maxHeight: 300, // 最大高度
items: [...], // 数据项
onItemSelected: function(profile, item){ ... } // 选中事件
});
3.3 模板与样式隔离
通过 Appearances
静态属性集中管理样式,$submap
定义模板结构,实现:
- 样式与逻辑分离
- 主题定制便捷
- 组件外观一致性
3.4 事件驱动交互
组件内置完整的事件处理机制:
- 基础事件:点击、双击、悬停
- 手势事件:滑动、按压
- 业务事件:选中变化、命令执行
- 生命周期事件:渲染完成、数据变更
3.5 自适应与响应式设计
通过 adjustSize
、autoItemSize
、autoImgSize
等特性,组件能够:
- 适应不同容器尺寸
- 处理不同分辨率
- 优化移动端展示
四、自定义扩展实现指南
4.1 创建自定义 List 子类
通过 xui.Class
继承 xui.UI.List
并实现差异化:
javascript
xui.Class("xui.UI.CustomList", "xui.UI.List", {
// 1. 初始化:修改模板
Initialize: function(){
var t = this.getTemplate();
// 修改模板结构
t.$submap.items.ITEM.CUSTOM = {
$order: 3,
text: '{customField}'
};
this.setTemplate(t);
},
// 2. 静态属性:样式与数据模型
Static: {
Appearances: {
CUSTOM: {
color: '#ff0000',
'margin-left': '10px'
}
},
DataModel: {
customProp: {
ini: 'default',
action: function(v){
// 属性变化处理
}
}
}
},
// 3. 自定义方法
customMethod: function(){
// 业务逻辑
},
// 4. 重写父类方法
_prepareItem: function(profile, item){
// 调用父类方法
arguments.callee.upper.apply(this, arguments);
// 自定义处理
item.customField = 'custom: ' + item.value;
}
});
4.2 扩展要点
- 模板扩展 :通过
$submap
添加新元素或修改现有元素 - 样式定制 :在
Appearances
中定义新元素样式 - 数据模型扩展 :在
DataModel
中添加自定义属性及动作 - 交互增强 :在
Behaviors
中添加新事件处理 - 数据处理 :重写
_prepareData
/_prepareItem
实现数据转换
4.3 扩展实例:进度指示列表
通过继承 xui.UI.List
实现带进度条的列表项:
javascript
xui.Class("xui.UI.ProgressList", "xui.UI.List", {
Initialize: function(){
var t = this.getTemplate();
t.$submap.items.ITEM.PROGRESS = {
$order: 2,
className: 'xui-progress',
style: 'width:{progress}%'
};
this.setTemplate(t);
},
Static: {
Appearances: {
PROGRESS: {
height: '6px',
'background-color': '#46C37B'
}
},
DataModel: {
showProgress: {
ini: true
}
}
},
_prepareItem: function(profile, item){
arguments.callee.upper.apply(this, arguments);
item.progress = item.progress || 0;
}
});
五、总结
OneCode List 组件体系通过精心设计的基类与丰富的子类实现,为数据展示提供了全方位解决方案。其核心优势在于:
- 高度可定制:从外观到行为的精细化控制
- 良好扩展性:继承与组合并重的扩展机制
- 一致的交互体验:统一的交互模式降低学习成本
- 跨场景适配:从简单列表到复杂卡片的全场景覆盖
无论是快速构建常规列表,还是开发高度定制化的交互界面,OneCode List 组件体系都能提供坚实的基础与灵活的扩展能力,帮助开发者高效实现各类数据展示需求。