feature: 优化组件文档

src/zh_CN/reference/controls/alert/api.md

@@ -0,0 +1,44 @@
+# Alert API 参考
+
+## 属性
+
+| 属性 | 说明 | 类型 | 默认值 |
+|---|---|---|---|
+| `Type` | 警告提示类型 | `AlertType` | `Success` |
+| `Message` | 提示消息内容（也可作为 Content 直接书写） | `string` | `""` |
+| `Description` | 辅助描述信息 | `string?` | `null` |
+| `IsShowIcon` | 是否显示类型对应的语义图标 | `bool` | `false` |
+| `IsClosable` | 是否显示关闭按钮 | `bool` | `false` |
+| `CloseIcon` | 自定义关闭按钮图标 | `PathIcon?` | `null`（默认使用 CloseOutlined） |
+| `IsMessageMarqueEnabled` | 是否启用消息跑马灯滚动 | `bool` | `false` |
+| `ExtraAction` | 自定义操作区域，位于 Alert 右侧 | `Control?` | `null` |
+
+## 事件
+
+| 事件 | 说明 | 参数类型 |
+|---|---|---|
+| `CloseRequest` | 点击关闭按钮时触发 | `EventHandler` |
+
+## 枚举类型
+
+### AlertType
+
+| 值 | 说明 | 图标 |
+|---|---|---|
+| `Success` | 成功提示，绿色系 | CheckCircleFilled |
+| `Info` | 信息提示，蓝色系 | InfoCircleFilled |
+| `Warning` | 警告提示，黄色系 | ExclamationCircleFilled |
+| `Error` | 错误提示，红色系 | CloseCircleFilled |
+
+## 伪类（Pseudo Classes）
+
+| 伪类 | 说明 |
+|---|---|
+| `:has-description` | Description 属性非空时 |
+| `:has-extra-action` | ExtraAction 属性非空时 |
+
+## 模板部件（Template Parts）
+
+| 名称 | 类型 | 说明 |
+|---|---|---|
+| `PART_CloseBtn` | `IconButton` | 关闭按钮 |

src/zh_CN/reference/controls/alert/getting-started.md

@@ -1,16 +1,154 @@
-# Alert 快速入门
+# Alert 快速入门
 
-### 基础配置条件
+## 前置条件
 
-* Nuget安装Avalonia
-* Nuget安装AtomUI
+- NuGet 安装 `Avalonia`
+- NuGet 安装 `AtomUI`
 
-### 初始化一个最基础的 `Alert` 文本框
+## 基础用法
+
+Alert 提供四种类型，通过 `Type` 属性设置，分别表达不同的语义。Message 内容可直接作为 Alert 的 Content 书写。
+
+![AtomUI Alert 四种类型](./images/different-types.png)
 
 ```xaml
-<StackPanel>
+<StackPanel Orientation="Vertical" Spacing="10">
     <atom:Alert Type="Success">Success Text</atom:Alert>
+    <atom:Alert Type="Info">Info Text</atom:Alert>
+    <atom:Alert Type="Warning">Warning Text</atom:Alert>
+    <atom:Alert Type="Error">Error Text</atom:Alert>
+</StackPanel>
+```
+
+| Type | 说明 | 对应图标 |
+|---|---|---|
+| `Success` | 操作成功提示 | CheckCircleFilled |
+| `Info` | 一般信息提示 | InfoCircleFilled |
+| `Warning` | 警告提示 | ExclamationCircleFilled |
+| `Error` | 错误/危险提示 | CloseCircleFilled |
+
+## 显示图标
+
+设置 `IsShowIcon="True"` 在提示信息前显示类型对应的语义图标，帮助用户快速识别信息级别。
+
+![AtomUI Alert 图标](./images/description-with-icon.png)
+
+```xaml
+<StackPanel Orientation="Vertical" Spacing="10">
+    <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>
+```
+
+## 描述信息
+
+通过 `Description` 属性添加辅助描述文本。当同时设置 Message 和 Description 时，Alert 以双行模式展示：标题加粗、描述在下方。
+
+![AtomUI Alert 描述](./images/description.png)
+
+```xaml
+<StackPanel Orientation="Vertical" Spacing="10">
+    <atom:Alert Type="Success"
+                Message="Success Text"
+                Description="Detailed description and advice about successful copywriting." />
+    <atom:Alert Type="Info"
+                Message="Info Text"
+                IsShowIcon="True"
+                Description="Additional description and information about copywriting." />
+    <atom:Alert Type="Warning"
+                Message="Warning Text"
+                IsShowIcon="True"
+                Description="This is a warning notice about copywriting." />
+    <atom:Alert Type="Error"
+                Message="Error Text"
+                IsShowIcon="True"
+                Description="This is an error message about copywriting." />
 </StackPanel>
 ```
 
