抠丁客 抠丁客
项目
编辑 (2025/12/26)

图像处理

ABP提供图片压缩与尺寸调整服务，并通过主流的 ImageSharp 和 Magick.NET 库实现这些功能。您可在可复用模块、库及应用程序中使用这些服务，从而避免依赖特定的图像处理库。

该图片尺寸调整/压缩系统设计为可扩展架构。您可以实现自定义的图像尺寸调整/压缩贡献器，并在应用程序中使用。

安装方式

您可通过 ABP CLI 工具或手动安装方式将此包添加到项目中。推荐使用 ABP CLI 进行安装。

使用ABP CLI

在项目文件夹（.csproj文件所在目录）打开命令行终端，输入以下命令：

abp add-package Volo.Abp.Imaging.Abstractions

手动安装

若需手动安装：

  1. 添加Volo.Abp.Imaging.Abstractions NuGet包至项目：
dotnet add package Volo.Abp.Imaging.Abstractions
  1. 在模块的依赖列表中添加AbpImagingAbstractionsModule：
[DependsOn(
    //...其他依赖项
    typeof(AbpImagingAbstractionsModule) //添加新模块依赖
    )]
public class YourModule : AbpModule
{
}

提供程序

ABP默认提供两种图片尺寸调整/压缩实现：

需安装其中任一提供程序才能使功能生效。

若未安装任何提供程序包，压缩/尺寸调整操作将返回未经处理的原始图片。

IImageResizer服务

您可注入IImageResizer服务用于图片尺寸调整操作。该服务提供以下方法：

public interface IImageResizer
{
    /* 处理代表图片的Stream对象 */
    Task<ImageResizeResult<Stream>> ResizeAsync(
        Stream stream,
        ImageResizeArgs resizeArgs,
        string mimeType = null,
        CancellationToken cancellationToken = default
    );

    /* 处理包含图片文件的字节数组 */
    Task<ImageResizeResult<byte[]>> ResizeAsync(
        byte[] bytes,
        ImageResizeArgs resizeArgs,
        string mimeType = null,
        CancellationToken cancellationToken = default
    );
}

使用示例：

var resizeResult = await _imageResizer.ResizeAsync(
    imageStream, /* 代表图片的流对象 */
    new ImageResizeArgs
    {
        Width = 100,
        Height = 100,
        Mode = ImageResizeMode.Crop
    },
    mimeType: "image/jpeg"
);

注意： 若resizeResult.State返回'Done'，表示尺寸调整操作成功。若返回其他状态，所使用的流可能已损坏。可通过如下检查并分配正确流至主流：

if (resizeResult.Result is not null && imageStream != resizeResult.Result && resizeResult.Result.CanRead)
{
    await imageStream.DisposeAsync();
    imageStream = resizeResult.Result;
}

可使用MimeTypes.Image.Jpeg常量替代示例中的魔术字符串image/jpeg。

ImageResizeArgs参数

ImageResizeArgs类用于定义尺寸调整操作参数，包含以下属性：

  • Width: 调整后图片的宽度
  • Height: 调整后图片的高度
  • Mode: 尺寸调整模式（详见ImageResizeMode章节）

ImageResizeMode模式

ImageResizeMode枚举定义尺寸调整模式，包含以下值：

public enum ImageResizeMode : byte
{
    None = 0,
    Stretch = 1,
    BoxPad = 2,
    Min = 3,
    Max = 4,
    Crop = 5,
    Pad = 6,
    Default = 7
}

关于调整模式的详细信息请参阅ImageSharp文档

ImageResizeResult结果

ImageResizeResult泛型类返回图片尺寸调整操作结果，包含以下属性：

  • Result: 调整后的图片（流或字节数组）
  • State: 调整操作结果（类型：ImageProcessState）

ImageProcessState状态

ImageProcessState枚举返回图片尺寸调整操作结果，包含以下值：

public enum ImageProcessState : byte
{
    Done = 1,
    Canceled = 2,
    Unsupported = 3,
}

ImageResizeOptions选项

ImageResizeOptions是用于配置图片尺寸调整系统的选项对象，包含以下属性：

  • DefaultResizeMode: 默认尺寸调整模式（默认值：ImageResizeMode.None）

IImageCompressor服务

您可注入IImageCompressor服务用于图片压缩操作。该服务提供以下方法：

public interface IImageCompressor
{
    /* 处理代表图片的Stream对象 */
    Task<ImageCompressResult<Stream>> CompressAsync(
        Stream stream,
        string mimeType = null,
        CancellationToken cancellationToken = default
    );
    
    /* 处理包含图片文件的字节数组 */
    Task<ImageCompressResult<byte[]>> CompressAsync(
        byte[] bytes,
        string mimeType = null,
        CancellationToken cancellationToken = default
    );
}

使用示例：

var compressResult = await _imageCompressor.CompressAsync(
    imageStream, /* 代表图片的流对象 */
    mimeType: "image/jpeg"
);

注意： 若compressResult.State返回'Done'，表示压缩操作成功。若返回其他状态，所使用的流可能已损坏。可通过如下检查并分配正确流至主流：

if (compressResult.Result is not null && imageStream != compressResult.Result && compressResult.Result.CanRead)
{
    await imageStream.DisposeAsync();
    imageStream = compressResult.Result;
}

ImageCompressResult结果

ImageCompressResult泛型类返回图片压缩操作结果，包含以下属性：

  • Result: 压缩后的图片（流或字节数组）
  • State: 压缩操作结果（类型：ImageProcessState）

