AtomUI/docs/Desktop.Controls/Message/MessageStyling.md

Message 自定义样式指南

Message 系统由 MessageCard（单条消息）和 WindowMessageManager（容器管理器）两部分组成，各自有独立的 ControlTheme。由于 Message 是通过代码创建（而非 AXAML 声明式使用），自定义样式主要通过 Style 选择器和 Token 资源覆盖实现。

---

1. 通过构造参数控制

最直接的方式是通过 Message 构造函数参数控制消息的表现：

// 不同消息类型
_messageManager?.Show(new Message("操作成功", MessageType.Success));
_messageManager?.Show(new Message("发生错误", MessageType.Error));
_messageManager?.Show(new Message("请注意", MessageType.Warning));
_messageManager?.Show(new Message("正在加载...", MessageType.Loading));

// 自定义过期时间
_messageManager?.Show(new Message(
    content: "这条消息 10 秒后关闭",
    expiration: TimeSpan.FromSeconds(10)
));

// 永不自动关闭
_messageManager?.Show(new Message(
    content: "需要手动关闭",
    expiration: TimeSpan.Zero
));

// 自定义图标
_messageManager?.Show(new Message(
    content: "自定义图标消息",
    icon: new HeartFilled()
));

📖 完整示例参考：controlgallery/AtomUIGallery/ShowCases/Views/Feedback/MessageShowCase.axaml.cs

---

2. 通过 Style 覆盖 MessageCard 样式

可以在 AXAML 中对 MessageCard 进行全局样式覆盖：

自定义消息卡片外观

<Window.Styles>
    <!-- 统一调整消息卡片的圆角 -->
    <Style Selector="atom|MessageCard /template/ Border#PART_Frame">
        <Setter Property="CornerRadius" Value="4" />
    </Style>

    <!-- 调整消息文本样式 -->
    <Style Selector="atom|MessageCard /template/ SelectableTextBlock#PART_Message">
        <Setter Property="FontWeight" Value="SemiBold" />
    </Style>
</Window.Styles>

按消息类型定制图标颜色

<Window.Styles>
    <!-- 自定义成功消息的图标颜色 -->
    <Style Selector="atom|MessageCard[MessageType=Success] /template/ atom|IconPresenter">
        <Setter Property="IconBrush" Value="#52c41a" />
    </Style>

    <!-- 自定义错误消息的图标颜色 -->
    <Style Selector="atom|MessageCard[MessageType=Error] /template/ atom|IconPresenter">
        <Setter Property="IconBrush" Value="#ff4d4f" />
    </Style>
</Window.Styles>

通过样式类附加自定义样式

WindowMessageManager.Show 方法支持附加样式类名，可以为特定消息指定独立样式：

// 显示消息时附加样式类
_messageManager?.Show(
    new Message("Important!", MessageType.Warning),
    classes: new[] { "important" }
);

<Window.Styles>
    <!-- 仅对带 "important" 样式类的消息生效 -->
    <Style Selector="atom|MessageCard.important /template/ Border#PART_Frame">
        <Setter Property="BorderBrush" Value="Orange" />
        <Setter Property="BorderThickness" Value="1" />
    </Style>
</Window.Styles>

---

3. 通过 WindowMessageManager 属性控制

// 在 OnAttachedToVisualTree 中初始化
var topLevel = TopLevel.GetTopLevel(this);
_messageManager = new WindowMessageManager(topLevel)
{
    MaxItems = 10,          // 最多同时显示 10 条消息
    Position = NotificationPosition.TopCenter  // 顶部居中（默认行为）
};

---

4. 控制动画行为

// 禁用消息入场/出场动画
_messageManager = new WindowMessageManager(topLevel)
{
    IsMotionEnabled = false
};

当 IsMotionEnabled = false 时，消息将直接显示/消失，不播放滑入/滑出动画。

---

5. 通过 ControlTheme 替换主题

如果需要彻底替换 MessageCard 的模板，可以定义自定义 ControlTheme：

<ControlTheme x:Key="MyCustomMessageCard" TargetType="atom:MessageCard">
    <Setter Property="Template">
        <ControlTemplate>
            <atom:MotionActor Name="{x:Static atom:BaseMotionActor.MotionActorPart}"
                              ClipToBounds="False">
                <Border Background="#f6ffed" CornerRadius="8" Padding="12,8"
                        BoxShadow="0 2 8 0 #0000001a">
                    <StackPanel Orientation="Horizontal" Spacing="8">
                        <atom:IconPresenter Name="PART_IconContent"
                                            Icon="{TemplateBinding Icon}"
                                            Width="16" Height="16" />
                        <TextBlock Name="PART_Message"
                                   Text="{TemplateBinding Message}"
                                   VerticalAlignment="Center" />
                    </StackPanel>
                </Border>
            </atom:MotionActor>
        </ControlTemplate>
    </Setter>
</ControlTheme>

⚠️ 注意：替换 ControlTheme 时必须保留 MotionActor（名称为 PART_MotionActor），否则入场/出场动画将失效。

---

样式选择器速查

说明：Avalonia 样式选择器中使用 atom|MessageCard 语法引用 atom XML 命名空间下的 MessageCard 类型，其中 | 是命名空间分隔符。

按控件类型选择

选择器	说明
atom|MessageCard	匹配所有消息卡片实例
atom|WindowMessageManager	匹配消息容器管理器

按消息类型选择

选择器	说明
atom|MessageCard[MessageType=Information]	匹配信息类型消息
atom|MessageCard[MessageType=Success]	匹配成功类型消息
atom|MessageCard[MessageType=Warning]	匹配警告类型消息
atom|MessageCard[MessageType=Error]	匹配错误类型消息
atom|MessageCard[MessageType=Loading]	匹配加载中类型消息

按伪类选择

选择器	说明
atom|MessageCard:information	信息类型伪类（等效于属性选择器）
atom|MessageCard:success	成功类型伪类
atom|MessageCard:warning	警告类型伪类
atom|MessageCard:error	错误类型伪类
atom|MessageCard:loading	加载中类型伪类

按状态选择

选择器	说明
atom|MessageCard[IsClosed=True]	匹配已关闭的消息（此时 Margin 被清零）

模板部件选择

选择器	说明
atom|MessageCard /template/ Border#PART_Frame	消息卡片主框架（背景、阴影、圆角）
atom|MessageCard /template/ atom|IconPresenter#PART_IconContent	消息图标展示器
atom|MessageCard /template/ SelectableTextBlock#PART_Message	消息文本
atom|MessageCard /template/ DockPanel#PART_HeaderContainer	内容布局容器

组合选择器示例

选择器	说明
atom|MessageCard[MessageType=Error] /template/ atom|IconPresenter	错误消息的图标展示器
atom|MessageCard.important /template/ Border#PART_Frame	带 "important" 样式类的消息主框架
atom|WindowMessageManager:topcenter /template/ ReversibleStackPanel#PART_Items	顶部居中位置时的消息列表面板