QML元素 - DirectionalBlur

QML 的 DirectionalBlur 用于创建方向性模糊效果，模拟元素沿特定方向的运动模糊或动态拖影，适用于滑动菜单、滚动列表、动态卡片等场景。以下是使用技巧和关键点：

---

1. 基本用法

import QtQuick 2.15
import QtQuick.Effects 1.15  // 确保模块已正确引入

Image {
    id: sourceImage
    source: "image.png"
    anchors.fill: parent

    // 应用方向性模糊
    layer.enabled: true
    layer.effect: DirectionalBlur {
        anchors.fill: sourceImage
        angle: 45       // 模糊方向角度（0~360度）
        length: 32      // 模糊强度（像素距离）
        samples: 24     // 采样数（影响平滑度）
        transparentBorder: true  // 处理边缘透明区域
    }
}

关键属性：

• angle：模糊方向角度（0 为向右，90 为向上，180 为向左，270 为向下）。
• length：模糊强度（像素距离），值越大拖影越长（0 到 64）。
• samples：采样数，建议设为 length * 0.75 以上以确保平滑。
• transparentBorder：设为 true 避免边缘黑边。

---

2. 方向与强度控制

(1) 水平/垂直模糊

• 水平模糊（左右拖影）：

  DirectionalBlur {
      angle: 0    // 向右模糊
      length: 40
      samples: 32
  }
  

• 垂直模糊（上下拖影）：

  DirectionalBlur {
      angle: 90   // 向上模糊
      length: 30
      samples: 24
  }
  

(2) 对角线模糊

DirectionalBlur {
    angle: 135    // 向左上角模糊
    length: 50
    samples: 40
}

(3) 动态调整模糊参数

Slider {
    id: angleSlider
    from: 0
    to: 360
    value: 0
}

Slider {
    id: lengthSlider
    from: 0
    to: 64
    value: 20
}

DirectionalBlur {
    angle: angleSlider.value
    length: lengthSlider.value
    samples: Math.max(16, lengthSlider.value * 0.8)
}

---

3. 动态效果实现

(1) 滑动列表的惯性模糊

ListView {
    id: listView
    // ... 列表内容

    DirectionalBlur {
        source: listView.contentItem
        angle: 90  // 垂直方向模糊
        length: Math.min(64, Math.abs(listView.verticalVelocity))  // 根据滚动速度动态模糊
        samples: 32
    }
}

(2) 按钮悬停动态拖影

Rectangle {
    id: button
    width: 120
    height: 40
    color: "lightblue"

    layer.effect: DirectionalBlur {
        id: blurEffect
        length: button.hovered ? 16 : 0  // 悬停时显示拖影
        angle: 0  // 水平向右
        samples: 12
        Behavior on length { NumberAnimation { duration: 200 } }
    }

    MouseArea {
        id: mouseArea
        anchors.fill: parent
        hoverEnabled: true
    }
}

---

4. 性能优化

• 合理设置 samples：建议 samples ≥ length * 0.6（如 length: 40, samples: 24）。
• 启用缓存：对静态模糊设置 cached: true。
• 降采样处理：通过缩小源元素分辨率提升性能：

  layer.textureSize: Qt.size(width/2, height/2)  // 纹理尺寸降为 50%
  

---

5. 常见问题

(1) 模糊效果不明显

• 增加 length 值（如从 20 改为 40）。
• 确保 angle 方向与元素运动方向一致。

(2) 边缘出现黑边

• 启用 transparentBorder: true。
• 扩展源元素的边界（如设置 sourceSize 为 width*1.1）。

(3) 性能卡顿

• 降低 samples 和 length 值。
• 避免在低端设备上同时使用多个方向性模糊效果。

---

6. 进阶技巧

(1) 结合遮罩裁剪模糊区域

Rectangle {
    width: 300
    height: 300
    layer.enabled: true
    layer.effect: OpacityMask {
        maskSource: Rectangle {  // 圆形遮罩
            width: 300
            height: 300
            radius: 150
        }
        DirectionalBlur {
            angle: 45
            length: 50
            samples: 32
        }
    }
}

(2) 文本动态模糊

Text {
    text: "Directional Blur"
    font.pixelSize: 32
    layer.enabled: true
    layer.effect: DirectionalBlur {
        angle: 0  // 水平模糊
        length: mouseArea.containsMouse ? 20 : 0
        samples: 16
        Behavior on length { NumberAnimation { duration: 300 } }
    }

    MouseArea {
        id: mouseArea
        anchors.fill: parent
        hoverEnabled: true
    }
}

(3) 多方向模糊叠加

layer.effect: MultiEffect {
    directionalBlurEnabled: true
    directionalBlurAngle: 45
    directionalBlurLength: 30
    // 注意：Qt6 的 MultiEffect 提供更高效的组合效果
}

---

7. 与其他模糊效果对比

特性	DirectionalBlur	FastBlur	GaussianBlur
模糊类型	方向性运动模糊	全向快速模糊	全向高质量模糊
性能消耗	中高（依赖 length 和方向）	低	高
适用场景	滑动元素、动态拖影	实时背景虚化	静态高精度模糊

---

总结

• 核心作用：模拟元素沿特定方向的运动模糊或视觉拖影。
• 关键参数：angle（方向）、length（强度）、samples（平滑度）。
• 适用场景：滑动菜单、惯性滚动、动态交互反馈。
• 优化要点：控制 length 和 samples 平衡效果与性能，动态场景优先启用缓存。