AtomUI/docs/Desktop.Controls/Empty/EmptyUsage.md

Empty 使用文档

本文档介绍 AtomUI Empty 控件的各种使用方式，示例代码摘自 Gallery 演示程序。

📖 Gallery 源码位置：controlgallery/AtomUIGallery/ShowCases/Views/DataDisplay/EmptyShowCase.axaml

---

前置准备

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

xmlns:atom="https://atomui.net"

在 C# 代码中引入：

using AtomUI.Desktop.Controls;   // Empty 控件
using AtomUI.Controls;            // SizeType、PresetImage 等共享类型

---

1. 基本用法

最基本的空状态展示，使用默认预设图片：

<atom:Empty PresetImage="Default" />

默认情况下，Empty 控件会：

• 显示彩色的默认预设图片
• 在图片下方显示本地化的描述文字（英文 "No Data"，中文 "暂无数据"）
• 水平和垂直居中显示
• 使用 Middle 尺寸

---

2. 简洁模式

Ant Design 中的 PRESENTED_IMAGE_SIMPLE，适用于在列表/表格内显示小尺寸空状态：

<atom:Empty PresetImage="Simple" />

Simple 模式使用灰色线条图，视觉更轻量，适合作为容器内的内嵌空状态。

---

3. 尺寸切换

通过 SizeType 属性控制图片大小和描述文字间距：

<StackPanel Orientation="Horizontal" Spacing="10">
    <atom:Empty PresetImage="Simple" SizeType="Small" />
    <atom:Empty PresetImage="Simple" SizeType="Middle" />
    <atom:Empty PresetImage="Simple" SizeType="Large" />
</StackPanel>

三种尺寸的具体效果：

尺寸	图片高度	描述文字间距	适用场景
Small	约 35px	较小	表格单元格、紧凑列表
Middle	约 74px	较小	卡片、面板
Large	约 100px	较大	页面级空状态

---

4. 自定义描述文字

<!-- 自定义描述文字 -->
<atom:Empty PresetImage="Default" Description="Customize Description" />

<!-- 中文描述 -->
<atom:Empty PresetImage="Simple" Description="暂无搜索结果" />

---

5. 隐藏描述文字

通过 IsShowDescription="False" 隐藏描述文字，仅显示图片：

<atom:Empty PresetImage="Default" IsShowDescription="False" />

---

6. 自定义图片

使用 SVG 文件路径

通过 ImagePath 使用打包在应用资源中的自定义 SVG 图片：

<atom:Empty ImagePath="avares://AtomUIGallery/Assets/EmptyShowCase/empty.svg"
            SizeType="Large"
            Description="Customize Description" />

📖 Gallery 中的自定义图片示例：controlgallery/AtomUIGallery/ShowCases/Views/DataDisplay/EmptyShowCase.axaml

使用 SVG 内容字符串

通过 ImageSource 直接传入 SVG 源码字符串，适合动态生成的图片：

// Code-behind
var svgContent = """
    <svg width="64" height="41" xmlns="http://www.w3.org/2000/svg">
        <circle cx="32" cy="20" r="18" fill="#e6e6e6" stroke="#d9d9d9" />
        <text x="32" y="25" text-anchor="middle" fill="#999">?</text>
    </svg>
    """;
myEmpty.ImageSource = svgContent;

⚠️ 互斥规则：PresetImage、ImagePath、ImageSource 三者只能设置其中一个。同时设置多个会抛出异常。

---

7. 配合额外操作按钮

Ant Design 中 Empty 支持 children 插槽放置额外内容（如创建按钮）。AtomUI 中可通过外部组合实现：

<StackPanel Orientation="Vertical" Spacing="10">
    <atom:Empty ImagePath="avares://AtomUIGallery/Assets/EmptyShowCase/empty.svg"
                SizeType="Large"
                Description="Customize Description" />
    <atom:Button HorizontalAlignment="Center" ButtonType="Primary">Create Now</atom:Button>
</StackPanel>

---

8. 在数据容器中使用

在 Card 中使用

<atom:Card Header="Data List">
    <!-- 无数据时显示 -->
    <atom:Empty PresetImage="Simple" Description="No items" />
</atom:Card>

在列表中条件显示

<!-- AXAML：数据绑定示例（伪代码） -->
<Panel>
    <!-- 数据列表 -->
    <ListBox Items="{Binding Items}"
             IsVisible="{Binding HasItems}" />
    
    <!-- 空状态 -->
    <atom:Empty PresetImage="Simple"
                Description="暂无数据"
                IsVisible="{Binding !HasItems}" />
</Panel>

---

9. 预设图片类型对比

两种预设图片可通过 PresetImage 属性切换：

<!-- 默认预设图：彩色，适合独立展示 -->
<atom:Empty PresetImage="Default" Description="Default style" />

<!-- 简洁预设图：灰色线条，适合内嵌展示 -->
<atom:Empty PresetImage="Simple" Description="Simple style" />

选择指南：

场景	推荐预设	推荐尺寸
页面级空状态（整个页面无内容）	Default	Large
面板/卡片内空状态	Default 或 Simple	Middle
表格/列表内嵌空状态	Simple	Small 或 Middle
下拉选择器空选项	Simple	Small