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 не документируются явно. Для получения более подробной информации о их использовании, обратитесь к стандарту ECMA-262 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

Список поддерживаемых QML движком объектов, функций и свойств JavaScript можно найти в Списке объектов и функций 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)
      }
  }

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