JavaScript-среда хоста

QML предоставляет среду JavaScript-хоста, предназначенную для написания приложений QML. Эта среда отличается от среды хоста, предоставляемой браузером или серверной JavaScript-средой, такой как Node.js. Например, QML не предоставляет объект window или DOM API, как это обычно встречается в среде браузера.

Общая база

Как и среда JavaScript браузера или серверной стороны, среда выполнения QML реализует стандарт Спецификации языка ECMAScript. Это обеспечивает доступ ко всем встроенным типам и функциям, определенным стандартом, таким как Object, Array и Math. Среда выполнения QML реализует 7-ю редакцию стандарта.

Начиная с Qt 5.15, операция нулевого слияния также реализована в среде выполнения QML.

В документации QML стандартные встроенные элементы ECMAScript не документируются явно. Для получения дополнительной информации об их использовании обратитесь к стандарту ECMAScript 7-го издания или к одному из многих онлайн-справочников и обучающих сайтов по JavaScript, например, к справочнику по JavaScript W3Schools (раздел «Справочник по JavaScript Objects»). Многие сайты ориентированы на JavaScript в браузере, поэтому в некоторых случаях вам может потребоваться проверить спецификацию, чтобы определить, является ли данная функция или объект частью стандартного ECMAScript или специфична для среды браузера. В случае с приведенной выше ссылкой на W3Schools раздел JavaScript Objects Reference обычно охватывает стандарт, а разделы Browser Objects Reference и HTML DOM Objects Reference специфичны для браузера (и, следовательно, не применимы к QML).

Глобальный объект QML

Среда JavaScript-хоста QML реализует ряд объектов и функций хоста, как подробно описано в документации Глобальный объект QML.

Эти объекты и функции хоста всегда доступны, независимо от того, были ли импортированы какие-либо модули.

Объекты и функции JavaScript

Список объектов, функций и свойств JavaScript, поддерживаемых движком QML, можно найти в списке объектов и функций JavaScript.

Обратите внимание, что QML вносит следующие изменения в родные объекты:

• Функция arg() добавлена в прототип String.
• Функции преобразования с учетом региональных настроек добавлены в прототипы Date и Number.

Кроме того, QML также расширяет поведение функции instanceof, чтобы позволить проверку типов по отношению к типам QML. Это означает, что вы можете использовать её для проверки того, что переменная действительно является ожидаемым типом, например:

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

...

Ограничения среды JavaScript

QML реализует следующие ограничения для кода JavaScript:

• Код JavaScript, написанный в файле .qml , не может изменять глобальный объект. Код JavaScript в файле .js может изменять глобальный объект, и эти изменения будут видны в файле .qml при импорте.

  В QML глобальный объект является постоянным — существующие свойства не могут быть изменены или удалены, и новые свойства не могут быть созданы.

  Большинство JavaScript-программ не намеренно изменяют глобальный объект. Однако автоматическое создание 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 с кодом «global», он выполняется в области видимости, содержащей только сам внешний файл и глобальный объект. То есть он не будет иметь доступа к объектам и свойствам 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)
      }
  }

См. также Область видимости и разрешение имен.