Qt WebChannel JavaScript API
JavaScript API の設定
QWebChannel またはWebChannel と通信するには、クライアントはqwebchannel.js が提供する JavaScript API を使用し、設定する必要があります。 Qt WebEngine内で実行されるクライアントの場合、ページをローカルで読み込む場合はqrc:///qtwebchannel/qwebchannel.js 経由でファイルをロードするか、QWebEngineUrlScheme にQWebEngineUrlScheme::SecureScheme として登録されたQWebEngineUrlSchemeHandler からqwebchannel.js にアクセスできるようにします。外部クライアントの場合は、ファイルをWebサーバーにコピーする必要があります。 次に、QWebChannel オブジェクトをインスタンス化し、トランスポートオブジェクトとコールバック関数を渡します。このコールバック関数は、チャネルの初期化が完了し、公開されたオブジェクトが利用可能になった時点で呼び出されます。オプションの3番目の引数には、コンバータラッパー関数の配列、または単一の関数を指定できます。
トランスポートオブジェクトは、最小限のメッセージパッシングインターフェースを実装します。これは、文字列化されたJSONメッセージを受け取り、それをサーバー側のQWebChannelAbstractTransport オブジェクトに送信するsend() 関数を持つオブジェクトである必要があります。さらに、サーバーからのメッセージを受信した際には、そのonmessage プロパティが呼び出される必要があります。あるいは、WebSocketを使用してこのインターフェースを実装することもできます。
なお、JavaScriptのQWebChannel オブジェクトは、トランスポートオブジェクトが完全に動作し始めてから構築する必要があります。WebSocketの場合、これはQWebChannel をソケットのonopen ハンドラ内で作成する必要があることを意味します。具体的な実装方法については、「Qt WebChannel スタンドアロンサンプル」を参照してください。
注: 同じページ内で、1つのトランスポートにつき1つのQWebChannel オブジェクトのみ 作成できます。
コンバータのラッパー関数は、組み込みコンバータの名前を指定した文字列、または処理対象のオブジェクトを引数として受け取り、結果の型を返す(関数が適用できない場合は `undefined` を返す)ユーザー定義関数のいずれかです。`undefined` が返された場合、次のコンバータが処理されます。 undefined 以外の値を返すコンバータが存在しない場合、処理は通常通り進行します。現在、組み込みのコンバータ関数として「Date」のみが用意されています。この関数は、ISO 8601 形式の日付を含む文字列を受け取り、構文が正しく日付が有効な場合に新しい Date オブジェクトを返します。
QObject との連携
QWebChannel オブジェクトに渡されたコールバックが呼び出されると、チャネルの初期化が完了し、公開されたすべてのオブジェクトに、HTMLクライアントはchannel.objects プロパティを介してアクセスできるようになります。したがって、識別子「foo」でオブジェクトが公開されていたと仮定すると、以下の例に示すようにそのオブジェクトとやり取りすることができます。 なお、HTMLクライアントとQML/C++サーバー間の通信はすべて非同期であることに注意してください。プロパティはHTML側でキャッシュされます。さらに、JSONに変換可能なQML/C++データ型のみが適切に(デ)シリアライズされ、HTMLクライアントからアクセス可能になる点にも留意してください。
new QWebChannel(yourTransport, function(channel) {
// Connect to a signal:
channel.objects.foo.mySignal.connect(function() {
// This callback will be invoked whenever the signal is emitted on the C++/QML side.
console.log(arguments);
});
// To make the object known globally, assign it to the window object, i.e.:
window.foo = channel.objects.foo;
// Invoke a method:
foo.myMethod(arg1, arg2, function(returnValue) {
// This callback will be invoked when myMethod has a return value. Keep in mind that
// the communication is asynchronous, hence the need for this callback.
console.log(returnValue);
});
// Read a property value, which is cached on the client side:
console.log(foo.myProperty);
// Writing a property will instantly update the client side cache.
// The remote end will be notified about the change asynchronously
foo.myProperty = "Hello World!";
// To get notified about remote property changes,
// simply connect to the corresponding notify signal:
foo.myPropertyChanged.connect(function() {
console.log(foo.myProperty);
});
// One can also access enums that are marked with Q_ENUM:
console.log(foo.MyEnum.MyEnumerator);
});オーバーロードされたメソッドとシグナル
オーバーロードされたメソッドを持つQObject を公開する場合、QWebChannel はメソッドの呼び出しを最適な一致に解決します。 なお、JavaScriptの型システム上、C++の「double」に最もよく対応する「number」型は1つしか存在しません。オーバーロードが数値型のパラメータの型のみ異なる場合、QWebChannel は常にJavaScriptの「number」型に最も一致するオーバーロードを選択します。 オーバーロードされたシグナルに接続する場合、QWebChannel クライアントはデフォルトで、その名前の最初のシグナルオーバーロードにのみ接続します。さらに、メソッドやシグナルのオーバーロードは、完全なQMetaMethod シグネチャを指定することで明示的に要求することもできます。C++側で次のようなQObject のサブクラスがあると仮定します:
class Foo : public QObject
{
Q_OBJECT
slots:
void foo(int i);
void foo(double d);
void foo(const QString &str);
void foo(const QString &str, int i);
signals:
void bar(int i);
void bar(const QString &str);
void bar(const QString &str, int i);
};この場合、JavaScript側では次のようにこのクラスとやり取りすることができます:
// methods
foo.foo(42); // will call the method named foo which best matches the JavaScript number parameter, i.e. foo(double d)
foo.foo("asdf"); // will call foo(const QString &str)
foo.foo("asdf", 42); // will call foo(const QString &str, int i)
foo["foo(int)"](42); // explicitly call foo(int i), *not* foo(double d)
foo["foo(QString)"]("asdf"); // explicitly call foo(const QString &str)
foo["foo(QString,int)"]("asdf", 42); // explicitly call foo(const QString &str, int i)
// signals
foo.bar.connect(...); // connect to first signal named bar, i.e. bar(int i)
foo["bar(int)"].connect(...); // connect explicitly to bar(int i)
foo["bar(QString)"].connect(...); // connect explicitly to bar(const QString &str)
foo["bar(QString,int)"].connect(...); // connect explicitly to bar(const QString &str, int i)© 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.