AtomUI/docs/Desktop.Controls/ImagePreviewer/ImagePreviewerUsage.md

ImagePreviewer 使用文档

本文档介绍 AtomUI ImagePreviewer 控件的使用方式。

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

---

前置准备

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

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

在 C# 代码中引入：

using AtomUI.Desktop.Controls;   // ImagePreviewer, ImageGroupPreviewer

---

1. 基本使用 — 单图预览

最基本的用法是展示一张图片，点击后弹出预览对话框（来自 Gallery 示例 ImagePreviewerShowCase.axaml）：

<atom:ImagePreviewer Name="BasicPreviewer" Width="200" />

// Code-behind (ReactiveUI)
this.WhenActivated(disposables =>
{
    viewModel.DefaultImages = [
        "avares://AtomUIGallery/Assets/ImagePreviewerShowCase/1.png"
    ];
    this.OneWayBind(viewModel, vm => vm.DefaultImages, v => v.BasicPreviewer.ItemsSource)
        .DisposeWith(disposables);
});

---

2. 容错图片

当 ItemsSource 为空或加载失败时，使用 FallbackImageSrc 显示占位图：

<atom:ImagePreviewer Name="FaultTolerantPreviewer" Width="200" />

viewModel.FallbackImage = "avares://AtomUIGallery/Assets/ImagePreviewerShowCase/Fallback.png";
this.OneWayBind(viewModel, vm => vm.FallbackImage, v => v.FaultTolerantPreviewer.FallbackImageSrc)
    .DisposeWith(disposables);

---

3. 从一张封面预览多张图片

ItemsSource 包含多张图片路径，但 ImagePreviewer 仅展示首张作为封面，点击后可左右切换浏览所有图片：

<atom:ImagePreviewer Name="FromOnImagePreviewer" Width="200" />

viewModel.ThreeImages = [
    "avares://AtomUIGallery/Assets/ImagePreviewerShowCase/4.webp",
    "avares://AtomUIGallery/Assets/ImagePreviewerShowCase/5.webp",
    "avares://AtomUIGallery/Assets/ImagePreviewerShowCase/6.webp"
];
this.OneWayBind(viewModel, vm => vm.ThreeImages, v => v.FromOnImagePreviewer.ItemsSource)
    .DisposeWith(disposables);

---

4. 自定义封面图

通过 CoverImageSrc 指定与预览图不同的封面（如模糊缩略图）：

<atom:ImagePreviewer Name="CustomImagePreviewer" Width="200" />

viewModel.DefaultImages = ["avares://AtomUIGallery/Assets/ImagePreviewerShowCase/1.png"];
viewModel.BlurImage = "avares://AtomUIGallery/Assets/ImagePreviewerShowCase/Blur.png";
this.OneWayBind(viewModel, vm => vm.DefaultImages, v => v.CustomImagePreviewer.ItemsSource)
    .DisposeWith(disposables);
this.OneWayBind(viewModel, vm => vm.BlurImage, v => v.CustomImagePreviewer.CoverImageSrc)
    .DisposeWith(disposables);

---

5. 多图组预览

ImageGroupPreviewer 展示多张缩略图，点击任意一张直接跳转到该图片的预览：

<atom:ImageGroupPreviewer Name="MultiImagesPreviewer"
                          CoverWidth="200" CoverHeight="200" />

viewModel.TwoImages = [
    "avares://AtomUIGallery/Assets/ImagePreviewerShowCase/2.svg",
    "avares://AtomUIGallery/Assets/ImagePreviewerShowCase/3.svg"
];
this.OneWayBind(viewModel, vm => vm.TwoImages, v => v.MultiImagesPreviewer.ItemsSource)
    .DisposeWith(disposables);

💡 注意 SVG 格式的图片（.svg 后缀）会自动走 SVG 渲染路径。

---

6. 隐藏封面遮罩

<atom:ImagePreviewer IsShowCoverMask="False" Width="200" />

隐藏遮罩后，封面仍可点击打开预览，但不显示悬浮提示。

---

7. 自定义遮罩指示器

<atom:ImagePreviewer Width="200">
    <atom:ImagePreviewer.CoverIndicatorContentTemplate>
        <DataTemplate>
            <TextBlock Text="查看大图"
                       HorizontalAlignment="Center"
                       VerticalAlignment="Center"
                       Foreground="White"
                       FontSize="14" />
        </DataTemplate>
    </atom:ImagePreviewer.CoverIndicatorContentTemplate>
</atom:ImagePreviewer>

---

8. 对话框定位

<!-- 对话框居中显示 -->
<atom:ImagePreviewer DialogHorizontalStartupLocation="Center"
                     DialogVerticalStartupLocation="Center" />

<!-- 对话框置顶 + 模态 -->
<atom:ImagePreviewer IsDialogModal="True"
                     IsDialogTopmost="True" />

---

9. 缩放配置

<!-- 更细粒度的缩放（每次 25%），最大 10 倍 -->
<atom:ImagePreviewer ImageScaleStep="0.25"
                     ImageMinScale="0.5"
                     ImageMaxScale="10.0" />

---

10. 禁用拖拽

<atom:ImagePreviewer IsImageMovable="False" />

---

11. 编程方式控制对话框

通过 IsOpen 属性

// 打开
previewer.IsOpen = true;

// 关闭
previewer.IsOpen = false;

通过方法调用

// 打开
previewer.OpenDialog();

// 监听关闭事件
previewer.DialogClosing += (sender, e) =>
{
    // 阻止关闭（如有未保存操作）
    if (hasUnsavedChanges)
    {
        e.Cancel = true;
    }
};

previewer.DialogClosed += (sender, e) =>
{
    // 对话框已关闭
};

---

12. C# 动态创建

using AtomUI.Desktop.Controls;

var previewer = new ImagePreviewer
{
    Width = 200,
    ItemsSource = new List<string>
    {
        "avares://MyApp/Assets/photo1.png",
        "avares://MyApp/Assets/photo2.webp",
        "avares://MyApp/Assets/icon.svg"
    },
    ImageScaleStep = 0.3,
    IsDialogModal = false
};

parentPanel.Children.Add(previewer);

---

预览对话框交互速查

操作	方式
打开预览	点击封面图 / 设置 IsOpen = true / 调用 OpenDialog()
关闭预览	点击窗口关闭按钮 / 设置 IsOpen = false
缩放	工具栏按钮 / 鼠标滚轮
旋转	标题栏或浮动工具栏的旋转按钮
翻转	标题栏或浮动工具栏的翻转按钮
切换图片	导航按钮 / 键盘 ← → / 工具栏前/后按钮
适应窗口/原始尺寸	工具栏切换按钮
拖拽移动	缩放后鼠标左键拖拽