SkiaSharp 2.88.0 破坏性变更:SkiaSharp.Views.iOS 移除 ToUIImage 缩放/方向重载的迁移指南
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 的检查清单
- 更新包版本:将
SkiaSharp.Views.iOS(及配套的SkiaSharp、SkiaSharp.NativeAssets.iOS等)NuGet 包统一升级到 2.88.0,程序集版本即变为2.88.0.0。 - 全局搜索调用点:在解决方案中搜索
ToUIImage,逐个检查是否传入了scale或orientation参数;命中者按第四节迁移。iOS 与 tvOS 工程都要检查。 - 处理编译错误:移除重载属于破坏性变更,升级后所有旧调用会直接产生
CS1501(无匹配重载)类编译错误,正好可以借编译器报错清单逐一清理,避免遗漏。 - 处理 Obsolete 警告:若直接使用
SKPaintGLSurfaceEventArgs的旧构造函数,会收到[Obsolete]警告,建议改用带SKImageInfo的新重载,并可通过Info/RawInfo区分逻辑尺寸与原始像素尺寸。 - 回归验证:重点验证两类场景——纯数据转换(Bitmap/Pixmap/Image 转 UIImage 后显示)与图片(Picture)栅格化输出(确认
dimensions传参后的输出尺寸符合预期)。
更多同版本其他平台(Android、Desktop、Mac、UWP、Tizen 等)的变更详情,可继续查阅仓库 documentation/docfx/releases/2.88.0/SkiaSharp.Views 目录下的系列 API diff 文档。