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 のセマンティクスとは異なります。デフォルトではqvariant_cast によって実行されない、JavaScript と同等の型間の多くの暗黙の変換があります。

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 に関連付けられた静的なQMetaObject をラップする 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)

nameSymbol クラスの 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 は直ちに中断され、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++メソッドが、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()も参照 ください。