PyQt5中QWebChannel无法注册QObject至WebEngineView的问题

问题现象 #

开发PyQt5应用展示Plotly交互式图表时，需要捕获JavaScript事件并在Python中处理，但执行self.web_channel.registerObject("qtBridge", self.qt_bridge)后，HTML仍报错ReferenceError: qtBridge is not defined，无法完成Python与JS的通信。

已排查的常见原因 #

• HTML内容无问题，self.qt_bridge对象存在，其余功能正常
• 不存在时序问题（已尝试延迟调用）
• 无命名冲突或语法错误
• QWebChannel与QWebEngineView已正确初始化
• 排查了Python与JavaScript端其他可能问题

修复方案 #

代码存在三个核心问题导致注册失败，以下是针对性修复：

1. 补充QWebChannel前端依赖 #

JS端必须加载Qt官方的qwebchannel.js才能建立通信，原HTML缺少该关键文件，需在<head>中添加：

<script src="qrc:///qtwebchannel/qwebchannel.js"></script>

2. 显式初始化QWebChannel获取对象 #

JS端不能直接调用qtBridge，必须通过QWebChannel实例的回调获取Python注册的对象，替换原DOMContentLoaded逻辑：

new QWebChannel(qt.webChannelTransport, function(channel) {
    qtBridge = channel.objects.qtBridge;
    // 后续操作放在回调内确保对象已初始化
});

3. 修正槽函数参数匹配 #

JS端传递了JSON字符串，但原Python槽函数未定义参数，需调整QtBridge类：

class QtBridge(QObject):
    update_it = pyqtSignal(str)

    @pyqtSlot(str)
    def onPlotClick(self, message_str):
        try:
            message = json.loads(message_str)
            print(f"User clicked in plot! Coordinates: x={message['x']}, y={message['y']}")
            self.update_it.emit(message_str)
        except Exception as e:
            print("Error in onPlotClick:", str(e))

完整修复后的核心代码 #

修改后的set_fig_to_webview方法

def set_fig_to_webview(self):
    fig_json = self.fig.to_json()
    
    html_content = f"""
    <!DOCTYPE html>
    <html>
    <head>
        <title>My Plotly Plot</title>
        <script src="https://cdn.plot.ly/plotly-latest.min.js"></script>
        <script src="qrc:///qtwebchannel/qwebchannel.js"></script>
    </head>
    <body>
        <div id="plotly-container"></div>
        <script>
            var qtBridge;
            document.addEventListener("DOMContentLoaded", function() {{
                new QWebChannel(qt.webChannelTransport, function(channel) {{
                    qtBridge = channel.objects.qtBridge;
                    
                    var plotlyDiv = document.getElementById('plotly-container');
                    var plotlyData = {fig_json};
                    Plotly.newPlot(plotlyDiv, plotlyData);

                    // 绑定Plotly点击事件
                    plotlyDiv.on('plotly_click', function(data) {{
                        if (qtBridge) {{
                            var message = {{ 
                                x: data.points[0].x, 
                                y: data.points[0].y 
                            }};
                            qtBridge.onPlotClick(JSON.stringify(message));
                        }}
                    }});
                }});
            }});
        </script>
    </body>
    </html>
    """
    self.webview.setHtml(html_content)

额外优化 #

• 移除不必要的setTimeout，通过QWebChannel回调确保对象初始化完成后再操作
• 直接绑定Plotly原生plotly_click事件，贴合业务需求
• 修复update_plot方法参数与信号的匹配问题

内容的提问来源于stack exchange，提问作者Qosa