SkiaSharp 2.88.0 破坏性变更:SkiaSharp.Views.iOS 移除 ToUIImage 缩放/方向重载的迁移指南

原创2026-10-13 18:27:391,705 阅读
文章标签:图形学图像处理跨平台WebAssembly

SkiaSharp 2.88.0 破坏性变更:SkiaSharp.Views.iOS 移除 ToUIImage 缩放/方向重载的迁移指南

SkiaSharp 在 2.88.0 版本中对 iOS/tvOS 平台视图库 SkiaSharp.Views.iOS 做了一次 API 精简:iOSExtensions 中带 scale(缩放因子)与 orientation(方向)参数的 3 个 ToUIImage 重载被移除。本文以仓库中的 API diff 文档 SkiaSharp.Views.iOS.breaking.md 为骨架,结合 iOSExtensions.cs 源码与 SkiaSharp.Views.iOS.md 同版本变更记录,帮你理清变更影响、迁移路径与验证方法,升级后不再踩编译错误。

一、变更概览:版本号与影响范围

该破坏性变更文档首先明确了版本基线:

Assembly Version Changed: 2.88.0.0 vs 2.80.0.0

也就是说,SkiaSharp.Views.iOS.dll 的程序集版本从 2.80.0.0 提升到 2.88.0.0,属于大版本内的 API 调整。变更集中在命名空间 SkiaSharp.Views.iOS 下唯一的受影响类型:

Type Changed: SkiaSharp.Views.iOS.iOSExtensions

需要特别注意:同样的变更也同步发生在 tvOS 平台。仓库中的 SkiaSharp.Views.tvOS.breaking.md 内容与 iOS 版完全一致(tvOS 侧类名为 SkiaSharp.Views.tvOS.iOSExtensions)。原因是这两个平台的扩展类在源码中是同一份文件、通过条件编译切换命名空间,见 iOSExtensions.cs 顶部的 #if __TVOS__ / #elif __IOS__ 指令。因此,同时面向 iOS 与 tvOS 的工程在升级到 2.88.0 时,两端的调用点都需要检查。

二、被移除的 API 明细

文档明确列出 iOSExtensions 中被移除的 3 个方法,均为 ToUIImage 扩展方法的重载:

public static UIKit.UIImage ToUIImage (this SkiaSharp.SKBitmap skiaBitmap, nfloat scale, UIKit.UIImageOrientation orientation);
public static UIKit.UIImage ToUIImage (this SkiaSharp.SKPixmap skiaPixmap, nfloat scale, UIKit.UIImageOrientation orientation);
public static UIKit.UIImage ToUIImage (this SkiaSharp.SKPicture skiaPicture, SkiaSharp.SKSizeI dimensions, nfloat scale, UIKit.UIImageOrientation orientation);

这三个重载的共性特征是同时携带 nfloat scale 与 UIKit.UIImageOrientation orientation 两个 UIKit 展示层参数:

  • scale:目标 UIImage 的缩放因子,1.0f 表示图像原始尺寸(源码注释原文:"A factor of 1.0 is the original size of the image");
  • orientation:应用到图像上的旋转方向(如 Up、Down、Left、Right 等);
  • SKPicture 版本额外需要 SKSizeI dimensions,用于指定把图片(Picture)栅格化输出的目标尺寸。

从源码实现看,这三个被移除的重载的内部逻辑完全一致——先借助 ToCGImage() 把 SkiaSharp 对象转成 CoreGraphics 的 CGImage,再包一层 new UIImage(cgImage, scale, orientation)(对应旧实现的 iOSExtensions.cs 历史版本)。因此,移除的并不是"SkiaSharp → UIKit 转换"能力本身,而是"转换时直接携带 UIKit 缩放与方向"的便捷形态。

三、当前仍保留的 ToUIImage 重载(源码证据)

升级到 2.88.0 后,iOSExtensions 仍保留不带 scale/orientation 的简化重载,完整实现见当前源码 iOSExtensions.cs:

// SKPicture → UIImage(仍需指定栅格化尺寸)
public static UIImage ToUIImage(this SKPicture skiaPicture, SKSizeI dimensions)

// SKImage → UIImage
public static UIImage ToUIImage(this SKImage skiaImage)

// SKPixmap → UIImage
public static UIImage ToUIImage(this SKPixmap skiaPixmap)

// SKBitmap → UIImage
public static UIImage ToUIImage(this SKBitmap skiaBitmap)

保留形态的实现同样走 ToCGImage() 通道,例如:

public static UIImage ToUIImage(this SKBitmap skiaBitmap)
{
    var cgImage = skiaBitmap.ToCGImage();
    return new UIImage(cgImage);
}

也就是说,SKBitmap、SKPixmap、SKImage 的基础转换接口没有消失,只是不再在转换入口处直接接收 UIKit 的 scale 与 orientation。

这些保留重载在仓库内部已有真实调用者:Maui 图像源服务 SKImageSourceService.Apple.cs 中,正是通过 img.Image?.ToUIImage()、bmp.Bitmap?.ToUIImage()、pix.Pixmap?.ToUIImage()、pic.Picture?.ToUIImage(pic.Dimensions) 把各类 SkiaSharp 图像源转换为 UIKit 的 UIImage 后交给 Maui 渲染管线。这可以作为你迁移后代码风格的直接参照。

