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 으로 변환하여 반환합니다. 변환은 자바스크립트 시맨틱으로 이루어집니다. 이는 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 에 널이 아닌 포인터를 전달하면 스크립트에서 처리되지 않은 예외가 발생하면 "스택프레임 메시지" 목록으로, 그렇지 않으면 빈 목록으로 설정됩니다. 스택프레임 메시지는 함수 이름:줄 번호:열:파일 이름 형식입니다.

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

이 엔진의 글로벌 오브젝트를 반환합니다.

기본적으로 글로벌 객체에는 수학, 날짜 및 문자열과 같은 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()을 사용하여 정규화됩니다. 즉, 서로 다른 상대 경로를 사용하여 디스크에 있는 동일한 파일을 여러 번 임포트하면 파일이 한 번만 로드됩니다.

registerModule()도 참조하세요 .

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

자바스크립트 extensions 를 설치하여 표준 ECMAScript 구현에서 사용할 수 없는 기능을 추가합니다.

확장 프로그램은 지정된 object 또는 객체가 지정되지 않은 경우 Global Object 에 설치됩니다.

열거형 값을 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 클래스의 자바스크립트 객체를 생성합니다.

생성된 객체의 프로토타입은 errorType 입니다.

newObject(), throwError() 및 QJSValue::isError()도 참조하세요 .

QJSValue QJSEngine::newObject()

Object 클래스의 JavaScript 객체를 생성합니다.

생성된 객체의 프로토타입은 Object 프로토타입 객체가 됩니다.

newArray() 및 QJSValue::setProperty()도 참조하세요 .

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

T 클래스와 연관된 정적 QMetaObject 을 래핑하는 자바스크립트 객체를 생성합니다.

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

QJSValue QJSEngine::newQMetaObject(const QMetaObject *metaObject)

주어진 QMetaObject 을 래핑하는 자바스크립트 객체를 만듭니다. metaObject 은 스크립트 엔진보다 오래 지속되어야 합니다. 이 메서드는 정적 메타객체에만 사용하는 것이 좋습니다.

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

newQObject() 및 QObject Integration 을참조하세요 .

QJSValue QJSEngine::newQObject(QObject *object)

JavaScriptOwnership 을 사용하여 주어진 QObject object 을 래핑하는 자바스크립트 객체를 생성합니다.

object 의 신호와 슬롯, 프로퍼티 및 자식은 생성된 QJSValue 의 프로퍼티로 사용할 수 있습니다.

object 이 널 포인터인 경우 이 함수는 널 값을 반환합니다.

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

지정된 object 이 엔진의 제어 범위를 벗어나 삭제된 경우, 스크립트 코드 또는 C++ 로 JavaScript 래퍼 객체를 통해 삭제된 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 을 반환합니다.

importModule()도 참조하세요 .

void QJSEngine::setInterrupted(bool interrupted)

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

interrupted 이 true 인 경우 이 엔진에서 실행되는 모든 JavaScript는 즉시 중단되고 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 을 통해 JavaScript 함수에 의해 호출된 C++ 코드에서만 호출해야 합니다.

C++에서 반환할 때 엔진은 정상적인 실행 흐름을 중단하고 지정된 message 이 포함된 오류 객체를 사용하여 미리 등록된 다음 예외 처리기를 호출합니다. 에러 객체는 자바스크립트 호출자 스택에서 가장 위에 있는 컨텍스트의 위치를 가리키며, 구체적으로 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;
}

자바스크립트에서 던져진 오류를 포착할 수도 있습니다:

// 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()도 참조하세요 .