ProgressiveBlur class

对应 Figma：Effects -> Background blur -> Progressive（Start / End）。

用法与 BackdropFilter 一致：直接包裹子组件，真正被模糊的是组件背后的场景内容 （例如导航栏背后滚动的列表），child 本身不被模糊，绘制在模糊层之上。

模糊量沿 begin 到 end 的连线，由 sigmaStart 线性过渡到 sigmaEnd：

sigma 原样写入着色器，单位与背景快照纹理一致（物理像素）；取值范围与 Figma 一致为 0～maxSigma（100，含端点），超出会被钳制到区间内。卷积核半径为 3σ、最多 255 个 采样点，因此 sigma 超过约 42 后实际模糊量不再继续增大。

仅支持 Impeller：通过 ui.ImageFilter.shader 以两遍（水平 / 垂直）可分离高斯卷积 实现，由内部的 BackdropFilterLayer 合成。以下情况不做模糊、原样呈现 child （child 为空时退化为零尺寸占位，与无孩子的 RenderProxyBox 行为一致）：

  • 运行在 Skia 后端（ui.ImageFilter.isShaderFilterSupported 为 false）；
  • 着色器尚未加载完成的首帧（建议在 runApp() 前调用 precache 预编译）；
  • sigmaStart 与 sigmaEnd 均为 0。

child 可为空：为空时组件仍会对自身区域（尺寸由父级约束决定）内的背景应用模糊， 只是不绘制前景内容。

使用限制：

  • 组件的全局位置仅在 paint 阶段读取一次。若祖先通过纯合成层位移移动本组件 （AnimatedSlide、FractionalTranslation，或命中图层缓存的 Transform.translate）， 本节点不会重新 paint，移动过程中渐变带会与组件错位，需由调用方主动触发重绘。
  • 不支持祖先存在旋转/缩放等非平移变换：begin/end 按轴对齐矩形换算，变换后位置不成立。
  • 渐变定位所用的视口尺寸取自 MediaQuery.sizeOf；若祖先覆写了 MediaQuery.size， 归一化坐标会与真实视口不一致，渐变位置可能偏移。
  • 组件部分移出屏幕时，渐变会被重新映射到可见区域（边缘被裁断），与 Figma 中 “沿组件完整尺寸渐变”的语义略有差异。
Inheritance

Constructors

ProgressiveBlur({Key? key, AlignmentGeometry begin = .topCenter, AlignmentGeometry end = .bottomCenter, double sigmaStart = 0, required double sigmaEnd, Widget? child})
const

Properties

begin → AlignmentGeometry
渐变起点在本组件区域内的对齐位置，默认为 Alignment.topCenter。
final
child → Widget?
模糊层之上的子组件（通常是半透明渐变填充等），可为空。
final
end → AlignmentGeometry
渐变终点在本组件区域内的对齐位置，默认为 Alignment.bottomCenter。
final
hashCode → int
The hash code for this object.
no setterinherited
key → Key?
Controls how one widget replaces another widget in the tree.
finalinherited
runtimeType → Type
A representation of the runtime type of the object.
no setterinherited
sigmaEnd → double
渐变终点的高斯模糊 sigma，对应 Figma 的 End。
final
sigmaStart → double
渐变起点的高斯模糊 sigma，对应 Figma 的 Start。
final

Methods

createElement() → StatefulElement
Creates a StatefulElement to manage this widget's location in the tree.
inherited
createState() → State<ProgressiveBlur>
Creates the mutable state for this widget at a given location in the tree.
override
debugDescribeChildren() → List<DiagnosticsNode>
Returns a list of DiagnosticsNode objects describing this node's children.
inherited
debugFillProperties(DiagnosticPropertiesBuilder properties) → void
Add additional properties associated with the node.
inherited
noSuchMethod(Invocation invocation) → dynamic
Invoked when a nonexistent method or property is accessed.
inherited
toDiagnosticsNode({String? name, DiagnosticsTreeStyle? style}) → DiagnosticsNode
Returns a debug representation of the object that is used by debugging tools and by DiagnosticsNode.toStringDeep.
inherited
toString({DiagnosticLevel minLevel = DiagnosticLevel.info}) → String
A string representation of this object.
inherited
toStringDeep({String prefixLineOne = '', String? prefixOtherLines, DiagnosticLevel minLevel = DiagnosticLevel.debug, int wrapWidth = 65}) → String
Returns a string representation of this node and its descendants.
inherited
toStringShallow({String joiner = ', ', DiagnosticLevel minLevel = DiagnosticLevel.debug}) → String
Returns a one-line detailed description of the object.
inherited
toStringShort() → String
A short, textual description of this widget.
inherited

Operators

operator ==(Object other) → bool
The equality operator.
inherited

Static Methods

precache() → Future<void>
预编译着色器，避免使用首帧卡顿。建议在 main() 中 runApp 之前调用。

Constants

maxSigma → const double
sigma 的取值上限（含），与 Figma Background blur 的 0～100 限制一致。
shaderAssetKey → const String
着色器资源 Key（需在 pubspec.yaml 的 shaders 中注册）。