选择器：
tabwidget· 设计器组件： 选项卡 · 按名称：tabwidget#名称或#名称
用途： 多页内容切换。
硬约束与叠画
- 控件名来自窗口 XML「名称」；属性赋值无括号（如
标题 = "确定"），方法调用必须带括号（如刷新()）。 - 事件写
函数 控件名.事件名(参数…)，形参类型以本页事件表为准。 - 任意控件客户区叠画用支持库 绘制类：
绘制类 g→g.绑组件(本控件名)（组件名无引号）。画布场景编辑见 画布控件。 - 字体对象见绘制文档中的字体类；
置字体(字体类)将字体应用到本控件。 - 不要虚构未列出的方法；YSS 键见下文与 YSS.md。
- 键盘切页：
Ctrl+←/→（标签栏在左/右时为Ctrl+↑/↓），或Ctrl+Tab/Ctrl+Shift+Tab。裸方向键留给页内控件（如数据表格单元格移动）。
属性
设计器属性面板与代码侧可读可写属性（来源：组件类库）。
| 属性 | 类型 | 读写 | 说明 |
|---|---|---|---|
提示 |
文本 | 读写 | 鼠标悬停时的提示文字 |
鼠标指针 |
文本 | 读写 | 空=默认；可用 arrow/hand/ibeam/cross/wait/no/sizeall 等预设，或.cur/.ani 路径（如 资源/press.cur） |
左边 |
小数 | 读写 | 相对窗体左边的位置（像素） |
顶边 |
小数 | 读写 | 相对窗体顶边的位置（像素） |
宽度 |
小数 | 读写 | 控件宽度（像素） |
高度 |
小数 | 读写 | 控件高度（像素） |
停靠 |
整数 | 读写 | 0无 1上 2下 3左 4右 5填充；菜单/工具/状态栏仍用专用吸附 |
可见 |
逻辑 | 读写 | 真=显示，假=隐藏 |
启用 |
逻辑 | 读写 | 真=可用，假=禁用 |
句柄 |
长整数 | 只读 | 组件逻辑句柄（1 起，供动画类等绑定；非 HWND）；只读 |
页列表 |
文本 | 读写 | 每行一页标题 |
当前页 |
整数 | 读写 | 0 起，对应页列表行号 |
标签栏高度 |
整数 | 读写 | 标签栏高度（像素） |
圆角 |
整数 | 读写 | 像素，0=直角 |
显示边框 |
逻辑 | 读写 | 真=显示边框 |
边框大小 |
整数 | 读写 | 像素 |
边框颜色 |
文本 | 读写 | 如 #RRGGBB |
页可关闭 |
逻辑 | 读写 | 总开关：真=允许关闭；页列表可单独勾选某页 |
页图标大小 |
整数 | 读写 | 标签图标边长（像素） |
图文间距 |
整数 | 读写 | 图标与标题间距 |
文本位置 |
整数/枚举 | 读写 | 标签标题对齐：左对齐 / 居中（新建默认） / 右对齐；属性面板「文本位置」，不是 YSS |
关闭按钮位置 |
整数 | 读写 | 0=右中，1=右下，2=左上，3=左下，4=右上，5=左中 |
标签位置 |
整数 | 读写 | 0=上，1=下，2=左，3=右 |
标签页位置 |
整数 | 读写 | 0=边框外（标签在内容区边框外，默认），1=边框内（标签画在控件外框内）。例：选项卡1.标签页位置 = 1。与「标签风格」无关 |
标签风格 |
整数 | 读写 | 0=经典，1=分段，2=胶囊。例：选项卡1.标签风格 = 1 |
可拖动 |
逻辑 | 读写 | 真=允许拖动标签排序 |
拖动动画 |
整数 | 读写 | 0=Excel经典，1=柔和，2=快速吸附，3=仅标签动，4=无动画，5=淡入淡出，6=弹性，7=加速，8=正弦，9=缓出 |
切换动画 |
整数 | 读写 | 0=Excel经典，1=柔和，2=快速吸附，3=仅标签动，4=无动画，5=淡入淡出，6=弹性，7=加速，8=正弦，9=缓出 |
标签栏宽度 |
整数 | 读写 | 左/右标签位置时栏宽（0=按内容自动） |
标签栏水平内边距 |
整数 | 读写 | 标签栏内水平留白（像素） |
标签栏垂直内边距 |
整数 | 读写 | 标签栏内垂直留白（像素） |
内容区左内边距 |
整数 | 读写 | 内容区左侧内边距（像素） |
内容区上内边距 |
整数 | 读写 | 内容区顶部内边距（像素） |
内容区右内边距 |
整数 | 读写 | 内容区右侧内边距（像素） |
内容区下内边距 |
整数 | 读写 | 内容区底部内边距（像素） |
单页隐藏标签栏 |
逻辑 | 读写 | 已取消自动隐藏（标签栏始终显示）；属性保留兼容，默认假 |
标签背景色 |
文本 | 读写 | 普通标签背景，如 #RRGGBB |
标签悬停背景色 |
文本 | 读写 | 如 #3E3E42 |
标签选中背景色 |
文本 | 读写 | 如 #0E639C |
标签文字色 |
文本 | 读写 | 如 #DCDCDC |
标签悬停文字色 |
文本 | 读写 | 如 #FF6644 |
标签选中文字色 |
文本 | 读写 | 如 #FFFFFF |
内容区背景色 |
文本 | 读写 | 如 #2D2D30 |
显示角标 |
逻辑 | 读写 | 真=显示页角标 |
角标背景色 |
文本 | 读写 | 角标默认背景色，如 #RRGGBB |
角标字号 |
整数 | 读写 | 角标文字字号（像素） |
角标文字色 |
文本 | 读写 | 角标默认文字色 |
方法
调用必须带括号。页索引从 0 起。下表为带类型签名。
| 方法 | 签名 | 返回 | 说明 |
|---|---|---|---|
置当前页 |
无 置当前页(整数 索引) |
无 | |
取当前页 |
整数 取当前页() |
整数 | |
加入页 |
无 加入页(文本 文本) |
无 | 末尾追加 |
插入页 |
无 插入页(整数 索引, 文本 文本) |
无 | |
删除页 |
无 删除页(整数 索引) |
无 | |
置页标题 |
无 置页标题(整数 索引, 文本 文本) |
无 | |
取页标题 |
文本 取页标题(整数 索引) |
文本 | |
取页数 |
整数 取页数() |
整数 | |
移动页 |
整数 移动页(整数 原索引, 整数 目标索引) |
整数 | |
置页图标 |
无 置页图标(整数 索引, 文本 路径) |
无 | :/ 或文件路径 |
取页图标 |
文本 取页图标(整数 索引) |
文本 | |
置页启用 |
无 置页启用(整数 索引, 逻辑 启用) |
无 | |
取页启用 |
整数 取页启用(整数 索引) |
整数 | 1/0 |
置页角标 |
无 置页角标(整数 索引, 文本 角标) |
无 | 空文本清除 |
取页角标 |
文本 取页角标(整数 索引) |
文本 | |
清空 |
无 清空() |
无 | |
置下一页 |
无 置下一页() |
无 | 遵循切换动画 |
置上一页 |
无 置上一页() |
无 | |
置首页 |
无 置首页() |
无 | |
置尾页 |
无 置尾页() |
无 | |
取下一页 |
整数 取下一页() |
整数 | 不改变当前页 |
取上一页 |
整数 取上一页() |
整数 | |
取首页 |
整数 取首页() |
整数 | 恒 0 |
取尾页 |
整数 取尾页() |
整数 | |
移动 |
无 移动(小数 左边, 小数 顶边, [小数 宽度], [小数 高度]) |
无 | 可选同时改宽高 |
置焦点 |
无 置焦点() |
无 | |
刷新 |
无 刷新() |
无 | |
显示 |
无 显示() |
无 | 等同 可见 = 真 |
隐藏 |
无 隐藏() |
无 | 等同 可见 = 假 |
页签1.加入页("概况")
页签1.置当前页(0)
事件
在代码中写 函数 控件名.事件名(...) 处理。
| 事件 | 参数 | 说明 |
|---|---|---|
单击 |
整数 X, 整数 Y | 鼠标左键单击控件。 |
双击 |
整数 X, 整数 Y | 鼠标左键双击控件。 |
右键单击 |
整数 X, 整数 Y | 鼠标右键单击控件。 |
鼠标按下 |
整数 X, 整数 Y, 逻辑 按下 | 鼠标键在控件上按下。按下=真表示当前仍按住。 |
鼠标抬起 |
整数 X, 整数 Y, 逻辑 按下 | 鼠标键在控件上放开。 |
鼠标移动 |
整数 X, 整数 Y, 逻辑 按下 | 鼠标在控件上移动。按下表示左键是否按住。 |
鼠标进入 |
整数 X, 整数 Y | 鼠标指针进入控件区域。 |
鼠标离开 |
整数 X, 整数 Y | 鼠标指针离开控件区域。 |
鼠标左键单击 |
整数 X, 整数 Y | 鼠标左键单击（与「单击」同时触发）。 |
鼠标左键双击 |
整数 X, 整数 Y | 鼠标左键双击（与「双击」同时触发）。 |
鼠标中间单击 |
整数 X, 整数 Y | 鼠标中键单击控件。 |
鼠标齿轮滚动 |
整数 X, 整数 Y, 逻辑 向上 | 在控件上滚动鼠标滚轮。向上=真表示向上滚。 |
鼠标右键单击 |
整数 X, 整数 Y | 鼠标右键单击（与「右键单击」同时触发）。 |
鼠标右键双击 |
整数 X, 整数 Y | 鼠标右键双击控件。 |
当前页改变 |
整数 当前索引, 文本 项目 | 当前页索引已改变时触发（程序置页或用户点击标签）。 |
即将切换 |
整数 旧索引, 整数 新索引 | 页索引即将改变时触发（点击另一标签或程序置页前）。 |
正在切换 |
整数 旧索引, 整数 新索引 | 页切换动画进行中周期性触发。 |
切换完成 |
整数 当前索引, 文本 项目 | 页切换动画结束且新页已显示后触发。 |
即将拖动 |
整数 当前索引, 文本 项目 | 用户按下标签准备拖动排序时触发。 |
拖动中 |
整数 旧索引, 整数 新索引 | 标签拖动排序过程中触发。 |
拖动完成 |
整数 旧索引, 整数 新索引 | 标签拖动排序结束且顺序已更新后触发。 |
关闭请求 |
整数 当前索引, 文本 项目 | 用户点击标签×或程序删除页前触发。 |
关闭完成 |
整数 当前索引, 文本 项目 | 页已关闭并从列表移除后触发。 |
函数 选项卡1.单击 (整数 X, 整数 Y) {
// …
}
YSS 样式
以下为样式表（.yss）键与示例；写样式前请先读窗体 XML 取控件 名称 与 typeId，见 window-xml.md。
样式概览
YSS 分三层：标签栏轨道（位置/厚度/风格）、标签页（选中/悬停/圆角/阴影）、内容区 pane（底色可按页切换）。
伪状态与映射
子控件 / 伪类： tabwidget:tab · tabwidget:tab:selected · tabwidget:tab:hover · tabwidget:pane
伪态映射（ 必读）：
| 在子选择器 / 伪态块中写的键 | 实际落到控件的字段 |
|---|---|
tabwidget:tab:selected { background-color } / background |
item-selected-background |
tabwidget:tab:selected { color } |
item-selected-color |
tabwidget:tab:hover { background-color } / background |
item-hover-background |
tabwidget:tab:hover { color } |
item-hover-color |
tabwidget:pane { background-color } / background |
pane-background-color |
:selected 伪类 |
与 :pressed 同义，映射到 当前页标签 配色键 |
也可直接在基选择器写 item-selected-* / item-hover-* / pane-background-color 等键，效果相同。
阴影与内边距（pill/segmented 必读）： 在
tab-style: segmented或pill下，shadow-offset-x/shadow-offset-y只偏移选中标签块的软阴影，不再充当标签栏轨道的内边距。轨道内留白请用item-padding（胶囊默认约 4px，见下表）。
经典模式例外：tab-style: classic时，正数shadow-offset-*仍可能缩进标签栏绘制区（历史行为）；新样式表请优先item-padding。渐变注意： 选项卡上写
background-gradient时，不会覆盖轨道background-color与 pane 的backColor2；多停渐变供选中标签绘制，首色同步到item-selected-background作回退。
属性说明（逐键）
本控件支持 YSS 通用属性速查 中的外壳子集；下表按「标签栏布局 → 标签风格 → 指示条 → 标签配色 → 内容区 → 图标 → 阴影 → 外壳 → 字体」展开。
标签栏布局
| 属性 | 作用 | 取值 / 范围 | 说明与注意 |
|---|---|---|---|
tab-bar-position |
标签栏位置 | top/0 · bottom/1 · left/2 · right/3 |
亦可用中文「上/下/左/右」。 |
tab-bar-height |
标签栏厚度 | 像素 20–200，默认约 28 |
不含内容区高度；左右栏位时为栏宽。 |
closable-tabs / page-closable |
页可关闭（全局默认） | true / false |
对应属性「页可关闭」；单页是否显示 × 仍看页数据。 |
标签风格（轨道 + 选中块）
| 属性 | 作用 | 取值 / 范围 | 说明与注意 |
|---|---|---|---|
tab-style / tabs-style |
标签栏视觉模式 | classic/0 · segmented/1/分段 · pill/capsule/2/胶囊 |
与属性「标签风格」一致。classic：独立标签块。segmented：轨道内分段+分隔线。pill：轨道内胶囊选中块。未写 YSS 时以「标签风格」为准。 |
item-radius / item-border-radius / item-corner-radius |
选中标签块圆角 | 像素 0–64 |
segmented/pill 下覆盖 border-radius 对标签块的影响；pill 下若超过内缩后高度的一半会自动钳制。 |
item-padding / tab-padding / tab-item-padding |
标签相对轨道内边距 | 像素 0–32 |
仅 pill 四向内缩选中块（未选中标签透明）。默认约 4；设 box-shadow 且 shadow-blur>0 时，运行时会自动加大 item-padding 以免光晕被轨道裁切——这是阴影留白，不是把 shadow-offset 当 padding。 |
选中指示条（classic 专用）
| 属性 | 作用 | 取值 / 范围 | 说明与注意 |
|---|---|---|---|
tab-indicator / tab-indicator-style |
当前页指示样式 | none/0/无 · underline/bar/1/下划线 · notch/arrow/2/三角 |
仅 tab-style: classic 绘制；segmented/pill 请设 none。underline=底边条；notch=指向内容区的三角缺口（管家风格）。 |
tab-indicator-color |
指示条/三角颜色 | 颜色 | 映射 focus-border-color；默认白或跟随选中文字色。 |
tab-indicator-transition / indicator-transition |
指示条滑动时长 | 如 180ms；0/none=无过渡 |
与窗体「切换动画」预设独立；切换动画=无时 notch/underline 仍可滑动。 |
勿与按钮
border-style: underline混淆：后者是按钮底边线，不是选项卡指示条。
标签配色（皮肤）
| 属性 | 作用 | 取值 / 范围 | 说明与注意 |
|---|---|---|---|
color |
未选中标签文字色 | 颜色 | classic 下亦作标签底板参考。 |
background-color / background |
标签栏轨道底色 | 颜色 | segmented/pill 下铺整段轨道圆角矩形；classic 下为未选中标签底。 |
item-selected-background |
当前页标签背景 | 颜色 | segmented/pill 下仅选中块；classic 下为选中标签底。 |
item-hover-background |
悬停标签背景 | 颜色 | 未选中页悬停；segmented/pill 下铺圆角块。 |
item-selected-color |
当前页标签文字色 | 颜色 | |
item-hover-color |
悬停标签文字色 | 颜色 | |
background-gradient / background-gradient-stops |
选中标签多停渐变 | ≥2 色，逗号/分号分隔 | segmented 模式首尾页圆角与渐变配合；≥2 停即写入旁路表。 |
内容区（pane）
| 属性 | 作用 | 取值 / 范围 | 说明与注意 |
|---|---|---|---|
pane-background-color |
内容区统一底色 | 颜色；transparent 可透 |
亦可用 tabwidget:pane { background-color }。 |
pane-backgrounds / page-backgrounds / pane-background-colors |
按页序内容区底色 | 逗号/分号分隔颜色，如 #FFF, #F5F5F5, transparent |
随当前页切换；transparent/0 表示该页 pane 不垫色。与 pane-background-color 二选一或以后者覆盖默认。 |
页图标
| 属性 | 作用 | 取值 / 范围 | 说明与注意 |
|---|---|---|---|
page-icon-size |
页图标边长 | 像素 8–128 |
|
icon-text-spacing |
图标与标题间距 | 像素 0–32 |
|
page-icons / tab-icons / item-icons |
按页序图标路径 | 如 :/img/a.png, :/img/b.png |
路径 :/ 相对 exe 根；页序与 XML/代码页列表一致。 |
阴影（选中块）
| 属性 | 作用 | 取值 / 范围 | 说明与注意 |
|---|---|---|---|
shadow / box-shadow |
启用选中块阴影 | true / false |
segmented/pill 下作用于当前页标签块；classic 下一般不用于标签浮动。 |
shadow-color |
阴影色 | 颜色 | pill 常用与选中底同色半透明光晕。 |
shadow-blur |
软阴影模糊半径 | 0–64 |
pill 下 blur>0 时可能触发 item-padding 自动加大（见上表）。 |
shadow-offset-x / shadow-offset-y |
阴影偏移 | -64–64 |
只移动阴影绘制位置；segmented/pill 不是标签栏 padding。 |
shadow-style |
阴影风格 | soft / hard |
同按钮语义。 |
外壳 · 描边
| 属性 | 作用 | 取值 / 范围 | 说明与注意 |
|---|---|---|---|
show-border |
内容区外框 | true / false |
主要描 content pane 轮廓。 |
border-color |
边框色 | 颜色 | classic 下亦影响标签分隔线色。 |
border-width |
边框宽 | 像素 | |
border-radius / corner-radius |
外框/轨道圆角 | 像素 0–64 |
segmented/pill 轨道圆角；标签块圆角见 item-radius。 |
opacity |
整控不透明度 | 0–100 |
|
font-size / font-family / font-bold / font-italic |
标签字体 | 同通用 |
角标用代码 置页角标；segmented/pill 模式下可不依赖 outer-glow-size。
使用示例
胶囊导航（pill）
tabwidget#胶囊导航 {
tab-style: pill;
tab-bar-height: 48;
border-radius: 24;
item-radius: 18;
item-padding: 4;
background-color: #F3F4F6;
item-selected-background: #7C4DFF;
item-selected-color: #FFFFFF;
box-shadow: true;
shadow-color: #7C4DFF;
shadow-blur: 14;
shadow-offset-y: 4;
tab-indicator: none;
pane-background-color: transparent;
}
分段导航（segmented + 渐变选中）
tabwidget#分段导航 {
tab-style: segmented;
tab-bar-height: 44;
border-radius: 10;
background-color: #ECEFF1;
background-gradient: #64B5F6, #1E88E5;
item-selected-color: #FFFFFF;
tab-indicator: none;
pane-background-color: #FFFFFF;
}
经典 + 三角指示（notch）
tabwidget#选项卡1 {
tab-style: classic;
tab-bar-position: top;
tab-bar-height: 48;
page-icon-size: 18;
icon-text-spacing: 6;
background-color: #1E7AD6;
item-selected-background: #1565B8;
item-selected-color: #FFFFFF;
tab-indicator: notch;
tab-indicator-color: #FFFFFF;
tab-indicator-transition: 180ms;
pane-background-color: transparent;
}
按页 pane 底色
tabwidget#多色内容 {
pane-backgrounds: #FFFFFF, #F0F4F8, transparent;
}
子选择器写法
tabwidget:tab:selected {
background-color: #0E639C;
color: #FFFFFF;
}
tabwidget:tab:hover {
background-color: #3E3E42;
}
tabwidget:pane {
background-color: #252526;
}
完整示例
tabwidget#主导航 {
tab-style: pill;
tab-bar-position: top;
tab-bar-height: 44;
border-radius: 12;
item-radius: 10;
item-padding: 4;
background-color: #2D2D30;
item-selected-background: #007ACC;
item-selected-color: #FFFFFF;
item-hover-background: #3E3E42;
tab-indicator: none;
box-shadow: true;
shadow-color: #007ACC;
shadow-blur: 10;
shadow-offset-y: 2;
pane-background-color: #252526;
show-border: true;
border-color: #3F3F46;
font-size: 13;
}
tabwidget:tab:selected {
background-color: #007ACC;
color: #FFFFFF;
}
tabwidget:pane {
background-color: #252526;
}