QJSEngine Class

メンバ関数ドキュメント

QJSEngine::QJSEngine()

QJSEngine オブジェクトを構築します。

globalObject() は、ECMA-262 のセクション 15.1 に記述されているプロパティを持つように初期化される。

[explicit] QJSEngine::QJSEngine(QObject *parent)

指定されたparent を持つ QJSEngine オブジェクトを構築します。

globalObject() は、ECMA-262 のセクション 15.1 に記述されているプロパティを持つように初期化されます。

[override virtual noexcept] QJSEngine::~QJSEngine()

このQJSEngine を破棄します。

QJSEngine の破棄中は、永続 JS ヒープからゴミは収集されません。すべてのメモリを解放する必要がある場合は、QJSEngine を破棄する直前にcollectGarbage() を手動で呼び出します。

[since Qt 6.1] QJSValue QJSEngine::catchError()

現在保留中の例外がある場合は、それをキャッチし、QJSValue として返します。それ以外の場合は、QJSValue として未定義を返します。このメソッドを呼び出した後、hasError() はfalse を返します。

この関数は Qt 6.1 で導入されました。

template <typename From, typename To> To QJSEngine::coerceValue(const From &from)

与えられたfrom をテンプレート型To に変換して返します。変換は JavaScript のセマンティクスで行われます。これらはqvariant_cast のセマンティクスとは異なります。デフォルトではqvariant_cast によって実行されない、JavaScript と同等の型間の暗黙の変換が多数あります。このメソッドは、このクラスの他のすべての変換メソッドの一般化です。

fromVariant(),qvariant_cast(),fromScriptValue(),toScriptValue()も参照してください 。

void QJSEngine::collectGarbage()

ガベージ・コレクタを実行します。

ガベージ・コレクタは、スクリプト環境で到達できなくなったオブジェクトを探し出し、廃棄することで、メモリの再利用を試みます。

通常、この関数を呼び出す必要はありません。ガベージコレクタは、QJSEngine がそうするのが賢明だと判断したとき（つまり、一定数の新しいオブジェクトが作成されたとき）に自動的に呼び出されます。しかし、この関数を呼び出して、できるだけ早くガベージコレクションを実行するよう明示的に要求することもできます。

ガベージ・コレクションおよびgc()も参照して ください。

QJSValue QJSEngine::evaluate(const QString &program, const QString &fileName = QString(), int lineNumber = 1, QStringList *exceptionStackTrace = nullptr)

lineNumber を基準行番号としてprogram を評価し、評価結果を返します。

スクリプト・コードは、グローバル・オブジェクトのコンテキストで評価されます。

program を評価すると、エンジン内でexception が発生することがあります。この場合、返り値はスローされた例外（通常はError オブジェクト。QJSValue::isError() を参照）になります。

lineNumber は、 の開始行番号を指定するために使用されます。この評価に関連してエンジンから報告される行番号情報は、この引数に基づいています。たとえば、 が2行のコードで構成され、2行目のステートメントでスクリプト例外が発生した場合、例外行番号は に1を足したものになります。開始行番号が指定されない場合、行番号は1ベースとなる。program program lineNumber

fileName はエラー報告に使用されます。例えば、この関数でファイル名を指定すると、エラーオブジェクトの "fileName" プロパティからファイル名にアクセスできるようになります。

exceptionStackTrace は、捕捉されない例外が発生したかどうかを報告するために使用されます。この関数に への NULL 以外のポインタを渡すと、スクリプトが未処理の例外をスローした場合は「スタックフレームメッセージ」のリストが設定され、そうでない場合は空のリストが設定されます。スタックフレームメッセージの書式は、関数名：行番号：列：ファイル名です。QStringList

QQmlExpression::evaluateも参照してください 。

template <typename T> T QJSEngine::fromManagedValue(const QJSManagedValue &value)

与えられたvalue をテンプレート型T に変換して返します。

toManagedValue() およびcoerceValue() も参照 。

template <typename T> T QJSEngine::fromPrimitiveValue(const QJSPrimitiveValue &value)

与えられたvalue をテンプレート型T に変換して返します。

