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 のセマンティクスとは異なります。JavaScriptで同等の型間には多くの暗黙的な変換が存在しますが、qvariant_cast ではデフォルトではこれらが実行されません。このメソッドは、このクラス内の他のすべての変換メソッドを一般化したものです。

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)

`program` を、`lineNumber ` を基数として評価し、その評価結果を返します。

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

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

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

fileName はエラー報告に使用されます。例えば、エラーオブジェクトでは、この関数でファイル名が指定されている場合、そのファイル名は「fileName」プロパティを通じてアクセス可能です。

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

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実装では利用できない機能を追加するために、JavaScriptのextensions をインストールします。

拡張機能は、指定された `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` に関連付けられた静的 `QMetaObject ` をラップする JavaScript オブジェクトを作成します。

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

QJSValue QJSEngine::newQMetaObject(const QMetaObject *metaObject)

指定されたQMetaObject をラップするJavaScriptオブジェクトを作成します。metaObject は、スクリプトエンジンよりも長く存続する必要があります。このメソッドは、静的なメタオブジェクトに対してのみ使用することを推奨します。

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

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

QJSValue QJSEngine::newQObject(QObject *object)

JavaScriptOwnership を使用して、指定された `QObject ` `object` をラップする JavaScript オブジェクトを作成します。

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

object がヌルポインタの場合、この関数はヌル値を返します。object が削除予定になっている場合や、そのデストラクタがすでに実行中の場合も同様です。

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

指定されたobject がエンジンの制御外で削除された場合、JavaScriptラッパーオブジェクトを介して（スクリプトコードまたはC++のいずれかによって）削除されたQObject のメンバにアクセスしようとすると、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 ` を返します。

// C++ setup
QJSValue container = engine.newObject();
container.setProperty("instance", engine.newQObject(&myDynamicObject));
engine.registerModule("api.mjs", container);

// JavaScript usage
import {instance as Api} from "api.mjs"

// ...

console.log(Api.dynamicProperty)

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

void QJSEngine::setInterrupted(bool interrupted)

JavaScriptの実行を中断または再開します。

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

この関数はスレッドセーフです。たとえば、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++ メソッドが、qmlFile.qml内のreadFileAsText() が呼び出される位置でエラーをスローします：

// 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)

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

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

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

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

指定された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()も参照してください 。