Canvas、Shader 与视觉效果：先选择渲染边界，再追求像素

SwiftUI 视觉实现常从错误的问题开始：“Canvas 和 Shader 哪个更快？”二者处理的并不是同一层。Canvas 用 GraphicsContext 在一块区域里执行即时二维绘制；Shader 接收像素、位置或已栅格化图层并改变输出；普通 View 则保留布局、交互和无障碍语义。正确问题是：这部分内容需要多少独立语义节点，效果要在哪个采样阶段发生，失败时留下什么？

本文面向已经会写 Shape 和 animation、准备实现粒子、图表背景、扭曲文字或颜色处理的开发者。三段 Swift 代码已映射到 examples/swiftui/Sources/WebSunSwiftUIExamples/CanvasShaderExamples.swift，通过 macOS Swift Package 与通用 iOS Simulator 编译；两段 Metal 转换契约明确是非可执行文档片段。本站没有可用的 Metal 编译证据与目标设备 GPU 记录，因此 shader 视觉与性能结论仍是 source-reviewed。

版本边界

Canvas 与 GraphicsContext 从 iOS 15、macOS 12 起可用；SwiftUI 的 ShaderLibrary、colorEffect、distortionEffect 和 layerEffect 从 iOS 17、macOS 14 对齐版本起成为稳定 API。Creating visual effects with SwiftUI给出完整组合入口，Shader 文档说明各类 effect 的用途和 stitchable 函数约定，WWDC24：Create custom visual effects展示了滚动视觉、文字渲染与 Metal 效果的组合。

本文稳定基线是 Xcode 26.6。Xcode 27 仍是 Beta，任何 Metal 4 或新 SDK 行为都不作为实现前提；即使同一 MSL 文件在 Beta 可编译，也不能据此替代稳定工具链与部署目标验证。

三层工具，三种职责

普通 View 适合按钮、文本、图片和可独立聚焦的图形，因为它们天然参与布局和 accessibility tree。Canvas 适合大量细粒度绘制命令共享一个语义区域，例如波形、粒子和静态装饰背景。Apple 的 GraphicsContext 文档列出 fill、stroke、image、text、filter、transform 与 blend mode 等即时绘制能力。

Shader 继续向像素层走：colorEffect 改变每个输入像素颜色；distortionEffect 把输出位置映射到新的采样位置；layerEffect 可以读取 SwiftUI 为视图生成的栅格图层。它们不应该承担业务布局或可点击元素命中。

语义 View、Canvas 与三类 Shader effect 的选择管线

图 1：先按语义与采样需求选择工具，再为像素效果保留可读回退；本站原创 1400×800 程序化 SVG。

向量图元进入着色棱镜后形成受控的波纹、粒子、遮罩与像素干涉

图 2（1600 × 900）：Canvas 与 Shader 的编辑式视觉隐喻，不代表实际渲染阶段。OpenAI Image Gen × WEB/SUN，2026-07-16；项目内原创生成资产。

一个实用顺序是：能由标准 View/Shape 完成就停在语义层；大量同类绘制才合并进 Canvas；必须逐像素处理才增加 Shader。层级越低，你越需要自己补足降级、能耗和可访问性。

Canvas：减少视图节点，不是免费画布

下面的波场把多个 Path 画进一个 Canvas。时间由 TimelineView 提供，而不是手写永久 RAF。Apple 的 Canvas 文档将它定义为即时绘制 View；Timeline schedule 则允许系统按上下文更新。

struct WaveField: View {
    @Environment(\.accessibilityReduceMotion) private var reduceMotion

    var body: some View {
        Group {
            if reduceMotion {
                waveCanvas(time: 0)
            } else {
                TimelineView(.animation) { timeline in
                    waveCanvas(time: timeline.date.timeIntervalSinceReferenceDate)
                }
            }
        }
        .accessibilityLabel("交错的橙蓝波形背景")
    }

