想给图形加个模糊效果？MaskFilter 让你轻松实现

你有没有在一些设计类 APP 里见过那种"毛玻璃"效果？或者在修图软件里给图片加个模糊遮罩？这些效果在 HarmonyOS 的 drawing 模块里，用 MaskFilter 就能实现。

MaskFilter 是什么？

简单说，MaskFilter 就是一个"蒙版滤镜"。它可以在绘制图形的时候，给图形的边缘或者整体加上一些特殊效果。目前 HarmonyOS 提供的 MaskFilter 主要支持模糊效果，也就是高斯模糊。

打个比方：你在画布上画了一个红色的圆，正常情况下边缘是清晰的。加上 MaskFilter 之后，这个圆的边缘就会变得模糊、柔和，就像用手指在纸上抹了一下颜料的感觉。

MaskFilter 四种模糊类型

下面是四种 BlurType 的效果示意和适用场景：

创建一个模糊滤镜：createBlurMaskFilter

MaskFilter 的创建很简单，因为它只有一个静态方法 createBlurMaskFilter：

import { RenderNode } from '@kit.ArkUI';
import { drawing } from '@kit.ArkGraphics2D';

class DrawingRenderNode extends RenderNode {
  draw(context : DrawContext) {
    const canvas = context.canvas;
    let maskFilter = drawing.MaskFilter.createBlurMaskFilter(drawing.BlurType.OUTER, 10);
  }
}

这里有两个参数需要解释一下：

第一个参数：blurType（模糊类型）

BlurType 是一个枚举，它决定了模糊效果作用在图形的哪个位置。你可以想象一下：

• OUTER：模糊效果只作用在图形的外部。就像你在窗户上贴了一张纸，然后从外面看过去，纸的边缘是模糊的，但纸本身是清晰的。
• INNER：模糊效果只作用在图形的内部。图形的边缘保持清晰，但内部变得模糊。
• NORMAL：内外都有模糊效果，整体都变得柔和。
• SOLID：图形内部保持实心，边缘有模糊效果。

在上面的例子里，我们用的是 drawing.BlurType.OUTER，意思是模糊效果只往外扩散。

第二个参数：sigma（标准偏差）

这个参数控制模糊的程度。你可以把它理解为"模糊半径"。值越大，模糊范围越广，效果越明显。

• sigma = 1：轻微模糊，几乎看不出来
• sigma = 10：中等模糊，边缘明显柔和
• sigma = 50：重度模糊，图形都快"化"掉了

在例子里我们传的是 10，这是一个比较适中的值。

怎么使用 MaskFilter？

创建好 MaskFilter 之后，你需要把它"挂"到画布上才能生效。具体来说，是通过画布的 setMaskFilter 方法来设置的。不过这里要注意，MaskFilter 通常是配合 Brush 或 Pen 一起使用的。

下面是一个更完整的例子，展示怎么用 MaskFilter 画一个带模糊效果的图形：

import { RenderNode } from '@kit.ArkUI';
import { drawing } from '@kit.ArkGraphics2D';

class DrawingRenderNode extends RenderNode {
  draw(context : DrawContext) {
    const canvas = context.canvas;
    // 创建一个模糊滤镜，模糊类型为 OUTER，sigma 为 10
    let maskFilter = drawing.MaskFilter.createBlurMaskFilter(drawing.BlurType.OUTER, 10);
    // 创建一个画笔
    let pen = new drawing.Pen();
    pen.setColor({alpha: 255, red: 255, green: 0, blue: 0});
    pen.setStrokeWidth(5);
    // 将 MaskFilter 应用到画笔上
    pen.setMaskFilter(maskFilter);
    canvas.attachPen(pen);
    // 画一个圆，边缘会带有模糊效果
    canvas.drawCircle(200, 200, 100);
  }
}

这段代码做了一件事：画一个红色的圆，但圆的边缘带有模糊效果。你注意看，我们是把 MaskFilter 设置到了 Pen 上，然后用这个 Pen 来绘制。这样 Pen 绘制出来的所有图形都会带上这个模糊效果。

