JavaScript-окружение хоста

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

Общие основы

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

Оператор нулевого слияния (с Qt 5.15) и Оператор необязательной цепочки (с Qt 6.2) также реализованы в среде выполнения QML.

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

Аннотации и утверждения типов

Объявления функций могут и должны содержать аннотации типов. Аннотации типов добавляются к объявлению аргументов и самой функции для аннотации возвращаемого типа. Следующая функция принимает параметр int и параметр string и возвращает QtObject:

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

Аннотации типов помогают инструментам, таким как Qt Creator и qmllint, понять код и предоставить лучшие диагностические сообщения. Кроме того, они облегчают использование функций из C++. Подробнее см. Взаимодействие с объектами QML из C++.

Утверждения типов (иногда называемые приведениями типов) также могут использоваться для приведения типа объекта к другому типу объекта. Если объект фактически является заданного типа, то утверждение типа возвращает тот же объект. В противном случае он возвращает null. В следующем фрагменте мы утверждаем, что объект parent является объектом типа Rectangle перед доступом к определённому члену.

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

Оператор необязательной цепочки (?.) предотвращает выброс исключения, если родительский объект не является прямоугольником. В этом случае «красный» выбирается как parentColor.

Глобальный объект 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)
      }
  }

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