如何在 Jetpack Compose 中实现矢量图形遮罩

关于什么是图形遮罩的场景解释

在网络上下载得到的 SVG 图标，大部分场合都是颜色单一或相对简单的颜色组合，如下面这种：

单色 SVG 图标

而在实际项目中，我们需要的图标颜色可能与获取到的 SVG 原始颜色并不一致，例如需要变成这样的：

渲染成彩色的 SVG 图标

此时，就需要在后期修改 SVG 图标上的填充颜色了。

修改 SVG 颜色的方法有很多种，例如：

• 在导入 SVG 后，对应的 XML 中修改 path 里面的 fillColor

• 在通过 Jetpack Compose 的 Icon 显示图标时，指定 tint 属性的颜色

Icon(
  painterResource(imageId),
  contentDescription = "icon",
  modifier,
  tint = Color.Red
) 

在一般情况下，上面的方式足以覆盖指定某个图标使用某种颜色，或 SVG 图标上不同部分使用不同颜色的场景。

但是，如果需要将图标渲染成较为复杂的渐变色，甚至是需要使用另一张图片来镂空显示，上面的方法就不够用了。

针对这种复杂场景，遮罩（或者标题所说的图形遮罩）就是来描述一种 使用另一个图像来镂空渲染一个图形的方法。
※ 图像可以是一个 Bitmap 点阵图，或者是某种填充颜色，如单色或渐变色

使用渐变色来渲染一个矢量图标示例：

原始图标

渐变渲染后

在 Compose 中如何实现遮罩

在 Compose 中，要实现使用一个图像以某种特殊方式覆盖渲染另一个具备特殊形状的图形，需要调用 Canvas 进行手动指定。

例如，通过 Icon 或 Image 显示一个矢量图：

Image(
  painterResource(imageId),
  contentDescription = "icon",
  modifier
)

矢量图标素材自身是透明背景的黑色图形，为了突出效果显示，将 Image 装进了一个 Box 中，并指定一个绿色背景：

原始图标

通过 Modifier 指定图标的渲染方式：

Modifier
  .size(200.dp)
  .drawWithContent {
    // 0. 获取 canvas 对象
    drawIntoCanvas { canvas ->
      // 1. 调用 saveLayer 创建一个新图层（离屏缓冲）
      canvas.saveLayer(Rect(Offset.Zero, size), Paint())
      // 2. 先绘制图标本身的矢量图形
      drawContent()
      // 3. 在矩形中绘制一个渐变色
      drawRect(
        Brush.sweepGradient(
          listOf(
            Color.Red, Color.Blue, Color.Green, Color.Red
          )
        // 4. 指定混合模式为 SrcIn
        ), blendMode = BlendMode.SrcIn
      )
      // 5. 将图层合成到 canvas 的原始图像上
      canvas.restore()
    }
  }

步骤解释：

1. drawIntoCanvas { canvas ->
   通过 drawIntoCanvas 获取到在 Image 中用于绘制图标的 Canvas 对象，Canvas 直译是画布，但可理解为在画布上绘图的手或机械臂
2. canvas.saveLayer
   为了正确显示第 4 步中指定的 BlendMode 混合模式效果，需要将当前 Canvas 架空到一个新图层上，以隔离 Canvas 前置绘制的背景色，该操作称为离屏缓冲
3. drawContent()
   先将 Image 中的 SVG 图标绘制到 Canvas 上，由于离屏缓冲，Canvas 当前所在的图层上只有该图标，背景为透明
4. drawRect(Brush.sweepGradient(...
   在一个矩形上绘制渐变色，目标是将该渐变色渲染在第 2 步的 SVG 图形上
5. blendMode = BlendMode.SrcIn
   指定第 3 步中渐变色矩形的混合方式为 SrcIn，表示当前准备绘制的渐变色矩形图像（Src）不透明地覆盖在 Canvas 当前图层上的已有内容（Dst）上，并且仅显示重叠部分。由于 Canvas 当前图层上仅有第 2 步所绘制的矢量图标，因此该渐变色使用了图标的轮廓，而图标内容则替换为覆盖其上的渐变色
6. canvas.restore()
   将完成的绘制内容重新合成到 Canvas 原有内容（背景颜色）上

遮罩渲染效果

为了便于重用，可将上面的 Modifier 打包成一个函数：

fun Modifier.maskedBy(maskPattern: MaskPattern,
                      blendMode: BlendMode = BlendMode.SrcIn): Modifier =
  this.drawWithContent {
    drawIntoCanvas { canvas ->
      canvas.saveLayer(Rect(Offset.Zero, size), Paint())
      drawContent()
      when (maskPattern) {
        is ColorPattern -> {
          drawRect(maskPattern.color, blendMode = blendMode)
        }
        is GradientPattern -> {
          drawRect(maskPattern.gradient, blendMode = blendMode)
        }
      }
      canvas.restore()
    }
  }

// 将用于遮罩渲染的颜色或渐变色对象封装为 MaskPattern
sealed class MaskPattern {
  data class ColorPattern(val color: Color) : MaskPattern()
  data class GradientPattern(val gradient: Brush) : MaskPattern()
}

封装到一个自定义 Composable Icon 组件：

@Composable
fun IconView(@DrawableRes imageId: Int, iconPattern: MaskPattern?) {
  fun createModifier(): Modifier {
    val instance = Modifier.size(30.dp)
    return if (iconPattern != null) instance.maskedBy(iconPattern) else instance
  }

  val modifier = remember { createModifier() }

  Icon(
    painterResource(imageId),
    contentDescription = "icon",
    modifier
  )
}

关于不使用 离屏缓冲 的失败案例

不使用离屏缓冲的 SrcIn

BlendMode 使用 Plus 叠加，可以看到原本属于 Box 的背景色，在 Image 的 Canvas 上也一同参与混合叠加计算，此时叠加的 Src 被视为一个全像素覆盖的矩形而非背景透明的矢量图形：

不使用离屏缓冲的 Plus

关于 离屏缓冲 及 BlendMode（旧称 PorterDuff.Mode）的各种模式，可在下面的文章的 1.3 setXfermode(Xfermode xfermode) 小节中找到相关资料介绍：
HenCoder Android 开发进阶: 自定义 View 1-2 Paint 详解

使用不同的渐变色渲染效果例子：

渲染效果图示例

顺便一提 iOS

在上面使用 BlendMode.SrcIn 模式实现的遮罩，在 SwiftUI 中已提供了现成的 Modifier 函数：mask

简单的使用方式示例：

color.mask(Image(image))
gradient.mask(Image(image))

更详细的使用方式可在下面的文章中找到：
剖析：如何用 SwiftUI 5天组装一个微信 —— 通讯录发现我篇 -