QWebChannel Class
将 QObject 暴露给远程 HTML 客户端。更多...
| Header: | #include <QWebChannel> |
| qmake: | QT += webchannel |
| Inherits: | QObject |
属性
- blockUpdates : bool
- propertyUpdateInterval : int
公共函数
| QWebChannel(QObject *parent = nullptr) | |
| virtual | ~QWebChannel() |
| QBindable<bool> | bindableBlockUpdates() |
| QBindable<int> | bindablePropertyUpdateInterval() |
| bool | blockUpdates() const |
| void | deregisterObject(QObject *object) |
| int | propertyUpdateInterval() const |
| void | registerObject(const QString &id, QObject *object) |
| void | registerObjects(const QHash<QString, QObject *> &objects) |
| QHash<QString, QObject *> | registeredObjects() const |
| void | setBlockUpdates(bool block) |
| void | setPropertyUpdateInterval(int ms) |
公共槽位
| void | connectTo(QWebChannelAbstractTransport *transport) |
| void | disconnectFrom(QWebChannelAbstractTransport *transport) |
信号
| void | blockUpdatesChanged(bool block) |
详细说明
QWebChannel 填补了 C++ 应用程序与 HTML/JavaScript 应用程序之间的空白。通过将一个从 `QObject ` 派生的对象发布到 QWebChannel，并在 HTML 端使用 `qwebchannel.js`，用户可以透明地访问 `QObject` 的属性、公共槽和方法。 无需手动传递消息或对数据进行序列化，C++ 侧的属性更新和信号发布会自动传输给可能在远程运行的 HTML 客户端。在客户端，对于任何已发布的 C++ `QObject`，都会创建一个 JavaScript 对象。该对象完全反映了 C++ 对象的 API，因此使用起来非常直观。
QWebChannel 透明地支持QFuture 。当客户端调用一个返回QFuture 的方法时，QWebChannel 仅会在QFuture 完成后，才发送包含QFuture 结果的响应。
通过定义使用QMetaType::registerConverter() 进行QJsonValue 与QJsonValue 之间转换的转换器，可以实现自定义的 JSON 类型转换。请注意，如果QJsonValue 不符合预期格式，则从 转换为具体类型的自定义转换器必须失败。否则，QWebChannel 将无法回退到其默认的转换机制。JavaScript 端也支持自定义转换器。
C++ QWebChannel API 使得与任何 HTML 客户端进行通信成为可能，这些客户端既可在本地机器上运行，也可在远程机器上运行。唯一的限制是 HTML 客户端必须支持qwebchannel.js 所使用的 JavaScript 功能。因此，基本上可以与任何现代 HTML 浏览器或独立的 JavaScript 运行时（如 node.js）进行交互。
此外，还提供了一个声明式的WebChannel API 。
另请参阅 Qt WebChannel 独立示例、JavaScript API 以及QMetaType::registerConverter()。
属性文档
[bindable] blockUpdates : bool
注意：此 属性支持QProperty 绑定。
当设置为true 时，更新将被阻止，且远程客户端不会收到属性更改的通知。
更改会被记录下来，并在将此属性设置为false 从而再次解除更新阻塞后，发送给客户端。默认情况下，更新不会被阻塞。
访问函数：
| bool | blockUpdates() const |
| void | setBlockUpdates(bool block) |
通知器信号：
| void | blockUpdatesChanged(bool block) |
[bindable] propertyUpdateInterval : int
注意：此 属性支持QProperty 绑定。
该属性用于存储属性更新间隔。
可以通过将其设置为正值来将该间隔更改为以毫秒为单位的其他间隔。 属性更新会进行批量处理，并在该时间间隔到期后发送出去。如果设置为零，则在单次事件循环运行期间发生的更新将进行批量处理，并在下次运行时发送出去。如果为负数，更新将立即发送。默认值为 50 毫秒。
访问函数：
| int | propertyUpdateInterval() const |
| void | setPropertyUpdateInterval(int ms) |
成员函数文档
[explicit] QWebChannel::QWebChannel(QObject *parent = nullptr)
使用给定的parent 构建QWebChannel对象。
请注意，只有将 QWebChannel 连接到QWebChannelAbstractTransport 后，它才能完全正常工作。HTML 客户端也需要使用 qwebchannel.js进行适当配置。
[virtual noexcept] QWebChannel::~QWebChannel()
销毁QWebChannel 。
[slot] void QWebChannel::connectTo(QWebChannelAbstractTransport *transport)
将QWebChannel 连接到指定的transport 对象。
随后，该传输对象将负责处理 C++ 应用程序与远程 HTML 客户端之间的通信。
另请参阅 QWebChannelAbstractTransport 和QWebChannel::disconnectFrom()。
[invokable] void QWebChannel::deregisterObject(QObject *object)
将给定的object 从QWebChannel 中注销。
远程客户端将收到针对该对象的destroyed 信号。
注意：此 函数可通过元对象系统和 QML 调用。参见Q_INVOKABLE 。
另请参阅 QWebChannel::registerObjects()、QWebChannel::registerObject() 和QWebChannel::registeredObjects()。
[slot] void QWebChannel::disconnectFrom(QWebChannelAbstractTransport *transport)
将QWebChannel 与transport 对象断开连接。
另请参阅 QWebChannel::connectTo()。
[invokable] void QWebChannel::registerObject(const QString &id, QObject *object)
将单个对象注册到QWebChannel 中。
object 的属性、信号和公共方法将发布给远程客户端。随后，在客户端会构建一个标识符为id 的对象。
对于属于BINDABLE 但未具有NOTIFY 信号的属性，其属性更新在客户端上仍可正常工作，但没有机制可注册回调以接收变更通知。
注意： 当前的限制 是，必须在任何客户端初始化之前注册对象。
注意：此 函数可通过元对象系统和 QML 调用。参见Q_INVOKABLE 。
另请参阅 QWebChannel::registerObjects()、QWebChannel::deregisterObject() 和QWebChannel::registeredObjects()。
void QWebChannel::registerObjects(const QHash<QString, QObject *> &objects)
将一组对象注册到QWebChannel 中。
这些对象的属性、信号和公共可调用方法将发布给远程客户端。随后，远程客户端会根据在objects 映射中用作键的标识符，构建一个对象。
注意： 当前的限制 是，必须在任何客户端初始化之前完成对象的注册。
另请参阅 QWebChannel::registerObject()、QWebChannel::deregisterObject() 和QWebChannel::registeredObjects()。
QHash<QString, QObject *> QWebChannel::registeredObjects() const
返回已注册且已发布给远程客户端的对象映射。
另请参阅 QWebChannel::registerObjects()、QWebChannel::registerObject() 和QWebChannel::deregisterObject()。
© 2026 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.
