使用現代 API 強化影像處理

簡介

在過去，Aspose Slides 依賴於 System.Drawing，且在公共 API 中提供了以下來自該命名空間的類別：

自 24.4 版起，此公共 API 已被宣告為已棄用。

由於 .NET6 以上版本在非 Windows 平台中已移除 System.Drawing 支援（重大變更），Slides 採用了兩套套件的方式：

Aspose.Slides.NET - 支援 Windows 上的 .NET6+，Windows/Linux/MacOS 上的 .NETStandard，Windows 上的 .NETFramework 2+。
- 依賴於 System.Drawing.Common。
Aspose.Slides.NET6.CrossPlatform - Windows/Linux/MacOS 版本，無任何依賴。

[Aspose.Slides.NET6.CrossPlatform] 的不便之處在於它在同一命名空間中實作了自己的 System.Drawing 版本（以支援與公共 API 的向後相容性）。因此，當同時使用 Aspose.Slides.NET6.CrossPlatform 與 .NET Framework 的 System.Drawing 或 System.Drawing.Common 套件時，除非使用別名，否則會發生名稱衝突。

為了在主要的 Aspose.Slides.NET 套件中移除對 System.Drawing 的依賴，我們加入了所謂的「現代 API」——即應取代已棄用 API 的新 API，其簽章中不再依賴 System.Drawing 中的 [Image] 與 [Bitmap]。[PrinterSettings] 與 [Graphics] 已被宣告為已棄用，且其支援已從公共 Slides API 中移除。

在目前的版本中，請將依賴於 System.Drawing 的公共 API 視為舊版/已棄用。新程式碼以及遷移既有影像處理工作流程時，請使用現代 API。

現代 API

已將以下類別與列舉加入公共 API：

Aspose.Slides.IImage - 代表點陣或向量影像。
Aspose.Slides.ImageFormat - 代表影像的檔案格式。
Aspose.Slides.Images - 用於實例化和操作 IImage 介面的相關方法。

請注意，IImage 為可釋放資源的物件（它實作了 IDisposable 介面，使用時應以 using 包住或以其他適當方式釋放）。

使用 GetImage 來渲染單一投影片或形狀。使用 GetImages 來渲染多張投影片。使用 Images 方法載入影像，使用 AddImage 搭配 [IImage] 將影像加入簡報，並使用 ReplaceImage 搭配 [IImage] 來更新簡報中已存在的影像。

以下是一個使用新 API 的典型情境：

using (Presentation pres = new Presentation())
{
    IPPImage ppImage;
    // 從磁碟上的檔案實例化一個可釋放的 IImage 實例。  
    using (IImage image = Images.FromFile("image.png"))
    {
        // 透過將 IImage 實例加入簡報的影像集合來建立 PowerPoint 影像。
        ppImage = pres.Images.AddImage(image);
    }

    // 在投影片 #1 上新增圖片形狀
    pres.Slides[0].Shapes.AddPictureFrame(ShapeType.Rectangle, 10, 10, 100, 100, ppImage);

    // 取得代表投影片 #1 的 IImage 實例。
    using (var slideImage = pres.Slides[0].GetImage(new Size(1920, 1080)))
    {
        // 將影像儲存至磁碟。
        slideImage.Save("slide1.jpeg", ImageFormat.Jpeg);
    }
}

以現代 API 取代舊代碼

為了簡化過渡，新 [IImage] 介面的設計重複了 [Image] 與 [Bitmap] 類別的各個簽章。一般而言，只需將使用 System.Drawing 的舊方法呼叫換成對應的新方法即可。

取得投影片縮圖

舊版/已棄用 API：

using (Presentation pres = new Presentation("pres.pptx"))
{
    pres.Slides[0].GetThumbnail().Save("slide1.png");
}

現代 API：

using (Presentation pres = new Presentation("pres.pptx"))
{
    pres.Slides[0].GetImage().Save("slide1.png");
}

取得形狀縮圖

舊版/已棄用 API：

using (Presentation pres = new Presentation("pres.pptx"))
{
    pres.Slides[0].Shapes[0].GetThumbnail().Save("shape.png");
}

現代 API：

using (Presentation pres = new Presentation("pres.pptx"))
{
    pres.Slides[0].Shapes[0].GetImage().Save("shape.png");
}

取得簡報縮圖

舊版/已棄用 API：

using (Presentation pres = new Presentation("pres.pptx"))
{
    var bitmaps = pres.GetThumbnails(new RenderingOptions(), new Size(1980, 1028));
    try
    {
        for (var index = 0; index < bitmaps.Length; index++)
        {
            Bitmap thumbnail = bitmaps[index];
            thumbnail.Save($"slide{index}.png", ImageFormat.Png);
        }
    }
    finally
    {
        foreach (Bitmap bitmap in bitmaps)
        {
            bitmap.Dispose();
        }
    }
}

現代 API：

using (Presentation pres = new Presentation("pres.pptx"))
{
    var images = pres.GetImages(new RenderingOptions(), new Size(1980, 1028));
    try
    {
        for (var index = 0; index < images.Length; index++)
        {
            IImage thumbnail = images[index];
            thumbnail.Save($"slide{index}.png", ImageFormat.Png);
        }
    }
    finally
    {
        foreach (IImage image in images)
        {
            image.Dispose();
        }
    }
}

將圖片加入簡報

舊版/已棄用 API：

using (Presentation pres = new Presentation())
{
    IPPImage ppImage;
    using (Image image = Image.FromFile("image.png"))
    {
        ppImage = pres.Images.AddImage(image);
    }

    pres.Slides[0].Shapes.AddPictureFrame(ShapeType.Rectangle, 10, 10, 100, 100, ppImage);
}

