AtomUI/docs/Desktop.Controls/Alert/AlertUsage.md

Alert 使用文档

本文档介绍 AtomUI Alert 控件的各种使用方式，覆盖所有常见场景。

📖 Gallery 源码位置：controlgallery/AtomUIGallery/ShowCases/Views/Feedback/AlertShowCase.axaml

---

前置准备

在 AXAML 中使用 Alert，需要引入以下命名空间：

xmlns:atom="https://atomui.net"
xmlns:antdicons="https://atomui.net/icons/antdesign"

在 C# 代码中引入：

using AtomUI.Desktop.Controls;   // Alert 控件、AlertType 枚举

---

1. 四种类型

AtomUI 提供四种 Alert 类型，通过 Type 属性设置。不设置时默认为 Success。

<StackPanel Spacing="16">
    <atom:Alert Type="Success">Success Tips</atom:Alert>
    <atom:Alert Type="Info">Informational Notes</atom:Alert>
    <atom:Alert Type="Warning">Warning</atom:Alert>
    <atom:Alert Type="Error">Error</atom:Alert>
</StackPanel>

使用场景指引：

• Success：操作成功后的正面反馈，如"保存成功""提交已完成"
• Info：中性提示信息，如使用说明、功能介绍
• Warning：需要用户注意但不阻断操作的提醒，如"即将过期""请备份数据"
• Error：操作失败或存在风险的严重警告，如"验证失败""权限不足"

---

2. 带图标

通过 IsShowIcon="True" 自动显示匹配类型的图标，增强视觉辨识度：

<StackPanel Spacing="16">
    <atom:Alert Type="Success" IsShowIcon="True">Success Tips</atom:Alert>
    <atom:Alert Type="Info" IsShowIcon="True">Informational Notes</atom:Alert>
    <atom:Alert Type="Warning" IsShowIcon="True">Warning</atom:Alert>
    <atom:Alert Type="Error" IsShowIcon="True">Error</atom:Alert>
</StackPanel>

图标自动匹配规则：

• Success → CheckCircleFilled（绿色）
• Info → InfoCircleFilled（蓝色）
• Warning → ExclamationCircleFilled（橙色）
• Error → CloseCircleFilled（红色）

---

3. 带描述信息

添加 Description 可在消息下方展示更多细节。注意此时需使用 Message 属性而非标签内容：

<StackPanel Spacing="16">
    <atom:Alert Type="Success" IsShowIcon="True"
                Message="Success Tips"
                Description="Detailed description and advice about successful copywriting." />
    <atom:Alert Type="Info" IsShowIcon="True"
                Message="Informational Notes"
                Description="Additional description and information about copywriting." />
    <atom:Alert Type="Warning" IsShowIcon="True"
                Message="Warning"
                Description="This is a warning notice about copywriting." />
    <atom:Alert Type="Error" IsShowIcon="True"
                Message="Error"
                Description="This is an error message about copywriting." />
</StackPanel>

视觉变化：设置 Description 后，消息文字自动变大（充当标题角色），图标也随之增大，整体内间距增加。

---

4. 可关闭

通过 IsClosable="True" 在右侧显示关闭按钮：

<StackPanel x:Name="AlertContainer" Spacing="16">
    <atom:Alert Type="Warning" IsClosable="True"
                CloseRequest="HandleAlertClose">
        Warning Text. Warning Text. Warning Text.
    </atom:Alert>

    <atom:Alert Type="Error" IsClosable="True" IsShowIcon="True"
                Message="Error Text"
                Description="Error Description. Error Description."
                CloseRequest="HandleAlertClose" />
</StackPanel>

// Code-behind
private void HandleAlertClose(object? sender, EventArgs e)
{
    if (sender is Alert alert && alert.Parent is Panel panel)
    {
        panel.Children.Remove(alert);
    }
}

重要：CloseRequest 事件触发后 Alert 不会自动移除，你需要在事件处理中手动操作。这使得你可以在关闭前执行额外逻辑（如确认对话框、记录日志等）。

---

