本文详解如何在 QML 的 Text（富文本模式）中，为 HTML 链接自动启用手指光标（Qt.PointingHandCursor），同时完整保留 onLinkActivated 事件响应能力，避免手动拦截鼠标事件导致功能失效。

本文详解如何在 qml 的 `text`（富文本模式）中，为 html `` 链接自动启用手指光标（`qt.pointinghandcursor`），同时完整保留 `onlinkactivated` 事件响应能力，避免手动拦截鼠标事件导致功能失效。

在 QML 中，Text 元素支持 textFormat: Text.RichText 渲染 HTML 内容，包括可点击的 <a href="https://www.php.cn/link/263b1243ca2dbeb358777ceabc4a2e4c"></a> 链接。但默认情况下，鼠标悬停在链接上不会自动切换光标——这与 Web 浏览器体验不符，也降低了用户交互直觉性。直接嵌套 MouseArea 虽能控制 cursorShape，却会遮挡 Text 的原生链接事件（如 onLinkActivated），导致逻辑冗余且维护困难。

Qt 6.5+ 引入的 HoverHandler 提供了优雅、声明式的解决方案：它专为“感知悬停状态”而设计，不捕获鼠标事件、不干扰底层组件行为，仅监听并响应悬停状态变化，完美契合 Text 链接场景。

✅ 正确做法：使用 HoverHandler + hoveredLink 属性

QML 的 Text 元素内置一个只读属性 hoveredLink（自 Qt 6.5 起可用），当鼠标悬停在任意 <a></a> 链接上时自动变为 true；离开后恢复 false。配合 HoverHandler，即可精准触发光标切换：

Text {
    id: linkText
    textFormat: Text.RichText
    wrapMode: Text.WordWrap
    text: qsTr('<p>Here is my first paragraph.</p>' +
               '<p>My second paragraph contains the <a href="link1">first link</a>.</p>' +
               '<p>My third paragraph contains the <a href="link2">second link</a>.</p>')

    // 关键：声明式悬停处理，零侵入
    HoverHandler {
        enabled: linkText.hoveredLink  // 仅当悬停在链接上时生效
        cursorShape: Qt.PointingHandCursor
    }

    onLinkActivated: (link) => {
        console.log("Link activated:", link)
        // 推荐：使用 Qt.openUrlExternally() 打开外部 URL
        if (link.startsWith("http")) {
            Qt.openUrlExternally(link)
        } else {
            // 自定义协议处理（如 link1/link2）
            handleCustomLink(link)
        }
    }
}

⚠️ 注意：hoveredLink 是 Text 的原生属性，无需额外计算或 linkAt() 判断，性能高效且语义清晰。

? 进阶：动态样式化悬停链接（颜色/下划线）

Text 支持内联 CSS，结合 hoveredLink 可实现样式响应式更新：

Text {
    text: qsTr(
        '<style>' +
            'a:link { color: %1; text-decoration: %2; }' +
            'a:hover { color: %3; }' +
        '</style>' +
        'Visit <a href="https://qt.io">Qt Official Site</a> for more.'
    ).arg(
        hoveredLink ? "purple" : "#0066cc",   // 默认链接色
        hoveredLink ? "underline" : "none",   // 悬停时加下划线
        "darkblue"                            // 悬停时高亮色
    )

    HoverHandler {
        enabled: hoveredLink
        cursorShape: Qt.PointingHandCursor
    }
}

? 最佳实践要点总结

• 不要用 MouseArea 替代 HoverHandler：MouseArea 会抢占事件流，破坏 onLinkActivated，属于反模式；
• 确保 Qt 版本 ≥ 6.5：hoveredLink 和 HoverHandler 在早期版本中不可用；
• HoverHandler 必须作为 Text 的子元素声明，且 enabled 绑定到 parent.hoveredLink（或直接 id.hoveredLink）；
• 链接协议需明确：href="link1" 属于自定义协议，需在 onLinkActivated 中手动处理；href="https://https://www.php.cn/link/263b1243ca2dbeb358777ceabc4a2e4c" 可直接调用 Qt.openUrlExternally()；
• 性能无忧：hoveredLink 由 QML 引擎内部优化实现，无额外计算开销。

通过 HoverHandler 与 hoveredLink 的组合，你既能获得 Web 级别的悬停反馈体验，又能保持 QML 声明式开发的简洁性与事件完整性——这才是现代 Qt Quick 交互设计的正确打开方式。