ImageProcessState状态

ImageProcessState枚举返回图片压缩操作结果，包含以下值：

public enum ImageProcessState : byte
{
    Done = 1,
    Canceled = 2,
    Unsupported = 3,
}

Magick.NET提供程序

Volo.Abp.Imaging.MagickNet NuGet 包使用 Magick.NET 库实现图像处理功能。

安装

您可通过 ABP CLI 工具或手动安装方式将此包添加到项目中。推荐使用 ABP CLI 进行安装。

使用ABP CLI

在项目文件夹（.csproj文件所在目录）打开命令行终端，输入以下命令：

abp add-package Volo.Abp.Imaging.MagickNet

手动安装

若需手动安装：

  1. 添加Volo.Abp.Imaging.MagickNet NuGet包至项目：
dotnet add package Volo.Abp.Imaging.MagickNet
  1. 在模块的依赖列表中添加AbpImagingMagickNetModule：
[DependsOn(typeof(AbpImagingMagickNetModule))]
public class MyModule : AbpModule
{
    //...
}

配置

MagickNetCompressOptions是用于配置Magick.NET图片压缩系统的选项对象，包含以下属性：

  • OptimalCompression: 是否启用最优压缩（默认：false）
  • IgnoreUnsupportedFormats: 是否忽略不支持的格式（默认：false）
  • Lossless: 是否启用无损压缩（默认：false）

ImageSharp提供程序

Volo.Abp.Imaging.ImageSharp NuGet包使用ImageSharp库实现图像处理功能。

安装

您可通过 ABP CLI 工具或手动安装方式将此包添加到项目中。推荐使用 ABP CLI 进行安装。

使用ABP CLI

在项目文件夹（.csproj文件所在目录）打开命令行终端，输入以下命令：

abp add-package Volo.Abp.Imaging.ImageSharp

手动安装

若需手动安装：

  1. 添加Volo.Abp.Imaging.ImageSharp NuGet包至项目：
dotnet add package Volo极.Abp.Imaging.ImageSharp
  1. 在模块的依赖列表中添加Abp极ImagingImageSharpModule：
[DependsOn(typeof(AbpImagingImageSharpModule))]
public class MyModule : AbpModule
{
    //...
}

配置

ImageSharpCompressOptions是用于配置ImageSharp图片压缩系统的选项对象，包含以下属性：

  • DefaultQuality: JPEG和WebP编码器的默认质量（默认：75）
  • JpegEncoder: JPEG编码器（默认：Quality设为DefaultQuality的JpegEncoder）
  • PngEncoder: PNG编码器（默认：IgnoreMetadata设为true且CompressionLevel设为PngCompressionLevel.BestCompression的PngEncoder）
  • WebPEncoder: WebP编码器（默认：Quality设为DefaultQuality的WebPEncoder）

使用示例：

Configure<ImageSharp极CompressOptions>(options =>
{
    options.JpegEncoder = new JpegEncoder
    {
        Quality = 60
    };
    options.PngEncoder = new PngEncoder
    {
        CompressionLevel = PngCompressionLevel.BestCompression
    };
    options.WebPEncoder = new WebPEncoder
    {
        Quality = 65
    };
});

ASP.NET Core集成

Volo.Abp.Imaging.AspNetCore NuGet包为控制器动作定义属性，可自动压缩和/或调整上传文件的尺寸。

安装

您可通过 ABP CLI 工具或手动安装方式将此包添加到项目中。推荐使用 ABP CLI 进行安装。

使用ABP CLI

在项目文件夹（.csproj文件所在目录）打开命令行终端，输入以下命令：

abp add-package Volo.Abp.Imaging.AspNetCore

手动安装

若需手动安装：

  1. 添加Volo.Abp.Imaging.AspNetCore NuGet包至项目：
dotnet add package Volo.Abp.Imaging.AspNetCore
  1. 在模块的依赖列表中添加AbpImagingAspNetCoreModule：
[DependsOn(typeof(AbpImagingAspNetCoreModule))]
public class MyModule : AbpModule
{
    //...
}

CompressImageAttribute属性

CompressImageAttribute用于在动作执行前压缩图片。支持IFormFile、IRemoteStreamContent、Stream和IEnumrable<byte>类型。包含以下属性：

  • Parameters: 用于配置图片压缩系统的参数名称。当动作包含非图片参数时特别有用。若不指定参数名，所有方法参数都将被视为图片。

使用示例：

[HttpPost]
[CompressImage] /* 压缩给定文件（自动确定文件MIME类型） */
public async Task<IActionResult> Upload(IFormFile file)
{
    //...
}

ResizeImageAttribute属性

ResizeImageAttribute用于在请求动作前调整图片尺寸。支持IFormFile、IRemoteStreamContent、Stream和IEnumrable<byte>类型。包含以下属性：

  • Parameters: 用于配置图片尺寸调整系统的参数名称。当动作包含非图片参数时特别有用。若不指定参数名，所有方法参数都将被视为图片
  • Width: 调整后图片的目标宽度
  • Height: 调整后图片的目标高度
  • Mode: 尺寸调整模式（详见ImageResizeMode章节）

使用示例：

[HttpPost]
[ResizeImage(Width = 100, Height = 100, Mode = ImageResizeMode.Crop)] 
public async Task<IActionResult> Upload(IFormFile file)
{
    //...
}
在本文档中