前言
欢迎使用OneCode平台通用组件属性手册。本手册旨在为开发者提供全面、系统的组件属性参考指南,帮助您快速掌握各类UI组件的配置方法与最佳实践。
编写目的
随着OneCode平台组件库的不断丰富与迭代,为确保开发团队能够统一理解和正确使用组件属性,我们编写了这份标准化文档。本手册通过结构化的属性说明、分类示例和使用建议,致力于降低组件配置难度,提升开发效率,保证界面一致性。
1.1 布局相关属性
属性名 | 说明 | 类型 | 可选值 |
---|---|---|---|
dock |
组件停靠方式 | string | left, right, top, bottom, fill |
width |
组件宽度 | string/number | 如: ‘100px’, ‘50%’, 200 |
height |
组件高度 | string/number | 如: ‘100px’, ‘50%’, 200 |
margin |
外边距 | object | {left, top, right, bottom} |
padding |
内边距 | object | {left, top, right, bottom} |
visibility |
可见性 | string | visible, hidden |
position |
定位方式 | string | absolute, relative, static |
1.2 外观相关属性
属性名 | 说明 | 类型 | 可选值 |
---|---|---|---|
className |
CSS类名 | string | - |
style |
内联样式 | object | CSS属性键值对 |
background |
背景色 | string | 颜色值 |
border |
边框样式 | string | CSS边框值 |
fontSize |
字体大小 | string | 如: ‘12px’, ‘1em’ |
fontColor |
字体颜色 | string | 颜色值 |
fontWeight |
字体粗细 | string | normal, bold |
1.3 数据相关属性
属性名 | 说明 | 类型 | 可选值 |
---|---|---|---|
value |
组件值 | any | - |
items |
选项列表 | array | 对象数组 |
dataSource |
数据源 | string/object | - |
disabled |
是否禁用 | boolean | true, false |
readonly |
是否只读 | boolean | true, false |
editable |
是否可编辑 | boolean | true, false |
1.4 事件相关属性
属性名 | 说明 | 回调参数 |
---|---|---|
onClick |
点击事件 | (event) => void |
onChange |
值变化事件 | (value) => void |
onLoad |
加载完成事件 | () => void |
onError |
错误事件 | (error) => void |
onSelect |
选择事件 | (selectedItem) => void |
二、基础组件
2.1 xui.UI.Button
使用场景:触发操作的按钮
配置属性:
{
type: 'button', // 按钮类型: button, submit, reset
caption: '确定', // 按钮文本
imageClass: 'icon-save', // 图标类名
iconFontCode: '', // 图标字体编码
disabled: false, // 是否禁用
visible: true, // 是否可见
onClick: () => {}, // 点击事件
style: { width: '100px' } // 样式
}
2.2 xui.UI.Input
使用场景:文本输入框
配置属性:
{
value: '', // 输入值
type: 'text', // 输入类型: text, password, number
placeholder: '请输入', // 占位文本
readonly: false, // 是否只读
disabled: false, // 是否禁用
maxlength: 50, // 最大长度
onChange: (value) => {}, // 值变化事件
labelCaption: '用户名', // 标签文本
labelSize: 80 // 标签宽度
}
2.3 xui.UI.CheckBox
使用场景:复选框
配置属性:
{
value: false, // 选中状态
caption: '同意协议', // 文本
disabled: false, // 是否禁用
onChange: (checked) => {} // 变化事件
}
2.4 xui.UI.Label
使用场景:文本标签
配置属性:
{
caption: '显示文本', // 文本内容
fontSize: '14px', // 字体大小
fontColor: '#333', // 字体颜色
fontWeight: 'bold', // 字体粗细
dock: 'left', // 停靠方式
onClick: () => {} // 点击事件
}
2.5 xui.UI.ComboInput
使用场景:下拉选择框
配置属性:
{
value: '', // 当前值
items: [ // 选项列表
{ id: '1', caption: '选项1' },
{ id: '2', caption: '选项2' }
],
disabled: false, // 是否禁用
editable: true, // 是否可编辑
onSelect: (item) => {}, // 选择事件
labelCaption: '选择', // 标签文本
iconFontCode: '' // 图标
}
三、容器组件
3.1 xui.UI.Div
使用场景:通用容器
配置属性:
{
html: '', // HTML内容
className: 'my-div', // CSS类名
style: { padding: '10px' }, // 样式
overflow: 'auto', // 溢出处理
dock: 'fill', // 停靠方式
dataBinder: 'dataSource' // 数据绑定
}
3.2 xui.UI.Block
使用场景:带边框的容器
配置属性:
{
caption: '标题', // 标题
borderType: 'solid', // 边框类型
background: '#fff', // 背景色
html: '', // HTML内容
overflow: 'hidden', // 溢出处理
dock: 'fill' // 停靠方式
}
3.3 xui.UI.Group
使用场景:可折叠的分组容器
配置属性:
{
caption: '分组标题', // 标题
folded: false, // 是否折叠
html: '', // HTML内容
onExpand: () => {}, // 展开事件
onFold: () => {}, // 折叠事件
dock: 'top', // 停靠方式
height: 200 // 高度
}
3.4 xui.UI.Tabs
使用场景:选项卡容器
配置属性:
{
value: 'tab1', // 当前选中选项卡ID
items: [ // 选项卡列表
{
id: 'tab1',
caption: '标签1',
html: '<div>内容1</div>', // 内容
iconFontCode: '' // 图标
},
{
id: 'tab2',
caption: '标签2',
html: '<div>内容2</div>'
}
],
onItemSelected: (item) => {}, // 选择事件
dock: 'fill', // 停靠方式
height: 300 // 高度
}
3.5 xui.UI.Layout
使用场景:复杂布局容器
配置属性:
{
type: 'hbox', // 布局类型: hbox, vbox
items: [ // 子组件
{
id: 'left',
size: 200, // 大小
min: 100, // 最小大小
max: 300, // 最大大小
html: '左侧面板'
},
{
id: 'main',
pos: 'main', // 主区域
html: '主内容区'
},
{
id: 'right',
size: 150,
html: '右侧面板'
}
],
dock: 'fill' // 停靠方式
}
四、数据展示组件
4.1 xui.UI.TreeGrid
使用场景:树形表格
配置属性:
{
header: [ // 列定义
{
id: 'name',
caption: '名称',
width: 200,
editable: true,
type: 'input'
},
{
id: 'type',
caption: '类型',
width: 100,
type: 'combobox',
editorListItems: ['文本', '数字', '日期']
}
],
rows: [ // 行数据
{
id: 'row1',
caption: '节点1',
cells: [ // 单元格数据
{ value: '项目1' },
{ value: '文本' }
],
sub: [ // 子节点
{
id: 'row1-1',
caption: '子节点1',
cells: [ { value: '子项目1' }, { value: '数字' } ]
}
]
}
],
uidColumn: 'id', // 唯一标识列
rowNumbered: true, // 是否显示行号
selMode: 'single', // 选择模式: single, multiple
onRowSelected: (rows) => {}, // 行选择事件
dock: 'fill', // 停靠方式
height: 400 // 高度
}
4.2 xui.UI.List
使用场景:列表展示
配置属性:
{
items: [ // 列表项
{ id: '1', caption: '选项1', imageClass: 'icon-item' },
{ id: '2', caption: '选项2', disabled: true }
],
value: '1', // 当前选中值
onItemSelected: (item) => {}, // 选择事件
dock: 'left', // 停靠方式
width: 200 // 宽度
}
4.3 xui.UI.TreeView
使用场景:树形结构展示
配置属性:
{
items: [ // 树形节点
{
id: 'node1',
caption: '节点1',
imageClass: 'icon-folder',
sub: [ // 子节点
{ id: 'node1-1', caption: '子节点1' },
{ id: 'node1-2', caption: '子节点2' }
]
},
{ id: 'node2', caption: '节点2', imageClass: 'icon-file' }
],
value: 'node1', // 当前选中值
onItemSelected: (item) => {}, // 选择事件
dock: 'left', // 停靠方式
width: 250 // 宽度
}
4.4 xui.UI.Gallery
使用场景:图片画廊
配置属性:
{
items: [ // 图片项
{
id: 'img1',
image: 'path/to/image1.jpg',
caption: '图片1',
itemWidth: 150,
itemHeight: 100
},
{
id: 'img2',
image: 'path/to/image2.jpg',
caption: '图片2',
itemWidth: 150,
itemHeight: 100
}
],
onItemSelected: (item) => {}, // 选择事件
dock: 'fill', // 停靠方式
height: 300 // 高度
}
五、高级组件
5.1 xui.APICaller
使用场景:API调用器
配置属性:
{
name: 'api1', // 名称
queryURL: '/api/data', // 请求URL
requestType: 'GET', // 请求类型: GET, POST
responseType: 'json', // 响应类型: json, text
queryArgs: { param1: 'value1' }, // 请求参数
onData: (data) => {}, // 成功回调
onError: (error) => {}, // 错误回调
beforeData: (data) => { return data; } // 数据预处理
}
5.2 xui.Timer
使用场景:定时器
配置属性:
{
interval: 1000, // 间隔时间(毫秒)
autoStart: true, // 是否自动启动
onTime: () => {} // 定时回调
}
5.3 xui.UI.Dialog
使用场景:对话框
配置属性:
{
caption: '对话框标题', // 标题
width: 500, // 宽度
height: 300, // 高度
modal: true, // 是否模态
minBtn: true, // 是否显示最小化按钮
maxBtn: true, // 是否显示最大化按钮
html: '<div>对话框内容</div>', // 内容
beforeClose: () => { return true; }, // 关闭前回调
dock: 'center' // 停靠方式
}
5.4 xui.UI.ECharts
使用场景:图表展示
配置属性:
{
chartOption: { // ECharts配置
title: { text: '图表标题' },
series: [{ type: 'pie', data: [{ value: 30, name: '数据1' }, { value: 70, name: '数据2' }] }]
},
dataset: [], // 数据集
chartTheme: 'light', // 主题
onChartEvent: (event) => {}, // 图表事件
dock: 'fill', // 停靠方式
height: 400 // 高度
}
六、SVG组件
6.1 xui.svg.rect
使用场景:矩形图形
配置属性:
{
attr: { // SVG属性
x: 10, // x坐标
y: 10, // y坐标
width: 100, // 宽度
height: 50, // 高度
fill: '#ff0000', // 填充色
stroke: '#000', // 边框色
'stroke-width': 2 // 边框宽度
},
onClick: () => {}, // 点击事件
animDraw: true // 是否启用绘制动画
}
6.2 xui.svg.circle
使用场景:圆形图形
配置属性:
{
attr: { // SVG属性
cx: 50, // 圆心x坐标
cy: 50, // 圆心y坐标
r: 40, // 半径
fill: '#00ff00', // 填充色
stroke: '#000', // 边框色
'stroke-width': 2 // 边框宽度
},
onClick: () => {}, // 点击事件
animDraw: true // 是否启用绘制动画
}
6.3 xui.svg.text
使用场景:文本图形
配置属性:
{
attr: { // SVG属性
x: 100, // x坐标
y: 50, // y坐标
text: 'SVG文本', // 文本内容
fill: '#0000ff', // 颜色
'font-size': 14, // 字体大小
'text-anchor': 'middle' // 文本对齐
},
onClick: () => {} // 点击事件
}
6.4 xui.svg.path
使用场景:路径图形
配置属性:
{
attr: { // SVG属性
d: 'M10 10 L100 10 L100 100 Z', // 路径数据
fill: '#ffff00', // 填充色
stroke: '#000', // 边框色
'stroke-width': 2 // 边框宽度
},
onClick: () => {}, // 点击事件
animDraw: true // 是否启用绘制动画
}
七、特殊属性配置
7.1 动态字典配置
动态字典用于配置下拉框等组件的选项来源:
{
editorListItems: [ // 静态列表
{ id: '1', caption: '选项1' },
{ id: '2', caption: '选项2' }
],
// 或使用动态数据源
editorListItems: {
url: '/api/dictionary', // 数据源URL
valueField: 'id', // 值字段
textField: 'name' // 文本字段
}
}
7.2 自定义单元格配置
在表格组件中自定义单元格渲染:
{
cellRenderer: function(row, col, value) {
// 自定义渲染函数
return `<span style="color: red">${value}</span>`;
},
editorType: 'combobox', // 编辑器类型
editorOptions: { // 编辑器选项
items: [ { id: '1', caption: '是' }, { id: '0', caption: '否' } ]
}
}
八、组件层级关系总览
基础组件
- xui.UI.Button, xui.UI.Input, xui.UI.Label, xui.UI.CheckBox, xui.UI.RadioBox
- xui.UI.ComboInput, xui.UI.DatePicker, xui.UI.TimePicker, xui.UI.ColorPicker
- xui.UI.Slider, xui.UI.ProgressBar, xui.UI.RichEditor
容器组件
- xui.UI.Div, xui.UI.Block, xui.UI.Group, xui.UI.Panel
- xui.UI.Tabs, xui.UI.MTabs, xui.UI.Stacks, xui.UI.ButtonViews
- xui.UI.FoldingTabs, xui.UI.Layout, xui.UI.FormLayout
数据展示组件
- xui.UI.List, xui.UI.TreeView, xui.UI.MTreeView, xui.UI.TreeGrid
- xui.UI.MTreeGrid, xui.UI.Gallery, xui.UI.StatusButtons, xui.UI.PageBar
高级组件
- xui.APICaller, xui.MQTT, xui.Timer, xui.AnimBinder
- xui.MessageService, xui.UI.Dialog, xui.UI.ECharts
- xui.UI.FusionChartsXT, xui.UI.FileUpload
SVG组件
- xui.svg.rect, xui.svg.circle, xui.svg.ellipse, xui.svg.path
- xui.svg.image, xui.svg.text, xui.svg.connector
- xui.svg.rectComb, xui.svg.circleComb, xui.svg.ellipseComb
九、配置最佳实践
性能优化
- 大数据列表使用虚拟滚动
- 复杂布局避免过深嵌套
- 合理设置组件可见性减少渲染压力
数据绑定
- 使用dataBinder属性实现双向绑定
- 复杂数据处理使用formula属性
- 异步数据加载使用xui.APICaller
样式管理
- 优先使用className而非inline style
- 公共样式定义在全局CSS中
- 使用主题变量保持风格一致
事件处理
- 事件处理函数保持简洁
- 复杂逻辑提取为独立函数
- 及时解绑不再需要的事件
可维护性
- 组件ID使用有意义的命名
- 复杂配置提取为变量
- 使用注释说明特殊配置
十、组件完整列表
以下是所有OneCode组件的完整列表:
核心模块
- xui.Module
- xui.APICaller
- xui.MQTT
- xui.Timer
- xui.AnimBinder
- xui.MessageService
UI组件
- xui.UI.CSSBox
- xui.UI.Element
- xui.UI.Icon
- xui.UI.Span
- xui.UI.Label
- xui.UI.Link
- xui.UI.HTMLButton
- xui.UI.Button
- xui.UI.CheckBox
- xui.UI.Input
- xui.UI.HiddenInput
- xui.UI.RichEditor
- xui.UI.List
- xui.UI.ComboInput
- xui.UI.ProgressBar
- xui.UI.Slider
- xui.UI.RadioBox
- xui.UI.DatePicker
- xui.UI.TimePicker
- xui.UI.ColorPicker
- xui.UI.StatusButtons
- xui.UI.FoldingList
- xui.UI.Gallery
- xui.UI.ButtonLayout
- xui.UI.Opinion
- xui.UI.TitleBlock
- xui.UI.ContentBlock
- xui.UI.PageBar
- xui.UI.PopMenu
- xui.UI.MenuBar
- xui.UI.SystemMenu
- xui.UI.TreeBar
- xui.UI.ToolBar
- xui.UI.TreeView
- xui.UI.MTreeView
- xui.UI.TreeGrid
- xui.UI.MTreeGrid
- xui.UI.Image
- xui.UI.Flash
- xui.UI.FormLayout
- xui.UI.MFormLayout
- xui.UI.Audio
- xui.UI.FileUpload
- xui.UI.Video
- xui.UI.ECharts
- xui.UI.FusionChartsXT
- xui.UI.Div
- xui.UI.Block
- xui.UI.Group
- xui.UI.Panel
- xui.UI.Tabs
- xui.UI.MTabs
- xui.UI.Stacks
- xui.UI.ButtonViews
- xui.UI.FoldingTabs
- xui.UI.Layout
- xui.UI.Dialog
- xui.UI.SVGPaper
SVG组件
- xui.svg.circle
- xui.svg.ellipse
- xui.svg.rect
- xui.svg.image
- xui.svg.text
- xui.svg.path
- xui.svg.rectComb
- xui.svg.circleComb
- xui.svg.ellipseComb
- xui.svg.pathComb
- xui.svg.imageComb
- xui.svg.connector
十一、总结
本指南详细介绍了OneCode平台所有组件的属性配置方法,包括通用属性、各类型组件的具体配置以及特殊场景的应用。通过合理配置组件属性,可以构建出功能丰富、交互友好的Web应用。
在实际开发中,建议参考以下资源获取更多帮助:
- OneCode官方文档
- 组件示例库
- API参考手册
- 社区论坛
如需进一步定制组件或实现复杂功能,请联系技术支持团队获取专业帮助。