    private func waveCanvas(time: TimeInterval) -> some View {
        Canvas(opaque: false, colorMode: .linear) { context, size in
            for index in 0..<18 {
                var path = Path()
                let baseline = size.height * CGFloat(index + 1) / 19

                for x in stride(from: 0.0, through: size.width, by: 6) {
                    let wave = sin(Double(x / 32) + time * 1.2 + Double(index))
                    let y = baseline + CGFloat(wave) * 9
                    if x == 0 {
                        path.move(to: CGPoint(x: x, y: y))
                    } else {
                        path.addLine(to: CGPoint(x: x, y: y))
                    }
                }

                context.stroke(
                    path,
                    with: .color(index.isMultiple(of: 2) ? .orange : .blue),
                    lineWidth: 1.5
                )
            }
        }
    }
}

这段代码用于说明数据流，不代表已测性能。生产实现应把不会随帧变化的几何预计算在绘制闭包之外，或缓存可重用 Path；避免每帧做网络读取、日期格式化、模型过滤。步长、路径数量、画布像素面积和设备 scale 都会改变成本，不能只用“视图节点更少”推导更快。

Canvas 内绘制的十八条路径不是十八个 VoiceOver 元素。装饰图可以把整块 Canvas 标成单一说明或隐藏；交互图表则应在 Canvas 上方提供透明但真实的 Button、列表或摘要，让相同数据能通过触摸、键盘和辅助技术访问。不要试图用几十个 accessibilityLabel 模拟不存在的语义子树。

Color effect：颜色进，颜色出

SwiftUI shader 函数需要 [[ stitchable ]]，参数顺序必须匹配 effect 类型。当前机器没有可用的可选 Metal 编译组件，因此这里不伪装成已编译示例；下面只用非可执行转换契约表达 posterize 的输入、透明度与预乘规则：

colorEffect contract
input  = premultiplied RGBA + band count
guard  = alpha == 0 → return transparent input
step   = unpremultiply RGB → quantize by bands → premultiply RGB
output = premultiplied RGBA in the destination color space

ArticleCover()
    .colorEffect(ShaderLibrary.posterize(.float(6)))

Apple 的 Shader 文档要求返回目标颜色空间中的 premultiplied color。透明度处理错误会产生暗边；广色域和 HDR 内容还需要在目标设备验证，不能只看 Simulator 截图。

Distortion 与 Layer effect：采样边界必须诚实

几何扭曲函数返回新的采样位置。SwiftUI 需要 maxSampleOffset 扩展可读取边界；它不是视觉强度参数，而是你承诺 shader 最远会采样到哪里。报得过小会裁切，报得过大可能扩大中间图层和工作量。

distortionEffect contract
input  = position + time + amplitude
step   = horizontal displacement from a bounded sine phase
output = a sample position no farther than amplitude points on x
bound  = maxSampleOffset.width >= abs(amplitude)

Text("WEB/SUN")
    .font(.system(size: 72, weight: .black))
    .distortionEffect(
        ShaderLibrary.ripple(.float(time), .float(amplitude)),
        maxSampleOffset: CGSize(width: amplitude, height: 0),
        isEnabled: !reduceMotion
    )

layerEffect 能从栅格化 layer 周围取样，适合 blur-like、邻域比较和更复杂滤镜，同时也更容易因大图层、高采样半径和嵌套效果增加成本。先限定 effect 的视图边界，再提供保守但真实的最大偏移。不要把整个长列表包成一个 layer 只为给某行做效果。

把 Shader 当作有契约的模块

视觉原型常把函数名、参数顺序和 Swift 调用散落在页面里，稍微修改 Metal 签名就只能到运行时发现效果消失。更稳妥的边界是把每个 shader 写成小而明确的变换：输入坐标属于哪个空间，颜色是否预乘，uniform 的单位和范围是什么，最大采样偏移如何推导，透明像素怎样处理。Swift 侧再用一个命名 wrapper 组装 ShaderLibrary 参数，页面只传业务强度。

时间也是接口的一部分。动画从进程启动时间、视图出现时间还是用户手势开始计时，会决定切页后是否跳帧；进入后台后继续累加，恢复时可能突然跨越很大相位。对循环装饰可以在视图重新出现时建立局部起点，对可交互模拟则应保存明确状态。不要把 Date.now 隐藏在 shader wrapper 内，否则预览、截图和自动测试无法固定输出。

