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

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

Общий базис

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

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

Объект QML глобального уровня

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

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