QJSPrimitiveValue は int、bool、double、QString 、および JavaScript のnull とundefined に相当するものしか保持できないので、それ以外の型を要求した場合、値は積極的に強制されます。

toPrimitiveValue() およびcoerceValue()も参照 。

template <typename T> T QJSEngine::fromScriptValue(const QJSValue &value)

与えられたvalue をテンプレート型T に変換して返します。

toScriptValue() およびcoerceValue() も参照 。

template <typename T> T QJSEngine::fromVariant(const QVariant &value)

与えられたvalue をテンプレート型T に変換して返します。変換はJavaScriptのセマンティクスで行われます。これらはqvariant_cast のセマンティクスとは異なります。JavaScriptと等価な型間の暗黙の変換がいくつかあり、デフォルトではqvariant_cast では実行されません。

coerceValue(),fromScriptValue(),qvariant_cast()も参照してください 。

QJSValue QJSEngine::globalObject() const

このエンジンのグローバル・オブジェクトを返します。

デフ ォル ト では、 グローバル オブジ ェ ク ト には、 Math ・ Date ・ String と いっ たECMA-262 の一部であ る 組み込みオブジ ェ ク ト が含まれてい ます。さらに、グローバル・オブジェクトのプロパティを設定して、独自の拡張をすべてのスクリプト・コードで使用できるようにすることもできます。スクリプトコード内の非ローカル変数は、グローバルコード内のローカル変数と同様に、グローバルオブジェクトのプロパティとして作成されます。

[since Qt 6.1] bool QJSEngine::hasError() const

最後の JavaScript 実行で例外が発生した場合、またはthrowError() が呼び出された場合はtrue を返します。そうでない場合はfalse を返します。evaluate() は、評価されたコードでスローされた例外をキャッチします。

この関数は Qt 6.1 で導入されました。

QJSValue QJSEngine::importModule(const QString &fileName)

fileName にあるモジュールをインポートし、すべてのエクスポートされた変数、定数、関数をプロパティとして含むモジュール名前空間オブジェクトを返します。

エンジンでモジュールが初めてインポートされる場合、ファイルはローカルファイルシステムまたは Qt リソースシステムの指定された場所からロードされ、ECMAScript モジュールとして評価されます。ファイルは UTF-8 テキストでエンコードされます。

同じモジュールを続けてインポートすると、前にインポートしたインスタンスが返されます。モジュールはシングルトンであり、エンジンが破棄されるまで残ります。

指定されたfileName は、内部的にQFileInfo::canonicalFilePath() を使って正規化されます。つまり、ディスク上の同じファイルを異なる相対パスで複数回インポートしても、ファイルは1回しかロードされません。

registerModule()も参照 。

void QJSEngine::installExtensions(QJSEngine::Extensions extensions, const QJSValue &object = QJSValue())

標準の ECMAScript 実装では利用できない機能を追加するために、JavaScriptextensions をインストールします。

拡張機能は、指定されたobject にインストールされ、オブジェクトが指定されていない場合はGlobal Object にインストールされます。

列挙値をOR- することで、複数の拡張を一度にインストールすることができます：

installExtensions(QJSEngine::TranslationExtension | QJSEngine::ConsoleExtension);

Extensionも参照 。

bool QJSEngine::isInterrupted() const

JavaScript の実行が現在中断されているかどうかを返します。

setInterrupted()も参照して ください。

QJSValue QJSEngine::newArray(uint length = 0)

指定されたlength で Array クラスの JavaScript オブジェクトを作成します。

newObject() も参照して ください。

QJSValue QJSEngine::newErrorObject(QJSValue::ErrorType errorType, const QString &message = QString())

エラーメッセージとしてmessage を指定して、Error クラスの JavaScript オブジェクトを作成します。

作成されたオブジェクトのプロトタイプはerrorType になります。

newObject()、throwError()、QJSValue::isError() も参照 。

QJSValue QJSEngine::newObject()

Object クラスの JavaScript オブジェクトを作成します。

作成されたオブジェクトのプロトタイプは、Object プロトタイプ・オブジェクトになります。

newArray() およびQJSValue::setProperty() も参照して ください。