颜色验证不能只在 paper 背景上看一张截图。至少覆盖透明边缘、不同 color scheme、Display P3 输入、较低 alpha、离屏合成与文字抗锯齿。像素效果改变了对比度时，重要文本应继续满足可读性要求，必要时只处理背景或增加不受 shader 影响的前景层。

VisualEffect：位置驱动但不改布局

visualEffect 提供内容占位和 GeometryProxy，返回的效果不影响祖先或后代布局。VisualEffect 的官方说明强调它适合基于位置施加 offset、scale、opacity、blur 或 shader，而不是写回 frame 到 @State 再触发布局。这也是滚动视觉更稳定的基础：几何进入渲染路径，不形成状态反馈环。

视觉变换仍会影响用户感知和命中预期。大幅 offset 后，语义焦点顺序依旧来自 View tree；如果视觉顺序与语义顺序脱离，VoiceOver 与键盘用户会困惑。效果应该强化层级，不应重新定义信息架构。

资源生命周期与失败边界

Shader 函数能被调用不代表所有目标设备都值得启用完整效果。应用应在效果出现前确定可用路径，不要先把重要内容隐藏，再等待管线准备完成。视图离屏、Scene 进入 inactive 或后台时停止 Timeline；返回前台后按当前状态恢复，而不是补算离开的每一帧。大量动画 Canvas 若嵌在列表中，还要以可见性约束更新范围。

编译错误、函数签名不匹配或图层分配失败时，回退必须是原始 View、静态渐变或预先生成的图像，不能是空白矩形。回退与完整版本共享相同 frame、文字和操作语义，避免效果失败同时引发 CLS 式布局跳变。调试日志可以记录启用路径与 shader 名称，但不要每帧输出 uniform。

素材与代码也要可追踪。Metal 文件、Swift wrapper、效果预览和正文示例应来自同一源码；如果文章为了排版复制片段，就需要自动检查它仍与可编译示例一致。只在 Beta SDK 可用的签名必须明确标记并与稳定实现隔离，不能让部署目标通过字符串判断悄悄选择未验证行为。

降级与性能验证

至少准备三条路径：完整 shader；稳定 API 但关闭动态 uniforms 的静态效果；不支持或 Reduce Motion 时的原始语义 View。Shader 编译失败、低电量、应用进入后台和视图离屏都不应让内容消失。重要文字不能只存在于像素输出，按钮不能只由 Canvas 命中区域模拟。

性能实验一次只改变一个维度：画布尺寸、绘制元素数、采样半径、Timeline 频率或 effect 层数。使用 Release 构建和目标真机记录 CPU/GPU 与 hitch，再用相同场景对照。drawingGroup 或异步 Canvas 不是通用开关；它们会改变合成和延迟特征，只有记录证明瓶颈匹配时才保留。

测试矩阵至少包括静止首帧、持续运行、快速滚动进出、后台恢复、Reduce Motion、较低电量路径和目标最低系统。为 shader 准备固定 uniforms 的参考截图可以发现采样与颜色回归，但截图相同不证明实时性能；性能 trace 相同也不证明无障碍语义仍然存在。两类证据需要分开保存。

如果效果接受用户输入，还要验证极值。振幅为零应退化为原图，密度和速度达到上限时不能让 maxSampleOffset 失真，无限值与负值应在 Swift wrapper 入口被约束。手势离开视图或被系统取消后，参数要回到确定状态，避免一个未结束的 gesture 让 Timeline 永久保持高频更新。

常见失败包括：每帧重建不变 Path；无限 Timeline 在离屏继续；把大列表整体 rasterize；低报 maxSampleOffset；忽略 premultiplied alpha；Canvas 承载交互却没有等价语义；Reduce Motion 只把振幅减半但仍持续循环。

最终原则是让渲染边界与产品语义对齐。View 负责可操作结构，Canvas 合并即时绘制，Shader 处理明确的像素变换。效果可以很强，但原始内容、可访问路径和验证方法必须比效果本身更稳定。