Duilib XML 属性参考手册

📦 第一部分：通用基础属性 (CControlUI)

核心基类

所有控件均继承自 CControlUI，因此所有控件都支持以下属性。

CControlUI

属性名	类型	默认值	功能说明
name	string	无	控件的唯一标识符（ID），用于在代码中查找控件
text	string	""	控件显示的文本内容。支持 `{\n}` 换行
pos	rect	0,0,0,0	绝对坐标位置 (left,top,right,bottom)
float	bool/percent	false	是否浮动，可设置百分比位置
floatalign	string	无	浮动对齐：`left`,`top`,`right`,`bottom`,`center`,`vcenter`
padding	rect	0,0,0,0	外边距 (left,top,right,bottom)
bkcolor	color	0x00000000	背景颜色 (ARGB 16进制，如 #FFFF0000)
bkcolor2	color	0x00000000	背景渐变色2
bkcolor3	color	0x00000000	背景渐变色3
gradient	string	无	设置渐变方向
bkimage	string	无	背景图片，支持属性如 `file='x.png' source='0,0,10,10'`
foreimage	string	无	前景图片路径（绘制在文字之上）
bordersize	rect/int	0	边框宽度 (left,top,right,bottom) 或统一宽度
bordercolor	color	0x00000000	边框颜色
focusbordercolor	color	0x00000000	获得焦点时的边框颜色
borderround	size	0,0	圆角大小 (width,height)
width	int	0	控件固定宽度
height	int	0	控件固定高度
minwidth	int	0	最小宽度
minheight	int	0	最小高度
maxwidth	int	9999	最大宽度
maxheight	int	9999	最大高度
visible	bool	true	是否可见
enabled	bool	true	是否启用
mouse	bool	true	是否响应鼠标事件
keyboard	bool	true	是否响应键盘事件
tooltip	string	无	鼠标悬停提示文本
userdata	string	无	用户自定义字符串数据
menu	bool	false	是否启用右键菜单
cursor	string	arrow	鼠标光标形状 (arrow, hand, ibeam 等)

📦 CContainerUI 容器基类

容器

所有布局控件的基类，定义了子控件管理和滚动条属性。

📁 文件: Core/UIContainer.cpp 👥 继承: CControlUI

CControlUI → CContainerUI

属性名	类型	默认值	功能说明
inset	rect	0,0,0,0	容器内边距 (left,top,right,bottom)
childpadding	int	0	子控件之间的间距
hscrollbar	bool	false	是否启用水平滚动条
vscrollbar	bool	false	是否启用垂直滚动条
hscrollbarstyle	string	无	水平滚动条样式
vscrollbarstyle	string	无	垂直滚动条样式
mousechild	bool	true	子控件是否可以响应鼠标事件
scrollstepsize	int	0	滚动步长

                                XML 示例
                                
                                <Container width="300" height="200" inset="10,10,10,10" bkcolor="#FFFFFFFF" bordercolor="#FF000000" bordersize="1">
    <Button text="我是子控件" width="100" height="30" />
</Container>

📐 CVerticalLayoutUI 垂直布局

布局

子控件从上到下垂直排列。

📁 文件: Layout/UIVerticalLayout.cpp 👥 继承: CContainerUI

CControlUI → CContainerUI → VerticalLayout

属性名	类型	默认值	功能说明
sepheight	int	0	拖动分隔条的高度，设置 >0 可在底部启用拖动调整大小
sepimm	bool	false	拖动分隔条时是否即时刷新布局

                                XML 示例
                                
                            

                                <VerticalLayout width="200" height="300" bkcolor="#FFEEEEEE" inset="5,5,5,5" childpadding="5">
    <Button text="按钮 1" height="30" />
    <Button text="按钮 2" height="30" />
    <Label text="自动填充区域" bkcolor="#FFAAAAAA" />
</VerticalLayout>
                            

📐 CHorizontalLayoutUI 水平布局

布局

子控件从左到右水平排列。

📁 文件: Layout/UIHorizontalLayout.cpp 👥 继承: CContainerUI

CControlUI → CContainerUI → HorizontalLayout

属性名	类型	默认值	功能说明
sepwidth	int	0	拖动分隔条的宽度，设置 >0 可在右侧启用拖动调整大小
sepimm	bool	false	拖动分隔条时是否即时刷新布局

                                XML 示例
                                
                            

                                <HorizontalLayout width="400" height="50" bkcolor="#FFDDDDDD" inset="5,5,5,5" childpadding="10">
    <Button text="左侧" width="80" />
    <Label text="中间文本" />
    <Button text="右侧" width="80" />
</HorizontalLayout>
                            

📐 CTileLayoutUI 平铺布局

布局

子控件像瓷砖一样排列，支持固定列数。

📁 文件: Layout/UITileLayout.cpp 👥 继承: CContainerUI

CControlUI → CContainerUI → TileLayout

属性名	类型	默认值	功能说明
columns	int	1	列数，指定每行显示的控件数量
itemsize	size	0,0	每个子项的固定大小 (width,height)

                                XML 示例
                                
                            

                                <TileLayout width="400" height="300" columns="3" itemsize="100,100" inset="10,10,10,10" childpadding="10">
    <Button text="Item 1" />
    <Button text="Item 2" />
    <Button text="Item 3" />
    <Button text="Item 4" />
</TileLayout>
                            

📐 CTabLayoutUI 标签页布局

布局

类似于卡片堆叠，同一时间只显示一个子控件。通常配合 Option 控件使用。

📁 文件: Layout/UITabLayout.cpp 👥 继承: CContainerUI

CControlUI → CContainerUI → TabLayout

属性名	类型	默认值	功能说明
selectedid	int	0	默认选中的子控件索引（从0开始）

                                XML 示例
                                
                            

                                <VerticalLayout>
    <HorizontalLayout height="30">
        <Option text="Tab 1" group="tabs" selected="true" bindtablayoutname="my_tab_layout" bindtabindex="0" />
        <Option text="Tab 2" group="tabs" bindtablayoutname="my_tab_layout" bindtabindex="1" />
    </HorizontalLayout>
    
    <TabLayout name="my_tab_layout" selectedid="0">
        <VerticalLayout bkcolor="#FFFF0000">
            <Label text="Page 1 Content" align="center" />
        </VerticalLayout>
        <VerticalLayout bkcolor="#FF00FF00">
            <Label text="Page 2 Content" align="center" />
        </VerticalLayout>
    </TabLayout>
</VerticalLayout>
                            

📐 CChildLayoutUI 子布局加载器

布局

用于加载外部 XML 文件作为子布局，实现界面模块化。

📁 文件: Layout/UIChildLayout.cpp 👥 继承: CContainerUI

CControlUI → CContainerUI → ChildLayout

属性名	类型	默认值	功能说明
xmlfile	string	无	外部 XML 文件的路径

                                XML 示例
                                
                            

                                <VerticalLayout>
    <Label text="Header" height="50" />
    <ChildLayout xmlfile="layouts/content_part.xml" />
    <Label text="Footer" height="50" />
</VerticalLayout>
                            

T CLabelUI 文本标签

基础控件

基础文本显示控件。

📁 文件: Control/UILabel.cpp 👥 继承: CControlUI

CControlUI → Label

属性名	类型	默认值	功能说明
align	string	left	水平对齐：`left`, `center`, `right`
valign	string	center	垂直对齐：`top`, `vcenter`, `bottom`
font	int	-1	字体索引
textcolor	color	0	文本颜色
disabledtextcolor	color	0	禁用状态颜色
textpadding	rect	0,0,0,0	文本内边距
showhtml	bool	false	是否启用 HTML 渲染 (支持 `<b>`, `<i>`, `<c color>`)
endellipsis	bool	false	文本过长显示省略号 (...)
wordbreak	bool	false	自动换行

XML 示例

<Label text="这是一个标签" font="0" textcolor="#FF000000" align="center" valign="vcenter" />
<Label text="{c #FF0000}红色文字{/c} 普通文字" showhtml="true" />

◼ CButtonUI 按钮

基础控件

拥有多种状态图片的按钮。

📁 文件: Control/UIButton.cpp 👥 继承: CLabelUI

CControlUI → Label → Button

属性名	类型	默认值	功能说明
normalimage	string	无	正常状态图片
hotimage	string	无	鼠标悬停状态图片
pushedimage	string	无	按下状态图片
focusedimage	string	无	获得焦点状态图片
disabledimage	string	无	禁用状态图片
hottextcolor	color	0	悬停文本颜色
pushedtextcolor	color	0	按下文本颜色
focusedtextcolor	color	0	焦点文本颜色
bindtablayoutname	string	无	绑定 TabLayout 的名称
bindtabindex	int	-1	绑定 TabLayout 的索引

XML 示例

<Button text="点击我" width="100" height="30" 
        normalimage="btn_normal.png" hotimage="btn_hot.png" pushedimage="btn_pushed.png"
        hottextcolor="#FFFF0000" />

☑ COptionUI 选项/单选框

基础控件

具有选中状态的按钮，常用于单选组或复选框。

📁 文件: Control/UIOption.cpp 👥 继承: CButtonUI

CControlUI → Label → Button → Option

属性名	类型	默认值	功能说明
group	string	无	分组名称，同组 Option 互斥（单选）
selected	bool	false	初始是否选中
selectedimage	string	无	选中状态图片
selectedhotimage	string	无	选中且悬停状态图片
selectedtextcolor	color	0	选中状态文本颜色

                                XML 示例
                                
                            

                                <!-- 单选组 -->
<HorizontalLayout height="30">
    <Option name="opt1" group="g1" text="选项 A" selected="true" width="60" />
    <Option name="opt2" group="g1" text="选项 B" width="60" />
</HorizontalLayout>

<!-- 复选框 (无 group) -->
<Option name="chk1" text="复选框" width="80" selectedimage="checked.png" normalimage="unchecked.png" />
                            

⌨ CEditUI 输入框

基础控件

文本输入控件。

📁 文件: Control/UIEdit.cpp 👥 继承: CLabelUI

CControlUI → Label → Edit

属性名	类型	默认值	功能说明
readonly	bool	false	是否只读
password	bool	false	是否为密码模式
passwordchar	char	*	密码掩码字符
maxchar	int	-1	最大输入字符数
numberonly	bool	false	仅允许输入数字
tipvalue	string	无	提示文本（PlaceHolder）
tipvaluecolor	color	0xFFBAC0C5	提示文本颜色
nativebkcolor	color	0xFFFFFFFF	原生编辑框背景色
nativetextcolor	color	0x00000000	原生编辑框文本色

XML 示例

<Edit width="200" height="30" tipvalue="请输入用户名" bordercolor="#FF888888" bordersize="1" />
<Edit width="200" height="30" password="true" tipvalue="请输入密码" />

▓ CProgressUI 进度条

进度控件

用于显示操作进度的控件。

📁 文件: Control/UIProgress.cpp 👥 继承: CLabelUI

CControlUI → Label → Progress

属性名	类型	默认值	功能说明
hor	bool	true	是否为水平进度条，false 为垂直
min	int	0	进度最小值
max	int	100	进度最大值
value	int	0	当前进度值
isstretchfore	bool	true	是否拉伸前景图片以适应进度

XML 示例

<Progress width="200" height="20" min="0" max="100" value="50" foreimage="progress_fore.png" bkimage="progress_bg.png" />

◐ CSliderUI 滑动条

进度控件

允许用户通过拖动滑块选择值的控件。

📁 文件: Control/UISlider.cpp 👥 继承: CProgressUI

CControlUI → Label → Progress → Slider

属性名	类型	默认值	功能说明
thumbimage	string	无	滑块的普通状态图片
thumbhotimage	string	无	滑块的悬停图片
thumbpushedimage	string	无	滑块的按下状态图片
thumbsize	size	10,10	滑块的大小 (width,height)
step	int	1	步长，每次调整的增量
sendmove	bool	false	拖动时是否实时发送变化事件

XML 示例

<Slider width="200" height="20" min="0" max="100" value="30" thumbsize="15,20" thumbimage="slider_thumb.png" />

↕ CScrollBarUI 滚动条

滚动控件

通常由容器自动创建，但也可以独立使用。拥有非常丰富的图片属性以定制外观。

📁 文件: Control/UIScrollBar.cpp 👥 继承: CControlUI

CControlUI → ScrollBar

属性名	类型	默认值	功能说明
hor	bool	false	是否为水平滚动条
range	int	100	滚动范围
value	int	0	当前位置
linesize	int	8	点击箭头的滚动步长
showbutton1	bool	true	是否显示第一个按钮
showbutton2	bool	true	是否显示第二个按钮

图片属性： 还包括 button1normalimage, button1hotimage, button1pushedimage, button2normalimage, thumbnormalimage, railnormalimage, bknormalimage 等丰富的图片属性。

XML 示例

<ScrollBar width="16" height="100" 
    button1normalimage="scrollbar_up.png" button2normalimage="scrollbar_down.png" 
    thumbnormalimage="scrollbar_bar.png" railnormalimage="scrollbar_rail.png" />

📝 CRichEditUI 富文本编辑框

高级控件

支持多行、多样式文本编辑的强大控件。

📁 文件: Control/UIRichEdit.cpp 👥 继承: CContainerUI

CControlUI → CContainerUI → RichEdit

属性名	类型	默认值	功能说明
multiline	bool	true	是否多行模式
readonly	bool	false	是否只读
password	bool	false	是否密码模式
wanttab	bool	true	是否接收 TAB 键输入
wantreturn	bool	true	是否接收回车键换行
wantctrlreturn	bool	true	是否接收 Ctrl+Enter
rich	bool	true	是否启用富文本特性
vscrollbar	bool	false	强制显示垂直滚动条
autovscroll	bool	false	自动显示垂直滚动条
tipvalue	string	无	提示文本 (Placeholder)

XML 示例

<RichEdit width="300" height="200" multiline="true" vscrollbar="true" autovscroll="true" textcolor="#FF000000" tipvalue="请输入内容..." />

📋 CListUI 列表控件

列表控件

显示垂直滚动的列表项，支持表头。

📁 文件: Control/UIList.cpp 👥 继承: CVerticalLayoutUI

CControlUI → CContainerUI → CVerticalLayoutUI → List

属性名	类型	默认值	功能说明
header	string	visible	表头状态，设为 `hidden` 可隐藏
multiselect	bool	false	是否允许多选
itemfont	int	-1	列表项默认字体
itemaltbk	bool	false	是否启用隔行变色
itemselectedbkcolor	color	0xFFC1E3FF	选中项背景颜色
itemhotbkcolor	color	0xFFE9F5FF	悬停项背景颜色
itemshowrowline	bool	false	显示行线
itemshowcolumnline	bool	false	显示列线

                                XML 示例
                                
                            

                                <List width="300" height="200" itemshowrowline="true" itemshowcolumnline="true">
    <ListHeader height="24">
        <ListHeaderItem text="姓名" width="100" />
        <ListHeaderItem text="年龄" width="50" />
        <ListHeaderItem text="地址" width="150" />
    </ListHeader>
    <ListLabelElement text="张三" />
    <ListLabelElement text="李四" />
</List>
                            

▼ CComboUI 下拉框

列表控件

点击展开下拉列表供选择。

📁 文件: Control/UICombo.cpp 👥 继承: CContainerUI

CControlUI → CContainerUI → Combo

属性名	类型	默认值	功能说明
dropbox	string	无	下拉列表容器的属性列表
dropboxsize	size	0,150	下拉列表的大小 (width,height)
itemfont	int	-1	下拉项字体
itemselectedbkcolor	color	0xFFC1E3FF	下拉项选中背景色
itemhotbkcolor	color	0xFFE9F5FF	下拉项悬停背景色

                                XML 示例
                                
                            

                                <Combo width="150" height="30" dropboxsize="0,100" text="请选择">
    <ListLabelElement text="选项 A" selected="true" />
    <ListLabelElement text="选项 B" />
    <ListLabelElement text="选项 C" />
</Combo>
                            

🌳 CTreeViewUI 树形视图

树形控件

用于显示层级数据的树形控件。

📁 文件: Control/UITreeView.cpp 👥 继承: CListUI

CControlUI → CContainerUI → CVerticalLayoutUI → List → TreeView

属性名	类型	默认值	功能说明
visiblefolderbtn	bool	true	是否显示展开/折叠按钮
visiblecheckbtn	bool	false	是否显示复选框
itemminwidth	int	0	节点的最小宽度
itemtextcolor	color	0	节点文本颜色
selitemtextcolor	color	0	选中节点文本颜色

                                XML 示例
                                
                            

                                <TreeView width="200" height="300" visiblefolderbtn="true">
    <TreeNode text="根节点 1">
        <TreeNode text="子节点 1.1" />
        <TreeNode text="子节点 1.2" />
    </TreeNode>
    <TreeNode text="根节点 2">
        <TreeNode text="子节点 2.1" />
    </TreeNode>
</TreeView>
                            

⚡ CActiveXUI ActiveX 容器

高级控件

用于加载 ActiveX 控件。

📁 文件: Control/UIActiveX.cpp 👥 继承: CControlUI

CControlUI → ActiveX

属性名	类型	默认值	功能说明
clsid	string	无	ActiveX 控件的 CLSID (如 `{xxx-xxx...}`)
modulename	string	无	包含 ActiveX 控件的模块 (DLL) 名称
delaycreate	bool	true	是否延迟创建控件

XML 示例

<ActiveX clsid="{D27CDB6E-AE6D-11CF-96B8-444553540000}" width="400" height="300" />

🌐 CWebBrowserUI IE 浏览器

高级控件

封装了 IE 内核的浏览器控件。

📁 文件: Control/UIWebBrowser.cpp 👥 继承: CActiveXUI

CControlUI → ActiveX → WebBrowser

属性名	类型	默认值	功能说明
homepage	string	无	初始主页 URL
autonavi	bool	false	是否自动导航到主页

XML 示例

<WebBrowser homepage="https://www.baidu.com" autonavi="true" width="800" height="600" />

▶ CGifAnimUI GIF 动画

高级控件

播放 GIF 动画。

📁 文件: Control/UIGifAnim.cpp 👥 继承: CControlUI

CControlUI → GifAnim

属性名	类型	默认值	功能说明
autoplay	bool	true	是否自动播放
autosize	bool	false	是否根据图片大小自动调整控件大小

XML 示例

<GifAnim bkimage="loading.gif" autoplay="true" autosize="true" />

⌘ CHotKeyUI 热键控件

系统控件

用于捕获用户键盘热键输入。

📁 文件: Control/UIHotKey.cpp 👥 继承: CLabelUI

CControlUI → Label → HotKey

属性名	类型	默认值	功能说明
normalimage	string	无	正常背景图
hotimage	string	无	悬停背景图
focusedimage	string	无	焦点背景图
disabledimage	string	无	禁用背景图
nativebkcolor	color	0xFFFFFFFF	原生热键控件背景色

XML 示例

<HotKey width="100" height="30" focusedimage="hotkey_focus.png" />

📅 CDateTimeUI 日期时间

系统控件

日期时间选择控件，封装了系统的 SysDateTimePick32 窗口。

📁 文件: Control/UIDateTime.cpp 👥 继承: CLabelUI

CControlUI → Label → DateTime

该控件主要继承 CLabelUI 属性，无特有 XML 属性，通常通过代码设置时间。

XML 示例

<DateTime width="120" height="30" textpadding="5,0,0,0" />

⚡ CFlashUI Flash 控件

高级控件

专门用于播放 Flash (SWF) 的控件，继承自 CActiveXUI。

📁 文件: Control/UIFlash.cpp 👥 继承: CActiveXUI

CControlUI → ActiveX → Flash

该控件继承自 CActiveXUI，无特殊 XML 属性，核心通过加载 Flash CLSID 实现。

XML 示例

<Flash width="400" height="300" />

🎯 Duilib 全控件综合演示

综合示例

AllControlsDemo.xml

这是一个包含所有主要控件的综合 XML 窗口示例。你可以直接保存为 AllControlsDemo.xml 并在 Duilib 程序中加载它来预览效果。

                                    完整 XML 示例
                                    
                                

                                    <?xml version="1.0" encoding="utf-8"?>
<Window size="900,700" caption="Duilib 全控件演示窗口" mininfo="600,400" roundcorner="5,5">
    <VerticalLayout bkcolor="#FFFFFFFF" inset="15,15,15,15" childpadding="10">
        <HorizontalLayout height="40" bkcolor="#FF336699">
            <Label text="Duilib Controls Gallery" textcolor="#FFFFFFFF" font="0" align="left" valign="vcenter" />
        </HorizontalLayout>

        <HorizontalLayout childpadding="15">
            <VerticalLayout width="300" childpadding="10">
                <Label text="【基础控件】" height="20" font="1" />
                <HorizontalLayout height="30" childpadding="5">
                    <Button text="普通按钮" width="80" />
                    <Label text="普通文本标签" align="center" valign="vcenter" />
                </HorizontalLayout>
            </VerticalLayout>
        </HorizontalLayout>
    </VerticalLayout>
</Window>
                                

为了保证预览效果，部分需要资源文件（图片/GIF）的属性被设为了默认或颜色填充，实际使用时请替换为你项目中的图片路径。