template <typename T> QJSValue QJSEngine::newQMetaObject()

クラスT に関連付けられた staticQMetaObject をラップする JavaScript オブジェクトを作成します。

newQObject() およびQObject Integration も参照して ください。

QJSValue QJSEngine::newQMetaObject(const QMetaObject *metaObject)

指定されたQMetaObject をラップする JavaScript オブジェクトを作成します。metaObject は、スクリプト・エンジンよりも長生きしなければなりません。このメソッドは、静的メタオブジェクトでのみ使用することをお勧めします。

コンストラクタとして呼び出されると、クラスの新しいインスタンスが作成されます。スクリプトエンジンから見えるのは、Q_INVOKABLE によって公開されたコンストラクタだけです。

newQObject() およびQObject Integrationも参照してください 。

QJSValue QJSEngine::newQObject(QObject *object)

与えられたQObject object をラップする JavaScript オブジェクトを、JavaScriptOwnership を使って作成します。

object のシグナル と ス ロ ッ ト 、 プ ロ パテ ィ と 子プ ロ パテ ィ は、 作成 さ れたQJSValue のプ ロ パテ ィ と し て利用可能です。

object が NULL ポインタの場合、この関数は NULL 値を返します。

object のクラス（または再帰的にそのスーパークラス）にデフォルトのプロトタイプが登録されている場合、新しいスクリプトオブジェクトのプロトタイプはそのデフォルトのプロトタイプに設定されます。

指定 さ れたobject がエン ジ ンの制御外で削除 さ れた場合、 JavaScript ラ ッ パオブジ ェ ク ト を通 じ て削除 さ れたQObject の メ ンバにア ク セ ス し よ う と す る と （ス ク リ プ ト コ ー ド で も C++ で も）、script exception にな り ます。

QJSValue::toQObject()も参照して ください。

[since 6.2] QJSValue QJSEngine::newSymbol(const QString &name)

値name を持つ Symbol クラスの JavaScript オブジェクトを作成します。

作成されたオブジェクトのプロトタイプは Symbol プロトタイプオブジェクトになります。

この関数は Qt 6.2 で導入されました。

newObject()も参照してください 。

[static] QJSEngine::ObjectOwnership QJSEngine::objectOwnership(QObject *object)

object の所有権を返します。

setObjectOwnership() およびQJSEngine::ObjectOwnershipも参照のこと 。

bool QJSEngine::registerModule(const QString &moduleName, const QJSValue &value)

QJSValue をモジュールとして登録する。この関数が呼ばれた後、moduleName をインポートするすべてのモジュールは、ファイルシステムからmoduleName をロードする代わりに、value の値をインポートします。

有効なQJSValue ならどれでも登録できますが、名前付きエクスポート（すなわちimport { name } from "info" ）はオブジェクトのメンバーとして扱われるため、デフォルトのエクスポートはQJSEngine の newXYZ メソッドのいずれかで作成する必要があります。

これにより、ファイルシステム上に存在しないモジュールをインポートできるため、スクリプト・アプリケーションはこれを使用して、Node.jsのような組み込みモジュールを提供できる。

成功すればtrue を、そうでなければfalse を返す。

importModule()も参照のこと 。

void QJSEngine::setInterrupted(bool interrupted)

JavaScript の実行を中断または再有効化します。

interrupted がtrue の場合、このエンジンによって実行された JavaScript は、この関数がfalse の値interrupted で再度呼び出されるまで、直ちに中断され、エラーオブジェクトを返します。

この関数はスレッドセーフです。たとえば、JavaScript の無限ループを中断するために、別のスレッドからこの関数を呼び出すことができます。

isInterrupted()も参照 。

[static] void QJSEngine::setObjectOwnership(QObject *object, QJSEngine::ObjectOwnership ownership)

object のownership を設定します。

JavaScriptOwnership を持つオブジェクトは、たとえそのオブジェクトへの参照がなくても、親が存在する限りガベージコレクションされません。

objectOwnership() およびQJSEngine::ObjectOwnershipも参照 。

[since Qt 5.12] void QJSEngine::throwError(const QString &message)