現代 API：

using (Presentation pres = new Presentation())
{
    IPPImage ppImage;
    using (IImage image = Aspose.Slides.Images.FromFile("image.png"))
    {
        ppImage = pres.Images.AddImage(image);
    }

    pres.Slides[0].Shapes.AddPictureFrame(ShapeType.Rectangle, 10, 10, 100, 100, ppImage);
}

已棄用的方法/屬性及其在現代 API 中的取代方案

簡報

方法簽章	取代方法簽章
public Bitmap[] GetThumbnails(IRenderingOptions options)	GetImages(IRenderingOptions options)
public Bitmap[] GetThumbnails(IRenderingOptions options, int[] slides)	GetImages(IRenderingOptions options, int[] slides)
public Bitmap[] GetThumbnails(IRenderingOptions options, float scaleX, float scaleY)	GetImages(IRenderingOptions options, float scaleX, float scaleY)
public Bitmap[] GetThumbnails(IRenderingOptions options, int[] slides, float scaleX, float scaleY)	GetImages(IRenderingOptions options, int[] slides, float scaleX, float scaleY)
public Bitmap[] GetThumbnails(IRenderingOptions options, Size imageSize)	GetImages(IRenderingOptions options, Size imageSize)
public Bitmap[] GetThumbnails(IRenderingOptions options, int[] slides, Size imageSize)	GetImages(IRenderingOptions options, int[] slides, Size imageSize)
public void Save(string fname, SaveFormat format, HttpResponse response, bool showInline)	No Modern API replacement
public void Save(string fname, SaveFormat format, ISaveOptions options, HttpResponse response, bool showInline)	No Modern API replacement
public void Print()	No Modern API replacement
public void Print(PrinterSettings printerSettings)	No Modern API replacement
public void Print(string printerName)	No Modern API replacement
public void Print(PrinterSettings printerSettings, string presName)	No Modern API replacement

形狀

方法簽章	取代方法簽章
public Bitmap GetThumbnail()	GetImage
public Bitmap GetThumbnail(ShapeThumbnailBounds bounds, float scaleX, float scaleY)	GetImage(ShapeThumbnailBounds bounds, float scaleX, float scaleY)

投影片

方法簽章	取代方法簽章
public Bitmap GetThumbnail(float scaleX, float scaleY)	GetImage(float scaleX, float scaleY)
public Bitmap GetThumbnail()	GetImage
public Bitmap GetThumbnail(IRenderingOptions options)	GetImage(IRenderingOptions options)
public Bitmap GetThumbnail(Size imageSize)	GetImage(Size imageSize)
public Bitmap GetThumbnail(ITiffOptions options)	GetImage(ITiffOptions options)
public Bitmap GetThumbnail(IRenderingOptions options, float scaleX, float scaleY)	GetImage(IRenderingOptions options, float scaleX, float scaleY)
public Bitmap GetThumbnail(IRenderingOptions options, Size imageSize)	GetImage(IRenderingOptions options, Size imageSize)
public void RenderToGraphics(IRenderingOptions options, Graphics graphics)	No Modern API replacement
public void RenderToGraphics(IRenderingOptions options, Graphics graphics, float scaleX, float scaleY)	No Modern API replacement
public void RenderToGraphics(IRenderingOptions options, Graphics graphics, Size renderingSize)	No Modern API replacement

輸出

方法簽章	取代方法簽章
public IOutputFile Add(string path, Image image)	Add(string path, IImage image)

ImageCollection

方法簽章	取代方法簽章
IPPImage AddImage(Image image)	AddImage(IImage image)

ImageWrapperFactory

方法簽章	取代方法簽章
IImageWrapper CreateImageWrapper(Image image)	CreateImageWrapper(IImage image)

PPImage

方法/屬性簽章	取代方法簽章
void ReplaceImage(Image newImage)	ReplaceImage(IImage newImage)
Image SystemImage { get; }	IImage Image { get; }

PatternFormat

方法簽章	取代方法簽章
Bitmap GetTileImage(Color background, Color foreground)	GetTile(Color background, Color foreground)
Bitmap GetTileImage(Color styleColor)	GetTile(Color styleColor)

IPatternFormatEffectiveData

方法簽章	取代方法簽章
Bitmap GetTileImage(Color background, Color foreground)	GetTileIImage(SlidesImage image)

Graphics 與 PrinterSettings 的 API 支援

Graphics 類別在 .NET6 以上的跨平台版本中不受支援。在 Aspose Slides 中，請改用現代 API 的影像渲染方法取代渲染至 [Graphics] 的 API： ISlide

此外，與透過 PrinterSettings 相關的列印 API 目前沒有直接的現代 API 取代方案：

IPresentation：

常見問題

為何棄用 [Graphics]？

在公共 API 中棄用 [Graphics] 旨在統一渲染與影像的處理方式，消除對平台專屬依賴，並改以跨平台的 [IImage] 方式實作。請改用 GetImage 或 GetImages 取代渲染至 [Graphics]。

[IImage] 相較於 [Image]/[Bitmap] 有什麼實務上的好處？

[IImage] 統一了點陣與向量影像的操作，透過 [ImageFormat] 簡化多種格式的儲存，減少對 System.Drawing 的依賴，讓程式碼在不同環境間更具可移植性。

使用現代 API 會影響產生縮圖的效能嗎？

從 GetThumbnail 轉為 GetImage 不會降低效能；新方法在功能上與舊方法等價，皆支援相同的選項與尺寸。具體的效能提升或下降取決於實際情境，但在功能上兩者是等效的。

.NET 6 支援已支援目標平台的更新