자바스크립트 호스트 환경

QML은 QML 애플리케이션 작성에 맞춘 JavaScript 호스트 환경을 제공합니다. 이 환경은 브라우저에서 제공하는 호스트 환경이나 Node.js와 같은 서버 측 JavaScript 환경과는 다릅니다. 예를 들어, QML은 브라우저 환경에서 흔히 볼 수 있는 window 객체나 DOM API 객체를 제공하지 않습니다.

공통 기반

브라우저 또는 서버 측 JavaScript 환경과 마찬가지로 QML 런타임은 ECMAScript 언어 사양 표준을 구현합니다. 이를 통해 객체, 배열, 수학 등 표준에 정의된 모든 기본 제공 유형과 함수에 액세스할 수 있습니다. QML 런타임은 표준의 7번째 에디션을 구현합니다.

Nullish Coalescing (??)(Qt 5.15부터)과 Optional Chaining (?.)(Qt 6.2부터)도 QML 런타임에서 구현됩니다.

표준 ECMAScript 내장 기능은 QML 문서에 명시적으로 문서화되어 있지 않습니다. 사용에 대한 자세한 내용은 ECMA-262 7판 표준 또는 W3Schools JavaScript 참조 (JavaScript 객체 참조 섹션)와 같은 많은 온라인 JavaScript 참조 및 튜토리얼 사이트 중 하나를 참조하시기 바랍니다. 많은 사이트가 브라우저의 JavaScript에 초점을 맞추고 있으므로 특정 함수나 객체가 표준 ECMAScript의 일부인지 아니면 브라우저 환경에 특정한 것인지 확인하기 위해 사양을 다시 확인해야 하는 경우도 있습니다. 위의 W3Schools 링크의 경우 JavaScript Objects Reference 섹션은 일반적으로 표준을 다루고 있지만 Browser Objects Reference 및 HTML DOM Objects Reference 섹션은 브라우저별(따라서 QML에는 적용되지 않음)입니다.

유형 주석 및 어설션

QML 문서의 함수 선언에는 유형 어노테이션이 포함될 수 있으며 반드시 포함되어야 합니다. 타입 어노테이션은 인자 선언과 함수 자체에 추가되어 반환 타입에 주석을 달 수 있습니다. 다음 함수는 int 및 string 매개 변수를 받아 QtObject 를 반환합니다:

function doThings(a: int, b: string) : QtObject { ... }

타입 어노테이션은 Qt Creator 및 qmllint와 같은 도구가 코드를 이해하고 더 나은 진단을 제공하는 데 도움이 됩니다. 또한 C++에서 함수를 더 쉽게 사용할 수 있게 해줍니다. 자세한 내용은 C++에서 QML 객체와 상호 작용하기를 참조하세요.

유형 어설션( as-cast라고도 함)을 사용하여 객체를 다른 객체 유형으로 캐스팅할 수도 있습니다. 객체가 실제로 지정된 유형인 경우 유형 어설션은 동일한 객체를 반환합니다. 그렇지 않은 경우 null 을 반환합니다. 다음 코드 조각에서는 특정 멤버에 액세스하기 전에 parent 객체가 Rectangle 객체임을 어설 션합니다.

Item {
    property color parentColor: (parent as Rectangle)?.color || "red"
}

선택적 체인(?.)은 부모가 실제로 사각형이 아닌 경우 예외가 발생하지 않도록 합니다. 이 경우 "빨간색"은 parentColor 로 선택됩니다.

Qt 6.7부터는 함수를 호출할 때 항상 타입 어노테이션이 적용됩니다. 값은 필요에 따라 필요한 유형으로 강제로 지정됩니다. 이전에는 인터프리터와 JIT 컴파일러에서 타입 어노테이션이 무시되었지만, C++로 컴파일할 때 qmlcachegen과 qmlsc에 의해 강제 적용되었습니다. 이로 인해 일부 코너 케이스에서 동작에 차이가 발생할 수 있습니다. 인터프리터와 JIT의 이전 동작을 명시적으로 요청하려면 QML 문서에 다음을 추가하면 됩니다:

pragma FunctionSignatureBehavior: Ignored

QML 전역 객체

QML JavaScript 호스트 환경은 QML 글로벌 객체 문서에 자세히 설명된 대로 여러 호스트 객체와 함수를 구현합니다.