与えられたmessage でランタイム・エラー（例外）をスローします。

このメソッドは、JavaScript のthrow() 式に対応する C++ メソッドです。こ れに よ り 、 C++ コ ー ド は実行時エ ラ ーをQJSEngine に報告で き る よ う にな り ます。 こ のため、 こ の メ ソ ッ ド は、 JavaScript 関数か らQJSEngine を通 じ て呼び出 さ れた C++ コ ー ド か ら のみ呼び出す必要があ り ます。

C++ から戻るとき、エンジンは通常の実行フローを中断し、あらかじめ登録された次の例外ハンドラを、指定されたmessage を含むエラー・オブジェクトとともに呼び出します。エラー・オブジェクトは、JavaScriptの呼び出し側スタックの最上位コンテキストの場所を指します。具体的には、lineNumber 、fileName 、stack のプロパティを持ちます。これらのプロパティはScript Exceptions で説明されています。

以下の例では、FileAccess.cppのC++メソッドが、readFileAsText() が呼び出された位置のqmlFile.qmlでエラーをスローしています：

// qmlFile.qml
function someFunction() {
  ...
  var text = FileAccess.readFileAsText("/path/to/file.txt");
}

// FileAccess.cpp
// Assuming that FileAccess is a QObject-derived class that has been
// registered as a singleton type and provides an invokable method
// readFileAsText()

QJSValue FileAccess::readFileAsText(const QString & filePath) {
  QFile file(filePath);

  if (!file.open(QIODevice::ReadOnly)) {
    jsEngine->throwError(file.errorString());
    return QString();
  }

  ...
  return content;
}

スローされたエラーをJavaScriptでキャッチすることも可能です：

// qmlFile.qml
function someFunction() {
  ...
  var text;
  try {
    text = FileAccess.readFileAsText("/path/to/file.txt");
  } catch (error) {
    console.warn("In " + error.fileName + ":" + "error.lineNumber" +
                 ": " + error.message);
  }
}

例外を記述するために、より具体的なランタイムエラーが必要な場合、throwError(QJSValue::ErrorType errorType, const QString &message)オーバーロードを使用することができます。

この関数はQt 5.12で導入されました。

Script Exceptionsも参照してください 。

[since 6.1] void QJSEngine::throwError(const QJSValue &error)

この関数は throwError() をオーバーロードします。

事前に構成されたランタイムerror （例外）をスローします。これにより、newErrorObject() を使用してエラーを作成し、必要に応じてカスタマイズすることができます。

この関数は Qt 6.1 で導入されました。

Script Exceptions とnewErrorObject()も参照してください 。

[since Qt 5.12] void QJSEngine::throwError(QJSValue::ErrorType errorType, const QString &message = QString())

この関数は throwError() をオーバーロードします。

与えられたerrorType とmessage でランタイムエラー（例外）をスローします。

// Assuming that DataEntry is a QObject-derived class that has been
// registered as a singleton type and provides an invokable method
// setAge().

void DataEntry::setAge(int age) {
  if (age < 0 || age > 200) {
    jsEngine->throwError(QJSValue::RangeError,
                         "Age must be between 0 and 200");
  }
  ...
}

この関数は Qt 5.12 で導入されました。

Script Exceptions およびnewErrorObject()も参照してください 。

template <typename T> QJSManagedValue QJSEngine::toManagedValue(const T &value)

与えられたvalue でQJSManagedValue を作成します。

fromManagedValue() およびcoerceValue() も参照して ください。

template <typename T> QJSPrimitiveValue QJSEngine::toPrimitiveValue(const T &value)

与えられたvalue でQJSPrimitiveValue を作成します。

QJSPrimitiveValue が保持できるのは int、bool、double、QString 、および JavaScript のnull とundefined に相当するものだけなので、それ以外の型を渡すと、値は積極的に強制されます。

fromPrimitiveValue() およびcoerceValue()も参照 。

template <typename T> QJSValue QJSEngine::toScriptValue(const T &value)

与えられたvalue を持つQJSValue を作成します。

fromScriptValue() およびcoerceValue()も参照 ください。