-![AtomUI Alert快速入门](./images/basic.png)
+## 可关闭
+
+设置 `IsClosable="True"` 显示关闭按钮。可通过 `CloseIcon` 自定义关闭图标。
+
+![AtomUI Alert 关闭](./images/closer.png)
+
+```xaml
+<StackPanel Orientation="Vertical" Spacing="10">
+    <atom:Alert Type="Warning" IsClosable="True">
+        Warning Text Warning Text Warning Text
+    </atom:Alert>
+    <atom:Alert Type="Error" IsClosable="True"
+                Description="Error Description Error Description">
+        Error Text
+    </atom:Alert>
+    <!-- 自定义关闭图标 -->
+    <atom:Alert Type="Error" IsClosable="True"
+                CloseIcon="{atom:IconProvider CloseSquareFilled}"
+                Description="Error Description Error Description">
+        Error Text
+    </atom:Alert>
+</StackPanel>
+```
+
+关闭事件通过 `CloseRequest` 事件获取：
+
+```csharp
+alert.CloseRequest += (sender, args) =>
+{
+    // 处理关闭逻辑
+};
+```
+
+## 自定义操作
+
+通过 `ExtraAction` 属性在 Alert 右侧插入自定义操作区域，支持放置按钮或任意控件。
+
+![AtomUI Alert 自定义操作](./images/custom-action.png)
+
+```xaml
+<atom:Alert Type="Success" IsShowIcon="True" IsClosable="True">
+    <atom:Alert.ExtraAction>
+        <atom:Button ButtonType="Text" SizeType="Small">UNDO</atom:Button>
+    </atom:Alert.ExtraAction>
+    Success Tips
+</atom:Alert>
+
+<atom:Alert Type="Error" IsShowIcon="True"
+            Description="Error Description Error Description">
+    <atom:Alert.ExtraAction>
+        <atom:Button ButtonType="Default" SizeType="Small" IsDanger="True">
+            Detail
+        </atom:Button>
+    </atom:Alert.ExtraAction>
+    Error Text
+</atom:Alert>
+```
+
+也可以放置多个操作按钮：
+
+```xaml
+<atom:Alert Type="Info" IsClosable="True"
+            Description="Info Description Info Description">
+    <atom:Alert.ExtraAction>
+        <StackPanel Orientation="Vertical" Spacing="5">
+            <atom:Button ButtonType="Primary" SizeType="Small">Accept</atom:Button>
+            <atom:Button SizeType="Small" IsDanger="True" IsGhost="True">Decline</atom:Button>
+        </StackPanel>
+    </atom:Alert.ExtraAction>
+    Info Text
+</atom:Alert>
+```
+
+## 文案轮播
+
+当消息文本过长时，设置 `IsMessageMarqueEnabled="True"` 开启跑马灯滚动效果。
+
+![AtomUI Alert 滚动](./images/loop-banner.webp)
+
+```xaml
+<atom:Alert Type="Warning" IsShowIcon="True" IsMessageMarqueEnabled="True">
+    This is a long message that will scroll automatically when the text overflows the alert container
+</atom:Alert>
+```

src/zh_CN/reference/controls/alert/overview.md

@@ -1,14 +1,21 @@
-# Alert 概述
+# Alert 警告提示
 
-### 简介
+## 简介
 
-在必要业务场景中，提供多种警告提示，向用户展示需要关注的信息。
+警告提示用于向用户展示需要关注的信息。与 Notification 不同，Alert 是静态嵌入页面内容中的非浮层组件，不会自动消失，适合展示持续性的提示信息。
 
-![AtomUI Alert快速入门](./images/custom-action.png)
+![AtomUI Alert 组件](./images/custom-action.png)
 
-### 主要功能
-* 四种样式
-* 关闭按钮
-* 文案轮播
-* 携带图标
-* 自定义操作按钮
+## 何时使用
+
+- 当页面中某个区域需要向用户显示提示性信息时
+- 非浮层的静态展示形式，始终展现在页面中，不会自动消失
+
+## 主要特性
+
+- **四种类型** — Success、Info、Warning、Error，通过颜色和图标传达不同语义
+- **图标显示** — 可选显示类型对应的语义图标，增强信息辨识度
+- **描述信息** — 支持标题 + 描述的双行展示模式
+- **可关闭** — 支持关闭按钮，用户可手动移除提示
+- **自定义操作** — 通过 ExtraAction 插入自定义按钮或操作区域
+- **文案轮播** — 消息过长时可启用跑马灯滚动效果