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

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

Общий базовый уровень

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

В документации QML встроенные элементы стандарта ECMAScript не документируются явно. Для получения дополнительной информации об их использовании, пожалуйста, обратитесь к 5-му изданию стандарта 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 добавлены функции преобразования, учитывающие локаль.

Ограничения среды 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. Во всех остальных ситуациях значение this в QML не определено.

  Для ссылки на конкретный объект, укажите id. Например:

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