不同 BlurType 的效果区别

让我用更具体的方式来解释四种模糊类型的区别。假设你画了一个蓝色的矩形：

NORMAL 模式：矩形的内外都模糊，整体看起来像一团蓝色的雾。

OUTER 模式：矩形内部保持清晰，但外部有一圈模糊的"晕影"。这是最常用的模式，适合做发光效果、阴影效果。

INNER 模式：矩形的边缘是清晰的，但内部变得模糊。适合做"磨砂玻璃"效果。

SOLID 模式：矩形内部保持实心不透明，边缘有模糊过渡。适合做柔和的按钮、卡片背景。

使用 MaskFilter 的完整流程

下面是使用 MaskFilter 实现模糊效果的典型流程：

Sigma 值怎么选？

Sigma 的选择取决于你想要的效果强度。这里给一些参考值：

• 1-3：非常轻微的模糊，适合做微妙的阴影
• 5-15：中等模糊，适合做毛玻璃效果、柔和的光晕
• 20-50：重度模糊，适合做背景虚化、景深效果
• 50 以上：极度模糊，图形几乎不可辨认

要注意的是，sigma 值越大，渲染的开销也越大。如果你在做动画效果（比如模糊程度随时间变化），太大的 sigma 值可能会导致卡顿。建议在性能和效果之间找一个平衡点。

实际应用场景

场景一：发光文字效果

想让文字看起来像在发光？先用 Font 和 TextBlob 创建文字路径，然后用带有 MaskFilter 的 Brush 来绘制：

let maskFilter = drawing.MaskFilter.createBlurMaskFilter(drawing.BlurType.NORMAL, 15);
let brush = new drawing.Brush();
brush.setColor({alpha: 255, red: 255, green: 200, blue: 0});
brush.setMaskFilter(maskFilter);
canvas.attachBrush(brush);
// 绘制文字...

场景二：卡片投影效果

给卡片加一个柔和的投影：

let shadowFilter = drawing.MaskFilter.createBlurMaskFilter(drawing.BlurType.NORMAL, 8);
let brush = new drawing.Brush();
brush.setColor({alpha: 100, red: 0, green: 0, blue: 0});
brush.setMaskFilter(shadowFilter);
canvas.attachBrush(brush);
canvas.drawRect({left: 50, top: 55, right: 250, height: 155});

先画一个半透明的黑色矩形作为阴影，然后在上面画真正的卡片。

场景三：背景虚化

做弹窗时，想让背景变模糊：

let blurFilter = drawing.MaskFilter.createBlurMaskFilter(drawing.BlurType.NORMAL, 30);
// 先把背景图绘制到画布上
// 然后应用 blurFilter 来模糊整个画布

注意事项

1. 线程安全：MaskFilter 和其他 drawing 对象一样，是单线程模型。如果你在多线程环境下使用，需要自己管理线程安全。

2. 性能考虑：模糊效果是比较消耗性能的，特别是 sigma 值很大的时候。如果你需要实时更新模糊效果（比如做动画），建议适当降低 sigma 值，或者降低绘制的频率。

3. 物理像素：MaskFilter 使用的是物理像素单位 px，和 Font 一样。在高分屏上，同样的 sigma 值看起来会比低分屏上更"细腻"。

4. API 版本：MaskFilter 从 API version 12 开始支持，确保你的项目最低版本符合要求。

小结

MaskFilter 是一个简单但实用的工具，专门用来给图形加模糊效果。它的核心就是 createBlurMaskFilter 这个静态方法，通过调整 BlurType 和 sigma 两个参数，你可以实现从轻微阴影到重度虚化的各种效果。

虽然它目前只支持模糊这一种效果，但在实际开发中，模糊效果的用途非常广泛——发光、阴影、毛玻璃、景深，几乎所有的视觉特效都离不开它。