5. 自定义关闭图标

<atom:Alert Type="Info" IsClosable="True"
            CloseIcon="{antdicons:AntDesignIconProvider Kind=CloseCircleOutlined}"
            CloseRequest="HandleAlertClose">
    Info with custom close icon
</atom:Alert>

---

6. 带额外操作

通过 ExtraAction 在消息行右侧放置操作控件，通常是 Text 或 Link 类型的小按钮：

<StackPanel Spacing="16">
    <!-- 简单文本按钮 -->
    <atom:Alert Type="Info" IsShowIcon="True" IsClosable="True"
                Message="Information">
        <atom:Alert.ExtraAction>
            <atom:Button ButtonType="Text" SizeType="Small">Detail</atom:Button>
        </atom:Alert.ExtraAction>
    </atom:Alert>

    <!-- 带描述的 Alert + 额外操作 -->
    <atom:Alert Type="Success" IsShowIcon="True" IsClosable="True"
                Message="Submission Successful"
                Description="Your application has been submitted. We will review it within 3 business days.">
        <atom:Alert.ExtraAction>
            <atom:Button ButtonType="Link" SizeType="Small">View Details</atom:Button>
        </atom:Alert.ExtraAction>
    </atom:Alert>
</StackPanel>

---

7. 跑马灯效果

长文本自动水平滚动，适合在有限宽度内展示长消息：

<atom:Alert Type="Warning" IsMessageMarqueeEnabled="True" IsShowIcon="True">
    This is a very long warning message that will scroll automatically when the content overflows the available width.
</atom:Alert>

💡 跑马灯是 AtomUI 的扩展功能，Ant Design React 版不具备此特性。

---

8. 数据绑定

Alert 支持所有属性的数据绑定：

<atom:Alert Type="{Binding AlertType}"
            Message="{Binding AlertMessage}"
            Description="{Binding AlertDescription}"
            IsShowIcon="True"
            IsClosable="{Binding IsAlertClosable}" />

// ViewModel（使用 ReactiveUI）
public class AlertViewModel : ReactiveObject
{
    [Reactive] public AlertType AlertType { get; set; } = AlertType.Info;
    [Reactive] public string AlertMessage { get; set; } = "Dynamic message";
    [Reactive] public string? AlertDescription { get; set; }
    [Reactive] public bool IsAlertClosable { get; set; } = true;
}

---

常见组合模式

页面顶部提示

<StackPanel Spacing="16">
    <atom:Alert Type="Info" IsShowIcon="True" IsClosable="True"
                CloseRequest="HandleAlertClose">
        A new version is available. Please refresh the page.
    </atom:Alert>
    <!-- 页面内容 -->
</StackPanel>

表单验证错误

<StackPanel Spacing="16">
    <atom:Alert Type="Error" IsShowIcon="True"
                Message="Form Validation Failed"
                Description="Please check the following fields: Name, Email, Phone number." />
    <!-- 表单内容 -->
</StackPanel>

操作结果反馈

<atom:Alert Type="Success" IsShowIcon="True" IsClosable="True"
            Message="Submission Successful"
            Description="Your application has been submitted. We will review it within 3 business days."
            CloseRequest="HandleAlertClose">
    <atom:Alert.ExtraAction>
        <atom:Button ButtonType="Link" SizeType="Small">View Details</atom:Button>
    </atom:Alert.ExtraAction>
</atom:Alert>

多条提示堆叠

<StackPanel Spacing="8">
    <atom:Alert Type="Error" IsShowIcon="True" IsClosable="True"
                CloseRequest="HandleAlertClose">
        Database connection failed. Retrying in 30 seconds.
    </atom:Alert>
    <atom:Alert Type="Warning" IsShowIcon="True" IsClosable="True"
                CloseRequest="HandleAlertClose">
        Your session will expire in 5 minutes.
    </atom:Alert>
    <atom:Alert Type="Info" IsShowIcon="True">
        System maintenance scheduled for tonight 10:00 PM.
    </atom:Alert>
</StackPanel>