GithubStar/AtomUI

Fork 0

mirror of https://github.com/AtomUI/AtomUI.git synced 2026-10-20 07:39:09 +08:00

Files

T

chinboy 6345fd43a2 docs(TabControl): add comprehensive design, API, styling, token and usage documentation

2026-04-14 00:11:06 +08:00

8.3 KiB

Raw Permalink Blame History

TabControl API 参考

命名空间

namespace AtomUI.Desktop.Controls;

AXAML 命名空间前缀：atom（xmlns:atom="https://atomui.net"）

枚举类型

SizeType（来自 `AtomUI.Controls`）

值	说明
`Small`	小号标签页
`Middle`	中号标签页（默认）
`Large`	大号标签页

TabSharp

标签形状枚举（内部使用，由控件类型自动设置）。

值	说明
`Line`	线条式
`Card`	卡片式

BaseTabControl 公共属性

BaseTabControl 是 TabControl 和 CardTabControl 的共享基类，以下属性对两者均有效。

属性名	类型	默认值	说明
`TabStripPlacement`	`Dock`	`Dock.Top`	标签栏位置（Top/Right/Bottom/Left）
`SizeType`	`SizeType`	`SizeType.Middle`	标签尺寸（共享属性）
`TabAlignmentCenter`	`bool`	`false`	标签是否居中对齐
`IsTabClosable`	`bool`	`false`	是否全局启用标签关闭按钮
`IsTabAutoHideCloseButton`	`bool`	`false`	关闭按钮是否仅悬浮时显示
`HeaderStartExtraContent`	`object?`	`null`	标签栏起始端额外内容
`HeaderStartExtraContentTemplate`	`IDataTemplate?`	`null`	起始端额外内容模板
`HeaderEndExtraContent`	`object?`	`null`	标签栏末端额外内容
`HeaderEndExtraContentTemplate`	`IDataTemplate?`	`null`	末端额外内容模板
`ContentTemplate`	`IDataTemplate?`	`null`	内容面板模板
`ContentPadding`	`Thickness`	由 Token 控制	内容区域内间距
`TabAndContentGutter`	`double`	由 Token 控制	标签栏与内容区域间距
`HeaderStartEdgePadding`	`double`	`0`	标签栏起始端边距
`HeaderEndEdgePadding`	`double`	`0`	标签栏末端边距
`IsMotionEnabled`	`bool`	跟随全局 Token	是否启用过渡动画
`HorizontalContentAlignment`	`HorizontalAlignment`	`Stretch`	内容水平对齐
`VerticalContentAlignment`	`VerticalAlignment`	`Stretch`	内容垂直对齐
`SelectedContent`	`object?`	— (只读)	当前选中标签的内容
`SelectedContentTemplate`	`IDataTemplate?`	— (只读)	当前选中标签的内容模板

继承自 SelectingItemsControl 的常用属性

属性名	类型	默认值	说明
`SelectedIndex`	`int`	`0`	当前选中标签索引
`SelectedItem`	`object?`	—	当前选中项
`ItemsSource`	`IEnumerable?`	`null`	数据绑定源
`ItemTemplate`	`IDataTemplate?`	`null`	数据项模板

CardTabControl 附加属性

CardTabControl 在 BaseTabControl 基础上增加：

属性名	类型	默认值	说明
`IsShowAddTabButton`	`bool`	`false`	是否显示添加标签按钮

BaseTabStrip 公共属性

BaseTabStrip 是 TabStrip 和 CardTabStrip 的共享基类。属性与 BaseTabControl 高度一致，但无内容面板相关属性。

属性名	类型	默认值	说明
`TabStripPlacement`	`Dock`	`Dock.Top`	标签栏位置
`SizeType`	`SizeType`	`SizeType.Middle`	标签尺寸
`TabAlignmentCenter`	`bool`	`false`	标签是否居中对齐
`IsTabClosable`	`bool`	`false`	是否全局启用标签关闭按钮
`IsTabAutoHideCloseButton`	`bool`	`false`	关闭按钮是否仅悬浮时显示
`HeaderStartExtraContent`	`object?`	`null`	标签栏起始端额外内容
`HeaderStartExtraContentTemplate`	`IDataTemplate?`	`null`	起始端额外内容模板
`HeaderEndExtraContent`	`object?`	`null`	标签栏末端额外内容
`HeaderEndExtraContentTemplate`	`IDataTemplate?`	`null`	末端额外内容模板
`HeaderStartEdgePadding`	`double`	`0`	标签栏起始端边距
`HeaderEndEdgePadding`	`double`	`0`	标签栏末端边距
`IsMotionEnabled`	`bool`	跟随全局 Token	是否启用过渡动画

