AtomUI/docs/Desktop.Controls/Separator/SeparatorAPI.md

Separator API 参考

命名空间

namespace AtomUI.Desktop.Controls;       // Separator, VerticalSeparator
namespace AtomUI.Controls.Commons;        // AbstractSeparator（设备无关基类）
namespace AtomUI.Controls;                // SeparatorTitlePosition, SeparatorVariant, SeparatorPseudoClass, SizeType

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

---

枚举类型

SeparatorTitlePosition

标题位置枚举，定义标题在水平分割线中的位置。

值	说明
Left	标题靠左，左侧为短线条（或无线条，取决于 OrientationMargin）
Right	标题靠右，右侧为短线条
Center	标题居中（默认），两侧等长线条

SeparatorVariant

线条样式变体枚举。

值	说明
Solid	实线（默认），连续直线
Dotted	点线，[1, 1] 间隔
Dashed	虚线，[4, 2] 间隔

SizeType（来自 AtomUI.Controls）

尺寸类型枚举。

值	说明
Small	小号
Middle	中号（默认）
Large	大号

---

公共属性（StyledProperty）

以下属性定义在 AbstractSeparator（设备无关基类），Separator 和 VerticalSeparator 完整继承。

属性名	类型	默认值	说明
Title	string?	null	分割线标题文本（内容属性 [Content]，仅水平方向有效）。设置后自动激活 :has-title 伪类
TitlePosition	SeparatorTitlePosition	Center	标题在线条中的位置：Left（靠左）、Center（居中）、Right（靠右）
TitleColor	IBrush?	ColorTextHeading	标题文本颜色。未设置时由主题通过 SharedToken.ColorTextHeading 控制
LineColor	IBrush?	ColorSplit	分割线颜色。未设置时由主题通过 SharedToken.ColorSplit 控制
Orientation	Orientation	Horizontal	分割线方向。Horizontal：水平全宽线条；Vertical：垂直短线条
Variant	SeparatorVariant	Solid	线条样式变体：Solid（实线）、Dashed（虚线）、Dotted（点线）
OrientationMargin	double	NaN	标题距左/右边缘的精确像素值。设为 NaN（默认）时使用 OrientationMarginPercent 百分比计算
LineWidth	double	1	线条宽度（像素），由主题通过 SharedToken.LineWidth 控制
IsPlain	bool	false	标题是否使用普通正文样式。false 时使用大字号加粗，true 时使用正常字号字重
SizeType	SizeType	Middle	分割线垂直间距尺寸（共享属性，通过 AddOwner 注册）。仅影响水平分割线的上下 Margin

继承自 Avalonia.Controls.Separator 的常用属性

属性名	类型	默认值	说明
Margin	Thickness	由主题控制	外间距，水平分割线的上下间距由 SizeType 对应的 Token 自动设置
IsEnabled	bool	true	是否启用
Background	IBrush?	由主题控制	背景色
Foreground	IBrush?	由主题控制	前景色
FontSize	double	由主题控制	标题文字大小，IsPlain=False 时为 FontSizeLG，IsPlain=True 时为 FontSize
FontWeight	FontWeight	由主题控制	标题文字粗细，IsPlain=False 时为 500（Medium），IsPlain=True 时为 Normal
FontStyle	FontStyle	Normal	标题文字样式（Normal / Italic / Oblique）
HorizontalAlignment	HorizontalAlignment	由主题控制	水平对齐。水平分割线主题设为 Stretch，垂直分割线设为 Center
VerticalAlignment	VerticalAlignment	由主题控制	垂直对齐。两种方向均由主题设为 Center

---

内部属性（由主题/Token 驱动）

以下属性为 internal，由 ControlTheme 通过 Token 资源绑定设置，开发者无需手动操作：

属性名	类型	来源	说明
TextPaddingInline	double	SeparatorToken.TextPaddingInline	标题文本两侧的横向内间距（单位 em），默认 1.0
OrientationMarginPercent	double	SeparatorToken.OrientationMarginPercent	标题与边缘距离的百分比（0～1），默认 0.05
VerticalMarginInline	double	SeparatorToken.VerticalMarginInline	垂直分割线的横向外间距

---

伪类（Pseudo-Classes）

Separator 支持以下伪类，可在样式选择器中使用：

伪类	常量	触发条件
:has-title	SeparatorPseudoClass.HasTitleText	Title 属性不为 null 且不为空字符串

继承的标准伪类

伪类	触发条件
:disabled	IsEnabled == false

---

实现的接口

ISizeTypeAware

public SizeType SizeType { get; set; }

支持 SizeType（Small / Middle / Large）三种尺寸，控制水平分割线的垂直间距。通过共享属性 SizeTypeControlProperty.SizeTypeProperty.AddOwner<AbstractSeparator>() 注册。

---

类层次结构

AbstractSeparator（设备无关基类）

namespace AtomUI.Controls.Commons;

[PseudoClasses(SeparatorPseudoClass.HasTitleText)]
public abstract class AbstractSeparator : Avalonia.Controls.Separator, ISizeTypeAware

职责：定义所有平台共享的属性、布局逻辑（MeasureOverride / ArrangeOverride）和自绘渲染（Render）。包含标题定位算法、线条绘制、DashStyle/DotStyle 静态实例等核心逻辑。

关键常量：

• SEPARATOR_LINE_MIN_PROPORTION = 0.25 — 标题区域保证至少 25% 的线条比例

Separator（桌面实现）

namespace AtomUI.Desktop.Controls;

public class Separator : AbstractSeparator
{
    public Separator()
    {
        this.RegisterTokenResourceScope(SeparatorToken.ScopeProvider);
    }
}

职责：注册桌面端 SeparatorToken 的 Token 作用域，使主题能通过 Token 资源键控制视觉属性。

VerticalSeparator（垂直分割线便捷类）

namespace AtomUI.Desktop.Controls;

public class VerticalSeparator : Separator
{
    static VerticalSeparator()
    {
        OrientationProperty.OverrideDefaultValue<VerticalSeparator>(Orientation.Vertical);
    }
    protected override Type StyleKeyOverride => typeof(Separator);
}

职责：将 Orientation 默认值覆盖为 Vertical，使用时无需手动设置方向。通过 StyleKeyOverride 共享 Separator 的 ControlTheme。

<!-- 两种写法等价 -->
<atom:Separator Orientation="Vertical" />
<atom:VerticalSeparator />

---

模板部件

部件名	控件类型	说明
PART_Title	TextBlock	标题文本，仅在 Orientation=Horizontal 且 Title 不为空时可见。通过 ArrangeOverride 手动定位

---

静态成员

成员	类型	说明
AbstractSeparator.DashStyle	IDashStyle	虚线样式（[4, 2]，offset=0），Variant=Dashed 时使用
AbstractSeparator.DotStyle	IDashStyle	点线样式（[1, 1]，offset=0），Variant=Dotted 时使用