이러한 호스트 객체와 함수는 모듈을 가져왔는지 여부에 관계없이 항상 사용할 수 있습니다.

자바스크립트 객체 및 함수

QML 엔진에서 지원하는 JavaScript 객체, 함수 및 프로퍼티 목록은 JavaScript 객체 및 함수 목록에서 확인할 수 있습니다.

QML은 네이티브 객체를 다음과 같이 수정합니다:

• String 프로토타입에 arg() 함수가 추가되었습니다.
• Date 및 Number 프로토타입에 로캘 인식 변환 함수가 추가되었습니다.

또한 QML은 인스턴스 오브 함수의 동작을 확장하여 QML 유형에 대한 유형 검사를 허용합니다. 즉, 예를 들어 변수가 실제로 예상한 유형인지 확인하는 데 사용할 수 있습니다:

var v = something();
if (!v instanceof Item) {
    throw new TypeError("I need an Item type!");
}

...

자바스크립트 환경 제한

QML은 JavaScript 코드에 대해 다음과 같은 제한을 구현합니다:

• .qml 파일에 작성된 JavaScript 코드는 전역 객체를 수정할 수 없습니다. .js 파일의 JavaScript 코드는 전역 객체를 수정할 수 있으며, 이러한 수정 사항은 가져올 때 .qml 파일에 표시됩니다.

  QML에서 전역 객체는 상수이므로 기존 속성을 수정하거나 삭제할 수 없으며 새 속성을 만들 수도 없습니다.

  대부분의 JavaScript 프로그램은 의도적으로 전역 객체를 수정하지 않습니다. 그러나 자바스크립트가 선언되지 않은 변수를 자동으로 생성하는 것은 전역 객체를 암시적으로 수정하는 것으로, QML에서는 금지되어 있습니다.

  a 변수가 스코프 체인에 존재하지 않는다고 가정할 때 다음 코드는 QML에서 불법입니다:

  // Illegal modification of undeclared variable
  a = 1;
  for (var ii = 1; ii < 10; ++ii)
      a = a * ii;
  console.log("Result: " + a);

  이 합법적인 코드로 간단히 수정할 수 있습니다.

  var a = 1;
  for (var ii = 1; ii < 10; ++ii)
      a = a * ii;
  console.log("Result: " + a);

  암시적이든 명시적이든 글로벌 객체를 수정하려고 시도하면 예외가 발생합니다. 적발되지 않으면 문제가 되는 코드의 파일 및 줄 번호가 포함된 경고가 인쇄됩니다.

• 전역 코드는 축소된 범위에서 실행됩니다.

  시작 시 QML 파일에 '전역' 코드가 포함된 외부 JavaScript 파일이 포함되어 있으면 외부 파일 자체와 전역 객체만 포함된 범위에서 실행됩니다. 즉, 평소와 같이 QML 객체 및 프로퍼티에 액세스할 수 없습니다.

  스크립트 로컬 변수에만 액세스하는 전역 코드는 허용됩니다. 다음은 유효한 전역 코드의 예시입니다.

  var colors = [ "red", "blue", "green", "orange", "purple" ];

  QML 객체에 액세스하는 전역 코드는 올바르게 실행되지 않습니다.

  // Invalid global code - the "rootObject" variable is undefined
  var initialPosition = { rootObject.x, rootObject.y }

  이 제한은 QML 환경이 아직 완전히 설정되지 않았기 때문에 존재합니다. 환경 설정이 완료된 후 코드를 실행하려면 애플리케이션 시작 코드의 JavaScript를 참조하세요.

• this 값은 대부분의 컨텍스트에서 QML에서 정의되지 않습니다.

  this 키워드는 JavaScript에서 속성을 바인딩할 때 지원됩니다. QML 바인딩 표현식, QML 시그널 핸들러 및 QML 선언 함수에서 this 은 범위 객체를 참조합니다. 다른 모든 상황에서 this 의 값은 QML에서 정의되지 않습니다.

  특정 객체를 참조하려면 id 를 제공하세요:

  Item {
      width: 200; height: 100
      function mouseAreaClicked(area) {
          console.log("Clicked in area at: " + area.x + ", " + area.y);
      }
      // This will pass area to the function
      MouseArea {
          id: area
          y: 50; height: 50; width: 200
          onClicked: mouseAreaClicked(area)
      }
  }