CardTabStrip 附加属性

属性名	类型	默认值	说明
`IsShowAddTabButton`	`bool`	`false`	是否显示添加标签按钮

TabItem 公共属性

TabItem 用于 TabControl / CardTabControl 中的标签项。

属性名	类型	默认值	说明
`Header`	`object?`	`null`	标签标题（继承自 `HeaderedContentControl`）
`HeaderTemplate`	`IDataTemplate?`	`null`	标题模板
`Content`	`object?`	`null`	标签面板内容
`ContentTemplate`	`IDataTemplate?`	`null`	面板内容模板
`Icon`	`PathIcon?`	`null`	标签图标
`CloseIcon`	`PathIcon?`	`CloseOutlined`	关闭按钮图标
`IsClosable`	`bool`	`false`	该标签是否可关闭
`IsAutoHideCloseButton`	`bool`	`false`	关闭按钮是否自动隐藏
`IsSelected`	`bool`	`false`	是否选中
`IsEnabled`	`bool`	`true`	是否启用
`TabStripPlacement`	`Dock?`	— (只读)	标签栏位置（由父容器传递）

TabStripItem 公共属性

TabStripItem 用于 TabStrip / CardTabStrip 中的标签项。

属性名	类型	默认值	说明
`Content`	`object?`	`null`	标签文本内容（继承自 `ContentControl`）
`Icon`	`PathIcon?`	`null`	标签图标
`CloseIcon`	`PathIcon?`	`CloseOutlined`	关闭按钮图标
`IsClosable`	`bool`	`false`	该标签是否可关闭
`IsAutoHideCloseButton`	`bool`	`false`	关闭按钮是否自动隐藏
`IsEnabled`	`bool`	`true`	是否启用
`TabStripPlacement`	`Dock?`	— (只读)	标签栏位置（由父容器传递）

ITabItemData 接口

用于 ItemsSource 数据绑定场景，自动映射属性到 TabItem / TabStripItem。

public interface ITabItemData : IHeadered
{
    PathIcon? Icon { get; }
    PathIcon? CloseIcon { get; }
    bool IsEnabled { get; }
    bool IsClosable { get; }
    bool IsAutoHideCloseButton { get; }
}

TabItemData 是其默认实现，所有属性为 init 属性。

事件

BaseTabControl / BaseTabStrip 事件

事件名	类型	说明
`Closing`	`EventHandler<TabClosingEventArgs>`	标签关闭前触发，可设置 `Cancel = true` 阻止关闭
`Closed`	`EventHandler<TabClosedEventArgs>`	标签成功关闭后触发
`SelectionChanged`	`EventHandler<SelectionChangedEventArgs>`	选中标签变更时触发（继承自 `SelectingItemsControl`）

CardTabControl / CardTabStrip 事件

事件名	类型	说明
`AddTabRequest`	`EventHandler<RoutedEventArgs>`	点击添加按钮时触发

TabClosingEventArgs

属性	类型	说明
`TabItem`	`TabItem`	即将被关闭的标签项
`Cancel`	`bool`	设置为 `true` 阻止关闭

TabClosedEventArgs

属性	类型	说明
`TabItem`	`TabItem`	已关闭的标签项

公共方法

BaseTabControl.CloseTab

public bool CloseTab(TabItem tabItem)

以编程方式关闭指定标签。触发 Closing / Closed 事件流。返回 true 表示成功关闭。

BaseTabStrip.CloseTab

public bool CloseTab(TabStripItem tabStripItem)

同上，用于 TabStrip 系列。

伪类（Pseudo-Classes）

BaseTabControl / BaseTabStrip 伪类

伪类	常量	触发条件
`:top`	`TabPseudoClass.Top`	`TabStripPlacement == Dock.Top`
`:right`	`TabPseudoClass.Right`	`TabStripPlacement == Dock.Right`
`:bottom`	`TabPseudoClass.Bottom`	`TabStripPlacement == Dock.Bottom`
`:left`	`TabPseudoClass.Left`	`TabStripPlacement == Dock.Left`

TabItem / TabStripItem 伪类

伪类	触发条件
`:selected`	该标签被选中
`:pressed`	鼠标按下
`:pointerover`	鼠标悬浮
`:disabled`	`IsEnabled == false`

实现的接口

IMotionAwareControl（BaseTabControl / BaseTabStrip）

public bool IsMotionEnabled { get; set; }

ISizeTypeAware（BaseTabStrip）

public SizeType SizeType { get; set; }

键盘交互

按键	行为
`←` / `→`	水平布局时切换标签
`↑` / `↓`	垂直布局时切换标签
`Tab`	焦点在标签间导航

8.3 KiB Raw Permalink Blame History Unescape Escape