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`로 `undefined`를 반환합니다. 이 메서드를 호출한 후 ` hasError()`는 ` false`를 반환합니다.

이 함수는 Qt 6.1에서 도입되었습니다.

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

주어진 ` from `를 템플릿 유형 ` To`로 변환하여 반환합니다. 변환은 자바스크립트 의미 체계에 따라 수행됩니다. 이는 qvariant_cast 의 의미 체계와는 다릅니다. 자바스크립트 상응 유형 간에는 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)

lineNumber 를 기준 번호로 사용하여 ` program`을 평가하고, 평가 결과를 반환합니다.

스크립트 코드는 전역 객체의 컨텍스트에서 평가됩니다.

program 의 평가는 엔진에서 exception 을 발생시킬 수 있습니다. 이 경우 반환 값은 던져진 예외(일반적으로 Error 객체)가 됩니다( QJSValue::isError() 참조).

lineNumber 는 program 의 시작 줄 번호를 지정하는 데 사용됩니다. 이 평가와 관련하여 엔진에서 보고하는 줄 번호 정보는 이 인수를 기준으로 합니다. 예를 들어, ` program `이 두 줄의 코드로 구성되어 있고 두 번째 줄의 문장이 스크립트 예외를 유발하는 경우, 예외 줄 번호는 ` 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`로 변환한 결과를 반환합니다. 변환은 자바스크립트 의미 체계에 따라 수행됩니다. 이는 ` qvariant_cast`의 의미 체계와는 다릅니다. 자바스크립트와 동등한 유형 간에는 여러 암시적 변환이 존재하지만, ` qvariant_cast `는 기본적으로 이러한 변환을 수행하지 않습니다.

coerceValue(), fromScriptValue(), qvariant_cast()도 참조하십시오 .

QJSValue QJSEngine::globalObject() const

이 엔진의 전역 객체를 반환합니다.

기본적으로 전역 객체에는 Math, Date, String 등 ECMA-262의 일부인 내장 객체들이 포함되어 있습니다. 또한, 전역 객체의 속성을 설정하여 모든 스크립트 코드에서 사용자 정의 확장을 사용할 수 있도록 할 수 있습니다. 스크립트 코드 내의 비국소 변수는 전역 코드의 국소 변수와 마찬가지로 전역 객체의 속성으로 생성됩니다.

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

마지막 자바스크립트 실행에서 예외가 발생했거나 ` throwError()`가 호출된 경우 ` true `를 반환합니다. 그렇지 않은 경우 ` false`를 반환합니다. ` evaluate()`는 평가된 코드에서 발생된 모든 예외를 처리한다는 점에 유의하십시오.

이 함수는 Qt 6.1에서 도입되었습니다.

QJSValue QJSEngine::importModule(const QString &fileName)

fileName 에 위치한 모듈을 가져와, 내보낸 모든 변수, 상수 및 함수를 속성으로 포함하는 모듈 네임스페이스 객체를 반환합니다.

엔진에서 해당 모듈을 처음 가져오는 경우, 파일은 로컬 파일 시스템이나 Qt 리소스 시스템의 지정된 위치에서 로드되어 ECMAScript 모듈로 평가됩니다. 파일은 UTF-8 텍스트로 인코딩되어 있어야 합니다.

동일한 모듈을 이후에 다시 가져올 경우, 이전에 가져온 인스턴스가 반환됩니다. 모듈은 싱글톤이며 엔진이 소멸될 때까지 유지됩니다.

지정된 ` fileName `는 내부적으로 ` QFileInfo::canonicalFilePath()`를 사용하여 정규화됩니다. 즉, 서로 다른 상대 경로를 사용하여 디스크상의 동일한 파일을 여러 번 가져오더라도 파일은 한 번만 로드됩니다.

registerModule()도 참조하십시오 .

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

표준 ECMAScript 구현에서는 사용할 수 없는 기능을 추가하기 위해 JavaScript extensions 를 설치합니다.

확장 기능은 지정된 object 에 설치되며, 객체가 지정되지 않은 경우 Global Object 에 설치됩니다.

enum 값을 ` OR`로 지정하여 여러 확장 기능을 한 번에 설치할 수 있습니다:

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

Extension도 참조하십시오 .

bool QJSEngine::isInterrupted() const

현재 자바스크립트 실행이 중단되었는지 여부를 반환합니다.

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 )를 감싸는 자바스크립트 객체를 생성합니다. 이 메타객체( metaObject )는 스크립트 엔진보다 오래 지속되어야 합니다. 이 메서드는 정적 메타객체에만 사용하는 것이 좋습니다.

생성자로 호출되면 클래스의 새 인스턴스가 생성됩니다. 스크립트 엔진에서는 ` Q_INVOKABLE `가 노출한 생성자만 볼 수 있습니다.

newQObject() 및 QObject Integration도 참조하십시오 .

QJSValue QJSEngine::newQObject(QObject *object)

JavaScriptOwnership 를 사용하여, 지정된 QObject object 를 래핑하는 JavaScript 객체를 생성합니다.

object 의 시그널 및 슬롯, 속성, 자식 노드는 생성된 QJSValue 의 속성으로 사용할 수 있습니다.

object 가 null 포인터인 경우, 이 함수는 null 값을 반환합니다. object 가 삭제 예정이거나 소멸자가 이미 실행 중인 경우에도 마찬가지입니다.

object 의 클래스(또는 재귀적으로 그 슈퍼클래스)에 대해 기본 프로토타입이 등록된 경우, 새로운 스크립트 객체의 프로토타입은 해당 기본 프로토타입으로 설정됩니다.

지정된 ` object `가 엔진의 제어 범위 밖에서 삭제된 경우, 자바스크립트 래퍼 객체를 통해(스크립트 코드나 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)

자바스크립트 실행을 중단하거나 다시 활성화합니다.

interrupted 가 true 인 경우, 이 엔진에서 실행 중인 모든 자바스크립트는 즉시 중단되고, interrupted 에 대해 false 값을 지정하여 이 함수가 다시 호출될 때까지 오류 객체를 반환합니다.

이 함수는 스레드 안전합니다. 예를 들어, 자바스크립트 내의 무한 루프를 중단하기 위해 다른 스레드에서 이 함수를 호출할 수 있습니다.

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 를 사용하여 런타임 오류(예외)를 발생시킵니다.

이 메서드는 자바스크립트의 ` throw() ` 표현식에 해당하는 C++ 메서드입니다. 이 메서드를 사용하면 C++ 코드에서 ` QJSEngine`에 런타임 오류를 보고할 수 있습니다. 따라서 이 메서드는 ` 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()도 참조하십시오 .