四、迁移方案:三步替换旧调用

针对三种典型旧用法,给出对应的迁移写法。

4.1 旧代码形态

// SKBitmap → UIImage
var uiImage = bitmap.ToUIImage(scale: 2.0f, orientation: UIImageOrientation.Up);

// SKPixmap → UIImage
var uiImage2 = pixmap.ToUIImage(scale: 2.0f, orientation: UIImageOrientation.Up);

// SKPicture → UIImage
var uiImage3 = picture.ToUIImage(new SKSizeI(320, 240), scale: 2.0f, orientation: UIImageOrientation.Up);

4.2 新代码形态

场景 A:不需要缩放与旋转

直接换用保留重载即可,这是绝大多数情况的最简迁移:

var uiImage = bitmap.ToUIImage();
var uiImage2 = pixmap.ToUIImage();
var uiImage3 = picture.ToUIImage(new SKSizeI(320, 240)); // dimensions 仍需显式给出

场景 B:确实需要 scale / orientation

先通过保留重载(或底层 ToCGImage() 扩展)拿到 UIImage/CGImage,再用 UIKit 原生方式重建带缩放与方向的图像:

// 方式一:基于 CGImage 重建(与旧实现行为一致)
var cgImage = bitmap.ToCGImage(); // iOSExtensions 内实际使用的底层转换
var uiImage = new UIImage(cgImage, scale: 2.0f, orientation: UIImageOrientation.Up);

// 方式二:基于转换结果重建
var image = bitmap.ToUIImage();
var uiImage = new UIImage(image.CGImage, scale: 2.0f, orientation: UIImageOrientation.Up);

对 SKPicture,栅格化尺寸参数仍必须提供,因为它决定图片以多大像素尺寸被绘制出来:

var cgImage = picture.ToCGImage(new SKSizeI(320, 240));
var uiImage = new UIImage(cgImage, scale: 2.0f, orientation: UIImageOrientation.Up);

提示:scale 对应 UIKit 的像素密度概念,在 Retina 屏上通常应传入 UIScreen.MainScreen.Scale 或视图的 ContentScaleFactor,1.0f 即逻辑点与像素 1:1;orientation 保持 UIImageOrientation.Up 即不做旋转。

五、同版本关联变更:SKPaintGLSurfaceEventArgs 的 Info/RawInfo

升级 2.88.0 时,除了上述破坏性移除,同版本的 SkiaSharp.Views.iOS.md 还记录了 SkiaSharp.Views.iOS 中另外两处非破坏性 API 调整,建议一并了解:

  • SKPaintGLSurfaceEventArgs:新增 SKImageInfo info 与 SKImageInfo rawInfo 两个构造函数重载,并新增只读属性 Info、RawInfo;旧的带 GRGlFramebufferInfo glInfo 构造函数被标记 [Obsolete],提示改用 SKPaintGLSurfaceEventArgs(SKSurface, GRBackendRenderTarget, GRSurfaceOrigin, SKColorType);
  • SKPaintSurfaceEventArgs:新增 3 参数构造函数(surface、info、rawInfo)与 RawInfo 属性。

这两个事件参数类的完整实现位于共享源码 SKPaintGLSurfaceEventArgs.cs 与 SKPaintSurfaceEventArgs.cs,并已在 iOS 视图内部使用:例如 SKCanvasView.cs 中构造 new SKPaintSurfaceEventArgs(surface, info.WithSize(userVisibleSize), info) 同时传入"用户可见尺寸"与"原始像素尺寸"两份 SKImageInfo;SKGLView.cs 仍走 (surface, renderTarget, surfaceOrigin, colorType) 旧形态构造 GL 事件参数。含义区分:Info 是画布对外暴露的逻辑尺寸,RawInfo 是底层渲染目标的实际像素尺寸,二者在开启像素缩放(IgnorePixelScaling = false)的 Retina 屏上往往不同。

六、升级到 2.88.0 的检查清单

  1. 更新包版本:将 SkiaSharp.Views.iOS(及配套的 SkiaSharp、SkiaSharp.NativeAssets.iOS 等)NuGet 包统一升级到 2.88.0,程序集版本即变为 2.88.0.0。
  2. 全局搜索调用点:在解决方案中搜索 ToUIImage,逐个检查是否传入了 scale 或 orientation 参数;命中者按第四节迁移。iOS 与 tvOS 工程都要检查。
  3. 处理编译错误:移除重载属于破坏性变更,升级后所有旧调用会直接产生 CS1501(无匹配重载)类编译错误,正好可以借编译器报错清单逐一清理,避免遗漏。
  4. 处理 Obsolete 警告:若直接使用 SKPaintGLSurfaceEventArgs 的旧构造函数,会收到 [Obsolete] 警告,建议改用带 SKImageInfo 的新重载,并可通过 Info/RawInfo 区分逻辑尺寸与原始像素尺寸。
  5. 回归验证:重点验证两类场景——纯数据转换(Bitmap/Pixmap/Image 转 UIImage 后显示)与图片(Picture)栅格化输出(确认 dimensions 传参后的输出尺寸符合预期)。

更多同版本其他平台(Android、Desktop、Mac、UWP、Tizen 等)的变更详情,可继续查阅仓库 documentation/docfx/releases/2.88.0/SkiaSharp.Views 目录下的系列 API diff 文档。

登录后查看全文
SkiaSharp